README

   1 Welcome to the AllMyData "tahoe" project. This project implements a
   2 secure, distributed, fault-tolerant storage mesh.
   3
   4 The basic idea is that the data in this storage mesh is spread over all
   5 participating nodes, using an algorithm that can recover the data even if a
   6 majority of the nodes are no longer available.
   7
   8 The interface to the storage mesh allows you to store and fetch files, either
   9 by self-authenticating cryptographic identifier or by filename and path.
  10
  11
  12 GETTING THE SOURCE CODE:
  13
  14  The code is available via darcs by running the following command:
  15
  16  darcs get http://allmydata.org/source/tahoe/trunk
  17
  18  See http://allmydata.org for all kinds of information, news, and community
  19  contributions.
  20
  21
  22 LICENCE:
  23
  24  Tahoe is offered under the GNU General Public License (v2 or later), with
  25  the added permission that, if you become obligated to release a derived work
  26  under this licence (as per section 2.b), you may delay the fulfillment of
  27  this obligation for up to 12 months.  See the COPYING file for details.
  28
  29
  30 DEPENDENCIES:
  31
  32  Note: All of the following dependencies can probably be installed through
  33  your standard package management tool if you are running on a modern Unix
  34  operating system.  If you are running any modern Linux or *BSD distribution
  35  then you can almost certainly get them through your standard package
  36  manager.  If you are running Mac OS X then the "fink" package management
  37  tool does not have most of these packages, but the "darwinports" package
  38  management tool appears to have them.  If you are running on Windows then
  39  I'm afraid you'll have to install them by hand (although the "cygwin"
  40  package management tool does have some of them).  If you are running on
  41  Solaris, I would like to hear from you -- I have no idea how it is done on
  42  Solaris nowadays.
  43
  44  * a C compiler (language)
  45
  46  * GNU make (build tool)
  47
  48  * Python 2.4 or newer (tested against 2.4, and 2.5.1, but v2.5 or higher is
  49    required on Windows-native), including development headers (language)
  50
  51    http://python.org/
  52
  53  * Python Twisted (tested against both 2.4 and 2.5) (network and operating
  54    system integration library)
  55
  56    http://twistedmatrix.com/
  57
  58    You need the following subpackages, which are included in the default
  59    Twisted distribution:
  60
  61    * core (the standard Twisted package)
  62    * web, trial, conch
  63
  64    Twisted requires zope.interface, a copy of which is included in the
  65    Twisted distribution.
  66
  67  * Python Nevow (probably 0.9.0 or later) (web presentation language)
  68
  69    http://divmod.org/trac/wiki/DivmodNevow
  70
  71  * Python setuptools (build and distribution tool)
  72
  73    http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions
  74
  75  * Python PyOpenSSL (0.6 or later) (secure transport layer)
  76
  77    http://pyopenssl.sourceforge.net
  78
  79    To install PyOpenSSL on Windows-native, download this:
  80    http://allmydata.org/source/pyOpenSSL-0.6.win32-py2.5.exe
  81
  82  * to build the debian packages you will need all the usual debian-packaging
  83    tools, which means the 'build-essential' metapackage and all of the
  84    packages listed as "Build-Depends" in DIST/debian/control for your
  85    distribution. You will also want the 'fakeroot' package to allow the
  86    top-level 'make deb-DIST' targets work.
  87
  88  * on Windows, the pywin32 package
  89
  90    http://sourceforge.net/projects/pywin32/
  91
  92
  93 BUILDING:
  94
  95  Just type 'make'. This works on Windows too, provided that you have the
  96  dependencies mentioned above (either a normal cygwin build or a mingw-style
  97  native build is supported by the makefile -- the cygwin build is the
  98  default).
  99
 100  If the desired version of 'python' is not already on your PATH, then type
 101  'make PYTHON=/path/to/your/preferred/python'.
 102
 103  'make test' runs the unit test suite.
 104
 105
 106 INSTALLING:
 107
 108  The Debian Way:
 109
 110   If you're running on a debian system, use 'make deb-dapper', 'make
 111   deb-sid', 'make deb-edgy', or 'make deb-feisty' to construct a debian
 112   package named 'allmydata-tahoe', which you can then install.
 113
 114  The Python Way:
 115
 116   You'll need to run four separate install steps, one for each of the four
 117   subpackages (allmydata, allmydata.Crypto, foolscap, and zfec).  If you use
 118   GNU stow, add the options "--prefix=." and
 119   "--root=/usr/local/stow/${PACKAGE}" to the "setup.py install" command.
 120
 121    for PACKAGE in zfec Crypto foolscap ; do
 122      cd src/${PACKAGE} && python setup.py install && cd ../..
 123    done
 124
 125    # the tahoe subpackage's setup.py script is in the root directory
 126    PACKAGE=tahoe
 127    python setup.py install
 128
 129  The Running-In-Place Way:
 130
 131   To run from a source tree (without installing first), type 'make', which
 132   will put all the necessary libraries into a local directory named
 133   "./instdir/", which you can then add to your PYTHONPATH .
 134
 135
 136  To Test That It Is Properly Installed:
 137
 138   To test that all the modules got installed properly, start a python
 139   interpreter and import modules as follows:
 140
 141    % python
 142    Python 2.4.4 (#2, Jan 13 2007, 17:50:26)
 143    [GCC 4.1.2 20061115 (prerelease) (Debian 4.1.1-21)] on linux2
 144    Type "help", "copyright", "credits" or "license" for more information.
 145    >>> import zfec
 146    >>> import allmydata.Crypto
 147    >>> import foolscap
 148    >>> import allmydata.interfaces
 149
 150
 151 RUNNING:
 152
 153  If you installed one of the debian packages constructed by "make deb-*" then
 154  it creates an 'allmydata-tahoe' executable, usually in /usr/bin . If you
 155  didn't install a package you can find allmydata-tahoe in bin/ . This tool is
 156  used to create, start, and stop nodes. Each node lives in a separate base
 157  directory, inside of which you can add files to configure and control the
 158  node. Nodes also read and write files within that directory.
 159
 160  A mesh consists of a single central 'introducer and vdrive' node and a large
 161  number of 'client' nodes. If you are joining an existing mesh, the
 162  introducer-and-vdrive node will already be running, and you'll just need to
 163  create a client node. If you're creating a brand new mesh, you'll need to
 164  create both an introducer-and-vdrive and a client (and then invite other
 165  people to create their own client nodes and join your mesh).
 166
 167  The introducer (-and-vdrive) node is constructed by running 'allmydata-tahoe
 168  create-introducer --basedir $HERE'. Once constructed, you can start the
 169  introducer by running 'allmydata-tahoe start --basedir $HERE' (or, if you
 170  are already in the introducer's base directory, just type 'allmydata-tahoe
 171  start'). Inside that base directory, there will be a pair of files
 172  'introducer.furl' and 'vdrive.furl'. Make a copy of these, as they'll be
 173  needed on the client nodes.
 174
 175  To construct a client node, pick a new working directory for it, then run
 176  'allmydata-tahoe create-client --basedir $HERE'. Copy the two .furl files
 177  from the introducer into this new directory, then run 'allmydata-tahoe start
 178  --basedir $HERE'. After that, the client node should be off and running. The
 179  first thing it will do is connect to the introducer and introduce itself to
 180  all other nodes on the mesh. You can follow its progress by looking at the
 181  $HERE/twistd.log file.
 182
 183  To actually use the client, enable the web interface by writing a port
 184  number (like "8080") into a file named $HERE/webport and then restarting the
 185  node with 'allmydata-tahoe restart --basedir $HERE'. This will prompt the
 186  client node to run a webserver on the desired port, through which you can
 187  view, upload, download, and delete files.
 188
 189  A client node directory can also be created without installing the code
 190  first. Just use 'make create-client', and a new directory named 'CLIENTDIR'
 191  will be created inside the top of the source tree. Copy the relevant .furl
 192  files in, set the webport, then start the node by using 'make start-client'.
 193  To stop it again, use 'make stop-client'. Similar makefile targets exist for
 194  making and running an introducer node.
 195
 196  There is a public mesh available for testing. Look at the wiki page
 197  (http://allmydata.org) for the necessary .furl data.
 198