mirror of
https://github.com/tahoe-lafs/tahoe-lafs.git
synced 2025-01-31 08:25:35 +00:00
doc: formatting: reflow to fill-column=77
This commit is contained in:
Zooko O'Whielacronx
parent
a98a4ec13f
commit
33461a775e
@ -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
|
||||
======================
|
||||
@ -84,9 +84,9 @@ the BASEDIR/tahoe.cfg file::
|
||||
port = tcp:8021:interface=127.0.0.1
|
||||
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.
|
||||
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::
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user