From b713e2208519e7cba1c779cbd9387137eb101e5e Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Thu, 15 Oct 2009 16:21:32 +0300 Subject: Various fixes. * README: Fix typo. * doc/usr-acl.texi: New file. * doc/Makefile.am (pies_TEXINFOS): Remove pies.texi, add usr-acl.texi (check-config, check-sub-config): Handle @deffnx * doc/pies.texi: Update. * src/Makefile.am (AM_CPPFLAGS): Remove superfluous defs, use ../gnu/configmake.h instead * src/acl.c (_acl_common_section_parser): Handle tag, depending on the value of `flag' parameter. Avoid coredumping on NULL pacl. (acl_section_parser, defacl_section_parser): Update calls to _acl_common_section_parser. * src/pies.c (STATEDIR): Replace with LOCALSTATEDIR. (GRECS_VALUE_IS_EMPTY): New define (possibly belongs to grecs more than to pies). (assert_grecs_value_type) (return_code_section_parser): Use GRECS_VALUE_IS_EMPTY to check for empty value. (_get_array_arg): Bugfix. (component_keywords, pies_keywords): Add missing docstrings. * src/progman.c (TYPE_RETR): Rename to TYPE_REDIRECTOR. All uses updated. --- doc/Makefile.am | 8 +- doc/pies.texi | 418 ++++++++++++++++++++++++++++++++++++++----------------- doc/usr-acl.texi | 48 +++++++ 3 files changed, 343 insertions(+), 131 deletions(-) create mode 100644 doc/usr-acl.texi (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index fec8df3..bb2ff49 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -18,8 +18,8 @@ info_TEXINFOS=pies.texi pies_TEXINFOS=\ fdl.texi\ macros.texi\ - pies.texi\ - rendition.texi + rendition.texi\ + usr-acl.texi EXTRA_DIST = \ check-docs.sh\ @@ -48,7 +48,7 @@ check-options: check-config: @check-docs.sh 'configuration statements' \ '/pies_keywords\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ - 's/@deffn {Config} *\([^@,]*\).*/\1/p' \ + 's/@deffnx\{0,1\} {Config} *\([^@,]*\).*/\1/p' \ $(top_srcdir)/src/pies.c -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ $(info_TEXINFOS) @@ -58,7 +58,7 @@ check-sub-config: while read ident kw; do \ check-docs.sh "$$ident configuration statements" \ "/$$kw"'\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ - "s/@deffn {Config: *$${ident}}"' *\([^@,]*\).*/\1/p' \ + "s/@deffnx\{0,1\} {Config: *$${ident}}"' *\([^@,]*\).*/\1/p' \ $(top_srcdir)/src/pies.c $(top_srcdir)/src/acl.c -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ $(info_TEXINFOS); \ 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 "