aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-09-15 10:40:29 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2009-09-15 10:40:54 +0300
commit989a5bbb74c3620abaa2191ce2c4f8d5968dbf0a (patch)
treec0b2324a523905c3c17201cc2468c9078976fc74 /doc
parentdbad35177723e19147ab49b59a3728e00fe05875 (diff)
downloadpies-989a5bbb74c3620abaa2191ce2c4f8d5968dbf0a.tar.gz
pies-989a5bbb74c3620abaa2191ce2c4f8d5968dbf0a.tar.bz2
Branch off from the Mailfromd project into a separate repository.
Diffstat (limited to 'doc')
-rw-r--r--doc/.gitignore22
-rw-r--r--doc/Makefile.am39
-rw-r--r--doc/pies.texi176
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

Return to:

Send suggestions and report system problems to the System administrator.