aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-02 10:26:39 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-12-02 10:26:39 +0200
commitb63563c9c5271d088d80a31f780be74d1c16fef4 (patch)
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')
-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
@@ -79,12 +79,13 @@ Software Foundation raise funds for GNU development.''
This edition of the @cite{GNU Pies Manual}, last updated @value{UPDATED},
documents @command{pies} Version @value{VERSION}.
@end ifnottex
@menu
* Intro::
+* Dependencies::
* Pies Configuration File::
* Pies Debugging::
* Configuration Example::
* Command Line Usage::
* Invocation::
* Reporting Bugs::
@@ -149,28 +150,12 @@ executed in the foreground. Upon startup, @command{pies} reads the list
of components from its configuration file, starts them, and remains in
the background, controlling their execution. When any of the components
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.
@anchor{init-style}
@cindex init-style components
This way of operation applies to the @dfn{init-style}
@@ -192,19 +177,19 @@ bound to component's @samp{stdin} and @samp{stdout} streams. The
described above. This mode of operation is similar to that of
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.
@anchor{accept-style}
@cindex accept-style components
@@ -214,30 +199,88 @@ except that after binding to the socket @command{pies} immediately
starts the component, without waiting for an actual connection.
Any number of components of all three styles can be handled
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.
@xopindex{lint, introduced}
To test the configuration file without actually starting the server, the
@option{--lint} (@option{-t}) command line option is provided. It causes
@@ -586,22 +629,49 @@ Command line for the program. The argument should be just as
arguments normally are, starting with the name of the program. The
latter may be different from the one specified to @code{program}
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 @{ ... @}
Set access control list for this component. @xref{ACL}, for a
detailed description of access control lists.
@end deffn
@@ -1886,12 +1956,23 @@ Force startup even if another instance may be running.
@item --foreground
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
@opsummary{source-info}
@item --source-info
@@ -1908,16 +1989,40 @@ Log to standard error.
@opsummary{stop}
@item --stop
@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
@itemx --reload
@itemx --hup
Reload the running instance of pies.

Return to:

Send suggestions and report system problems to the System administrator.