diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-05-08 15:48:00 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-05-09 00:02:44 +0300 |
commit | 30775f7ce1215423967c681ab9f3cf0a4704b51e (patch) | |
tree | 55c74e44570a1d698fb00497a9965b8ec4e3a3e4 | |
parent | ae42310eae46e763e207a2204d43dbadf20f8390 (diff) | |
download | mailfromd-30775f7ce1215423967c681ab9f3cf0a4704b51e.tar.gz mailfromd-30775f7ce1215423967c681ab9f3cf0a4704b51e.tar.bz2 |
Fix the docs
-rw-r--r-- | doc/gacopyz.texi | 6 | ||||
-rw-r--r-- | doc/pies.texi | 59 | ||||
-rw-r--r-- | doc/pmult.texi | 30 |
3 files changed, 50 insertions, 45 deletions
diff --git a/doc/gacopyz.texi b/doc/gacopyz.texi index 7354db6c..88348cc6 100644 --- a/doc/gacopyz.texi +++ b/doc/gacopyz.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 2005, 2006 Sergey Poznyakoff +@c Copyright (C) 2005, 2006, 2009 Sergey Poznyakoff @c Permission is granted to copy, distribute and/or modify this document @c under the terms of the GNU Free Documentation License, Version 1.2 or @c any later version published by the Free Software Foundation; with no @@ -35,11 +35,11 @@ new and more flexible @acronym{API}. The old @acronym{API} is supported for compatibility with @command{libmilter}. The library name comes from the song @samp{Rozprawa o robokach} by -@uref{http://gray.gnu.org.ua/grzeskowiak.html, Kazimierz Grzeskowiak}. +@uref{http://grzeskowiak.art.pl, Kazimierz Grzeskowiak}. The phrase @samp{A to nie je mysa, ino gacopyz} exactly describes what the library is: @samp{That is no libmilter, but gacopyz}. - Future versions of this documentation will include the detailed + Future versions of this documentation will include a detailed description of the library. diff --git a/doc/pies.texi b/doc/pies.texi index 599e630d..1d9df839 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -1,5 +1,5 @@ @c This file is part of the Mailfromd manual. -@c Copyright (C) 2008 Sergey Poznyakoff +@c Copyright (C) 2008, 2009 Sergey Poznyakoff @c See file mailfromd.texi for copying conditions. @c ******************************************************************* @cindex component, pies @@ -7,9 +7,9 @@ @samp{Program Invocation and Execution Supervisor}. This utility starts and controls execution of external programs, called @dfn{components}. Each component is a stand-alone program, which is -executed in foreground. Upon startup, @command{pies} reads the list +executed in the foreground. Upon startup, @command{pies} reads the list of components from its configuration file, starts them, and remains in -background, controlling their execution. When any of the components +the background, controlling their execution. When any of the components terminates, @command{pies} restarts it. Its configuration allows to specify actions other than simple restart, depending on the exit code of the component. @@ -48,7 +48,7 @@ components. startup. Instead, @command{pies} opens a socket for each of them and listens for connections on these sockets. When a connection arrives, it decides what component the socket corresponds to, and invokes this -component to service that connection. In this case, the connection is +component to handle that connection. In this case, the connection is bound to component's @samp{stdin} and @samp{stdout} streams. The @samp{stderr} stream can be redirected to a file or to syslog, as described above. This mode of operation is similar to that of @@ -57,7 +57,7 @@ described above. This mode of operation is similar to that of @anchor{meta1-style} @cindex meta1-style components @cindex smtps - Third type of components, supported by @command{pies} are + The third type of components, supported by @command{pies} are @dfn{meta1-style} components. As the name suggests this type is designed expressly as a support for MeTA1 components, namely @command{smtps}. This type can be regarded as a mixture of the above @@ -78,8 +78,8 @@ starts the component, without waiting for an actual connection. simultaneously. Components are started in the order of their appearance in the -configuration file and terminated in reverse order. When starting or -stopping component dependencies, the same order is preserved. +configuration file and terminated in the reverse order. When starting or +stopping component dependencies, the same ordering is preserved. This order is reversed for files included by @code{include-meta1} statement (@pxref{include-meta1}). @@ -136,6 +136,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: + @deffn {Pies Conf} mode @var{mode} Declare the type (style) of the component. Accepted values for @var{mode} are: @@ -230,8 +232,8 @@ component tags. @node Component Privileges @subsection Component Privileges @cindex privileges, pies - Following statements control the privileges with which the component -is executed. + Following statements control the privileges the component +is executed with. @deffn {Pies Conf} user @var{user-name} Start component with the UID and GID of this user. @@ -242,8 +244,8 @@ Retain supplementary groups, specified in @var{group-list}. @end deffn @deffn {Pies Conf} allgroups @var{bool} -Retain all supplementary groups of which user, given with -@command{user} statement, is a member. This is the default for +Retain all supplementary groups of which the user (as given with +@command{user} statement) is a member. This is the default for components specified in @file{meta1.conf} file (@pxref{include-meta1}). @end deffn @@ -406,9 +408,10 @@ are: @deffn {Pies Conf} action @samp{disable | restart} If @samp{restart} is given, restart the component. This is the -default. Otherwise, mark the component and as disabled. Component -dependents are stopped and marked as disabled as well. Disabled -components are never started, unless requested by the administrator. +default. Otherwise, mark the component as disabled. Component +dependents are stopped and marked as disabled as well. Once disabled, +the components are never restarted, unless their restart is requested +by the administrator. @end deffn @deffn {Pies Conf} notify @var{email-string} @@ -460,13 +463,13 @@ 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. The @code{return-code} statements appearing within a +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 standard error and/or standard + Output redirectors allow to redirect the standard error and/or standard output of a component to a file or @command{syslog} facility. @deffn {Pies Conf} stderr @var{type} @var{channel} @@ -478,7 +481,7 @@ The type of redirection is specified by @var{type} argument: @table @asis @item file -Redirect to file. In this case @var{channel} gives the full name of +Redirect to the file. In this case @var{channel} gives the full name of the file. For example: @smallexample @@ -529,7 +532,7 @@ 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 a @acronym{UNIX} socket file @var{file}, which may be either +Listen on the @acronym{UNIX} socket file @var{file}, which may be either 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 @@ -689,7 +692,7 @@ component @var{tag} @{ @node include-meta1 @section Using MeTA1 Configuration File @cindex /etc/meta1/meta1.conf - @command{Pies} is able to take list of components from MeTA1 + @command{Pies} is able to take a list of components from MeTA1 configuration file: @deffn {Pies Conf} include-meta1 @var{file} @@ -705,8 +708,8 @@ Thus, you can use @command{pies} instead of the default MeTA1 program manager @command{mcp}. To ensure compatibility with MeTA1, the components read from MeTA1 -configuration are started in reverse order (i.e. from last to first), -and stopped in order of their appearance in @var{file}. Of course, +configuration 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 @@ -800,7 +803,7 @@ Set file name of the statistics output file. Default is @end deffn Normally, @command{pies} must be run with root privileges. If, -however, you've found an implementation for it, that requires another +however, you found such an implementation for it, that requires another privileges, you may change them using the following three statements: @command{pies} process. @@ -820,7 +823,7 @@ Retain all supplementary groups of which user, given with @node Pies Debugging @section Pies Debugging The amount of debugging information produced by @command{pies} is configured -using two configuration statements. First of all, the standard +by the following two configuration statements. First of all, the standard @code{debug} block statement controls debugging of the underlying GNU Mailutils libraries (@pxref{Debug Statement, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}). Secondly, the @code{debug} @@ -840,7 +843,7 @@ Log all basic actions: starting and stopping of components, received incoming limits. Log pre-startup actions (@pxref{Actions Before Startup}). @item trace2 -Log setting particular limits. Log recomputing alarms. +Log setting particular limits. Log the recomputed alarms. @item trace4 Dump execution environments @@ -868,7 +871,7 @@ configuration files. @subsection Simplest Case: Using Pies to Run Pmult The example below runs @command{pmult} (@pxref{pmult}) utility with the privileges of @samp{meta1} user. Both standard error and standard -output are redirected to syslog facility @samp{mail}, priorities +output are redirected to the syslog facility @samp{mail}, priorities @samp{err} and @samp{info}, correspondingly. @smallexample @@ -1025,8 +1028,8 @@ $ pies --stop @cindex --dump-depmap option, pies Two options are provided for verifying inter-component dependencies. The @option{--dump-depmap} option prints on the -standard output the @dfn{dependency map}. This map is a square table -where rows represent dependents and columns represent prerequisites. +standard output the @dfn{dependency map}. This map is a square matrix +with rows representing dependents and columns representing prerequisites. An @samp{X} sign is placed on each crossing which corresponds to the actual dependency. For example: @@ -1068,6 +1071,8 @@ smtps: smar qmgr @node Pies Invocation @section Pies Invocation +This section summarizes @command{pies} command line options. + @table @option @item --force Force startup even if another instance may be running. diff --git a/doc/pmult.texi b/doc/pmult.texi index 93abec7d..42799e1c 100644 --- a/doc/pmult.texi +++ b/doc/pmult.texi @@ -1,5 +1,5 @@ @c This file is part of the Mailfromd manual. -@c Copyright (C) 2008 Sergey Poznyakoff +@c Copyright (C) 2008, 2009 Sergey Poznyakoff @c See file mailfromd.texi for copying conditions. @c ******************************************************************* @cindex @command{pmult}, described @@ -109,7 +109,7 @@ care to invoke right Milter handlers within the single @samp{data} Pmilter state. Therefore in the discussion that follows we will refer to Mailfromd handlers, rather than to Pmilter stages. - Most important standard Milter macros are always provided by + The most important standard Milter macros are always provided by @command{pmult} itself. These are: @table @asis @@ -243,8 +243,7 @@ MeTA1 transaction id. Message-Id of the message. @item c -The hop count. Basically, this is a count of the number of -@samp{Received:} headers. +The hop count. Basically, this is the number of @samp{Received:} headers. @end table Notice the following limitations: @@ -255,8 +254,9 @@ Notice the following limitations: @item All @samp{tls_*} macros are valid only after a @code{STARTTLS} command. @item The number of MeTA1 macros per stage is limited by -@code{PM_MAX_MACROS} define in @file{include/sm/pmfdef.h}. In MeTA1 -versions up to and including 1.0.PreAlpha27.0, this number is 8. +@code{PM_MAX_MACROS} define in @file{include/sm/pmfdef.h}. In MeTA1 +versions up to and including 1.0.PreAlpha28.0, this number is 8. If +you need more macros, inrease this number and recompile MeTA1. @end enumerate @end deffn @@ -369,7 +369,7 @@ See also the following subsection. @subsection Debugging Pmult If needed, @command{pmult} can be instructed to provide additional debugging information. The amount of this information is configured -using three configuration statements. First of all, the standard +by three configuration statements. First of all, the standard @code{debug} block statement controls debugging of the underlying GNU Mailutils libraries (@pxref{Debug Statement, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}). Secondly, the @code{debug} @@ -377,7 +377,7 @@ statement controls debugging output of the @command{pmult} utility itself. The @code{pmilter-debug} statement controls debugging output of the underlying MeTA1 libraries, and, finally, the @code{log-level} statement, described in the previous subsection, defines debugging -level for Milter library (@code{libgacopyz}). +level for the Milter library (@code{libgacopyz}). @deffn {Pmult Conf} debug @var{spec} Set debugging level for the @command{pmult} code. @xref{Debug @@ -419,7 +419,7 @@ and 100 (maximum debugging). Pmilter debugging information is printed on the standard error. Use @command{pies} @code{stderr} statement to capture this stream and -redirect it to syslog or file (@pxref{Output Redirectors}). +redirect it to the syslog or file (@pxref{Output Redirectors}). @end deffn @node pmult example @@ -427,11 +427,11 @@ redirect it to syslog or file (@pxref{Output Redirectors}). The following is an example of a working @command{pmult} configuration. The multiplexer listens on localhost, port @samp{3333}. It prints its diagnostics using syslog facility -@code{local2}. A single Mailfromd client is declared. This client +@code{local2}. A single Mailfromd client is declared, which listens on @acronym{UNIX} socket -@file{/usr/local/var/mailfromd/mailfrom}. Log verbosity level -for this client is set to @samp{info}, @samp{warn}, @samp{err} and -@samp{fatal}. +@file{/usr/local/var/mailfromd/mailfrom}. The log verbosity level +for this client is set to @samp{info} and higher, i.e.: @samp{info}, +@samp{warn}, @samp{err} and @samp{fatal}. @smallexample listen inet://127.0.0.1:3333; @@ -481,13 +481,13 @@ Disable signal handling in the main thread. This is for debugging purposes. @item --syslog -Log to syslog. This is the default. @xref{Logging Statement, Logging +Log to the syslog. This is the default. @xref{Logging Statement, Logging Statement, , mailutils, GNU Mailutils Manual}, for information on how to configure syslog logging. @item -s @itemx --stderr -Log to standard error stream. +Log to the standard error stream. @item --url=@var{url} Listen on the given @var{url}. This overrides the @code{url} |