diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/pies.texi | 290 |
1 files changed, 167 insertions, 123 deletions
diff --git a/doc/pies.texi b/doc/pies.texi index 51eac43..13deec0 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -1,5 +1,4 @@ \input texinfo @c -*-texinfo-*- -@smallbook @c %**start of header @setfilename pies.info @settitle GNU Pies Manual @@ -251,9 +250,9 @@ this format, the program also understands configuration files in Alternative configuration files may be specified using @option{--config-file} (@option{-c} command line option), e.g.: -@smallexample +@example pies --config-file @var{filename} -@end smallexample +@end example @anchor{config syntax} Any number of such options may be given. The files named in @@ -286,13 +285,13 @@ the end of the command line or the next occurrence of the @command{pies} to read several configuration files of various formats in a single command line, e.g.: -@smallexample +@example @group pies --config-file /etc/pies.conf \ --syntax=inetd --config-file /etc/inetd.conf \ --syntax=meta1 --config-file /etc/meta1/meta1.conf @end group -@end smallexample +@end example @xopindex{config-help, introduced} The rest of this chapter concerns the @command{pies} native @@ -321,10 +320,11 @@ line option. @menu * Syntax:: Configuration File Syntax * Component Statement:: -* Notification:: Mail Notification -* ACL:: Access Control Lists -* inetd:: Using @command{inetd} Configuration Files -* include-meta1:: Using @command{meta1} Configuration Files +* Notification:: Mail Notification. +* ACL:: Access Control Lists. +* control:: The @samp{control} statement. +* inetd:: Using @command{inetd} Configuration Files. +* include-meta1:: Using @command{meta1} Configuration Files. * Global Configuration:: * Pies Privileges:: * State Files:: @@ -355,10 +355,10 @@ 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 +@example # This is a comment // This too is a comment -@end smallexample +@end example The following constructs, appearing at the start of a line are treated specially: @samp{#include}, @samp{#include_once}, @@ -384,11 +384,11 @@ with a semicolon (@samp{;}). Examples of simple statements are: -@smallexample +@example pidfile /var/run/pies.pid; source-info yes; debug 10; -@end smallexample +@end example A @dfn{keyword} begins with a letter and may contain letters, decimal digits, underscores (@samp{_}) and dashes (@samp{-}). @@ -442,12 +442,12 @@ a newline character (@acronym{ASCII} 10) is removed from the string. This allows to split long strings over several physical lines, e.g.: -@smallexample +@example @group "a long string may be\ split over several lines" @end group -@end smallexample +@end example If the character following a backslash is not one of those specified above, the backslash is ignored and a warning is issued. @@ -457,12 +457,12 @@ another way to split long strings over several lines to improve readability. The following fragment produces the same result as in the example above: -@smallexample +@example @group "a long string may be" " split over several lines" @end group -@end smallexample +@end example @anchor{here-document} @item Here-document @@ -475,14 +475,14 @@ 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 +@example @group <<EOT A multiline string EOT @end group -@end smallexample +@end example Body of a here-document is interpreted the same way as double-quoted string, unless @var{word} is preceded by a backslash @@ -495,14 +495,14 @@ tab characters are stripped from input lines and the line containing all leading whitespace is stripped from them. This allows to indent here-documents in a natural fashion. For example: -@smallexample +@example @group <<- TEXT All leading whitespace will be ignored when reading these lines. TEXT @end group -@end smallexample +@end example It is important that the terminating delimiter be the only token on its line. The only exception to this rule is allowed if a @@ -510,11 +510,11 @@ 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 +@example help-text <<-EOT A sample help text. EOT; -@end smallexample +@end example @item list @cindex list @@ -522,9 +522,9 @@ EOT; delimited by parentheses. The following example shows a statement whose value is a list of strings: -@smallexample +@example dependents (pmult, auth); -@end smallexample +@end example 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 @@ -540,13 +540,13 @@ 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 +@example @group component multiplexor @{ command "pmult"; @} @end group -@end smallexample +@end example The closing curly brace may be followed by a semicolon, although this is not required. @@ -684,11 +684,11 @@ compatibility with the @sc{c} preprocessor. The @code{component} statement defines a new component: @end deffn -@smallexample +@example component @var{tag} @{ @dots{} @} -@end smallexample +@end example The component is identified by its @dfn{tag}, which is given as argument to the @code{component} keyword. Component declarations with @@ -960,9 +960,9 @@ utility: For example: -@smallexample +@example limits T10 R20 U16 P20 -@end smallexample +@end example Additionally, the command letter @samp{L} is recognized. It is reserved for future use (@samp{number of logins} limit) and is ignored @@ -1005,9 +1005,9 @@ begins with a punctuation character, this character is removed from it before the assignment. This is convenient for using this construct with environment variables like @env{PATH}, e.g.: -@smallexample +@example PATH+=:/sbin -@end smallexample +@end example In this example, if @env{PATH} exists, @samp{:/sbin} will be appended to it. Otherwise, it will be created and @samp{/sbin} will be @@ -1061,11 +1061,11 @@ to the log file. This behavior can be modified using @code{return-code} statement: @deffn {Config: component} return-code -@smallexample +@example return-code @var{codes} @{ @dots{} @} -@end smallexample +@end example @end deffn The @var{codes} argument is a list of exit codes or signal names. @@ -1181,9 +1181,9 @@ The type of redirection is specified by @var{type} argument: Redirect to a file. In this case @var{channel} gives the full name of the file. For example: -@smallexample +@example stderr file /var/log/component/name.err; -@end smallexample +@end example @item syslog Redirect to a syslog channel. The syslog priority is given by the @@ -1195,9 +1195,9 @@ statement (see below), if given. Example: -@smallexample +@example stderr syslog err; -@end smallexample +@end example @end table @end deffn @@ -1255,10 +1255,10 @@ and @samp{777}). For example: -@smallexample +@example socket "unix:///var/run/socket;user=nobody;group=mail;mode=770"; -@end smallexample +@end example The @var{file} part may be a relative file name, provided that the @code{chdir} statement is used for this component @@ -1382,7 +1382,7 @@ listed in the above table. For example, the following component declaration defines a standard TCP-based echo service: -@smallexample +@example @group component echo @{ socket "inet://0.0.0.0:echo"; @@ -1390,13 +1390,13 @@ component echo @{ flags internal; @} @end group -@end smallexample +@end example It corresponds to the following @file{inetd.conf} line: -@smallexample +@example echo stream tcp nowait root internal -@end smallexample +@end example Another built-in services are defined in the same manner, replacing @samp{echo} in the @code{service} field with the corresponding service @@ -1446,13 +1446,13 @@ subordinate services, one name per line, and closes the connection. The master TCPMUX service is declared as a usual built-in service, e.g.: -@smallexample +@example component tcpmux-master @{ socket "inet://0.0.0.0:1"; service tcpmux; flags internal; @} -@end smallexample +@end example Any number of subordinate services may be defined for each master. A subordinate server component definition must contain at least the @@ -1488,14 +1488,14 @@ The command line for handling this service. For example: -@smallexample +@example component scp-to @{ service scp-to; flags (tcpmuxplus, sockenv); tcpmux-master tcpmux; command "/usr/sbin/in.wydawca"; @} -@end smallexample +@end example @cindex ACL in TCPMUX services For TCPMUX services, access control lists are handled in the @@ -1563,7 +1563,7 @@ the following configuration snippet configures an @acronym{FTP} server and ensures that a special program is invoked after closing each @acronym{FTP} connection: -@smallexample +@example component ftp @{ return-code EX_OK @{ exec "/sbin/sweeper --log"; @@ -1574,7 +1574,7 @@ component ftp @{ program /usr/sbin/in.ftpd command "ftpd -ll -C -t180"; @} -@end smallexample +@end example This approach may be used to process @command{FTP} uploads in real time. @@ -1602,7 +1602,7 @@ upon its startup. This subsection summarizes the @code{component} statements. For each statement, a reference to its detailed description is provided. -@smallexample +@example component @var{tag} @{ # @r{Component execution mode.} # @xref{Component Statement, mode}. @@ -1744,7 +1744,7 @@ component @var{tag} @{ exec @var{command} @} @} -@end smallexample +@end example @node Notification @section Notification @@ -1761,9 +1761,9 @@ in a @samp{return-code} block. Send email notification to each address from @var{email-string}. The latter is a comma-separated list of email addresses, e.g.: -@smallexample +@example notify "root@@localhost,postmaster@@localhost"; -@end smallexample +@end example @end deffn @deffn {Config: return-code} message @var{string} @@ -1776,9 +1776,9 @@ variable references. A @dfn{variable} is an entity that holds some data describing the event that occurred. Meta-variables are referenced using the following construct: -@smallexample +@example $@{@var{name}@} -@end smallexample +@end example @noindent where @var{name} is the name of the variable. Before actually sending @@ -1789,16 +1789,16 @@ to the name of the exited component and its exit code, correspondingly. Supposing that @samp{component} is @samp{ftpd} and @samp{retcode} is 76, the following fragment: -@smallexample +@example Subject: $@{component@} exited with code $@{retcode@} -@end smallexample +@end example @noindent will become: -@smallexample +@example Subject: ftpd exited with code 76 -@end smallexample +@end example The table below lists all available variables and their expansions: @@ -1823,9 +1823,9 @@ with the @samp{retcode} variable. Namely, its value is @samp{exited with}, if the component exited and @samp{terminated on signal}, if it terminated on a signal. Thus, using -@smallexample +@example $@{termination@} $@{retcode@} -@end smallexample +@end example @noindent results in a correct English sentence. This message, however, cannot @@ -1835,12 +1835,12 @@ versions. If @code{message} statement is not given, the following default message is used instead: -@smallexample +@example From: <> X-Agent: $@{canonical_program_name@} ($@{package@} $@{version@}) Subject: Component $@{component@} $@{termination@} $@{retcode@}. -@end smallexample +@end example @end deffn @cindex mailer @@ -1862,17 +1862,17 @@ recipient addresses. For example, the following statement instructs @command{pies} to use @command{exim} as a mailer: -@smallexample +@example mailer-program /usr/sbin/exim; -@end smallexample +@end example @end deffn By default, the mailer program is invoked as follows: -@smallexample +@example /usr/sbin/sendmail -oi -t @var{rcpts} -@end smallexample +@end example @noindent where @var{rcpts} is a whitespace-separated list of addresses supplied @@ -1890,9 +1890,9 @@ receives as @samp{argv[0]}. The example below shows how to use this statement to alter the envelope sender address: -@smallexample +@example mailer-command-line "sendmail -f root@@domain.com -oi -t"; -@end smallexample +@end example @end deffn @node ACL @@ -1906,11 +1906,11 @@ permissions that control access to @samp{inetd}, @samp{accept} and An @acronym{ACL} is defined using @code{acl} block statement: @deffn {Config} acl -@smallexample +@example acl @{ @var{definitions} @} -@end smallexample +@end example @end deffn This statement is allowed both in global context and within a @@ -1924,11 +1924,11 @@ assigned its own name. Named @acronym{ACL}s are defined using the @samp{defacl} statement: @deffn {Config} defacl @var{name} -@smallexample +@example defacl @var{name} @{ @var{definitions} @} -@end smallexample +@end example The @var{name} parameter specifies a unique name for that @acronym{ACL}. Named @acronym{ACL}s are applied only if @@ -1967,9 +1967,9 @@ future use and is described in more detail in @ref{User-Group ACLs}. The @var{sub-acl} part, if present, allows to branch to another @acronym{ACL}. The syntax of this part is: -@smallexample +@example acl @var{name} -@end smallexample +@end example @noindent where @var{name} is the name of an @acronym{ACL} defined previously in @@ -2011,9 +2011,9 @@ statement in an @acronym{ACL} definition. To summarize, the syntax of an access statement is: -@smallexample +@example allow|deny [acl @var{name}] [from @var{addr-list}] -@end smallexample +@end example @noindent where square brackets denote optional parts. @@ -2031,7 +2031,7 @@ or any connection that matches the named @acronym{ACL} @samp{my-nets} (which is defined elsewhere in the configuration file). Access is denied for anybody else: -@smallexample +@example @group acl @{ allow from (192.168.10.0/24, 192.168.100.0/24); @@ -2039,7 +2039,11 @@ acl @{ deny all; @} @end group -@end smallexample +@end example + +@node control +@section The Control Statement +@WRITEME @node inetd @section Using @command{inetd} Configuration Files @@ -2063,38 +2067,38 @@ list of components in order of their appearance. For example, the following statement reads components from the standard @command{inetd} configuration file: -@smallexample +@example include-inetd /etc/inetd.conf; -@end smallexample +@end example Any number of @code{include-inetd} may be specified. For example, the following reads the contents of the @file{/etc/inetd.conf} configuration file and all files from the @file{/etc/inetd.d} directory: -@smallexample +@example include-inetd /etc/inetd.conf; include-inetd /etc/inetd.d; -@end smallexample +@end example @end deffn Another way to read @command{inetd} configuration files is to supply them in the command line, like this: -@smallexample +@example pies --syntax=inetd --config-file /etc/inetd.conf -@end smallexample +@end example Notice the @option{--syntax} option (@pxref{config syntax}). It informs @command{pies} that the following files are in @command{inetd} format. Of course, several configuration file may be given: -@smallexample +@example @group pies --syntax=inetd \ --config-file /etc/inetd.conf --config-file /etc/inetd.d @end group -@end smallexample +@end example A special option is provided that instructs @command{pies} to behave as @command{inetd}: @@ -2116,9 +2120,9 @@ the system binary of that name. The command line usage of the @command{inetd} wrapper is entirely compatible with that of the usual @command{inetd} utility, i.e.: -@smallexample +@example inetd [@var{option}] [@var{config} [@var{config}...]] [-- @var{pies-options}] -@end smallexample +@end example Options are: @@ -2181,11 +2185,11 @@ first), and stopped in the order of their appearance in @var{file}. The following @command{pies} statements are silently applied to all MeTA1 components: -@smallexample +@example allgroups yes; stderr file @var{compname}.log chdir @var{queue-dir} -@end smallexample +@end example Here, @var{compname} stands for the name of the component, and @var{queue-dir} stands for the name of MeTA1 queue directory. The @@ -2202,14 +2206,14 @@ To override any default settings for a MeTA1 component, add a standard error of the @samp{smtps} component to @samp{local1.debug} syslog channel: -@smallexample +@example include-meta1 /etc/meta1/meta1.conf component smtps @{ facility local1; stderr syslog debug; @} -@end smallexample +@end example @node Global Configuration @section Global Configuration @@ -2355,9 +2359,9 @@ Debug the lexical analyzer of MeTA1 configuration file. This statement decides whether debugging messages should contain source information. To enable source information, use: -@smallexample +@example source-info yes; -@end smallexample +@end example This feature is designed for @command{pies} developers. @end deffn @@ -2757,7 +2761,7 @@ the privileges of @samp{meta1} user. Both standard error and standard output are redirected to the syslog facility @samp{mail}, priorities @samp{err} and @samp{info}, correspondingly. -@smallexample +@example component pmult @{ command "/usr/local/sbin/pmult"; user meta1s; @@ -2765,7 +2769,7 @@ component pmult @{ stderr syslog err; stdout syslog info; @} -@end smallexample +@end example @node Hairy Pies @section Using Pies to Run Pmult and MeTA1 @@ -2774,7 +2778,7 @@ component pmult @{ @file{/etc/meta1/meta1.conf}. The global @code{return-code} statement is used to configure @command{pies} behavior for some exit codes. -@smallexample +@example # Sample pies configuration for running pmult and MeTA1 # Special handling for exit codes that mean the program was @@ -2807,7 +2811,7 @@ component pmult @{ @} include-meta1 "/etc/meta1/meta1.conf"; -@end smallexample +@end example @node Inetd Pies @section Running Pies as Inetd @@ -2816,7 +2820,7 @@ This configuration file allows to run @command{pies} instead of @command{initd}. It starts two services: @samp{ftp} and @samp{pop3d}, and restricts access to them to two local subnets: -@smallexample +@example acl @{ allow from 10.10.10.0/24; allow from 192.168.10.0/27; @@ -2839,15 +2843,15 @@ component pop3d @{ program "/usr/sbin/pop3d"; command "pop3d --inetd"; @} -@end smallexample +@end example The following is almost equivalent configuration in @command{inetd} format: -@smallexample +@example ftp stream tcp nowait root /usr/sbin/ftpd ftpd -l -C pop3 stream tcp nowait root /usr/sbin/pop3d pop3d --inetd -@end smallexample +@end example This configuration is ``almost'' equivalent, because the @command{inetd} format has no way of specifying ACLs and setting the @@ -2883,11 +2887,11 @@ messages with @var{name}. For example, the following invocations create three instances of @command{pies}: -@smallexample +@example pies pies --instance=inetd pies --instance=mta -@end smallexample +@end example The first instance uses the default configuration and state files. The second one reads configuration from @file{/etc/inetd.conf}, and @@ -2897,7 +2901,7 @@ the third one reads it from @file{/etc/mta.conf}. After startup, you can verify the status of the running process using the @option{--status} command line option: -@smallexample +@example @group $ pies --status smtps/stderr R 4697 @@ -2913,7 +2917,7 @@ eklogin IL inet+tcp://0.0.0.0:eklogin /usr/sbin/klogind -k -c -e kshell IL inet+tcp://0.0.0.0:kshell /usr/sbin/kshd -k -c eklogin IR 13836 /usr/local/sbin/klogind -k -c -e @end group -@end smallexample +@end example Each output line contains at least two columns. The first column lists the tag of the component. The second one contains @dfn{flags}, @@ -2969,17 +2973,17 @@ listed in the next column. You can restart any component by using the @option{--restart-component} (@option{-R}) option, e.g.: -@smallexample +@example $ pies -R pmult smtps -@end smallexample +@end example @xopindex{stop, described} To stop all running components and shut down @command{pies}, use the @option{--stop} (@option{-S}) command line option: -@smallexample +@example $ pies --stop -@end smallexample +@end example @cindex dependencies @anchor{dump-depmap} @@ -2991,7 +2995,7 @@ with rows representing dependents and columns representing prerequisites. An @samp{X} sign is placed on each crossing which corresponds to the actual dependency. For example: -@smallexample +@example @group $ pies --dump-depmap Dependency map: @@ -3009,7 +3013,7 @@ Legend: 3: smtpc 4: smtps @end group -@end smallexample +@end example This example corresponds to the configuration file shown in @ref{Hairy Pies}. To illustrate how to read it, consider the 4th row of the @@ -3017,18 +3021,52 @@ table. According to the legend, number 4 means @samp{smtps} component. There are two @samp{X} marks: in columns 1 and 2. This means that @samp{smtps} depends on @samp{smar} and @samp{qmgr}. -@anchor{dump-prereq} -@xopindex{dump-prereq, described} +@anchor{trace-prereq} +@xopindex{trace-prereq, described} You can also list prerequisites explicitly: -@smallexample +@example @group -$ pies --dump-prereq +$ pies --trace-prereq qmgr: smar smtpc: qmgr smtps: smar qmgr @end group -@end smallexample +@end example + +@noindent +To list prerequisites for a particular component, give its name in +the command line: + +@example +@group +$ pies --trace-prereq smtps +smtps: smar qmgr +@end group +@end example + +Any number of components can be given in the command line. + +@anchor{trace-depend} +A counterpart option @option{--trace-depend} lists dependencies. Its +usage is similar to the described above: + +@example +@group +$ pies --trace-depend +smtps +smtpc +qmgr: smtps, smtpc +smar: smtps, qmgr +@end group +@end example + +@example +@group +$ pies --trace-depend qmgr +qmgr: smtps, smtpc +@end group +@end example @node Invocation @chapter Pies Invocation @@ -3064,9 +3102,15 @@ of @var{level}. @item --dump-depmap Dump dependency map. @xref{dump-depmap}. -@opsummary{dump-prereq} -@item --dump-prereq -Dump prerequisite charts. @xref{dump-prereq}. +@opsummary{trace-depend} +@item --trace-depend +List dependencies for components named in the command line. Without +arguments, dependencies for each component are listed. @xref{trace-depend}. + +@opsummary{trace-prereq} +@item --trace-prereq +List prerequisites for components named in the command line. Without +arguments, prerequisites for each component are listed. @xref{trace-prereq}. @item -E Preprocess configuration file and exit. @xref{Preprocessor}. |