diff options
Diffstat (limited to 'doc/pies.texi')
-rw-r--r-- | doc/pies.texi | 715 |
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 | ||
89 | Appendices | 87 | Appendices |
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 |
104 | starts and controls execution of external programs, called | 102 | starts and controls execution of external programs, called |
@@ -110,9 +108,9 @@ terminates, @command{pies} restarts it. Its configuration allows to | |||
110 | specify actions other than simple restart, depending on the exit code | 108 | specify actions other than simple restart, depending on the exit code |
111 | of the component. | 109 | of 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} |
135 | components, called so because of the similarity with the | 133 | components, 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 |
137 | components that receive input on their @samp{stdin} and send reply to | 135 | components 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} |
181 | statement (@pxref{include-meta1}). | 179 | statement (@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 | ||
188 | configuration directory} (in most cases @file{/etc} or | ||
189 | @file{/usr/local/etc}, depending on how the package was compiled). | ||
190 | An 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 | ||
194 | reports 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 | ||
200 | if 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 | ||
205 | configuration without actually parsing it, use @option{-E} command | ||
206 | line option. | ||
207 | |||
208 | @xopindex{config-help, introduced} | ||
209 | The rest of this section describes the configuration file syntax in | ||
210 | detail. You can receive a concise summary of all configuration | ||
211 | directives 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. |
189 | configuration file. @xref{configuration, Mailutils Configuration | 224 | |
190 | File,, mailutils, GNU Mailutils Manual}, for a description of GNU | 225 | There are three classes of lexical tokens: keywords, values, and |
191 | Mailutils configuration system. It is recommended to use | 226 | separators. 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 |
193 | Statement,, mailutils, GNU Mailutils Manual}), and to place | 228 | tokens. Some white space is required to separate otherwise adjacent |
194 | @command{pies} configuration in file @file{@var{directory}/pies}. | 229 | keywords and values. |
195 | @xref{MeTA1,,, mailfromd, Mailfromd Manual}, for an example. | 230 | |
196 | 231 | @menu | |
197 | The 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 | |
202 | mailutils, GNU Mailutils Manual}. | 237 | @node Comments |
203 | @item logging @tab @xref{Logging Statement, Mailutils Logging,, | 238 | @subsection Comments |
204 | mailutils, GNU Mailutils Manual}. | 239 | @cindex Comments in a configuration file |
205 | @item include @tab @xref{Include, Include Statements,, | 240 | @cindex single-line comments |
206 | mailutils, GNU Mailutils Manual}. | 241 | @dfn{Comments} may appear anywhere where white space may appear in the |
207 | @item mailer @tab @xref{Mailer, Mailer Statement,, | 242 | configuration file. There are two kinds of comments: |
208 | mailutils, GNU Mailutils Manual}. | 243 | single-line and multi-line comments. @dfn{Single-line} comments start |
209 | @item acl @tab @xref{ACL Statement, ACL Statement,, | 244 | with @samp{#} or @samp{//} and continue to the end of the line: |
210 | mailutils, 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 | ||
253 | characters @samp{/*} (slash, star) and continue until the first | ||
254 | occurrence 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 | ||
265 | separated by any amount of whitespace. Simple statement is terminated | ||
266 | with 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 | ||
272 | pidfile /var/run/pies.pid; | ||
273 | source-info yes; | ||
274 | debug 10; | ||
275 | @end smallexample | ||
276 | |||
277 | A @dfn{keyword} begins with a letter and may contain letters, | ||
278 | decimal digits, underscores (@samp{_}) and dashes (@samp{-}). | ||
279 | Examples 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 | ||
296 | following 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 | ||
304 | double-quotes (@samp{"}). A backslash appearing within a quoted | ||
305 | string introduces an @dfn{escape sequence}, which is replaced | ||
306 | with 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 | ||
324 | the string. This allows to split long strings over several | ||
325 | physical 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 | ||