diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-10 15:23:58 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-10 15:23:58 +0200 |
commit | 3809390c3e8df46b85371957b2da42fabfda9788 (patch) | |
tree | b5e5b6a7c381abcdfd1f0aa387fd3cfc02172553 | |
parent | 8f42fc862f0580cb5ecafac3e16582a1a817cf54 (diff) | |
download | pies-3809390c3e8df46b85371957b2da42fabfda9788.tar.gz pies-3809390c3e8df46b85371957b2da42fabfda9788.tar.bz2 |
Document state files and instances.
* doc/pies.texi: Update.
-rw-r--r-- | doc/pies.texi | 146 |
1 files changed, 98 insertions, 48 deletions
diff --git a/doc/pies.texi b/doc/pies.texi index b51be37..db438c6 100644 --- a/doc/pies.texi +++ b/doc/pies.texi | |||
@@ -106,9 +106,11 @@ Pies Configuration File | |||
106 | * Component Statement:: | 106 | * Component Statement:: |
107 | * Notification:: Mail Notification | 107 | * Notification:: Mail Notification |
108 | * ACL:: Access Control Lists | 108 | * ACL:: Access Control Lists |
109 | * inetd:: Using @command{inetd} Configuration Files | 109 | * inetd:: |
110 | * include-meta1:: Using @command{meta1} Configuration Files | 110 | * include-meta1:: |
111 | * Global Configuration:: | 111 | * Global Configuration:: |
112 | * Pies Privileges:: | ||
113 | * State Files:: | ||
112 | 114 | ||
113 | Configuration File Syntax | 115 | Configuration File Syntax |
114 | 116 | ||
@@ -134,10 +136,6 @@ Inetd-Style Components | |||
134 | * TCPMUX:: TCPMUX Services | 136 | * TCPMUX:: TCPMUX Services |
135 | * sockenv:: Socket Environment Variables | 137 | * sockenv:: Socket Environment Variables |
136 | 138 | ||
137 | Global Configuration | ||
138 | |||
139 | * Less Useful Statements:: | ||
140 | |||
141 | Configuration Example | 139 | Configuration Example |
142 | 140 | ||
143 | * Simple Pies:: | 141 | * Simple Pies:: |
@@ -315,6 +313,8 @@ directives any time by running @command{pies --config-help}. | |||
315 | * inetd:: | 313 | * inetd:: |
316 | * include-meta1:: | 314 | * include-meta1:: |
317 | * Global Configuration:: | 315 | * Global Configuration:: |
316 | * Pies Privileges:: | ||
317 | * State Files:: | ||
318 | @end menu | 318 | @end menu |
319 | 319 | ||
320 | @node Syntax | 320 | @node Syntax |
@@ -1187,11 +1187,12 @@ echo stream tcp nowait root internal | |||
1187 | @samp{echo} in the @code{service} field with the corresponding service | 1187 | @samp{echo} in the @code{service} field with the corresponding service |
1188 | name. | 1188 | name. |
1189 | 1189 | ||
1190 | @anchor{qotd} | ||
1190 | The @samp{qotd} service reads the contents of the @dfn{qotd file} | 1191 | The @samp{qotd} service reads the contents of the @dfn{qotd file} |
1191 | and sends it back to the client. By default the @samp{qotd} file | 1192 | and sends it back to the client. By default the @samp{qotd} file |
1192 | is located in the local state directory and named | 1193 | is located in the local state directory and named |
1193 | @file{@var{instance}.qotd} (where @var{instance} is the name of the | 1194 | @file{@var{instance}.qotd} (where @var{instance} is the name of the |
1194 | @command{pies} instance, @FIXME-pxref{instances}). This default location | 1195 | @command{pies} instance; @pxref{instances}). This default location |
1195 | can be changed using the following statement: | 1196 | can be changed using the following statement: |
1196 | 1197 | ||
1197 | @deffn {Config} qotd-file @var{file-name} | 1198 | @deffn {Config} qotd-file @var{file-name} |
@@ -1832,7 +1833,7 @@ as @command{inetd}: | |||
1832 | @xopindex{inetd, described} | 1833 | @xopindex{inetd, described} |
1833 | @item --inetd | 1834 | @item --inetd |
1834 | Read configuration from @file{@var{sysconfdir}/inetd.conf} and make | 1835 | Read configuration from @file{@var{sysconfdir}/inetd.conf} and make |
1835 | sure @command{pies} state files (@FIXME-pxref{state files}) do not | 1836 | sure @command{pies} state files (@pxref{State Files}) do not |
1836 | conflict with those from other @command{pies} instances. | 1837 | conflict with those from other @command{pies} instances. |
1837 | @end table | 1838 | @end table |
1838 | 1839 | ||
@@ -1985,41 +1986,10 @@ Wait @var{number} of seconds for all components to shut down. | |||
1985 | Default is 5 seconds. | 1986 | Default is 5 seconds. |
1986 | @end deffn | 1987 | @end deffn |
1987 | 1988 | ||
1988 | @menu | 1989 | @node Pies Privileges |
1989 | * Less Useful Statements:: | 1990 | @section Pies Privileges |
1990 | @end menu | 1991 | @cindex privileges |
1991 | 1992 | Normally, @command{pies} is run with root privileges. If, | |
1992 | @node Less Useful Statements | ||
1993 | @subsection Less Useful Statements | ||
1994 | |||
1995 | Some configuration file statements are provided for completeness and | ||
1996 | are rarely, if at all used. If used improperly, they may severely | ||
1997 | impair the functionality of @command{pies} or even render it | ||
1998 | useless. Do not use them, unless you have a good knowledge of | ||
1999 | @command{pies} internals and understand their impact. | ||
2000 | |||
2001 | The following three statements define file names of various files | ||
2002 | needed by @command{pies}. Use them only if the defaults does not | ||
2003 | suit your needs: | ||
2004 | |||
2005 | @deffn {Config} pidfile @var{file} | ||
2006 | Write PID of the master @command{pies} process to @var{file}. By | ||
2007 | default the master PID is stored in @file{@var{localstatedir}/pies.pid}, | ||
2008 | where @var{localstatedir} is the @dfn{local state directory}, defined | ||
2009 | at compile time (usually, it is @file{/usr/local/var} or @file{/usr/var}). | ||
2010 | @end deffn | ||
2011 | |||
2012 | @deffn {Config} control-file @var{file} | ||
2013 | Set file name of the @command{pies} control file. Default is | ||
2014 | @file{@var{localstatedir}/pies.ctl} | ||
2015 | @end deffn | ||
2016 | |||
2017 | @deffn {Config} stat-file @var{file} | ||
2018 | Set file name of the statistics output file. Default is | ||
2019 | @file{@var{localstatedir}/pies.stat}. | ||
2020 | @end deffn | ||
2021 | |||
2022 | Normally, @command{pies} must be run with root privileges. If, | ||
2023 | however, you found such an implementation for it, that requires another | 1993 | however, you found such an implementation for it, that requires another |
2024 | privileges, you may change them using the following three statements: | 1994 | privileges, you may change them using the following three statements: |
2025 | 1995 | ||
@@ -2036,6 +2006,57 @@ Retain all supplementary groups of which user, given with | |||
2036 | @command{user} statement, is a member. | 2006 | @command{user} statement, is a member. |
2037 | @end deffn | 2007 | @end deffn |
2038 | 2008 | ||
2009 | An example of such implementation is using @command{pies} to | ||
2010 | start @command{jabberd} components: | ||
2011 | @uref{http://www.gnu.org.ua/software/pies/example.php?what=jabberd2}. | ||
2012 | |||
2013 | @node State Files | ||
2014 | @section State Files | ||
2015 | @cindex state files | ||
2016 | Pies uses several files to keep its state information. These files | ||
2017 | are kept in local state directory (usually @file{/var/run/pies}, or | ||
2018 | @file{/usr/local/var/run/pies}). The table below describes these | ||
2019 | files. The @var{instance} in this table stands for the @command{pies} | ||
2020 | instance name (@pxref{instances}). Usually, it is @samp{pies}. | ||
2021 | |||
2022 | @table @asis | ||
2023 | @item @file{@var{instance}.pid} | ||
2024 | The @dfn{PID file}. It keeps the PID number of the running | ||
2025 | @command{pies} instance. | ||
2026 | |||
2027 | @item @file{@var{instance}.ctl} | ||
2028 | The @dfn{control file}. This file is used by @command{pies | ||
2029 | --restart-component} to pass control requests to the running | ||
2030 | @command{pies} instance. | ||
2031 | |||
2032 | @item @file{@var{instance}.stat} | ||
2033 | The @dfn{statistics file}. Used by @command{pies --status}. | ||
2034 | |||
2035 | @item @file{@var{instance}.qotd} | ||
2036 | The @dfn{Quotation-of-the-day file}. It is used by the @samp{qotd} | ||
2037 | built-in service (@pxref{qotd}). | ||
2038 | @end table | ||
2039 | |||
2040 | The following statements allow to redefine state file names. | ||
2041 | Use them only if the defaults does not suit your needs, and the | ||
2042 | @option{--instance} option does not help: | ||
2043 | |||
2044 | @deffn {Config} pidfile @var{file} | ||
2045 | Sets the PID file name. | ||
2046 | @end deffn | ||
2047 | |||
2048 | @deffn {Config} control-file @var{file} | ||
2049 | Sets the control file name. | ||
2050 | @end deffn | ||
2051 | |||
2052 | @deffn {Config} stat-file @var{file} | ||
2053 | Sets the statistics file name. | ||
2054 | @end deffn | ||
2055 | |||
2056 | @deffn {Config} qotd-file @var{file-name} | ||
2057 | Sets the name of the @samp{quotation-of-the-day} file. | ||
2058 | @end deffn | ||
2059 | |||
2039 | @node Pies Debugging | 2060 | @node Pies Debugging |
2040 | @chapter Pies Debugging | 2061 | @chapter Pies Debugging |
2041 | @xopindex{debug, described} | 2062 | @xopindex{debug, described} |
@@ -2199,10 +2220,39 @@ This configuration is ``almost'' equivalent, because the | |||
2199 | When run without arguments, @command{pies} parses and loads the | 2220 | When run without arguments, @command{pies} parses and loads the |
2200 | configuration file, detaches itself from the controlling terminal | 2221 | configuration file, detaches itself from the controlling terminal |
2201 | (becomes a daemon), and starts all components. Before actually | 2222 | (becomes a daemon), and starts all components. Before actually |
2202 | starting up, it ensures that no another instance of it is | 2223 | starting up, it ensures that no another copy is already running, by |
2203 | already running, by looking for a PID file and verifying that the PID | 2224 | looking for a PID file and verifying that the PID listed there is |
2204 | listed there is alive and responding. If another instance is running, | 2225 | alive and responding. If another copy is running, @command{pies} |
2205 | @command{pies} refuses to start up. | 2226 | refuses to start up. |
2227 | |||
2228 | @anchor{instances} | ||
2229 | It is often necessary to run several copies of @command{pies} with | ||
2230 | different configuration files. To support such usage, @command{pies} | ||
2231 | provides a notion of @dfn{instance}. Pies instance is an independent | ||
2232 | invocation of @command{pies} that uses a separate configuration file | ||
2233 | and separate state files (@pxref{State Files}). Instances are created | ||
2234 | using the @option{--instance} option: | ||
2235 | |||
2236 | @table @option | ||
2237 | @item --instance=@var{name} | ||
2238 | Read configuration from @file{@var{sysconfdir}/@var{name}.conf}, | ||
2239 | use @var{name} as the base name for state files (i.e., they become | ||
2240 | @file{@var{name}.pid}, @file{@var{name}.clt}, etc.) and tag all syslog | ||
2241 | messages with @var{name}. | ||
2242 | @end table | ||
2243 | |||
2244 | For example, the following invocations create three instances of | ||
2245 | @command{pies}: | ||
2246 | |||
2247 | @smallexample | ||
2248 | pies | ||
2249 | pies --instance=inetd | ||
2250 | pies --instance=mta | ||
2251 | @end smallexample | ||
2252 | |||
2253 | The first instance uses the default configuration and state files. | ||
2254 | The second one reads configuration from @file{/etc/inetd.conf}, and | ||
2255 | the third one reads it from @file{/etc/mta.conf}. | ||
2206 | 2256 | ||
2207 | @anchor{pies-status} | 2257 | @anchor{pies-status} |
2208 | After startup, you can verify the status of the running process | 2258 | After startup, you can verify the status of the running process |
@@ -2385,7 +2435,7 @@ equivalent to @command{pies --instance=inetd --syntax=inetd}. | |||
2385 | 2435 | ||
2386 | @opsummary{instance} | 2436 | @opsummary{instance} |
2387 | @item --instance=@var{name} | 2437 | @item --instance=@var{name} |
2388 | Define the name of the @command{pies} @dfn{instance}. @FIXME-xref{instances}. | 2438 | Define the name of the @command{pies} instance. @xref{instances}. |
2389 | 2439 | ||
2390 | @opsummary{lint} | 2440 | @opsummary{lint} |
2391 | @item --lint | 2441 | @item --lint |