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