docs/frontends/FTP-and-SFTP.rst

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