source: trunk/docs/running.rst

Last change on this file was 593ebdf, checked in by Brian Warner <warner@…>, at 2017-09-19T16:25:39Z

add note about using docker compose to running docs

  • Property mode set to 100644
File size: 10.8 KB
Line 
1.. -*- coding: utf-8-with-signature-unix; fill-column: 73; -*-
2.. -*- indent-tabs-mode: nil -*-
3
4*********************
5How To Run Tahoe-LAFS
6*********************
7
8Introduction
9============
10
11This is how to run a Tahoe-LAFS client or a complete Tahoe-LAFS grid.
12First you have to install the Tahoe-LAFS software, as documented in
13:doc:`INSTALL`.
14
15The ``tahoe`` program in your virtualenv's ``bin`` directory is used to
16create, start, and stop nodes. Each node lives in a separate base
17directory, in which there is a configuration file named ``tahoe.cfg``.
18Nodes read and write files within this base directory.
19
20A grid consists of a set of *storage nodes* and *client nodes* running
21the Tahoe-LAFS code. There is also an *introducer node* that is
22responsible for getting the other nodes talking to each other.
23
24If you're getting started we recommend you try connecting to the `public test
25grid`_ as you only need to create a client node. When you want to create your
26own grid you'll need to create the introducer and several initial storage
27nodes (see the note about small grids below).
28
29
30Being Introduced to a Grid
31--------------------------
32
33A collection of Tahoe servers is called a Grid and usually has 1
34Introducer (but sometimes more, and it's possible to run with zero). The
35Introducer announces which storage servers constitute the Grid and how to
36contact them. There is a secret "fURL" you need to know to talk to the
37Introducer.
38
39One way to get this secret is using traditional tools such as encrypted
40email, encrypted instant-messaging, etcetera. It is important to transmit
41this fURL secretly as knowing it gives you access to the Grid.
42
43An additional way to share the fURL securely is via `magic
44wormhole`_. This uses a weak one-time password and a server on the
45internet (at `wormhole.tahoe-lafs.org`) to open a secure channel between
46two computers. In Tahoe-LAFS this functions via the commands `tahoe
47invite` and `tahoe create-client --join`. A person who already has access
48to a Grid can use `tahoe invite` to create one end of the `magic
49wormhole`_ and then transmits some JSON (including the Introducer's
50secret fURL) to the other end. `tahoe invite` will print a one-time
51secret code; you must then communicate this code to the person who will
52join the Grid.
53
54The other end of the `magic wormhole`_ in this case is `tahoe
55create-client --join <one-time code>`, where the person being invited
56types in the code they were given. Ideally, this code would be
57transmitted securely. It is, however, only useful exactly once. Also, it
58is much easier to transcribe by a human. Codes look like
59`7-surrender-tunnel` (a short number and two words).
60
61
62Running a Client
63----------------
64
65To construct a client node, run “``tahoe create-client``”, which will create
66``~/.tahoe`` to be the node's base directory. Acquire the ``introducer.furl``
67(see below if you are running your own introducer, or use the one from the
68`TestGrid page`_), and paste it after ``introducer.furl =`` in the
69``[client]`` section of ``~/.tahoe/tahoe.cfg``. Then use “``tahoe run
70~/.tahoe``”. After that, the node should be off and running. The first thing
71it will do is connect to the introducer and get itself connected to all other
72nodes on the grid.
73
74Some Grids use "magic wormhole" one-time codes to configure the basic
75options. In such a case you use ``tahoe create-client --join
76<one-time-code>`` and do not have to do any of the ``tahoe.cfg`` editing
77mentioned above.
78
79By default, “``tahoe create-client``” creates a client-only node, that
80does not offer its disk space to other nodes. To configure other behavior,
81use “``tahoe create-node``” or see :doc:`configuration`.
82
83The “``tahoe run``” command above will run the node in the foreground.
84On Unix, you can run it in the background instead by using the
85``tahoe start``” command. To stop a node started in this way, use
86``tahoe stop``”. ``tahoe --help`` gives a summary of all commands.
87
88
89Running a Server or Introducer
90------------------------------
91
92To build either a storage server node, or an introducer node, you'll need
93a way for clients to connect to it. The simplest case is when the
94computer is on the public internet (e.g. a "VPS" virtual private server,
95with a public IP address and a DNS hostname like ``example.net``). See
96:doc:`servers` for help with more complex scenarios, using the ``--port``
97and ``--location`` arguments.
98
99To construct an introducer, create a new base directory for it (the name
100of the directory is up to you), ``cd`` into it, and run “``tahoe
101create-introducer --hostname=example.net .``” (but using the hostname of
102your VPS). Now run the introducer using “``tahoe start .``”. After it
103starts, it will write a file named ``introducer.furl`` into the
104``private/`` subdirectory of that base directory. This file contains the
105URL the other nodes must use in order to connect to this introducer.
106(Note that “``tahoe run .``” doesn't work for introducers, this is a
107known issue: `#937`_.)
108
109You can distribute your Introducer fURL securely to new clients by using
110the ``tahoe invite`` command. This will prepare some JSON to send to the
111other side, request a `magic wormhole`_ code from
112``wormhole.tahoe-lafs.org`` and print it out to the terminal. This
113one-time code should be transmitted to the user of the client, who can
114then run ``tahoe create-client --join <one-time-code>``.
115
116Storage servers are created the same way: ``tahoe create-node
117--hostname=HOSTNAME .`` from a new directory. You'll need to provide the
118introducer FURL (either as a ``--introducer=`` argument, or by editing
119the ``tahoe.cfg`` configuration file afterwards) to connect to the
120introducer of your choice.
121
122See :doc:`configuration` for more details about how to configure
123Tahoe-LAFS.
124
125.. _public test grid: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid
126.. _TestGrid page: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid
127.. _#937:  https://tahoe-lafs.org/trac/tahoe-lafs/ticket/937
128.. _magic wormhole: https://magic-wormhole.io/
129
130
131A note about small grids
132------------------------
133
134By default, Tahoe-LAFS ships with the configuration parameter
135``shares.happy`` set to 7. If you are using Tahoe-LAFS on a grid with
136fewer than 7 storage nodes, this won't work well for you — none of your
137uploads will succeed. To fix this, see :doc:`configuration` to learn how
138to set ``shares.happy`` to a more suitable value for your grid.
139
140
141Development with Docker
142-----------------------
143
144If you want to stand up a small local test environment, you can install
145`Docker`_ and `Docker Compose`_. Once you have cloned the repository, run
146``docker-compose up`` from the project's root directory. This will start a
147introducer, server, and a client configured to connect to them. After the
148containers start, you can access the WUI by navigating to
149``http://localhost:3456`` in your browser.
150
151.. _Docker: https://docs.docker.com/
152.. _Docker Compose: https://docs.docker.com/compose/
153
154Do Stuff With It
155================
156
157This is how to use your Tahoe-LAFS node.
158
159The WUI
160-------
161
162Point your web browser to `http://127.0.0.1:3456`_ — which is the URL of the
163gateway running on your own local computer — to use your newly created node.
164
165Create a new directory (with the button labelled “create a directory”).
166Your web browser will load the new directory.  Now if you want to be
167able to come back to this directory later, you have to bookmark it, or
168otherwise save a copy of the URL.  If you lose the URL to this directory,
169then you can never again come back to this directory.
170
171.. _http://127.0.0.1:3456: http://127.0.0.1:3456
172
173
174The CLI
175-------
176
177Prefer the command-line? Run “``tahoe --help``” (the same command-line
178tool that is used to start and stop nodes serves to navigate and use the
179decentralized file store). To get started, create a new directory and
180mark it as the 'tahoe:' alias by running “``tahoe create-alias tahoe``”.
181Once you've done that, you can do “``tahoe ls tahoe:``” and “``tahoe cp
182LOCALFILE tahoe:foo.txt``” to work with your file store. The Tahoe-LAFS
183CLI uses similar syntax to the well-known scp and rsync tools. See
184:doc:`frontends/CLI` for more details.
185
186
187To backup a directory full of files and subdirectories, run “``tahoe backup
188LOCALDIRECTORY tahoe:``”. This will create a new LAFS subdirectory inside the
189“tahoe” LAFS directory named “Archive”, and inside “Archive”, it will create
190a new subdirectory whose name is the current date and time. That newly
191created subdirectory will be populated with a snapshot copy of all files and
192directories currently reachable from LOCALDIRECTORY. Then ``tahoe backup``
193will make a link to that snapshot directory from the “tahoe” LAFS directory,
194and name the link “Latest”.
195
196``tahoe backup`` cleverly avoids uploading any files or directories that
197haven't changed, and it also cleverly deduplicates any files or directories
198that have identical contents to other files or directories that it has
199previously backed-up. This means that running ``tahoe backup`` is a nice
200incremental operation that backs up your files and directories efficiently,
201and if it gets interrupted (for example by a network outage, or by you
202rebooting your computer during the backup, or so on), it will resume right
203where it left off the next time you run ``tahoe backup``.
204
205See :doc:`frontends/CLI` for more information about the ``tahoe backup``
206command, as well as other commands.
207
208As with the WUI (and with all current interfaces to Tahoe-LAFS), you
209are responsible for remembering directory capabilities yourself. If you
210create a new directory and lose the capability to it, then you cannot
211access that directory ever again.
212
213
214The SFTP and FTP frontends
215--------------------------
216
217You can access your Tahoe-LAFS grid via any SFTP_ or FTP_ client. See
218:doc:`frontends/FTP-and-SFTP` for how to set this up. On most Unix
219platforms, you can also use SFTP to plug Tahoe-LAFS into your computer's
220local filesystem via ``sshfs``, but see the `FAQ about performance
221problems`_.
222
223The SftpFrontend_ page on the wiki has more information about using SFTP with
224Tahoe-LAFS.
225
226.. _SFTP:  https://en.wikipedia.org/wiki/SSH_file_transfer_protocol
227.. _FTP: https://en.wikipedia.org/wiki/File_Transfer_Protocol
228.. _FAQ about performance problems: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/FAQ#Q23_FUSE
229.. _SftpFrontend: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend
230
231
232The WAPI
233--------
234
235Want to program your Tahoe-LAFS node to do your bidding?  Easy!  See
236:doc:`frontends/webapi`.
237
238
239Socialize
240=========
241
242You can chat with other users of and hackers of this software on the
243#tahoe-lafs IRC channel at ``irc.freenode.net``, or on the `tahoe-dev mailing
244list`_.
245
246.. _tahoe-dev mailing list: https://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev
247
248
249Complain
250========
251
252Bugs can be filed on the Tahoe-LAFS "Trac" instance, at
253https://tahoe-lafs.org/trac/ .
254
255You can also "fork" the repo and submit Pull Requests on Github:
256https://github.com/tahoe-lafs/tahoe-lafs .
Note: See TracBrowser for help on using the repository browser.