Skip to content

Z
ZODB
Commit 3c8e20f1 authored by Jim Fulton's avatar Jim Fulton
Browse files
Options

Documentation cleanup.

parent 43d0a0f8
Show whitespace changes
Inline Side-by-side
Showing with 10 additions and 516 deletions
doc/Makefile deleted 100644 → 0
View file @ 43d0a0f8
MKHOWTO=mkhowto
MKHTML=$(MKHOWTO) --html --iconserver=. --split=4 --dvips-safe
ZODBTEX = guide/gfdl.tex guide/introduction.tex guide/modules.tex \
guide/prog-zodb.tex guide/storages.tex guide/transactions.tex \
guide/zeo.tex guide/zodb.tex
default: pdf
all: pdf ps html
pdf: storage.pdf zodb.pdf
ps: storage.ps zodb.ps
html: storage/storage.html zodb/zodb.html
storage.pdf: storage.tex
$(MKHOWTO) --pdf $<
storage.ps: storage.tex
$(MKHOWTO) --ps $<
storage/storage.html: storage.tex
$(MKHTML) storage.tex
zodb.pdf: $(ZODBTEX)
$(MKHOWTO) --pdf guide/zodb.tex
zodb.ps: $(ZODBTEX)
$(MKHOWTO) --ps guide/zodb.tex
zodb/zodb.html: $(ZODBTEX)
$(MKHTML) guide/zodb.tex
clobber:
rm -rf storage.pdf storage.ps storage/ zodb.pdf zodb.ps zodb/
doc/ZEO/README.txt deleted 100644 → 0
View file @ 43d0a0f8
ZEO Documentation
=================
This directory contains ZEO documentation.
howto.txt
The first place to look.
It provides a high-level overview of ZEO features and details on
how to install and configure clients and servers. Includes a
configuration reference.
cache.txt
Explains how the client cache works.
trace.txt
Describe cache trace tool used to determine ideal cache size.
ZopeREADME.txt
A somewhat dated description of how to integrate ZEO with Zope.
It provides a few hints that are not yet in howto.txt.
doc/ZEO/ZopeREADME.txt deleted 100644 → 0
View file @ 43d0a0f8
Zope Enterprise Objects (ZEO)
Installation
ZEO 2.0 requires Zope 2.4 or higher and Python 2.1 or higher.
If you use Python 2.1, we recommend the latest minor release
(2.1.3 as of this writing) because it includes a few bug fixes
that affect ZEO.
Put the package (the ZEO directory, without any wrapping directory
included in a distribution) in your Zope lib/python.
The setup.py script in the top-level ZEO directory can also be
used. Run "python setup.py install --home=ZOPE" where ZOPE is the
top-level Zope directory.
You can test ZEO before installing it with the test script::
python test.py -v
Run the script with the -h option for a full list of options. The
ZEO 2.0b2 release contains 122 unit tests on Unix.
Starting (and configuring) the ZEO Server
To start the storage server, go to your Zope install directory and
run::
python lib/python/ZEO/start.py -p port_number
This run the storage sever under zdaemon. zdaemon automatically
restarts programs that exit unexpectedly.
The server and the client don't have to be on the same machine.
If they are on the same machine, then you can use a Unix domain
socket::
python lib/python/ZEO/start.py -U filename
The start script provides a number of options not documented here.
See doc/start.txt for more information.
Running Zope as a ZEO client
To get Zope to use the server, create a custom_zodb module,
custom_zodb.py, in your Zope install directory, so that Zope uses a
ClientStorage::
from ZEO.ClientStorage import ClientStorage
Storage = ClientStorage(('', port_number))
You can specify a host name (rather than '') if you want. The port
number is, of course, the port number used to start the storage
server.
You can also give the name of a Unix domain socket file::
from ZEO.ClientStorage import ClientStorage
Storage = ClientStorage(filename)
There are a number of configuration options available for the
ClientStorage. See doc/ClientStorage.txt for details.
If you want a persistent client cache which retains cache contents
across ClientStorage restarts, you need to define the environment
variable, ZEO_CLIENT, or set the client keyword argument to the
constructor to a unique name for the client. This is needed so
that unique cache name files can be computed. Otherwise, the
client cache is stored in temporary files which are removed when
the ClientStorage shuts down. For example, to start two Zope
processes with unique caches, use something like::
python z2.py -P8700 ZEO_CLIENT=8700
python z2.py -P8800 ZEO_CLIENT=8800
Zope product installation
Normally, Zope updates the Zope database during startup to reflect
product changes or new products found. It makes no sense for
multiple ZEO clients to do the same installation. Further, if
different clients have different software installed, the correct
state of the database is ambiguous.
Zope will not modify the Zope database during product installation
if the environment variable ZEO_CLIENT is set.
Normally, Zope ZEO clients should be run with ZEO_CLIENT set so
that product initialization is not performed.
If you do install new Zope products, then you need to take a
special step to cause the new products to be properly registered
in the database. The easiest way to do this is to start Zope
once with the environment variable FORCE_PRODUCT_LOAD set.
The interaction between ZEO and Zope product installation is
unfortunate.
doc/zdctl.txt deleted 100644 → 0
View file @ 43d0a0f8
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
documented 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
(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
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).
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
------------
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::
$ 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'
$
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, 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
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, 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
--------------------------
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 "zeoctl.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
socket-name /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. 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::
$ zdctl.py -C zeoctl.conf start
$ zdctl.py -C zeoctl.conf status
$ zdctl.py -C zeoctl.conf stop
Interactive mode
----------------
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.
One final note: some people don't like it that an invocation without
arguments enters interactive mode. If this describes you, there's an
easy way to disable this feature: add a line saying
default-to-interactive false
to the zeoctl.conf file. You can still enter interactive mode by
using the -i option.
Using mkzeoinst.py
------------------
If you still think that all of the above is a lot of typing, you're
right. Fortunately, there's a simple utility that help you creating
and configuring a ZEO server instance. mkzeoinst.py requires one
argument, the ZEO server's "home directory". After that, you can
optionally specify a service port number; the port defaults to 9999.
mkzeoinst.py creates the server home directory (and its ancestor
directories if necessary), and then creates the following directory
substructure:
bin/ - directory for scripts (zeoctl)
etc/ - directory for configuration files (zeo.conf, zeoctl.conf)
log/ - directory for log files (zeo.log, zeoctl.log)
var/ - directory for data files (Data.fs and friends)
If the server home directory or any of its subdirectories already
exist, mkzeoinst.py will note this and assume you are rebuilding an
existing instance. (In fact, it prints a message for each directory
it creates but is silent about existing directories.)
It then creates the following files:
bin/zeoctl - executable shell script to run zdctl.py
etc/zeo.conf - configuration file for ZEO
etc/zeoctl.conf - configuration file for zdrun.py and zdctl.py
If any of the files it wants to create already exists and is
non-empty, it does not write the file. (An empty file will be
overwritten though.) If the existing contents differ from what it
would have written if the file didn't exist, it prints a warning
message; otherwise the skipping is silent.
Other errors (e.g. permission errors creating or reading files or
directories) cause mkzeoinst.py to bail with an error message; it does
not clean up the work already done.
The created files contain absolute path references to all of the
programs, files, directories used. They also contain default values
for most configuration settings that one might normally want to
configure. Most configured settings are the same as the defaults;
however, daemon mode is on while the regular default is off. Log
files are configured to go into the log directory. If configures
separate log files for zdrun.py/zdctl.py (log/zeoctl.log) and for the
ZEO server itself (log/zeo.log). Once created, the files are yours;
feel free to edit them to suit your taste.
The bin/zeoctl script should be invoked with the positional arguments
(e,g, "start", "stop" or "status") that you would pass to zdctl.py;
the script hardcodes the configuration file so you don't have to pass
that. It can also be invoked without arguments to enter interactive
mode.
One final detail: if you want the ZEO server to be started
automatically when the machine is rebooted, and you're lucky enough to
be using a recent Red Hat (or similar) system, you can copy the
bin/zeoctl script into the /etc/rc.d/init.d/ directory and use
chkconfig(8) to create the correct symlinks to it; the bin/zeoctl
script already has the appropriate magical comments for chkconfig.
zdctl reference
---------------
TBD
zdrun reference
---------------
TBD
doc/ZEO/howto.txt → doc/zeo.txt
View file @ 3c8e20f1
...@@ -142,10 +142,10 @@ Connection management ...@@ -142,10 +142,10 @@ Connection management
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
A ZEO client manages its connection to the ZEO server. If it loses A ZEO client manages its connection to the ZEO server. If it loses
the connection, it starts a thread that attempts to reconnect. While the connection, it attempts to reconnect. While
it is disconnected, it can satisfy some reads by using its cache. it is disconnected, it can satisfy some reads by using its cache.
The client can be configured to wait a connection when it is created The client can be configured to wait for a connection when it is created
or to return immediately and provide data from its persistent cache. or to return immediately and provide data from its persistent cache.
It usually simplifies programming to have the client wait for a It usually simplifies programming to have the client wait for a
connection on startup. connection on startup.
...@@ -192,27 +192,15 @@ Installing software ...@@ -192,27 +192,15 @@ Installing software
------------------- -------------------
ZEO is distributed as part of the ZODB3 package and with Zope, ZEO is distributed as part of the ZODB3 package and with Zope,
starting with Zope 2.7. You can download it from: starting with Zope 2.7. You can download it from
http://pypi.python.org/pypi/ZODB3.
- http://www.zope.org/Products/ZODB3.2, or
- http://www.zope.org/Products/Zope
To use ZEO with Zope 2.6, download ZODB3.2 and install it into your
Zope software home. ZODB3 comes with a distutils setup.py script.
You can use the --home option to setup.py install to the software in
custom location. For example, if Zope is installed in /home/zope,
then this command will install the new ZEO and ZODB:
python setup.py install --home /home/zope
The install command should create a /home/zope/lib/python/ZEO directoy.
Configuring server Configuring server
------------------ ------------------
The script runzeo.py runs the ZEO server. The server can be The script runzeo.py runs the ZEO server. The server can be
configured using command-line arguments or a config file. This configured using command-line arguments or a config file. This
document describes only describes the config file. Run runzeo.py document only describes the config file. Run runzeo.py
-h to see the list of command-line arguments. -h to see the list of command-line arguments.
The runzeo.py script imports the ZEO package. ZEO must either be The runzeo.py script imports the ZEO package. ZEO must either be
...@@ -312,8 +300,8 @@ authentication-realm ...@@ -312,8 +300,8 @@ authentication-realm
schemes use a realm to identify the logic set of usernames schemes use a realm to identify the logic set of usernames
that are accepted by this server. that are accepted by this server.
Configuring client Configuring clients
------------------ -------------------
The ZEO client can also be configured using ZConfig. The ZODB.config The ZEO client can also be configured using ZConfig. The ZODB.config
module provides several function for opening a storage based on its module provides several function for opening a storage based on its
...@@ -330,12 +318,6 @@ specified. Everything else is optional. An example configuration is:: ...@@ -330,12 +318,6 @@ specified. Everything else is optional. An example configuration is::
server zeo.example.com:8090 server zeo.example.com:8090
</zeoclient> </zeoclient>
To use a ZEO client from Zope, write a configuration file and load it
from custom_zodb.py::
from ZODB.config import storageFromURL
Storage = storageFromURL("/path/to/client.txt")
The other configuration options are listed below. The other configuration options are listed below.
storage storage
...@@ -400,9 +382,9 @@ Running the ZEO server as a daemon ...@@ -400,9 +382,9 @@ Running the ZEO server as a daemon
In an operational setting, you will want to run the ZEO server a In an operational setting, you will want to run the ZEO server a
daemon process that is restarted when it dies. The zdaemon package daemon process that is restarted when it dies. The zdaemon package
provides two tools for running daemons: zdrun.py and zdctl.py. The provides two tools for running daemons: zdrun.py and zdctl.py. You can
document "Using zdctl and zdrun to manage server processes" find zdaemon and it's documentation at
(Doc/zdctl.txt) explains how to use these scripts to manage daemons. http://pypi.python.org/pypi/zdaemon.
Rotating log files Rotating log files
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7