aboutsummaryrefslogtreecommitdiff
path: root/doc/pies.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/pies.texi')
-rw-r--r--doc/pies.texi715
1 files changed, 597 insertions, 118 deletions
diff --git a/doc/pies.texi b/doc/pies.texi
index cc35b5d..22c0f83 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -75,47 +75,45 @@ This edition of the @cite{Pies Manual}, last updated @value{UPDATED},
documents @command{pies} Version @value{VERSION}.
@end ifnottex
@menu
* Intro::
* Pies Configuration File::
-* Component Statement::
-* include-meta1::
-* Global Configuration::
* Pies Debugging::
* Configuration Example::
* Command Line Usage::
* Pies Invocation::
+* Reporting Bugs::
Appendices
* Copying This Manual:: The GNU Free Documentation License.
* Concept Index:: Index of Concepts.
-@c @detailmenu
-@c @end detailmenu
+@detailmenu
+@end detailmenu
@end menu
@node Intro
@chapter Introduction
-@cindex component, pies
+@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, pies
-@cindex dependency, pies
-@cindex dependents, pies
+@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}.
@@ -128,13 +126,13 @@ 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
- These way of operation applies to so-called @dfn{init-style}
+ 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.
@@ -177,59 +175,323 @@ simultaneously.
configuration file and terminated in the reverse order. When starting or
stopping component dependencies, the same ordering is preserved.
This order is reversed for 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 a non-zero status.
+
+@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 1 otherwise.
+
+@opindex -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::
+* ACL:: Access Control Lists
+* include-meta1::
+* Global Configuration::
@end menu
-@node Pies Configuration File
-@chapter Pies Configuration File
- @command{Pies} reads its configuration from the main Mailutils
-configuration file. @xref{configuration, Mailutils Configuration
-File,, mailutils, GNU Mailutils Manual}, for a description of GNU
-Mailutils configuration system. It is recommended to use
-@code{include @var{directory}} statement (@pxref{Include, Include
-Statement,, mailutils, GNU Mailutils Manual}), and to place
-@command{pies} configuration in file @file{@var{directory}/pies}.
-@xref{MeTA1,,, mailfromd, Mailfromd Manual}, for an example.
-
-The following standard Mailutils configuration statements are understood:
-
-@multitable @columnfractions 0.3 0.6
-@headitem Statement @tab Reference
-@item debug @tab @xref{Debug Statement, Mailutils Debug Statement,,
-mailutils, GNU Mailutils Manual}.
-@item logging @tab @xref{Logging Statement, Mailutils Logging,,
-mailutils, GNU Mailutils Manual}.
-@item include @tab @xref{Include, Include Statements,,
-mailutils, GNU Mailutils Manual}.
-@item mailer @tab @xref{Mailer, Mailer Statement,,
-mailutils, GNU Mailutils Manual}.
-@item acl @tab @xref{ACL Statement, ACL Statement,,
-mailutils, GNU Mailutils Manual}.
+@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. Simple statement is terminated
+with a semicolon (@samp{;}), unless it contains a @dfn{here-document}
+(see below), in which case semicolon is optional.
+
+ Examples of simple statements:
+
+@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
+@item 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 \\ @tab A single backslash (@samp{\})
+@item \" @tab A double-quote.
@end multitable
+@end float
+
+ In addition, the sequence @samp{\@var{newline}} 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 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 (mime);}.
+
+@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 configuration file, @command{pies} preprocesses
+it. The built-in preprocessor handles only file inclusion
+and @code{#line} statements (@FIXME-pxref{Pragmatic Comments}), while the
+rest of traditional preprocessing facilities, such as macro expansion,
+is supported via @command{m4}, which is used as an external preprocessor.
+
+ The detailed description of @command{m4} facilities lies far beyond
+the scope of this document. You will find a complete user manual in
+@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
+For the rest of 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.
@node Component Statement
-@chapter 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 statements are allowed within the @code{component} block:
-@deffn {Pies Conf} mode @var{mode}
+@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
@@ -246,35 +508,35 @@ the default.
@item accept
Create a @samp{accept-style} component (@pxref{accept-style}).
@end table
@end deffn
-@deffn {Pies Conf} program @var{name}
+@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 {Pies Conf} command @var{string}
+@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 {Pies Conf} disable @var{bool}
+@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 {Pies Conf} precious @var{bool}
-@cindex precious components, pies
+@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
@@ -288,19 +550,19 @@ respawn too fast.
* Inetd-Style Components::
* Meta1-Style Components::
* Component Syntax Summary::
@end menu
@node Prerequisites
-@section Component Prerequisites
+@subsection Component Prerequisites
@cindex declaring prerequisites
@cindex prerequisites, declaring
Prerequisites (@pxref{component prerequisite}) for a component are
declared using the following statement:
-@deffn {Pies Conf} prerequisites @var{tag-list}
+@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.
@@ -309,41 +571,41 @@ Declare all components defined so far as prerequisites for this one.
No prerequisites. This is the default.
@end table
@end deffn
If you wish, you can define dependents, instead of prerequisites:
-@deffn {Pies Conf} dependents @var{tag-list}
+@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
-@section Component Privileges
-@cindex privileges, pies
+@subsection Component Privileges
+@cindex privileges
Following statements control the privileges the component
is executed with.
-@deffn {Pies Conf} user @var{user-name}
+@deffn {Config: component} user @var{user-name}
Start component with the UID and GID of this user.
@end deffn
-@deffn {Pies Conf} group @var{group-list}
+@deffn {Config: component} group @var{group-list}
Retain supplementary groups, specified in @var{group-list}.
@end deffn
-@deffn {Pies Conf} allgroups @var{bool}
+@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
-@section Resources
+@subsection Resources
-@deffn {Pies Conf} limits @var{string}
+@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:
@@ -371,18 +633,18 @@ limits T10 R20 U16 P20
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 {Pies Conf} umask @var{number}
+@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 {Pies Conf} env @var{args}
+@deffn {Config: component} env @var{args}
Set program environment.
Arguments are a whitespace-delimited list of specifiers. The
following specifiers are understood:
@table @asis
@@ -425,50 +687,52 @@ 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
-@section Actions Before Startup
+@subsection Actions Before Startup
Several statements are available that specify actions to perform
immediately before starting the component:
-@deffn {Pies Conf} chdir @var{dir}
+@deffn {Config: component} chdir @var{dir}
Change to the directory @var{dir}.
@end deffn
-@deffn {Pies Conf} remove-file @var{file-name}
+@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 {Pies Conf} settle-timeout @var{number}
+@deffn {Config: component} settle-timeout @var{number}
Wait @var{number} seconds. This is kind of kludge. Currently it is
used for components imported from @file{meta1.conf} file
(@pxref{include-meta1}), where @code{settle-timeout 1} is implied.
This may change in future versions.
@end deffn
@node Exit Actions
-@section 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} 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:
@multitable @columnfractions 0.5 0.3
@@ -505,13 +769,13 @@ is the signal number, or as signal names from the following list:
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 by its substatements.
They are executed in the order of their appearance below:
-@deffn {Pies Conf} exec @var{command}
+@deffn {Config: return-code} exec @var{command}
Execute external command. Prior to execution of @var{command} all
file descriptors are closed. It inherits the environment from the
main @command{pies} process with the following additional variables:
@table @env
@item PIES_VERSION
@@ -528,35 +792,33 @@ If the component terminated on signal, the number of that signal.
@item PIES_STATUS
Program exit code.
@end table
@end deffn
-@deffn {Pies Conf} action @samp{disable | restart}
+@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 {Pies Conf} notify @var{email-string}
+@deffn {Config: return-code} notify @var{email-string}
Send an email notification to addresses in @var{email-string}. The
latter is a comma-separated list of email addresses, e.g.:
@smallexample
notify "root@@localhost,postmaster@@localhost";
@end smallexample
-The @code{mailer} statement (@pxref{Mailer, Mailer Statement,,
-mailutils, GNU Mailutils Manual}) configures the mailer used to send
-the message. The message itself is configured by the @code{message}
+The message itself is configured by the @code{message}
statement.
@end deffn
-@deffn {Pies Conf} message @var{string}
+@deffn {Config: return-code} message @var{string}
Supply notification message text to use by @code{notify} statement.
@var{String} must be a valid RFC 822 message text, i.e. it must begin
with message headers, followed by an empty line and actual message
body.
The following macro-variables are expanded within @var{string}:
@@ -564,13 +826,12 @@ The following macro-variables are expanded within @var{string}:
@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 mu-version @tab Version of GNU Mailutils.
@item component @tab Name of the terminated component.
@item retcode @tab Component exit code, in decimal.
@end multitable
If @code{message} statement is not given, the following default
message is used instead:
@@ -589,19 +850,19 @@ that their @var{codes} do not intersect.
Such 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
-@section 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 {Pies Conf} stderr @var{type} @var{channel}
-@deffnx {Pies Conf} stdout @var{type} @var{channel}
+@deffn {Config: component} stderr @var{type} @var{channel}
+@deffnx {Config} 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
@@ -615,40 +876,39 @@ stderr file /var/log/component/name.err;
@item syslog
Redirect to the 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{logging} statement (@pxref{Logging Statement, Mailutils Logging,,
-mailutils, GNU Mailutils Manual}), or from @code{facility} statement
-(see below), if given.
+@code{syslog} statement (@pxref{syslog}), or from @code{facility}
+statement (see below), if given.
Example:
@smallexample
stderr syslog err;
@end smallexample
@end table
@end deffn
-@deffn {Pies Conf} facility @var{syslog-facility}
+@deffn {Config: component} facility @var{syslog-facility}
Specify the syslog facility to use in syslog redirectors. Allowed
values for @var{syslog-facility} 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
-@section 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 for requests for
such components:
@anchor{inetd-socket}
-@deffn {Pies Conf} socket @var{url}
+@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
@@ -693,32 +953,32 @@ 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
-@section 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 {Pies Conf} pass-fd-socket @var{file-name}
+@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
-@section 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.}
@@ -811,19 +1071,153 @@ component @var{tag} @{
# @r{Notification message text (with headers).}
message @var{string};
@}
@}
@end smallexample
+@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{name} @{
+ @var{definitions}
+@}
+@end smallexample
+@end deffn
+
+The @var{name} parameter specifies a unique name for that
+@acronym{ACL}. This name can be used by another configuration
+statements to refer to that @acronym{ACL}.
+
+A part between the curly braces (denoted by @var{definitions} above),
+is a list of @dfn{access statements}. There are two types of
+such statements:
+
+@deffn {Config: acl} allow @var{user-group} @var{sub-acl} @var{host-list}
+Allow access to resource.
+@end deffn
+
+@deffn {Config: acl} deny @var{user-group} @var{sub-acl} @var{host-list}
+Deny access to resource.
+@end deffn
+
+All parts of an access statement are optional, but at least one
+of them must be present.
+
+The @var{user-group} part specifies which users match this entry.
+Allowed values are the following:
+
+@table @code
+@kwindex all
+@item all
+All users.
+
+@kwindex authenticated
+@item authenticated
+Only authenticated users.
+
+@kwindex group
+@item group @var{group-list}
+Authenticated users which are members of at least one of groups listed in
+@var{group-list}.
+@end table
+
+The @var{sub-acl} part, if present, allows to branch to another
+@acronym{ACL}. The syntax of this group is:
+
+@smallexample
+acl @var{name}
+@end smallexample
+
+@noindent
+where @var{name} is the name of a previously defined @acronym{ACL}.
+
+Finally, the @var{host-list} group allows to match client addresses.
+It consists of a @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
+
+To summarize, the syntax of an access statement is:
+
+@smallexample
+allow|deny [all|authenticated|group @var{group-list}]
+ [acl @var{name}] [from @var{addr-list}]
+@end smallexample
+
+@noindent
+where square brackets denote optional parts and vertical bar means
+@samp{one of}.
+
+When an @acronym{ACL} is applied to a particular object, 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 @acronym{ACL} match. If the end
+of list is reached, the result is @samp{allow}, unless explicitly
+specified otherwise.
+
+@FIXME{Trim that example:}
+For example, the following statement defines an @acronym{ACL} named
+@samp{common}, that allows access for any user connected via local
+@acronym{UNIX} socket @file{/tmp/dicod.sock} or coming from a local
+network @samp{192.168.10.0/24}. Any authenticated users are allowed,
+provided that they are allowed by another @acronym{ACL} @samp{my-nets}
+(which should have been defined before this definition). Users
+coming from the network @samp{10.10.0.0/24} are allowed if they
+authenticate themselves and are members of groups @samp{pies} or
+@samp{users}. Access is denied for anybody else:
+
+@smallexample
+@group
+acl common @{
+ allow all from ("/tmp/pies.sock", "192.168.10.0/24");
+ allow authenticated acl "my-nets";
+ allow group ("pies", "users") from "10.10.0.0/24";
+ deny all;
+@}
+@end group
+@end smallexample
+
@node include-meta1
-@chapter Using MeTA1 Configuration File
+@section Using MeTA1 Configuration File
@cindex /etc/meta1/meta1.conf
@command{Pies} is able to take a list of components from MeTA1
configuration file:
-@deffn {Pies Conf} include-meta1 @var{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;
@@ -848,13 +1242,13 @@ chdir @var{queue-dir}
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 {Pies Conf} meta1-queue-dir @var{dir}
+@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 program
@@ -867,123 +1261,149 @@ component smtps @{
facility local1;
stderr syslog debug;
@}
@end smallexample
@node Global Configuration
-@chapter Global Configuration
+@section Global Configuration
+@cindex Global Configuration
The statements described in this section affect @command{pies}
behavior as a whole.
-@deffn {Pies Conf} umask @var{number}
+@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.
+
+@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
+@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 {Pies Conf} limits @var{arg}
+@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 {Pies Conf} return-code @{ ... @}
+@deffn {Config} return-code @{ ... @}
Configure global exit actions. @xref{Exit Actions}, for a detailed
description of this statement.
@end deffn
-@deffn {Pies Conf} shutdown-timeout @var{number};
+@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
-@section 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 {Pies Conf} pidfile @var{file}
+@deffn {Config} pidfile @var{file}
Write PID of the master @command{pies} process to @var{file}. By
default, master PID is stored in @file{@var{statedir}/pies.pid}
(@FIXME-pxref{statedir}).
@end deffn
-@deffn {Pies Conf} control-file @var{file}
+@deffn {Config} control-file @var{file}
Set file name of the @command{pies} control file. Default is
@file{@var{statedir}/pies.ctl}
@end deffn
-@deffn {Pies Conf} stat-file @var{file}
+@deffn {Config} stat-file @var{file}
Set file name of the statistics output file. Default is
@file{@var{statedir}/pies.stat}.
@end deffn<