mirror of
https://github.com/tahoe-lafs/tahoe-lafs.git
synced 2024-12-21 05:53:12 +00:00
59d6c3c822
* use new decentralized directories everywhere instead of old centralized directories * provide UI to them through the web server * provide UI to them through the CLI * update unit tests to simulate decentralized mutable directories in order to test other components that rely on them * remove the notion of a "vdrive server" and a client thereof * remove the notion of a "public vdrive", which was a directory that was centrally published/subscribed automatically by the tahoe node (you can accomplish this manually by making a directory and posting the URL to it on your web site, for example) * add a notion of "wait_for_numpeers" when you need to publish data to peers, which is how many peers should be attached before you start. The default is 1. * add __repr__ for filesystem nodes (note: these reprs contain a few bits of the secret key!) * fix a few bugs where we used to equate "mutable" with "not read-only". Nowadays all directories are mutable, but some might be read-only (to you). * fix a few bugs where code wasn't aware of the new general-purpose metadata dict the comes with each filesystem edge * sundry fixes to unit tests to adjust to the new directories, e.g. don't assume that every share on disk belongs to a chk file.
172 lines
8.3 KiB
Plaintext
172 lines
8.3 KiB
Plaintext
|
|
= Configuring a Tahoe node =
|
|
|
|
A Tahoe node is configured by writing files to its base directory. These
|
|
files are read by the node when it starts, so each time you change them, you
|
|
need to restart the node.
|
|
|
|
The node also writes state to its base directory, so it will create files on
|
|
its own.
|
|
|
|
This document contains a complete list of the config files that are examined
|
|
by the client node, as well as the state files that you'll observe in its
|
|
base directory.
|
|
|
|
== Client Configuration ==
|
|
|
|
introducer.furl (mandatory): This FURL tells the client how to connect to the
|
|
introducer. Each Tahoe grid is defined by an introducer. The introducer's
|
|
furl is created by the introducer node and written into its base directory
|
|
when it starts, whereupon it should be published to everyone who wishes to
|
|
attach a client to that grid
|
|
|
|
webport (optional): This controls where the client's webserver should listen,
|
|
providing vdrive access as defined in webapi.txt . This file should contain a
|
|
Twisted "strports" specification, such as "8123" or
|
|
"tcp:8123:interface=127.0.0.1". The 'tahoe create-client' command sets the
|
|
webport to "tcp:8123:interface=127.0.0.1" by default, and is overridable by
|
|
the "--webport" option.
|
|
|
|
client.port (optional): This controls which port the node listens on. If not
|
|
provided, the node will ask the kernel for any available port, and write it
|
|
to this file so that subsequent runs will re-use the same port.
|
|
|
|
advertised_ip_addresses (optional): The node normally uses tools like
|
|
'ifconfig' to determine the set of IP addresses on which it can be reached
|
|
from nodes both near and far. The node introduces itself to the rest of the
|
|
grid with a FURL that contains a series of (ipaddr, port) pairs which other
|
|
nodes will use to contact this one. By providing this file, you can add to
|
|
this list. This can be useful if your node is running behind a firewall, but
|
|
you have created a port-forwarding to allow the outside world to access it.
|
|
Each line must have a dotted-quad IP address and an optional :portnum
|
|
specification:
|
|
|
|
123.45.67.89
|
|
44.55.66.77:8098
|
|
|
|
Lines that do not provide a port number will use the same client.port as the
|
|
automatically-discovered addresses.
|
|
|
|
authorized_keys.SSHPORT (optional): This enables an SSH-based interactive
|
|
Python shell, which can be used to inspect the internal state of the node,
|
|
for debugging. To cause the node to accept SSH connections on port 8022,
|
|
symlink "authorized_keys.8022" to your ~/.ssh/authorized_keys file, and it
|
|
will accept the same keys as the rest of your account.
|
|
|
|
sizelimit (optional): If present, this file establishes an upper bound (in
|
|
bytes) on the amount of storage consumed by share data (data that your node
|
|
holds on behalf of clients that are uploading files to the grid). To avoid
|
|
providing more than 100MB of data to other clients, write "100000000" into
|
|
this file. Note that this is a fairly loose bound, and the node may
|
|
occasionally use slightly more storage than this. To enforce a stronger (and
|
|
possibly more reliable) limit, use a symlink to place the 'storage/'
|
|
directory on a separate size-limited filesystem, and/or use per-user
|
|
OS/filesystem quotas.
|
|
|
|
my_private_dir.uri (optional): When you create a new tahoe client, this
|
|
file is created with no contents (as an empty file). When the node starts
|
|
up, it will inspect this file. If the file doesn't exist then nothing will
|
|
be done. If the file exists, then the node will try to read the contents of
|
|
the file and parse the contents as a read-write URI to a mutable directory.
|
|
If the file exists but doesn't contain a well-formed read-write URI to a
|
|
mutable directory (which is the case if the file is empty), then the node
|
|
will create a new decentralized mutable directory and write its URI into this
|
|
file. The start.html page will contain a URL pointing to this directory if
|
|
it exists.
|
|
|
|
|
|
== Node State ==
|
|
|
|
node.pem : This contains an SSL private-key certificate. The node generates
|
|
this the first time it is started, and re-uses it on subsequent runs. This
|
|
certificate allows the node to have a cryptographically-strong identifier
|
|
(the Foolscap "TubID"), and to establish secure connections to other nodes.
|
|
|
|
storage/ : Nodes which host StorageServers will create this directory to hold
|
|
shares of files on behalf of other clients. There will be a directory
|
|
underneath it for each StorageIndex for which this node is holding shares.
|
|
There is also an "incoming" directory where partially-completed shares are
|
|
held while they are being received.
|
|
|
|
client.tac : this file defines the client, by constructing the actual Client
|
|
instance each time the node is started. It is used by the 'twistd'
|
|
daemonization program (in the "-y" mode), which is run internally by the
|
|
"tahoe start" command. This file is created by the "tahoe create-client"
|
|
command.
|
|
|
|
control.furl : this file contains a FURL that provides access to a control
|
|
port on the client node, from which files can be uploaded and downloaded.
|
|
This file is created with permissions that prevent anyone else from reading
|
|
it (on operating systems that support such a concept), to insure that only
|
|
the owner of the client node can use this feature. This port is intended for
|
|
debugging and testing use.
|
|
|
|
logport.furl : this file contains a FURL that provides access to a 'log port'
|
|
on the client node, from which operational logs can be retrieved. Do not
|
|
grant logport access to strangers, because occasionally secret information
|
|
may be placed in the logs.
|
|
|
|
log_gatherer.furl : if present, this file is used to contact a 'log
|
|
gatherer', which will be granted access to the logport. This can be used by
|
|
centralized storage meshes to gather operational logs in a single place.
|
|
|
|
|
|
== Introducer configuration ==
|
|
|
|
Introducer nodes use the same 'advertised_ip_addresses' file as client
|
|
nodes. They also use 'authorized_keys.SSHPORT'.
|
|
|
|
encoding_parameters (optional): This file sets the encoding parameters that
|
|
will be distributed to all client nodes and used when they encode files
|
|
(unless locally overridden). It should contain three numbers, separated by
|
|
whitespace, called "needed", "desired", and "total".
|
|
|
|
"needed": this is the number of shares that will be needed to reconstruct
|
|
the file. Each share that is pushed to a StorageServer will be
|
|
the size of the original file divided by this number.
|
|
"desired": the encoding/upload process will be happy if it can push
|
|
this many shares to StorageServers. If it cannot, it will
|
|
report failure.
|
|
"total": this is the total number of shares that will be produced. The
|
|
expansion factor (i.e. the amount of space consumed on the whole
|
|
grid divided by the size of the file) will be total/needed. It does
|
|
not make a lot of sense to have "total" be much larger than the
|
|
maximum number of storage nodes you expect to ever have.
|
|
|
|
The default value of encoding_parameters is "3 7 10".
|
|
|
|
|
|
== Introducer state ==
|
|
|
|
The Introducer node maintains some different state than regular client
|
|
nodes.
|
|
|
|
introducer.furl : This is generated the first time the introducer node is
|
|
started, and used again on subsequent runs, to give the introduction service
|
|
a persistent long-term identity. This file should be published and copied
|
|
into new client nodes before they are started for the first time.
|
|
|
|
introducer.port : this serves exactly the same purpose as 'client.port', but
|
|
has a different name to make it clear what kind of node is being run.
|
|
|
|
introducer.tac : this file is like client.tac but defines an
|
|
introducer node instead of a client node.
|
|
|
|
== Other files ==
|
|
|
|
logs/ : Each Tahoe node creates a directory to hold the log messages produced
|
|
as the node runs. These logfiles are created and rotated by the "twistd"
|
|
daemonization program, so logs/twistd.log will contain the most recent
|
|
messages, logs/twistd.log.1 will contain the previous ones, logs/twistd.log.2
|
|
will be older still, and so on. twistd rotates logfiles after they grow
|
|
beyond 1MB in size. If the space consumed by logfiles becomes troublesome,
|
|
they should be pruned: a cron job to delete all files that were created more
|
|
than a month ago in this logs/ directory should be sufficient.
|
|
|
|
my_nodeid : this is written by all nodes after startup, and contains a
|
|
base32-encoded (i.e. human-readable) NodeID that identifies this specific
|
|
node. This NodeID is the same string that gets displayed on the web page (in
|
|
the "which peers am I connected to" list), and the shortened form (the first
|
|
characters) is recorded in various log messages.
|
|
|