+.. -*- coding: utf-8-with-signature -*-
+
=============================
Configuring a Tahoe-LAFS node
=============================
-1. `Overall Node Configuration`_
-2. `Client Configuration`_
-3. `Storage Server Configuration`_
-4. `Frontend Configuration`_
-5. `Running A Helper`_
-6. `Running An Introducer`_
-7. `Other Files in BASEDIR`_
-8. `Other files`_
-9. `Example`_
-
-A Tahoe-LAFS node is configured by writing to files in 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.
+1. `Node Types`_
+2. `Overall Node Configuration`_
+3. `Client Configuration`_
+4. `Storage Server Configuration`_
+5. `Frontend Configuration`_
+6. `Running A Helper`_
+7. `Running An Introducer`_
+8. `Other Files in BASEDIR`_
+9. `Other files`_
+10. `Example`_
+
+A Tahoe-LAFS node is configured by writing to files in 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.
a Twisted listening-port specification string, like "``tcp:80``" or
"``tcp:3456:interface=127.0.0.1``". For a full description of the format,
- see `the Twisted strports documentation
- <http://twistedmatrix.com/documents/current/api/twisted.application.strports.html>`_.
+ see `the Twisted strports documentation`_. Please note, if interface= is
+ not specified, Tahoe-LAFS will attempt to bind the port specified on all
+ interfaces.
``FURL string``
a Foolscap endpoint identifier, like
``pb://soklj4y7eok5c3xkmjeqpw@192.168.69.247:44801/eqpwqtzm``
+.. _the Twisted strports documentation: https://twistedmatrix.com/documents/current/api/twisted.application.strports.html
+
+
+Node Types
+==========
+
+A node can be a client/server, an introducer, a statistics gatherer, or a
+key generator.
+
+Client/server nodes provide one or more of the following services:
+
+* web-API service
+* SFTP service
+* FTP service
+* drop-upload service
+* helper service
+* storage service.
+
+A client/server that provides storage service (i.e. storing shares for
+clients) is called a "storage server". If it provides any of the other
+services, it is a "storage client" (a node can be both a storage server and a
+storage client). A client/server node that provides web-API service is called
+a "gateway".
+
Overall Node Configuration
==========================
This section controls the network behavior of the node overall: which ports
and IP addresses are used, when connections are timed out, etc. This
-configuration is independent of the services that the node is offering: the
-same controls are used for client and introducer nodes.
+configuration applies to all node types and is independent of the services
+that the node is offering.
If your node is behind a firewall or NAT device and you want other clients to
connect to it, you'll need to open a port in the firewall or NAT, and specify
``web.port = (strports string, optional)``
- This controls where the node's webserver should listen, providing
- filesystem access and node status as defined in
- `<frontends/webapi.rst>`_. This file contains a Twisted "strports"
- specification such as "``3456``" or "``tcp:3456:interface=127.0.0.1``".
- The "``tahoe create-node``" or "``tahoe create-client``" commands set the
- ``web.port`` to "``tcp:3456:interface=127.0.0.1``" by default; this is
- overridable by the ``--webport`` option. You can make it use SSL by
- writing "``ssl:3456:privateKey=mykey.pem:certKey=cert.pem``" instead.
+ This controls where the node's web server should listen, providing node
+ status and, if the node is a client/server, providing web-API service as
+ defined in webapi.rst_.
+
+ This file contains a Twisted "strports" specification such as "``3456``"
+ or "``tcp:3456:interface=127.0.0.1``". The "``tahoe create-node``" or
+ "``tahoe create-client``" commands set the ``web.port`` to
+ "``tcp:3456:interface=127.0.0.1``" by default; this is overridable by the
+ ``--webport`` option. You can make it use SSL by writing
+ "``ssl:3456:privateKey=mykey.pem:certKey=cert.pem``" instead.
If this is not provided, the node will not run a web server.
one log gatherer per node. See ticket `#1423`_ about lifting this
restriction and letting you have multiple log gatherers.
- .. _`#1423`: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1423
+ .. _`#1423`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1423
``timeout.keepalive = (integer in seconds, optional)``
contact us, our ping might be delayed, so we may disconnect them by
accident.
- .. _`#521`: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/521
+ .. _`#521`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/521
``ssh.port = (strports string, optional)``
used for files that usually (on a Unix system) go into ``/tmp``. The
string will be interpreted relative to the node's base directory.
+.. _webapi.rst: frontends/webapi.rst
+
Client Configuration
====================
This FURL tells the client how to connect to the introducer. Each
Tahoe-LAFS 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
+ created by the introducer node and written into its private base
+ directory when it starts, whereupon it should be published to everyone
+ who wishes to attach a client to that grid
``helper.furl = (FURL string, optional)``
If provided, the node will attempt to connect to and use the given helper
- for uploads. See `<helper.rst>`_ for details.
+ for uploads. See helper.rst_ for details.
``key_generator.furl = (FURL string, optional)``
ratios are more reliable, and small ``N``/``k`` ratios use less disk
space. ``N`` cannot be larger than 256, because of the 8-bit
erasure-coding algorithm that Tahoe-LAFS uses. ``k`` can not be greater
- than ``N``. See `<performance.rst>`_ for more details.
+ than ``N``. See performance.rst_ for more details.
``shares.happy`` allows you control over how well to "spread out" the
shares of an immutable file. For a successful upload, shares are
guarantee the availability of the uploaded file. This value should not be
larger than the number of servers on your grid.
- A value of ``shares.happy`` <= ``k`` is allowed, but does not provide any
- redundancy if some servers fail or lose shares.
+ A value of ``shares.happy`` <= ``k`` is allowed, but this is not
+ guaranteed to provide any redundancy if some servers fail or lose shares.
+ It may still provide redundancy in practice if ``N`` is greater than
+ the number of connected servers, because in that case there will typically
+ be more than one share on at least some storage nodes. However, since a
+ successful upload only guarantees that at least ``shares.happy`` shares
+ have been stored, the worst case is still that there is no redundancy.
(Mutable files use a different share placement algorithm that does not
currently consider this parameter.)
mutable-type parameter in the webapi. If you do not specify a value here,
Tahoe-LAFS will use SDMF for all newly-created mutable files.
- Note that this parameter only applies to mutable files. Mutable
- directories, which are stored as mutable files, are not controlled by
- this parameter and will always use SDMF. We may revisit this decision
- in future versions of Tahoe-LAFS.
+ Note that this parameter applies only to files, not to directories.
+ Mutable directories, which are stored in mutable files, are not
+ controlled by this parameter and will always use SDMF. We may revisit
+ this decision in future versions of Tahoe-LAFS.
+
+ See mutable.rst_ for details about mutable file formats.
+
+.. _helper.rst: helper.rst
+.. _performance.rst: performance.rst
+.. _mutable.rst: specifications/mutable.rst
+
+``peers.preferred = (string, optional)``
+
+ This is an optional comma-separated list of Node IDs of servers that will
+ be tried first when selecting storage servers for reading or writing.
+
+ Servers should be identified here by their Node ID as it appears in the web
+ ui, underneath the server's nickname. For storage servers running tahoe
+ versions >=1.10 (if the introducer is also running tahoe >=1.10) this will
+ be a "Node Key" (which is prefixed with 'v0-'). For older nodes, it will be
+ a TubID instead. When a preferred server (and/or the introducer) is
+ upgraded to 1.10 or later, clients must adjust their configs accordingly.
+
+ Every node selected for upload, whether preferred or not, will still
+ receive the same number of shares (one, if there are ``N`` or more servers
+ accepting uploads). Preferred nodes are simply moved to the front of the
+ server selection lists computed for each file.
+
+ This is useful if a subset of your nodes have different availability or
+ connectivity characteristics than the rest of the grid. For instance, if
+ there are more than ``N`` servers on the grid, and ``K`` or more of them
+ are at a single physical location, it would make sense for clients at that
+ location to prefer their local servers so that they can maintain access to
+ all of their uploads without using the internet.
+
Frontend Configuration
======================
directories and files, as well as a number of pages to check on the
status of your Tahoe node. It also provides a machine-oriented "WAPI",
with a REST-ful HTTP interface that can be used by other programs
- (including the CLI tools). Please see `<frontends/webapi.rst>`_ for full
- details, and the ``web.port`` and ``web.static`` config variables above.
- The `<frontends/download-status.rst>`_ document also describes a few WUI
- status pages.
+ (including the CLI tools). Please see webapi.rst_ for full details, and
+ the ``web.port`` and ``web.static`` config variables above. The
+ `download-status.rst`_ document also describes a few WUI status pages.
CLI
The main "bin/tahoe" executable includes subcommands for manipulating the
filesystem, uploading/downloading files, and creating/running Tahoe
- nodes. See `<frontends/CLI.rst>`_ for details.
+ nodes. See CLI.rst_ for details.
-FTP, SFTP
+SFTP, FTP
- Tahoe can also run both FTP and SFTP servers, and map a username/password
- pair to a top-level Tahoe directory. See `<frontends/FTP-and-SFTP.rst>`_
- for instructions on configuring these services, and the ``[ftpd]`` and
- ``[sftpd]`` sections of ``tahoe.cfg``.
+ Tahoe can also run both SFTP and FTP servers, and map a username/password
+ pair to a top-level Tahoe directory. See FTP-and-SFTP.rst_ for
+ instructions on configuring these services, and the ``[sftpd]`` and
+ ``[ftpd]`` sections of ``tahoe.cfg``.
Drop-Upload
As of Tahoe-LAFS v1.9.0, a node running on Linux can be configured to
automatically upload files that are created or changed in a specified
- local directory. See `<frontends/drop_upload.rst>`_ for details.
+ local directory. See drop-upload.rst_ for details.
+.. _download-status.rst: frontends/download-status.rst
+.. _CLI.rst: frontends/CLI.rst
+.. _FTP-and-SFTP.rst: frontends/FTP-and-SFTP.rst
+.. _drop-upload.rst: frontends/drop-upload.rst
Storage Server Configuration
that are being decommissioned: the ``storage/`` directory could be
mounted read-only, while shares are moved to other servers. Note that
this currently only affects immutable shares. Mutable shares (used for
- directories) will be written and modified anyway. See ticket `#390
- <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/390>`_ for the current
- status of this bug. The default value is ``False``.
+ directories) will be written and modified anyway. See ticket `#390`_ for
+ the current status of this bug. The default value is ``False``.
``reserved_space = (str, optional)``
If provided, this value defines how much disk space is reserved: the
storage server will not accept any share that causes the amount of free
disk space to drop below this value. (The free space is measured by a
- call to statvfs(2) on Unix, or GetDiskFreeSpaceEx on Windows, and is the
- space available to the user account under which the storage server runs.)
+ call to ``statvfs(2)`` on Unix, or ``GetDiskFreeSpaceEx`` on Windows, and
+ is the space available to the user account under which the storage server
+ runs.)
This string contains a number, with an optional case-insensitive scale
- suffix like "K" or "M" or "G", and an optional "B" or "iB" suffix. So
- "100MB", "100M", "100000000B", "100000000", and "100000kb" all mean the
- same thing. Likewise, "1MiB", "1024KiB", and "1048576B" all mean the same
- thing.
+ suffix, optionally followed by "B" or "iB". The supported scale suffixes
+ are "K", "M", "G", "T", "P" and "E", and a following "i" indicates to use
+ powers of 1024 rather than 1000. So "100MB", "100 M", "100000000B",
+ "100000000", and "100000kb" all mean the same thing. Likewise, "1MiB",
+ "1024KiB", "1024 Ki", and "1048576 B" all mean the same thing.
"``tahoe create-node``" generates a tahoe.cfg with
"``reserved_space=1G``", but you may wish to raise, lower, or remove the
These settings control garbage collection, in which the server will
delete shares that no longer have an up-to-date lease on them. Please see
- `<garbage-collection.rst>`_ for full details.
+ garbage-collection.rst_ for full details.
+
+.. _#390: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/390
+.. _garbage-collection.rst: garbage-collection.rst
Running A Helper
``enabled = (boolean, optional)``
- If ``True``, the node will run a helper (see `<helper.rst>`_ for
- details). The helper's contact FURL will be placed in
- ``private/helper.furl``, from which it can be copied to any clients that
- wish to use it. Clearly nodes should not both run a helper and attempt to
- use one: do not create ``helper.furl`` and also define
- ``[helper]enabled`` in the same node. The default is ``False``.
+ If ``True``, the node will run a helper (see helper.rst_ for details).
+ The helper's contact FURL will be placed in ``private/helper.furl``, from
+ which it can be copied to any clients that wish to use it. Clearly nodes
+ should not both run a helper and attempt to use one: do not create
+ ``helper.furl`` and also define ``[helper]enabled`` in the same node.
+ The default is ``False``.
Running An Introducer
The Introducer node maintains some different state than regular client nodes.
-``BASEDIR/introducer.furl``
+``BASEDIR/private/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
``private/helper.furl``
If the node is running a helper (for use by other clients), its contact
- FURL will be placed here. See `<helper.rst>`_ for more details.
+ FURL will be placed here. See helper.rst_ for more details.
``private/root_dir.cap`` (optional)
``access.blacklist``
- Gateway nodes may find it necessary to prohibit access to certain files. The
- web-API has a facility to block access to filecaps by their storage index,
- returning a 403 "Forbidden" error instead of the original file. For more
- details, see the "Access Blacklist" section of `<frontends/webapi.rst>`_.
+ Gateway nodes may find it necessary to prohibit access to certain
+ files. The web-API has a facility to block access to filecaps by their
+ storage index, returning a 403 "Forbidden" error instead of the original
+ file. For more details, see the "Access Blacklist" section of
+ webapi.rst_.
Example
timeout.disconnect = 1800
ssh.port = 8022
ssh.authorized_keys_file = ~/.ssh/authorized_keys
-
-
+
[client]
introducer.furl = pb://ok45ssoklj4y7eok5c3xkmj@tahoe.example:44801/ii3uumo
helper.furl = pb://ggti5ssoklj4y7eok5c3xkmj@helper.tahoe.example:7054/kk8lhr
-
-
+
[storage]
enabled = True
readonly = True
- sizelimit = 10000000000
-
-
+ reserved_space = 10000000000
+
[helper]
enabled = True
Tahoe-LAFS releases before v1.3.0 had no ``tahoe.cfg`` file, and used
distinct files for each item. This is no longer supported and if you have
configuration in the old format you must manually convert it to the new
-format for Tahoe-LAFS to detect it. See `<historical/configuration.rst>`_.
+format for Tahoe-LAFS to detect it. See `historical/configuration.rst`_.
+
+.. _historical/configuration.rst: historical/configuration.rst
projects / tahoe-lafs / tahoe-lafs.git / blobdiff