docs/running.rst

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