aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-10 15:23:58 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-12-10 15:23:58 +0200
commit3809390c3e8df46b85371957b2da42fabfda9788 (patch)
treeb5e5b6a7c381abcdfd1f0aa387fd3cfc02172553
parent8f42fc862f0580cb5ecafac3e16582a1a817cf54 (diff)
downloadpies-3809390c3e8df46b85371957b2da42fabfda9788.tar.gz
pies-3809390c3e8df46b85371957b2da42fabfda9788.tar.bz2
Document state files and instances.
* doc/pies.texi: Update.
-rw-r--r--doc/pies.texi146
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
113Configuration File Syntax 115Configuration 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
137Global Configuration
138
139* Less Useful Statements::
140
141Configuration Example 139Configuration 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
1188name. 1188name.
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}
1191and sends it back to the client. By default the @samp{qotd} file 1192and sends it back to the client. By default the @samp{qotd} file
1192is located in the local state directory and named 1193is 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
1195can be changed using the following statement: 1196can 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
1834Read configuration from @file{@var{sysconfdir}/inetd.conf} and make 1835Read configuration from @file{@var{sysconfdir}/inetd.conf} and make
1835sure @command{pies} state files (@FIXME-pxref{state files}) do not 1836sure @command{pies} state files (@pxref{State Files}) do not
1836conflict with those from other @command{pies} instances. 1837conflict 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.
1985Default is 5 seconds. 1986Default 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
1996are rarely, if at all used. If used improperly, they may severely
1997impair the functionality of @command{pies} or even render it
1998useless. 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
2002needed by @command{pies}. Use them only if the defaults does not
2003suit your needs:
2004
2005@deffn {Config} pidfile @var{file}
2006Write PID of the master @command{pies} process to @var{file}. By
2007default the master PID is stored in @file{@var{localstatedir}/pies.pid},
2008where @var{localstatedir} is the @dfn{local state directory}, defined
2009at compile time (usually, it is @file{/usr/local/var} or @file{/usr/var}).
2010@end deffn
2011
2012@deffn {Config} control-file @var{file}
2013Set 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}
2018Set 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,
2023however, you found such an implementation for it, that requires another 1993however, you found such an implementation for it, that requires another
2024privileges, you may change them using the following three statements: 1994privileges, 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
2010start @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
2017are kept in local state directory (usually @file{/var/run/pies}, or
2018@file{/usr/local/var/run/pies}). The table below describes these
2019files. The @var{instance} in this table stands for the @command{pies}
2020instance name (@pxref{instances}). Usually, it is @samp{pies}.
2021
2022@table @asis
2023@item @file{@var{instance}.pid}
2024The @dfn{PID file}. It keeps the PID number of the running
2025@command{pies} instance.
2026
2027@item @file{@var{instance}.ctl}
2028The @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}
2033The @dfn{statistics file}. Used by @command{pies --status}.
2034
2035@item @file{@var{instance}.qotd}
2036The @dfn{Quotation-of-the-day file}. It is used by the @samp{qotd}
2037built-in service (@pxref{qotd}).
2038@end table
2039
2040 The following statements allow to redefine state file names.
2041Use 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}
2045Sets the PID file name.
2046@end deffn
2047
2048@deffn {Config} control-file @var{file}
2049Sets the control file name.
2050@end deffn
2051
2052@deffn {Config} stat-file @var{file}
2053Sets the statistics file name.
2054@end deffn
2055
2056@deffn {Config} qotd-file @var{file-name}
2057Sets 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
2200configuration file, detaches itself from the controlling terminal 2221configuration 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
2202starting up, it ensures that no another instance of it is 2223starting up, it ensures that no another copy is already running, by
2203already running, by looking for a PID file and verifying that the PID 2224looking for a PID file and verifying that the PID listed there is
2204listed there is alive and responding. If another instance is running, 2225alive and responding. If another copy is running, @command{pies}
2205@command{pies} refuses to start up. 2226refuses to start up.
2227
2228@anchor{instances}
2229 It is often necessary to run several copies of @command{pies} with
2230different configuration files. To support such usage, @command{pies}
2231provides a notion of @dfn{instance}. Pies instance is an independent
2232invocation of @command{pies} that uses a separate configuration file
2233and separate state files (@pxref{State Files}). Instances are created
2234using the @option{--instance} option:
2235
2236@table @option
2237@item --instance=@var{name}
2238Read configuration from @file{@var{sysconfdir}/@var{name}.conf},
2239use @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
2241messages with @var{name}.
2242@end table
2243
2244 For example, the following invocations create three instances of
2245@command{pies}:
2246
2247@smallexample
2248pies
2249pies --instance=inetd
2250pies --instance=mta
2251@end smallexample
2252
2253 The first instance uses the default configuration and state files.
2254The second one reads configuration from @file{/etc/inetd.conf}, and
2255the 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}
2388Define the name of the @command{pies} @dfn{instance}. @FIXME-xref{instances}. 2438Define the name of the @command{pies} instance. @xref{instances}.
2389 2439
2390@opsummary{lint} 2440@opsummary{lint}
2391@item --lint 2441@item --lint

Return to:

Send suggestions and report system problems to the System administrator.