*********************
  ZFN Documentation
*********************

:Author: Ross Light
:Status: In-progress
:Version: 0.2.0b1
:Homepage: http://launchpad.net/zfilenet

Welcome to the Zero-Configuration File Network!  Please read the following
instructions to get started.

For up-to-date information on the latest releases, see the release notes.

.. contents::

==============
 Requirements
==============

* Python_ 2.5
* simplejson_ 1.7.4
* `zope.interface`_ 3.3.1
* Twisted_ 2.5.0
* PyBonjour_ 1.1.1
* SQLAlchemy_ 0.4.6

.. _Python: http://www.python.org/
.. _simplejson: http://www.undefined.org/python/
.. _zope.interface: http://www.zope.org/Products/ZopeInterface
.. _Twisted: http://twistedmatrix.com/
.. _PyBonjour: http://o2s.csail.mit.edu/o2s-wiki/pybonjour
.. _SQLAlchemy: http://www.sqlalchemy.org/

However, once you have Python_ 2.5, the installer script can automatically
install the other dependencies for you.

.. Important::
    ZFN makes extensive use of Bonjour for automatic discovery of servers on a
    local network.  However, it requires a compatible library to be installed
    in order to work.  For Mac OS X, Bonjour is already built in to the
    operating system.  Linux systems need the Avahi_ DNS-SD compatibility layer
    (if it is not already installed).  Windows users will need to download and
    install Apple's `Bonjour for Windows`_ kit.
    
    The installer script **will not** automatically install the Bonjour
    back-end for you; you must install it yourself.

.. _Avahi: http://avahi.org/
.. _Bonjour for Windows: http://developer.apple.com/networking/bonjour/download/

==============
 Installation
==============

Currently, the easiest way to install ZFN is through the `easy_install`_
script.  easy_install is a package manager for Python software.

.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall

After downloading and installing easy_install, run the following command to
install ZFN::

    easy_install http://zfilenet.googlecode.com/files/zfn-0.2.0b1-py2.5.egg

You may have to run this command as an administrator or root, depending on your
system.

Installing from source
++++++++++++++++++++++++

To install from source, download one of the source packages from the ZFN
downloads page, then extract the contents.  Open your system's command prompt
and navigate to the source directory, then run::

    python setup.py install

You may have to run this command as an administrator or root, depending on your
system.

.. Note::
    The installer script uses setuptools_, a library which simplifies
    many aspects of Python software installation.  However, setuptools
    is not a part of the standard library.  If you do not already have
    setuptools installed, the installer script will try to download it
    for you, but this requires an internet connection.
    
    Also be aware that if you do not have all of the dependencies
    installed ahead of time, the installer script will try to connect to
    the internet and install them for you.

.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools

===================
 Administering ZFN
===================

The general procedure for administering a ZFN share is:

1. Run blob servers on all machines
2. Run an index server on a host machine

Blob Servers
++++++++++++++

Blob servers are the storage servers of ZFN; they are the ones that actually
store all the data.  Blob servers can't be connected to directly, but are
managed by index servers.  Adding more blob servers means adding more storage
space to your share.

A blob server needs to be run on every computer.  Whether this is registered
with your OS's scheduling mechanism or executed manually is your decision.
Computers may run multiple blob servers simultaneously (as long as they aren't
using the same blob database).

The blob server program is invoked as follows::

    zfn-blobserver database_file

``database_file`` should be replaced with the name of the database file you want
to use.  If you do not specify a file, the file ``zfn_blob.db`` in the current
directory will be used.  For more help on running the blob server, type
``zfn-blobserver --help`` at the command line.

Index Servers
+++++++++++++++

Index servers are the managers of ZFN; they hold the directory structure and
allow access to the data.  Currently, you are limited to using only one index
server on the network at a time.

An index server should only be run on one computer, preferably one that is
turned on most of the time.

The index server program is invoked as follows::

    zfn-indexserver database_file

``database_file`` should be replaced with the name of the database file you want
to use.  If you do not specify a file, the file ``zfn_index.db`` in the current
directory will be used.  For more help on running the index server and options
available, type ``zfn-indexserver --help`` at the command line.

===============
 Accessing ZFN
===============

ZFN aims to be easy to access from a variety of different means, so servers can
be accessed through several means.

WebDAV Access
+++++++++++++++

The most common way to access ZFN is through `WebDAV`_.  WebDAV is a common
protocol for file-sharing over the internet, and is usually represented on the
desktop as a disk.

.. _WebDAV: http://webdav.org/

However, the method of connecting varies from platform to platform.

Mac OS X
##########

:Compatibility: Full access

In the Finder, choose "Go > Connect to Server...".  Type the following text
into the "Server Address" field::

    http://my.machine:47800/

Replace ``my.machine`` with the name of the computer that is running the
index server.  Click "Connect" at the bottom of the window.

Windows XP
############

:Compatibility: Read and write, but some operations are limited

Open up the "My Network Places" location in the Explorer.  Click the "Add a
network place" item in the sidebar.  Click "Next" to bypass the description
page.  Select "Choose another network location" from the list and click "Next"
to continue.  In the "Internet or network address" field, enter in::

    http://my_machine:47800/

Replace ``my.machine`` with the name of the computer that is running the
index server.  Click "Next".  Now type in a name for your shortcut.  Click
"Next" and then click "Finish".

GNOME
#######

:Compatibility: Full access

In Nautilus, choose "Places > Connect to Server...".  Choose "WebDAV (HTTP)"
from the "Service type" menu.  Type in the name of the index server's computer
in the "Server" field and "47800" in the "Port" field.  Click "Connect" at the
bottom of the window.

Text Client Access
++++++++++++++++++++

Another way to access the data in a ZFN share is by using the command-line
client.  This is usually most useful for developers and command-line users.

At the command line, type::

    zfn-client host ls /

where ``host`` is the name of the computer running the index server.  This
should present you with a list of all the files in the root of the ZFN share.

For more help on running the client and options available, type
``zfn-client --help`` at the command line.

JSON-RPC Access
+++++++++++++++++

For programmers wishing to integrate with ZFN, the index server exposes a
`JSON-RPC`_ API for accessing the files.  JSON-RPC is a light-weight networking
protocol that already has libraries available for many common languages.

.. _JSON-RPC: http://json-rpc.org/

Unfortunately, the API is mostly undocumented at this point, but should be
mostly stable.  For reference, examine the ``simpleclient.py`` source to see
how to access the share.  ``simpleclient.py`` is the back-end to the text
client (see `Text Client Access`_), and serves as a useful example of what is
possible with the API.