aboutsummaryrefslogtreecommitdiff
path: root/doc/pies.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/pies.texi')
-rw-r--r--doc/pies.texi418
1 files changed, 291 insertions, 127 deletions
diff --git a/doc/pies.texi b/doc/pies.texi
index e1ca650..e47f6a6 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -90,8 +90,46 @@ Appendices
* Concept Index:: Index of Concepts.
@detailmenu
-@end detailmenu
+ --- The Detailed Node Listing ---
+
+Pies Configuration File
+
+* Syntax:: Configuration File Syntax
+* Component Statement::
+* Notification:: Mail Notification
+* ACL:: Access Control Lists
+* include-meta1::
+* Global Configuration::
+
+Configuration File Syntax
+
+* Comments::
+* Statements::
+* Preprocessor:: Using preprocessor to improve the configuration.
+
+Component Statement
+
+* Prerequisites::
+* Component Privileges::
+* Resources::
+* Actions Before Startup::
+* Exit Actions::
+* Output Redirectors::
+* Inetd-Style Components::
+* Meta1-Style Components::
+* Component Syntax Summary::
+
+Global Configuration
+
+* Less Useful Statements::
+
+Configuration Example
+* Simple Pies::
+* Hairy Pies::
+* Inetd Pies::
+
+@end detailmenu
@end menu
@node Intro
@@ -200,7 +238,7 @@ reports them on the standard error and exits with a non-zero status.
@command{pies} to check its configuration file and exit with status 0
if no errors were detected, and with status 1 otherwise.
-@opindex -E, introduced
+@cindex @option{-E}, introduced
Before parsing, configuration file is preprocessed using
@command{m4} (@pxref{Preprocessor}). To see the preprocessed
configuration without actually parsing it, use @option{-E} command
@@ -212,8 +250,9 @@ detail. You can receive a concise summary of all configuration
directives any time by running @command{pies --config-help}.
@menu
-* Syntax:: Configuration file syntax.
+* Syntax:: Configuration File Syntax
* Component Statement::
+* Notification:: Mail Notification
* ACL:: Access Control Lists
* include-meta1::
* Global Configuration::
@@ -438,21 +477,16 @@ this is not required.
@subsection Using Preprocessor to Improve the Configuration.
@cindex preprocessor
@cindex m4
- Before parsing configuration file, @command{pies} preprocesses
-it. The built-in preprocessor handles only file inclusion
-and @code{#line} statements (@FIXME-pxref{Pragmatic Comments}), while the
-rest of traditional preprocessing facilities, such as macro expansion,
-is supported via @command{m4}, which is used as an external preprocessor.
-
- The detailed description of @command{m4} facilities lies far beyond
-the scope of this document. You will find a complete user manual in
+ Before parsing, the configuration file is @dfn{preprocessed} using
+external preprocessor @command{m4}. For a complete user manual, refer
+to
@ifnothtml
@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
@end ifnothtml
@ifhtml
@uref{http://www.gnu.org/software/m4/manual}.
@end ifhtml
-For the rest of this subsection we assume the reader is sufficiently
+In this subsection we assume the reader is sufficiently
acquainted with @command{m4} macro processor.
@flindex pp-setup
@@ -487,7 +521,8 @@ component @var{tag} @{
The component is identified by its @dfn{tag}, which is given as
argument to the @code{component} keyword.
-The following statements are allowed within the @code{component} block:
+Following are the basic statements which are allowed within the
+@code{component} block:
@deffn {Config: component} mode @var{mode}
Declare the type (style) of the component. Accepted values for
@@ -539,7 +574,14 @@ If @var{bool} is @samp{true}, this component is marked as precious.
Precious components are never disabled by @command{pies}, even if they
respawn too fast.
@end deffn
-
+
+@deffn {Config: component} acl @{ ... @}
+Set access control list for this component. @xref{ACL}, for a
+detailed description of access control lists.
+@end deffn
+
+The following subsections describe the rest of @samp{component}
+substatements.
@menu
* Prerequisites::
@@ -724,7 +766,7 @@ 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} return-code
+@deffn {Config: component} return-code
@smallexample
return-code @var{codes} @{
@dots{}
@@ -805,60 +847,13 @@ by the administrator.
@end deffn
@deffn {Config: return-code} notify @var{email-string}
-Send an email notification to addresses in @var{email-string}. The
-latter is a comma-separated list of email addresses, e.g.:
-
-@smallexample
-notify "root@@localhost,postmaster@@localhost";
-@end smallexample
-
-The message itself is configured by the @code{message}
-statement.
+Send an email notification to addresses in @var{email-string}.
+@xref{Notification}, for a detailed discussion of this feature.
@end deffn
@deffn {Config: return-code} message @var{string}
Supply notification message text to use by @code{notify} statement.
-@var{String} must be a valid RFC 822 message text, i.e. it must begin
-with message headers, followed by an empty line and actual message
-body.
-
-The following macro-variables are expanded within @var{string}:
-
-@multitable @columnfractions 0.5 0.5
-@headitem Variable @tab Expansion
-@item canonical-program-name @tab @samp{pies}
-@item program-name @tab Program name of the @command{pies} binary.
-@item package @tab Package name (@samp{Pies}).
-@item version @tab Package version (@value{VERSION}).
-@item component @tab Name of the terminated component.
-@item termination @tab Termination cause (see below).
-@item retcode @tab Component exit code (or signal number, if exited
-on signal), in decimal.
-@end multitable
-
-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
-the component terminated on a signal. Thus, using
-
-@smallexample
-$@{termination@} $@{retcode@}
-@end smallexample
-
-@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
-From: <>
-X-Agent: $@{canonical-program-name@} ($@{package@} $@{version@})
-Subject: Component $@{component@} $@{termination@} $@{retcode@}.
-
-@end smallexample
+@xref{Notification}, for a detailed discussion of this feature.
@end deffn
Any number of @code{return-code} statements are allowed, provided
@@ -876,7 +871,7 @@ all components. Any @code{return-code} statements appearing within a
output of a component to a file or @command{syslog} facility.
@deffn {Config: component} stderr @var{type} @var{channel}
-@deffnx {Config} stdout @var{type} @var{channel}
+@deffnx {Config: component} stdout @var{type} @var{channel}
Redirect standard error (if @code{stderr}) or standard output (if
@code{stdout}) to the given channel.
@@ -1091,6 +1086,157 @@ component @var{tag} @{
@}
@end smallexample
+@node Notification
+@section Notification
+@cindex Notification
+
+ Pies provides a @dfn{notification} mechanism, which can be used to
+send email messages when components terminate. The exact contents
+of such notifications and the list of their recipients may depend on
+the exit code which the component returned. Notification is
+configured by supplying @samp{notify} and @samp{message} statements
+within a @samp{return-code} block.
+
+@deffn {Config: return-code} notify @var{email-string}
+Send an email notification to addresses from @var{email-string}. The
+latter is a comma-separated list of email addresses, e.g.:
+
+@smallexample
+notify "root@@localhost,postmaster@@localhost";
+@end smallexample
+
+Each address may be optionally enclosed in angular brackets (@samp{<}
+and @samp{>}).
+@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
+$@{@var{name}@}
+@end smallexample
+
+@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
+Subject: $@{component@} exited with code $@{retcode@}
+@end smallexample
+
+@noindent
+will become:
+
+@smallexample
+Subject: ftpd exited with code 76
+@end smallexample
+
+The table below lists all available variables and their expansions:
+
+@float Table, notification-variables
+@caption{Notification Variables}
+@multitable @columnfractions 0.5 0.5
+@headitem Variable @tab Expansion
+@item canonical-program-name @tab @samp{pies}
+@item program-name @tab Program name of the @command{pies} binary.
+@item package @tab Package name (@samp{Pies}).
+@item version @tab Package version (@value{VERSION}).
+@item component @tab Name of the terminated component.
+@item termination @tab Termination cause (see below).
+@item retcode @tab Component exit code (or signal number, if exited
+on signal), in decimal.
+@end multitable
+@end float
+
+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
+$@{termination@} $@{retcode@}
+@end smallexample
+
+@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
+From: <>
+X-Agent: $@{canonical-program-name@} ($@{package@} $@{version@})
+Subject: Component $@{component@} $@{termination@} $@{retcode@}.
+
+@end smallexample
+@end deffn
+
+@cindex mailer
+@cindex @command{sendmail}
+ Notification messages are sent using external program, called
+@dfn{mailer}. By default it is @command{/usr/sbin/sendmail}. You can
+change it using the following configuration statement:
+
+@deffn {Config} mailer-program @var{prog}
+Use @var{prog} as a mailer program. The mailer must meet the
+following requirements:
+
+@enumerate 1
+@item It must read the message from its standard input.
+@item It must treat the non-optional arguments in its command line as
+recipient addresses.
+@end enumerate
+
+For example, the following statement instructs @command{pies} to use
+@command{exim} as a mailer:
+
+@smallexample
+mailer-program /usr/sbin/exim;
+@end smallexample
+
+@end deffn
+
+By default, the mailer program is invoked as follows:
+
+@smallexample
+/usr/sbin/sendmail -oi -t @var{rcpts}
+@end smallexample
+
+@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:
+
+@deffn {Config} mailer-command-line @var{string}
+Set mailer command line. Notice, that @var{string} must include the
+command name as well. The @samp{mailer-program} statement supplies
+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
+mailer-command-line "sendmail -f root@@domain.com -oi -t";
+@end smallexample
+@end deffn
+
@node ACL
@section Access Control Lists
@cindex @acronym{ACL}
@@ -1103,49 +1249,63 @@ An @acronym{ACL} is defined using @code{acl} block statement:
@deffn {Config} acl
@smallexample
-acl @var{name} @{
+acl @{
@var{definitions}
@}
@end smallexample
@end deffn
-The @var{name} parameter specifies a unique name for that
-@acronym{ACL}. This name can be used by another configuration
-statements to refer to that @acronym{ACL}.
-
-A part between the curly braces (denoted by @var{definitions} above),
-is a list of @dfn{access statements}. There are two types of
-such statements:
+ 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
+granted only if both lists allow it.
-@deffn {Config: acl} allow @var{user-group} @var{sub-acl} @var{host-list}
-Allow access to resource.
-@end deffn
+ 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: acl} deny @var{user-group} @var{sub-acl} @var{host-list}
-Deny access to resource.
+@deffn {Config} defacl @var{name}
+@smallexample
+defacl @var{name} @{
+ @var{definitions}
+@}
+@end smallexample
+
+ 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.
@end deffn
-All parts of an access statement are optional, but at least one
-of them must be present.
+ In both forms, the part between the curly braces (denoted by
+@var{definitions}), is a list of @dfn{access control statements}.
+There are two types of such statements:
-The @var{user-group} part specifies which users match this entry.
-Allowed values are the following:
-
-@table @code
-@kwindex all
-@item all
-All users.
+@deffn {Config: acl} allow [@var{user-group}] @var{sub-acl} @var{host-list}
+@deffnx {Config: acl} allow any
+Allow access to the component.
+@end deffn
+@ignore
+@deffn {Config: defacl} allow [@var{user-group}] @var{sub-acl} @var{host-list}
+@end deffn
+@end ignore
-@kwindex authenticated
-@item authenticated
-Only authenticated users.
+@deffn {Config: acl} deny [@var{user-group}] @var{sub-acl} @var{host-list}
+@deffnx {Config: acl} deny any
+Deny access to the component.
+@end deffn
+@ignore
+@deffn {Config: defacl} deny [@var{user-group}] @var{sub-acl} @var{host-list}
+@end deffn
+@end ignore
-@kwindex group
-@item group @var{group-list}
-Authenticated users which are members of at least one of groups listed in
-@var{group-list}.
-@end table
+All parts of an access statement are optional, but at least one
+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 group is:
@@ -1154,9 +1314,10 @@ acl @var{name}
@end smallexample
@noindent
-where @var{name} is the name of a previously defined @acronym{ACL}.
+where @var{name} is the name of @acronym{ACL} defined previously in
+@samp{defacl} statement.
-Finally, the @var{host-list} group allows to match client addresses.
+The @var{host-list} group allows to match client addresses.
It consists of a @code{from} keyword followed by a list of
@dfn{address specifiers}. Allowed address specifiers are:
@@ -1167,7 +1328,6 @@ The latter may be given either as an @acronym{IP}
address or as a host name, in which case it will be resolved and the
first of its @acronym{IP} addresses will be used.
-
@item @var{addr}/@var{netlen}
Matches if first @var{netlen} bits from the client @acronym{IP}
address equal to @var{addr}. The network mask length, @var{netlen}
@@ -1185,41 +1345,40 @@ Matches if connection was received from a @acronym{UNIX} socket
@var{filename}, which must be given as an absolute file name.
@end table
+@anchor{acl-any}.
+The special form @samp{allow any} means to allow access
+unconditionally. Similarly, @samp{deny any}, denies access
+unconditionally. Normally, these forms appear as the last
+statements in an @acronym{ACL} definition.
+
To summarize, the syntax of an access statement is:
@smallexample
-allow|deny [all|authenticated|group @var{group-list}]
- [acl @var{name}] [from @var{addr-list}]
+allow|deny [acl @var{name}] [from @var{addr-list}]
@end smallexample
@noindent
where square brackets denote optional parts and vertical bar means
@samp{one of}.
-When an @acronym{ACL} is applied to a particular object, its entries
-are tried in turn until one of them matches, or the end of the list is
-reached. If a matched entry is found, its command verb, @code{allow}
-or @code{deny}, defines the result of @acronym{ACL} match. If the end
-of list is reached, the result is @samp{allow}, unless explicitly
-specified otherwise.
-
-@FIXME{Trim that example:}
-For example, the following statement defines an @acronym{ACL} named
-@samp{common}, that allows access for any user connected via local
-@acronym{UNIX} socket @file{/tmp/dicod.sock} or coming from a local
-network @samp{192.168.10.0/24}. Any authenticated users are allowed,
-provided that they are allowed by another @acronym{ACL} @samp{my-nets}
-(which should have been defined before this definition). Users
-coming from the network @samp{10.10.0.0/24} are allowed if they
-authenticate themselves and are members of groups @samp{pies} or
-@samp{users}. Access is denied for anybody else:
+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
+entry is found, its command verb, @code{allow} or @code{deny}, defines
+the result of @acronym{ACL} match. If the end of list is reached,
+the result is @samp{allow}, unless explicitly specified otherwise
+(using the @pxref{acl-any, ``any'' form}).
+
+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 should have been defined before this definition). Access is
+denied for anybody else:
@smallexample
@group
-acl common @{
- allow all from ("/tmp/pies.sock", "192.168.10.0/24");
- allow authenticated acl "my-nets";
- allow group ("pies", "users") from "10.10.0.0/24";
+acl @{
+ allow from (192.168.10.0/24, 192.168.100.0/24);
+ allow acl "my-nets";
deny all;
@}
@end group
@@ -1352,18 +1511,19 @@ suit your needs:
@deffn {Config} pidfile @var{file}
Write PID of the master @command{pies} process to @var{file}. By
-default, master PID is stored in @file{@var{statedir}/pies.pid}
-(@FIXME-pxref{statedir}).
+default, master PID is stored in @file{@var{localstatedir}/pies.pid},
+where @var{localstatedir} is the @dfn{local state directory}, defined
+at compile time (usually, it is @file{/usr/local/var} or @file{/usr/var}).
@end deffn
@deffn {Config} control-file @var{file}
Set file name of the @command{pies} control file. Default is
-@file{@var{statedir}/pies.ctl}
+@file{@var{localstatedir}/pies.ctl}
@end deffn
@deffn {Config} stat-file @var{file}
Set file name of the statistics output file. Default is
-@file{@var{statedir}/pies.stat}.
+@file{@var{localstatedir}/pies.stat}.
@end deffn
Normally, @command{pies} must be run with root privileges. If,
@@ -1513,7 +1673,7 @@ acl @{
deny from any;
@}
-debug "<trace4";
+debug 3;
component ftp @{
mode inetd;
@@ -1752,6 +1912,10 @@ line options used).
@item Conditions under which the bug appears.
@end itemize
+@node User-Group ACLs
+@appendix User-Group ACLs
+@include usr-acl.texi
+
@node Copying This Manual
@appendix GNU Free Documentation License
@include fdl.texi

Return to:

Send suggestions and report system problems to the System administrator.