diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 53 | ||||
| -rw-r--r-- | doc/pies.texi | 715 |
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-pragmas: - @check-docs.sh pragmas \ - '/} option_cache\[\] = {/,/^}/s/[ \t]*{ *"\(.*\)".*/\1/pg' \ - 's/@deffnx* {pragma option} *\([^@, ]*\) .*/\1/p' \ - $(top_srcdir)/mfd/main.c -- \ - $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ - $(info_TEXINFOS) - check-options: @@ -51,3 +43,3 @@ check-options: 's/@opindex *\([^@,]*\).*/\1/p' \ - $(top_srcdir)/mfd/main.c -- \ + $(top_srcdir)/src/pies.c -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ @@ -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 -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ @@ -64,8 +56,8 @@ check-config: check-sub-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 -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ @@ -74,26 +66,2 @@ check-sub-config: -check-builtins: - @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 -- \ - $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ - $(info_TEXINFOS) - -check-mflib: - @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 -- \ - $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ - $(info_TEXINFOS) - -check-exceptions: - @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 -- \ - $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ - $(info_TEXINFOS) - check-refs: @@ -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 +@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}. + @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 @@ -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 @smallexample @@ -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} statement. @@ -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: @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: @@ -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 +@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 @@ -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} +@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 @@ -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 -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 @@ -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. +@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 @@ -1137,2 +1557,3 @@ component pmult [disabled; scheduled for Mon 01 Dec 2008 20:27:02] @anchor{pies-restart} +@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 @anchor{dump-depmap} -@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}. @anchor{dump-prereq} -@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 +@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 @@ -1205,2 +1643,3 @@ Force startup even if another instance may be running. +@opsummary{foreground} @item --foreground @@ -1208,2 +1647,11 @@ 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 @@ -1211,2 +1659,3 @@ Log to standard error. +@opsummary{syslog} @item --syslog @@ -1214,2 +1663,3 @@ Log to syslog. This is the default. +@opsummary{debug} @item -x @var{level} @@ -1219,2 +1669,4 @@ of @var{level}. +@opsummary{reload} +@opsummary{hup} @item -r @@ -1224,2 +1676,3 @@ Reload the running instance of pies. +@opsummary{restart-component} @item -R @@ -1228,2 +1681,3 @@ Restart components named in the command line. @xref{pies-restart}. +@opsummary{status} @item -s @@ -1232,2 +1686,3 @@ Display info about the running instance. @xref{pies-status}. +@opsummary{stop} @item -S @@ -123 |