\input texinfo @c -*-texinfo-*-
@smallbook
@c %**start of header
@setfilename pies.info
@settitle GNU Pies Manual
@c %**end of header
@setchapternewpage odd

@defcodeindex pr
@defcodeindex op
@c mt is the same as op, but used for mtasim options.
@defcodeindex mt
@defcodeindex kw
@defcodeindex fl

@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex mt cp
@syncodeindex pg cp
@syncodeindex tp cp
@syncodeindex op cp
@syncodeindex pr cp
@syncodeindex kw cp
@syncodeindex fl cp

@include version.texi
@include rendition.texi
@include macros.texi

@ifinfo
@dircategory System Administration
@direntry
* GNU Pies: (pies).             Program Invocation and Execution Supervisor.
* pies: (pies) Invocation.      GNU Pies Command Line Options.
@end direntry
@end ifinfo

@copying
Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301 USA 

Copyright @copyright{} 2005, 2006, 2007, 2008, 2009 Sergey Poznyakoff

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``GNU Pies Manual'',
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end copying

@titlepage
@title The @sc{GNU PIES} Manual
@subtitle version @value{VERSION}, @value{UPDATED}
@author Sergey Poznyakoff.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnothtml
@page
@summarycontents
@end ifnothtml

@page
@contents

@ifnottex
@node Top
@top GNU Pies Manual

This edition of the @cite{GNU Pies Manual}, last updated @value{UPDATED},
documents @command{pies} Version @value{VERSION}.
@end ifnottex

@menu
* Intro::
* Pies Configuration File::
* Pies Debugging::
* Configuration Example::
* Command Line Usage::
* Invocation::
* Reporting Bugs::

Appendices

* User-Group ACLs::
* Copying This Manual::  The GNU Free Documentation License.
* Concept Index::        Index of Concepts.

@detailmenu
 --- The Detailed Node Listing ---

Pies Configuration File

* Syntax::               Configuration File Syntax
* Component Statement::
* Notification::         Mail Notification
* ACL::                  Access Control Lists
* include-meta1::
* Global Configuration::

Configuration File Syntax

* Comments::
* Statements::
* Preprocessor::         Using preprocessor to improve the configuration.

Component Statement

* Prerequisites::
* Component Privileges::
* Resources::
* Actions Before Startup::
* Exit Actions::
* Output Redirectors::
* Inetd-Style Components::
* Meta1-Style Components::
* Component Syntax Summary::

Global Configuration

* Less Useful Statements::

Configuration Example

* Simple Pies::
* Hairy Pies::
* Inetd Pies::

@end detailmenu
@end menu

@node Intro
@chapter Introduction
@cindex component
  The name @command{pies} (pronounced @samp{p-yes}) stands for
@samp{Program Invocation and Execution Supervisor}.  This utility
starts and controls execution of external programs, called
@dfn{components}.  Each component is a stand-alone program, which is
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}
components, called so because of the similarity with the
@command{init} process manager.  @command{Pies} is also able to handle
components that receive input on their @samp{stdin} and send reply to
@samp{stdout}.  Such components are called @dfn{inetd-style}
components.

@anchor{inetd-style}
@cindex inetd-style components
  Inetd-style components are not executed right after @command{pies}
startup.  Instead, @command{pies} opens a socket for each of them and
listens for connections on these sockets.  When a connection arrives,
it decides what component the socket corresponds to, and invokes this
component to handle that connection.  In this case, the connection is
bound to component's @samp{stdin} and @samp{stdout} streams.  The
@samp{stderr} stream can be redirected to a file or to syslog, as
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
@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
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
  The last flavor of @command{pies} components are @dfn{accept-style}
components, which are handled basically as @samp{inetd-style} ones,
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
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 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
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).

  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
@command{pies} to check its configuration file and exit with status 0
if no errors were detected, and with status 78 otherwise.

@cindex @option{-E}, introduced
  Before parsing, configuration file is preprocessed using
@command{m4} (@pxref{Preprocessor}).  To see the preprocessed
configuration without actually parsing it, use @option{-E} command
line option.

@xopindex{config-help, introduced}
  The rest of this section describes the configuration file syntax in
detail.  You can receive a concise summary of all configuration
directives any time by running @command{pies --config-help}.

@menu
* Syntax::               Configuration File Syntax
* Component Statement::
* Notification::         Mail Notification
* ACL::                  Access Control Lists
* include-meta1::
* Global Configuration::
@end menu

@node Syntax
@section Configuration File Syntax
  The configuration file consists of statements and comments.

  There are three classes of lexical tokens: keywords, values, and
separators. Blanks, tabs, newlines and comments, collectively called
@dfn{white space} are ignored except as they serve to separate
tokens.  Some white space is required to separate otherwise adjacent 
keywords and values.

@menu
* Comments::
* Statements::
* Preprocessor::         Using preprocessor to improve the configuration.
@end menu

@node Comments
@subsection Comments
@cindex Comments in a configuration file
@cindex single-line comments
  @dfn{Comments} may appear anywhere where white space may appear in the
configuration file.  There are two kinds of comments:
single-line and multi-line comments.  @dfn{Single-line} comments start
with @samp{#} or @samp{//} and continue to the end of the line:

@smallexample
# This is a comment
// This too is a comment
@end smallexample

@cindex multi-line comments
  @dfn{Multi-line} or @dfn{C-style} comments start with the two
characters @samp{/*} (slash, star) and continue until the first
occurrence of @samp{*/} (star, slash).

  Multi-line comments cannot be nested.

@node Statements
@subsection Statements
@cindex statements, configuration file
@cindex configuration file statements
@cindex statement, simple
@cindex simple statements
  A @dfn{simple statement} consists of a keyword and value
separated by any amount of whitespace.  The simple statement is terminated
with a semicolon (@samp{;}), unless it contains a @dfn{here-document}
(see below), in which case the semicolon is optional.

  Examples of simple statements are:

@smallexample
pidfile /var/run/pies.pid;
source-info yes;
debug 10;
@end smallexample

  A @dfn{keyword} begins with a letter and may contain letters,
decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
Examples of keywords are: @samp{group}, @samp{control-file}.

  A @dfn{value} can be one of the following:

@table @asis
@item number
  A number is a sequence of decimal digits.

@item boolean
@cindex boolean value
  A boolean value is one of the following: @samp{yes}, @samp{true},
@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no},
@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}.
  
@item unquoted string
@cindex string, unquoted
  An unquoted string may contain letters, digits, and any of the
following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/},
@samp{:}.

@item quoted string
@cindex quoted string
@cindex string, quoted
@cindex escape sequence
  A quoted string is any sequence of characters enclosed in
double-quotes (@samp{"}).  A backslash appearing within a quoted
string introduces an @dfn{escape sequence}, which is replaced
with a single character according to the following rules:

@float Table, backslash-interpretation
@caption{Backslash escapes}
@multitable @columnfractions 0.30 .5
@headitem Sequence @tab Replaced with
@item \a @tab Audible bell character (@acronym{ASCII} 7)
@item \b @tab Backspace character (@acronym{ASCII} 8)
@item \f @tab Form-feed character (@acronym{ASCII} 12)
@item \n @tab Newline character (@acronym{ASCII} 10)
@item \r @tab Carriage return character (@acronym{ASCII} 13)
@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
@item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
@item \\ @tab A single backslash (@samp{\})
@item \" @tab A double-quote.
@end multitable
@end float

  In addition, any occurrence of @samp{\} immediately followed by
a newline character (@acronym{ASCII} 10) is removed from
the string.  This allows to split long strings over several
physical lines, e.g.:

@smallexample
@group
"a long string may be\
 split over several lines"
@end group
@end smallexample

  If the character following a backslash is not one of those specified
above, the backslash is ignored and a warning is issued.

  Two or more adjacent quoted strings are concatenated, which gives
another way to split long strings over several lines to improve
readability.  The following fragment produces the same result as in the
example above:

@smallexample
@group
"a long string may be"
" split over several lines"
@end group
@end smallexample

@anchor{here-document}
@item Here-document
@cindex here-document
  @dfn{Here-document} is a special construct that allows to introduce
strings of text containing embedded newlines.  

  The @code{<<@var{word}} construct instructs the parser to read all
the following lines up to the line containing only @var{word}, with
possible trailing blanks.  Any lines thus read are concatenated
together into a single string.  For example:

@smallexample
@group
<<EOT
A multiline
string
EOT
@end group
@end smallexample

  Body of a here-document is interpreted the same way as
double-quoted string, unless @var{word} is preceded by a backslash
(e.g. @samp{<<\EOT}) or enclosed in double-quotes, in which case
the text is read as is, without interpretation of escape sequences.

  If @var{word} is prefixed with @code{-} (a dash), then all leading
tab characters are stripped from input lines and the line containing
@var{word}.  Furthermore, if @code{-} is followed by a single space,
all leading whitespace is stripped from them.  This allows to indent
here-documents in a natural fashion.  For example:

@smallexample
@group
<<- TEXT
    All leading whitespace will be
    ignored when reading these lines.
TEXT
@end group
@end smallexample

  It is important that the terminating delimiter be the only token on
its line.  The only exception to this rule is allowed if a
here-document appears as the last element of a statement.  In this
case a semicolon can be placed on the same line with its terminating 
delimiter, as in: 

@smallexample
help-text <<-EOT
        A sample help text.
EOT;
@end smallexample

@item list
@cindex list
  A @dfn{list} is a comma-separated list of values.  Lists are
delimited by parentheses.  The following example shows a statement
whose value is a list of strings:

@smallexample
dependents (pmult, auth);
@end smallexample

  In any case where a list is appropriate, a single value is allowed
without being a member of a list: it is equivalent to a list with a
single member.  This means that, e.g. @samp{dependents auth;} is
equivalent to @samp{dependents (auth);}.

@end table

@cindex statement, block
@cindex block statement
  A @dfn{block statement} introduces a logical group of another
statements.  It consists of a keyword, followed by an optional value,
and a sequence of statements enclosed in curly braces, as shown in
the example below:

@smallexample
@group
component multiplexor @{
        command "pmult";
@}
@end group
@end smallexample

  The closing curly brace may be followed by a semicolon, although
this is not required.

@node Preprocessor
@subsection Using Preprocessor to Improve the Configuration.
@cindex preprocessor
@cindex m4
  Before parsing, the configuration file is @dfn{preprocessed} using
external preprocessor @command{m4}.  For a complete user manual, refer
to
@ifnothtml
@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
@end ifnothtml
@ifhtml
@uref{http://www.gnu.org/software/m4/manual}.
@end ifhtml
In this subsection we assume the reader is sufficiently
acquainted with @command{m4} macro processor.

@flindex pp-setup
  The external preprocessor is invoked with @option{-s} flag, instructing
it to include line synchronization information in its output.  This
information is then used by the parser to display meaningful
diagnostic.  An initial set of macro definitions is supplied by the 
@file{pp-setup} file, located in
@file{@var{$prefix}/share/pies/@var{version}/include} directory (where
@var{version} means the version of the package).

The default @file{pp-setup} file renames all @command{m4} built-in
macro names so they all start with the prefix @samp{m4_}.  This
is similar to GNU m4 @option{--prefix-builtin} options, but has an
advantage that it works with non-GNU @command{m4} implementations as
well.

Additional preprocessor symbols may be defined and the existing
symbols may be undefined using the following command line options:

@table @option
@xopindex{define, described}
@cindex @option{-D}
@item --define=@var{sym}[=@var{value}]
@itemx -D @var{symbol}[=@var{value}]
Define symbol @var{sym} as having @var{value}, or emtpy, if
the @var{value} is not given.

@xopindex{undefine, described}
@cindex @option{-U}
@item --undefine=@var{sym}
@itemx -U @var{sym}
Undefine symbol @var{sym}.
@end table

@node Component Statement
@section Component Statement
@kwindex component

@deffn {Config} component
  The @code{component} statement defines a new component:
@end deffn

@smallexample
component @var{tag} @{
  @dots{}
@}
@end smallexample

The component is identified by its @dfn{tag}, which is given as
argument to the @code{component} keyword.

The following are the basic statements which are allowed within the
@code{component} block:

@deffn {Config: component} mode @var{mode}
  Declare the type (style) of the component.  Accepted values for
@var{mode} are:

@table @asis
@item exec
@itemx wait
  Define an @samp{init-style} component (@pxref{init-style}).  This is
the default.
  
@item inetd
@itemx nostartaccept
  Define an @samp{inetd-style} component (@pxref{inetd-style}).
  
@item pass
@itemx pass-fd 
  Define a @samp{meta1-style} component (@pxref{meta1-style}).
  
@item accept
  Define a @samp{accept-style} component (@pxref{accept-style}).
@end table
@end deffn

@deffn {Config: component} program @var{name}
Full file name of the component binary.  This binary will be executed
(via @command{/bin/sh -c}) each time @command{pies} decides it needs
to start the component.

To supply command line arguments, use @code{command} statement.
@end deffn
  
@deffn {Config: component} command @var{string}
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} 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.
@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

The following subsections describe the rest of @samp{component}
substatements.

@menu
* Prerequisites::
* Component Privileges::
* Resources::
* Actions Before Startup::
* Exit Actions::
* Output Redirectors::
* Inetd-Style Components::
* Meta1-Style Components::
* Component Syntax Summary::
@end menu

@node Prerequisites
@subsection Component Prerequisites
@cindex declaring prerequisites
@cindex prerequisites, declaring
Prerequisites (@pxref{component prerequisite}) for a component are
declared using the following statement: 

@deffn {Config: component} prerequisites @var{tag-list}
The argument is either a list of component tags, @emph{defined before
this component}, or one of the following words:

@table @asis
@item all
Declare all components defined so far as prerequisites for this one.

@item none
No prerequisites.  This is the default.
@end table
@end deffn

  If you wish, you can define dependents, instead of prerequisites:

@deffn {Config: component} dependents @var{tag-list}
Declare dependents for this component.  @var{var-list} is a list of
component tags.
@end deffn

@node Component Privileges
@subsection Component Privileges
@cindex privileges
  The following statements control the privileges the component
is executed with.

@deffn {Config: component} user @var{user-name}
Start component with the UID and GID of this user. 
@end deffn

@deffn {Config: component} group @var{group-list}
Retain supplementary groups, specified in @var{group-list}.
@end deffn

@deffn {Config: component} allgroups @var{bool}
Retain all supplementary groups of which the user (as given with
@command{user} statement) is a member.  This is the default for
components specified in @file{meta1.conf} file (@pxref{include-meta1}).
@end deffn

@node Resources
@subsection Resources

@deffn {Config: component} limits @var{string}
Impose limits on system resources, as defined by @var{string}.  The
argument consists of @dfn{commands}, optionally separated by any
amount of whitespace.  A command is a single command letter followed
by a number, that specifies the limit.  The command letters are
case-insensitive and coincide with those used by the shell @code{ulimit}
utility:

@float Table, Limits
@caption{Limit Command Letters}
@multitable @columnfractions 0.3 0.6 
@headitem Command @tab  The limit it sets
@item     A       @tab  max address space (KB)
@item     C       @tab  max core file size (KB)
@item     D       @tab  max data size (KB)
@item     F       @tab  maximum file size (KB)
@item     M       @tab  max locked-in-memory address space (KB)
@item     N       @tab  max number of open files
@item     R       @tab  max resident set size (KB)
@item     S       @tab  max stack size (KB)
@item     T       @tab  max CPU time (MIN)
@item     U       @tab  max number of processes
@item     P       @tab  process priority -20..20 (negative = high priority)
@end multitable
@end float

For example:

@smallexample
limits T10 R20 U16 P20
@end smallexample

Additionally, the command letter @samp{L} is recognized.  It is
reserved for future use (@samp{number of logins} limit) and is ignored
in version @value{VERSION}.
@end deffn

@deffn {Config: component} umask @var{number}
Set the umask.  The @var{number} must be an octal value not greater
than @samp{777}.  The default umask is inherited at startup.
@end deffn

@deffn {Config: component} env @var{args}
Set program environment.

Arguments are a whitespace-delimited list of specifiers.  The
following specifiers are understood: 

@table @asis
@item - (a dash)
Clear the environment.  This is understood only when used as a first
word in @var{args}.

@item -@var{name}
Unset the environment variable @var{name}.

@item -@var{name}=@var{val}
Unset the environment variable @var{name} only if its value is @var{val}.

@item @var{name}
Retain the environment variable @var{name}.

@item @var{name}=@var{value}
Define environment variable @var{name} to have given @var{value}.

@item @var{name}+=@var{value}
Retain variable @var{name} and append @var{value} to its existing
value.  If no such variable is present in the environment, it is
created and @var{value} is assigned to it.  However, if @var{value}
begins with a punctuation character, this character is removed from it
before the assignment.  This is convenient for using this construct with
environment variables like @env{PATH}, e.g.:

@smallexample
PATH+=:/sbin
@end smallexample

In this example, if @env{PATH} exists, @samp{:/sbin} will be appended
to it.  Otherwise, it will be created and @samp{/sbin} will be
assigned to it.

@item @var{name}=+@var{value}
Retain variable @var{name} and prepend @var{value} to its existing
value.  If no such variable is present in the environment, it is
created and @var{value} is assigned to it.  However, if @var{value}
ends with a punctuation character, this character is removed from it
before assignment. 
@end table
@end deffn

@node Actions Before Startup
@subsection Actions Before Startup

  Several statements are available that specify actions to perform
immediately before starting the component:

@deffn {Config: component} chdir @var{dir}
Change to the directory @var{dir}.
@end deffn

@deffn {Config: component} remove-file @var{file-name}
Remove @var{file-name}.  This is useful, for example, to remove stale
@acronym{UNIX} sockets or pid-files, which may otherwise prevent the
component from starting normally.

As of version @value{VERSION} only one @command{remove-file} may be given.
@end deffn

@deffn {Config: component} pass-fd-timeout @var{number}
Wait @var{number} of seconds for the @samp{pass-fd} socket
to become available (@pxref{Meta1-Style Components}).  Default is
5 seconds.
@end deffn

@node Exit Actions
@subsection Exit Actions
@kwindex return-code
  The default behavior of @command{pies} if an @samp{init-style}
component terminates is to restart it.  Unless the component
terminates with 0 exit code, a corresponding error message is issued
to the log file.  This behavior can be modified using
@code{return-code} statement:

@deffn {Config: component} return-code
@smallexample
return-code @var{codes} @{
  @dots{}
@}
@end smallexample
@end deffn

  The @var{codes} argument is a list of exit codes or signal names.
Exit codes can be specified either as decimal numbers or as symbolic code
names from the table below: 

@float Table, exit-codes
@caption{Standard Exit Codes}
@multitable @columnfractions 0.5 0.3
@headitem Name       @tab Numeric value
@item EX_OK          @tab 0 
@item EX_USAGE       @tab 64
@item EX_DATAERR     @tab 65
@item EX_NOINPUT     @tab 66
@item EX_NOUSER      @tab 67
@item EX_NOHOST      @tab 68
@item EX_UNAVAILABLE @tab 69
@item EX_SOFTWARE    @tab 70
@item EX_OSERR       @tab 71
@item EX_OSFILE      @tab 72
@item EX_CANTCREAT   @tab 73
@item EX_IOERR       @tab 74
@item EX_TEMPFAIL    @tab 75
@item EX_PROTOCOL    @tab 76
@item EX_NOPERM      @tab 77
@item EX_CONFIG      @tab 78
@end multitable
@end float

Signal numbers can be given either as @samp{SIG+@var{n}}, where @var{n}
is the signal number, or as signal names from the following list:
@samp{SIGHUP}, @samp{SIGINT}, @samp{SIGQUIT}, @samp{SIGILL},
@samp{SIGTRAP}, @samp{SIGABRT}, @samp{SIGIOT}, @samp{SIGBUS},
@samp{SIGFPE}, @samp{SIGKILL}, @samp{SIGUSR1}, @samp{SIGSEGV},
@samp{SIGUSR2}, @samp{SIGPIPE}, @samp{SIGALRM}, @samp{SIGTERM},
@samp{SIGSTKFLT}, @samp{SIGCHLD}, @samp{SIGCONT}, @samp{SIGSTOP},
@samp{SIGTSTP}, @samp{SIGTTIN}, @samp{SIGTTOU}, @samp{SIGURG},
@samp{SIGXCPU}, @samp{SIGXFSZ}, @samp{SIGVTALRM}, @samp{SIGPROF},
@samp{SIGWINCH}, @samp{SIGPOLL}, @samp{SIGIO}, @samp{SIGPWR},
@samp{SIGSYS}.

  If the component exits with an exit code listed in @var{codes}
or is terminated on a signal listed in @var{codes},  
@command{pies} executes actions specified in that @samp{return-code}
block.  The actions are executed in the order of their appearance below:

@deffn {Config: return-code} exec @var{command}
Execute the supplied external command.  Prior to execution, all
file descriptors are closed.  The @var{command} inherits the
environment from the main @command{pies} process with the following
additional variables:

@table @env
@item PIES_VERSION
The @command{pies} version number (@value{VERSION}).

@item PIES_COMPONENT
Tag of the terminated component (@pxref{Component Statement, tag}).

@item PIES_PID
PID of the terminated component.

@item PIES_SIGNAL
If the component terminated on signal, the number of that signal.

@item PIES_STATUS
Program exit code.
@end table
@end deffn

@deffn {Config: return-code} action @samp{disable | restart}
If @samp{restart} is given, restart the component.  This is the
default.  Otherwise, mark the component as disabled.  Component
dependents are stopped and marked as disabled as well.  Once disabled,
the components are never restarted, unless their restart is requested
by the administrator. 
@end deffn

@deffn {Config: return-code} notify @var{email-string}
Send an email notification to addresses in @var{email-string}.
@xref{Notification}, for a detailed discussion of this feature.
@end deffn

@deffn {Config: return-code} message @var{string}
Supply notification message text to use by @code{notify} statement.
@xref{Notification}, for a detailed discussion of this feature.
@end deffn

  Any number of @code{return-code} statements are allowed, provided
that their @var{codes} do not intersect.

  The @code{return-code} statements can also be used outside of
@code{component} block.  In this case, they supply global actions,
i.e. actions applicable to all components.  Any @code{return-code}
statements appearing within a @code{component} block override the
global ones.

@node Output Redirectors
@subsection Output Redirectors
@cindex repeater
  Output redirectors allow to redirect the standard error and/or standard
output of a component to a file or @command{syslog} facility.

@deffn {Config: component} stderr @var{type} @var{channel}
@deffnx {Config: component} stdout @var{type} @var{channel}
Redirect standard error (if @code{stderr}) or standard output (if
@code{stdout}) to the given channel.

The type of redirection is specified by @var{type} argument:

@table @asis
@item file
Redirect to a file.  In this case @var{channel} gives the full name of
the file.  For example:

@smallexample
stderr file /var/log/component/name.err;
@end smallexample

@item syslog
Redirect to a syslog channel.  The syslog priority is given by the
@var{channel} argument.  Its allowed values are: @samp{emerg},
@samp{alert}, @samp{crit}, @samp{err}, @samp{warning}, @samp{notice},
@samp{info}, @samp{debug}.  The facility is inherited from the
@code{syslog} statement (@pxref{syslog}), or from the @code{facility}
statement (see below), if given.

Example:

@smallexample
stderr syslog err;
@end smallexample
@end table
@end deffn

@deffn {Config: component} facility @var{syslog-facility}
Specify the syslog facility to use in syslog redirectors.  Allowed 
@var{syslog-facility} values are: @samp{user}, @samp{daemon},
@samp{auth}, @samp{authpriv}, @samp{mail}, @samp{cron}, @samp{local0}
through @samp{local7} (all names case-insensitive), or a facility number.
@end deffn

@node Inetd-Style Components
@subsection Inetd-Style Components
@cindex inetd-style components
  Inetd-style components are declared using @code{mode inetd}
statement.  You must also declare a socket to listen on.

@anchor{inetd-socket}
@deffn {Config: component} socket @var{url}
Define a socket to listen on.  Allowed values for @var{url} are:

@table @asis
@item file name
Specifies a @acronym{UNIX} socket file name.  You may use a relative
file name, provided that @code{chdir} statement is used for this
component (@pxref{Actions Before Startup, chdir}).

@item local://@var{file}[;@var{args}]
@itemx file://@var{file}[;@var{args}]
@itemx unix://@var{file}[;@var{args}]
Listen on the @acronym{UNIX} socket file @var{file}, which is either
an absolute or relative file name, as described above.  Optional
arguments @var{args} control ownership and file mode of @var{file}.  They
are a list of assignments, separated by semicolons.  The following
values are allowed:

@table @asis
@item user
User name of the socket owner.

@item group
Owner group of the socket, if it differs from the @code{user} group.

@item mode
Socket file mode (octal number between @samp{0} and @samp{777}).

@item umask
Umask to use when creating the socket (octal number between @samp{0}
and @samp{777}). 
@end table

For example:

@smallexample
socket "unix:/var/run/socket;user=nobody;group=mail;mode=770";
@end smallexample

@item inet://@var{ip}:@var{port}
Listen on IPv4 address @var{ip} (may be given as a symbolic host name),
on port @var{port}.
@end table

Notice, that @command{pies} version @value{VERSION} handles only
@acronym{TCP} sockets and only IPv4 addresses.  Support for IPv6 will
be added in future versions.  Support for @acronym{UDP} sockets will
be added if there is a demand.
@end deffn

@node Meta1-Style Components
@subsection Meta1-Style Components
@cindex meta1-style components
  Meta1-style components are declared using @code{mode pass}
statement.  For such components, you must declare both a socket to
listen on (@pxref{inetd-socket} and a @acronym{UNIX} socket name to
pass the file descriptor to the component.  The latter is defined
using @code{pass-fd-socket} statement:

@deffn {Config: component} pass-fd-socket @var{file-name}
The argument is an absolute or relative file name of the socket file.
In the latter case, the @code{chdir @var{dir}} statement must be used
for this component (@pxref{Actions Before Startup, chdir}), and the
socket will be looked under @var{dir}.

This socket file is supposed to be created by the component binary
upon its startup.
@end deffn

@node Component Syntax Summary
@subsection Component Syntax Summary
  This subsection summarizes the @code{component} summary.  For each
statement, a reference to its detailed description is supplied.

@smallexample
component @var{tag} @{
  # @r{Component execution mode.}
  # @xref{Component Statement, mode}.
  mode @samp{exec | wait | accept | inetd | nostartaccept | pass-fd | pass};
  
  # @r{Full name of the program.}
  # @xref{Component Statement, program}.
  program @var{name};
  # @r{Command line.}
  # @xref{Component Statement, command}.
  command @var{string};
  
  # @r{Disable this entry.}
  # @xref{Component Statement, disable}.
  disable @var{bool};
  # @r{Mark this entry as precious.}
  # @xref{Component Statement, precious}.  
  precious @var{bool};
  
  # @r{List of prerequisites.}
  # @xref{Prerequisites}.
  prerequisites (@var{compnames});
  # @r{List of components for which this one is a prerequisite.}
  # @xref{Prerequisites, dependents}.
  dependents (@var{compnames});
  
  # @r{Listen on the given url.}
  # @xref{Inetd-Style Components}.
  socket @var{url};
  
  # @r{Pass fd through this socket.}
  # @xref{Meta1-Style Components}.
  pass-fd-socket @var{soket-name};
  
  # @r{ACL for this component.}
  # @xref{ACL Statement, ACL Statement,, mailutils, GNU Mailutils Manual}.
  acl @{ @dots{} @}
  
  # @r{Override default syslog facility for this component.}
  facility @var{facility};
  # @r{Redirect program's standard output to the given}
  # @r{file or syslog priority.}
  # @xref{Output Redirectors}.
  stdout @samp{file | syslog} @var{channel};
  # @r{Redirect program's standard error to the given}
  # @r{file or syslog priority.}
  # @xref{Output Redirectors}.
  stderr @samp{file | syslog} @var{channel};
  
  # @r{Run with this user privileges.}
  # @xref{Component Privileges}.
  user @var{user-name};
  # @r{Retain supplementary group.}
  # @xref{Component Privileges, group}.
  group @var{group-name};
  # @r{Retain all supplementary groups of which user is a member.}
  # @xref{Component Privileges, allgroups}.
  allgroups @var{bool};
  
  # @r{Set system limits.}
  # @xref{Resources}.
  limits @var{string};
  
  # @r{Force this umask.}
  # @xref{Resources, umask}.
  umask @var{number};
  
  # @r{Set program environment.}
  # @xref{Resources, env}.
  env @var{assignments};
  
  # @r{Change to this directory before executing the component.}
  # @xref{Actions Before Startup, chdir}.
  chdir @var{dir};
  # @r{Remove @var{file-name} before starting the component.}
  # @xref{Actions Before Startup, remove-file}.
  remove-file @var{file-name};
  # @r{Wait @var{number} of seconds for pass-fd socket to become available.}
  # @xref{Actions Before Startup, pass-fd-timeout}.
  pass-fd-timeout @var{number};
  
  # @r{Actions:}
  # @xref{Exit Actions}.
  return-code @var{exit-code-list} @{
    # @r{Action to take when a component finishes with this return code.}
    action @samp{disable | restart};
    # @r{Notify these addresses when then component terminates.}
    notify @var{email-string};
    # @r{Notification message text (with headers).}
    message @var{string};
  @}
@}
@end smallexample

@node Notification
@section Notification
@cindex Notification

  Pies provides a @dfn{notification} mechanism, which can be used to
send email messages when components terminate.  The exact contents
of such notifications and the list of their recipients may depend on
the exit code which the component returned.  Notification is
configured by supplying @samp{notify} and @samp{message} statements
in a @samp{return-code} block.

@deffn {Config: return-code} notify @var{email-string}
Send email notification to addresses from @var{email-string}.  The
latter is a comma-separated list of email addresses, e.g.:

@smallexample
notify "root@@localhost,postmaster@@localhost";
@end smallexample

Each address may be optionally enclosed in angular brackets (@samp{<}
and @samp{>}).
@end deffn

@deffn {Config: return-code} message @var{string}
Supply the email message text to be sent.  @var{String} must be a
valid RFC 822 message, i.e. it must begin with message headers,
followed by an empty line and the actual message body.

The message may contain variable data in the form of
variable references.  A @dfn{variable} is an entity that holds
some data describing the event that occurred.  Meta-variables
are referenced using the following construct:

@smallexample
$@{@var{name}@}
@end smallexample

@noindent
where @var{name} is the name of the variable.  Before actually sending
the message, each occurrence of this construct is removed from the
text and replaced by the actual value of the referenced variable.
For example, the variables @samp{component} and @samp{retcode} expand
to the name of the exited component and its exit code, correspondingly.
Supposing that @samp{component} is @samp{ftpd} and @samp{retcode} is
76, the following fragment:

@smallexample
Subject: $@{component@} exited with code $@{retcode@}
@end smallexample

@noindent
will become:

@smallexample
Subject: ftpd exited with code 76
@end smallexample

The table below lists all available variables and their expansions:

@float Table, notification-variables
@caption{Notification Variables}
@multitable @columnfractions 0.5 0.5
@headitem Variable @tab Expansion
@item canonical-program-name @tab @samp{pies}
@item program-name @tab Program name of the @command{pies} binary.
@item package      @tab Package name (@samp{Pies}).
@item version      @tab Package version (@value{VERSION}).
@item component    @tab Name of the terminated component.
@item termination  @tab Termination cause (see below).
@item retcode      @tab Component exit code (or signal number, if exited
on signal), in decimal.
@end multitable
@end float

The @samp{termination} variable is set so as to facilitate its use
with the @samp{retcode} variable.  Namely, its value is @samp{exited
with}, if the component exited and @samp{terminated on signal}, if it
terminated on a signal.  Thus, using

@smallexample
$@{termination@} $@{retcode@}
@end smallexample

@noindent
results in a correct English sentence.  This message, however, cannot
be properly internationalized.  This will be fixed in the future
versions.

If @code{message} statement is not given, the following default
message is used instead:

@smallexample
From: <>
X-Agent: $@{canonical-program-name@} ($@{package@} $@{version@})
Subject: Component $@{component@} $@{termination@} $@{retcode@}.

@end smallexample
@end deffn

@cindex mailer
@cindex @command{sendmail}
  Notification messages are sent using an external program, called
@dfn{mailer}.  By default it is @command{/usr/sbin/sendmail}.  You can
change it using the following configuration statement:

@deffn {Config} mailer-program @var{prog}
Use @var{prog} as a mailer program.  The mailer must meet the
following requirements:

@enumerate 1
@item It must read the message from its standard input.
@item It must treat the non-optional arguments in its command line as
recipient addresses.
@end enumerate

For example, the following statement instructs @command{pies} to use
@command{exim} as a mailer:

@smallexample
mailer-program /usr/sbin/exim;
@end smallexample

@end deffn

By default, the mailer program is invoked as follows:

@smallexample
/usr/sbin/sendmail -oi -t @var{rcpts}
@end smallexample

@noindent
where @var{rcpts} is a whitespace-separated list of addresses supplied
in the @samp{notify} statement.

The mailer command may be altered using @samp{mailer-command-line} statement:

@deffn {Config} mailer-command-line @var{string}
Set mailer command line.  Notice, that @var{string} must include the
command name as well.  The @samp{mailer-program} statement supplies
the full name of the binary which will be executed, while the first word
from the @samp{mailer-command-line} argument gives the string it
receives as @samp{argv[0]}. 

  The example below shows how to use this statement to alter the
envelope sender address:

@smallexample
mailer-command-line "sendmail -f root@@domain.com -oi -t";
@end smallexample
@end deffn

@node ACL
@section Access Control Lists
@cindex @acronym{ACL}
@cindex access control lists
@dfn{Access control lists}, or @acronym{ACL}s for short, are lists of
permissions that control access to @samp{inetd}, @samp{access} and
@samp{meta1}-style components.

An @acronym{ACL} is defined using @code{acl} block statement:

@deffn {Config} acl
@smallexample
acl @{
  @var{definitions}
@}
@end smallexample
@end deffn

  This statement is allowed both in global context and within a
@samp{component} block.  If both are present, the global-level
@acronym{ACL} is consulted first, and if it allows access, the
component @acronym{ACL} is consulted.  As a result, access is
granted only if both lists allow it.

  A @dfn{named @acronym{ACL}} is an access control list which is
assigned its own name.  Named @acronym{ACL}s are defined using
the @samp{defacl} statement:

@deffn {Config} defacl @var{name}
@smallexample
defacl @var{name} @{
  @var{definitions}
@}
@end smallexample
 
  The @var{name} parameter specifies a unique name for that
@acronym{ACL}.  Named @acronym{ACL}s are applied only if
referenced from another @acronym{ACL} (either global or a
per-component one, or any named @acronym{ACL}, referenced
from these).  @xref{acl-ref, ACL references}, below.
@end deffn

  In both forms, the part between the curly braces (denoted by
@var{definitions}), is a list of @dfn{access control statements}.
There are two types of such statements:  

@deffn {Config: acl} allow [@var{user-group}] @var{sub-acl} @var{host-list}
@deffnx {Config: acl} allow any
Allow access to the component.
@end deffn
@ignore
@deffn {Config: defacl} allow [@var{user-group}] @var{sub-acl} @var{host-list}
@end deffn
@end ignore

@deffn {Config: acl} deny [@var{user-group}] @var{sub-acl} @var{host-list}
@deffnx {Config: acl} deny any
Deny access to the component.
@end deffn
@ignore
@deffn {Config: defacl} deny [@var{user-group}] @var{sub-acl} @var{host-list}
@end deffn
@end ignore

All parts of an access statement are optional, but at least one
of them must be present.  The @var{user-group} part is reserved for
future use and is described in more detail in @ref{User-Group ACLs}.

@anchor{acl-ref}
The @var{sub-acl} part, if present, allows to branch to another
@acronym{ACL}.  The syntax of this part is:

@smallexample
acl @var{name}
@end smallexample

@noindent
where @var{name} is the name of an @acronym{ACL} defined previously in
@samp{defacl} statement.

The @var{host-list} group allows to match client addresses.
It consists of the @code{from} keyword followed by a list of
@dfn{address specifiers}.  Allowed address specifiers are:

@table @asis
@item @var{addr}
Matches if the client @acronym{IP} equals @var{addr}.
The latter may be given either as an @acronym{IP}
address or as a host name, in which case it will be resolved and the
first of its @acronym{IP} addresses will be used.

@item @var{addr}/@var{netlen}
Matches if first @var{netlen} bits from the client @acronym{IP}
address equal to @var{addr}.  The network mask length, @var{netlen}
must be an integer number in the range from 0 to 32.  The address part,
@var{addr}, is as described above. 

@item @var{addr}/@var{netmask}
The specifier matches if the result of logical @acronym{AND} between
the client @acronym{IP} address and @var{netmask} equals to
@var{addr}.  The network mask must be specified in ``dotted quad''
form, e.g. @samp{255.255.255.224}.

@item @var{filename}
Matches if connection was received from a @acronym{UNIX} socket
@var{filename}, which must be given as an absolute file name.
@end table

@anchor{acl-any}
The special form @samp{allow any} means to allow access
unconditionally.  Similarly, @samp{deny any}, denies access
unconditionally.  Normally, one of these forms appears as the last
statement in an @acronym{ACL} definition.

To summarize, the syntax of an access statement is:

@smallexample
allow|deny [acl @var{name}] [from @var{addr-list}]
@end smallexample

@noindent
where square brackets denote optional parts.

When an @acronym{ACL} is checked, its entries are tried in turn until
one of them matches, or the end of the list is reached.  If a matched
entry is found, its command verb, @code{allow} or @code{deny}, defines
the result of the @acronym{ACL} check.  If the end of the list is reached,
the result is @samp{allow}, unless explicitly specified otherwise
(using the @ref{acl-any, ``any'' form}.)

For example, the following @acronym{ACL} allows access for anybody 
coming from networks @samp{192.168.10.0/24} and @samp{192.168.100.0/24},
or any connection that matches the named @acronym{ACL} @samp{my-nets}
(which should have been defined before this definition).  Access is
denied for anybody else:

@smallexample
@group
acl @{
    allow from (192.168.10.0/24, 192.168.100.0/24);
    allow acl "my-nets";
    deny all;
@}
@end group
@end smallexample

@node include-meta1
@section Using MeTA1 Configuration File
@flindex /etc/meta1/meta1.conf
  MeTA1 is a mail transfer agent of new generation, designed
to replace Sendmail in the future (@uref{http://www.meta1.org}).
It has a modular structure, each module being an independent
responsible for a particular task.  The components are configured in
the MeTA1 configuration file @file{/etc/meta1/meta1.conf}.

  @command{Pies} is able to take a list of components directly
from MeTA1 configuration file:

@deffn {Config} include-meta1 @var{file}
Parse @var{file} as MeTA1 configuration file and incorporate
components defined there into the current component list.

For example:

include-meta1 /etc/meta1/meta1.conf;
@end deffn

Thus, you can use @command{pies} instead of the default MeTA1 program
manager @command{mcp}.  This is particularly useful if you use
@samp{Mailfromd} (@uref{http://mailfromd.software.gnu.org.ua}) to
control the mail flow.

To ensure compatibility with MeTA1, the components read from its
configuration file are started in the reverse order (i.e. from last to
first), and stopped in the order of their appearance in @var{file}.
Of course, this does not affect normal @command{pies} components.

The following @command{pies} statements are silently applied to
all MeTA1 components:

@smallexample
allgroups yes;
stderr file @var{compname}.log
chdir @var{queue-dir}
@end smallexample

Here, @var{compname} stands for the name of the component, and
@var{queue-dir} stands for the name of MeTA1 queue directory.  The
latter is @file{/var/spool/meta1} by default.  It can be changed using
the following statement:

@deffn {Config} meta1-queue-dir @var{dir}
Set name of MeTA1 queue directory.
@end deffn

To override any default settings for a MeTA1 component, add a
@code{command} section with the desired settings after including
@file{meta1.conf}.  For example, here is how to redirect the
standard error of the @samp{smtps} component to @samp{local1.debug}
syslog channel:

@smallexample
include-meta1 /etc/meta1/meta1.conf

component smtps @{
  facility local1;
  stderr syslog debug;
@}
@end smallexample

@node Global Configuration
@section Global Configuration
@cindex Global Configuration
The statements described in this section affect @command{pies}
behavior as a whole.

@anchor{syslog}
@deffn {Config} syslog @{ ... @}
This block statement configures logging via syslog.  It has two
substatements:
@end deffn

@deffn {Config: syslog} tag @var{string}
Prefix syslog messages with this string.  By default, the program name
is used.
@end deffn

@deffn {Config: syslog} facility @var{string}
Set syslog facility to use.  Allowed values are: @samp{user},
@samp{daemon}, @samp{auth}, @samp{authpriv}, @samp{mail}, @samp{cron},
@samp{local0} through @samp{local7} (case-insensitive), or a facility
number.
@end deffn

@deffn {Config} umask @var{number}
Set the default umask.  The @var{number} must be an octal value not greater
than @samp{777}.  The default umask is inherited at startup.
@end deffn

@deffn {Config} limits @var{arg}
Set global system limits for all pies components.  @xref{Resources,
limits}, for a detailed description of @var{arg}.
@end deffn

@deffn {Config} return-code @{ ... @}
Configure global exit actions.  @xref{Exit Actions}, for a detailed
description of this statement.
@end deffn

@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,
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

@deffn {Config} group @var{group-list}
Retain the supplementary groups, specified in @var{group-list}.
@end deffn

@deffn {Config} allgroups @var{bool}
Retain all supplementary groups of which user, given with
@command{user} statement, is a member.  
@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:

@deffn {Config} debug @var{level}
Set debugging level.  The @var{level} must be a non-negative decimal
integer.  In version @value{VERSION} the following debugging levels
are used:

@table @asis
@item 1
Log all basic actions: starting and stopping of components, received incoming
@acronym{TCP} connections, sending mails.  Notify about setting
limits.  Log pre-startup actions (@pxref{Actions Before Startup}).

@item 2
Log setting particular limits.  Log the recomputed alarms.

@item 4
Dump execution environments

@item 6
Debug the parser of MeTA1 configuration grammar.

@item 7
Debug the lexical analyzer of MeTA1 configuration file.
@end table
@end deffn

@anchor{source-info}
@deffn {Config} source-info @var{bool}
This statement decides whether debugging messages should contain
source information.  To enable source information, use:

@smallexample
source-info yes;
@end smallexample

This feature is designed for @command{pies} developers.
@end deffn

@node Configuration Example
@chapter Configuration Example
  In this section we provide several examples of working @command{pies}
configuration files.

@menu
* Simple Pies::
* Hairy Pies::
* Inetd Pies::
@end menu

@node Simple Pies
@section Simplest Case: Using Pies to Run Pmult
  The example below runs @command{pmult} (@pxref{pmult, Pmilter
multiplexer program,, mailfromd, Mailfromd Manual}) utility with
the privileges of @samp{meta1} user.  Both standard error and standard
output are redirected to the syslog facility @samp{mail}, priorities
@samp{err} and @samp{info}, correspondingly.

@smallexample
component pmult @{
  command "/usr/local/sbin/pmult";
  user meta1s;
  facility mail;
  stderr syslog err;
  stdout syslog info;
@}
@end smallexample

@node Hairy Pies
@section Using Pies to Run Pmult and MeTA1
  The example below is a working configuration file for running
@command{pmult} and all components of MeTA1, configured in
@file{/etc/meta1/meta1.conf}.  The global @code{return-code} statement
is used to configure @command{pies} behavior for some exit codes.

@smallexample
# Sample pies configuration for running pmult and MeTA1

# Special handling for exit codes that mean the program was
# incorrectly used or misconfigured.
return-code (EX_USAGE, EX_CONFIG) @{
  action disable;
  notify "root";
  message <<- EOT
    From: Pies <>
    X-Agent: $@{canonical-program-name@} ($@{package@} $@{version@})
    Subject: Component $@{component@} disabled.
    
    Component "$@{component@}" has terminated with code $@{retcode@},
    which means it encountered some configuration problem.
    I will not restart it automatically. Please fix its configuration
    and restart it manually at your earliest convenience.
    
    To restart, run ``$@{program-name@} -R $@{component@}''
    ---
    Wuff-wuff,
    Pies
  EOT;
@}

component pmult @{
  command "/usr/local/sbin/pmult";
  user meta1s;
  stderr syslog err;
  stdout syslog info;
@}

include-meta1 "/etc/meta1/meta1.conf";
@end smallexample

@node Inetd Pies
@section Running Pies Instead of Inetd

This configuration file allows to run @command{pies} instead of
@command{initd}.  It starts two services: @samp{ftp} and @samp{pop3d},
and restricts access to them to two local subnets:

@smallexample
acl @{
   allow from 10.10.10.0/24;
   allow from 192.168.10.0/27;
   deny from any;
@}

debug 3;

component ftp @{
   mode inetd;
   socket "inet://0.0.0.0:21";
   umask 027;
   program /usr/sbin/ftpd
   command "ftpd -l -C";
@}

component pop3d @{
   mode inetd;
   socket "inet://0.0.0.0:110";
   program "/usr/sbin/pop3d";
   command "pop3d --inetd";
@}
@end smallexample

@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.

@anchor{pies-status}
  After startup, you can verify the status of the running process
using @option{--status} command line option:

@smallexample
@group
$ pies --status
redirector smtps/stderr 4697
redirector pmult/stderr 4677
redirector pmult/stdout 4676
component pmult 4678 /usr/local/sbin/pmult
component smar 4680 smar -f /etc/meta1/meta1.conf -d 100
component qmgr 4691 qmgr -f /etc/meta1/meta1.conf
component smtpc 4696 smtpc -f /etc/meta1/meta1.conf
component smtps 4698 smtps -d100 -f /etc/meta1/meta1.conf
@end group
@end smallexample

  In its output, lines beginning with @samp{component} refer to
running components.  For running components, the following information
is displayed:

@enumerate 1
@item Component tag (@pxref{Component Statement}).
@item PID of the running instance of the component.
@item Command line of the component, as set by the @code{command}
statement (@pxref{Component Statement, command}).
@end enumerate

If the component is not running, the reason is indicated in the PID
column, between the square brackets, e.g.:

@smallexample
component pmult [disabled; scheduled for Mon 01 Dec 2008 20:27:02] 
  /usr/local/sbin/pmult
@end smallexample

@noindent
(the example above is split in two lines for readability).

@anchor{pies-restart}
@xopindex{restart-component, described}
  You can restart any component by using the
@option{--restart-component} (@option{-R}) option, e.g.:

@smallexample
$ pies -R pmult smtps
@end smallexample

@xopindex{stop, described}
  To stop all running components and shut down @command{pies}, use the
@option{--stop} (@option{-S}) command line option:

@smallexample
$ pies --stop
@end smallexample

@cindex dependencies
@anchor{dump-depmap}
@xopindex{dump-depmap option, introduced}
  Two options are provided for verifying inter-component
dependencies.  The @option{--dump-depmap} option prints on the
standard output the @dfn{dependency map}.  This map is a square matrix
with rows representing dependents and columns representing prerequisites.
An @samp{X} sign is placed on each crossing which corresponds to the
actual dependency.  For example:

@smallexample
@group
$ pies --dump-depmap
Dependency map:
    0  1  2  3  4
 0                
 1                
 2     X          
 3        X       
 4     X  X       

Legend:
 0: pmult
 1: smar
 2: qmgr
 3: smtpc
 4: smtps
@end group
@end smallexample

This example corresponds to the configuration file shown in @ref{Hairy
Pies}.  To illustrate how to read it, consider the 4th row of the
table.  According to the legend, number 4 means @samp{smtps}
component.  There are two @samp{X} marks: in columns 1 and 2.  This
means that @samp{smtps} depends on @samp{smar} and @samp{qmgr}.

@anchor{dump-prereq}
@xopindex{dump-prereq, described}
  You can also list prerequisites explicitly:

@smallexample
@group
$ pies --dump-prereq
qmgr: smar
smtpc: qmgr
smtps: smar qmgr
@end group
@end smallexample

@node Invocation
@chapter Pies Invocation

This section summarizes @command{pies} command line options.

@table @option
@opsummary{config-file}
@item --config-file=@var{file}
@item -c @var{file}
Read configuration from @var{file}, instead of the default
@file{/etc/pies.conf}.

@xref{Pies Configuration File}.

@opsummary{config-help}
@item --config-help
Show configuration file summary.  @xref{Pies Configuration File}.

@opsummary{define}
@item --define=@var{sym}[=@var{value}]
@itemx -D @var{symbol}[=@var{value}]
Define symbol @var{sym} as having @var{value}, or emtpy, if
the @var{value} is not given.  @xref{Preprocessor}.

@opsummary{debug}
@item --debug=@var{level}
@itemx -x @var{level}
Set debug verbosity level.  @xref{Pies Debugging}, for a description
of @var{level}.

@opsummary{dump-depmap}
@item --dump-depmap
Dump dependency map.  @xref{dump-depmap}.

@opsummary{dump-prereq}
@item --dump-prereq
Dump prerequisite charts.  @xref{dump-prereq}.

@item -E
Preprocess configuration file and exit.  @xref{Preprocessor}.

@opsummary{force}
@item --force
Force startup even if another instance may be running.

@opsummary{foreground}
@item --foreground
Remain in foreground.

@item --help
Display a short usage summary and exit.

@opsummary{lint}
@item --lint
@itemx -t

@opsummary{source-info}
@item --source-info
Show source info with debugging messages.  @xref{source-info}.

@opsummary{status}
@item --status
@itemx -s
Display info about the running instance.  @xref{pies-status}.

@opsummary{stderr}
@item --stderr
Log to standard error.

@opsummary{stop}
@item --stop
@itemx -S
Stop the running instance.  

@opsummary{syslog}
@item --syslog
Log to syslog.  This is the default.

@opsummary{reload}
@opsummary{hup}
@item -r
@itemx --reload
@itemx --hup
Reload the running instance of pies.

@opsummary{restart-component}
@item -R
@itemx --restart-component
Restart components named in the command line.  @xref{pies-restart}.

@item --version
Display program version and license information and exit.

@xopindex{undefine}
@item --undefine=@var{sym}
@itemx -U @var{sym}
Undefine symbol @var{sym}.  @xref{Preprocessor}.

@item --usage
Display a short summary of available options and exit.
@end table

@node Reporting Bugs
@chapter How to Report a Bug

  Send bug-reports and suggestions to @email{bug-pies@@gnu.org.ua}.

  If you think you've found a bug, please be sure to include maximum
information needed to reliably reproduce it, or at least to analyze
it.  The information needed is:

@itemize
@item Version of the package you are using.
@item Compilation options used when configuring the package.
@item Run-time configuration (@file{pies.conf} file and the command
line options used).
@item Detailed description of the bug.
@item Conditions under which the bug appears.
@end itemize  

@node User-Group ACLs
@appendix User-Group ACLs
@include usr-acl.texi

@node Copying This Manual
@appendix GNU Free Documentation License
@include fdl.texi

@node Concept Index
@unnumbered Concept Index

This is a general index of all issues discussed in this manual

@printindex cp

@bye