aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am8
-rw-r--r--doc/pies.texi418
-rw-r--r--doc/usr-acl.texi48
3 files changed, 343 insertions, 131 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index fec8df3..bb2ff49 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -18,8 +18,8 @@ info_TEXINFOS=pies.texi
18pies_TEXINFOS=\ 18pies_TEXINFOS=\
19 fdl.texi\ 19 fdl.texi\
20 macros.texi\ 20 macros.texi\
21 pies.texi\ 21 rendition.texi\
22 rendition.texi 22 usr-acl.texi
23 23
24EXTRA_DIST = \ 24EXTRA_DIST = \
25 check-docs.sh\ 25 check-docs.sh\
@@ -48,7 +48,7 @@ check-options:
48check-config: 48check-config:
49 @check-docs.sh 'configuration statements' \ 49 @check-docs.sh 'configuration statements' \
50 '/pies_keywords\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ 50 '/pies_keywords\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
51 's/@deffn {Config} *\([^@,]*\).*/\1/p' \ 51 's/@deffnx\{0,1\} {Config} *\([^@,]*\).*/\1/p' \
52 $(top_srcdir)/src/pies.c -- \ 52 $(top_srcdir)/src/pies.c -- \
53 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ 53 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
54 $(info_TEXINFOS) 54 $(info_TEXINFOS)
@@ -58,7 +58,7 @@ check-sub-config:
58 while read ident kw; do \ 58 while read ident kw; do \
59 check-docs.sh "$$ident configuration statements" \ 59 check-docs.sh "$$ident configuration statements" \
60 "/$$kw"'\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ 60 "/$$kw"'\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
61 "s/@deffn {Config: *$${ident}}"' *\([^@,]*\).*/\1/p' \ 61 "s/@deffnx\{0,1\} {Config: *$${ident}}"' *\([^@,]*\).*/\1/p' \
62 $(top_srcdir)/src/pies.c $(top_srcdir)/src/acl.c -- \ 62 $(top_srcdir)/src/pies.c $(top_srcdir)/src/acl.c -- \
63 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ 63 $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
64 $(info_TEXINFOS); \ 64 $(info_TEXINFOS); \
diff --git a/doc/pies.texi b/doc/pies.texi
index e1ca650..e47f6a6 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -90,8 +90,46 @@ Appendices
90* Concept Index:: Index of Concepts. 90* Concept Index:: Index of Concepts.
91 91
92@detailmenu 92@detailmenu
93@end detailmenu 93 --- The Detailed Node Listing ---
94
95Pies Configuration File
96
97* Syntax:: Configuration File Syntax
98* Component Statement::
99* Notification:: Mail Notification
100* ACL:: Access Control Lists
101* include-meta1::
102* Global Configuration::
103
104Configuration File Syntax
105
106* Comments::
107* Statements::
108* Preprocessor:: Using preprocessor to improve the configuration.
109
110Component Statement
111
112* Prerequisites::
113* Component Privileges::
114* Resources::
115* Actions Before Startup::
116* Exit Actions::
117* Output Redirectors::
118* Inetd-Style Components::
119* Meta1-Style Components::
120* Component Syntax Summary::
121
122Global Configuration
123
124* Less Useful Statements::
125
126Configuration Example
94 127
128* Simple Pies::
129* Hairy Pies::
130* Inetd Pies::
131
132@end detailmenu
95@end menu 133@end menu
96 134
97@node Intro 135@node Intro
@@ -200,7 +238,7 @@ reports them on the standard error and exits with a non-zero status.
200@command{pies} to check its configuration file and exit with status 0 238@command{pies} to check its configuration file and exit with status 0
201if no errors were detected, and with status 1 otherwise. 239if no errors were detected, and with status 1 otherwise.
202 240
203@opindex -E, introduced 241@cindex @option{-E}, introduced
204 Before parsing, configuration file is preprocessed using 242 Before parsing, configuration file is preprocessed using
205@command{m4} (@pxref{Preprocessor}). To see the preprocessed 243@command{m4} (@pxref{Preprocessor}). To see the preprocessed
206configuration without actually parsing it, use @option{-E} command 244configuration without actually parsing it, use @option{-E} command
@@ -212,8 +250,9 @@ detail. You can receive a concise summary of all configuration
212directives any time by running @command{pies --config-help}. 250directives any time by running @command{pies --config-help}.
213 251
214@menu 252@menu
215* Syntax:: Configuration file syntax. 253* Syntax:: Configuration File Syntax
216* Component Statement:: 254* Component Statement::
255* Notification:: Mail Notification
217* ACL:: Access Control Lists 256* ACL:: Access Control Lists
218* include-meta1:: 257* include-meta1::
219* Global Configuration:: 258* Global Configuration::
@@ -438,21 +477,16 @@ this is not required.
438@subsection Using Preprocessor to Improve the Configuration. 477@subsection Using Preprocessor to Improve the Configuration.
439@cindex preprocessor 478@cindex preprocessor
440@cindex m4 479@cindex m4
441 Before parsing configuration file, @command{pies} preprocesses 480 Before parsing, the configuration file is @dfn{preprocessed} using
442it. The built-in preprocessor handles only file inclusion 481external preprocessor @command{m4}. For a complete user manual, refer
443and @code{#line} statements (@FIXME-pxref{Pragmatic Comments}), while the 482to
444rest of traditional preprocessing facilities, such as macro expansion,
445is supported via @command{m4}, which is used as an external preprocessor.
446
447 The detailed description of @command{m4} facilities lies far beyond
448the scope of this document. You will find a complete user manual in
449@ifnothtml 483@ifnothtml
450@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}. 484@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
451@end ifnothtml 485@end ifnothtml
452@ifhtml 486@ifhtml
453@uref{http://www.gnu.org/software/m4/manual}. 487@uref{http://www.gnu.org/software/m4/manual}.
454@end ifhtml 488@end ifhtml
455For the rest of this subsection we assume the reader is sufficiently 489In this subsection we assume the reader is sufficiently
456acquainted with @command{m4} macro processor. 490acquainted with @command{m4} macro processor.
457 491
458@flindex pp-setup 492@flindex pp-setup
@@ -487,7 +521,8 @@ component @var{tag} @{
487The component is identified by its @dfn{tag}, which is given as 521The component is identified by its @dfn{tag}, which is given as
488argument to the @code{component} keyword. 522argument to the @code{component} keyword.
489 523
490The following statements are allowed within the @code{component} block: 524Following are the basic statements which are allowed within the
525@code{component} block:
491 526
492@deffn {Config: component} mode @var{mode} 527@deffn {Config: component} mode @var{mode}
493 Declare the type (style) of the component. Accepted values for 528 Declare the type (style) of the component. Accepted values for
@@ -539,7 +574,14 @@ If @var{bool} is @samp{true}, this component is marked as precious.
539Precious components are never disabled by @command{pies}, even if they 574Precious components are never disabled by @command{pies}, even if they
540respawn too fast. 575respawn too fast.
541@end deffn 576@end deffn
542 577
578@deffn {Config: component} acl @{ ... @}
579Set access control list for this component. @xref{ACL}, for a
580detailed description of access control lists.
581@end deffn
582
583The following subsections describe the rest of @samp{component}
584substatements.
543 585
544@menu 586@menu
545* Prerequisites:: 587* Prerequisites::
@@ -724,7 +766,7 @@ terminates with 0 exit code, a corresponding error message is issued
724to the log file. This behavior can be modified using 766to the log file. This behavior can be modified using
725@code{return-code} statement: 767@code{return-code} statement:
726 768
727@deffn {Config} return-code 769@deffn {Config: component} return-code
728@smallexample 770@smallexample
729return-code @var{codes} @{ 771return-code @var{codes} @{
730 @dots{} 772 @dots{}
@@ -805,60 +847,13 @@ by the administrator.
805@end deffn 847@end deffn
806 848
807@deffn {Config: return-code} notify @var{email-string} 849@deffn {Config: return-code} notify @var{email-string}
808Send an email notification to addresses in @var{email-string}. The 850Send an email notification to addresses in @var{email-string}.
809latter is a comma-separated list of email addresses, e.g.: 851@xref{Notification}, for a detailed discussion of this feature.
810
811@smallexample
812notify "root@@localhost,postmaster@@localhost";
813@end smallexample
814
815The message itself is configured by the @code{message}
816statement.
817@end deffn 852@end deffn
818 853
819@deffn {Config: return-code} message @var{string} 854@deffn {Config: return-code} message @var{string}
820Supply notification message text to use by @code{notify} statement. 855Supply notification message text to use by @code{notify} statement.
821@var{String} must be a valid RFC 822 message text, i.e. it must begin 856@xref{Notification}, for a detailed discussion of this feature.
822with message headers, followed by an empty line and actual message
823body.
824
825The following macro-variables are expanded within @var{string}:
826
827@multitable @columnfractions 0.5 0.5
828@headitem Variable @tab Expansion
829@item canonical-program-name @tab @samp{pies}
830@item program-name @tab Program name of the @command{pies} binary.
831@item package @tab Package name (@samp{Pies}).
832@item version @tab Package version (@value{VERSION}).
833@item component @tab Name of the terminated component.
834@item termination @tab Termination cause (see below).
835@item retcode @tab Component exit code (or signal number, if exited
836on signal), in decimal.
837@end multitable
838
839The @samp{termination} variable is set so as to facilitate its use
840with the @samp{retcode} variable. Namely, its value is @samp{exited
841with}, if the component exited and @samp{terminated on signal}, if
842the component terminated on a signal. Thus, using
843
844@smallexample
845$@{termination@} $@{retcode@}
846@end smallexample
847
848@noindent
849results in a correct English sentence. This message, however, cannot
850be properly internationalized. This will be fixed in the future
851versions.
852
853If @code{message} statement is not given, the following default
854message is used instead: