source: trunk/docs/running.rst

Last change on this file was 7aae2f7, checked in by GitHub <noreply@…>, at 2022-09-28T15:34:54Z

Clarify

Co-authored-by: Jean-Paul Calderone <exarkun@…>

  • Property mode set to 100644
File size: 11.9 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
127Multiple Instances
128------------------
129
130Running multiple instances against the same configuration directory isn't supported.
131This will lead to undefined behavior and could corrupt the configuration or state.
132
133We attempt to avoid this situation with a "pidfile"-style file in the config directory called ``running.process``.
134There may be a parallel file called ``running.process.lock`` in existence.
135
136The ``.lock`` file exists to make sure only one process modifies ``running.process`` at once.
137The lock file is managed by the `lockfile <https://pypi.org/project/lockfile/>`_ library.
138If you wish to make use of ``running.process`` for any reason you should also lock it and follow the semantics of lockfile.
139
140If ``running.process`` exists then it contains the PID and the creation-time of the process.
141When no such file exists, there is no other process running on this configuration.
142If there is a ``running.process`` file, it may be a leftover file or it may indicate that another process is running against this config.
143To tell the difference, determine if the PID in the file exists currently.
144If it does, check the creation-time of the process versus the one in the file.
145If these match, there is another process currently running and using this config.
146Otherwise, the file is stale -- it should be removed before starting Tahoe-LAFS.
147
148Some example Python code to check the above situations:
149
150.. literalinclude:: check_running.py
151
152
153
154
155
156A note about small grids
157------------------------
158
159By default, Tahoe-LAFS ships with the configuration parameter
160``shares.happy`` set to 7. If you are using Tahoe-LAFS on a grid with
161fewer than 7 storage nodes, this won't work well for you — none of your
162uploads will succeed. To fix this, see :doc:`configuration` to learn how
163to set ``shares.happy`` to a more suitable value for your grid.
164
165
166Development with Docker
167-----------------------
168
169If you want to stand up a small local test environment, you can install
170`Docker`_ and `Docker Compose`_. Once you have cloned the repository, run
171``docker-compose up`` from the project's root directory. This will start a
172introducer, server, and a client configured to connect to them. After the
173containers start, you can access the WUI by navigating to
174``http://localhost:3456`` in your browser.
175
176.. _Docker: https://docs.docker.com/
177.. _Docker Compose: https://docs.docker.com/compose/
178
179Do Stuff With It
180================
181
182This is how to use your Tahoe-LAFS node.
183
184The WUI
185-------
186
187Point your web browser to `http://127.0.0.1:3456`_ — which is the URL of the
188gateway running on your own local computer — to use your newly created node.
189
190Create a new directory (with the button labelled “create a directory”).
191Your web browser will load the new directory.  Now if you want to be
192able to come back to this directory later, you have to bookmark it, or
193otherwise save a copy of the URL.  If you lose the URL to this directory,
194then you can never again come back to this directory.
195
196.. _http://127.0.0.1:3456: http://127.0.0.1:3456
197
198
199The CLI
200-------
201
202Prefer the command-line? Run “``tahoe --help``” (the same command-line
203tool that is used to start and stop nodes serves to navigate and use the
204decentralized file store). To get started, create a new directory and
205mark it as the 'tahoe:' alias by running “``tahoe create-alias tahoe``”.
206Once you've done that, you can do “``tahoe ls tahoe:``” and “``tahoe cp
207LOCALFILE tahoe:foo.txt``” to work with your file store. The Tahoe-LAFS
208CLI uses similar syntax to the well-known scp and rsync tools. See
209:doc:`frontends/CLI` for more details.
210
211
212To backup a directory full of files and subdirectories, run “``tahoe backup
213LOCALDIRECTORY tahoe:``”. This will create a new LAFS subdirectory inside the
214“tahoe” LAFS directory named “Archive”, and inside “Archive”, it will create
215a new subdirectory whose name is the current date and time. That newly
216created subdirectory will be populated with a snapshot copy of all files and
217directories currently reachable from LOCALDIRECTORY. Then ``tahoe backup``
218will make a link to that snapshot directory from the “tahoe” LAFS directory,
219and name the link “Latest”.
220
221``tahoe backup`` cleverly avoids uploading any files or directories that
222haven't changed, and it also cleverly deduplicates any files or directories
223that have identical contents to other files or directories that it has
224previously backed-up. This means that running ``tahoe backup`` is a nice
225incremental operation that backs up your files and directories efficiently,
226and if it gets interrupted (for example by a network outage, or by you
227rebooting your computer during the backup, or so on), it will resume right
228where it left off the next time you run ``tahoe backup``.
229
230See :doc:`frontends/CLI` for more information about the ``tahoe backup``
231command, as well as other commands.
232
233As with the WUI (and with all current interfaces to Tahoe-LAFS), you
234are responsible for remembering directory capabilities yourself. If you
235create a new directory and lose the capability to it, then you cannot
236access that directory ever again.
237
238
239The SFTP frontend
240-----------------
241
242You can access your Tahoe-LAFS grid via any SFTP_ client. See
243:doc:`frontends/FTP-and-SFTP` for how to set this up. On most Unix
244platforms, you can also use SFTP to plug Tahoe-LAFS into your computer's
245local filesystem via ``sshfs``, but see the `FAQ about performance
246problems`_.
247
248The SftpFrontend_ page on the wiki has more information about using SFTP with
249Tahoe-LAFS.
250
251.. _SFTP:  https://en.wikipedia.org/wiki/SSH_file_transfer_protocol
252.. _FAQ about performance problems: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/FAQ#Q23_FUSE
253.. _SftpFrontend: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend
254
255
256The WAPI
257--------
258
259Want to program your Tahoe-LAFS node to do your bidding?  Easy!  See
260:doc:`frontends/webapi`.
261
262
263Socialize
264=========
265
266You can chat with other users of and hackers of this software on the
267#tahoe-lafs IRC channel at ``irc.libera.chat``, or on the `tahoe-dev mailing
268list`_.
269
270.. _tahoe-dev mailing list: https://lists.tahoe-lafs.org/mailman/listinfo/tahoe-dev
271
272
273Complain
274========
275
276Bugs can be filed on the Tahoe-LAFS "Trac" instance, at
277https://tahoe-lafs.org/trac/ .
278
279You can also "fork" the repo and submit Pull Requests on Github:
280https://github.com/tahoe-lafs/tahoe-lafs .
Note: See TracBrowser for help on using the repository browser.