diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/.gitignore | 22 | ||||
-rw-r--r-- | doc/Makefile.am | 39 | ||||
-rw-r--r-- | doc/pies.texi | 176 |
3 files changed, 176 insertions, 61 deletions
diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..94d867b --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,22 @@ +Makefile +Makefile.in +pies.info* +stamp-vti +version.texi +pies.aux +pies.cp +pies.cps +pies.dvi +pies.fl +pies.fn +pies.kw +pies.ky +pies.log +pies.mt +pies.op +pies.pg +pies.pr +pies.ps +pies.toc +pies.tp +pies.vr diff --git a/doc/Makefile.am b/doc/Makefile.am index ee522f2..502c46e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,50 +1,41 @@ -# This file is part of Mailfromd. +# This file is part of Pies. # Copyright (C) 2005, 2006, 2007, 2008, 2009 Sergey Poznyakoff # -# Mailfromd is free software; you can redistribute it and/or modify +# Pies is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 3, or (at your option) # any later version. # -# Mailfromd is distributed in the hope that it will be useful, +# Pies is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License -# along with Mailfromd. If not, see <http://www.gnu.org/licenses/>. +# along with Pies. If not, see <http://www.gnu.org/licenses/>. -info_TEXINFOS=mailfromd.texi -mailfromd_TEXINFOS=\ +info_TEXINFOS=pies.texi +pies_TEXINFOS=\ fdl.texi\ - gacopyz.texi\ macros.texi\ - mtasim.texi\ pies.texi\ - pmult.texi\ - pragma-database.texi\ - pragma-option.texi\ - rendition.texi\ - smap.texi\ - strftime.texi\ - upgrade.texi\ - values.texi + rendition.texi EXTRA_DIST = \ check-docs.sh\ gendocs_template\ mastermenu.el\ untabify.el clean-local: @rm -rf manual # Checking check-format: - @if test -n "`cat $(info_TEXINFOS) $(mailfromd_TEXINFOS) | tr -d -c '\t'`"; then \ + @if test -n "`cat $(info_TEXINFOS) $(pies_TEXINFOS) | tr -d -c '\t'`"; then \ echo "Sources contain tabs; run make untabify"; \ false; \ fi check-pragmas: @check-docs.sh pragmas \ @@ -62,13 +53,13 @@ check-options: $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ $(info_TEXINFOS) check-config: @check-docs.sh 'configuration statements' \ '/mf_cfg_param\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ - 's/@deffn {Mailfromd Conf} *\([^@,]*\).*/\1/p' \ + 's/@deffn {Pies Conf} *\([^@,]*\).*/\1/p' \ $(top_srcdir)/mfd/main.c -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ $(info_TEXINFOS) check-sub-config: @list=`sed -n '/mf_cfg_param\[\] *= *{/,/^}/{s/[ \t]*{ *"\([^,"]*\)", *mu_cfg_section *,.*/\1/pg}' $(top_srcdir)/mfd/main.c`; \ @@ -98,18 +89,18 @@ check-mflib: $(info_TEXINFOS) check-exceptions: @check-docs.sh exceptions \ '/typedef enum mf_exception_code {/,/^};/s/[ \t]*mfe_\(.*\),.*/e_\1/p;/typedef enum mf_status_code {/,/^};/s/[ \t]*mf_\(.*\),.*/\1/p' \ 's/@cindex \([^,][^,]*\), exception type/\1/p' \ - $(top_srcdir)/mfd/mailfromd.h -- \ + $(top_srcdir)/mfd/pies.h -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ $(info_TEXINFOS) check-refs: - @for file in $(info_TEXINFOS) $(mailfromd_TEXINFOS); \ + @for file in $(info_TEXINFOS) $(pies_TEXINFOS); \ do \ sed -e = $$file | \ sed -n 'N;/@FIXME-.*ref/{s/\(^[0-9][0-9]*\).*@FIXME-.*ref{\([^}]*\)}.*/'$$file':\1: \2/gp}'; \ done > $@-t; \ if [ -s $@-t ]; then \ echo "Unresolved cross-references:"; \ @@ -117,13 +108,13 @@ check-refs: rm $@-t; \ else \ rm -f $@-t; \ fi check-fixmes: - @for file in $(info_TEXINFOS) $(mailfromd_TEXINFOS); \ + @for file in $(info_TEXINFOS) $(pies_TEXINFOS); \ do \ sed -e = $$file | \ sed -n 'N;/@FIXME{/{s/\(^[0-9][0-9]*\).*@FIXME{\([^}]*\).*/'$$file':\1: \2/gp}'; \ done > $@-t; \ if [ -s $@-t ]; then \ echo "Unresolved FIXMEs:"; \ @@ -132,24 +123,24 @@ check-fixmes: false; \ else \ rm -f $@-t; \ fi check-writeme: - @grep -Hn @WRITEME $(info_TEXINFOS) $(mailfromd_TEXINFOS) > $@-t; \ + @grep -Hn @WRITEME $(info_TEXINFOS) $(pies_TEXINFOS) > $@-t; \ if [ -s $@-t ]; then \ echo "Empty nodes:"; \ cat $@-t; \ rm $@-t; \ false;\ else \ rm $@-t; \ fi check-unrevised: - @grep -Hn @UNREVISED $(info_TEXINFOS) $(mailfromd_TEXINFOS) > $@-t; \ + @grep -Hn @UNREVISED $(info_TEXINFOS) $(pies_TEXINFOS) > $@-t; \ if [ -s $@-t ]; then \ echo "Unrevised nodes:"; \ cat $@-t; \ rm $@-t; \ false;\ else \ @@ -167,13 +158,13 @@ check-docs: # master-menu: $(AM_V_GEN)emacs -batch -l mastermenu.el -f make-master-menu $(info_TEXINFOS) untabify: - @emacs -batch -l untabify.el $(info_TEXINFOS) $(mailfromd_TEXINFOS) + @emacs -batch -l untabify.el $(info_TEXINFOS) $(pies_TEXINFOS) final: untabify master-menu # The rendering level is one of PUBLISH, DISTRIB or PROOF. # Just call `make RENDITION=PROOF [target]' if you want PROOF rendition. diff --git a/doc/pies.texi b/doc/pies.texi index 7f020f1..cc35b5d 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -1,10 +1,106 @@ -@c This file is part of the Mailfromd manual. -@c Copyright (C) 2008, 2009 Sergey Poznyakoff -@c See file mailfromd.texi for copying conditions. -@c ******************************************************************* +\input texinfo @c -*-texinfo-*- +@smallbook +@c %**start of header +@setfilename pies.info +@settitle Pies +@c %**end of header +@setchapternewpage odd + +@defcodeindex pr +@defcodeindex op +@c mt is the same as op, but used for mtasim options. +@defcodeindex mt +@defcodeindex kw +@defcodeindex fl + +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp +@syncodeindex mt cp +@syncodeindex pg cp +@syncodeindex tp cp +@syncodeindex op cp +@syncodeindex pr cp +@syncodeindex kw cp +@syncodeindex fl cp + +@include version.texi +@include rendition.texi +@include macros.texi + +@ifinfo +@dircategory GNU Utilities +@direntry (pies) pies. Program execution supervisor. +@end direntry +@end ifinfo + +@copying +Published by the Free Software Foundation, +51 Franklin Street, Fifth Floor, +Boston, MA 02110-1301 USA + +Copyright @copyright{} 2005, 2006, 2007, 2008, 2009 Sergey Poznyakoff + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``Pies Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License''. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@end copying + +@titlepage +@title Program Invocation and Execution Supervisor +@subtitle version @value{VERSION}, @value{UPDATED} +@author Sergey Poznyakoff. +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@page +@summarycontents +@page +@contents + +@ifnottex +@node Top +@top Pies + +This edition of the @cite{Pies Manual}, last updated @value{UPDATED}, +documents @command{pies} Version @value{VERSION}. +@end ifnottex + +@menu +* Intro:: +* Pies Configuration File:: +* Component Statement:: +* include-meta1:: +* Global Configuration:: +* Pies Debugging:: +* Configuration Example:: +* Command Line Usage:: +* Pies Invocation:: + +Appendices + +* Copying This Manual:: The GNU Free Documentation License. +* Concept Index:: Index of Concepts. + +@c @detailmenu +@c @end detailmenu + +@end menu + +@node Intro +@chapter Introduction @cindex component, pies The name @command{pies} (pronounced @samp{p-yes}) stands for @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 the foreground. Upon startup, @command{pies} reads the list @@ -82,32 +178,24 @@ 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}). @menu -* Pies Configuration File:: -* Component Statement:: -* include-meta1:: -* Global Configuration:: -* Pies Debugging:: -* Configuration Example:: -* Command Line Usage:: -* Pies Invocation:: @end menu @node Pies Configuration File -@section Pies Configuration File +@chapter Pies Configuration File @command{Pies} reads its configuration from the main Mailutils configuration file. @xref{configuration, Mailutils Configuration File,, mailutils, GNU Mailutils Manual}, for a description of GNU Mailutils configuration system. It is recommended to use @code{include @var{directory}} statement (@pxref{Include, Include Statement,, mailutils, GNU Mailutils Manual}), and to place @command{pies} configuration in file @file{@var{directory}/pies}. -@xref{MeTA1}, for an example. +@xref{MeTA1,,, mailfromd, Mailfromd Manual}, for an example. The following standard Mailutils configuration statements are understood: @multitable @columnfractions 0.3 0.6 @headitem Statement @tab Reference @item debug @tab @xref{Debug Statement, Mailutils Debug Statement,, @@ -120,13 +208,13 @@ mailutils, GNU Mailutils Manual}. mailutils, GNU Mailutils Manual}. @item acl @tab @xref{ACL Statement, ACL Statement,, mailutils, GNU Mailutils Manual}. @end multitable @node Component Statement -@section Component Statement +@chapter Component Statement @kwindex component The @code{component} statement defines a new component: @smallexample component @var{tag} @{ @dots{} @@ -200,13 +288,13 @@ respawn too fast. * Inetd-Style Components:: * Meta1-Style Components:: * Component Syntax Summary:: @end menu @node Prerequisites -@subsection Component Prerequisites +@section Component Prerequisites @cindex declaring prerequisites @cindex prerequisites, declaring Prerequisites (@pxref{component prerequisite}) for a component are declared using the following statement: @deffn {Pies Conf} prerequisites @var{tag-list} @@ -227,13 +315,13 @@ No prerequisites. This is the default. @deffn {Pies Conf} dependents @var{tag-list} Declare dependents for this component. @var{var-list} is a list of component tags. @end deffn @node Component Privileges -@subsection Component Privileges +@section Component Privileges @cindex privileges, pies 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. @@ -247,13 +335,13 @@ Retain supplementary groups, specified in @var{group-list}. 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 @node Resources -@subsection Resources +@section Resources @deffn {Pies Conf} limits @var{string} Impose limits on system resources, as defined by @var{string}. The argument consists of @dfn{commands}, optionally separated by any amount of whitespace. A command is a single command letter followed by a number, that specifies the limit. The command letters are @@ -337,13 +425,13 @@ created and @var{value} is assigned to it. However, if @var{value} ends with a punctuation character, this character is removed from it before assignment. @end table @end deffn @node Actions Before Startup -@subsection Actions Before Startup +@section Actions Before Startup Several statements are available that specify actions to perform immediately before starting the component: @deffn {Pies Conf} chdir @var{dir} Change to the directory @var{dir}. @@ -362,13 +450,13 @@ Wait @var{number} 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 -@subsection Exit Actions +@section Exit Actions @kwindex return-code The default behavior of @command{pies} if 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 @code{return-code} statement: @@ -474,13 +562,13 @@ body. The following macro-variables are expanded within @var{string}: @multitable @columnfractions 0.5 0.5 @headitem Variable @tab Expansion @item canonical-program-name @tab @samp{pies} @item program-name @tab Program name of the @command{pies} binary. -@item package @tab Package name (@samp{Mailfromd}). +@item package @tab Package name (@samp{Pies}). @item version @tab Package version (@value{VERSION}). @item mu-version @tab Version of GNU Mailutils. @item component @tab Name of the terminated component. @item retcode @tab Component exit code, in decimal. @end multitable @@ -501,13 +589,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. Any @code{return-code} statements appearing within a @code{component} block override the global ones. @node Output Redirectors -@subsection Output Redirectors +@section 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. @deffn {Pies Conf} stderr @var{type} @var{channel} @deffnx {Pies Conf} stdout @var{type} @var{channel} @@ -547,13 +635,13 @@ Specify the syslog facility to use in syslog redirectors. Allowed values for @var{syslog-facility} 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 +@section 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: @anchor{inetd-socket} @@ -605,13 +693,13 @@ Notice, that @command{pies} version @value{VERSION} handles only @acronym{TCP} sockets and only IPv4 addresses. Support for IPv6 will be added in future versions. Support for @acronym{UDP} sockets will be added if there is a demand. @end deffn @node Meta1-Style Components -@subsection Meta1-Style Components +@section Meta1-Style Components @cindex meta1-style components Meta1-style components are declared using @code{mode pass} statement. For such components, you must declare both a socket to listen on (@pxref{inetd-socket} and a @acronym{UNIX} socket name to pass the file descriptor to the component. The latter is defined using @code{pass-fd-socket} statement: @@ -624,13 +712,13 @@ socket will be looked under @var{dir}. This socket file is supposed to be created by the component binary upon its startup. @end deffn @node Component Syntax Summary -@subsection Component Syntax Summary +@section Component Syntax Summary This subsection summarizes the @code{component} summary. For each statement, a reference to its detailed description is supplied. @smallexample component @var{tag} @{ # @r{Component execution mode.} @@ -724,13 +812,13 @@ component @var{tag} @{ message @var{string}; @} @} @end smallexample @node include-meta1 -@section Using MeTA1 Configuration File +@chapter Using MeTA1 Configuration File @cindex /etc/meta1/meta1.conf @command{Pies} is able to take a list of components from MeTA1 configuration file: @deffn {Pies Conf} include-meta1 @var{file} Parse @var{file} as MeTA1 configuration file and incorporate @@ -779,13 +867,13 @@ component smtps @{ facility local1; stderr syslog debug; @} @end smallexample @node Global Configuration -@section Global Configuration +@chapter Global Configuration The statements described in this section affect @command{pies} behavior as a whole. @deffn {Pies Conf} 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. @@ -808,13 +896,13 @@ Default is 5 seconds. @menu * Less Useful Statements:: @end menu @node Less Useful Statements -@subsection Less Useful Statements +@section Less Useful Statements Some configuration file statements are provided for completeness and are rarely, if at all used. If used improperly, they may severely impair the functionality of @command{pies} or even render it useless. Do not use them, unless you have a good knowledge of @command{pies} internals and understand their impact. @@ -823,13 +911,13 @@ useless. Do not use them, unless you have a good knowledge of needed by @command{pies}. Use them only if the defaults does not suit your needs: @deffn {Pies Conf} pidfile @var{file} Write PID of the master @command{pies} process to @var{file}. By default, master PID is stored in @file{@var{statedir}/pies.pid} -(@pxref{statedir}). +(@FIXME-pxref{statedir}). @end deffn @deffn {Pies Conf} control-file @var{file} Set file name of the @command{pies} control file. Default is @file{@var{statedir}/pies.ctl} @end deffn @@ -855,13 +943,13 @@ Retain supplementary groups, specified in @var{group-list}. @deffn {Pies Conf} allgroups @var{bool} Retain all supplementary groups of which user, given with @command{user} statement, is a member. @end deffn @node Pies Debugging -@section Pies Debugging +@chapter Pies Debugging The amount of debugging information produced by @command{pies} is configured 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} statement controls debugging output of the @command{pies} utility @@ -891,25 +979,26 @@ Debug the parser of MeTA1 configuration grammar. @item trace7 Debug the lexical analyzer of MeTA1 configuration file. @end table @end deffn @node Configuration Example -@section Configuration Example +@chapter Configuration Example In this section we provide several examples of working @command{pies} configuration files. @menu * Simple Pies:: * Hairy Pies:: * Inetd Pies:: @end menu @node Simple Pies -@subsection Simplest Case: Using Pies to Run Pmult - The example below runs @command{pmult} (@pxref{pmult}) utility with +@section Simplest Case: Using Pies to Run Pmult + The example below runs @command{pmult} (@pxref{pmult, Pmilter +multiplexer program,, mailfromd, Mailfromd Manual}) utility with the privileges of @samp{meta1} user. Both standard error and standard output are redirected to the syslog facility @samp{mail}, priorities @samp{err} and @samp{info}, correspondingly. @smallexample component pmult @{ @@ -919,13 +1008,13 @@ component pmult @{ stderr syslog err; stdout syslog info; @} @end smallexample @node Hairy Pies -@subsection Using Pies to Run Pmult and MeTA1 +@section Using Pies to Run Pmult and MeTA1 The example below is a working configuration file for running @command{pmult} and all components of MeTA1, configured in @file{/etc/meta1/meta1.conf}. The global @code{return-code} statement is used to configure @command{pies} behavior for some exit codes. @smallexample @@ -961,13 +1050,13 @@ component pmult @{ @} include-meta1 "/etc/meta1/meta1.conf"; @end smallexample @node Inetd Pies -@subsection Running Pies Instead of Inetd +@section Running Pies Instead of Inetd 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 @@ -994,13 +1083,13 @@ component pop3d @{ program "/usr/sbin/pop3d"; command "pop3d --inetd"; @} @end smallexample @node Command Line Usage -@section Command Line Usage +@chapter Command Line Usage When run without arguments, @command{pies} parses and loads the configuration file, detaches itself from the controlling terminal (becomes a daemon), and starts all components. Before actually starting up, it ensures that no another instance of it is already running, by looking for a PID file and verifying that the PID @@ -1103,13 +1192,13 @@ $ pies --dump-prereq qmgr: smar smtpc: qmgr smtps: smar qmgr @end smallexample @node Pies Invocation -@section Pies Invocation +@chapter Pies Invocation This section summarizes @command{pies} command line options. @table @option @item --force Force startup even if another instance may be running. @@ -1154,6 +1243,19 @@ Dump prerequisite charts. @xref{dump-prereq}. @end table Apart from these, the common GNU Mailutils options are understood, which are useful for checking @command{pies} configuration file for syntax errors. @xref{Common Options, Common Options, , mailutils, GNU Mailutils Manual}, for a detailed description of these. + +@node Copying This Manual +@appendix GNU Free Documentation License +@include fdl.texi + +@node Concept Index +@unnumbered Concept Index + +This is a general index of all issues discussed in this manual + +@printindex cp + +@bye |