README

   1 Welcome to the Allmydata-Tahoe project.  This project implements a secure,
   2 distributed, fault-tolerant storage grid.  All of the source code is available
   3 under a Free Software licence.
   4
   5 The basic idea is that the data in this storage grid is spread over all
   6 participating nodes, using an algorithm that can recover the data even if a
   7 majority of the nodes are no longer available.
   8
   9 The interface to the storage grid allows you to store and fetch files, either
  10 by self-authenticating cryptographic identifier or by filename and path.
  11
  12 See the web site for all kinds of information, news, and community
  13 contributions, and prebuilt packages for Debian-like systems:
  14
  15 http://allmydata.org
  16
  17
  18 LICENCE:
  19
  20  Tahoe is offered under the GNU General Public License (v2 or later), with
  21  the added permission that, if you become obligated to release a derived work
  22  under this licence (as per section 2.b), you may delay the fulfillment of
  23  this obligation for up to 12 months.  If you are obligated to release code
  24  under section 2.b of this licence, you are obligated to release it under
  25  these same terms, including the 12-month grace period clause.  See the
  26  COPYING file
  27  for details.
  28
  29
  30 GETTING PRECOMPILED BINARIES:
  31
  32 See http://allmydata.org .  Currently pre-compiled binaries are available
  33 only for Debian or Ubuntu.  For any other platform you have to build it
  34 yourself from source, which is what this text file is all about.
  35
  36
  37 GETTING THE SOURCE CODE:
  38
  39 The code is available via darcs by running the following command:
  40
  41 darcs get http://allmydata.org/source/tahoe/trunk tahoe
  42
  43 This will create a directory named "tahoe" in the current working directory
  44 and put a copy of the latest source code into it.  Later, if you want to get
  45 any new changes, then cd into that directory and run the command "darcs
  46 pull".
  47
  48 Tarballs of sources are available at:
  49
  50 http://allmydata.org/source/tahoe/
  51
  52
  53 DEPENDENCIES:
  54
  55 Note: All of the following dependencies can probably be installed through
  56 your standard package management tool if you are running on a modern Unix
  57 operating system.
  58
  59 For example, on an debian-like system, you can do "sudo apt-get install
  60 gcc make python-dev python-twisted python-nevow python-pyopenssl".
  61
  62  + a C compiler (language)
  63
  64  + GNU make (build tool)
  65
  66  + Python 2.4 or newer (tested against 2.4, and 2.5.1 -- on Windows-native
  67    Python 2.5 or higher is required), including development headers (language)
  68
  69    http://python.org/
  70
  71  + Python Twisted (tested against both 2.4 and 2.5) (network and operating
  72    system integration library)
  73
  74    http://twistedmatrix.com/
  75
  76    You need the following subpackages, which are included in the default
  77    Twisted distribution:
  78
  79    * core (the standard Twisted package)
  80    * web, trial, conch
  81
  82    Twisted requires zope.interface, a copy of which is included in the
  83    Twisted distribution.
  84
  85  + Python Nevow (0.9.18 or later) (web presentation language)
  86
  87    http://divmod.org/trac/wiki/DivmodNevow
  88
  89  + Python setuptools (build and distribution tool)
  90
  91    Note: The build process will automatically download and install setuptools
  92    if it is not present.  However, if an old, incompatible version of
  93    setuptools is present (< v0.6c6 on Cygwin, or < v0.6a9 on other
  94    platforms), then the build will fail.
  95
  96    So if the build fails due to setuptools not being compatible, you can
  97    either upgrade or uninstall your version of setuptools and try again.
  98
  99    http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions
 100
 101  + Python PyOpenSSL (0.6 or later) (secure transport layer)
 102
 103    http://pyopenssl.sourceforge.net
 104
 105    To install PyOpenSSL on Windows-native, download this:
 106    http://allmydata.org/source/pyOpenSSL-0.6.win32-py2.5.exe
 107
 108    To install PyOpenSSL on Windows-cygwin, install the OpenSSL development
 109    libraries with the cygwin package management tool, then get the pyOpenSSL
 110    source code, cd into it, and run "python ./setup.py install".
 111
 112  + pysqlite3 (database library)
 113
 114  + the pywin32 package: only required on Windows
 115
 116    http://sourceforge.net/projects/pywin32/
 117
 118    (Tested with build 210, and known to not work with build 204.
 119    Feedback with details of other builds is greatly appreciated)
 120
 121
 122 Tahoe uses a few additional libraries which are included in this source
 123 distribution for convenience. These will be automatically built when you type
 124 'make', but if you have separate installations of them you may wish to modify
 125 the makefile to use those in preference to the included versions. They
 126 include Foolscap (a secure remote-object-invocation library) and zfec
 127 (erasure coding). There are also pieces of PyCrypto copied into
 128 allmydata.Crypto, modified to provide a faster CTR-mode API.
 129
 130
 131 BUILDING:
 132
 133  Just type 'make' in the top-level tahoe directory.  This works on Windows
 134  too, provided that you have the dependencies mentioned above.  (Either a
 135  normal cygwin build or a mingw-style native build will be done by the
 136  makefile, depending on whether the version of python that you have installed
 137  is the Windows-native python or the cygwin python.)
 138
 139  If the desired version of 'python' is not already on your PATH, then type
 140  'make PYTHON=/path/to/your/preferred/python'.
 141
 142  'make test-all' runs the unit test suites.  (This can take a long time on
 143  slow computers.  There are a lot of tests and some of them do a lot of
 144  public-key cryptography.)
 145
 146
 147 INSTALLING:
 148
 149 There are three ways to do it: The Debian Way, The Python Way, and The
 150 Running-In-Place Way.  Choose one:
 151
 152  The Debian Way:
 153
 154   The Debian Way is to build .deb files which you can then install with
 155   "dpkg".
 156
 157   This requires certain debian packages (build-essential, fakeroot,
 158   devscripts, debhelper, cdbs) to be installed first, since they are used to
 159   construct the tahoe .deb files. A full list of these required packages can
 160   be found in the "Build-Depends" line in the misc/DIST/debian/control in the
 161   top-level tahoe directory (replacing the word DIST with etch, dapper, edgy,
 162   or feisty as appropriate).
 163
 164   If you're running on a debian system, run 'make deb-etch', 'make deb-sid',
 165   'make deb-edgy', or 'make deb-feisty' from within the tahoe top-level
 166   directory to construct a debian package named 'allmydata-tahoe' which you
 167   can then install with dpkg.
 168
 169  The Python Way:
 170
 171   Just run make install.  (This works on cygwin and Windows, too.)
 172
 173   In case you want to configure the location or other install options you can
 174   learn how it is done here:
 175
 176   The Python Way is to execute "setup.py install" for each Python package.
 177
 178   You'll need to run "setup.py install" four separate times, one for each of
 179   the four subpackages (allmydata, foolscap, simplejson, and zfec).
 180
 181     for PACKAGE in zfec foolscap simplejson; do
 182       cd src/${PACKAGE} && python setup.py install && cd ../..
 183     done
 184
 185     # the tahoe subpackage's setup.py script is in the root directory
 186     PACKAGE=tahoe
 187     python setup.py install
 188
 189  The Running-In-Place Way:
 190
 191   The Running-In-Place Way is to add a directory to your PYTHONPATH.
 192
 193   To run from a source tree (without installing first) just build it
 194   (i.e. type 'make'), which will put all the necessary libraries into a local
 195   directory named "./instdir/lib", which you can then add to your
 196   PYTHONPATH .  It will put executables into "./instdir/bin".
 197
 198
 199 TESTING THAT IT IS PROPERLY INSTALLED
 200
 201  To test that all the modules got installed properly, cd to the root
 202  directory of the tahoe source distribution (the directory which contains
 203  this README file), start a python interpreter and import modules as follows.
 204  If each one imports successfully instead of raising ImportError then it is
 205  correctly installed.
 206
 207    % python
 208    Python 2.4.4 (#2, Jan 13 2007, 17:50:26)
 209    [GCC 4.1.2 20061115 (prerelease) (Debian 4.1.1-21)] on linux2
 210    Type "help", "copyright", "credits" or "license" for more information.
 211    >>> import zfec
 212    >>> import allmydata.Crypto
 213    >>> import foolscap
 214    >>> import allmydata.interfaces
 215
 216
 217 RUNNING:
 218
 219  If you installed one of the debian packages constructed by "make deb-*", or
 220  installed "The Python Way", then it creates an 'allmydata-tahoe' executable,
 221  usually in /usr/bin . Else, you can find allmydata-tahoe in ./instdir/bin/ .
 222  This tool is used to create, start, and stop nodes.  Each node lives in a
 223  separate base directory, inside of which you can add files to configure and
 224  control the node.  Nodes also read and write files within that directory.
 225
 226  A grid consists of a single central 'introducer and vdrive' node and one or
 227  more 'client' nodes.  If you are joining an existing grid, the
 228  introducer-and-vdrive node will already be running, and you'll just need to
 229  create a client node.  If you're creating a brand new grid, you'll need to
 230  create both an introducer-and-vdrive and a client (and then invite other
 231  people to create their own client nodes and join your grid).
 232
 233  The introducer (-and-vdrive) node is constructed by running 'allmydata-tahoe
 234  create-introducer --basedir $HERE'.  Once constructed, you can start the
 235  introducer by running 'allmydata-tahoe start --basedir $HERE' (or, if you
 236  are already in the introducer's base directory, just type 'allmydata-tahoe
 237  start').  Inside that base directory, there will be a pair of files
 238  'introducer.furl' and 'vdrive.furl'.  Make a copy of these, as they'll be
 239  needed on the client nodes.
 240
 241  To construct a client node, pick a new working directory for it, then run
 242  'allmydata-tahoe create-client --basedir $HERE'.  Copy the two .furl files
 243  from the introducer into this new directory, then run 'allmydata-tahoe start
 244  --basedir $HERE'.  After that, the client node should be off and running.
 245  The first thing it will do is connect to the introducer and introduce itself
 246  to all other nodes on the grid.  You can follow its progress by looking at
 247  the $HERE/logs/twistd.log file.
 248
 249  To actually use the client, enable the web interface by writing a port
 250  number (like "8080") into a file named $HERE/webport and then restarting the
 251  node with 'allmydata-tahoe restart --basedir $HERE'. This will prompt the
 252  client node to run a webserver on the desired port, through which you can
 253  view, upload, download, and delete files. This 'webport' file is actually a
 254  "strports specification", defined in
 255  http://twistedmatrix.com/documents/current/api/twisted.application.strports.html
 256  , so you can have it only listen on a local interface by writing
 257  "tcp:8080:interface=127.0.0.1" to this file, or make it use SSL by writing
 258  "ssl:8443:privateKey=mykey.pem:certKey=cert.pem" instead.
 259
 260  A client node directory can also be created without installing the code
 261  first.  Just use 'make create-client', and a new directory named 'CLIENTDIR'
 262  will be created inside the top of the source tree.  Copy the relevant .furl
 263  files in, set the webport, then start the node by using 'make start-client'.
 264  To stop it again, use 'make stop-client'.  Similar makefile targets exist
 265  for making and running an introducer node.
 266
 267  If you are behind a firewall and you can configure your firewall to forward
 268  TCP connections on a port to the computer running your Tahoe node, then you
 269  can configure the Tahoe node to announce itself as being available on that
 270  IP address and port.  The way to do this is to create a file named
 271  $HERE/advertised_ip_addresses, in which you can put IP addresses and port numbers in
 272  "dotted-quad:port" form, e.g. "209.97.232.113:1345".  You can put multiple
 273  IP-address-and-port-number entries into this file, on separate lines.
 274
 275  There is a public grid available for testing.  Look at the wiki page
 276  (http://allmydata.org) for the necessary .furl data.
 277