From 252160d0090298198d3794d356063d985778a73a Mon Sep 17 00:00:00 2001
From: Sergey Poznyakoff <gray@gnu.org.ua>
Date: Mon, 1 Dec 2008 19:04:20 +0000
Subject: Update

---
 doc/pies.texi | 339 ++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 306 insertions(+), 33 deletions(-)

(limited to 'doc')

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.
-- 
cgit v1.2.1