summaryrefslogtreecommitdiffabout
path: root/doc
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-11 11:31:58 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2009-12-11 11:31:58 (GMT)
commit4d759daeec0abf98294ece5a689c608890ffb4d1 (patch) (side-by-side diff)
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') (more/less context) (ignore whitespace changes)
-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
@@ -107,7 +107,7 @@ Servers using stream sockets generally are multi-threaded and use the
accepted by @command{pies}, and the server is given only the
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.:
@samp{nowait.15}.
@@ -187,14 +187,13 @@ causes any previous default address specifier to be forgotten.
An example of @file{inetd.conf} file with various services follows:
-@example
+@smallexample
ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l
ntalk dgram udp wait root /usr/libexec/ntalkd ntalkd
tcpmux stream tcp nowait root internal
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
@@ -85,7 +85,7 @@ documents @command{pies} Version @value{VERSION}.
* Dependencies::
* Pies Configuration File::
* Pies Debugging::
-* Configuration Example::
+* Configuration Examples::
* Command Line Usage::
* Invocation::
* Reporting Bugs::
@@ -106,8 +106,8 @@ Pies Configuration File
* Component Statement::
* Notification:: Mail Notification
* ACL:: Access Control Lists
-* inetd::
-* include-meta1::
+* inetd:: Using @command{inetd} Configuration Files
+* include-meta1:: Using @command{meta1} Configuration Files
* Global Configuration::
* Pies Privileges::
* State Files::
@@ -132,11 +132,12 @@ Component Statement
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
* Simple Pies::
* Hairy Pies::
@@ -164,7 +165,7 @@ redirected to a file or to an arbitrary @command{syslog} channel.
@anchor{init-style}
@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
@command{init} process manager. @command{Pies} is also able to handle
components that receive input on their @samp{stdin} and send reply to
@@ -185,11 +186,12 @@ the @command{inetd} utility.
@anchor{meta1-style}
@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
two. For each meta1-style component @command{pies} opens a socket
after start-up, and starts the component binary. Once the component
@@ -209,10 +211,12 @@ simultaneously.
Components are started in the order of their appearance in the
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}).
@node Dependencies
@chapter Inter-Component Dependencies
@@ -228,7 +232,7 @@ startup. Components @samp{B} and @samp{C} are called
Before restarting any component, @command{pies} verifies if it is a
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
configuration file.
@@ -242,9 +246,9 @@ or more @dfn{configuration files}. The default configuration file
is named @file{pies.conf} and is located in the @dfn{system
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.
Alternative configuration files may be specified using @option{--config-file}
(@option{-c} command line option), e.g.:
@@ -279,8 +283,11 @@ pies /etc/pies.conf \
@end group
@end smallexample
+@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
is described in @ref{include-meta1}
@@ -300,18 +307,13 @@ if no errors were detected, and with status 78 otherwise.
configuration without actually parsing it, use @option{-E} command
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
* Syntax:: Configuration File Syntax
* Component Statement::
* Notification:: Mail Notification
* ACL:: Access Control Lists
-* inetd::
-* include-meta1::
+* inetd:: Using @command{inetd} Configuration Files
+* include-meta1:: Using @command{meta1} Configuration Files
* Global Configuration::
* Pies Privileges::
* State Files::
@@ -361,9 +363,8 @@ occurrence of @samp{*/} (star, slash).
@cindex statement, simple
@cindex simple statements
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{;}).
Examples of simple statements are:
@@ -573,7 +574,7 @@ symbols may be undefined using the following command line options:
@cindex @option{-D}
@item --define=@var{sym}[=@var{value}]
@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.
@xopindex{undefine, described}
@@ -598,7 +599,8 @@ component @var{tag} @{
@end smallexample
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.
The following are the basic statements which are allowed within the
@code{component} block:
@@ -732,7 +734,7 @@ component tags.
@node Component Privileges
@subsection Component Privileges
@cindex privileges
- The following statements control the privileges the component
+ The following statements control privileges the component
is executed with.
@deffn {Config: component} user @var{user-name}
@@ -850,7 +852,7 @@ component.
@node Actions Before Startup
@subsection Actions Before Startup
- Several statements are available that specify actions to perform
+ The statements described in this subsection specify actions to perform
immediately before starting the component:
@deffn {Config: component} chdir @var{dir}
@@ -874,7 +876,7 @@ to become available (@pxref{Meta1-Style Components}). Default is
@node Exit Actions
@subsection Exit Actions
@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
terminates with 0 exit code, a corresponding error message is issued
to the log file. This behavior can be modified using
@@ -1007,7 +1009,7 @@ stderr file /var/log/component/name.err;
@item syslog
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},
@samp{info}, @samp{debug}. The facility is inherited from the
@code{syslog} statement (@pxref{syslog}), or from the @code{facility}
@@ -1032,7 +1034,8 @@ through @samp{local7} (all names case-insensitive), or a facility number.
@subsection Inetd-Style Components
@cindex inetd-style components
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:
@anchor{inetd-socket}
@deffn {Config: component} socket @var{url}
@@ -1075,14 +1078,22 @@ and @samp{777}).
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
Specifies a @acronym{UNIX} socket file name. It is a shortcut for
@samp{unix:@var{file-name}}. You may use a relative file name,
provided that @code{chdir} statement is used for this component
(@pxref{Actions Before Startup, chdir}).
+@end ignore
+
@end table
@end deffn
@@ -1110,9 +1121,10 @@ opened connections.
@end deffn
@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
@node builtin
@@ -1154,10 +1166,10 @@ TCP Port Service Multiplexer. Defined in @RFC{1078}.
@cindex @code{internal} flag
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:
@deffn {Config: component} service @var{name}
Set the built-in service name. Its argument is one of the keywords
@@ -1334,6 +1346,35 @@ the @samp{resolve} flag is set (@pxref{flags,resolve}).
The variables whose names begin with @env{REMOTE} are defined only
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
@subsection Meta1-Style Components
@cindex meta1-style components
@@ -1355,8 +1396,8 @@ upon its startup.
@node Component Syntax Summary
@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.
@smallexample
component @var{tag} @{
@@ -1416,7 +1457,7 @@ component @var{tag} @{
max-rate @var{number};
# @r{ACL for this component.}
- # @xref{ACL Statement, ACL Statement,, mailutils, GNU Mailutils Manual}.
+ # @xref{ACL}.
acl @{ @dots{} @}
# @r{Override default syslog facility for this component.}
@@ -1482,19 +1523,16 @@ component @var{tag} @{
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
+configured by @samp{notify} and @samp{message} statements
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.:
@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}
@@ -1540,6 +1578,7 @@ The table below lists all available variables and their expansions:
@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 instance @tab Instance name (@pxref{instances}).
@item version @tab Package version (@value{VERSION}).
@item component @tab Name of the terminated component.
@item termination @tab Termination cause (see below).
@@ -1718,7 +1757,7 @@ 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}
+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,
@var{addr}, is as described above.
@@ -1758,7 +1797,7 @@ the result is @samp{allow}, unless explicitly specified otherwise
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
+(which is defined elsewhere in the configuration file). Access is
denied for anybody else:
@smallexample
@@ -1784,7 +1823,7 @@ way to use such configuration files is by including them to your main
@deffn {Config} include-inetd @var{file}
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.
The components read from @var{file} are appended to the @command{pies}
@@ -1883,11 +1922,11 @@ given to @command{inetd} after the @samp{--} separator.
@flindex /etc/meta1/meta1.conf
MeTA1 is a mail transfer agent of new generation, designed
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
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:
@deffn {Config} include-meta1 @var{file}
@@ -1907,7 +1946,6 @@ control the mail flow.
To ensure compatibility with MeTA1, the components read from its
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.
The following @command{pies} statements are silently applied to
all MeTA1 components:
@@ -2002,13 +2040,13 @@ Retain the supplementary groups, specified in @var{group-list}.
@end deffn
@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
An example of such implementation is using @command{pies} to
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}.
@node State Files
@section State Files
@@ -2100,8 +2138,8 @@ source-info yes;
This feature is designed for @command{pies} developers.
@end deffn
-@node Configuration Example
-@chapter Configuration Example
+@node Configuration Examples
+@chapter Configuration Examples
In this section we provide several examples of working @command{pies}
configuration files.
@@ -2172,7 +2210,7 @@ include-meta1 "/etc/meta1/meta1.conf";
@end smallexample
@node Inetd Pies
-@section Running Pies Instead of Inetd
+@section Running Pies as Inetd
This configuration file allows to run @command{pies} instead of
@command{initd}. It starts two services: @samp{ftp} and @samp{pop3d},
@@ -2212,7 +2250,8 @@ pop3 stream tcp nowait root /usr/sbin/pop3d pop3d --inetd
@end smallexample
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.
@node Command Line Usage
@chapter Command Line Usage
@@ -2269,6 +2308,10 @@ smar CR 4680 smar -f /etc/meta1/meta1.conf -d 100
qmgr CR 4691 qmgr -f /etc/meta1/meta1.conf
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
@end smallexample
@@ -2279,12 +2322,12 @@ describes the type:
@multitable @columnfractions 0.2 0.7
@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
@item P @tab Pass-style component
@item R @tab Output redirector
-@item E @tab Command being executed
@end multitable
The second flag is meaningful only for components, i.e. if the first
@@ -2292,15 +2335,15 @@ flag is one of @samp{CAIP}. Its values are:
@multitable @columnfractions 0.2 0.7
@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
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.
If the component is sleeping, the time of its scheduled wake-up is
@@ -2395,7 +2438,7 @@ Show configuration file summary. @xref{Pies Configuration File}.
@opsummary{define}
@item --define=@var{sym}[=@var{value}]
@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}.
@opsummary{debug}
@@ -2473,7 +2516,7 @@ Native @command{pies} configuration. @xref{Pies Configuration File}.
@samp{Inetd}-style configuration files. @xref{inetd.conf}.
@item meta1
-@samp{meta1}-style configuration files. @FIXME-xref{meta1}.
+@samp{meta1}-style configuration files. @xref{include-meta1}.
@end table
@xref{config syntax}, for a detailed description of this option.

Return to:

Send suggestions and report system problems to the System administrator.