diff options
Diffstat (limited to 'doc/pies.texi')
-rw-r--r-- | doc/pies.texi | 146 |
1 files changed, 98 insertions, 48 deletions
diff --git a/doc/pies.texi b/doc/pies.texi index b51be37..db438c6 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -108,5 +108,7 @@ Pies Configuration File * ACL:: Access Control Lists -* inetd:: Using @command{inetd} Configuration Files -* include-meta1:: Using @command{meta1} Configuration Files +* inetd:: +* include-meta1:: * Global Configuration:: +* Pies Privileges:: +* State Files:: @@ -136,6 +138,2 @@ Inetd-Style Components -Global Configuration - -* Less Useful Statements:: - Configuration Example @@ -317,2 +315,4 @@ directives any time by running @command{pies --config-help}. * Global Configuration:: +* Pies Privileges:: +* State Files:: @end menu @@ -1189,2 +1189,3 @@ name. +@anchor{qotd} The @samp{qotd} service reads the contents of the @dfn{qotd file} @@ -1193,3 +1194,3 @@ is located in the local state directory and named @file{@var{instance}.qotd} (where @var{instance} is the name of the -@command{pies} instance, @FIXME-pxref{instances}). This default location +@command{pies} instance; @pxref{instances}). This default location can be changed using the following statement: @@ -1834,3 +1835,3 @@ as @command{inetd}: Read configuration from @file{@var{sysconfdir}/inetd.conf} and make -sure @command{pies} state files (@FIXME-pxref{state files}) do not +sure @command{pies} state files (@pxref{State Files}) do not conflict with those from other @command{pies} instances. @@ -1987,37 +1988,6 @@ Default is 5 seconds. -@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 {Config} pidfile @var{file} -Write PID of the master @command{pies} process to @var{file}. By -default the master PID is stored in @file{@var{localstatedir}/pies.pid}, -where @var{localstatedir} is the @dfn{local state directory}, defined -at compile time (usually, it is @file{/usr/local/var} or @file{/usr/var}). -@end deffn - -@deffn {Config} control-file @var{file} -Set file name of the @command{pies} control file. Default is -@file{@var{localstatedir}/pies.ctl} -@end deffn - -@deffn {Config} stat-file @var{file} -Set file name of the statistics output file. Default is -@file{@var{localstatedir}/pies.stat}. -@end deffn - - Normally, @command{pies} must be run with root privileges. If, +@node Pies Privileges +@section Pies Privileges +@cindex privileges + Normally, @command{pies} is run with root privileges. If, however, you found such an implementation for it, that requires another @@ -2038,2 +2008,53 @@ Retain all supplementary groups of which user, given with + An example of such implementation is using @command{pies} to +start @command{jabberd} components: +@uref{http://www.gnu.org.ua/software/pies/example.php?what=jabberd2}. + +@node State Files +@section State Files +@cindex state files + Pies uses several files to keep its state information. These files +are kept in local state directory (usually @file{/var/run/pies}, or +@file{/usr/local/var/run/pies}). The table below describes these +files. The @var{instance} in this table stands for the @command{pies} +instance name (@pxref{instances}). Usually, it is @samp{pies}. + +@table @asis +@item @file{@var{instance}.pid} +The @dfn{PID file}. It keeps the PID number of the running +@command{pies} instance. + +@item @file{@var{instance}.ctl} +The @dfn{control file}. This file is used by @command{pies +--restart-component} to pass control requests to the running +@command{pies} instance. + +@item @file{@var{instance}.stat} +The @dfn{statistics file}. Used by @command{pies --status}. + +@item @file{@var{instance}.qotd} +The @dfn{Quotation-of-the-day file}. It is used by the @samp{qotd} +built-in service (@pxref{qotd}). +@end table + + The following statements allow to redefine state file names. +Use them only if the defaults does not suit your needs, and the +@option{--instance} option does not help: + +@deffn {Config} pidfile @var{file} +Sets the PID file name. +@end deffn + +@deffn {Config} control-file @var{file} +Sets the control file name. +@end deffn + +@deffn {Config} stat-file @var{file} +Sets the statistics file name. +@end deffn + +@deffn {Config} qotd-file @var{file-name} +Sets the name of the @samp{quotation-of-the-day} file. +@end deffn + @node Pies Debugging @@ -2201,6 +2222,35 @@ 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. +starting up, it ensures that no another copy is already running, by +looking for a PID file and verifying that the PID listed there is +alive and responding. If another copy is running, @command{pies} +refuses to start up. + +@anchor{instances} + It is often necessary to run several copies of @command{pies} with +different configuration files. To support such usage, @command{pies} +provides a notion of @dfn{instance}. Pies instance is an independent +invocation of @command{pies} that uses a separate configuration file +and separate state files (@pxref{State Files}). Instances are created +using the @option{--instance} option: + +@table @option +@item --instance=@var{name} +Read configuration from @file{@var{sysconfdir}/@var{name}.conf}, +use @var{name} as the base name for state files (i.e., they become +@file{@var{name}.pid}, @file{@var{name}.clt}, etc.) and tag all syslog +messages with @var{name}. +@end table + + For example, the following invocations create three instances of +@command{pies}: + +@smallexample +pies +pies --instance=inetd +pies --instance=mta +@end smallexample + + The first instance uses the default configuration and state files. +The second one reads configuration from @file{/etc/inetd.conf}, and +the third one reads it from @file{/etc/mta.conf}. @@ -2387,3 +2437,3 @@ equivalent to @command{pies --instance=inetd --syntax=inetd}. @item --instance=@var{name} -Define the name of the @command{pies} @dfn{instance}. @FIXME-xref{instances}. +Define the name of the @command{pies} instance. @xref{instances}. |