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