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

Last change on this file was 72a3709, checked in by Jason R. Coombs <jaraco@…>, at 2021-04-17T22:24:22Z

Remove ToC entry for account server.

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