aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/pies.texi339
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.

Return to:

Send suggestions and report system problems to the System administrator.