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
@@ -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
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
-* 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
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:
+@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.
+ 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}.
After startup, you can verify the status of the running process
using the @option{--status} command line option:
@@ -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}.
@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}.
@item --lint
@itemx -t

Return to:

Send suggestions and report system problems to the System administrator.