aboutsummaryrefslogtreecommitdiff
path: root/doc/pies.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/pies.texi')
-rw-r--r--doc/pies.texi418
1 files changed, 291 insertions, 127 deletions
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:
855
856@smallexample
857From: <>
858X-Agent: $@{canonical-program-name@} ($@{package@} $@{version@})
859Subject: Component $@{component@} $@{termination@} $@{retcode@}.
860
861@end smallexample
862@end deffn 857@end deffn
863 858
864 Any number of @code{return-code} statements are allowed, provided 859 Any number of @code{return-code} statements are allowed, provided
@@ -876,7 +871,7 @@ all components. Any @code{return-code} statements appearing within a
876output of a component to a file or @command{syslog} facility. 871output of a component to a file or @command{syslog} facility.
877 872
878@deffn {Config: component} stderr @var{type} @var{channel} 873@deffn {Config: component} stderr @var{type} @var{channel}
879@deffnx {Config} stdout @var{type} @var{channel} 874@deffnx {Config: component} stdout @var{type} @var{channel}
880Redirect standard error (if @code{stderr}) or standard output (if 875Redirect standard error (if @code{stderr}) or standard output (if
881@code{stdout}) to the given channel. 876@code{stdout}) to the given channel.
882 877
@@ -1091,6 +1086,157 @@ component @var{tag} @{
1091@} 1086@}
1092@end smallexample 1087@end smallexample
1093 1088
1089@node Notification
1090@section Notification
1091@cindex Notification
1092
1093 Pies provides a @dfn{notification} mechanism, which can be used to
1094send email messages when components terminate. The exact contents
1095of such notifications and the list of their recipients may depend on
1096the exit code which the component returned. Notification is
1097configured by supplying @samp{notify} and @samp{message} statements
1098within a @samp{return-code} block.
1099
1100@deffn {Config: return-code} notify @var{email-string}
1101Send an email notification to addresses from @var{email-string}. The