README

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