path: root/doc
diff options
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-10 15:23:58 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-12-10 15:23:58 +0200
commit3809390c3e8df46b85371957b2da42fabfda9788 (patch)
treeb5e5b6a7c381abcdfd1f0aa387fd3cfc02172553 /doc
parent8f42fc862f0580cb5ecafac3e16582a1a817cf54 (diff)
Document state files and instances.
* doc/pies.texi: Update.
Diffstat (limited to 'doc')
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.
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.
-* 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
-@end deffn
-@deffn {Config} stat-file @var{file}
-Set file name of the statistics output file. Default is
-@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:
+@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.
+ 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
+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}.

Return to:

Send suggestions and report system problems to the System administrator.