source: trunk/docs/running.rst

Last change on this file was 65a1040, checked in by Sajith Sasidharan <sajith@…>, at 2021-08-31T13:58:43Z

Update references to the mailing list

New list is tahoe-dev@…, list info page is at
https://lists.tahoe-lafs.org/mailman/listinfo/tahoe-dev, and list
archives are now at https://lists.tahoe-lafs.org/pipermail/tahoe-dev/.

Sadly message numbers in list archive seem to have changed, so
updating references to list archive is not as simple as prefixing
list.

  • Property mode set to 100644
File size: 10.5 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:`Installing Tahoe-LAFS <../Installation/install-tahoe>`.
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 write it to ``~/.tahoe/private/introducers.yaml``
69(see :ref:`introducer-definitions`). Then use “``tahoe run ~/.tahoe``”.
70After 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.
84``tahoe --help`` gives a summary of all commands.
85
86
87Running a Server or Introducer
88------------------------------
89
90To build either a storage server node, or an introducer node, you'll need
91a way for clients to connect to it. The simplest case is when the
92computer is on the public internet (e.g. a "VPS" virtual private server,
93with a public IP address and a DNS hostname like ``example.net``). See
94:doc:`servers` for help with more complex scenarios, using the ``--port``
95and ``--location`` arguments.
96
97To construct an introducer, create a new base directory for it (the name
98of the directory is up to you), ``cd`` into it, and run “``tahoe
99create-introducer --hostname=example.net .``” (but using the hostname of
100your VPS). Now run the introducer using “``tahoe run .``”. After it
101starts, it will write a file named ``introducer.furl`` into the
102``private/`` subdirectory of that base directory. This file contains the
103URL the other nodes must use in order to connect to this introducer.
104
105You can distribute your Introducer fURL securely to new clients by using
106the ``tahoe invite`` command. This will prepare some JSON to send to the
107other side, request a `magic wormhole`_ code from
108``wormhole.tahoe-lafs.org`` and print it out to the terminal. This
109one-time code should be transmitted to the user of the client, who can
110then run ``tahoe create-client --join <one-time-code>``.
111
112Storage servers are created the same way: ``tahoe create-node
113--hostname=HOSTNAME .`` from a new directory. You'll need to provide the
114introducer FURL (either as a ``--introducer=`` argument, or by editing
115the ``tahoe.cfg`` configuration file afterwards) to connect to the
116introducer of your choice.
117
118See :doc:`configuration` for more details about how to configure
119Tahoe-LAFS.
120
121.. _public test grid: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid
122.. _TestGrid page: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid
123.. _#937:  https://tahoe-lafs.org/trac/tahoe-lafs/ticket/937
124.. _magic wormhole: https://magic-wormhole.io/
125
126
127A note about small grids
128------------------------
129
130By default, Tahoe-LAFS ships with the configuration parameter
131``shares.happy`` set to 7. If you are using Tahoe-LAFS on a grid with
132fewer than 7 storage nodes, this won't work well for you — none of your
133uploads will succeed. To fix this, see :doc:`configuration` to learn how
134to set ``shares.happy`` to a more suitable value for your grid.
135
136
137Development with Docker
138-----------------------
139
140If you want to stand up a small local test environment, you can install
141`Docker`_ and `Docker Compose`_. Once you have cloned the repository, run
142``docker-compose up`` from the project's root directory. This will start a
143introducer, server, and a client configured to connect to them. After the
144containers start, you can access the WUI by navigating to
145``http://localhost:3456`` in your browser.
146
147.. _Docker: https://docs.docker.com/
148.. _Docker Compose: https://docs.docker.com/compose/
149
150Do Stuff With It
151================
152
153This is how to use your Tahoe-LAFS node.
154
155The WUI
156-------
157
158Point your web browser to `http://127.0.0.1:3456`_ — which is the URL of the
159gateway running on your own local computer — to use your newly created node.
160
161Create a new directory (with the button labelled “create a directory”).
162Your web browser will load the new directory.  Now if you want to be
163able to come back to this directory later, you have to bookmark it, or
164otherwise save a copy of the URL.  If you lose the URL to this directory,
165then you can never again come back to this directory.
166
167.. _http://127.0.0.1:3456: http://127.0.0.1:3456
168
169
170The CLI
171-------
172
173Prefer the command-line? Run “``tahoe --help``” (the same command-line
174tool that is used to start and stop nodes serves to navigate and use the
175decentralized file store). To get started, create a new directory and
176mark it as the 'tahoe:' alias by running “``tahoe create-alias tahoe``”.
177Once you've done that, you can do “``tahoe ls tahoe:``” and “``tahoe cp
178LOCALFILE tahoe:foo.txt``” to work with your file store. The Tahoe-LAFS
179CLI uses similar syntax to the well-known scp and rsync tools. See
180:doc:`frontends/CLI` for more details.
181
182
183To backup a directory full of files and subdirectories, run “``tahoe backup
184LOCALDIRECTORY tahoe:``”. This will create a new LAFS subdirectory inside the
185“tahoe” LAFS directory named “Archive”, and inside “Archive”, it will create
186a new subdirectory whose name is the current date and time. That newly
187created subdirectory will be populated with a snapshot copy of all files and
188directories currently reachable from LOCALDIRECTORY. Then ``tahoe backup``
189will make a link to that snapshot directory from the “tahoe” LAFS directory,
190and name the link “Latest”.
191
192``tahoe backup`` cleverly avoids uploading any files or directories that
193haven't changed, and it also cleverly deduplicates any files or directories
194that have identical contents to other files or directories that it has
195previously backed-up. This means that running ``tahoe backup`` is a nice
196incremental operation that backs up your files and directories efficiently,
197and if it gets interrupted (for example by a network outage, or by you
198rebooting your computer during the backup, or so on), it will resume right
199where it left off the next time you run ``tahoe backup``.
200
201See :doc:`frontends/CLI` for more information about the ``tahoe backup``
202command, as well as other commands.
203
204As with the WUI (and with all current interfaces to Tahoe-LAFS), you
205are responsible for remembering directory capabilities yourself. If you
206create a new directory and lose the capability to it, then you cannot
207access that directory ever again.
208
209
210The SFTP frontend
211-----------------
212
213You can access your Tahoe-LAFS grid via any SFTP_ client. See
214:doc:`frontends/FTP-and-SFTP` for how to set this up. On most Unix
215platforms, you can also use SFTP to plug Tahoe-LAFS into your computer's
216local filesystem via ``sshfs``, but see the `FAQ about performance
217problems`_.
218
219The SftpFrontend_ page on the wiki has more information about using SFTP with
220Tahoe-LAFS.
221
222.. _SFTP:  https://en.wikipedia.org/wiki/SSH_file_transfer_protocol
223.. _FAQ about performance problems: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/FAQ#Q23_FUSE
224.. _SftpFrontend: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend
225
226
227The WAPI
228--------
229
230Want to program your Tahoe-LAFS node to do your bidding?  Easy!  See
231:doc:`frontends/webapi`.
232
233
234Socialize
235=========
236
237You can chat with other users of and hackers of this software on the
238#tahoe-lafs IRC channel at ``irc.libera.chat``, or on the `tahoe-dev mailing
239list`_.
240
241.. _tahoe-dev mailing list: https://lists.tahoe-lafs.org/mailman/listinfo/tahoe-dev
242
243
244Complain
245========
246
247Bugs can be filed on the Tahoe-LAFS "Trac" instance, at
248https://tahoe-lafs.org/trac/ .
249
250You can also "fork" the repo and submit Pull Requests on Github:
251https://github.com/tahoe-lafs/tahoe-lafs .
Note: See TracBrowser for help on using the repository browser.