diff options
Diffstat (limited to 'doc')
-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 @@ -103,15 +103,17 @@ Appendices Pies Configuration File * Syntax:: Configuration File Syntax * 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 * Comments:: * Statements:: * Preprocessor:: Using preprocessor to improve the configuration. @@ -131,16 +133,12 @@ Component Statement Inetd-Style Components * builtin:: Built-in Inetd Services * TCPMUX:: TCPMUX Services * sockenv:: Socket Environment Variables -Global Configuration - -* Less Useful Statements:: - Configuration Example * Simple Pies:: * Hairy Pies:: * Inetd Pies:: @@ -312,12 +310,14 @@ directives any time by running @command{pies --config-help}. * Component Statement:: * Notification:: Mail Notification * ACL:: Access Control Lists * inetd:: * include-meta1:: * Global Configuration:: +* Pies Privileges:: +* State Files:: @end menu @node Syntax @section Configuration File Syntax The configuration file consists of statements and comments. @@ -1184,17 +1184,18 @@ echo stream tcp nowait root internal @end smallexample Another built-in services are defined in the same manner, replacing @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} Set the name of the @samp{quotation-of-the-day} file. @end deffn @@ -1829,13 +1830,13 @@ A special option is provided that instructs @command{pies} to behave as @command{inetd}: @table @option @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 The GNU Pies package also provides a wrapper that allows to use @command{pies} instead of @command{inetd}. It is built if the package is configured with the @option{--enable-inetd} option. The wrapper @@ -1982,47 +1983,16 @@ description of this statement. @deffn {Config} 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 {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: @deffn {Config} user @var{user-name} Start @command{pies} with the UID and GID of this user. @end deffn @@ -2033,12 +2003,63 @@ Retain the supplementary groups, specified in @var{group-list}. @deffn {Config} allgroups @var{bool} 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} The amount of debugging information produced by @command{pies} is configured by the following statements: @@ -2196,16 +2217,45 @@ This configuration is ``almost'' equivalent, because the @node Command Line Usage @chapter 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. +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 using the @option{--status} command line option: @smallexample @@ -2382,13 +2432,13 @@ Display a short usage summary and exit. Run in @command{inetd}-compatibility mode. It is roughly equivalent to @command{pies --instance=inetd --syntax=inetd}. @xref{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 @itemx -t @opsummary{source-info} |