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
@@ -78,27 +78,25 @@ documents @command{pies} Version @value{VERSION}.
@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
@@ -110,9 +108,9 @@ 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
@@ -131,7 +129,7 @@ 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
@@ -180,40 +178,304 @@ 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} @{
@@ -226,7 +488,7 @@ 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:
@@ -249,7 +511,7 @@ the default.
@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.
@@ -257,7 +519,7 @@ 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}
@@ -265,13 +527,13 @@ 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.
@@ -291,13 +553,13 @@ respawn too fast.
@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:
@@ -312,35 +574,35 @@ No prerequisites. This is the default.
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
@@ -374,12 +636,12 @@ 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
@@ -428,16 +690,16 @@ before assignment.
@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.
@@ -445,7 +707,7 @@ 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.
@@ -453,7 +715,7 @@ 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
@@ -461,11 +723,13 @@ 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
@@ -508,7 +772,7 @@ 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:
@@ -531,7 +795,7 @@ 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,
@@ -539,7 +803,7 @@ 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.:
@@ -547,13 +811,11 @@ latter is a comma-separated list of email addresses, e.g.:
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
@@ -567,7 +829,6 @@ The following macro-variables are expanded within @var{string}:
@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
@@ -592,13 +853,13 @@ 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.
@@ -618,9 +879,8 @@ 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:
@@ -630,7 +890,7 @@ stderr syslog err;
@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}
@@ -638,14 +898,14 @@ 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
@@ -696,7 +956,7 @@ 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
@@ -704,7 +964,7 @@ 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
@@ -715,7 +975,7 @@ 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.
@@ -814,13 +1074,147 @@ component @var{tag} @{
@}
@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.
@@ -851,7 +1245,7 @@ Here, @var{compname} stands for the name of the component, and
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
@@ -870,26 +1264,45 @@ component smtps @{
@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
@@ -899,7 +1312,7 @@ Default is 5 seconds.
@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
@@ -911,18 +1324,18 @@ useless. Do not use them, unless you have a good knowledge of
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
@@ -932,55 +1345,62 @@ however, you found such an implementation for it, that requires another
privileges, you may change them using the following three statements:
@command{pies} process.
-@deffn {Pies Conf} user @var{user-name}
+@deffn {Config} user @var{user-name}
Start @command{pies} with the UID and GID of this user.
@end deffn
-@deffn {Pies Conf} group @var{group-list}
+@deffn {Config} group @var{group-list}
Retain supplementary groups, specified in @var{group-list}.
@end deffn
-@deffn {Pies Conf} allgroups @var{bool}
+@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 two configuration statements. First of all, the standard
-@code{debug} block statement controls debugging of the underlying GNU
-Mailutils libraries (@pxref{Debug Statement, Mailutils Configuration
-File,, mailutils, GNU Mailutils Manual}). Secondly, the @code{debug}
-statement controls debugging output of the @command{pies} utility
-itself.
-
-@deffn {Pies Conf} debug @var{spec}
-Set debugging level for the @command{pies} code. @xref{Debug
-Statement, Mailutils Configuration File,, mailutils, GNU Mailutils
-Manual}, for a description of @var{spec} syntax. The following
-debugging levels are used:
+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 trace1
+@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 trace2
+@item 2
Log setting particular limits. Log the recomputed alarms.
-@item trace4
+@item 4
Dump execution environments
-@item trace6
+@item 6
Debug the parser of MeTA1 configuration grammar.
-@item trace7
+@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}
@@ -1135,6 +1555,7 @@ component pmult [disabled; scheduled for Mon 01 Dec 2008 20:27:02]
(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.:
@@ -1142,6 +1563,7 @@ component pmult [disabled; scheduled for Mon 01 Dec 2008 20:27:02]
$ 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:
@@ -1149,9 +1571,9 @@ $ pies -R pmult smtps
$ pies --stop
@end smallexample
-@cindex dependencies, pies
+@cindex dependencies
@anchor{dump-depmap}
-@cindex --dump-depmap option, pies
+@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
@@ -1184,7 +1606,7 @@ 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}
-@cindex --dump-prereq option, pies
+@xopindex{dump-prereq, described}
You can also list prerequisites explicitly:
@smallexample
@@ -1200,52 +1622,109 @@ smtps: smar qmgr
This section summarizes @command{pies} command line options.
@table @option
+@opsummary{config-help}
+@item --config-help
+Show configuration file summary. @xref{Pies Configuration File}.
+
+@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}.
+
+@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.
+@opsummary{source-info}
+@item --source-info
+Show source info with debugging messages. @xref{source-info}.
+
+@opsummary{lint}
+@item --lint
+@itemx -t
+
+@opsummary{stderr}
@item --stderr
Log to standard error.
+@opsummary{syslog}
@item --syslog
Log to syslog. This is the default.
+@opsummary{debug}
@item -x @var{level}
@itemx --debug=@var{level}
Set debug verbosity level. @xref{Pies Debugging}, for a description
of @var{level}.
+@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}.
+@opsummary{status}
@item -s
@itemx --status
Display info about the running instance. @xref{pies-status}.
+@opsummary{stop}
@item -S
@itemx --stop
Stop the running instance.
+@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 --help
+Display a short usage summary and exit.
+
+@item --usage
+Display a short summary of available options and exit.
+
+@item --version
+Display program version and license information and exit.
+
@end table
-Apart from these, the common GNU Mailutils options are understood, which
-are useful for checking @command{pies} configuration file for syntax
-errors. @xref{Common Options, Common Options, , mailutils, GNU
-Mailutils Manual}, for a detailed description of these.
+@node Reporting Bugs
+@chapter How to Report a Bug
+
+ Send bug-reports and suggestions to @email{bug-mailfromd@@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 Copying This Manual
@appendix GNU Free Documentation License

Return to:

Send suggestions and report system problems to the System administrator.