=================================
-Tahoe-LAFS FTP and SFTP Frontends
+Tahoe-LAFS SFTP and FTP Frontends
=================================
-1. `FTP/SFTP Background`_
+1. `SFTP/FTP Background`_
2. `Tahoe-LAFS Support`_
3. `Creating an Account File`_
-4. `Configuring FTP Access`_
+4. `Running An Account Server (accounts.url)`_
5. `Configuring SFTP Access`_
-6. `Dependencies`_
-7. `Immutable and mutable files`_
-8. `Known Issues`_
+6. `Configuring FTP Access`_
+7. `Dependencies`_
+8. `Immutable and Mutable Files`_
+9. `Known Issues`_
-FTP/SFTP Background
+SFTP/FTP Background
===================
FTP is the venerable internet file-transfer protocol, first developed in
and passwords, octal file modes (user/group/other, read/write/execute), and
ctime/mtime timestamps.
+We recommend SFTP over FTP, because the protocol is better, and the server
+implementation in Tahoe-LAFS is more complete. See `Known Issues`_, below,
+for details.
+
Tahoe-LAFS Support
==================
-All Tahoe-LAFS client nodes can run a frontend FTP server, allowing regular FTP
-clients (like /usr/bin/ftp, ncftp, and countless others) to access the
-virtual filesystem. They can also run an SFTP server, so SFTP clients (like
-/usr/bin/sftp, the sshfs FUSE plugin, and others) can too. These frontends
-sit at the same level as the web-API interface.
-
-Since Tahoe-LAFS does not use user accounts or passwords, the FTP/SFTP servers
-must be configured with a way to first authenticate a user (confirm that a
-prospective client has a legitimate claim to whatever authorities we might
-grant a particular user), and second to decide what root directory cap should
-be granted to the authenticated username. A username and password is used
-for this purpose. (The SFTP protocol is also capable of using client
-RSA or DSA public keys, but this is not currently implemented.)
-
-Tahoe-LAFS provides two mechanisms to perform this user-to-rootcap mapping. The
+All Tahoe-LAFS client nodes can run a frontend SFTP server, allowing regular
+SFTP clients (like ``/usr/bin/sftp``, the ``sshfs`` FUSE plugin, and many
+others) to access the virtual filesystem. They can also run an FTP server,
+so FTP clients (like ``/usr/bin/ftp``, ``ncftp``, and others) can too. These
+frontends sit at the same level as the web-API interface.
+
+Since Tahoe-LAFS does not use user accounts or passwords, the SFTP/FTP
+servers must be configured with a way to first authenticate a user (confirm
+that a prospective client has a legitimate claim to whatever authorities we
+might grant a particular user), and second to decide what directory cap
+should be used as the root directory for a log-in by the authenticated user.
+A username and password is used for this purpose. (The SFTP protocol is also
+capable of using client RSA or DSA public keys, but this is not currently
+implemented in Tahoe-LAFS.)
+
+Tahoe-LAFS provides two mechanisms to perform this user-to-cap mapping. The
first is a simple flat file with one account per line. The second is an
-HTTP-based login mechanism, backed by simple PHP script and a database. The
-latter form is used by allmydata.com to provide secure access to customer
-rootcaps.
+HTTP-based login mechanism, backed by simple PHP script and a database.
Creating an Account File
========================
-To use the first form, create a file (probably in
-BASEDIR/private/ftp.accounts) in which each non-comment/non-blank line is a
-space-separated line of (USERNAME, PASSWORD, ROOTCAP), like so::
+To use the first form, create a file (for example ``BASEDIR/private/accounts``)
+in which each non-comment/non-blank line is a space-separated line of
+(USERNAME, PASSWORD, ROOTCAP), like so::
- % cat BASEDIR/private/ftp.accounts
- # This is a password line, (username, password, rootcap)
+ % cat BASEDIR/private/accounts
+ # This is a password line, (username, password, cap)
alice password URI:DIR2:ioej8xmzrwilg772gzj4fhdg7a:wtiizszzz2rgmczv4wl6bqvbv33ag4kvbr6prz3u6w3geixa6m6a
bob sekrit URI:DIR2:6bdmeitystckbl9yqlw7g56f4e:serp5ioqxnh34mlbmzwvkp3odehsyrr7eytt5f64we3k9hhcrcja
the public key format, so users cannot have a password equal to either of
these strings.
-Now add an 'accounts.file' directive to your tahoe.cfg file, as described
-in the next sections.
-
-Configuring FTP Access
-======================
+Now add an ``accounts.file`` directive to your ``tahoe.cfg`` file, as described in
+the next sections.
-To enable the FTP server with an accounts file, add the following lines to
-the BASEDIR/tahoe.cfg file::
+Running An Account Server (accounts.url)
+========================================
- [ftpd]
- enabled = true
- port = tcp:8021:interface=127.0.0.1
- accounts.file = private/ftp.accounts
+The accounts.url directive allows access requests to be controlled by an
+HTTP-based login service, useful for centralized deployments. This was used
+by AllMyData to provide web-based file access, where the service used a
+simple PHP script and database lookups to map an account email address and
+password to a Tahoe-LAFS directory cap. The service will receive a
+multipart/form-data POST, just like one created with a <form> and <input>
+fields, with three parameters:
-The FTP server will listen on the given port number and on the loopback
-interface only. The "accounts.file" pathname will be interpreted
-relative to the node's BASEDIR.
+• action: "authenticate" (this is a static string, for backwards
+ compatibility with the old AllMyData authentication service)
+• email: USERNAME (Tahoe-LAFS has no notion of email addresses, but the
+ authentication service uses them as account names, so the interface
+ presents this argument as "email" rather than "username").
+• passwd: PASSWORD
-To enable the FTP server with an account server instead, provide the URL of
-that server in an "accounts.url" directive::
+It should return a single string that either contains a Tahoe-LAFS directory
+cap (URI:DIR2:...), or "0" to indicate a login failure.
- [ftpd]
- enabled = true
- port = tcp:8021:interface=127.0.0.1
- accounts.url = https://example.com/login
-
-You can provide both accounts.file and accounts.url, although it probably
-isn't very useful except for testing.
-
-FTP provides no security, and so your password or caps could be eavesdropped
-if you connect to the FTP server remotely. The examples above include
-":interface=127.0.0.1" in the "port" option, which causes the server to only
-accept connections from localhost.
+Tahoe-LAFS recommends the service be secure, preferably localhost-only. This
+makes it harder for attackers to brute force the password or use DNS
+poisoning to cause the Tahoe-LAFS gateway to talk with the wrong server,
+thereby revealing the usernames and passwords.
Configuring SFTP Access
=======================
can connect to the SFTP server (which is provided by the Tahoe-LAFS gateway)
only from a client on the same host, then you would be safe from any problem
with the SFTP connection security. The examples given below enforce this
-policy by including ":interface=127.0.0.1" in the "port" option, which
-causes the server to only accept connections from localhost.
+policy by including ":interface=127.0.0.1" in the "port" option, which causes
+the server to only accept connections from localhost.
You will use directives in the tahoe.cfg file to tell the SFTP code where to
find these keys. To create one, use the ``ssh-keygen`` tool (which comes with
-the standard openssh client distribution)::
+the standard OpenSSH client distribution)::
% cd BASEDIR
% ssh-keygen -f private/ssh_host_rsa_key
port = tcp:8022:interface=127.0.0.1
host_pubkey_file = private/ssh_host_rsa_key.pub
host_privkey_file = private/ssh_host_rsa_key
- accounts.file = private/ftp.accounts
+ accounts.file = private/accounts
The SFTP server will listen on the given port number and on the loopback
-interface only. The "accounts.file" pathname will be interpreted
-relative to the node's BASEDIR.
+interface only. The "accounts.file" pathname will be interpreted relative to
+the node's BASEDIR.
Or, to use an account server instead, do this::
isn't very useful except for testing.
For further information on SFTP compatibility and known issues with various
-clients and with the sshfs filesystem, see
-http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend .
+clients and with the sshfs filesystem, see wiki:SftpFrontend_
+
+.. _wiki:SftpFrontend: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend
+
+Configuring FTP Access
+======================
+
+To enable the FTP server with an accounts file, add the following lines to
+the BASEDIR/tahoe.cfg file::
+
+ [ftpd]
+ enabled = true
+ port = tcp:8021:interface=127.0.0.1
+ accounts.file = private/accounts
+
+The FTP server will listen on the given port number and on the loopback
+interface only. The "accounts.file" pathname will be interpreted relative to
+the node's BASEDIR.
+
+To enable the FTP server with an account server instead, provide the URL of
+that server in an "accounts.url" directive::
+
+ [ftpd]
+ enabled = true
+ port = tcp:8021:interface=127.0.0.1
+ accounts.url = https://example.com/login
+
+You can provide both accounts.file and accounts.url, although it probably
+isn't very useful except for testing.
+
+FTP provides no security, and so your password or caps could be eavesdropped
+if you connect to the FTP server remotely. The examples above include
+":interface=127.0.0.1" in the "port" option, which causes the server to only
+accept connections from localhost.
Dependencies
============
-The Tahoe-LAFS SFTP server requires the Twisted "Conch" component (a "conch" is
-a twisted shell, get it?). Many Linux distributions package the Conch code
+The Tahoe-LAFS SFTP server requires the Twisted "Conch" component (a "conch"
+is a twisted shell, get it?). Many Linux distributions package the Conch code
separately: debian puts it in the "python-twisted-conch" package. Conch
requires the "pycrypto" package, which is a Python+C implementation of many
cryptographic functions (the debian package is named "python-crypto").
-Note that "pycrypto" is different than the "pycryptopp" package that Tahoe-LAFS
-uses (which is a Python wrapper around the C++ -based Crypto++ library, a
-library that is frequently installed as /usr/lib/libcryptopp.a, to avoid
-problems with non-alphanumerics in filenames).
-
-The FTP server requires code in Twisted that enables asynchronous closing of
-file-upload operations. This code was landed to Twisted's SVN trunk in r28453
-on 23-Feb-2010, slightly too late for the Twisted-10.0 release, but it should
-be present in the next release after that. To use Tahoe-LAFS's FTP server with
-Twisted-10.0 or earlier, you will need to apply the patch attached to
-http://twistedmatrix.com/trac/ticket/3462 . The Tahoe-LAFS node will refuse to
-start the FTP server unless it detects the necessary support code in Twisted.
-This patch is not needed for SFTP.
+Note that "pycrypto" is different than the "pycryptopp" package that
+Tahoe-LAFS uses (which is a Python wrapper around the C++ -based Crypto++
+library, a library that is frequently installed as /usr/lib/libcryptopp.a, to
+avoid problems with non-alphanumerics in filenames).
Immutable and Mutable Files
===========================
-All files created via SFTP (and FTP) are immutable files. However, files
-can only be created in writeable directories, which allows the directory
-entry to be relinked to a different file. Normally, when the path of an
-immutable file is opened for writing by SFTP, the directory entry is
-relinked to another file with the newly written contents when the file
-handle is closed. The old file is still present on the grid, and any other
-caps to it will remain valid. (See `docs/garbage-collection.rst
-<../garbage-collection.rst>`_ for how to reclaim the space used by files
-that are no longer needed.)
+All files created via SFTP (and FTP) are immutable files. However, files can
+only be created in writeable directories, which allows the directory entry to
+be relinked to a different file. Normally, when the path of an immutable file
+is opened for writing by SFTP, the directory entry is relinked to another
+file with the newly written contents when the file handle is closed. The old
+file is still present on the grid, and any other caps to it will remain
+valid. (See `docs/garbage-collection.rst`_ for how to reclaim the space used
+by files that are no longer needed.)
The 'no-write' metadata field of a directory entry can override this
behaviour. If the 'no-write' field holds a true value, then a permission
writeable directory. This does not prevent the directory entry from being
unlinked or replaced.
-When using sshfs, the 'no-write' field can be set by clearing the 'w'
-bits in the Unix permissions, for example using the command
-'chmod 444 path/to/file'. Note that this does not mean that arbitrary
-combinations of Unix permissions are supported. If the 'w' bits are
-cleared on a link to a mutable file or directory, that link will become
-read-only.
+When using sshfs, the 'no-write' field can be set by clearing the 'w' bits in
+the Unix permissions, for example using the command ``chmod 444 path/to/file``.
+Note that this does not mean that arbitrary combinations of Unix permissions
+are supported. If the 'w' bits are cleared on a link to a mutable file or
+directory, that link will become read-only.
-If SFTP is used to write to an existing mutable file, it will publish a
-new version when the file handle is closed.
+If SFTP is used to write to an existing mutable file, it will publish a new
+version when the file handle is closed.
+
+.. _docs/garbage-collection.rst: file:../garbage-collection.rst
Known Issues
============
-Mutable files are not supported by the FTP frontend (`ticket #680
-<http://tahoe-lafs.org/trac/tahoe-lafs/ticket/680>`_). Currently, a directory
-containing mutable files cannot even be listed over FTP.
+Known Issues in the SFTP Frontend
+---------------------------------
-The FTP frontend sometimes fails to report errors, for example if an upload
-fails because it does meet the "servers of happiness" threshold (`ticket #1081
-<http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1081>`_). Upload errors also may not
-be reported when writing files using SFTP via sshfs (`ticket #1059
-<http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1059>`_).
+Upload errors may not be reported when writing files using SFTP via sshfs
+(`ticket #1059`_).
-Non-ASCII filenames are not supported by FTP (`ticket #682
-<http://tahoe-lafs.org/trac/tahoe-lafs/ticket/682>`_). They can be used
-with SFTP only if the client encodes filenames as UTF-8 (`ticket #1089
-<http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1089>`_).
+Non-ASCII filenames are supported with SFTP only if the client encodes
+filenames as UTF-8 (`ticket #1089`_).
-The gateway node may incur a memory leak when accessing many files via SFTP
-(`ticket #1045 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1045>`_).
+The gateway node may hang or consume 100% CPU if the client tries to rekey.
+(`ticket #1297`_). This is due to a bug in Twisted (`Twisted ticket #4395`_)
+which was fixed in Twisted 11.0 (released 3-April-2011).
+
+See also wiki:SftpFrontend_.
+
+.. _ticket #1059: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1059
+.. _ticket #1089: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1089
+.. _ticket #1297: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1297
+.. _Twisted ticket #4395: https://twistedmatrix.com/trac/ticket/4395
+
+Known Issues in the FTP Frontend
+--------------------------------
+
+Mutable files are not supported by the FTP frontend (`ticket #680`_).
+
+Non-ASCII filenames are not supported by FTP (`ticket #682`_).
+
+The FTP frontend sometimes fails to report errors, for example if an upload
+fails because it does meet the "servers of happiness" threshold (`ticket
+#1081`_).
-For other known issues in SFTP, see
-<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>.
+.. _ticket #680: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/680
+.. _ticket #682: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/682
+.. _ticket #1081: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1081
projects / tahoe-lafs / tahoe-lafs.git / blobdiff