path: root/doc
diff options
authorSergey Poznyakoff <gray@gnu.org.ua>2009-10-12 23:41:21 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2009-10-12 23:42:04 +0300
commit8a4ba77068e5d7f6eab2cc1c1c10f31dcbccf7a6 (patch)
treec70f38d943c778684bb9dbfc7db018e7efb21bf1 /doc
parentaf04ed630f18e9003756317cc627a11084d0d59a (diff)
Fix make distcheck and check-docs.
* doc/Makefile.am: Fix `check-*' goals. * doc/pies.texi: Update and rearrange material. Document new configuration. * lib/Makefile.am (libpies_a_SOURCES): Remove nls.c * src/Makefile.am (EXTRA_DIST): Remove pies.rc, add pp-setup. (INCLUDES): Add $(top_builddir)/gnu * src/pies.c: Minor changes. * src/progman.c: Minor changes. * README-hacking: New file.
Diffstat (limited to 'doc')
2 files changed, 607 insertions, 161 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 502c46e..d7d69d1 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -39,10 +39,2 @@ check-format:
- @check-docs.sh pragmas \
- '/} option_cache\[\] = {/,/^}/s/[ \t]*{ *"\(.*\)".*/\1/pg' \
- 's/@deffnx* {pragma option} *\([^@, ]*\) .*/\1/p' \
- $(top_srcdir)/mfd/main.c -- \
- $(info_TEXINFOS)
@@ -51,3 +43,3 @@ check-options:
's/@opindex *\([^@,]*\).*/\1/p' \
- $(top_srcdir)/mfd/main.c -- \
+ $(top_srcdir)/src/pies.c -- \
@@ -57,5 +49,5 @@ check-config:
@check-docs.sh 'configuration statements' \
- '/mf_cfg_param\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
- 's/@deffn {Pies Conf} *\([^@,]*\).*/\1/p' \
- $(top_srcdir)/mfd/main.c -- \
+ '/pies_keywords\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
+ 's/@deffn {Config} *\([^@,]*\).*/\1/p' \
+ $(top_srcdir)/src/pies.c -- \
@@ -64,8 +56,8 @@ check-config:
- @list=`sed -n '/mf_cfg_param\[\] *= *{/,/^}/{s/[ \t]*{ *"\([^,"]*\)", *mu_cfg_section *,.*/\1/pg}' $(top_srcdir)/mfd/main.c`; \
- for ident in $$list; do \
+ sed -n '/pies_keywords\[\] *= *{/,/^}/{p}' ../src/pies.c|tr '\n{' ' \n'|sed -n '/grecs_type_section/s/"\([^"]*\)".*grecs_type_section,[^,]*,[^,]*,[^,]*,[^,]*, *\(.*\) *}.*/\1 \2/p' | \
+ while read ident kw; do \
check-docs.sh "$$ident configuration statements" \
- "/$${ident}_section_param"'\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
- "s/@deffn {$${ident}}"' *\([^@,]*\).*/\1/p' \
- $(top_srcdir)/mfd/main.c -- \
+ "/$$kw"'\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
+ "s/@deffn {Config: *$${ident}}"' *\([^@,]*\).*/\1/p' \
+ $(top_srcdir)/src/pies.c $(top_srcdir)/src/acl.c -- \
@@ -74,26 +66,2 @@ check-sub-config:
- @check-docs.sh builtins \
- '/MF_DEFUN/{s/[ \t]*MF_DEFUN *(\([a-zA-Z_][a-zA-Z0-9_]*\),.*/\1/p;s/[ \t]*MF_DEFUN_VARARGS\(_NO_PROM\)\? *(\([a-zA-Z_][a-zA-Z0-9_]*\),.*/\2/p;s/[ \t]*MF_DEFUN_CTYPE *(\([a-zA-Z_][a-zA-Z0-9_]*\))/\1/p}'\
- 's/@deftypefnx\{0,1\} {Built-in Function} *[^ ][^ ]* *\([^ ]*\).*/\1/p' \
- $(top_srcdir)/mfd/bi_*.m4 -- \
- $(info_TEXINFOS)
- @check-docs.sh "library functions" \
- '/^[ \t]*func[ \t][ \t]*__/b;/^[ \t]*func/s/[ \t]*func[ \t][ \t]*\(.[^ \t(]*\).*/\1/p' \
- 's/@deftypefn {Library Function} *[^ ][^ ]* *\([^ ]*\).*/\1/p' \
- $(top_srcdir)/mflib/*.mf -- \
- $(info_TEXINFOS)
- @check-docs.sh exceptions \
- '/typedef enum mf_exception_code {/,/^};/s/[ \t]*mfe_\(.*\),.*/e_\1/p;/typedef enum mf_status_code {/,/^};/s/[ \t]*mf_\(.*\),.*/\1/p' \
- 's/@cindex \([^,][^,]*\), exception type/\1/p' \
- $(top_srcdir)/mfd/pies.h -- \
- $(info_TEXINFOS)
@@ -149,5 +117,4 @@ check-unrevised:
-all-check-docs: check-format check-options check-pragmas \
+all-check-docs: check-format check-options \
check-config check-sub-config \
- check-builtins check-mflib check-exceptions \
check-refs check-fixmes check-writeme check-unrevised
diff --git a/doc/pies.texi b/doc/pies.texi
index cc35b5d..22c0f83 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -80,5 +80,2 @@ documents @command{pies} Version @value{VERSION}.
* Pies Configuration File::
-* Component Statement::
-* include-meta1::
-* Global Configuration::
* Pies Debugging::
@@ -87,2 +84,3 @@ documents @command{pies} Version @value{VERSION}.
* Pies Invocation::
+* Reporting Bugs::
@@ -93,4 +91,4 @@ Appendices
-@c @detailmenu
-@c @end detailmenu
+@end detailmenu
@@ -100,3 +98,3 @@ Appendices
@chapter Introduction
-@cindex component, pies
+@cindex component
The name @command{pies} (pronounced @samp{p-yes}) stands for
@@ -112,5 +110,5 @@ of the component.
-@cindex prerequisite, pies
-@cindex dependency, pies
-@cindex dependents, pies
+@cindex prerequisite
+@cindex dependency
+@cindex dependents
@anchor{component prerequisite}
@@ -133,3 +131,3 @@ redirected to a file or to an arbitrary @command{syslog} channel.
@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
@@ -182,36 +180,300 @@ 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}.
+* 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.
+* 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:
+# 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:
+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{/},
+@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.:
+"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:
+"a long string may be"
+" split over several lines"
+@end group
+@end smallexample
+@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:
+A multiline
+@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:
+<<- TEXT
+ All leading whitespace will be
+ ignored when reading these lines.
+@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:
+help-text <<-EOT
+ A sample help text.
+@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:
+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:
+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
+@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
+@end ifnothtml
+@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
@node Component Statement
-@chapter Component Statement
+@section Component Statement
@kwindex component
+@deffn {Config} component
The @code{component} statement defines a new component:
+@end deffn
@@ -228,3 +490,3 @@ 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
@@ -251,3 +513,3 @@ the default.
-@deffn {Pies Conf} program @var{name}
+@deffn {Config: component} program @var{name}
Full file name of the component binary. This binary will be executed
@@ -259,3 +521,3 @@ To supply command line arguments, use @code{command} statement.
-@deffn {Pies Conf} command @var{string}
+@deffn {Config: component} command @var{string}
Command line for the program. The argument should be just as
@@ -267,3 +529,3 @@ statement. Its value will be available to the program as
-@deffn {Pies Conf} disable @var{bool}
+@deffn {Config: component} disable @var{bool}
If @var{bool} is @samp{true}, this component is disabled,
@@ -272,4 +534,4 @@ i.e. @command{pies} will ignore it.
-@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.
@@ -293,3 +555,3 @@ respawn too fast.
@node Prerequisites
-@section Component Prerequisites
+@subsection Component Prerequisites
@cindex declaring prerequisites
@@ -299,3 +561,3 @@ 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
@@ -314,3 +576,3 @@ No prerequisites. This is the default.
-@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
@@ -320,4 +582,4 @@ component tags.
@node Component Privileges
-@section Component Privileges
-@cindex privileges, pies
+@subsection Component Privileges
+@cindex privileges
Following statements control the privileges the component
@@ -325,3 +587,3 @@ 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.
@@ -329,3 +591,3 @@ Start component with the UID and GID of this user.
-@deffn {Pies Conf} group @var{group-list}
+@deffn {Config: component} group @var{group-list}
Retain supplementary groups, specified in @var{group-list}.
@@ -333,3 +595,3 @@ Retain supplementary groups, specified in @var{group-list}.
-@deffn {Pies Conf} allgroups @var{bool}
+@deffn {Config: component} allgroups @var{bool}
Retain all supplementary groups of which the user (as given with
@@ -340,5 +602,5 @@ components specified in @file{meta1.conf} file (@pxref{include-meta1}).
@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
@@ -376,3 +638,3 @@ in version @value{VERSION}.
-@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
@@ -381,3 +643,3 @@ than @samp{777}. The default umask is inherited at startup.
-@deffn {Pies Conf} env @var{args}
+@deffn {Config: component} env @var{args}
Set program environment.
@@ -430,3 +692,3 @@ before assignment.
@node Actions Before Startup
-@section Actions Before Startup
+@subsection Actions Before Startup
@@ -435,3 +697,3 @@ immediately before starting the component:
-@deffn {Pies Conf} chdir @var{dir}
+@deffn {Config: component} chdir @var{dir}
Change to the directory @var{dir}.
@@ -439,3 +701,3 @@ Change to the directory @var{dir}.
-@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
@@ -447,3 +709,3 @@ As of version @value{VERSION} only one @command{remove-file} may be given.
-@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
@@ -455,3 +717,3 @@ This may change in future versions.
@node Exit Actions
-@section Exit Actions
+@subsection Exit Actions
@kwindex return-code
@@ -463,2 +725,3 @@ to the log file. This behavior can be modified using
+@deffn {Config} return-code
@@ -468,2 +731,3 @@ return-code @var{codes} @{
@end smallexample
+@end deffn
@@ -510,3 +774,3 @@ 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
@@ -533,3 +797,3 @@ Program exit code.
-@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
@@ -541,3 +805,3 @@ by the administrator.
-@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
@@ -549,5 +813,3 @@ notify "root@@localhost,postmaster@@localhost";
-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}
@@ -555,3 +817,3 @@ statement.
-@deffn {Pies Conf} message @var{string}
+@deffn {Config: return-code} message @var{string}
Supply notification message text to use by @code{notify} statement.
@@ -569,3 +831,2 @@ The following macro-variables are expanded within @var{string}:
@item version @tab Package version (@value{VERSION}).
-@item mu-version @tab Version of GNU Mailutils.
@item component @tab Name of the terminated component.
@@ -594,3 +855,3 @@ all components. Any @code{return-code} statements appearing within a
@node Output Redirectors
-@section Output Redirectors
+@subsection Output Redirectors
@cindex repeater
@@ -599,4 +860,4 @@ 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
@@ -620,5 +881,4 @@ Redirect to the syslog channel. The syslog priority is given by the
@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.
@@ -632,3 +892,3 @@ stderr syslog err;
-@deffn {Pies Conf} facility @var{syslog-facility}
+@deffn {Config: component} facility @var{syslog-facility}
Specify the syslog facility to use in syslog redirectors. Allowed
@@ -640,3 +900,3 @@ through @samp{local7} (all names case-insensitive), or a facility number.
@node Inetd-Style Components
-@section Inetd-Style Components
+@subsection Inetd-Style Components
@cindex inetd-style components
@@ -647,3 +907,3 @@ such components:
-@deffn {Pies Conf} socket @var{url}
+@deffn {Config: component} socket @var{url}
Define a socket to listen on. Allowed values for @var{url} are:
@@ -698,3 +958,3 @@ be added if there is a demand.
@node Meta1-Style Components
-@section Meta1-Style Components
+@subsection Meta1-Style Components
@cindex meta1-style components
@@ -706,3 +966,3 @@ 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.
@@ -717,3 +977,3 @@ upon its startup.
@node Component Syntax Summary
-@section Component Syntax Summary
+@subsection Component Syntax Summary
This subsection summarizes the @code{component} summary. For each
@@ -816,4 +1076,138 @@ component @var{tag} @{
+@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
+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
+@end table
+The @var{sub-acl} part, if present, allows to branch to another
+@acronym{ACL}. The syntax of this group is:
+acl @var{name}
+@end smallexample
+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{}.
+@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:
+allow|deny [all|authenticated|group @var{group-list}]
+ [acl @var{name}] [from @var{addr-list}]
+@end smallexample
+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{}. 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{} are allowed if they
+authenticate themselves and are members of groups @samp{pies} or
+@samp{users}. Access is denied for anybody else:
+acl common @{
+ allow all from ("/tmp/pies.sock", "");
+ allow authenticated acl "my-nets";
+ allow group ("pies", "users") from "";
+ deny all;
+@end group
+@end smallexample
@node include-meta1
-@chapter Using MeTA1 Configuration File
+@section Using MeTA1 Configuration File
@cindex /etc/meta1/meta1.conf
@@ -822,3 +1216,3 @@ configuration file:
-@deffn {Pies Conf} include-meta1 @var{file}
+@deffn {Config} include-meta1 @var{file}
Parse @var{file} as MeTA1 configuration file and incorporate
@@ -853,3 +1247,3 @@ the following statement
-@deffn {Pies Conf} meta1-queue-dir @var{dir}
+@deffn {Config} meta1-queue-dir @var{dir}
Set name of MeTA1 queue directory.
@@ -872,3 +1266,4 @@ component smtps @{
@node Global Configuration
-@chapter Global Configuration
+@section Global Configuration
+@cindex Global Configuration
The statements described in this section affect @command{pies}
@@ -876,3 +1271,21 @@ behavior as a whole.
-@deffn {Pies Conf} umask @var{number}
+@deffn {Config} syslog @{ ... @}
+This block statement configures logging via syslog. It has two
+@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
+@end deffn
+@end deffn
+@deffn {Config} umask @var{number}
Set the default umask. The @var{number} must be an octal value not greater
@@ -881,3 +1294,3 @@ than @samp{777}. The default umask is inherited at startup.
-@deffn {Pies Conf} limits @var{arg}
+@deffn {Config} limits @var{arg}
Set global system limits for all pies components. @xref{Resources,
@@ -886,3 +1299,3 @@ limits}, for a detailed description of @var{arg}.
-@deffn {Pies Conf} return-code @{ ... @}
+@deffn {Config} return-code @{ ... @}
Configure global exit actions. @xref{Exit Actions}, for a detailed
@@ -891,3 +1304,3 @@ description of this statement.
-@deffn {Pies Conf} shutdown-timeout @var{number};
+@deffn {Config} shutdown-timeout @var{number};
Wait @var{number} of seconds for all components to shut down.
@@ -901,3 +1314,3 @@ Default is 5 seconds.
@node Less Useful Statements
-@section Less Useful Statements
+@subsection Less Useful Statements
@@ -913,3 +1326,3 @@ 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
@@ -919,3 +1332,3 @@ default, master PID is stored in @file{@var{statedir}/pies.pid}
-@deffn {Pies Conf} control-file @var{file}
+@deffn {Config} control-file @var{file}
Set file name of the @command{pies} control file. Default is
@@ -924,3 +1337,3 @@ Set file name of the @command{pies} control file. Default is
-@deffn {Pies Conf} stat-file @var{file}
+@deffn {Config} stat-file @var{file}
Set file name of the statistics output file. Default is
@@ -934,3 +1347,3 @@ 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.
@@ -938,3 +1351,3 @@ Start @command{pies} with the UID and GID of this user.
-@deffn {Pies Conf} group @var{group-list}
+@deffn {Config} group @var{group-list}
Retain supplementary groups, specified in @var{group-list}.
@@ -942,3 +1355,3 @@ Retain supplementary groups, specified in @var{group-list}.
-@deffn {Pies Conf} allgroups @var{bool}
+@deffn {Config} allgroups @var{bool}
Retain all supplementary groups of which user, given with
@@ -949,18 +1362,13 @@ Retain all supplementary groups of which user, given with
@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
-@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
@@ -969,12 +1377,12 @@ 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.
@@ -983,2 +1391,14 @@ Debug the lexical analyzer of MeTA1 configuration file.
+@deffn {Config} source-info @var{bool}
+This statement decides whether debugging messages should contain
+source information. To enable source information, use:
+source-info yes;
+@end smallexample
+This feature is designed for @command{pies} developers.
+@end deffn
@node Configuration Example
@@ -1137,2 +1557,3 @@ component pmult [disabled; scheduled for Mon 01 Dec 2008 20:27:02]
+@xopindex{restart-component, described}
You can restart any component by using the
@@ -1144,2 +1565,3 @@ $ pies -R pmult smtps
+@xopindex{stop, described}
To stop all running components and shut down @command{pies}, use the
@@ -1151,5 +1573,5 @@ $ pies --stop
-@cindex dependencies, pies
+@cindex dependencies
-@cindex --dump-depmap option, pies
+@xopindex{dump-depmap option, introduced}
Two options are provided for verifying inter-component
@@ -1186,3 +1608,3 @@ means that @samp{smtps} depends on @samp{smar} and @samp{qmgr}.
-@cindex --dump-prereq option, pies
+@xopindex{dump-prereq, described}
You can also list prerequisites explicitly:
@@ -1202,2 +1624,18 @@ This section summarizes @command{pies} command line options.
@table @option
+@item --config-help
+Show configuration file summary. @xref{Pies Configuration File}.
+@item --config-file=@var{file}
+@item -c @var{file}
+Read configuration from @var{file}, instead of the default
+@xref{Pies Configuration File}.
+@item -E
+Preprocess configuration file and exit. @xref{Preprocessor}.
@item --force
@@ -1205,2 +1643,3 @@ Force startup even if another instance may be running.
@item --foreground
@@ -1208,2 +1647,11 @@ Remain in foreground.
+@item --source-info
+Show source info with debugging messages. @xref{source-info}.
+@item --lint
+@itemx -t
@item --stderr
@@ -1211,2 +1659,3 @@ Log to standard error.
@item --syslog
@@ -1214,2 +1663,3 @@ Log to syslog. This is the default.
@item -x @var{level}
@@ -1219,2 +1669,4 @@ of @var{level}.
@item -r
@@ -1224,2 +1676,3 @@ Reload the running instance of pies.
@item -R
@@ -1228,2 +1681,3 @@ Restart components named in the command line. @xref{pies-restart}.
@item -s
@@ -1232,2 +1686,3 @@ Display info about the running instance. @xref{pies-status}.
@item -S
@@ -1236,2 +1691,3 @@ Stop the running instance.
@item --dump-depmap
@@ -1239,2 +1695,3 @@ Dump dependency map. @xref{dump-depmap}.
@item --dump-prereq
@@ -1242,8 +1699,30 @@ 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:
+@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

Return to:

Send suggestions and report system problems to the System administrator.