diff options
Diffstat (limited to 'doc/pies.texi')
-rw-r--r-- | doc/pies.texi | 418 |
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 @@ -92,4 +92,42 @@ Appendices @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 @@ -202,3 +240,3 @@ if no errors were detected, and with status 1 otherwise. -@opindex -E, introduced +@cindex @option{-E}, introduced Before parsing, configuration file is preprocessed using @@ -214,4 +252,5 @@ 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 @@ -440,10 +479,5 @@ this is not required. @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 @@ -454,3 +488,3 @@ the scope of this document. You will find a complete user manual in @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. @@ -489,3 +523,4 @@ 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: @@ -541,3 +576,10 @@ 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. @@ -726,3 +768,3 @@ to the log file. This behavior can be modified using -@deffn {Config} return-code +@deffn {Config: component} return-code @smallexample @@ -807,11 +849,4 @@ by the administrator. @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 @@ -820,43 +855,3 @@ statement. 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 @@ -878,3 +873,3 @@ 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 @@ -1093,2 +1088,153 @@ component @var{tag} @{ +@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 @@ -1105,3 +1251,3 @@ An @acronym{ACL} is defined using @code{acl} block statement: @smallexample -acl @var{name} @{ +acl @{ @var{definitions} @@ -1111,39 +1257,53 @@ acl @var{name} @{ -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 @@ -1156,5 +1316,6 @@ acl @var{name} @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 @@ -1169,3 +1330,2 @@ first of its @acronym{IP} addresses will be used. - @item @var{addr}/@var{netlen} @@ -1187,2 +1347,8 @@ Matches if connection was received from a @acronym{UNIX} socket +@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: @@ -1190,4 +1356,3 @@ 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 @@ -1198,19 +1363,14 @@ where square brackets denote optional parts and vertical bar means -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: @@ -1218,6 +1378,5 @@ authenticate themselves and are members of groups @samp{pies} or @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; @@ -1354,4 +1513,5 @@ suit your needs: 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 @@ -1360,3 +1520,3 @@ default, master PID is stored in @file{@var{statedir}/pies.pid} Set file name of the @command{pies} control file. Default is -@file{@var{statedir}/pies.ctl} +@file{@var{localstatedir}/pies.ctl} @end deffn @@ -1365,3 +1525,3 @@ Set file name of the @command{pies} control file. Default is Set file name of the statistics output file. Default is -@file{@var{statedir}/pies.stat}. +@file{@var{localstatedir}/pies.stat}. @end deffn @@ -1515,3 +1675,3 @@ acl @{ -debug "<trace4"; +debug 3; @@ -1754,2 +1914,6 @@ line options used). +@node User-Group ACLs +@appendix User-Group ACLs +@include usr-acl.texi + @node Copying This Manual |