aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-11 13:31:58 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-12-11 13:31:58 +0200
commit4d759daeec0abf98294ece5a689c608890ffb4d1 (patch)
tree7287200a195bf1bc6169d66c97c6b6211cf26ad1 /doc
parent9cfa003658ff1df27284e409cbeda705496a808a (diff)
downloadpies-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.texi7
-rw-r--r--doc/pies.texi183
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

Return to:

Send suggestions and report system problems to the System administrator.