docs/running.rst

   1 =====================
   2 How To Run Tahoe-LAFS
   3 =====================
   4
   5 Intro
   6 =====
   7
   8 This is how to run a Tahoe-LAFS client or a complete Tahoe-LAFS grid.
   9 First you have to install the Tahoe-LAFS software, as documented in
  10 `quickstart.rst <quickstart.rst>`_.
  11
  12 The ``tahoe`` program in the ``bin`` directory is used to create,
  13 start, and stop nodes. Each node lives in a separate base directory, in
  14 which there is a configuration file named ``tahoe.cfg``. Nodes read and
  15 write files within this base directory.
  16
  17 A grid consists of a set of *storage nodes* and *client nodes* running
  18 the Tahoe-LAFS code. There is also an *introducer node* that is
  19 responsible for getting the other nodes talking to each other.
  20
  21 If you're getting started we recommend you try connecting to
  22 the `the public test grid
  23 <http://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid>`_ as you only
  24 need to create a client node. When you want to create your own grid
  25 you'll need to create the introducer and several initial storage nodes
  26 (see the note about small grids below).
  27
  28 If the Tahoe-LAFS ``bin`` directory is not on your PATH, then in all
  29 the command lines below, specify the full path to ``bin/tahoe``.
  30
  31 To construct a client node, run "``tahoe create-client``", which will
  32 create ``~/.tahoe`` to be the node's base directory. Acquire a copy of
  33 the ``introducer.furl`` from the introducer and put it into this
  34 directory, then use "``tahoe run``". After that, the node should be off
  35 and running. The first thing it will do is connect to the introducer
  36 and get itself connected to all other nodes on the grid.  By default,
  37 "``tahoe create-client``" creates a client-only node, that does not
  38 offer its disk space to other nodes. To configure other behavior, use
  39 "``tahoe create-node``" or see `configuration.rst <configuration.rst>`_.
  40
  41 To construct an introducer, create a new base directory for it (the
  42 name of the directory is up to you), ``cd`` into it, and run
  43 "``tahoe create-introducer .``". Now run the introducer using
  44 "``tahoe start .``". After it starts, it will write a file named
  45 ``introducer.furl`` in that base directory. This file contains the URL
  46 the other nodes must use in order to connect to this introducer. (Note
  47 that "``tahoe run .``" doesn't work for introducers, this is a known
  48 issue: `#937 <http://allmydata.org/trac/tahoe-lafs/ticket/937>`_.)
  49
  50 The "``tahoe run``" command above will run the node in the foreground.
  51 On Unix, you can run it in the background instead by using the
  52 "``tahoe start``" command. To stop a node started in this way, use
  53 "``tahoe stop``". ``tahoe --help`` gives a summary of all commands.
  54
  55 See `configuration.rst <configuration.rst>`_ for more details about how
  56 to configure Tahoe-LAFS, including how to get other clients to connect
  57 to your node if it is behind a firewall or NAT device.
  58
  59 A note about small grids
  60 ------------------------
  61
  62 By default, Tahoe-LAFS ships with the configuration parameter
  63 ``shares.happy`` set to 7. If you are using Tahoe-LAFS on a
  64 grid with fewer than 7 storage nodes, this won't work well for you
  65 &mdash; none of your uploads will succeed. To fix this, see <a
  66 href='configuration.rst'>configuration.rst</a> to learn how to set
  67 ``shares.happy`` to a more suitable value for your
  68 grid.
  69
  70 Do Stuff With It
  71 ================
  72
  73 This is how to use your Tahoe-LAFS node.
  74
  75 The WUI
  76 -------
  77
  78 Point your web browser to `http://127.0.0.1:3456
  79 <http://127.0.0.1:3456>`_ -- which is the URL of the gateway running on
  80 your own local computer -- to use your newly created node.
  81
  82 Create a new directory (with the button labelled "create a directory").
  83 Your web browser will load the new directory.  Now if you want to be
  84 able to come back to this directory later, you have to bookmark it, or
  85 otherwise save a copy of the URL.  If you lose URL to this directory,
  86 then you can never again come back to this directory.
  87
  88 You can do more or less everything you want to do with a decentralized
  89 filesystem through the WUI.
  90
  91 The CLI
  92 -------
  93
  94 Prefer the command-line? Run "``tahoe --help``" (the same command-line
  95 tool that is used to start and stop nodes serves to navigate and use
  96 the decentralized filesystem). To get started, create a new directory
  97 and mark it as the 'tahoe:' alias by running
  98 "``tahoe create-alias tahoe``". Once you've done that, you can do
  99 "``tahoe ls tahoe:``" and "``tahoe cp LOCALFILE tahoe:foo.txt``" to
 100 work with your filesystem. The Tahoe-LAFS CLI uses similar syntax to
 101 the well-known scp and rsync tools. See `CLI.rst <frontends/CLI.rst>`_
 102 for more details.
 103
 104 As with the WUI (and with all current interfaces to Tahoe-LAFS), you
 105 are responsible for remembering directory capabilities yourself. If you
 106 create a new directory and lose the capability to it, then you cannot
 107 access that directory ever again.
 108
 109 The SFTP and FTP frontends
 110 --------------------------
 111
 112 You can access your Tahoe-LAFS grid via any `SFTP
 113 <http://en.wikipedia.org/wiki/SSH_file_transfer_protocol>`_ or `FTP
 114 <http://en.wikipedia.org/wiki/File_Transfer_Protocol>`_ client.
 115 See `FTP-and-SFTP.rst <frontends/FTP-and-SFTP.rst>`_ for how to set
 116 this up. On most Unix platforms, you can also use SFTP to plug
 117 Tahoe-LAFS into your computer's local filesystem via ``sshfs``.
 118
 119 The `SftpFrontend
 120 <http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>`_ page on the
 121 wiki has more information about using SFTP with Tahoe-LAFS.
 122
 123 The WAPI
 124 --------
 125
 126 Want to program your Tahoe-LAFS node to do your bidding?  Easy!  See
 127 `webapi.rst <frontends/webapi.rst>`_.
 128
 129 Socialize
 130 =========
 131
 132 You can chat with other users of and hackers of this software on the
 133 #tahoe-lafs IRC channel at ``irc.freenode.net``, or on the `tahoe-dev
 134 mailing list
 135 <http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_.