diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-11 13:31:58 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-11 13:31:58 +0200 |
commit | 4d759daeec0abf98294ece5a689c608890ffb4d1 (patch) | |
tree | 7287200a195bf1bc6169d66c97c6b6211cf26ad1 /doc | |
parent | 9cfa003658ff1df27284e409cbeda705496a808a (diff) | |
download | pies-4d759daeec0abf98294ece5a689c608890ffb4d1.tar.gz pies-4d759daeec0abf98294ece5a689c608890ffb4d1.tar.bz2 |
Finish the docs.
* doc/inetd.texi: Update.
* doc/pies.texi: Update.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/inetd.texi | 7 | ||||
-rw-r--r-- | doc/pies.texi | 183 |
2 files changed, 116 insertions, 74 deletions
diff --git a/doc/inetd.texi b/doc/inetd.texi index a1c5f8a..c7c8bbb 100644 --- a/doc/inetd.texi +++ b/doc/inetd.texi @@ -109,3 +109,3 @@ newly-accepted socket connected to a client of the service. Most stream-based services and all TCPMUX services operate in this manner. -For such services, the invocation rate may be limitied by specifying +For such services, the invocation rate may be limited by specifying optional @samp{max-rate} suffix (a decimal number), e.g.: @@ -189,3 +189,3 @@ An example of @file{inetd.conf} file with various services follows: -@example +@smallexample ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l @@ -195,4 +195,3 @@ tcpmux/+scp-to stream tcp nowait guest /usr/sbin/in.wydawca wydawca tcpmux/docref stream tcp nowait guest /usr/bin/docref docref -@end example - +@end smallexample diff --git a/doc/pies.texi b/doc/pies.texi index db438c6..04c85a4 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -87,3 +87,3 @@ documents @command{pies} Version @value{VERSION}. * Pies Debugging:: -* Configuration Example:: +* Configuration Examples:: * Command Line Usage:: @@ -108,4 +108,4 @@ Pies Configuration File * ACL:: Access Control Lists -* inetd:: -* include-meta1:: +* inetd:: Using @command{inetd} Configuration Files +* include-meta1:: Using @command{meta1} Configuration Files * Global Configuration:: @@ -134,7 +134,8 @@ Inetd-Style Components -* builtin:: Built-in Inetd Services -* TCPMUX:: TCPMUX Services -* sockenv:: Socket Environment Variables +* builtin:: Built-in Inetd Services +* TCPMUX:: TCPMUX Services +* sockenv:: Socket Environment Variables +* inetd exit:: Exit Actions in Inetd Components -Configuration Example +Configuration Examples @@ -166,3 +167,3 @@ redirected to a file or to an arbitrary @command{syslog} channel. @cindex init-style components - This way of operation applies to the @dfn{init-style} + This way of operation applies to @dfn{init-style} components, called so because of the similarity with the @@ -187,7 +188,8 @@ the @command{inetd} utility. @cindex meta1-style components +@cindex pass-style components @cindex smtps Yet another type of components supported by @command{pies} are -@dfn{meta1-style} components. As its name suggests, this type is -designed expressly as a support for MeTA1@footnote{See -@uref{http://www.meta1.org}} components, namely +@dfn{pass-style} or @dfn{meta1-style} components. As the name +suggests, this type is designed expressly as a support for +MeTA1@footnote{See @uref{http://www.meta1.org}} components, namely @command{smtps}. This type can be regarded as a mixture of the above @@ -211,6 +213,8 @@ simultaneously. configuration file and terminated in reverse order. The same -ordering applies when starting or stopping a component dependencies, +ordering applies when starting or stopping component dependencies, As an exception, this order is reversed for the components read from -files included by @code{include-meta1} statement (@pxref{include-meta1}). +MeTA1 configuration files, either included by @code{include-meta1} +statement (@pxref{include-meta1}) or expressly supplied in the command +line (@pxref{config syntax}). @@ -230,3 +234,3 @@ startup. Components @samp{B} and @samp{C} are called prerequisite for any other components. If so, it first terminates its -dependencies, then restarts the component, and then starts its +dependencies, restarts the component, and then starts its dependencies again, in the order of their appearance in the @@ -244,5 +248,5 @@ configuration directory} (in most cases @file{/etc} or @file{/usr/local/etc}, depending on how the package was compiled). -This file uses the @dfn{native Pies configuration syntax}. The -program also understands configuration files in @dfn{inetd} and -@dfn{meta1} formats. +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. @@ -281,4 +285,7 @@ pies /etc/pies.conf \ +@xopindex{config-help, introduced} The rest of this chapter concerns the @command{pies} native -configuration file format. The use of inetd configuration files is +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 covered in @ref{inetd} and the use of meta1 configuration files @@ -302,7 +309,2 @@ line option. -@xopindex{config-help, introduced} - The rest of this section describes the configuration file syntax in -detail. You can receive a concise summary of all configuration -directives any time by running @command{pies --config-help}. - @menu @@ -312,4 +314,4 @@ directives any time by running @command{pies --config-help}. * ACL:: Access Control Lists -* inetd:: -* include-meta1:: +* inetd:: Using @command{inetd} Configuration Files +* include-meta1:: Using @command{meta1} Configuration Files * Global Configuration:: @@ -363,5 +365,4 @@ occurrence of @samp{*/} (star, slash). A @dfn{simple statement} consists of a keyword and value -separated by any amount of whitespace. The simple statement is terminated -with a semicolon (@samp{;}), unless it contains a @dfn{here-document} -(see below), in which case the semicolon is optional. +separated by any amount of whitespace. The statement is terminated +with a semicolon (@samp{;}). @@ -575,3 +576,3 @@ symbols may be undefined using the following command line options: @itemx -D @var{symbol}[=@var{value}] -Define symbol @var{sym} as having @var{value}, or emtpy, if +Define symbol @var{sym} as having @var{value}, or empty, if the @var{value} is not given. @@ -600,3 +601,4 @@ component @var{tag} @{ The component is identified by its @dfn{tag}, which is given as -argument to the @code{component} keyword. +argument to the @code{component} keyword. Component declarations with +the same tags are merged into a single declaration. @@ -734,3 +736,3 @@ component tags. @cindex privileges - The following statements control the privileges the component + The following statements control privileges the component is executed with. @@ -852,3 +854,3 @@ component. - Several statements are available that specify actions to perform + The statements described in this subsection specify actions to perform immediately before starting the component: @@ -876,3 +878,3 @@ to become available (@pxref{Meta1-Style Components}). Default is @kwindex return-code - The default behavior of @command{pies} if an @samp{init-style} + The default behavior of @command{pies} when an @samp{init-style} component terminates is to restart it. Unless the component @@ -1009,3 +1011,3 @@ stderr file /var/log/component/name.err; Redirect to a syslog channel. The syslog priority is given by the -@var{channel} argument. Its allowed values are: @samp{emerg}, +@var{channel} argument. Allowed values are: @samp{emerg}, @samp{alert}, @samp{crit}, @samp{err}, @samp{warning}, @samp{notice}, @@ -1034,3 +1036,4 @@ through @samp{local7} (all names case-insensitive), or a facility number. Inetd-style components are declared using @code{mode inetd} -statement. You must also declare a socket to listen on. +statement. The @samp{component} declaration must contain a +@samp{socket} statement: @@ -1077,5 +1080,11 @@ For example: @smallexample -socket "unix:/var/run/socket;user=nobody;group=mail;mode=770"; +socket + "unix:///var/run/socket;user=nobody;group=mail;mode=770"; @end smallexample +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 @item file name @@ -1085,2 +1094,4 @@ provided that @code{chdir} statement is used for this component (@pxref{Actions Before Startup, chdir}). +@end ignore + @end table @@ -1112,5 +1123,6 @@ opened connections. @menu -* builtin:: Built-in Inetd Services -* TCPMUX:: TCPMUX Services -* sockenv:: Socket Environment Variables +* builtin:: Built-in Inetd Services +* TCPMUX:: TCPMUX Services +* sockenv:: Socket Environment Variables +* inetd exit:: Exit Actions in Inetd Components @end menu @@ -1156,6 +1168,6 @@ TCP Port Service Multiplexer. Defined in @RFC{1078}. A definition of a built-in service component must -have the @code{internal} flag (@pxref{flags}). It may not have +have the @code{internal} flag (@pxref{flags}) set. It may not contain @code{command} or @code{program} statements, as built-in services do -not need external programs. Instead, it must have a @dfn{service} -declaration: +not need external programs. Instead, a @dfn{service} declaration must +be present: @@ -1336,2 +1348,31 @@ for @acronym{TCP} connections. +@node inetd exit +@subsubsection Exit Actions in Inetd Components + + Exit actions (@pxref{Exit Actions}) work for @samp{inet-style} components. +The only difference from @samp{init-style} components is that the +@samp{restart} action is essentially ignored, as it makes no sense to +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 +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 + + This approach may be used to process @command{FTP} uploads in real time. + @node Meta1-Style Components @@ -1357,4 +1398,4 @@ upon its startup. @subsection Component Syntax Summary - This subsection summarizes the @code{component} summary. For each -statement, a reference to its detailed description is supplied. + This subsection summarizes the @code{component} statements. For each +statement, a reference to its detailed description is provided. @@ -1418,3 +1459,3 @@ component @var{tag} @{ # @r{ACL for this component.} - # @xref{ACL Statement, ACL Statement,, mailutils, GNU Mailutils Manual}. + # @xref{ACL}. acl @{ @dots{} @} @@ -1484,3 +1525,3 @@ 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 +configured by @samp{notify} and @samp{message} statements in a @samp{return-code} block. @@ -1488,3 +1529,3 @@ in a @samp{return-code} block. @deffn {Config: return-code} notify @var{email-string} -Send email notification to addresses from @var{email-string}. The +Send email notification to each address from @var{email-string}. The latter is a comma-separated list of email addresses, e.g.: @@ -1494,5 +1535,2 @@ notify "root@@localhost,postmaster@@localhost"; @end smallexample - -Each address may be optionally enclosed in angular brackets (@samp{<} -and @samp{>}). @end deffn @@ -1542,2 +1580,3 @@ The table below lists all available variables and their expansions: @item package @tab Package name (@samp{Pies}). +@item instance @tab Instance name (@pxref{instances}). @item version @tab Package version (@value{VERSION}). @@ -1720,3 +1759,3 @@ first of its @acronym{IP} addresses will be used. Matches if first @var{netlen} bits from the client @acronym{IP} -address equal to @var{addr}. The network mask length, @var{netlen} +address equal to @var{addr}. The network mask length, @var{netlen}, must be an integer number in the range from 0 to 32. The address part, @@ -1760,3 +1799,3 @@ 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 +(which is defined elsewhere in the configuration file). Access is denied for anybody else: @@ -1786,3 +1825,3 @@ Read components from @command{inetd}-style configuration file @var{file}. The argument may also be a directory, in which case -all regular files from that directory will be read and parsed +all regular files from that directory are read and parsed as @command{inetd}-style configuration files. @@ -1885,3 +1924,3 @@ given to @command{inetd} after the @samp{--} separator. to replace Sendmail in the future (@uref{http://www.meta1.org}). -It has a modular structure, each module being an independent +It has a modular structure, each module being a component responsible for a particular task. The components are configured in @@ -1889,3 +1928,3 @@ the MeTA1 configuration file @file{/etc/meta1/meta1.conf}. - @command{Pies} is able to take a list of components directly + @command{Pies} can take a list of components directly from MeTA1 configuration file: @@ -1909,3 +1948,2 @@ 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}. -Of course, this does not affect normal @command{pies} components. @@ -2004,4 +2042,4 @@ Retain the supplementary groups, specified in @var{group-list}. @deffn {Config} allgroups @var{bool} -Retain all supplementary groups of which user, given with -@command{user} statement, is a member. +Retain all supplementary groups the user (as given with +@command{user} statement) is a member of. @end deffn @@ -2010,3 +2048,3 @@ Retain all supplementary groups of which user, given with start @command{jabberd} components: -@uref{http://www.gnu.org.ua/software/pies/example.php?what=jabberd2}. +@uref{http://www.gnu.org.ua/@/software/@/pies/@/example.php?what=jabberd2}. @@ -2102,4 +2140,4 @@ This feature is designed for @command{pies} developers. -@node Configuration Example -@chapter Configuration Example +@node Configuration Examples +@chapter Configuration Examples In this section we provide several examples of working @command{pies} @@ -2174,3 +2212,3 @@ include-meta1 "/etc/meta1/meta1.conf"; @node Inetd Pies -@section Running Pies Instead of Inetd +@section Running Pies as Inetd @@ -2214,3 +2252,4 @@ pop3 stream tcp nowait root /usr/sbin/pop3d pop3d --inetd This configuration is ``almost'' equivalent, because the -@command{inetd} has no way of specifying ACLs and setting the umask. +@command{inetd} format has no way of specifying ACLs and setting the +umask. @@ -2271,2 +2310,6 @@ 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 @@ -2281,4 +2324,5 @@ describes the type: @headitem Flag @tab Meaning -@item C @tab Init-style component @item A @tab Accept-style component +@item C @tab Init-style component +@item E @tab Command being executed @item I @tab Inetd-style component @@ -2286,3 +2330,2 @@ describes the type: @item R @tab Output redirector -@item E @tab Command being executed @end multitable @@ -2294,7 +2337,7 @@ flag is one of @samp{CAIP}. Its values are: @headitem Flag @tab Meaning -@item R @tab Running component @item D @tab Disabled component @item L @tab Inetd listener -@item s @tab Component is sleeping +@item R @tab Running component @item S @tab Component is stopping +@item s @tab Component is sleeping @end multitable @@ -2302,3 +2345,3 @@ flag is one of @samp{CAIP}. Its values are: The next column lists the PID (for running components) or socket address -(for internet listeners), or the string @samp{N/A} if neither of the +(for Internet listeners), or the string @samp{N/A} if neither of the above applies. @@ -2397,3 +2440,3 @@ Show configuration file summary. @xref{Pies Configuration File}. @itemx -D @var{symbol}[=@var{value}] -Define symbol @var{sym} as having @var{value}, or emtpy, if +Define symbol @var{sym} as having @var{value}, or empty, if the @var{value} is not given. @xref{Preprocessor}. @@ -2475,3 +2518,3 @@ Native @command{pies} configuration. @xref{Pies Configuration File}. @item meta1 -@samp{meta1}-style configuration files. @FIXME-xref{meta1}. +@samp{meta1}-style configuration files. @xref{include-meta1}. @end table |