diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-02 10:26:39 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-02 10:26:39 +0200 |
commit | b63563c9c5271d088d80a31f780be74d1c16fef4 (patch) | |
tree | a30cab9cf81c44becdc3da6ae88a0264c7fe2ac4 /doc | |
parent | dc8b82d5b62e879c1291f531fd0d352a25fbfa87 (diff) | |
download | pies-b63563c9c5271d088d80a31f780be74d1c16fef4.tar.gz pies-b63563c9c5271d088d80a31f780be74d1c16fef4.tar.bz2 |
Minor changes
* doc/pies.texi: Update
* src/progman.c (run_command): handle return-code for inetd components.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/pies.texi | 169 |
1 files changed, 137 insertions, 32 deletions
diff --git a/doc/pies.texi b/doc/pies.texi index 9db612b..96cbfb5 100644 --- a/doc/pies.texi +++ b/doc/pies.texi | |||
@@ -82,6 +82,7 @@ documents @command{pies} Version @value{VERSION}. | |||
82 | 82 | ||
83 | @menu | 83 | @menu |
84 | * Intro:: | 84 | * Intro:: |
85 | * Dependencies:: | ||
85 | * Pies Configuration File:: | 86 | * Pies Configuration File:: |
86 | * Pies Debugging:: | 87 | * Pies Debugging:: |
87 | * Configuration Example:: | 88 | * Configuration Example:: |
@@ -152,22 +153,6 @@ terminates, @command{pies} restarts it. Its configuration allows to | |||
152 | specify actions other than simple restart, depending on the exit code | 153 | specify actions other than simple restart, depending on the exit code |
153 | of the component. | 154 | of the component. |
154 | 155 | ||
155 | @cindex prerequisite | ||
156 | @cindex dependency | ||
157 | @cindex dependents | ||
158 | @anchor{component prerequisite} | ||
159 | A component @samp{A} may depend on another components, say | ||
160 | @samp{B} and @samp{C}, i.e. require them to be running at the moment of its | ||
161 | startup. Components @samp{B} and @samp{C} are called | ||
162 | @dfn{prerequisites} for @samp{A}, while @samp{A} is called a | ||
163 | @dfn{dependency} or @dfn{dependent} component of @samp{B}, @samp{C}. | ||
164 | |||
165 | Before restarting any component, @command{pies} verifies if it is a | ||
166 | prerequisite for any other components. If so, it first terminates its | ||
167 | dependencies, then restarts the component, and then starts its | ||
168 | dependencies again, in the order of their appearance in the | ||
169 | configuration file. | ||
170 | |||
171 | The standard output and standard error streams of a component can be | 156 | The standard output and standard error streams of a component can be |
172 | redirected to a file or to an arbitrary @command{syslog} channel. | 157 | redirected to a file or to an arbitrary @command{syslog} channel. |
173 | 158 | ||
@@ -195,13 +180,13 @@ the @command{inetd} utility. | |||
195 | @anchor{meta1-style} | 180 | @anchor{meta1-style} |
196 | @cindex meta1-style components | 181 | @cindex meta1-style components |
197 | @cindex smtps | 182 | @cindex smtps |
198 | Third type of components supported by @command{pies} are | 183 | Yet another type of components supported by @command{pies} are |
199 | @dfn{meta1-style} components. As its name suggests, this type is | 184 | @dfn{meta1-style} components. As its name suggests, this type is |
200 | designed expressly as a support for MeTA1@footnote{See | 185 | designed expressly as a support for MeTA1@footnote{See |
201 | @uref{http://www.meta1.org}} components, namely | 186 | @uref{http://www.meta1.org}} components, namely |
202 | @command{smtps}. This type can be regarded as a mixture of the above | 187 | @command{smtps}. This type can be regarded as a mixture of the above |
203 | two. For each meta1-style component @command{pies} opens a socket | 188 | two. For each meta1-style component @command{pies} opens a socket |
204 | after start-up, and then executes the component. Once the component | 189 | after start-up, and starts the component binary. Once the component |
205 | is running, @command{pies} passes it the file descriptor of that | 190 | is running, @command{pies} passes it the file descriptor of that |
206 | socket, through another preconfigured @acronym{UNIX}-style socket. Further | 191 | socket, through another preconfigured @acronym{UNIX}-style socket. Further |
207 | handling of the socket is the responsibility of the component itself. | 192 | handling of the socket is the responsibility of the component itself. |
@@ -217,24 +202,82 @@ starts the component, without waiting for an actual connection. | |||
217 | simultaneously. | 202 | simultaneously. |
218 | 203 | ||
219 | Components are started in the order of their appearance in the | 204 | Components are started in the order of their appearance in the |
220 | configuration file and terminated in the reverse order. The same | 205 | configuration file and terminated in reverse order. The same |
221 | ordering applies when starting or stopping a component dependencies, | 206 | ordering applies when starting or stopping a component dependencies, |
222 | 207 | ||
223 | As an exception, this order is reversed for the components read from | 208 | As an exception, this order is reversed for the components read from |
224 | files included by @code{include-meta1} statement (@pxref{include-meta1}). | 209 | files included by @code{include-meta1} statement (@pxref{include-meta1}). |
225 | 210 | ||
211 | @node Dependencies | ||
212 | @chapter Inter-Component Dependencies | ||
213 | @cindex prerequisite | ||
214 | @cindex dependency | ||
215 | @cindex dependents | ||
216 | @anchor{component prerequisite} | ||
217 | A component @samp{A} may depend on another components, say | ||
218 | @samp{B} and @samp{C}, i.e. require them to be running at the moment of its | ||
219 | startup. Components @samp{B} and @samp{C} are called | ||
220 | @dfn{prerequisites} for @samp{A}, while @samp{A} is called a | ||
221 | @dfn{dependency} or @dfn{dependent} component of @samp{B}, @samp{C}. | ||
222 | |||
223 | Before restarting any component, @command{pies} verifies if it is a | ||
224 | prerequisite for any other components. If so, it first terminates its | ||
225 | dependencies, then restarts the component, and then starts its | ||
226 | dependencies again, in the order of their appearance in the | ||
227 | configuration file. | ||
228 | |||
226 | @node Pies Configuration File | 229 | @node Pies Configuration File |
227 | @chapter Pies Configuration File | 230 | @chapter Pies Configuration File |
228 | @cindex configuration file | 231 | @cindex configuration file |
229 | @flindex pies.conf | 232 | @flindex pies.conf |
230 | @xopindex{config-file, introduced} | 233 | @xopindex{config-file, introduced} |
231 | @command{Pies} reads its settings and component definitions from the | 234 | @command{Pies} reads its settings and component definitions from one |
232 | @dfn{configuration file} @file{pies.conf}, located in the @dfn{system | 235 | or more @dfn{configuration files}. The default configuration file |
236 | is named @file{pies.conf} and is located in the @dfn{system | ||
233 | configuration directory} (in most cases @file{/etc} or | 237 | configuration directory} (in most cases @file{/etc} or |
234 | @file{/usr/local/etc}, depending on how the package was compiled). | 238 | @file{/usr/local/etc}, depending on how the package was compiled). |
235 | An alternative location may be specified using @option{--config-file} | 239 | This file uses the @dfn{native Pies configuration syntax}. The |
236 | (@option{-c} command line option). | 240 | program also understands configuration files in @dfn{inetd} and |
241 | @dfn{meta1} formats. | ||
237 | 242 | ||
243 | Alternative configuration files may be specified using @option{--config-file} | ||
244 | (@option{-c} command line option), e.g.: | ||
245 | |||
246 | @smallexample | ||
247 | pies --config-file @var{filename} | ||
248 | @end smallexample | ||
249 | |||
250 | @anchor{config syntax} | ||
251 | Any number of such options may be given. The files named in | ||
252 | @option{--config-file} options are processed in order of their | ||
253 | appearance in the command line. By default, @command{pies} expects | ||
254 | configuration files in its native format. This, however, can be | ||
255 | changed by using the @option{--syntax=@var{format}} command line | ||
256 | option. This option instructs @command{pies} that any configuration | ||
257 | files given after it have are written in the specified @var{format}. | ||
258 | Valid formats are: @samp{pies}, @samp{inetd} and @samp{meta1}, which | ||
259 | stand for pies native format, inetd-style configuration files | ||
260 | (@FIXME-pxref{inetd-format} and MeTA1-style configuration files. The | ||
261 | configuration file format set by the @option{--syntax} option remains | ||
262 | in effect for all @option{--config-file} options that follow it, up to | ||
263 | the end of the command line or the next occurrence of the | ||
264 | @option{--syntax} option. This means that you can instruct | ||
265 | @command{pies} to read several configuration files of various formats | ||
266 | in a single command line, e.g.: | ||
267 | |||
268 | @smallexample | ||
269 | @group | ||
270 | pies /etc/pies.conf \ | ||
271 | --syntax=inetd --config-file /etc/inetd.conf \ | ||
272 | --syntax=meta1 --config-file /etc/meta1/meta1.conf | ||
273 | @end group | ||
274 | @end smallexample | ||
275 | |||
276 | The rest of this chapter concerns the @command{pies} native | ||
277 | configuration file format. The use of inetd configuration files is | ||
278 | covered in @FIXME-ref{inetd} and the use of meta1 configuration files | ||
279 | is described in @FIXME-ref{meta1} | ||
280 | |||
238 | If any errors are encountered in the configuration file, the program | 281 | If any errors are encountered in the configuration file, the program |
239 | reports them on the standard error and exits with status 78. | 282 | reports them on the standard error and exits with status 78. |
240 | 283 | ||
@@ -589,16 +632,43 @@ statement. Its value will be available to the program as | |||
589 | @code{argv[0]}. | 632 | @code{argv[0]}. |
590 | @end deffn | 633 | @end deffn |
591 | 634 | ||
592 | @deffn {Config: component} disable @var{bool} | 635 | @deffn {Config: component} flags (@var{flag-list}) |
593 | If @var{bool} is @samp{true}, this component is disabled, | 636 | Define flags for this component. The @var{flag-list} is a |
594 | i.e. @command{pies} will ignore it. | 637 | comma-separated list of flags. Valid flags are: |
595 | @end deffn | 638 | |
639 | @table @asis | ||
640 | @item disable | ||
641 | This component is disabled, i.e. @command{pies} will parse and | ||
642 | remember its settings, but will not start it. | ||
643 | |||
644 | @item precious | ||
645 | Mark this component as @dfn{precious}. Precious components are never | ||
646 | disabled by @command{pies}, even if they respawn too fast. | ||
647 | |||
648 | @item wait | ||
649 | This flag is valid only for @samp{inetd} components. It has the same | ||
650 | meaning as @samp{wait} in @file{inetd.conf} file, i.e. it tells | ||
651 | @command{pies} to wait for the server program to | ||
652 | return. @FIXME-xref{inetd}. | ||
596 | 653 | ||
597 | @deffn {Config: component} precious @var{bool} | 654 | @item tcpmux |
598 | @cindex precious components | 655 | This is a @acronym{TCPMUX} component. @FIXME-xref{tcpmux}. |
599 | If @var{bool} is @samp{true}, this component is marked as precious. | 656 | |
600 | Precious components are never disabled by @command{pies}, even if they | 657 | @item tcpmuxplus |
601 | respawn too fast. | 658 | This is a @acronym{TCPMUX+} component. @FIXME-xref{tcpmux}. |
659 | |||
660 | @item internal | ||
661 | This is an internal inetd component. @FIXME-xref{internal inetd}. | ||
662 | |||
663 | @item sockenv | ||
664 | This inetd component wants socket description variables in its | ||
665 | environment. @FIXME-xref{sockenv}. | ||
666 | |||
667 | @item resolve | ||
668 | When used with @samp{sockenv}, the @env{LOCALHOST} and | ||
669 | @env{REMOTEHOST} environment variables will contain resolved host | ||
670 | names, instead of IP addresses. | ||
671 | @end table | ||
602 | @end deffn | 672 | @end deffn |
603 | 673 | ||
604 | @deffn {Config: component} acl @{ ... @} | 674 | @deffn {Config: component} acl @{ ... @} |
@@ -1889,6 +1959,17 @@ Remain in foreground. | |||
1889 | @item --help | 1959 | @item --help |
1890 | Display a short usage summary and exit. | 1960 | Display a short usage summary and exit. |
1891 | 1961 | ||
1962 | @opsummary{inetd} | ||
1963 | @item --inetd | ||
1964 | @itemx -i | ||
1965 | Run in @command{inetd}-compatibility mode. It is roughly | ||
1966 | equivalent to @command{pies --instance=inetd --syntax=inetd}. | ||
1967 | @FIXME-xref{inetd}. | ||
1968 | |||
1969 | @opsummary{instance} | ||
1970 | @item --instance=@var{name} | ||
1971 | Define the name of the @command{pies} @dfn{instance}. @FIXME-xref{instances}. | ||
1972 | |||
1892 | @opsummary{lint} | 1973 | @opsummary{lint} |
1893 | @item --lint | 1974 | @item --lint |
1894 | @itemx -t | 1975 | @itemx -t |
@@ -1911,10 +1992,34 @@ Log to standard error. | |||
1911 | @itemx -S | 1992 | @itemx -S |
1912 | Stop the running instance. | 1993 | Stop the running instance. |
1913 | 1994 | ||
1995 | @opsummary{syntax} | ||
1996 | @item --syntax=@var{type} | ||
1997 | Define the syntax for parsing the configuration files specified by any | ||
1998 | @option{- |