+.. -*- coding: utf-8-with-signature -*-
+
=============================
Configuring a Tahoe-LAFS node
=============================
-1. `Node Types`_
+1. `Node Types`_
2. `Overall Node Configuration`_
3. `Client Configuration`_
4. `Storage Server Configuration`_
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>`_.
- Please note, if interface= is not specified, Tahoe-LAFS will attempt to
- bind the port specified on all interfaces.
+ 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
==========
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 <frontends/webapi.rst>_`.
+ 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
this when using a Tor proxy to avoid revealing your actual IP address
through the Introducer announcement.
+ If ``tub.location`` is specified, by default it entirely replaces the
+ automatically determined set of IP addresses. To include the automatically
+ determined addresses as well as the specified ones, include the uppercase
+ string "``AUTO``" in the list.
+
The value is a comma-separated string of host:port location hints, like
this::
tub.port = 8098
tub.location = tahoe.example.com:8098
+ * Use a DNS name but also include the default set of addresses::
+
+ tub.port = 8098
+ tub.location = tahoe.example.com:8098,AUTO
+
* Run a node behind a firewall (which has an external IP address) that
has been configured to forward port 7912 to our internal node's port
8098::
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
- <https://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)
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>`_.
+ webapi.rst_.
Example
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