ExternalVendorCode/tahoe-lafs
1
0
Fork 0
mirror of https://github.com/tahoe-lafs/tahoe-lafs.git synced 2025-01-31 08:25:35 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

doc: formatting: reflow to fill-column=77

Browse Source
This commit is contained in:
Zooko O'Whielacronx 2011-08-09 06:25:10 -07:00
parent a98a4ec13f
commit 33461a775e
1 changed files with 52 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
docs/frontends/FTP-and-SFTP.rst
View File

@ -33,25 +33,25 @@ ctime/mtime timestamps.
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
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.)
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
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.
Tahoe-LAFS provides two mechanisms to perform this user-to-rootcap
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.
Creating an Account File
========================
@ -70,8 +70,8 @@ The words "ssh-rsa" and "ssh-dsa" after the username are reserved to specify
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.
Now add an 'accounts.file' directive to your tahoe.cfg file, as described in
the next sections.
Configuring FTP Access
======================
@ -85,8 +85,8 @@ the BASEDIR/tahoe.cfg file::
accounts.file = private/ftp.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.
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::
@ -122,8 +122,8 @@ the code for encrypting files and directories in Tahoe-LAFS itself. If you
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
@ -145,8 +145,8 @@ lines to the BASEDIR/tahoe.cfg file::
accounts.file = private/ftp.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::
@ -167,29 +167,28 @@ clients and with the sshfs filesystem, see
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).
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 <../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
@ -197,15 +196,14 @@ error will occur when trying to write to the file, even if it is in a
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.
Known Issues
============
@ -215,19 +213,19 @@ Mutable files are not supported by the FTP frontend (`ticket #680
containing mutable files cannot even be listed over FTP.
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>`_).
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>`_).
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/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>`_).
The gateway node may hang or consume 100% CPU if the client tries to rekey.
(`ticket #1297 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1297>`_).
This is due to `a bug in Twisted <http://twistedmatrix.com/trac/ticket/4395>`_
(`ticket #1297 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1297>`_). This
is due to `a bug in Twisted <http://twistedmatrix.com/trac/ticket/4395>`_
which was fixed in Twisted 11.0 (released 3-April-2011).
For options to disable rekeying in various clients in order to work around