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. `Backwards Compatibility Files`_
+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.
+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>`_.
+ <https://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.
``FURL string``
``pb://soklj4y7eok5c3xkmjeqpw@192.168.69.247:44801/eqpwqtzm``
+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 `webapi.rst
- <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 <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.
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)``
These three values set the default encoding parameters. Each time a new
file is uploaded, erasure-coding is used to break the ciphertext into
- separate pieces. There will be ``N`` (i.e. ``shares.total``) pieces
+ separate shares. There will be ``N`` (i.e. ``shares.total``) shares
created, and the file will be recoverable if any ``k``
- (i.e. ``shares.needed``) pieces are retrieved. The default values are
+ (i.e. ``shares.needed``) shares are retrieved. The default values are
3-of-10 (i.e. ``shares.needed = 3``, ``shares.total = 10``). Setting
``k`` to 1 is equivalent to simple replication (uploading ``N`` copies of
the file).
- These values control the tradeoff between storage overhead, performance,
- and reliability. To a first approximation, a 1MB file will use (1MB *
+ These values control the tradeoff between storage overhead and
+ reliability. To a first approximation, a 1MB file will use (1MB *
``N``/``k``) of backend storage space (the actual value will be a bit
more, because of other forms of overhead). Up to ``N``-``k`` shares can
- be lost before the file becomes unrecoverable, so assuming there are at
- least ``N`` servers, up to ``N``-``k`` servers can be offline without
- losing the file. So large ``N``/``k`` ratios are more reliable, and small
- ``N``/``k`` ratios use less disk space. Clearly, ``k`` must never be
- greater than ``N``.
-
- Large values of ``N`` will slow down upload operations slightly, since
- more servers must be involved, and will slightly increase storage
- overhead due to the hash trees that are created. Large values of ``k``
- will cause downloads to be marginally slower, because more servers must
- be involved. ``N`` cannot be larger than 256, because of the 8-bit
- erasure-coding algorithm that Tahoe-LAFS uses.
-
- ``shares.happy`` allows you control over the distribution of your
- immutable file. For a successful upload, shares are guaranteed to be
- initially placed on at least ``shares.happy`` distinct servers, the
- correct functioning of any ``k`` of which is sufficient to guarantee the
- availability of the uploaded file. This value should not be larger than
- the number of servers on your grid.
+ be lost before the file becomes unrecoverable. So large ``N``/``k``
+ 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.
+
+ ``shares.happy`` allows you control over how well to "spread out" the
+ shares of an immutable file. For a successful upload, shares are
+ guaranteed to be initially placed on at least ``shares.happy`` distinct
+ servers, the correct functioning of any ``k`` of which is sufficient to
+ 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.
(Mutable files use a different share placement algorithm that does not
currently consider this parameter.)
+``mutable.format = sdmf or mdmf``
+
+ This value tells Tahoe-LAFS what the default mutable file format should
+ be. If ``mutable.format=sdmf``, then newly created mutable files will be
+ in the old SDMF format. This is desirable for clients that operate on
+ grids where some peers run older versions of Tahoe-LAFS, as these older
+ versions cannot read the new MDMF mutable file format. If
+ ``mutable.format`` is ``mdmf``, then newly created mutable files will use
+ the new MDMF format, which supports efficient in-place modification and
+ streaming downloads. You can overwrite this value using a special
+ 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 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 `<frontends/specifications/mutable.rst>`_ for details about mutable
+ file formats.
Frontend Configuration
======================
filesystem, uploading/downloading files, and creating/running Tahoe
nodes. See `<frontends/CLI.rst>`_ for details.
-FTP, SFTP
+SFTP, FTP
- Tahoe can also run both FTP and SFTP servers, and map a username/password
+ Tahoe can also run both SFTP and FTP 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``.
+ 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 `<frontends/drop-upload.rst>`_ for details.
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
+ <https://tahoe-lafs.org/trac/tahoe-lafs/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
"which peers am I connected to" list), and the shortened form (the first
few characters) is recorded in various log messages.
+``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>`_.
+
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
projects / tahoe-lafs / tahoe-lafs.git / blobdiff