[Zodb-checkins] CVS: ZODB3/Doc - zdctl.txt:1.1

[Guido van Rossum]

Update of /cvs-repository/ZODB3/Doc
In directory cvs.zope.org:/tmp/cvs-serv11813

Added Files:
	zdctl.txt 
Log Message:
A bit of documentation for zdctl/zdrun.  Needs more work.


=== Added File ZODB3/Doc/zdctl.txt ===
Using zdctl and zdrun to manage server processes
================================================


Summary
-------

Starting with Zope 2.7 and ZODB 3.2, Zope has a new way to configure
and control server processes.  This file documents the new approach to
server process management; the new approach to configuration is
dcoumented elsewhere, although some examples will be given here.  We
use the ZEO server as a running example, although this isn't a
complete manual for configuring or running ZEO.

This documentation applies to Unix/Linux systems; zdctl and zdrun do
not work on Windows.


Prerequisites
-------------

This document assumes that you have installed the ZODB3 software using
a variation on the following command, given from the root directory of
the ZODB3 distribution::

  python setup.py install

This installs the packages ZConfig, ZEO, zdaemon, zLOG, ZODB and
various other needed packages and extension modules in the Python
interpreter's site-packages directory, and installs scripts including
zdctl.py, zdrun.py, runzeo.py and mkzeoinst.py in /usr/local/bin
(actually the bin directory from which the python interpreter was
loaded).


Introduction
------------

The most basic way to run a ZEO server is using the following
command::

  runzeo.py -a 9999 -f Data.fs

Here 9999 is the ZEO port (you can pick your own unused TCP port
number in the range 1024 through 65535, inclusive); Data.fs is the
storage file.  Again, you can pick any filename you want; the
ZODB.FileStorage module code creates this file and various other files
with additional extensions, like Data.fs.index, Data.fs.lock, and
Data.fs.tmp.

If something's wrong, for example if you picked a bad port number or
filename, you'll get an error message or an exception right away and
runzeo.py will exit with a non-zero exit status.  The exit status is 2
for command line syntax errors, 1 for other errors.

If all's well, runzeo.py will emit a few logging messages to stderr
and start serving, until you hit ^C.  For example::

  [guido@odiug /tmp]$ runzeo.py -a 9999 -f Data.fs
  ------
  2003-01-24T11:49:27 INFO(0) RUNSVR opening storage '1' using FileStorage
  ------
  2003-01-24T11:49:27 INFO(0) ZSS:23531 StorageServer created RW with
  storages: 1:RW:Data.fs
  ------
  2003-01-24T11:49:27 INFO(0) zrpc:23531 listening on ('', 9999)

At this point you can hit ^C to stop it; runzeo.py will catch the
interrupt signal, emit a few more log messages and exit::

  ^C
  ------
  2003-01-24T12:11:15 INFO(0) RUNSVR terminated by SIGINT
  ------
  2003-01-24T12:11:15 INFO(0) RUNSVR closing storage '1'
  [guido@odiug /tmp]$ 

This may be fine for testing, but a bad idea for running a ZEO server
in a production environment.  In production, you want the ZEO server
to be run as a daemon process, you want the log output to go to a
file, you want the ZEO server to be started when the system is
rebooted, and (usually) you want the ZEO server to be automatically
restarted when it crashes.  You should also have a log rotation policy
in place so that your disk doesn't fill up with log messages.

The zdctl/zdrun combo can take care of running a server as a daemon
process and restarting it when it crashes.  It can also be used to
start it when the system is rebooted.  Sending log output to a file is
done by adjusting the ZEO server configuration.  There are many fine
existing tools to rotate log files, so we don't provide this
functionality; zdctl has a command to send the server process a
SIGUSR2 signal to tell it to reopen its log file after log rotation
has taken place (the ZEO server has a signal handler that catches
SIGUSR2 for this purpose).

In addition, zdctl lets a system administrator or developer control
the server process.  This is useful to deal with typical problems like
restarting a hanging server or adjusting a server's configuration.

The zdctl program can be used in two ways: in one-shot mode it
executes a single command (such as "start", "stop" or "restart"); in
interactive mode it acts much like a typical Unix shell or the Python
interpreter, printing a prompt to standard output and reading commands
from standard input.  It currently cannot be used to read commands
from a file; if you need to script it, you can use a shell script
containing repeated one-shot invocations.

zdctl can be configured using command line options or a configuration
file.  In practice, you'll want to use a configuration file; but first
we'll show some examples using command line options only.  Here's a
one-shot zdctl command to start the ZEO server::

  zdctl.py -p "runzeo.py -a 9999 -f Data.fs" start

The -p option specifies the server program; it is the runzeo
invocation that we showed before.  The start argument tells it to
start the process.  What actually happens is that zdctl starts zdrun,
and zdrun now manages the ZEO server process.  The zdctl process exits
once zdrun has started the ZEO server process; the zdrun process stays
around, and when the ZEO server process crashes it will restart it.

To check that the ZEO server is now running, use the zdctl status
command::

  zdctl.py -p "runzeo.py -a 9999 -f Data.fs" status

This prints a one-line message telling you that the program is
running.  To stop the ZEO server, use the zdctl stop command::

  zdctl.py -p "runzeo.py -a 9999 -f Data.fs" stop

To check that is no longer running, use the zdctl status command
again.


Daemon mode
-----------

If you are playing along on your computer, you cannot have missed that
some log output has been spewing to your terminal window.  While this
may give you a warm and fuzzy feeling that something is actually
happening, it can be quite annoying (especially if clients are
actually connecting to the server).  This can be avoided by using the
-d flag, which enables "daemon mode"::

  zdctl.py -d -p "runzeo.py -a 9999 -f Data.fs" start

Daemon mode does several subtle things; see for example section 13.3
of "Advanced Programming in the UNIX Environment" by Richard Stevens
for a good explanation of daemon mode.  For now, the most important
effect is that the standard input, output and error streams are
redirected to /dev/null.


Using a configuration file
--------------------------

I hope you are using a Unix shell with command line history, otherwise
entering the examples above would have been quite a pain.  But a
better way to control zdctl and zdrun's many options without having to
type them over and over again is to use a configuration file.  Here's
a small configuration file; place this in the file "runner.conf" (the
name is just a convention; you can call it "foo" if you prefer)::

  # Sample zdctl/zdrun configuration
  <runner>
    program       runzeo.py -a 9999 -f Data.fs
    daemon	  true
    directory     /tmp/zeohome
    sockname      /tmp/zeohome/zdsock
  </runner>

The "program" and "daemon" lines correspond to the -p and -d command
line options discussed above.  The "directory" line is new.  It
specifies a directory into which zdrun (but not zdctl!) chdirs.  The
Data.fs filename passed to runzeo.py is interpreted relative to this
directory.  Finally, the "sockname" line names the Unix domain socket
that is used for communication between zdctl and zdrun.  It defaults
to zdsock in the current directory, a default you definitely want to
override for production usage.

To invoke zdctl with a configuration file, use its -C option to name
the configuration file, for example::

  zdrun.py -C runner.conf start


Interactive mode
----------------

XXX TBD


Using mkzeoinst.py
------------------

XXX TBD


zdctl reference
---------------

XXX TBD


zdrun reference
---------------

XXX TBD