diff options
-rw-r--r-- | doc/pies.texi | 290 | ||||
-rw-r--r-- | src/comp.c | 18 | ||||
-rw-r--r-- | src/meta1parse.c | 6 |
3 files changed, 183 insertions, 131 deletions
diff --git a/doc/pies.texi b/doc/pies.texi index 51eac43..13deec0 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -1,8 +1,7 @@ \input texinfo @c -*-texinfo-*- -@smallbook @c %**start of header @setfilename pies.info @settitle GNU Pies Manual @c %**end of header @setchapternewpage odd @@ -248,15 +247,15 @@ This file uses the @dfn{native Pies configuration syntax}. Apart from this format, the program also understands configuration files in @dfn{inetd} and @dfn{meta1} formats. 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 @option{--config-file} options are processed in order of their appearance in the command line. By default, @command{pies} expects configuration files in its native format. This, however, can be @@ -283,19 +282,19 @@ The configuration file format set by the @option{--syntax} option remains in effect for all @option{--config-file} options that follow it, up to the end of the command line or the next occurrence of the @option{--syntax} option. This means that you can instruct @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 configuration file format. You can receive a concise summary of all configuration directives any time by running @command{pies --config-help}. The use of inetd configuration files is @@ -318,16 +317,17 @@ if no errors were detected, and with status 78 otherwise. configuration without actually parsing it, use @option{-E} command 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:: @end menu @node Syntax @@ -352,16 +352,16 @@ keywords and values. @cindex single-line comments @dfn{Comments} may appear anywhere where white space may appear in the configuration file. There are two kinds of comments: single-line and multi-line comments. @dfn{Single-line} comments start with @samp{#} or @samp{//} and continue to the end of the line: -@smallexample +@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}, @samp{#line}, @samp{# @var{num}} (where @var{num} is a decimal number). These are described in detail in @ref{Preprocessor}. @@ -381,17 +381,17 @@ occurrence of @samp{*/} (star, slash). A @dfn{simple statement} consists of a keyword and value separated by any amount of whitespace. The statement is terminated 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{-}). Examples of keywords are: @samp{group}, @samp{control-file}. A @dfn{value} can be one of the following: @@ -439,95 +439,95 @@ with a single character according to the following rules: In addition, any occurrence of @samp{\} immediately followed by 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. Two or more adjacent quoted strings are concatenated, which gives another way to split long strings over several lines to improve readability. The following fragment produces the same result as 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 @cindex here-document @dfn{Here-document} is a special construct that allows to introduce strings of text containing embedded newlines. The @code{<<@var{word}} construct instructs the parser to read all the following lines up to the line containing only @var{word}, with possible trailing blanks. Any lines thus read are concatenated together into a single string. For example: -@smallexample +@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 (e.g.@: @samp{<<\EOT}) or enclosed in double-quotes, in which case the text is read as is, without interpretation of escape sequences. If @var{word} is prefixed with @code{-} (a dash), then all leading tab characters are stripped from input lines and the line containing @var{word}. Furthermore, if @code{-} is followed by a single space, all leading whitespace is stripped from them. This allows to indent here-documents in a natural fashion. For example: -@smallexample +@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 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 A @dfn{list} is a comma-separated list of values. Lists are delimited by parentheses. The following example shows a statement whose value is a list of strings: -@smallexample +@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 single member. This means that, e.g.@: @samp{dependents auth;} is equivalent to @samp{dependents (auth);}. @@ -537,19 +537,19 @@ equivalent to @samp{dependents (auth);}. @cindex block statement A @dfn{block statement} introduces a logical group of another statements. It consists of a keyword, followed by an optional value, and a sequence of statements enclosed in curly braces, as shown in the example below: -@smallexample +@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. @node Preprocessor @subsection Using Preprocessor to Improve the Configuration. @@ -681,17 +681,17 @@ compatibility with the @sc{c} preprocessor. @kwindex component @deffn {Config} component 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 the same tags are merged into a single declaration. The following are the basic statements which are allowed within the @@ -957,15 +957,15 @@ utility: @item P @tab process priority -20..20 (negative = high priority) @end multitable @end float 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 in version @value{VERSION}. @end deffn @@ -1002,15 +1002,15 @@ Retain variable @var{name} and append @var{value} to its existing value. If no such variable is present in the environment, it is created and @var{value} is assigned to it. However, if @var{value} 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 assigned to it. @item @var{name}=+@var{value} @@ -1058,17 +1058,17 @@ to become available (@pxref{Meta1-Style Components}). Default is component terminates is to restart it. Unless the component terminates with 0 exit code, a corresponding error message is issued 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. Exit codes can be specified either as decimal numbers or as symbolic code names from the table below: @@ -1178,29 +1178,29 @@ The type of redirection is specified by @var{type} argument: @table @asis @item file 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 @var{channel} argument. Allowed values are: @samp{emerg}, @samp{alert}, @samp{crit}, @samp{err}, @samp{warning}, @samp{notice}, @samp{info}, @samp{debug}. The facility is inherited from the @code{syslog} statement (@pxref{syslog}), or from the @code{facility} statement (see below), if given. Example: -@smallexample +@example stderr syslog err; -@end smallexample +@end example @end table @end deffn @deffn {Config: component} facility @var{syslog-facility} Specify the syslog facility to use in syslog redirectors. Allowed @var{syslog-facility} values are: @samp{user}, @samp{daemon}, @@ -1252,16 +1252,16 @@ Socket file mode (octal number between @samp{0} and @samp{777}). Umask to use when creating the socket (octal number between @samp{0} and @samp{777}). @end table 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 (@pxref{Actions Before Startup, chdir}). @ignore @@ -1379,27 +1379,27 @@ Set the built-in service name. Its argument is one of the keywords listed in the above table. @end deffn 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"; service 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 name. @anchor{qotd} @@ -1443,19 +1443,19 @@ Otherwise, it closes the connection. @samp{help} is always defined; it outputs a list of all the 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 following statements: @deffn {Config: component} service @var{name} @@ -1485,20 +1485,20 @@ Simple service. Before starting it, @command{pies} will send the @deffn {Config: component} command @var{command-line} The command line for handling this service. @end deffn 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 following order. First, the global @acronym{ACL} is checked. If it rejects the connection, no further checks are done. Then, if the master TCPMUX service has an @acronym{ACL}, that @acronym{ACL} @@ -1560,24 +1560,24 @@ start an @samp{inet-style} component without a communication socket. A common use of @code{return-code} statement is to invoke an external program upon the termination of a component. For example, 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"; @} mode inetd; socket "inet://0.0.0.0:21"; umask 027; 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. @node Meta1-Style Components @subsection Meta1-Style Components @cindex meta1-style components @@ -1599,13 +1599,13 @@ upon its startup. @node Component Syntax Summary @subsection Component Syntax Summary 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}. mode @samp{exec | wait | accept | inetd | nostartaccept | pass-fd | pass}; # @r{Full name of the program.} @@ -1741,13 +1741,13 @@ component @var{tag} @{ # @r{Notification message text (with headers).} message @var{string}; # @r{Execute this command.} exec @var{command} @} @} -@end smallexample +@end example @node Notification @section Notification @cindex Notification Pies provides a @dfn{notification} mechanism, which can be used to @@ -1758,50 +1758,50 @@ configured by @samp{notify} and @samp{message} statements in a @samp{return-code} block. @deffn {Config: return-code} notify @var{email-string} 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} Supply the email message text to be sent. @var{String} must be a valid RFC 822 message, i.e. it must begin with message headers, followed by an empty line and the actual message body. The message may contain variable data in the form of 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 the message, each occurrence of this construct is removed from the text and replaced by the actual value of the referenced variable. For example, the variables @samp{component} and @samp{retcode} expand 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: @float Table, notification-variables @caption{Notification Variables} @multitable @columnfractions 0.5 0.5 @@ -1820,30 +1820,30 @@ on signal), in decimal. The @samp{termination} variable is set so as to facilitate its use 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 be properly internationalized. This will be fixed in the future 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 @cindex @command{sendmail} Notification messages are sent using an external program, called @dfn{mailer}. By default it is @command{/usr/sbin/sendmail}. You can @@ -1859,23 +1859,23 @@ following requirements: recipient addresses. @end enumerate 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 in the @samp{notify} statement. The mailer command may be altered using @samp{mailer-command-line} statement: @@ -1887,15 +1887,15 @@ the full name of the binary which will be executed, while the first word from the @samp{mailer-command-line} argument gives the string it 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 @section Access Control Lists @cindex @acronym{ACL} @cindex access control lists @@ -1903,17 +1903,17 @@ mailer-command-line "sendmail -f root@@domain.com -oi -t"; permissions that control access to @samp{inetd}, @samp{accept} and @samp{meta1}-style components. 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 @samp{component} block. If both are present, the global-level @acronym{ACL} is consulted first, and if it allows access, the component @acronym{ACL} is consulted. As a result, access is @@ -1921,17 +1921,17 @@ granted only if both lists allow it. A @dfn{named @acronym{ACL}} is an access control list which is 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 referenced from another @acronym{ACL} (either global or a per-component one, or any named @acronym{ACL}, referenced from these). @xref{acl-ref, ACL references}, below. @@ -1964,15 +1964,15 @@ of them must be present. The @var{user-group} part is reserved for future use and is described in more detail in @ref{User-Group ACLs}. @anchor{acl-ref} 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 @samp{defacl} statement. The @var{host-list} group allows to match client addresses. @@ -2008,15 +2008,15 @@ The special form @samp{allow any} means to allow access unconditionally. Similarly, @samp{deny any}, denies access unconditionally. Normally, one of these forms appears as the last 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. When an @acronym{ACL} is checked, its entries are tried in turn until one of them matches, or the end of the list is reached. If a matched @@ -2028,21 +2028,25 @@ the result is @samp{allow}, unless explicitly specified otherwise For example, the following @acronym{ACL} allows access for anybody coming from networks @samp{192.168.10.0/24} and @samp{192.168.100.0/24}, 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); allow acl "my-nets"; deny all; @} @end group -@end smallexample +@end example + +@node control +@section The Control Statement +@WRITEME @node inetd @section Using @command{inetd} Configuration Files @cindex inetd.conf @flindex /etc/inetd.conf In addition to its native configuration file format, GNU @@ -2060,44 +2064,44 @@ as @command{inetd}-style configuration files. The components read from @var{file} are appended to the @command{pies} 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}: @table @option @xopindex{inetd, described} @@ -2113,15 +2117,15 @@ is configured with the @option{--enable-inetd} option. The wrapper is then installed in @var{sbindir} as @file{inetd}, possibly replacing 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: @table @option @item -d Increase debug level. @@ -2178,17 +2182,17 @@ To ensure compatibility with MeTA1, the components read from its configuration file are started in the reverse order (i.e. from last to 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 latter is @file{/var/spool/meta1} by default. It can be changed using the following statement: @@ -2199,20 +2203,20 @@ Set name of MeTA1 queue directory. To override any default settings for a MeTA1 component, add a @code{command} section with the desired settings after including @file{meta1.conf}. For example, here is how to redirect the 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 @cindex Global Configuration The statements described in this section affect @command{pies} behavior as a whole. @@ -2352,15 +2356,15 @@ Debug the lexical analyzer of MeTA1 configuration file. @anchor{source-info} @deffn {Config} source-info @var{bool} This statement decides whether debugging messages should contain source information. To enable source information, use: -@smallexample +@example source-info yes; -@end smallexample +@end example This feature is designed for @command{pies} developers. @end deffn @node Piesctl @chapter Communicating with Running @command{pies} Instances @@ -2754,30 +2758,30 @@ configuration files. The example below runs @command{pmult} (@pxref{pmult, Pmilter multiplexer program,, mailfromd, Mailfromd Manual}) utility with 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; facility mail; stderr syslog err; stdout syslog info; @} -@end smallexample +@end example @node Hairy Pies @section Using Pies to Run Pmult and MeTA1 The example below is a working configuration file for running @command{pmult} and all components of MeTA1, configured in @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 # incorrectly used or misconfigured. return-code (EX_USAGE, EX_CONFIG) @{ action disable; @@ -2804,22 +2808,22 @@ component pmult @{ user meta1s; stderr syslog err; stdout syslog info; @} include-meta1 "/etc/meta1/meta1.conf"; -@end smallexample +@end example @node Inetd Pies @section Running Pies as Inetd 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; deny from any; @} @@ -2836,21 +2840,21 @@ component ftp @{ component pop3d @{ mode inetd; socket "inet://0.0.0.0:110"; 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 umask. @node Command Line Usage @@ -2880,27 +2884,27 @@ use @var{name} as the base name for state files (i.e., they become messages with @var{name}. @end table 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 the third one reads it from @file{/etc/mta.conf}. @anchor{pies-status} 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 pmult/stderr R 4677 pmult/stdout R 4676 pmult CR 4678 /usr/local/sbin/pmult @@ -2910,13 +2914,13 @@ smtpc CR 4696 smtpc -f /etc/meta1/meta1.conf smtps PR 4698 smtps -d100 -f /etc/meta1/meta1.conf finger IL inet+tcp://0.0.0.0:finger /usr/sbin/in.fingerd -u 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}, describing the type and status of the component. The first flag describes the type: @@ -2966,35 +2970,35 @@ listed in the next column. @anchor{pies-restart} @xopindex{restart-component, described} 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} @xopindex{dump-depmap option, introduced} Two options are provided for verifying inter-component dependencies. The @option{--dump-depmap} option prints on the standard output the @dfn{dependency map}. This map is a square matrix 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: 0 1 2 3 4 0 1 @@ -3006,32 +3010,66 @@ Legend: 0: pmult 1: smar 2: qmgr 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 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 This section summarizes @command{pies} command line options. @@ -3061,15 +3099,21 @@ Set debug verbosity level. @xref{Pies Debugging}, for a description of @var{level}. @opsummary{dump-depmap} @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}. @opsummary{force} @item --force @@ -660,19 +660,25 @@ component_verify (struct component *comp, grecs_locus_t *locus) else if (comp->flags & CF_WAIT) { /* TRANSLATORS: `wait' is a keywords, do not translate. */ |