source: trunk/docs/frontends/FTP-and-SFTP.rst

Last change on this file was 44cddc2, checked in by meejah <meejah@…>, at 2019-06-24T17:23:54Z

conch doesn't require cryptopp any more

(as per exarkun review-comment)

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