[Zope-Checkins] CVS: ZODB3/zdaemon - schema.xml:1.10
Guido van Rossum
guido@python.org
Fri, 24 Jan 2003 17:55:22 -0500
Update of /cvs-repository/ZODB3/zdaemon
In directory cvs.zope.org:/tmp/cvs-serv27940
Modified Files:
schema.xml
Log Message:
Complete schema documentation.
=== ZODB3/zdaemon/schema.xml 1.9 => 1.10 ===
--- ZODB3/zdaemon/schema.xml:1.9 Fri Jan 24 08:04:08 2003
+++ ZODB3/zdaemon/schema.xml Fri Jan 24 17:55:19 2003
@@ -1,26 +1,216 @@
<schema>
<description>
- Schema for zdctl.py and zdrun.py.
+ This schema describes various options that control zdctl.py and
+ zdrun.py. zdrun.py is the "daemon process manager"; it runs a
+ subprocess in the background and restarts it when it crashes.
+ zdctl.py is the user interface to zdrun.py; it can tell zdrun.py
+ to start, stop or restart the subprocess, send it a signal, etc.
+
+ There are two sections: <runner> defines options unique
+ zdctl.py and zdrun.py, and <eventlog> defines a standard
+ event logging section used by zdrun.py.
+
+ More information about zdctl.py and zdrun.py can be found in the
+ file Doc/zdctl.txt. This all is specific to Unix/Linux.
</description>
<import package="zLOG"/>
<sectiontype name="runner">
- <key name="python" datatype="existing-path" />
- <key name="zdrun" datatype="existing-path" />
- <key name="program" datatype="string-list" required="yes" />
- <key name="backoff-limit" datatype="integer" default="10" />
- <key name="daemon" datatype="boolean" default="False" />
- <key name="forever" datatype="boolean" default="False" />
- <key name="socket-name" datatype="existing-dirpath" default="zdsock" />
+
+ <description>
+ This section describes the options for zdctl.py and zdrun.py.
+ The only required option is "program". Many other options have
+ no default value specified in the schema; in some cases, the
+ program calculates a dynamic default, in others, the feature
+ associated with the option is disabled.
+ </description>
+
+ <key name="program" datatype="string-list"
+ required="yes">
+ <description>
+ The command line used to start the subprocess managed by
+ zdrun.py. This is currently a simple list of
+ whitespace-delimited words. The first word is the program
+ file, subsequent words are its command line arguments. If the
+ program file contains no slashes, it is searched using $PATH.
+ (XXX There is no way to to include whitespace in the program
+ file or an argument, and under certain circumstances other
+ shell metacharacters are also a problem, e.g. the "foreground"
+ command of zdctl.py.)
+
+ NOTE: zdrun.py doesn't use this option; it uses its positional
+ arguments. Rather, zdctl.py uses this option to determine the
+ positional argument with which to invoke zdrun.py. (XXX This
+ could be better.)
+ </description>
+ </key>
+
+ <key name="python" datatype="existing-path"
+ required="no">
+ <description>
+ Path to the Python interpreter. Used by zdctl.py to start the
+ zdrun.py process. Defaults to sys.executable.
+ </description>
+ </key>
+
+ <key name="zdrun" datatype="existing-path"
+ required="no">
+ <description>
+ Path to the zdrun.py script. Used by zdctl.py to start the
+ zdrun.py process. Defaults to a file named "zdrun.py" in the
+ same directory as zdctl.py.
+ </description>
+ </key>
+
+ <key name="socket-name" datatype="existing-dirpath"
+ required="no"
+ default="zdsock">
+ <description>
+ The pathname of the Unix domain socket used for communication
+ between zdctl.py and zdrun.py. The default is relative to the
+ current directory in which zdctl.py and zdrun.py are started.
+ You want to specify an absolute pathname here.
+ </description>
+ </key>
+
+ <key name="daemon" datatype="boolean"
+ required="no"
+ default="false">
+ <description>
+ If this option is true, zdrun.py runs in the background as a
+ true daemon. It forks an child process which becomes the
+ subprocess manager, while the parent exits (making the shell
+ that started it believe it is done). The child process also
+ does the following:
+
+ - if the directory option is set, change into that directory
+
+ - redirect stdin, stdout and stderr to /dev/null
+
+ - call setsid() so it becomes a session leader
+
+ - call umask(022)
+ </description>
+ </key>
+
+ <key name="directory" datatype="existing-directory"
+ required="no">
+ <description>
+ If the daemon option is true, this option can specify a
+ directory into which zdrun.py changes as part of the
+ "daemonizing". If the daemon option is false, this option is
+ ignored.
+ </description>
+ </key>
+
+ <key name="backoff-limit" datatype="integer"
+ required="no"
+ default="10">
+ <description>
+ When the subprocess crashes, zdrun.py inserts a one-second
+ delay before it restarts it. When the subprocess crashes
+ again right away, the delay is incremented by one second, and
+ so on. What happens when the delay has reached the value of
+ backoff-limit (in seconds), depends on the value of the
+ forever option. If forever is false, zdrun.py gives up at
+ this point, and exits. An always-crashing subprocess will
+ have been restarted exactly backoff-limit times in this case.
+ If forever is true, zdrun.py continues to attempt to restart
+ the process, keeping the delay at backoff-limit seconds.
+
+ If the subprocess stays up for more than backoff-limit
+ seconds, the delay is reset to 1 second.
+ </description>
+ </key>
+
+ <key name="forever" datatype="boolean"
+ required="no"
+ default="false">
+ <description>
+ If this option is true, zdrun.py will keep restarting a
+ crashing subprocess forever. If it is false, it will give up
+ after backoff-limit crashes in a row. See the description of
+ backoff-limit for details.
+ </description>
+ </key>
+
<key name="exit-codes" datatype="zdaemon.zdoptions.list_of_ints"
- default="0,2" />
- <key name="user" datatype="string" />
- <key name="directory" datatype="existing-directory" required="no" />
- <key name="default-to-interactive" datatype="boolean" default="true" />
- <key name="hang-around" datatype="boolean" default="false" />
- <key name="logfile" datatype="existing-dirpath" />
+ required="no"
+ default="0,2">
+ <description>
+ If the subprocess exits with an exit status that is equal to
+ one of the integers in this list, zdrun.py will not restart
+ it. The default list requires some explanation. Exit status
+ 0 is considered a willful successful exit; the ZEO and Zope
+ server processes use this exit status when they want to stop
+ without being restarted. (Including in response to a
+ SIGTERM.) Exit status 2 is typically issued for command line
+ syntax errors; in this case, restarting the program will not
+ help!
+
+ NOTE: this mechanism overrides the backoff-limit and forever
+ options; i.e. even if forever is true, a subprocess exit
+ status code in this list makes zdrun.py give up. To disable
+ this, change the value to an empty list.
+ </description>
+ </key>
+
+ <key name="user" datatype="string"
+ required="no">
+ <description>
+ When zdrun.py is started by root, this option specifies the
+ user as who the the zdrun.py process (and hence the daemon
+ subprocess) will run. This can be a user name or a numeric
+ user id. Both the user and the group are set from the
+ corresponding password entry, using setuid() and setgid().
+ This is done before zdrun.py does anything else besides
+ parsing its command line arguments.
+
+ NOTE: when zdrun.py is not started by root, specifying this
+ option is an error. (XXX This may be a mistake.)
+
+ XXX The zdrun.py event log file may be opened *before*
+ setuid() is called. Is this good or bad?
+ </description>
+ </key>
+
+ <key name="hang-around" datatype="boolean"
+ required="no"
+ default="false">
+ <description>
+ If this option is true, the zdrun.py process will remain even
+ when the daemon subprocess is stopped. In this case, zdctl.py
+ will restart zdrun.py as necessary. If this option is false,
+ zdrun.py will exit when the daemon subprocess is stopped
+ (unless zdrun.py intends to restart it).
+ </description>
+ </key>
+
+ <key name="default-to-interactive" datatype="boolean"
+ required="no"
+ default="true">
+ <description>
+ If this option is true, zdctl.py enters interactive mode
+ when it is invoked without a positional command argument. If
+ it is false, you must use the -i or --interactive command line
+ option to zdctl.py to enter interactive mode.
+ </description>
+ </key>
+
+ <key name="logfile" datatype="existing-dirpath"
+ required="no">
+ <description>
+ This option specifies a log file that is the default target of
+ the "logtail" zdctl.py command.
+
+ NOTE: This is NOT the log file to which zdrun.py writes its
+ logging messages! That log file is specified by the
+ <eventlog> section.
+ </description>
+ </key>
+
</sectiontype>
<section name="*" type="runner" attribute="runner" required="yes" />