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