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

Last change on this file was 7b1bfad, checked in by Itamar Turner-Trauring <itamar@…>, at 2021-01-06T18:39:52Z

Rip out FTP.

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