[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