[Zodb-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: &lt;runner&gt; defines options unique
+    zdctl.py and zdrun.py, and &lt;eventlog&gt; 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
+        &lt;eventlog&gt; section.
+      </description>
+    </key>
+
   </sectiontype>
 
   <section name="*" type="runner" attribute="runner" required="yes" />