summaryrefslogtreecommitdiffabout
path: root/doc
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-02 08:26:39 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2009-12-02 08:26:39 (GMT)
commitb63563c9c5271d088d80a31f780be74d1c16fef4 (patch) (side-by-side diff)
treea30cab9cf81c44becdc3da6ae88a0264c7fe2ac4 /doc
parentdc8b82d5b62e879c1291f531fd0d352a25fbfa87 (diff)
downloadpies-b63563c9c5271d088d80a31f780be74d1c16fef4.tar.gz
pies-b63563c9c5271d088d80a31f780be74d1c16fef4.tar.bz2
Minor changes
* doc/pies.texi: Update * src/progman.c (run_command): handle return-code for inetd components.
Diffstat (limited to 'doc') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/pies.texi169
1 files changed, 137 insertions, 32 deletions
diff --git a/doc/pies.texi b/doc/pies.texi
index 9db612b..96cbfb5 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -82,6 +82,7 @@ documents @command{pies} Version @value{VERSION}.
@menu
* Intro::
+* Dependencies::
* Pies Configuration File::
* Pies Debugging::
* Configuration Example::
@@ -152,22 +153,6 @@ terminates, @command{pies} restarts it. Its configuration allows to
specify actions other than simple restart, depending on the exit code
of the component.
-@cindex prerequisite
-@cindex dependency
-@cindex dependents
-@anchor{component prerequisite}
- A component @samp{A} may depend on another components, say
-@samp{B} and @samp{C}, i.e. require them to be running at the moment of its
-startup. Components @samp{B} and @samp{C} are called
-@dfn{prerequisites} for @samp{A}, while @samp{A} is called a
-@dfn{dependency} or @dfn{dependent} component of @samp{B}, @samp{C}.
-
- Before restarting any component, @command{pies} verifies if it is a
-prerequisite for any other components. If so, it first terminates its
-dependencies, then restarts the component, and then starts its
-dependencies again, in the order of their appearance in the
-configuration file.
-
The standard output and standard error streams of a component can be
redirected to a file or to an arbitrary @command{syslog} channel.
@@ -195,13 +180,13 @@ the @command{inetd} utility.
@anchor{meta1-style}
@cindex meta1-style components
@cindex smtps
- Third type of components supported by @command{pies} are
+ Yet another type of components supported by @command{pies} are
@dfn{meta1-style} components. As its name suggests, this type is
designed expressly as a support for MeTA1@footnote{See
@uref{http://www.meta1.org}} components, namely
@command{smtps}. This type can be regarded as a mixture of the above
two. For each meta1-style component @command{pies} opens a socket
-after start-up, and then executes the component. Once the component
+after start-up, and starts the component binary. Once the component
is running, @command{pies} passes it the file descriptor of that
socket, through another preconfigured @acronym{UNIX}-style socket. Further
handling of the socket is the responsibility of the component itself.
@@ -217,24 +202,82 @@ starts the component, without waiting for an actual connection.
simultaneously.
Components are started in the order of their appearance in the
-configuration file and terminated in the reverse order. The same
+configuration file and terminated in reverse order. The same
ordering applies when starting or stopping a component dependencies,
As an exception, this order is reversed for the components read from
files included by @code{include-meta1} statement (@pxref{include-meta1}).
+@node Dependencies
+@chapter Inter-Component Dependencies
+@cindex prerequisite
+@cindex dependency
+@cindex dependents
+@anchor{component prerequisite}
+ A component @samp{A} may depend on another components, say
+@samp{B} and @samp{C}, i.e. require them to be running at the moment of its
+startup. Components @samp{B} and @samp{C} are called
+@dfn{prerequisites} for @samp{A}, while @samp{A} is called a
+@dfn{dependency} or @dfn{dependent} component of @samp{B}, @samp{C}.
+
+ Before restarting any component, @command{pies} verifies if it is a
+prerequisite for any other components. If so, it first terminates its
+dependencies, then restarts the component, and then starts its
+dependencies again, in the order of their appearance in the
+configuration file.
+
@node Pies Configuration File
@chapter Pies Configuration File
@cindex configuration file
@flindex pies.conf
@xopindex{config-file, introduced}
- @command{Pies} reads its settings and component definitions from the
-@dfn{configuration file} @file{pies.conf}, located in the @dfn{system
+ @command{Pies} reads its settings and component definitions from one
+or more @dfn{configuration files}. The default configuration file
+is named @file{pies.conf} and is located in the @dfn{system
configuration directory} (in most cases @file{/etc} or
@file{/usr/local/etc}, depending on how the package was compiled).
-An alternative location may be specified using @option{--config-file}
-(@option{-c} command line option).
+This file uses the @dfn{native Pies configuration syntax}. The
+program also understands configuration files in @dfn{inetd} and
+@dfn{meta1} formats.
+ Alternative configuration files may be specified using @option{--config-file}
+(@option{-c} command line option), e.g.:
+
+@smallexample
+pies --config-file @var{filename}
+@end smallexample
+
+@anchor{config syntax}
+Any number of such options may be given. The files named in
+@option{--config-file} options are processed in order of their
+appearance in the command line. By default, @command{pies} expects
+configuration files in its native format. This, however, can be
+changed by using the @option{--syntax=@var{format}} command line
+option. This option instructs @command{pies} that any configuration
+files given after it have are written in the specified @var{format}.
+Valid formats are: @samp{pies}, @samp{inetd} and @samp{meta1}, which
+stand for pies native format, inetd-style configuration files
+(@FIXME-pxref{inetd-format} and MeTA1-style configuration files. The
+configuration file format set by the @option{--syntax} option remains
+in effect for all @option{--config-file} options that follow it, up to
+the end of the command line or the next occurrence of the
+@option{--syntax} option. This means that you can instruct
+@command{pies} to read several configuration files of various formats
+in a single command line, e.g.:
+
+@smallexample
+@group
+pies /etc/pies.conf \
+ --syntax=inetd --config-file /etc/inetd.conf \
+ --syntax=meta1 --config-file /etc/meta1/meta1.conf
+@end group
+@end smallexample
+
+ The rest of this chapter concerns the @command{pies} native
+configuration file format. The use of inetd configuration files is
+covered in @FIXME-ref{inetd} and the use of meta1 configuration files
+is described in @FIXME-ref{meta1}
+
If any errors are encountered in the configuration file, the program
reports them on the standard error and exits with status 78.
@@ -589,16 +632,43 @@ statement. Its value will be available to the program as
@code{argv[0]}.
@end deffn
-@deffn {Config: component} disable @var{bool}
-If @var{bool} is @samp{true}, this component is disabled,
-i.e. @command{pies} will ignore it.
-@end deffn
+@deffn {Config: component} flags (@var{flag-list})
+Define flags for this component. The @var{flag-list} is a
+comma-separated list of flags. Valid flags are:
+
+@table @asis
+@item disable
+This component is disabled, i.e. @command{pies} will parse and
+remember its settings, but will not start it.
+
+@item precious
+Mark this component as @dfn{precious}. Precious components are never
+disabled by @command{pies}, even if they respawn too fast.
+
+@item wait
+This flag is valid only for @samp{inetd} components. It has the same
+meaning as @samp{wait} in @file{inetd.conf} file, i.e. it tells
+@command{pies} to wait for the server program to
+return. @FIXME-xref{inetd}.
-@deffn {Config: component} precious @var{bool}
-@cindex precious components
-If @var{bool} is @samp{true}, this component is marked as precious.
-Precious components are never disabled by @command{pies}, even if they
-respawn too fast.
+@item tcpmux
+This is a @acronym{TCPMUX} component. @FIXME-xref{tcpmux}.
+
+@item tcpmuxplus
+This is a @acronym{TCPMUX+} component. @FIXME-xref{tcpmux}.
+
+@item internal
+This is an internal inetd component. @FIXME-xref{internal inetd}.
+
+@item sockenv
+This inetd component wants socket description variables in its
+environment. @FIXME-xref{sockenv}.
+
+@item resolve
+When used with @samp{sockenv}, the @env{LOCALHOST} and
+@env{REMOTEHOST} environment variables will contain resolved host
+names, instead of IP addresses.
+@end table
@end deffn
@deffn {Config: component} acl @{ ... @}
@@ -1889,6 +1959,17 @@ Remain in foreground.
@item --help
Display a short usage summary and exit.
+@opsummary{inetd}
+@item --inetd
+@itemx -i
+Run in @command{inetd}-compatibility mode. It is roughly
+equivalent to @command{pies --instance=inetd --syntax=inetd}.
+@FIXME-xref{inetd}.
+
+@opsummary{instance}
+@item --instance=@var{name}
+Define the name of the @command{pies} @dfn{instance}. @FIXME-xref{instances}.
+
@opsummary{lint}
@item --lint
@itemx -t
@@ -1911,10 +1992,34 @@ Log to standard error.
@itemx -S
Stop the running instance.
+@opsummary{syntax}
+@item --syntax=@var{type}
+Define the syntax for parsing the configuration files specified by any
+@option{--config-file} options that follow this one. Possible values
+for @var{type} are:
+
+@table @asis
+@item pies
+Native @command{pies} configuration. @xref{Pies Configuration File}.
+
+@item inetd
+@samp{Inetd}-style configuration files. @FIXME-xref{inetd}.
+
+@item meta1
+@samp{meta1}-style configuration files. @FIXME-xref{meta1}.
+@end table
+
+@xref{config syntax}, for a detailed description of this option.
+
@opsummary{syslog}
@item --syslog
Log to syslog. This is the default.
+@opsummary{rate}
+@item --rate=@var{r}
+Set maximum connection rate (connections per second) for inetd-style
+components. @FIXME-xref{inetd rate}.
+
@opsummary{reload}
@opsummary{hup}
@item -r

Return to:

Send suggestions and report system problems to the System administrator.