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