docs/frontends/FTP-and-SFTP.txt

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