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

Jeremy Hylton jeremy at zope.com
Fri May 23 18:41:36 EDT 2003


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

Added Files:
	howto.txt 
Log Message:
Checkpoint progress on a ZEO howto.


=== Added File ZODB3/Doc/ZEO/howto.txt ===
Running a ZEO Server HOWTO
==========================

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

ZEO stands for Zope Enterprise Objects.  It is a client-server system
for sharing a single storage among many clients.  Normally, a ZODB
storage can only be used by a single process.  When you use ZEO, the
storage is opened in the ZEO server process.  Client programs connect
to this process using a ZEO ClientStorage.  ZEO provides a consistent
view of the database to all clients.  The ZEO client and server
communicate using a custom RPC protocol layered on top of TCP.

Installing software
-------------------

ZEO is distributed as part of the ZODB3 package and with Zope,
starting with Zope 2.7.  You can download it from:

- 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
------------------

The script ZEO/runzeo.py runs the ZEO server.  The server can be
configured using command-line arguments or a config file.  This
document describes only describes the config file.  Run ZEO/runzeo.py
-h to see the list of command-line arguments.

The runzeo.py script imports the ZEO package.  ZEO must either be
installed in Python's site-packages directory or be in a directory on
PYTHONPATH.  

The configuration file specifies the underlying storage the server
uses, the address it binds, and a few other optional parameters.
An example is:

    <zeo>
    address zeo.example.com:8090
    monitor-address zeo.example.com:8091
    </zeo>

    <filestorage 1>
    path /var/tmp/Data.fs
    </filestorage>

    <eventlog>
    <logfile>
    path /var/tmp/zeo.log
    format %(asctime)s %(message)s
    </logfile>
    </eventlog>

This file configures a server to use a FileStorage from
/var/tmp/Data.fs.  The server listens on port 8090 of zeo.example.com.
It also starts a monitor server that lists in port 8091.  The ZEO
server writes its log file to /var/tmp/zeo.log and uses a custom
format for each line.  Assuming the example configuration it stored in
zeo.config, you can run a server by typing:

    python ~/src/ZODB3/ZEO/runzeo.py -C zeo.config

A configuration file consists of a <zeo> section and a storage
section, where the storage section can use any of the valid ZODB
storage types.  It may also contain an eventlog configuration.  See
the document "Configuring a ZODB database" for more information about
configuring storages and eventlogs.

The zeo section must list the address.  All the other keys are
optional.

address

        The address at which the server should listen.  This can be in
        the form 'host:port' to signify a TCP/IP connection or a
        pathname string to signify a Unix domain socket connection (at
        least one '/' is required).  A hostname may be a DNS name or a
        dotted IP address.  If the hostname is omitted, the platform's
        default behavior is used when binding the listening socket (''
        is passed to socket.bind() as the hostname portion of the
        address).

read-only

        Flag indicating whether the server should operate in read-only
        mode.  Defaults to false.  Note that even if the server is
        operating in writable mode, individual storages may still be
        read-only.  But if the server is in read-only mode, no write
        operations are allowed, even if the storages are writable.  Note
        that pack() is considered a read-only operation.

invalidation-queue-size

        The storage server keeps a queue of the objects modified by the
        last N transactions, where N == invalidation_queue_size.  This
        queue is used to speed client cache verification when a client
        disconnects for a short period of time.

monitor-address

        The address at which the monitor server should listen.  If
        specified, a monitor server is started.  The monitor server
        provides server statistics in a simple text format.  This can
        be in the form 'host:port' to signify a TCP/IP connection or a
        pathname string to signify a Unix domain socket connection (at
        least one '/' is required).  A hostname may be a DNS name or a
        dotted IP address.  If the hostname is omitted, the platform's
        default behavior is used when binding the listening socket (''
        is passed to socket.bind() as the hostname portion of the
        address).

transaction-timeout

        The maximum amount of time to wait for a transaction to commit
        after acquiring the storage lock, specified in seconds.  If the
        transaction takes too long, the client connection will be closed
        and the transaction aborted.

Configuring client
------------------

The ZEO client can also be configured using ZConfig.  The ZODB.config
module provides several function for opening a storage based on its
configuration.

    ZODB.config.storageFromString()
    ZODB.config.storageFromFile()
    ZODB.config.storageFromURL()

The ZEO client configuration requires the server address be
specified.  Everything else is optional.  An example configuration is:

    <zeoclient>
    server zeo.example.com:8090
    </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.

storage

        The name of the storage that the client wants to use.  If the
        ZEO server serves more than one storage, the client selects
        the storage it wants to use by name.  The default name is '1',
        which is also the default name for the ZEO server.

cache-size

        The maximum size of the client cache, in bytes.

name

        The storage name.  If unspecified, the address of the server
        will be used as the name.

client

        Enables persistent cache files.  The string passed here is
        used to construct the cache filenames.  If it is not
        specified, the client creates a temporary cache that will
        only be used by the current object.

var

        The directory where persistent cache files are stored.  By
        default cache files, if they are persistent, are stored in 
        the current directory.

min-disconnect-poll

        The minimum delay in seconds between attempts to connect to
        the server, in seconds.  Defaults to 5 seconds.

max-disconnect-poll

        The maximum delay in seconds between attempts to connect to
        the server, in seconds.  Defaults to 300 seconds.

wait

        A boolean indicating whether the constructor should wait
        for the client to connect to the server and verify the cache
        before returning.  The default is true.

read-only

        A flag indicating whether this should be a read-only storage,
        defaulting to false (i.e. writing is allowed by default).

read-only-fallback

        A flag indicating whether a read-only remote storage should be
        acceptable as a fallback when no writable storages are
        available.  Defaults to false.  At most one of read_only and
        read_only_fallback should be true.

A ZEO client can also be created by calling the ClientStorage
constructor explicitly.  For example:

    from ZEO.ClientStorage import ClientStorage
    storage = ClientStorage(("zeo.example.com", 8090))

Running the ZEO server as a daemon
----------------------------------

ZEO features
------------

Client cache configuration
--------------------------

Setting the cache size.
Persistent or not.
cache trace.

Diagnosing problems
-------------------

How to use the debug logs.
Common gotchas.

Details
-------

How does the zrpc protocol work?




More information about the Zodb-checkins mailing list