docs/running.rst

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