How To Run Tahoe-LAFS¶
This is how to run a Tahoe-LAFS client or a complete Tahoe-LAFS grid. First you have to install the Tahoe-LAFS software, as documented in Installing Tahoe-LAFS.
tahoe program in your virtualenv’s
bin directory is used to
create, start, and stop nodes. Each node lives in a separate base
directory, in which there is a configuration file named
Nodes read and write files within this base directory.
A grid consists of a set of storage nodes and client nodes running the Tahoe-LAFS code. There is also an introducer node that is responsible for getting the other nodes talking to each other.
If you’re getting started we recommend you try connecting to the public test grid as you only need to create a client node. When you want to create your own grid you’ll need to create the introducer and several initial storage nodes (see the note about small grids below).
Running a Client¶
To construct a client node, run “
tahoe create-client”, which will create
~/.tahoe to be the node’s base directory. Acquire the
(see below if you are running your own introducer, or use the one from the
TestGrid page), and paste it after
introducer.furl = in the
[client] section of
~/.tahoe/tahoe.cfg. Then use “
~/.tahoe”. After that, the node should be off and running. The first thing
it will do is connect to the introducer and get itself connected to all other
nodes on the grid.
By default, “
tahoe create-client” creates a client-only node, that
does not offer its disk space to other nodes. To configure other behavior,
tahoe create-node” or see Configuring a Tahoe-LAFS node.
tahoe run” command above will run the node in the foreground.
On Unix, you can run it in the background instead by using the
tahoe start” command. To stop a node started in this way, use
tahoe --help gives a summary of all commands.
Running a Server or Introducer¶
To build either a storage server node, or an introducer node, you’ll need
a way for clients to connect to it. The simplest case is when the
computer is on the public internet (e.g. a “VPS” virtual private server,
with a public IP address and a DNS hostname like
How To Configure A Server for help with more complex scenarios, using the
To construct an introducer, create a new base directory for it (the name
of the directory is up to you),
cd into it, and run “
create-introducer --hostname=example.net .” (but using the hostname of
your VPS). Now run the introducer using “
tahoe start .”. After it
starts, it will write a file named
introducer.furl into the
private/ subdirectory of that base directory. This file contains the
URL the other nodes must use in order to connect to this introducer.
(Note that “
tahoe run .” doesn’t work for introducers, this is a
known issue: #937.)
Storage servers are created the same way:
--hostname=HOSTNAME . from a new directory. You’ll need to provide the
introducer FURL (either as a
--introducer= argument, or by editing
tahoe.cfg configuration file afterwards) to connect to the
introducer of your choice.
See Configuring a Tahoe-LAFS node for more details about how to configure Tahoe-LAFS.
A note about small grids¶
By default, Tahoe-LAFS ships with the configuration parameter
shares.happy set to 7. If you are using Tahoe-LAFS on a grid with
fewer than 7 storage nodes, this won’t work well for you — none of your
uploads will succeed. To fix this, see Configuring a Tahoe-LAFS node to learn how
shares.happy to a more suitable value for your grid.
Do Stuff With It¶
This is how to use your Tahoe-LAFS node.
Point your web browser to http://127.0.0.1:3456 — which is the URL of the gateway running on your own local computer — to use your newly created node.
Create a new directory (with the button labelled “create a directory”). Your web browser will load the new directory. Now if you want to be able to come back to this directory later, you have to bookmark it, or otherwise save a copy of the URL. If you lose the URL to this directory, then you can never again come back to this directory.
Prefer the command-line? Run “
tahoe --help” (the same command-line
tool that is used to start and stop nodes serves to navigate and use the
decentralized filesystem). To get started, create a new directory and
mark it as the ‘tahoe:’ alias by running “
tahoe create-alias tahoe”.
Once you’ve done that, you can do “
tahoe ls tahoe:” and “
LOCALFILE tahoe:foo.txt” to work with your filesystem. The Tahoe-LAFS
CLI uses similar syntax to the well-known scp and rsync tools. See
The Tahoe-LAFS CLI commands for more details.
To backup a directory full of files and subdirectories, run “
LOCALDIRECTORY tahoe:”. This will create a new LAFS subdirectory inside the
“tahoe” LAFS directory named “Archive”, and inside “Archive”, it will create
a new subdirectory whose name is the current date and time. That newly
created subdirectory will be populated with a snapshot copy of all files and
directories currently reachable from LOCALDIRECTORY. Then
will make a link to that snapshot directory from the “tahoe” LAFS directory,
and name the link “Latest”.
tahoe backup cleverly avoids uploading any files or directories that
haven’t changed, and it also cleverly deduplicates any files or directories
that have identical contents to other files or directories that it has
previously backed-up. This means that running
tahoe backup is a nice
incremental operation that backs up your files and directories efficiently,
and if it gets interrupted (for example by a network outage, or by you
rebooting your computer during the backup, or so on), it will resume right
where it left off the next time you run
See The Tahoe-LAFS CLI commands for more information about the
command, as well as other commands.
As with the WUI (and with all current interfaces to Tahoe-LAFS), you are responsible for remembering directory capabilities yourself. If you create a new directory and lose the capability to it, then you cannot access that directory ever again.
The SFTP and FTP frontends¶
You can access your Tahoe-LAFS grid via any SFTP or FTP client. See
Tahoe-LAFS SFTP and FTP Frontends for how to set this up. On most Unix
platforms, you can also use SFTP to plug Tahoe-LAFS into your computer’s
local filesystem via
sshfs, but see the FAQ about performance
The SftpFrontend page on the wiki has more information about using SFTP with Tahoe-LAFS.