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 @@ -106,9 +106,11 @@ Pies Configuration File * Component Statement:: * Notification:: Mail Notification * 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:: Configuration File Syntax @@ -134,10 +136,6 @@ Inetd-Style Components * TCPMUX:: TCPMUX Services * sockenv:: Socket Environment Variables -Global Configuration - -* Less Useful Statements:: - Configuration Example * Simple Pies:: @@ -315,6 +313,8 @@ directives any time by running @command{pies --config-help}. * inetd:: * include-meta1:: * Global Configuration:: +* Pies Privileges:: +* State Files:: @end menu @node Syntax @@ -1187,11 +1187,12 @@ echo stream tcp nowait root internal @samp{echo} in the @code{service} field with the corresponding service name. +@anchor{qotd} The @samp{qotd} service reads the contents of the @dfn{qotd file} and sends it back to the client. By default the @samp{qotd} file 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: @deffn {Config} qotd-file @var{file-name} @@ -1832,7 +1833,7 @@ as @command{inetd}: @xopindex{inetd, described} @item --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. @end table @@ -1985,41 +1986,10 @@ 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 {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 privileges, you may change them using the following three statements: @@ -2036,6 +2006,57 @@ Retain all supplementary groups of which user, given with @command{user} statement, is a member. @end deffn + 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 @chapter Pies Debugging @xopindex{debug, described} @@ -2199,10 +2220,39 @@ This configuration is ``almost'' equivalent, because the 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. +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}. @anchor{pies-status} After startup, you can verify the status of the running process @@ -2385,7 +2435,7 @@ equivalent to @command{pies --instance=inetd --syntax=inetd}. @opsummary{instance} @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}. @opsummary{lint} @item --lint |