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
- `<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)``
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.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 `<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
- "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
"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