diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/pies.texi | 339 |
1 files changed, 306 insertions, 33 deletions
diff --git a/doc/pies.texi b/doc/pies.texi index 4197bbf..90f21e5 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -27,7 +27,7 @@ startup. Components @samp{B} and @samp{C} are called Before restarting any component, @command{pies} verifies if it is a prerequisite for any other components. If so, it first terminates its dependencies, then restarts the component, and then starts its -dependencies again, in the order of their appearence in the +dependencies again, in the order of their appearance in the configuration file. The standard output and standard error streams of a component can be @@ -51,7 +51,7 @@ it decides what component the socket corresponds to, and invokes this component to service that connection. In this case, the connection is bound to component's @samp{stdin} and @samp{stdout} streams. The @samp{stderr} stream can be redirected to a file or to syslog, as -described above. This mode of operation is sililar to that of +described above. This mode of operation is similar to that of @command{inetd} utility. @anchor{meta1-style} @@ -71,13 +71,13 @@ handling of the socket is the responsibility of the component itself. @cindex accept-style components The last flavor of @command{pies} components are @dfn{accept-style} components, which are handled basically as @samp{inetd-style} ones, -except that after binding to the socket @command{pies} immedately +except that after binding to the socket @command{pies} immediately starts the component, without waiting for an actual connection. Any number of components of all three styles can be handled simultaneously. - Components are started in the order of their appearence in the + Components are started in the order of their appearance in the configuration file and terminated in reverse order. When starting or stopping component dependencies, the same order is preserved. @@ -91,6 +91,7 @@ statement (@pxref{include-meta1}). * Global Configuration:: * Pies Debugging:: * Configuration Example:: +* Command Line Usage:: * Pies Invocation:: @end menu @@ -142,7 +143,8 @@ argument to the @code{component} keyword. @table @asis @item exec @itemx wait - Create an @samp{init-style} component (@pxref{init-style}). + Create an @samp{init-style} component (@pxref{init-style}). This is +the default. @item inetd @itemx nostartaccept @@ -704,7 +706,7 @@ manager @command{mcp}. To ensure compatibility with MeTA1, the components read from MeTA1 configuration are started in reverse order (i.e. from last to first), -and stoppend in order of their appearence in @var{file}. Of course, +and stopped in order of their appearance in @var{file}. Of course, this does not affect normal @command{pies} components. The following @command{pies} statements are silently applied to @@ -741,29 +743,79 @@ component smtps @{ @node Global Configuration @section Global Configuration -@WRITEME{} - -@ignore -# Write PID to this file. -pidfile <arg: string>; -# Set location of the control file. -control-file <arg: string>; -# Set location of the statistics output file. -stat-file <arg: string>; -# Run with this user privileges. -user <arg: string>; -# Retain supplementary group. -group <arg: list of string>; -# Retain all supplementary groups of which user is a member. -allgroups <arg: boolean>; -# Force this umask. -umask <arg: number>; -# Set global system limits -limits <arg: string>; -# Wait <n> seconds for all components to shut down. -shutdown-timeout <n: number>; -return-code <tag: exit-code-list> { -@end ignore +The statements described in this section affect @command{pies} +behavior as a whole. + +@deffn {Pies Conf} umask @var{number} +Set the default umask. The @var{number} must be an octal value not greater +than @samp{777}. The default umask is inherited at startup. +@end deffn + +@deffn {Pies Conf} limits @var{arg} +Set global system limits for all pies components. @xref{Resources, +limits}, for a detailed description of @var{arg}. +@end deffn + +@deffn {Pies Conf} return-code @{ ... @} +Configure global exit actions. @xref{Exit Actions}, for a detailed +description of this statement. +@end deffn + +@deffn {Pies Conf} shutdown-timeout @var{number}; +Wait @var{number} of seconds for all components to shut down. +Default is 5 seconds. +@end deffn + +@menu +* Less Useful Statements:: +@end menu + +@node Less Useful Statements +@subsection Less Useful Statements + + Some configuration file statements are provided for completeness and +are rarely, if at all used. If used improperly, they may severely +impair the functionality of @command{pies} or even render it +useless. Do not use them, unless you have a good knowledge of +@command{pies} internals and understand their impact. + + The following three statements define file names of various files +needed by @command{pies}. Use them only if the defaults does not +suit your needs: + +@deffn {Pies Conf} pidfile @var{file} +Write PID of the master @command{pies} process to @var{file}. By +default, master PID is stored in @file{@var{statedir}/pies.pid} +(@pxref{statedir}). +@end deffn + +@deffn {Pies Conf} control-file @var{file} +Set file name of the @command{pies} control file. Default is +@file{@var{statedir}/pies.ctl} +@end deffn + +@deffn {Pies Conf} stat-file @var{file} +Set file name of the statistics output file. Default is +@file{@var{statedir}/pies.stat}. +@end deffn + + Normally, @command{pies} must be run with root privileges. If, +however, you've found an implementation for it, that requires another +privileges, you may change them using the following three statements: + +@command{pies} process. +@deffn {Pies Conf} user @var{user-name} +Start @command{pies} with the UID and GID of this user. +@end deffn + +@deffn {Pies Conf} group @var{group-list} +Retain supplementary groups, specified in @var{group-list}. +@end deffn + +@deffn {Pies Conf} allgroups @var{bool} +Retain all supplementary groups of which user, given with +@command{user} statement, is a member. +@end deffn @node Pies Debugging @section Pies Debugging @@ -803,7 +855,38 @@ Debug the lexical analyzer of MeTA1 configuration file. @node Configuration Example @section Configuration Example -@UNREVISED{} + In this section we provide several examples of working @command{pies} +configuration files. + +@menu +* Simple Pies:: +* Hairy Pies:: +* Inetd Pies:: +@end menu + +@node Simple Pies +@subsection Simplest Case: Using Pies to Run Pmult + The example below runs @command{pmult} (@pxref{pmult}) utility with +the privileges of @samp{meta1} user. Both standard error and standard +output are redirected to syslog facility @samp{mail}, priorities +@samp{err} and @samp{info}, correspondingly. + +@smallexample +component pmult @{ + command "/usr/local/sbin/pmult"; + user meta1s; + facility mail; + stderr syslog err; + stdout syslog info; +@} +@end smallexample + +@node Hairy Pies +@subsection Using Pies to Run Pmult and MeTA1 + The example below is a working configuration file for running +@command{pmult} and all components of MeTA1, configured in +@file{/etc/meta1/meta1.conf}. The global @code{return-code} statement +is used to configure @command{pies} behavior for some exit codes. @smallexample # Sample pies configuration for running pmult and MeTA1 @@ -823,22 +906,212 @@ return-code (EX_USAGE, EX_CONFIG) @{ I will not restart it automatically. Please fix its configuration and restart it manually at your earliest convenience. - To restart, run `$@{program-name@} --start $@{component@}' + To restart, run ``$@{program-name@} -R $@{component@}'' --- Wuff-wuff, Pies + EOT; @} component pmult @{ command "/usr/local/sbin/pmult"; user meta1s; - stderr syslog info; + stderr syslog err; stdout syslog info; @} include-meta1 "/etc/meta1/meta1.conf"; @end smallexample +@node Inetd Pies +@subsection Running Pies Instead of Inetd + +This configuration file allows to run @command{pies} instead of +@command{initd}. It starts two services: @samp{ftp} and @samp{pop3d}, +and restricts access to them to two local subnets: + +@smallexample +acl @{ + log from any "Connect from $@{address@}"; + allow from 10.10.10.0/24; + allow from 192.168.10.0/27; + deny from any; +@} + +debug "<trace4"; + +component ftp @{ + mode inetd; + socket "inet://0.0.0.0:21"; + umask 027; + program /usr/sbin/ftpd + command ftpd -l -C; +@} + +component pop3d @{ + mode inetd; + socket "inet://0.0.0.0:110"; + program "/usr/sbin/pop3d"; + command "pop3d --inetd"; +@} +@end smallexample + +@node Command Line Usage +@section Command Line Usage + + When run without arguments, @command{pies} parses and loads the +configuration file, detaches itself from the controlling terminal +(becomes a daemon), and starts all components. Before actually +starting up, it ensures that no another instance of it is +already running, by looking for a PID file and verifying that the PID +listed there is alive and responding. If another instance is running, +@command{pies} refuses to start up. + +@anchor{pies-status} + After startup, you can verify the status of the running process +using @option{--status} command line option: + +@smallexample +$ pies --status +redirector smtps/stderr 4697 +redirector pmult/stderr 4677 +redirector pmult/stdout 4676 +component pmult 4678 /usr/local/sbin/pmult +component smar 4680 smar -f /etc/meta1/meta1.conf -d 100 +component qmgr 4691 qmgr -f /etc/meta1/meta1.conf +component smtpc 4696 smtpc -f /etc/meta1/meta1.conf +component smtps 4698 smtps -d100 -f /etc/meta1/meta1.conf +@end smallexample + + In its output, lines beginning with @samp{component} refer to +running components. For running components, the following information +is displayed: + +@enumerate 1 +@item Component tag (@pxref{Component Statement}). +@item PID of the running instance of the component. +@item Command line of the component, as set by the @code{command} +statement (@pxref{Component Statement, command}). +@end enumerate + +If the component is not running, the reason is indicated in the PID +column, between the square brackets, e.g.: + +@smallexample +component pmult [disabled; scheduled for Mon 01 Dec 2008 20:27:02] + /usr/local/sbin/pmult +@end smallexample + +@noindent +(the example above is split in two lines for readability). + +@anchor{pies-restart} + You can restart any component by using the +@option{--restart-component} (@option{-R}) option, e.g.: + +@smallexample +$ pies -R pmult smtps +@end smallexample + + To stop all running components and shut down @command{pies}, use the +@option{--stop} (@option{-S}) command line option: + +@smallexample +$ pies --stop +@end smallexample + +@cindex dependencies, pies +@anchor{dump-depmap} +@cindex --dump-depmap option, pies + Two options are provided for verifying inter-component +dependencies. The @option{--dump-depmap} option prints on the +standard output the @dfn{dependency map}. This map is a square table +where rows represent dependents and columns represent prerequisites. +An @samp{X} sign is placed on each crossing which corresponds to the +actual dependency. For example: + +@smallexample +$ pies --dump-depmap +Dependency map: + 0 1 2 3 4 + 0 + 1 + 2 X + 3 X + 4 X X + +Legend: + 0: pmult + 1: smar + 2: qmgr + 3: smtpc + 4: smtps +@end smallexample + +This example corresponds to the configuration file shown in @ref{Hairy +Pies}. To illustrate how to read it, consider the 4th row of the +table. According to the legend, number 4 means @samp{smtps} +component. There are two @samp{X} marks: in columns 1 and 2. This +means that @samp{smtps} depends on @samp{smar} and @samp{qmgr}. + +@anchor{dump-prereq} +@cindex --dump-prereq option, pies + You can also list prerequisites explicitly: + +@smallexample +$ pies --dump-prereq +qmgr: smar +smtpc: qmgr +smtps: smar qmgr +@end smallexample + @node Pies Invocation @section Pies Invocation -@WRITEME{} + +@table @option +@item --force +Force startup even if another instance may be running. + +@item --foreground +Remain in foreground. + +@item --stderr +Log to standard error. + +@item --syslog +Log to syslog. This is the default. + +@item -x @var{level} +@itemx --debug=@var{level} +Set debug verbosity level. @xref{Pies Debugging}, for a description +of @var{level}. + +@item -r +@itemx --reload +@itemx --hup +Reload the running instance of pies. + +@item -R +@itemx --restart-component +Restart components named in the command line. @xref{pies-restart}. + +@item -s +@itemx --status +Display info about the running instance. @xref{pies-status}. + +@item -S +@itemx --stop +Stop the running instance. + +@item --dump-depmap +Dump dependency map. @xref{dump-depmap}. + +@item --dump-prereq +Dump prerequisite charts. @xref{dump-prereq}. + +@end table + +Apart from these, the common GNU Mailutils options are understood, which +are useful for checking @command{pmult} configuration file for syntax +errors. @xref{Common Options, Common Options, , mailutils, GNU +Mailutils Manual}, for a detailed description of these. |