mirror of
https://github.com/tahoe-lafs/tahoe-lafs.git
synced 2024-12-23 23:02:25 +00:00
0eb31774d1
These changes are a work-in-progress -- there are many incomplete and incorrect parts, but the install.html and running.html files are complete and should work (and they are delightfully concise!). I'm pushing this just to let people see incremental progress and to solicit feedback. "Testing out" the install.html and running.html files and submitting patches or bug reports would be quite welcome. More to come.
187 lines
9.1 KiB
Plaintext
187 lines
9.1 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 filesystem access as defined in webapi.txt . This
|
|
file contains a Twisted "strports" specification XXX hyperlink,
|
|
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.
|
|
|
|
XXX <pre>tahoe create-client</pre> will put a port specification into a file named
|
|
XXX $HERE/webport, unless overridden by the --webport option to
|
|
XXX create-client. The presence of a port specification in the webport
|
|
XXX file prompts the client node to run a webserver on the desired port,
|
|
XXX through which you can view, upload, download, and delete files. The
|
|
XXX contents of the webport file is actually a "strports specification",
|
|
XXX defined in
|
|
XXX http://twistedmatrix.com/documents/current/api/twisted.application.strports.html
|
|
XXX , so you can have it only listen on a local interface by writing
|
|
XXX "tcp:8123:interface=127.0.0.1" to this file (that's what create-client
|
|
XXX does by default), or make it use SSL by writing
|
|
XXX "ssl:8123:privateKey=mykey.pem:certKey=cert.pem" instead.
|
|
|
|
|
|
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.cap (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.
|
|
|