[Zodb-checkins] CVS: ZODB3/Doc - zdctl.txt:1.3
Guido van Rossum
guido@python.org
Tue, 11 Mar 2003 17:57:54 -0500
Update of /cvs-repository/ZODB3/Doc
In directory cvs.zope.org:/tmp/cvs-serv6253
Modified Files:
zdctl.txt
Log Message:
Added a little more, including a bit on interactive mode.
=== ZODB3/Doc/zdctl.txt 1.2 => 1.3 ===
--- ZODB3/Doc/zdctl.txt:1.2 Fri Feb 21 13:00:25 2003
+++ ZODB3/Doc/zdctl.txt Tue Mar 11 17:57:52 2003
@@ -19,11 +19,11 @@
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::
+This document assumes that you have installed the ZODB3 software
+(version 3.2 or higher) using a variation on the following command,
+given from the root directory of the ZODB3 distribution::
- python setup.py install
+ $ python setup.py install
This installs the packages ZConfig, ZEO, zdaemon, zLOG, ZODB and
various other needed packages and extension modules in the Python
@@ -32,6 +32,9 @@
(actually the bin directory from which the python interpreter was
loaded).
+When you receive ZODB as a part of Zope (version 2.7 or higher), the
+installation instructions will explain how to reach a similar state.
+
Introduction
------------
@@ -39,7 +42,7 @@
The most basic way to run a ZEO server is using the following
command::
- runzeo.py -a 9999 -f Data.fs
+ $ 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
@@ -56,7 +59,7 @@
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
+ $ runzeo.py -a 9999 -f Data.fs
------
2003-01-24T11:49:27 INFO(0) RUNSVR opening storage '1' using FileStorage
------
@@ -73,7 +76,7 @@
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
@@ -110,7 +113,7 @@
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
+ $ 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
@@ -122,12 +125,12 @@
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
+ $ 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
+ $ zdctl.py -p "runzeo.py -a 9999 -f Data.fs" stop
To check that is no longer running, use the zdctl status command
again.
@@ -139,17 +142,19 @@
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"::
+happening, after a whiile it can get 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
+ $ 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.
+redirected to /dev/null, and that the process is "detached" from your
+controlling tty, which implies that it won't receive a SIGHUP signal
+when you log out.
Using a configuration file
@@ -159,7 +164,7 @@
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
+a small configuration file; place this in the file "zeoctl.conf" (the
name is just a convention; you can call it "foo" if you prefer)::
# Sample zdctl/zdrun configuration
@@ -172,23 +177,78 @@
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 "socket-name" 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.
+specifies a directory into which zdrun (but not zdctl!) chdirs. This
+directory should exist; zdctl won't create it for you. The Data.fs
+filename passed to runzeo.py is interpreted relative to this
+directory. Finally, the "socket-name" 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
+ $ zdctl.py -C zeoctl.conf start
+
+ $ zdctl.py -C zeoctl.conf status
+
+ $ zdctl.py -C zeoctl.conf stop
Interactive mode
----------------
-XXX TBD
+Using a configuration file makes it a little easier to repeatedly
+start, stop and request status of a particular server, but it still
+requires typing the configuration file name on each command.
+Fortunately, zdctl.py can be used as an interactive "shell" which lets
+you execute repeated commands for the same server. Simply invoke
+zdctl.py without the final argument ("start", "status" or "stop" in
+the above examples)::
+
+ $ zdctl.py -C zeoctl.conf
+ program: runzeo.py -a 9999 -f Data.fs
+ daemon manager not running
+ zdctl>
+
+The first two lines of output are status messages (and could be
+different in your case); the final line is the interactive command
+prompt. At this prompt, you can type commands::
+
+ zdctl> help
+
+ Documented commands (type help <topic>):
+ ========================================
+ EOF fg foreground help kill
+ logreopen logtail quit reload restart
+ shell show start status stop
+ wait
+
+ zdctl> help start
+ start -- Start the daemon process.
+ If it is already running, do nothing.
+ zdctl> start
+ daemon process started, pid=31580
+ zdctl> status
+ program running; pid=31580
+ zdctl> stop
+ daemon process stopped
+ zdctl> quit
+ daemon manager not running
+ $
+
+In short, the commands you can type at the interactive prompt are the
+same commands (with optional arguments) that you can use as positional
+arguments on the zdctl.py command line.
+
+The interactive shell has some additional features:
+
+- Line editing and command line history using the standard GNU
+ readline module.
+
+- A blank line repeats the last command (especially useful for status).
+
+- Command and argument completion using the TAB key.
Using mkzeoinst.py