diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile.am | 8 | ||||
-rw-r--r-- | doc/pies.texi | 418 | ||||
-rw-r--r-- | doc/usr-acl.texi | 48 |
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 | |||
18 | pies_TEXINFOS=\ | 18 | pies_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 | ||
24 | EXTRA_DIST = \ | 24 | EXTRA_DIST = \ |
25 | check-docs.sh\ | 25 | check-docs.sh\ |
@@ -48,7 +48,7 @@ check-options: | |||
48 | check-config: | 48 | check-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 | |||
95 | Pies 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 | |||
104 | Configuration File Syntax | ||
105 | |||
106 | * Comments:: | ||
107 | * Statements:: | ||
108 | * Preprocessor:: Using preprocessor to improve the configuration. | ||
109 | |||
110 | Component 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 | |||
122 | Global Configuration | ||
123 | |||
124 | * Less Useful Statements:: | ||
125 | |||
126 | Configuration 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 |
201 | if no errors were detected, and with status 1 otherwise. | 239 | if 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 |
206 | configuration without actually parsing it, use @option{-E} command | 244 | configuration without actually parsing it, use @option{-E} command |
@@ -212,8 +250,9 @@ detail. You can receive a concise summary of all configuration | |||
212 | directives any time by running @command{pies --config-help}. | 250 | directives 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 |
442 | it. The built-in preprocessor handles only file inclusion | 481 | external preprocessor @command{m4}. For a complete user manual, refer |
443 | and @code{#line} statements (@FIXME-pxref{Pragmatic Comments}), while the | 482 | to |
444 | rest of traditional preprocessing facilities, such as macro expansion, | ||
445 | is supported via @command{m4}, which is used as an external preprocessor. | ||
446 | |||
447 | The detailed description of @command{m4} facilities lies far beyond | ||
448 | the 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 |
455 | For the rest of this subsection we assume the reader is sufficiently | 489 | In this subsection we assume the reader is sufficiently |
456 | acquainted with @command{m4} macro processor. | 490 | acquainted with @command{m4} macro processor. |
457 | 491 | ||
458 | @flindex pp-setup | 492 | @flindex pp-setup |
@@ -487,7 +521,8 @@ component @var{tag} @{ | |||
487 | The component is identified by its @dfn{tag}, which is given as | 521 | The component is identified by its @dfn{tag}, which is given as |
488 | argument to the @code{component} keyword. | 522 | argument to the @code{component} keyword. |
489 | 523 | ||
490 | The following statements are allowed within the @code{component} block: | 524 | Following 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. | |||
539 | Precious components are never disabled by @command{pies}, even if they | 574 | Precious components are never disabled by @command{pies}, even if they |
540 | respawn too fast. | 575 | respawn too fast. |
541 | @end deffn | 576 | @end deffn |
542 | 577 | ||
578 | @deffn {Config: component} acl @{ ... @} | ||
579 | Set access control list for this component. @xref{ACL}, for a | ||
580 | detailed description of access control lists. | ||
581 | @end deffn | ||
582 | |||
583 | The following subsections describe the rest of @samp{component} | ||
584 | substatements. | ||
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 | |||
724 | to the log file. This behavior can be modified using | 766 | to 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 |
729 | return-code @var{codes} @{ | 771 | return-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} |
808 | Send an email notification to addresses in @var{email-string}. The | 850 | Send an email notification to addresses in @var{email-string}. |
809 | latter is a comma-separated list of email addresses, e.g.: | 851 | @xref{Notification}, for a detailed discussion of this feature. |
810 | |||
811 | @smallexample | ||
812 | notify "root@@localhost,postmaster@@localhost"; | ||
813 | @end smallexample | ||
814 | |||
815 | The message itself is configured by the @code{message} | ||
816 | statement. | ||
817 | @end deffn | 852 | @end deffn |
818 | 853 | ||
819 | @deffn {Config: return-code} message @var{string} | 854 | @deffn {Config: return-code} message @var{string} |
820 | Supply notification message text to use by @code{notify} statement. | 855 | Supply 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. |
822 | with message headers, followed by an empty line and actual message | ||
823 | body. | ||
824 | |||
825 | The 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 | ||
836 | on signal), in decimal. | ||
837 | @end multitable | ||
838 | |||
839 | The @samp{termination} variable is set so as to facilitate its use | ||
840 | with the @samp{retcode} variable. Namely, its value is @samp{exited | ||
841 | with}, if the component exited and @samp{terminated on signal}, if | ||
842 | the component terminated on a signal. Thus, using | ||
843 | |||
844 | @smallexample | ||
845 | $@{termination@} $@{retcode@} | ||
846 | @end smallexample | ||
847 | |||
848 | @noindent | ||
849 | results in a correct English sentence. This message, however, cannot | ||
850 | be properly internationalized. This will be fixed in the future | ||
851 | versions. | ||
852 | |||
853 | If @code{message} statement is not given, the following default | ||
854 | message is used instead: | ||