aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
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)
downloadpies-8a4ba77068e5d7f6eab2cc1c1c10f31dcbccf7a6.tar.gz
pies-8a4ba77068e5d7f6eab2cc1c1c10f31dcbccf7a6.tar.bz2
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')
-rw-r--r--doc/Makefile.am53
-rw-r--r--doc/pies.texi715
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
@@ -37,65 +37,33 @@ check-format:
37 false; \ 37 false; \
38 fi 38 fi
39 39
40check-pragmas:
41 @check-docs.sh pragmas \
42 '/} option_cache\[\] = {/,/^}/s/[ \t]*{ *"\(.*\)".*/\1/pg' \
43 's/@deffnx* {pragma option} *\([^@, ]*\) .*/\1/p' \
44 $(top_srcdir)/mfd/main.c -- \
45 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
46 $(info_TEXINFOS)
47
48check-options: 40check-options:
49 @check-docs.sh options \ 41 @check-docs.sh options \
50 '/argp_option options\[\] = /,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ 42 '/argp_option options\[\] = /,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
51 's/@opindex *\([^@,]*\).*/\1/p' \ 43 's/@opindex *\([^@,]*\).*/\1/p' \
52 $(top_srcdir)/mfd/main.c -- \ 44 $(top_srcdir)/src/pies.c -- \
53 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ 45 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
54 $(info_TEXINFOS) 46 $(info_TEXINFOS)
55 47
56check-config: 48check-config:
57 @check-docs.sh 'configuration statements' \ 49 @check-docs.sh 'configuration statements' \
58 '/mf_cfg_param\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ 50 '/pies_keywords\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
59 's/@deffn {Pies Conf} *\([^@,]*\).*/\1/p' \ 51 's/@deffn {Config} *\([^@,]*\).*/\1/p' \
60 $(top_srcdir)/mfd/main.c -- \ 52 $(top_srcdir)/src/pies.c -- \
61 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ 53 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
62 $(info_TEXINFOS) 54 $(info_TEXINFOS)
63 55
64check-sub-config: 56check-sub-config:
65 @list=`sed -n '/mf_cfg_param\[\] *= *{/,/^}/{s/[ \t]*{ *"\([^,"]*\)", *mu_cfg_section *,.*/\1/pg}' $(top_srcdir)/mfd/main.c`; \ 57 sed -n '/pies_keywords\[\] *= *{/,/^}/{p}' ../src/pies.c|tr '\n{' ' \n'|sed -n '/grecs_type_section/s/"\([^"]*\)".*grecs_type_section,[^,]*,[^,]*,[^,]*,[^,]*, *\(.*\) *}.*/\1 \2/p' | \
66 for ident in $$list; do \ 58 while read ident kw; do \
67 check-docs.sh "$$ident configuration statements" \ 59 check-docs.sh "$$ident configuration statements" \
68 "/$${ident}_section_param"'\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ 60 "/$$kw"'\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
69 "s/@deffn {$${ident}}"' *\([^@,]*\).*/\1/p' \ 61 "s/@deffn {Config: *$${ident}}"' *\([^@,]*\).*/\1/p' \
70 $(top_srcdir)/mfd/main.c -- \ 62 $(top_srcdir)/src/pies.c $(top_srcdir)/src/acl.c -- \
71 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ 63 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
72 $(info_TEXINFOS); \ 64 $(info_TEXINFOS); \
73 done 65 done
74 66
75check-builtins:
76 @check-docs.sh builtins \
77 '/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}'\
78 's/@deftypefnx\{0,1\} {Built-in Function} *[^ ][^ ]* *\([^ ]*\).*/\1/p' \
79 $(top_srcdir)/mfd/bi_*.m4 -- \
80 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
81 $(info_TEXINFOS)
82
83check-mflib:
84 @check-docs.sh "library functions" \
85 '/^[ \t]*func[ \t][ \t]*__/b;/^[ \t]*func/s/[ \t]*func[ \t][ \t]*\(.[^ \t(]*\).*/\1/p' \
86 's/@deftypefn {Library Function} *[^ ][^ ]* *\([^ ]*\).*/\1/p' \
87 $(top_srcdir)/mflib/*.mf -- \
88 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
89 $(info_TEXINFOS)
90
91check-exceptions:
92 @check-docs.sh exceptions \
93 '/typedef enum mf_exception_code {/,/^};/s/[ \t]*mfe_\(.*\),.*/e_\1/p;/typedef enum mf_status_code {/,/^};/s/[ \t]*mf_\(.*\),.*/\1/p' \
94 's/@cindex \([^,][^,]*\), exception type/\1/p' \
95 $(top_srcdir)/mfd/pies.h -- \
96 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
97 $(info_TEXINFOS)
98
99check-refs: 67check-refs:
100 @for file in $(info_TEXINFOS) $(pies_TEXINFOS); \ 68 @for file in $(info_TEXINFOS) $(pies_TEXINFOS); \
101 do \ 69 do \
@@ -147,9 +115,8 @@ check-unrevised:
147 rm $@-t; \ 115 rm $@-t; \
148 fi 116 fi
149 117
150all-check-docs: check-format check-options check-pragmas \ 118all-check-docs: check-format check-options \
151 check-config check-sub-config \ 119 check-config check-sub-config \
152 check-builtins check-mflib check-exceptions \
153 check-refs check-fixmes check-writeme check-unrevised 120 check-refs check-fixmes check-writeme check-unrevised
154 121
155check-docs: 122check-docs:
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}.
78@menu 78@menu
79* Intro:: 79* Intro::
80* Pies Configuration File:: 80* Pies Configuration File::
81* Component Statement::
82* include-meta1::
83* Global Configuration::
84* Pies Debugging:: 81* Pies Debugging::
85* Configuration Example:: 82* Configuration Example::
86* Command Line Usage:: 83* Command Line Usage::
87* Pies Invocation:: 84* Pies Invocation::
85* Reporting Bugs::
88 86
89Appendices 87Appendices
90 88
91* Copying This Manual:: The GNU Free Documentation License. 89* Copying This Manual:: The GNU Free Documentation License.
92* Concept Index:: Index of Concepts. 90* Concept Index:: Index of Concepts.
93 91
94@c @detailmenu 92@detailmenu
95@c @end detailmenu 93@end detailmenu
96 94
97@end menu 95@end menu
98 96
99@node Intro 97@node Intro
100@chapter Introduction 98@chapter Introduction
101@cindex component, pies 99@cindex component
102 The name @command{pies} (pronounced @samp{p-yes}) stands for 100 The name @command{pies} (pronounced @samp{p-yes}) stands for
103@samp{Program Invocation and Execution Supervisor}. This utility 101@samp{Program Invocation and Execution Supervisor}. This utility
104starts and controls execution of external programs, called 102starts and controls execution of external programs, called
@@ -110,9 +108,9 @@ terminates, @command{pies} restarts it. Its configuration allows to
110specify actions other than simple restart, depending on the exit code 108specify actions other than simple restart, depending on the exit code
111of the component. 109of the component.
112 110
113@cindex prerequisite, pies 111@cindex prerequisite
114@cindex dependency, pies 112@cindex dependency
115@cindex dependents, pies 113@cindex dependents
116@anchor{component prerequisite} 114@anchor{component prerequisite}
117 A component @samp{A} may depend on another components, say 115 A component @samp{A} may depend on another components, say
118@samp{B} and @samp{C}, i.e. require them to be running at the moment of its 116@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.
131 129
132@anchor{init-style} 130@anchor{init-style}
133@cindex init-style components 131@cindex init-style components
134 These way of operation applies to so-called @dfn{init-style} 132 This way of operation applies to the @dfn{init-style}
135components, called so because of the similarity with the 133components, called so because of the similarity with the
136@command{init} process manager. @command{Pies} is also able to handle 134@command{init} process manager. @command{Pies} is also able to handle
137components that receive input on their @samp{stdin} and send reply to 135components that receive input on their @samp{stdin} and send reply to
@@ -180,40 +178,304 @@ stopping component dependencies, the same ordering is preserved.
180 This order is reversed for files included by @code{include-meta1} 178 This order is reversed for files included by @code{include-meta1}
181statement (@pxref{include-meta1}). 179statement (@pxref{include-meta1}).
182 180
181@node Pies Configuration File
182@chapter Pies Configuration File
183@cindex configuration file
184@flindex pies.conf
185@xopindex{config-file, introduced}
186 @command{Pies} reads its settings and component definitions from the
187@dfn{configuration file} @file{pies.conf}, located in the @dfn{system
188configuration directory} (in most cases @file{/etc} or
189@file{/usr/local/etc}, depending on how the package was compiled).
190An alternative location may be specified using @option{--config-file}
191(@option{-c} command line option.
192
193 If any errors are encountered in the configuration file, the program
194reports them on the standard error and exits with a non-zero status.
195
196@xopindex{lint, introduced}
197 To test the configuration file without actually starting the server, the
198@option{--lint} (@option{-t}) command line option is provided. It causes
199@command{pies} to check its configuration file and exit with status 0
200if no errors were detected, and with status 1 otherwise.
201
202@opindex -E, introduced
203 Before parsing, configuration file is preprocessed using
204@command{m4} (@pxref{Preprocessor}). To see the preprocessed
205configuration without actually parsing it, use @option{-E} command
206line option.
207
208@xopindex{config-help, introduced}
209 The rest of this section describes the configuration file syntax in
210detail. You can receive a concise summary of all configuration
211directives any time by running @command{pies --config-help}.
212
183@menu 213@menu
214* Syntax:: Configuration file syntax.
215* Component Statement::
216* ACL:: Access Control Lists
217* include-meta1::
218* Global Configuration::
184@end menu 219@end menu
185 220
186@node Pies Configuration File 221@node Syntax
187@chapter Pies Configuration File 222@section Configuration File Syntax
188 @command{Pies} reads its configuration from the main Mailutils 223 The configuration file consists of statements and comments.
189configuration file. @xref{configuration, Mailutils Configuration 224
190File,, mailutils, GNU Mailutils Manual}, for a description of GNU 225 There are three classes of lexical tokens: keywords, values, and
191Mailutils configuration system. It is recommended to use 226separators. Blanks, tabs, newlines and comments, collectively called
192@code{include @var{directory}} statement (@pxref{Include, Include 227@dfn{white space} are ignored except as they serve to separate
193Statement,, mailutils, GNU Mailutils Manual}), and to place 228tokens. Some white space is required to separate otherwise adjacent
194@command{pies} configuration in file @file{@var{directory}/pies}. 229keywords and values.
195@xref{MeTA1,,, mailfromd, Mailfromd Manual}, for an example. 230
196 231@menu
197The following standard Mailutils configuration statements are understood: 232* Comments::
198 233* Statements::
199@multitable @columnfractions 0.3 0.6 234* Preprocessor:: Using preprocessor to improve the configuration.
200@headitem Statement @tab Reference 235@end menu
201@item debug @tab @xref{Debug Statement, Mailutils Debug Statement,, 236
202mailutils, GNU Mailutils Manual}. 237@node Comments
203@item logging @tab @xref{Logging Statement, Mailutils Logging,, 238@subsection Comments
204mailutils, GNU Mailutils Manual}. 239@cindex Comments in a configuration file
205@item include @tab @xref{Include, Include Statements,, 240@cindex single-line comments
206mailutils, GNU Mailutils Manual}. 241 @dfn{Comments} may appear anywhere where white space may appear in the
207@item mailer @tab @xref{Mailer, Mailer Statement,, 242configuration file. There are two kinds of comments:
208mailutils, GNU Mailutils Manual}. 243single-line and multi-line comments. @dfn{Single-line} comments start
209@item acl @tab @xref{ACL Statement, ACL Statement,, 244with @samp{#} or @samp{//} and continue to the end of the line:
210mailutils, GNU Mailutils Manual}. 245
246@smallexample
247# This is a comment
248// This too is a comment
249@end smallexample
250
251@cindex multi-line comments
252 @dfn{Multi-line} or @dfn{C-style} comments start with the two
253characters @samp{/*} (slash, star) and continue until the first
254occurrence of @samp{*/} (star, slash).
255
256 Multi-line comments cannot be nested.
257
258@node Statements
259@subsection Statements
260@cindex statements, configuration file
261@cindex configuration file statements
262@cindex statement, simple
263@cindex simple statements
264 A @dfn{simple statement} consists of a keyword and value
265separated by any amount of whitespace. Simple statement is terminated
266with a semicolon (@samp{;}), unless it contains a @dfn{here-document}
267(see below), in which case semicolon is optional.
268
269 Examples of simple statements:
270
271@smallexample
272pidfile /var/run/pies.pid;
273source-info yes;
274debug 10;
275@end smallexample
276
277 A @dfn{keyword} begins with a letter and may contain letters,
278decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
279Examples of keywords are: @samp{group}, @samp{control-file}.
280
281 A @dfn{value} can be one of the following:
282
283@table @asis
284@item number
285 A number is a sequence of decimal digits.
286
287@item boolean
288@cindex boolean value
289 A boolean value is one of the following: @samp{yes}, @samp{true},
290@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no},
291@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}.
292
293@item unquoted string
294@cindex string, unquoted
295 An unquoted string may contain letters, digits, and any of the
296following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/},
297@samp{:}.
298
299@item quoted string
300@cindex quoted string
301@cindex string, quoted
302@cindex escape sequence
303 A quoted string is any sequence of characters enclosed in
304double-quotes (@samp{"}). A backslash appearing within a quoted
305string introduces an @dfn{escape sequence}, which is replaced
306with a single character according to the following rules:
307
308@float Table, backslash-interpretation
309@caption{Backslash escapes}
310@multitable @columnfractions 0.30 .5
311@item Sequence @tab Replaced with
312@item \a @tab Audible bell character (@acronym{ASCII} 7)
313@item \b @tab Backspace character (@acronym{ASCII} 8)
314@item \f @tab Form-feed character (@acronym{ASCII} 12)
315@item \n @tab Newline character (@acronym{ASCII} 10)
316@item \r @tab Carriage return character (@acronym{ASCII} 13)
317@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
318@item \\ @tab A single backslash (@samp{\})
319@item \" @tab A double-quote.
211@end multitable 320@end multitable
321@end float
322
323 In addition, the sequence @samp{\@var{newline}} is removed from
324the string. This allows to split long strings over several
325physical lines, e.g.:
326
327@smallexample
328@group
329"a long string may be\
330 split over several lines"
331@end group
332@end smallexample
333
334 If the character following a backslash is not one of those specified
335above, the backslash is ignored and a warning is issued.
336
337 Two or more adjacent quoted strings are concatenated, which gives
338another way to split long strings over several lines to improve
339readability. The following fragment produces the same result as the
340example above:
341
342@smallexample
343@group
344"a long string may be"
345" split over several lines"
346@end group
347@end smallexample
348
349@anchor{here-document}
350@item Here-document
351@cindex here-document
352 @dfn{Here-document} is a special construct that allows to introduce
353strings of text containing embedded newlines.
354
355 The @code{<<@var{word}} construct instructs the parser to read all
356the following lines up to the line containing only @var{word}, with
357possible trailing blanks. Any lines thus read are concatenated
358together into a single string. For example:
359
360@smallexample
361@group
362<<EOT
363A multiline
364string
365EOT
366@end group
367@end smallexample
368
369 Body of a here-document is interpreted the same way as
370double-quoted string, unless @var{word} is preceded by a backslash
371(e.g. @samp{<<\EOT}) or enclosed in double-quotes, in which case
372the text is read as is, without interpretation of escape sequences.
373
374 If @var{word} is prefixed with @code{-} (a dash), then all leading
375tab characters are stripped from input lines and the line containing
376@var{word}. Furthermore, if @code{-} is followed by a single space,
377all leading whitespace is stripped from them. This allows to indent
378here-documents in a natural fashion. For example:
379
380@smallexample
381@group
382<<- TEXT
383 All leading whitespace will be
384 ignored when reading these lines.
385TEXT
386@end group
387@end smallexample
388
389 It is important that the terminating delimiter be the only token on
390its line. The only exception to this rule is allowed if a
391here-document appears as the last element of a statement. In this
392case a semicolon can be placed on the same line with its terminating
393delimiter, as in:
394
395@smallexample
396help-text <<-EOT
397 A sample help text.
398EOT;
399@end smallexample
400
401@item list
402@cindex list
403 A @dfn{list} is a comma-separated list of values. Lists are
404delimited by parentheses. The following example shows a statement
405whose value is a list of strings:
406
407@smallexample
408dependents (pmult, auth);
409@end smallexample
410
411 In any case where a list is appropriate, a single value is allowed
412without being a member of a list: it is equivalent to a list with a
413single member. This means that, e.g. @samp{dependents auth;} is
414equivalent to @samp{dependents (mime);}.
415
416@end table
417
418@cindex statement, block
419@cindex block statement
420 A @dfn{block statement} introduces a logical group of another
421statements. It consists of a keyword, followed by an optional value,
422and a sequence of statements enclosed in curly braces, as shown in
423the example below:
424
425@smallexample
426@group
427component multiplexor @{
428 command "pmult";
429@}
430@end group
431@end smallexample
432
433 The closing curly brace may be followed by a semicolon, although
434this is not required.
435
436@node Preprocessor
437@subsection Using Preprocessor to Improve the Configuration.
438@cindex preprocessor
439@cindex m4
440 Before parsing configuration file, @command{pies} preprocesses
441it. The built-in preprocessor handles only file inclusion
442and @code{#line} statements (@FIXME-pxref{Pragmatic Comments}), while the
443rest of traditional preprocessing facilities, such as macro expansion,
444is supported via @command{m4}, which is used as an external preprocessor.
445
446 The detailed description of @command{m4} facilities lies far beyond
447the scope of this document. You will find a complete user manual in
448@ifnothtml
449@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
450@end ifnothtml
451@ifhtml
452@uref{http://www.gnu.org/software/m4/manual}.
453@end ifhtml
454For the rest of this subsection we assume the reader is sufficiently
455acquainted with @command{m4} macro processor.
456
457@flindex pp-setup
458 The external preprocessor is invoked with @option{-s} flag, instructing
459it to include line synchronization information in its output. This
460information is then used by the parser to display meaningful
461diagnostic. An initial set of macro definitions is supplied by the
462@file{pp-setup} file, located in
463@file{@var{$prefix}/share/pies/@var{version}/include} directory (where
464@var{version} means the version of the package).
465
466The default @file{pp-setup} file renames all @command{m4} built-in
467macro names so they all start with the prefix @samp{m4_}. This
468is similar to GNU m4 @option{--prefix-builtin} options, but has an
469advantage that it works with non-GNU @command{m4} implementations as
470well.
212 471
213@node Component Statement 472@node Component Statement
214@chapter Component Statement 473@section Component Statement
215@kwindex component 474@kwindex component
475
476@deffn {Config} component
216 The @code{component} statement defines a new component: 477 The @code{component} statement defines a new component:
478@end deffn
217 479
218@smallexample 480@smallexample
219component @var{tag} @{ 481component @var{tag} @{
@@ -226,7 +488,7 @@ argument to the @code{component} keyword.
226 488
227The following statements are allowed within the @code{component} block: 489The following statements are allowed within the @code{component} block:
228 490
229@deffn {Pies Conf} mode @var{mode} 491@deffn {Config: component} mode @var{mode}
230 Declare the type (style) of the component. Accepted values for 492 Declare the type (style) of the component. Accepted values for
231@var{mode} are: 493@var{mode} are:
232 494
@@ -249,7 +511,7 @@ the default.
249@end table 511@end table
250@end deffn 512@end deffn
251 513
252@deffn {Pies Conf} program @var{name} 514@deffn {Config: component} program @var{name}
253Full file name of the component binary. This binary will be executed 515Full file name of the component binary. This binary will be executed
254(via @command{/bin/sh -c}) each time @command{pies} decides it needs 516(via @command{/bin/sh -c}) each time @command{pies} decides it needs
255to start the component. 517to start the component.
@@ -257,7 +519,7 @@ to start the component.
257To supply command line arguments, use @code{command} statement. 519To supply command line arguments, use @code{command} statement.
258@end deffn 520@end deffn
259 521
260@deffn {Pies Conf} command @var{string} 522@deffn {Config: component} command @var{string}
261Command line for the program. The argument should be just as 523Command line for the program. The argument should be just as
262arguments normally are, starting with the name of the program. The 524arguments normally are, starting with the name of the program. The
263latter may be different from the one specified to @code{program} 525latter may be different from the one specified to @code{program}
@@ -265,13 +527,13 @@ statement. Its value will be available to the program as
265@code{argv[0]}. 527@code{argv[0]}.
266@end deffn 528@end deffn
267 529
268@deffn {Pies Conf} disable @var{bool} 530@deffn {Config: component} disable @var{bool}
269If @var{bool} is @samp{true}, this component is disabled, 531If @var{bool} is @samp{true}, this component is disabled,
270i.e. @command{pies} will ignore it. 532i.e. @command{pies} will ignore it.
271@end deffn 533@end deffn
272 534
273@deffn {Pies Conf} precious @var{bool} 535@deffn {Config: component} precious @var{bool}
274@cindex precious components, pies 536@cindex precious components
275If @var{bool} is @samp{true}, this component is marked as precious. 537If @var{bool} is @samp{true}, this component is marked as precious.
276Precious components are never disabled by @command{pies}, even if they 538Precious components are never disabled by @command{pies}, even if they
277respawn too fast. 539respawn too fast.
@@ -291,13 +553,13 @@ respawn too fast.
291@end menu 553@end menu
292 554
293@node Prerequisites 555@node Prerequisites
294@section Component Prerequisites 556@subsection Component Prerequisites
295@cindex declaring prerequisites 557@cindex declaring prerequisites
296@cindex prerequisites, declaring 558@cindex prerequisites, declaring
297Prerequisites (@pxref{component prerequisite}) for a component are 559Prerequisites (@pxref{component prerequisite}) for a component are
298declared using the following statement: 560declared using the following statement:
299 561
300@deffn {Pies Conf} prerequisites @var{tag-list} 562@deffn {Config: component} prerequisites @var{tag-list}
301The argument is either a list of component tags, @emph{defined before 563The argument is either a list of component tags, @emph{defined before
302this component}, or one of the following words: 564this component}, or one of the following words:
303 565
@@ -312,35 +574,35 @@ No prerequisites. This is the default.
312 574
313 If you wish, you can define dependents, instead of prerequisites: 575 If you wish, you can define dependents, instead of prerequisites:
314 576
315@deffn {Pies Conf} dependents @var{tag-list} 577@deffn {Config: component} dependents @var{tag-list}
316Declare dependents for this component. @var{var-list} is a list of 578Declare dependents for this component. @var{var-list} is a list of
317component tags. 579component tags.
318@end deffn 580@end deffn
319 581
320@node Component Privileges 582@node Component Privileges
321@section Component Privileges 583@subsection Component Privileges
322@cindex privileges, pies 584@cindex privileges
323 Following statements control the privileges the component 585 Following statements control the privileges the component
324is executed with. 586is executed with.
325 587
326@deffn {Pies Conf} user @var{user-name} 588@deffn {Config: component} user @var{user-name}
327Start component with the UID and GID of this user. 589Start component with the UID and GID of this user.
328@end deffn 590@end deffn
329 591
330@deffn {Pies Conf} group @var{group-list} 592@deffn {Config: component} group @var{group-list}
331Retain supplementary groups, specified in @var{group-list}. 593Retain supplementary groups, specified in @var{group-list}.
332@end deffn 594@end deffn
333 595
334@deffn {Pies Conf} allgroups @var{bool} 596@deffn {Config: component} allgroups @var{bool}
335Retain all supplementary groups of which the user (as given with 597Retain all supplementary groups of which the user (as given with
336@command{user} statement) is a member. This is the default for 598@command{user} statement) is a member. This is the default for
337components specified in @file{meta1.conf} file (@pxref{include-meta1}). 599components specified in @file{meta1.conf} file (@pxref{include-meta1}).
338@end deffn 600@end deffn
339 601
340@node Resources 602@node Resources
341@section Resources 603@subsection Resources
342 604
343@deffn {Pies Conf} limits @var{string} 605@deffn {Config: component} limits @var{string}
344Impose limits on system resources, as defined by @var{string}. The 606Impose limits on system resources, as defined by @var{string}. The
345argument consists of @dfn{commands}, optionally separated by any 607argument consists of @dfn{commands}, optionally separated by any
346amount of whitespace. A command is a single command letter followed 608amount 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
374in version @value{VERSION}. 636in version @value{VERSION}.
375@end deffn 637@end deffn
376 638
377@deffn {Pies Conf} umask @var{number} 639@deffn {Config: component} umask @var{number}
378Set the umask. The @var{number} must be an octal value not greater 640Set the umask. The @var{number} must be an octal value not greater
379than @samp{777}. The default umask is inherited at startup. 641than @samp{777}. The default umask is inherited at startup.
380@end deffn 642@end deffn
381 643
382@deffn {Pies Conf} env @var{args} 644@deffn {Config: component} env @var{args}
383Set program environment. 645Set program environment.
384 646
385Arguments are a whitespace-delimited list of specifiers. The 647Arguments are a whitespace-delimited list of specifiers. The
@@ -428,16 +690,16 @@ before assignment.
428@end deffn 690@end deffn
429 691
430@node Actions Before Startup 692@node Actions Before Startup
431@section Actions Before Startup 693@subsection Actions Before Startup
432 694
433 Several statements are available that specify actions to perform 695 Several statements are available that specify actions to perform
434immediately before starting the component: 696immediately before starting the component:
435 697
436@deffn {Pies Conf} chdir @var{dir} 698@deffn {Config: component} chdir @var{dir}
437Change to the directory @var{dir}. 699Change to the directory @var{dir}.
438@end deffn 700@end deffn
439 701
440@deffn {Pies Conf} remove-file @var{file-name} 702@deffn {Config: component} remove-file @var{file-name}
441Remove @var{file-name}. This is useful, for example, to remove stale 703Remove @var{file-name}. This is useful, for example, to remove stale
442@acronym{UNIX} sockets or pid-files, which may otherwise prevent the 704@acronym{UNIX} sockets or pid-files, which may otherwise prevent the
443component from starting normally. 705component from starting normally.
@@ -445,7 +707,7 @@ component from starting normally.
445As of version @value{VERSION} only one @command{remove-file} may be given. 707As of version @value{VERSION} only one @command{remove-file} may be given.
446@end deffn 708@end deffn
447 709
448@deffn {Pies Conf} settle-timeout @var{number} 710@deffn {Config: component} settle-timeout @var{number}
449Wait @var{number} seconds. This is kind of kludge. Currently it is 711Wait @var{number} seconds. This is kind of kludge. Currently it is
450used for components imported from @file{meta1.conf} file 712used for components imported from @file{meta1.conf} file
451(@pxref{include-meta1}), where @code{settle-timeout 1} is implied. 713(@pxref{include-meta1}), where @code{settle-timeout 1} is implied.
@@ -453,7 +715,7 @@ This may change in future versions.
453@end deffn 715@end deffn
454 716
455@node Exit Actions 717@node Exit Actions
456@section Exit Actions 718@subsection Exit Actions
457@kwindex return-code 719@kwindex return-code
458 The default behavior of @command{pies} if an @samp{init-style} 720 The default behavior of @command{pies} if an @samp{init-style}
459component terminates is to restart it. Unless the component 721component terminates is to restart it. Unless the component
@@ -461,11 +723,13 @@ terminates with 0 exit code, a corresponding error message is issued
461to the log file. This behavior can be modified using 723to the log file. This behavior can be modified using
462@code{return-code} statement: 724@code{return-code} statement:
463 725
726@deffn {Config} return-code
464@smallexample 727@smallexample
465return-code @var{codes} @{ 728return-code @var{codes} @{
466 @dots{} 729 @dots{}
467@} 730@}
468@end smallexample 731@end smallexample
732@end deffn
469 733
470 The @var{codes} argument is a list of exit codes or signal names. 734 The @var{codes} argument is a list of exit codes or signal names.
471Exit codes can be specified either as decimal numbers or as symbolic code 735Exit 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},
508@command{pies} executes actions specified by its substatements. 772@command{pies} executes actions specified by its substatements.
509They are executed in the order of their appearance below: 773They are executed in the order of their appearance below:
510 774
511@deffn {Pies Conf} exec @var{command} 775@deffn {Config: return-code} exec @var{command}
512Execute external command. Prior to execution of @var{command} all 776Execute external command. Prior to execution of @var{command} all
513file descriptors are closed. It inherits the environment from the 777file descriptors are closed. It inherits the environment from the
514main @command{pies} process with the following additional variables: 778main @command{pies} process with the following additional variables:
@@ -531,7 +795,7 @@ Program exit code.
531@end table 795@end table
532@end deffn 796@end deffn
533 797
534@deffn {Pies Conf} action @samp{disable | restart} 798@deffn {Config: return-code} action @samp{disable | restart}
535If @samp{restart} is given, restart the component. This is the 799If @samp{restart} is given, restart the component. This is the
536default. Otherwise, mark the component as disabled. Component 800default. Otherwise, mark the component as disabled. Component
537dependents are stopped and marked as disabled as well. Once disabled, 801dependents are stopped and marked as disabled as well. Once disabled,
@@ -539,7 +803,7 @@ the components are never restarted, unless their restart is requested
539by the administrator. 803by the administrator.
540@end deffn 804@end deffn
541 805
542@deffn {Pies Conf} notify @var{email-string} 806@deffn {Config: return-code} notify @var{email-string}
543Send an email notification to addresses in @var{email-string}. The 807Send an email notification to addresses in @var{email-string}. The
544latter is a comma-separated list of email addresses, e.g.: 808latter is a comma-separated list of email addresses, e.g.:
545 809
@@ -547,13 +811,11 @@ latter is a comma-separated list of email addresses, e.g.:
547notify "root@@localhost,postmaster@@localhost"; 811notify "root@@localhost,postmaster@@localhost";
548@end smallexample 812@end smallexample
549 813
550The @code{mailer} statement (@pxref{Mailer, Mailer Statement,, 814The message itself is configured by the @code{message}
551mailutils, GNU Mailutils Manual}) configures the mailer used to send
552the message. The message itself is configured by the @code{message}
553statement. 815statement.
554@end deffn 816@end deffn
555 817
556@deffn {Pies Conf} message @var{string} 818@deffn {Config: return-code} message @var{string}
557Supply notification message text to use by @code{notify} statement. 819Supply notification message text to use by @code{notify} statement.
558@var{String} must be a valid RFC 822 message text, i.e. it must begin 820@var{String} must be a valid RFC 822 message text, i.e. it must begin
559with message headers, followed by an empty line and actual message 821with message headers, followed by an empty line and actual message
@@ -567,7 +829,6 @@ The following macro-variables are expanded within @var{string}:
567@item program-name @tab Program name of the @command{pies} binary. 829@item program-name @tab Program name of the @command{pies} binary.
568@item package @tab Package name (@samp{Pies}). 830@item package @tab Package name (@samp{Pies}).
569@item version @tab Package version (@value{VERSION}). 831@item version @tab Package version (@value{VERSION}).
570@item mu-version @tab Version of GNU Mailutils.
571@item component @tab Name of the terminated component. 832@item component @tab Name of the terminated component.
572@item retcode @tab Component exit code, in decimal. 833@item retcode @tab Component exit code, in decimal.
573@end multitable 834@end multitable
@@ -592,13 +853,13 @@ all components. Any @code{return-code} statements appearing within a
592@code{component} block override the global ones. 853@code{component} block override the global ones.
593 854
594@node Output Redirectors 855@node Output Redirectors
595@section Output Redirectors 856@subsection Output Redirectors
596@cindex repeater 857@cindex repeater
597 Output redirectors allow to redirect the standard error and/or standard 858 Output redirectors allow to redirect the standard error and/or standard
598output of a component to a file or @command{syslog} facility. 859output of a component to a file or @command{syslog} facility.
599 860
600@deffn {Pies Conf} stderr @var{type} @var{channel} 861@deffn {Config: component} stderr @var{type} @var{channel}
601@deffnx {Pies Conf} stdout @var{type} @var{channel} 862@deffnx {Config} stdout @var{type} @var{channel}
602Redirect standard error (if @code{stderr}) or standard output (if 863Redirect standard error (if @code{stderr}) or standard output (if
603@code{stdout}) to the given channel. 864@code{stdout}) to the given channel.
604 865
@@ -618,9 +879,8 @@ Redirect to the syslog channel. The syslog priority is given by the
618@var{channel} argument. Its allowed values are: @samp{emerg}, 879@var{channel} argument. Its allowed values are: @samp{emerg},
619@samp{alert}, @samp{crit}, @samp{err}, @samp{warning}, @samp{notice}, 880@samp{alert}, @samp{crit}, @samp{err}, @samp{warning}, @samp{notice},
620@samp{info}, @samp{debug}. The facility is inherited from the 881@samp{info}, @samp{debug}. The facility is inherited from the
621@code{logging} statement (@pxref{Logging Statement, Mailutils Logging,, 882@code{syslog} statement (@pxref{syslog}), or from @code{facility}
622mailutils, GNU Mailutils Manual}), or from @code{facility} statement 883statement (see below), if given.
623(see below), if given.
624 884
625Example: 885Example:
626 886
@@ -630,7 +890,7 @@ stderr syslog err;
630@end table 890@end table
631@end deffn 891@end deffn
632 892
633@deffn {Pies Conf} facility @var{syslog-facility} 893@deffn {Config: component} facility @var{syslog-facility}
634Specify the syslog facility to use in syslog redirectors. Allowed 894Specify the syslog facility to use in syslog redirectors. Allowed
635values for @var{syslog-facility} are: @samp{user}, @samp{daemon}, 895values for @var{syslog-facility} are: @samp{user}, @samp{daemon},
636@samp{auth}, @samp{authpriv}, @samp{mail}, @samp{cron}, @samp{local0} 896@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.
638@end deffn 898@end deffn
639 899
640@node Inetd-Style Components 900@node Inetd-Style Components
641@section Inetd-Style Components 901@subsection Inetd-Style Components
642@cindex inetd-style components 902@cindex inetd-style components
643 Inetd-style components are declared using @code{mode inetd} 903 Inetd-style components are declared using @code{mode inetd}
644statement. You must also declare a socket to listen for requests for 904statement. You must also declare a socket to listen for requests for
645such components: 905such components:
646 906
647@anchor{inetd-socket} 907@anchor{inetd-socket}
648@deffn {Pies Conf} socket @var{url} 908@deffn {Config: component} socket @var{url}
649Define a socket to listen on. Allowed values for @var{url} are: 909Define a socket to listen on. Allowed values for @var{url} are:
650 910
651@table @asis 911@table @asis
@@ -696,7 +956,7 @@ be added if there is a demand.
696@end deffn 956@end deffn
697 957
698@node Meta1-Style Components 958@node Meta1-Style Components
699@section Meta1-Style Components 959@subsection Meta1-Style Components
700@cindex meta1-style components 960@cindex meta1-style components
701 Meta1-style components are declared using @code{mode pass} 961 Meta1-style components are declared using @code{mode pass}
702statement. For such components, you must declare both a socket to 962statement. 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
704pass the file descriptor to the component. The latter is defined 964pass the file descriptor to the component. The latter is defined
705using @code{pass-fd-socket} statement: 965using @code{pass-fd-socket} statement:
706 966
707@deffn {Pies Conf} pass-fd-socket @var{file-name} 967@deffn {Config: component} pass-fd-socket @var{file-name}
708The argument is an absolute or relative file name of the socket file. 968The argument is an absolute or relative file name of the socket file.
709In the latter case, the @code{chdir @var{dir}} statement must be used 969In the latter case, the @code{chdir @var{dir}} statement must be used
710for this component (@pxref{Actions Before Startup, chdir}), and the 970for this component (@pxref{Actions Before Startup, chdir}), and the
@@ -715,7 +975,7 @@ upon its startup.
715@end deffn 975@end deffn
716 976
717@node Component Syntax Summary 977@node Component Syntax Summary
718@section Component Syntax Summary 978@subsection Component Syntax Summary
719 This subsection summarizes the @code{component} summary. For each 979 This subsection summarizes the @code{component} summary. For each
720statement, a reference to its detailed description is supplied. 980statement, a reference to its detailed description is supplied.
721 981
@@ -814,13 +1074,147 @@ component @var{tag} @{
814@} 1074@}
815@end smallexample 1075@end smallexample
816 1076
1077@node ACL
1078@section Access Control Lists
1079@cindex @acronym{ACL}
1080@cindex access control lists
1081@dfn{Access control lists}, or @acronym{ACL}s for short, are lists of
1082permissions that control access to @samp{inetd}, @samp{access} and
1083@samp{meta1}-style components.
1084
1085An @acronym{ACL} is defined using @code{acl} block statement:
1086
1087@deffn {Config} acl
1088@smallexample
1089acl @var{name} @{
1090 @var{definitions}
1091@}
1092@end smallexample
1093@end deffn
1094
1095The @var{name} parameter specifies a unique name for that
1096@acronym{ACL}. This name can be used by another configuration
1097statements to refer to that @acronym{ACL}.
1098
1099A part between the curly braces (denoted by @var{definitions} above),
1100is a list of @dfn{access statements}. There are two types of
1101such statements:
1102
1103@deffn {Config: acl} allow @var{user-group} @var{sub-acl} @var{host-list}
1104Allow access to resource.
1105@end deffn
1106
1107@deffn {Config: acl} deny @var{user-group} @var{sub-acl} @var{host-list}
1108Deny access to resource.
1109@end deffn
1110
1111All parts of an access statement are optional, but at least one
1112of them must be present.
1113
1114The @var{user-group} part specifies which users match this entry.
1115Allowed values are the following:
1116
1117@table @code
1118@kwindex all
1119@item all
1120All users.
1121
1122@kwindex authenticated
1123@item authenticated
1124Only authenticated users.
1125
1126@kwindex group
1127@item group @var{group-list}
1128Authenticated users which are members of at least one of groups listed in
1129@var{group-list}.
1130@end table
1131
1132The @var{sub-acl} part, if present, allows to branch to another
1133@acronym{ACL}. The syntax of this group is:
1134
1135@smallexample
1136acl @var{name}
1137@end smallexample
1138
1139@noindent
1140where @var{name} is the name of a previously defined @acronym{ACL}.
1141
1142Finally, the @var{host-list} group allows to match client addresses.
1143It consists of a @code{from} keyword followed by a list of
1144@dfn{address specifiers}. Allowed address specifiers are:
1145
1146@table @asis
1147@item @var{addr}
1148Matches if the client @acronym{IP} equals @var{addr}.
1149The latter may be given either as an @acronym{IP}
1150address or as a host name, in which case it will be resolved and the
1151first of its @acronym{IP} addresses will be used.
1152
1153
1154@item @var{addr}/@var{netlen}
1155Matches if first @var{netlen} bits from the client @acronym{IP}
1156address equal to @var{addr}. The network mask length, @var{netlen}
1157must be an integer number in the range from 0 to 32. The address part,
1158@var{addr}, is as described above.
1159
1160@item @var{addr}/@var{netmask}
1161The specifier matches if the result of logical @acronym{AND} between
1162the client @acronym{IP} address and @var{netmask} equals to
1163@var{addr}. The network mask must be specified in ``dotted quad''
1164form, e.g. @samp{255.255.255.224}.
1165
1166@item @var{filename}
1167Matches if connection was received from a @acronym{UNIX} socket
1168@var{filename}, which must be given as an absolute file name.
1169@end table
1170
1171To summarize, the syntax of an access statement is:
1172
1173@smallexample
1174allow|deny [all|authenticated|group @var{group-list}]
1175 [acl @var{name}] [from @var{addr-list}]
1176@end smallexample
1177
1178@noindent
1179where square brackets denote optional parts and vertical bar means
1180@samp{one of}.
1181
1182When an @acronym{ACL} is applied to a particular object, its entries
1183are tried in turn until one of them matches, or the end of the list is
1184reached. If a matched entry is found, its command verb, @code{allow}
1185or @code{deny}, defines the result of @acronym{ACL} match. If the end
1186of list is reached, the result is @samp{allow}, unless explicitly
1187specified otherwise.
1188
1189@FIXME{Trim that example:}
1190For example, the following statement defines an @acronym{ACL} named
1191@samp{common}, that allows access for any user connected via local
1192@acronym{UNIX} socket @file{/tmp/dicod.sock} or coming from a local
1193network @samp{192.168.10.0/24}. Any authenticated users are allowed,
1194provided that they are allowed by another @acronym{ACL} @samp{my-nets}
1195(which should have been defined before this definition). Users
1196coming from the network @samp{10.10.0.0/24} are allowed if they
1197authenticate themselves and are members of groups @samp{pies} or
1198@samp{users}. Access is denied for anybody else:
1199
1200@smallexample
1201@group
1202acl common @{
1203 allow all from ("/tmp/pies.sock", "192.168.10.0/24");
1204 allow authenticated acl "my-nets";
1205 allow group ("pies", "users") from "10.10.0.0/24";
1206 deny all;
1207@}
1208@end group
1209@end smallexample
1210
817@node include-meta1 1211@node include-meta1
818@chapter Using MeTA1 Configuration File 1212@section Using MeTA1 Configuration File
819@cindex /etc/meta1/meta1.conf 1213@cindex /etc/meta1/meta1.conf
820 @command{Pies} is able to take a list of components from MeTA1 1214 @command{Pies} is able to take a list of components from MeTA1
821configuration file: 1215configuration file:
822 1216
823@deffn {Pies Conf} include-meta1 @var{file} 1217@deffn {Config} include-meta1 @var{file}
824Parse @var{file} as MeTA1 configuration file and incorporate 1218Parse @var{file} as MeTA1 configuration file and incorporate
825components defined there into the current component list. 1219components defined there into the current component list.
826 1220
@@ -851,7 +1245,7 @@ Here, @var{compname} stands for the name of the component, and
851latter is @file{/var/spool/meta1} by default. It can be changed using 1245latter is @file{/var/spool/meta1} by default. It can be changed using
852the following statement 1246the following statement
853 1247
854@deffn {Pies Conf} meta1-queue-dir @var{dir} 1248@deffn {Config} meta1-queue-dir @var{dir}
855Set name of MeTA1 queue directory. 1249Set name of MeTA1 queue directory.
856@end deffn 1250@end deffn
857 1251
@@ -870,26 +1264,45 @@ component smtps @{
870@end smallexample 1264@end smallexample
871 1265
872@node Global Configuration 1266@node Global Configuration
873@chapter Global Configuration 1267@section Global Configuration
1268@cindex Global Configuration
874The statements described in this section affect @command{pies} 1269The statements described in this section affect @command{pies}
875behavior as a whole. 1270behavior as a whole.
876 1271
877@deffn {Pies Conf} umask @var{number} 1272@anchor{syslog}
1273@deffn {Config} syslog @{ ... @}
1274This block statement configures logging via syslog. It has two
1275substatements:
1276@end deffn
1277
1278@deffn {Config: syslog} tag @var{string}
1279Prefix syslog messages with this string. By default, the program name
1280is used.
1281
1282@deffn {Config: syslog} facility @var{string}
1283Set syslog facility to use. Allowed values are: @samp{user},
1284@samp{daemon}, @samp{auth}, @samp{authpriv}, @samp{mail}, @samp{cron},
1285@samp{local0} through @samp{local7} (case-insensitive), or a facility
1286number.
1287@end deffn
1288@end deffn
1289
1290@deffn {Config} umask @var{number}
878Set the default umask. The @var{number} must be an octal value not greater 1291Set the default umask. The @var{number} must be an octal value not greater
879than @samp{777}. The default umask is inherited at startup. 1292than @samp{777}. The default umask is inherited at startup.
880@end deffn 1293@end deffn
881 1294
882@deffn {Pies Conf} limits @var{arg} 1295@deffn {Config} limits @var{arg}
883Set global system limits for all pies components. @xref{Resources, 1296Set global system limits for all pies components. @xref{Resources,
884limits}, for a detailed description of @var{arg}. 1297limits}, for a detailed description of @var{arg}.
885@end deffn 1298@end deffn
886 1299
887@deffn {Pies Conf} return-code @{ ... @} 1300@deffn {Config} return-code @{ ... @}
888Configure global exit actions. @xref{Exit Actions}, for a detailed 1301Configure global exit actions. @xref{Exit Actions}, for a detailed
889description of this statement. 1302description of this statement.
890@end deffn 1303@end deffn
891 1304
892@deffn {Pies Conf} shutdown-timeout @var{number}; 1305@deffn {Config} shutdown-timeout @var{number};
893Wait @var{number} of seconds for all components to shut down. 1306Wait @var{number} of seconds for all components to shut down.
894Default is 5 seconds. 1307Default is 5 seconds.
895@end deffn 1308@end deffn
@@ -899,7 +1312,7 @@ Default is 5 seconds.
899@end menu 1312@end menu
900 1313
901@node Less Useful Statements 1314@node Less Useful Statements
902@section Less Useful Statements 1315@subsection Less Useful Statements
903 1316
904 Some configuration file statements are provided for completeness and 1317 Some configuration file statements are provided for completeness and
905are rarely, if at all used. If used improperly, they may severely 1318are 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
911needed by @command{pies}. Use them only if the defaults does not 1324needed by @command{pies}. Use them only if the defaults does not
912suit your needs: 1325suit your needs:
913 1326
914@deffn {Pies Conf} pidfile @var{file} 1327@deffn {Config} pidfile @var{file}
915Write PID of the master @command{pies} process to @var{file}. By 1328Write PID of the master @command{pies} process to @var{file}. By
916default, master PID is stored in @file{@var{statedir}/pies.pid} 1329default, master PID is stored in @file{@var{statedir}/pies.pid}
917(@FIXME-pxref{statedir}). 1330(@FIXME-pxref{statedir}).
918@end deffn 1331@end deffn
919 1332
920@deffn {Pies Conf} control-file @var{file} 1333@deffn {Config} control-file @var{file}
921Set file name of the @command{pies} control file. Default is 1334Set file name of the @command{pies} control file. Default is
922@file{@var{statedir}/pies.ctl} 1335@file{@var{statedir}/pies.ctl}
923@end deffn 1336@end deffn
924 1337
925@deffn {Pies Conf} stat-file @var{file} 1338@deffn {Config} stat-file @var{file}
926Set file name of the statistics output file. Default is 1339Set file name of the statistics output file. Default is
927@file{@var{statedir}/pies.stat}. 1340@file{@var{statedir}/pies.stat}.
928@end deffn 1341@end deffn
@@ -932,55 +1345,62 @@ however, you found such an implementation for it, that requires another
932privileges, you may change them using the following three statements: 1345privileges, you may change them using the following three statements:
933 1346
934@command{pies} process. 1347@command{pies} process.
935@deffn {Pies Conf} user @var{user-name} 1348@deffn {Config} user @var{user-name}
936Start @command{pies} with the UID and GID of this user. 1349Start @command{pies} with the UID and GID of this user.
937@end deffn 1350@end deffn
938 1351
939@deffn {Pies Conf} group @var{group-list} 1352@deffn {Config} group @var{group-list}
940Retain supplementary groups, specified in @var{group-list}. 1353Retain supplementary groups, specified in @var{group-list}.
941@end deffn 1354@end deffn
942 1355
943@deffn {Pies Conf} allgroups @var{bool} 1356@deffn {Config} allgroups @var{bool}
944Retain all supplementary groups of which user, given with 1357Retain all supplementary groups of which user, given with
945@command{user} statement, is a member. 1358@command{user} statement, is a member.
946@end deffn 1359@end deffn
947 1360
948@node Pies Debugging 1361@node Pies Debugging
949@chapter Pies Debugging 1362@chapter Pies Debugging
1363@xopindex{debug, described}
950 The amount of debugging information produced by @command{pies} is configured 1364 The amount of debugging information produced by @command{pies} is configured
951by the following two configuration statements. First of all, the standard 1365by the following statements:
952@code{debug} block statement controls debugging of the underlying GNU 1366
953Mailutils libraries (@pxref{Debug Statement, Mailutils Configuration 1367@deffn {Config} debug @var{level}
954File,, mailutils, GNU Mailutils Manual}). Secondly, the @code{debug} 1368Set debugging level. The @var{level} must be a non-negative decimal
955statement controls debugging output of the @command{pies} utility 1369integer. In version @value{VERSION} the following debugging levels
956itself. 1370are used:
957
958@deffn {Pies Conf} debug @var{spec}
959Set debugging level for the @command{pies} code. @xref{Debug
960Statement, Mailutils Configuration File,, mailutils, GNU Mailutils
961Manual}, for a description of @var{spec} syntax. The following
962debugging levels are used:
963 1371
964@table @asis 1372@table @asis
965@item trace1 1373@item 1
966Log all basic actions: starting and stopping of components, received incoming 1374Log all basic actions: starting and stopping of components, received incoming
967@acronym{TCP} connections, sending mails. Notify about setting 1375@acronym{TCP} connections, sending mails. Notify about setting
968limits. Log pre-startup actions (@pxref{Actions Before Startup}). 1376limits. Log pre-startup actions (@pxref{Actions Before Startup}).
969 1377
970@item trace2 1378@item 2
971Log setting particular limits. Log the recomputed alarms. 1379Log setting particular limits. Log the recomputed alarms.
972 1380
973@item trace4 1381@item 4
974Dump execution environments 1382Dump execution environments
975 1383
976@item trace6 1384@item 6
977Debug the parser of MeTA1 configuration grammar. 1385Debug the parser of MeTA1 configuration grammar.
978 1386
979@item trace7 1387@item 7
980Debug the lexical analyzer of MeTA1 configuration file. 1388Debug the lexical analyzer of MeTA1 configuration file.
981@end table 1389@end table
982@end deffn 1390@end deffn
983 1391
1392@anchor{source-info}
1393@deffn {Config} source-info @var{bool}
1394This statement decides whether debugging messages should contain
1395source information. To enable source information, use:
1396
1397@smallexample
1398source-info yes;
1399@end smallexample
1400
1401This feature is designed for @command{pies} developers.
1402@end deffn
1403
984@node Configuration Example 1404@node Configuration Example
985@chapter Configuration Example 1405@chapter Configuration Example
986 In this section we provide several examples of working @command{pies} 1406 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]
1135(the example above is split in two lines for readability). 1555(the example above is split in two lines for readability).
1136 1556
1137@anchor{pies-restart} 1557@anchor{pies-restart}
1558@xopindex{restart-component, described}
1138 You can restart any component by using the 1559 You can restart any component by using the
1139@option{--restart-component} (@option{-R}) option, e.g.: 1560@option{--restart-component} (@option{-R}) option, e.g.:
1140 1561
@@ -1142,6 +1563,7 @@ component pmult [disabled; scheduled for Mon 01 Dec 2008 20:27:02]
1142$ pies -R pmult smtps 1563$ pies -R pmult smtps
1143@end smallexample 1564@end smallexample
1144 1565
1566@xopindex{stop, described}
1145 To stop all running components and shut down @command{pies}, use the 1567 To stop all running components and shut down @command{pies}, use the
1146@option{--stop} (@option{-S}) command line option: 1568@option{--stop} (@option{-S}) command line option:
1147 1569
@@ -1149,9 +1571,9 @@ $ pies -R pmult smtps
1149$ pies --stop 1571$ pies --stop
1150@end smallexample 1572@end smallexample
1151 1573
1152@cindex dependencies, pies 1574@cindex dependencies
1153@anchor{dump-depmap} 1575@anchor{dump-depmap}
1154@cindex --dump-depmap option, pies 1576@xopindex{dump-depmap option, introduced}
1155 Two options are provided for verifying inter-component 1577 Two options are provided for verifying inter-component
1156dependencies. The @option{--dump-depmap} option prints on the 1578dependencies. The @option{--dump-depmap} option prints on the
1157standard output the @dfn{dependency map}. This map is a square matrix 1579standard 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
1184means that @samp{smtps} depends on @samp{smar} and @samp{qmgr}. 1606means that @samp{smtps} depends on @samp{smar} and @samp{qmgr}.
1185 1607
1186@anchor{dump-prereq} 1608@anchor{dump-prereq}
1187@cindex --dump-prereq option, pies 1609@xopindex{dump-prereq, described}
1188 You can also list prerequisites explicitly: 1610 You can also list prerequisites explicitly:
1189 1611
1190@smallexample 1612@smallexample
@@ -1200,52 +1622,109 @@ smtps: smar qmgr
1200This section summarizes @command{pies} command line options. 1622This section summarizes @command{pies} command line options.
1201 1623
1202@table @option 1624@table @option
1625@opsummary{config-help}
1626@item --config-help
1627Show configuration file summary. @xref{Pies Configuration File}.
1628
1629@opsummary{config-file}
1630@item --config-file=@var{file}
1631@item -c @var{file}
1632Read configuration from @var{file}, instead of the default
1633@file{/etc/pies.conf}.
1634
1635@xref{Pies Configuration File}.
1636
1637@item -E
1638Preprocess configuration file and exit. @xref{Preprocessor}.
1639
1640@opsummary{force}
1203@item --force 1641@item --force
1204Force startup even if another instance may be running. 1642Force startup even if another instance may be running.
1205 1643
1644@opsummary{foreground}
1206@item --foreground 1645@item --foreground
1207Remain in foreground. 1646Remain in foreground.
1208 1647
1648@opsummary{source-info}
1649@item --source-info
1650Show source info with debugging messages. @xref{source-info}.
1651
1652@opsummary{lint}
1653@item --lint
1654@itemx -t
1655
1656@opsummary{stderr}
1209@item --stderr 1657@item --stderr
1210Log to standard error. 1658Log to standard error.
1211 1659
1660@opsummary{syslog}
1212@item --syslog 1661@item --syslog
1213Log to syslog. This is the default. 1662Log to syslog. This is the default.
1214 1663
1664@opsummary{debug}
1215@item -x @var{level} 1665@item -x @var{level}
1216@itemx --debug=@var{level} 1666@itemx --debug=@var{level}
1217Set debug verbosity level. @xref{Pies Debugging}, for a description 1667Set debug verbosity level. @xref{Pies Debugging}, for a description
1218of @var{level}. 1668of @var{level}.
1219 1669
1670@opsummary{reload}
1671@opsummary{hup}
1220@item -r 1672@item -r
1221@itemx --reload 1673@itemx --reload
1222@itemx --hup 1674@itemx --hup
1223Reload the running instance of pies. 1675Reload the running instance of pies.
1224 1676
1677@opsummary{restart-component}
1225@item -R 1678@item -R
1226@itemx --restart-component 1679@itemx --restart-component
1227Restart components named in the command line. @xref{pies-restart}. 1680Restart components named in the command line. @xref{pies-restart}.
1228 1681
1682@opsummary{status}
1229@item -s 1683@item -s
1230@itemx --status 1684@itemx --status
1231Display info about the running instance. @xref{pies-status}. 1685Display info about the running instance. @xref{pies-status}.
1232 1686
1687@opsummary{stop}
1233@item -S 1688@item -S
1234@itemx --stop 1689@itemx --stop
1235Stop the running instance. 1690Stop the running instance.
1236 1691
1692@opsummary{dump-depmap}
1237@item --dump-depmap 1693@item --dump-depmap
1238Dump dependency map. @xref{dump-depmap}. 1694Dump dependency map. @xref{dump-depmap}.
1239 1695
1696@opsummary{dump-prereq}
1240@item --dump-prereq 1697@item --dump-prereq
1241Dump prerequisite charts. @xref{dump-prereq}. 1698Dump prerequisite charts. @xref{dump-prereq}.
1242 1699
1700@item --help
1701Display a short usage summary and exit.
1702
1703@item --usage
1704Display a short summary of available options and exit.
1705
1706@item --version
1707Display program version and license information and exit.
1708
1243@end table 1709@end table
1244 1710
1245Apart from these, the common GNU Mailutils options are understood, which 1711@node Reporting Bugs
1246are useful for checking @command{pies} configuration file for syntax 1712@chapter How to Report a Bug
1247errors. @xref{Common Options, Common Options, , mailutils, GNU 1713
1248Mailutils Manual}, for a detailed description of these. 1714 Send bug-reports and suggestions to @email{bug-mailfromd@@gnu.org.ua}.
1715
1716 If you think you've found a bug, please be sure to include maximum
1717information needed to reliably reproduce it, or at least to analyze
1718it. The information needed is:
1719
1720@itemize
1721@item Version of the package you are using.
1722@item Compilation options used when configuring the package.
1723@item Run-time configuration (@file{pies.conf} file and the command
1724line options used).
1725@item Detailed description of the bug.
1726@item Conditions under which the bug appears.
1727@end itemize
1249 1728
1250@node Copying This Manual 1729@node Copying This Manual
1251@appendix GNU Free Documentation License 1730@appendix GNU Free Documentation License

Return to:

Send suggestions and report system problems to the System administrator.