docs/frontends/FTP-and-SFTP.rst

   1 =================================
   2 Tahoe-LAFS FTP and SFTP Frontends
   3 =================================
   4
   5 1.  `FTP/SFTP Background`_
   6 2.  `Tahoe-LAFS Support`_
   7 3.  `Creating an Account File`_
   8 4.  `Configuring FTP Access`_
   9 5.  `Configuring SFTP Access`_
  10 6.  `Dependencies`_
  11 7.  `Immutable and mutable files`_
  12 8.  `Known Issues`_
  13
  14
  15 FTP/SFTP Background
  16 ===================
  17
  18 FTP is the venerable internet file-transfer protocol, first developed in
  19 1971. The FTP server usually listens on port 21. A separate connection is
  20 used for the actual data transfers, either in the same direction as the
  21 initial client-to-server connection (for PORT mode), or in the reverse
  22 direction (for PASV) mode. Connections are unencrypted, so passwords, file
  23 names, and file contents are visible to eavesdroppers.
  24
  25 SFTP is the modern replacement, developed as part of the SSH "secure shell"
  26 protocol, and runs as a subchannel of the regular SSH connection. The SSH
  27 server usually listens on port 22. All connections are encrypted.
  28
  29 Both FTP and SFTP were developed assuming a UNIX-like server, with accounts
  30 and passwords, octal file modes (user/group/other, read/write/execute), and
  31 ctime/mtime timestamps.
  32
  33 Tahoe-LAFS Support
  34 ==================
  35
  36 All Tahoe-LAFS client nodes can run a frontend FTP server, allowing regular FTP
  37 clients (like /usr/bin/ftp, ncftp, and countless others) to access the
  38 virtual filesystem. They can also run an SFTP server, so SFTP clients (like
  39 /usr/bin/sftp, the sshfs FUSE plugin, and others) can too. These frontends
  40 sit at the same level as the web-API interface.
  41
  42 Since Tahoe-LAFS does not use user accounts or passwords, the FTP/SFTP servers
  43 must be configured with a way to first authenticate a user (confirm that a
  44 prospective client has a legitimate claim to whatever authorities we might
  45 grant a particular user), and second to decide what root directory cap should
  46 be granted to the authenticated username. A username and password is used
  47 for this purpose. (The SFTP protocol is also capable of using client
  48 RSA or DSA public keys, but this is not currently implemented.)
  49
  50 Tahoe-LAFS provides two mechanisms to perform this user-to-rootcap mapping. The
  51 first is a simple flat file with one account per line. The second is an
  52 HTTP-based login mechanism, backed by simple PHP script and a database. The
  53 latter form is used by allmydata.com to provide secure access to customer
  54 rootcaps.
  55
  56 Creating an Account File
  57 ========================
  58
  59 To use the first form, create a file (probably in
  60 BASEDIR/private/ftp.accounts) in which each non-comment/non-blank line is a
  61 space-separated line of (USERNAME, PASSWORD, ROOTCAP), like so::
  62
  63  % cat BASEDIR/private/ftp.accounts
  64  # This is a password line, (username, password, rootcap)
  65  alice password URI:DIR2:ioej8xmzrwilg772gzj4fhdg7a:wtiizszzz2rgmczv4wl6bqvbv33ag4kvbr6prz3u6w3geixa6m6a
  66  bob sekrit URI:DIR2:6bdmeitystckbl9yqlw7g56f4e:serp5ioqxnh34mlbmzwvkp3odehsyrr7eytt5f64we3k9hhcrcja
  67
  68 Future versions of Tahoe-LAFS may support using client public keys for SFTP.
  69 The words "ssh-rsa" and "ssh-dsa" after the username are reserved to specify
  70 the public key format, so users cannot have a password equal to either of
  71 these strings.
  72
  73 Now add an 'accounts.file' directive to your tahoe.cfg file, as described
  74 in the next sections.
  75
  76 Configuring FTP Access
  77 ======================
  78
  79 To enable the FTP server with an accounts file, add the following lines to
  80 the BASEDIR/tahoe.cfg file::
  81
  82  [ftpd]
  83  enabled = true
  84  port = tcp:8021:interface=127.0.0.1
  85  accounts.file = private/ftp.accounts
  86
  87 The FTP server will listen on the given port number and on the loopback
  88 interface only. The "accounts.file" pathname will be interpreted
  89 relative to the node's BASEDIR.
  90
  91 To enable the FTP server with an account server instead, provide the URL of
  92 that server in an "accounts.url" directive::
  93
  94  [ftpd]
  95  enabled = true
  96  port = tcp:8021:interface=127.0.0.1
  97  accounts.url = https://example.com/login
  98
  99 You can provide both accounts.file and accounts.url, although it probably
 100 isn't very useful except for testing.
 101
 102 FTP provides no security, and so your password or caps could be eavesdropped
 103 if you connect to the FTP server remotely. The examples above include
 104 ":interface=127.0.0.1" in the "port" option, which causes the server to only
 105 accept connections from localhost.
 106
 107 Configuring SFTP Access
 108 =======================
 109
 110 The Tahoe-LAFS SFTP server requires a host keypair, just like the regular SSH
 111 server. It is important to give each server a distinct keypair, to prevent
 112 one server from masquerading as different one. The first time a client
 113 program talks to a given server, it will store the host key it receives, and
 114 will complain if a subsequent connection uses a different key. This reduces
 115 the opportunity for man-in-the-middle attacks to just the first connection.
 116
 117 Exercise caution when connecting to the SFTP server remotely. The AES
 118 implementation used by the SFTP code does not have defenses against timing
 119 attacks. The code for encrypting the SFTP connection was not written by the
 120 Tahoe-LAFS team, and we have not reviewed it as carefully as we have reviewed
 121 the code for encrypting files and directories in Tahoe-LAFS itself. If you
 122 can connect to the SFTP server (which is provided by the Tahoe-LAFS gateway)
 123 only from a client on the same host, then you would be safe from any problem
 124 with the SFTP connection security. The examples given below enforce this
 125 policy by including ":interface=127.0.0.1" in the "port" option, which
 126 causes the server to only accept connections from localhost.
 127
 128 You will use directives in the tahoe.cfg file to tell the SFTP code where to
 129 find these keys. To create one, use the ``ssh-keygen`` tool (which comes with
 130 the standard openssh client distribution)::
 131
 132  % cd BASEDIR
 133  % ssh-keygen -f private/ssh_host_rsa_key
 134
 135 The server private key file must not have a passphrase.
 136
 137 Then, to enable the SFTP server with an accounts file, add the following
 138 lines to the BASEDIR/tahoe.cfg file::
 139
 140  [sftpd]
 141  enabled = true
 142  port = tcp:8022:interface=127.0.0.1
 143  host_pubkey_file = private/ssh_host_rsa_key.pub
 144  host_privkey_file = private/ssh_host_rsa_key
 145  accounts.file = private/ftp.accounts
 146
 147 The SFTP server will listen on the given port number and on the loopback
 148 interface only. The "accounts.file" pathname will be interpreted
 149 relative to the node's BASEDIR.
 150
 151 Or, to use an account server instead, do this::
 152
 153  [sftpd]
 154  enabled = true
 155  port = tcp:8022:interface=127.0.0.1
 156  host_pubkey_file = private/ssh_host_rsa_key.pub
 157  host_privkey_file = private/ssh_host_rsa_key
 158  accounts.url = https://example.com/login
 159
 160 You can provide both accounts.file and accounts.url, although it probably
 161 isn't very useful except for testing.
 162
 163 For further information on SFTP compatibility and known issues with various
 164 clients and with the sshfs filesystem, see
 165 `<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>`_.
 166
 167 Dependencies
 168 ============
 169
 170 The Tahoe-LAFS SFTP server requires the Twisted "Conch" component (a "conch" is
 171 a twisted shell, get it?). Many Linux distributions package the Conch code
 172 separately: debian puts it in the "python-twisted-conch" package. Conch
 173 requires the "pycrypto" package, which is a Python+C implementation of many
 174 cryptographic functions (the debian package is named "python-crypto").
 175
 176 Note that "pycrypto" is different than the "pycryptopp" package that Tahoe-LAFS
 177 uses (which is a Python wrapper around the C++ -based Crypto++ library, a
 178 library that is frequently installed as /usr/lib/libcryptopp.a, to avoid
 179 problems with non-alphanumerics in filenames).
 180
 181 Immutable and Mutable Files
 182 ===========================
 183
 184 All files created via SFTP (and FTP) are immutable files. However, files
 185 can only be created in writeable directories, which allows the directory
 186 entry to be relinked to a different file. Normally, when the path of an
 187 immutable file is opened for writing by SFTP, the directory entry is
 188 relinked to another file with the newly written contents when the file
 189 handle is closed. The old file is still present on the grid, and any other
 190 caps to it will remain valid. (See `docs/garbage-collection.rst
 191 <../garbage-collection.rst>`_ for how to reclaim the space used by files
 192 that are no longer needed.)
 193
 194 The 'no-write' metadata field of a directory entry can override this
 195 behaviour. If the 'no-write' field holds a true value, then a permission
 196 error will occur when trying to write to the file, even if it is in a
 197 writeable directory. This does not prevent the directory entry from being
 198 unlinked or replaced.
 199
 200 When using sshfs, the 'no-write' field can be set by clearing the 'w'
 201 bits in the Unix permissions, for example using the command
 202 'chmod 444 path/to/file'. Note that this does not mean that arbitrary
 203 combinations of Unix permissions are supported. If the 'w' bits are
 204 cleared on a link to a mutable file or directory, that link will become
 205 read-only.
 206
 207 If SFTP is used to write to an existing mutable file, it will publish a
 208 new version when the file handle is closed.
 209
 210 Known Issues
 211 ============
 212
 213 Mutable files are not supported by the FTP frontend (`ticket #680
 214 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/680>`_). Currently, a directory
 215 containing mutable files cannot even be listed over FTP.
 216
 217 The FTP frontend sometimes fails to report errors, for example if an upload
 218 fails because it does meet the "servers of happiness" threshold (`ticket #1081
 219 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1081>`_). Upload errors also
 220 may not be reported when writing files using SFTP via sshfs (`ticket #1059
 221 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1059>`_).
 222
 223 Non-ASCII filenames are not supported by FTP (`ticket #682
 224 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/682>`_). They can be used
 225 with SFTP only if the client encodes filenames as UTF-8 (`ticket #1089
 226 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1089>`_).
 227
 228 The gateway node may hang or consume 100% CPU if the client tries to rekey.
 229 (`ticket #1297 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1297>`_).
 230 This is due to `a bug in Twisted <http://twistedmatrix.com/trac/ticket/4395>`_
 231 which was fixed in Twisted 11.0 (released 3-April-2011).
 232
 233 For options to disable rekeying in various clients in order to work around
 234 this issue, and for other known issues in SFTP, see
 235 `<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>`_.