aboutsummaryrefslogtreecommitdiff
path: root/doc/pies.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/pies.texi')
-rw-r--r--doc/pies.texi715
1 files changed, 597 insertions, 118 deletions
diff --git a/doc/pies.texi b/doc/pies.texi
index cc35b5d..22c0f83 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -78,27 +78,25 @@ documents @command{pies} Version @value{VERSION}.
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