docs/frontends/FTP-and-SFTP.rst

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