aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-10-15 20:08:54 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2009-10-15 20:08:54 +0300
commit9670b8cada0df307c6ffd9be1b14f5dfd51cc958 (patch)
tree76e1323bace8855ef30a7ae733a37ae456790ce7 /doc
parent289d283fe50f85411e6a9cca9389cd803ed88c95 (diff)
downloadpies-9670b8cada0df307c6ffd9be1b14f5dfd51cc958.tar.gz
pies-9670b8cada0df307c6ffd9be1b14f5dfd51cc958.tar.bz2
Proofread the docs.
* doc/pies.texi: Final cleanup. * doc/usr-acl.texi: Minor fix.
Diffstat (limited to 'doc')
-rw-r--r--doc/pies.texi88
-rw-r--r--doc/usr-acl.texi2
2 files changed, 44 insertions, 46 deletions
diff --git a/doc/pies.texi b/doc/pies.texi
index 8569ab7..f1654c0 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -751,13 +751,13 @@ Remove @var{file-name}. This is useful, for example, to remove stale
component from starting normally.
As of version @value{VERSION} only one @command{remove-file} may be given.
@end deffn
@deffn {Config: component} settle-timeout @var{number}
-Wait @var{number} seconds. This is kind of kludge. Currently it is
+Wait @var{number} of seconds. This is kind of kludge. Currently it is
used for components imported from @file{meta1.conf} file
(@pxref{include-meta1}), where @code{settle-timeout 1} is implied.
This may change in future versions.
@end deffn
@node Exit Actions
@@ -798,13 +798,13 @@ names from the table below:
@item EX_TEMPFAIL @tab 75
@item EX_PROTOCOL @tab 76
@item EX_NOPERM @tab 77
@item EX_CONFIG @tab 78
@end multitable
-Signal codes can be given either as @samp{SIG+@var{n}}, where @var{n}
+Signal numbers can be given either as @samp{SIG+@var{n}}, where @var{n}
is the signal number, or as signal names from the following list:
@samp{SIGHUP}, @samp{SIGINT}, @samp{SIGQUIT}, @samp{SIGILL},
@samp{SIGTRAP}, @samp{SIGABRT}, @samp{SIGIOT}, @samp{SIGBUS},
@samp{SIGFPE}, @samp{SIGKILL}, @samp{SIGUSR1}, @samp{SIGSEGV},
@samp{SIGUSR2}, @samp{SIGPIPE}, @samp{SIGALRM}, @samp{SIGTERM},
@samp{SIGSTKFLT}, @samp{SIGCHLD}, @samp{SIGCONT}, @samp{SIGSTOP},
@@ -812,19 +812,20 @@ is the signal number, or as signal names from the following list:
@samp{SIGXCPU}, @samp{SIGXFSZ}, @samp{SIGVTALRM}, @samp{SIGPROF},
@samp{SIGWINCH}, @samp{SIGPOLL}, @samp{SIGIO}, @samp{SIGPWR},
@samp{SIGSYS}.
If the component exits with an exit code listed in @var{codes}
or is terminated on a signal listed in @var{codes},
-@command{pies} executes actions specified by its substatements.
-They are executed in the order of their appearance below:
+@command{pies} executes actions specified in that @samp{return-code}
+block. The actions are executed in the order of their appearance below:
@deffn {Config: return-code} exec @var{command}
-Execute external command. Prior to execution of @var{command} all
-file descriptors are closed. It inherits the environment from the
-main @command{pies} process with the following additional variables:
+Execute the supplied external command. Prior to execution, all
+file descriptors are closed. The @var{command} inherits the
+environment from the main @command{pies} process with the following
+additional variables:
@table @env
@item PIES_VERSION
The @command{pies} version number (@value{VERSION}).
@item PIES_COMPONENT
@@ -859,16 +860,17 @@ Supply notification message text to use by @code{notify} statement.
@xref{Notification}, for a detailed discussion of this feature.
@end deffn
Any number of @code{return-code} statements are allowed, provided
that their @var{codes} do not intersect.
- Such statements can also be used outside of @code{component} block.
-In this case, they supply global actions, i.e. actions applicable to
-all components. Any @code{return-code} statements appearing within a
-@code{component} block override the global ones.
+ The @code{return-code} statements can also be used outside of
+@code{component} block. In this case, they supply global actions,
+i.e. actions applicable to all components. Any @code{return-code}
+statements appearing within a @code{component} block override the
+global ones.
@node Output Redirectors
@subsection Output Redirectors
@cindex repeater
Output redirectors allow to redirect the standard error and/or standard
output of a component to a file or @command{syslog} facility.
@@ -879,48 +881,47 @@ Redirect standard error (if @code{stderr}) or standard output (if
@code{stdout}) to the given channel.
The type of redirection is specified by @var{type} argument:
@table @asis
@item file
-Redirect to the file. In this case @var{channel} gives the full name of
+Redirect to a file. In this case @var{channel} gives the full name of
the file. For example:
@smallexample
stderr file /var/log/component/name.err;
@end smallexample
@item syslog
-Redirect to the syslog channel. The syslog priority is given by the
+Redirect to a syslog channel. The syslog priority is given by the
@var{channel} argument. Its 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 @code{facility}
+@code{syslog} statement (@pxref{syslog}), or from the @code{facility}
statement (see below), if given.
Example:
@smallexample
stderr syslog err;
@end smallexample
@end table
@end deffn
@deffn {Config: component} facility @var{syslog-facility}
Specify the syslog facility to use in syslog redirectors. Allowed
-values for @var{syslog-facility} are: @samp{user}, @samp{daemon},
+@var{syslog-facility} values are: @samp{user}, @samp{daemon},
@samp{auth}, @samp{authpriv}, @samp{mail}, @samp{cron}, @samp{local0}
through @samp{local7} (all names case-insensitive), or a facility number.
@end deffn
@node Inetd-Style Components
@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 for requests for
-such components:
+statement. You must also declare a socket to listen on.
@anchor{inetd-socket}
@deffn {Config: component} socket @var{url}
Define a socket to listen on. Allowed values for @var{url} are:
@table @asis
@@ -929,14 +930,14 @@ Specifies a @acronym{UNIX} socket file name. You may use a relative
file name, provided that @code{chdir} statement is used for this
component (@pxref{Actions Before Startup, chdir}).
@item local://@var{file}[;@var{args}]
@itemx file://@var{file}[;@var{args}]
@itemx unix://@var{file}[;@var{args}]
-Listen on the @acronym{UNIX} socket file @var{file}, which may be either
-absolute or relative file name, as described above. Optional
+Listen on the @acronym{UNIX} socket file @var{file}, which is either
+an absolute or relative file name, as described above. Optional
arguments @var{args} control ownership and file mode of @var{file}. They
are a list of assignments, separated by semicolons. The following
values are allowed:
@table @asis
@item user
@@ -953,13 +954,13 @@ Umask to use when creating the socket (octal number between @samp{0}
and @samp{777}).
@end table
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
@item inet://@var{ip}:@var{port}
Listen on IPv4 address @var{ip} (may be given as a symbolic host name),
on port @var{port}.
@end table
@@ -1095,16 +1096,16 @@ component @var{tag} @{
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.
+in a @samp{return-code} block.
@deffn {Config: return-code} notify @var{email-string}
-Send an email notification to addresses from @var{email-string}. The
+Send 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
@@ -1187,13 +1188,13 @@ Subject: Component $@{component@} $@{termination@} $@{retcode@}.
@end smallexample
@end deffn
@cindex mailer
@cindex @command{sendmail}
- Notification messages are sent using external program, called
+ Notification messages are sent using an 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:
@@ -1307,24 +1308,24 @@ Deny access to the component.
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:
+@acronym{ACL}. The syntax of this part is:
@smallexample
acl @var{name}
@end smallexample
@noindent
-where @var{name} is the name of @acronym{ACL} defined previously in
+where @var{name} is the name of an @acronym{ACL} defined previously in
@samp{defacl} statement.
The @var{host-list} group allows to match client addresses.
-It consists of a @code{from} keyword followed by a list of
+It consists of the @code{from} keyword followed by a list of
@dfn{address specifiers}. Allowed address specifiers are:
@table @asis
@item @var{addr}
Matches if the client @acronym{IP} equals @var{addr}.
The latter may be given either as an @acronym{IP}
@@ -1345,34 +1346,33 @@ form, e.g. @samp{255.255.255.224}.
@item @var{filename}
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}.
+@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.
+unconditionally. Normally, one of these forms appears as the last
+statement in an @acronym{ACL} definition.
To summarize, the syntax of an access statement is:
@smallexample
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}.
+where square brackets denote optional parts.
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 of the @acronym{ACL} check. If the end of the list is reached,
the result is @samp{allow}, unless explicitly specified otherwise
-(using the @pxref{acl-any, ``any'' form}).
+(using the @ref{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:
@@ -1390,15 +1390,14 @@ acl @{
@node include-meta1
@section Using MeTA1 Configuration File
@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
-program, which is responsible for a particular task. The components
-are configured in the MeTA1 configuration file
-@file{/etc/meta1/meta1.conf}.
+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
from MeTA1 configuration file:
@deffn {Config} include-meta1 @var{file}
Parse @var{file} as MeTA1 configuration file and incorporate
@@ -1428,22 +1427,23 @@ stderr file @var{compname}.log
chdir @var{queue-dir}
@end smallexample
Here, @var{compname} stands for the name of the component, and
@var{queue-dir} stands for the name of MeTA1 queue directory. The
latter is @file{/var/spool/meta1} by default. It can be changed using
-the following statement
+the following statement:
@deffn {Config} meta1-queue-dir @var{dir}
Set name of MeTA1 queue directory.
@end deffn
To override any default settings for a MeTA1 component, add a
@code{command} section with the desired settings after including
-@file{meta1.conf}. For example, here is how to redirect program
-diagnostics to @samp{local1.debug} syslog channel:
+@file{meta1.conf}. For example, here is how to redirect the
+standard error of the @samp{smtps} component to @samp{local1.debug}
+syslog channel:
@smallexample
include-meta1 /etc/meta1/meta1.conf
component smtps @{
facility local1;
@@ -1463,20 +1463,20 @@ This block statement configures logging via syslog. It has two
substatements:
@end deffn
@deffn {Config: syslog} tag @var{string}
Prefix syslog messages with this string. By default, the program name
is used.
+@end deffn
@deffn {Config: syslog} facility @var{string}
Set syslog facility to use. Allowed values are: @samp{user},
@samp{daemon}, @samp{auth}, @samp{authpriv}, @samp{mail}, @samp{cron},
@samp{local0} through @samp{local7} (case-insensitive), or a facility
number.
@end deffn
-@end deffn
@deffn {Config} umask @var{number}
Set the default umask. The @var{number} must be an octal value not greater
than @samp{777}. The default umask is inherited at startup.
@end deffn
@@ -1511,13 +1511,13 @@ useless. Do not use them, unless you have a good knowledge of
The following three statements define file names of various files
needed by @command{pies}. Use them only if the defaults does not
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{localstatedir}/pies.pid},
+default the 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
@@ -1530,19 +1530,18 @@ Set file name of the statistics output file. Default is
@end deffn
Normally, @command{pies} must be run with root privileges. If,
however, you found such an implementation for it, that requires another
privileges, you may change them using the following three statements:
-@command{pies} process.
@deffn {Config} user @var{user-name}
Start @command{pies} with the UID and GID of this user.
@end deffn
@deffn {Config} group @var{group-list}
-Retain supplementary groups, specified in @var{group-list}.
+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.
@end deffn
@@ -1667,26 +1666,25 @@ include-meta1 "/etc/meta1/meta1.conf";
This configuration file allows to run @command{pies} instead of
@command{initd}. It starts two services: @samp{ftp} and @samp{pop3d},
and restricts access to them to two local subnets:
@smallexample
acl @{
- log from any "Connect from $@{address@}";
allow from 10.10.10.0/24;
allow from 192.168.10.0/27;
deny from any;
@}
debug 3;
component ftp @{
mode inetd;
socket "inet://0.0.0.0:21";
umask 027;
program /usr/sbin/ftpd
- command ftpd -l -C;
+ command "ftpd -l -C";
@}
component pop3d @{
mode inetd;
socket "inet://0.0.0.0:110";
program "/usr/sbin/pop3d";
diff --git a/doc/usr-acl.texi b/doc/usr-acl.texi
index 1fd69f5..86d70f1 100644
--- a/doc/usr-acl.texi
+++ b/doc/usr-acl.texi
@@ -24,13 +24,13 @@ Only authenticated users.
Authenticated users which are members of at least one of groups listed in
@var{group-list}.
@end table
For example, the following statement defines an @acronym{ACL}
which allows access for any user connected via local @acronym{UNIX}
-socket @file{/tmp/dicod.sock} or coming from a local network
+socket @file{/tmp/pies.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:

Return to:

Send suggestions and report system problems to the System administrator.