1SSHFS(1) User Commands SSHFS(1)
2
6 SSHFS - filesystem client based on SSH
7
9 To mount a filesystem:
10 sshfs [user@]host:[dir] mountpoint [options]
12 If host is a numeric IPv6 address, it needs to be enclosed in square
14 brackets.
15 To unmount it:
17 fusermount3 -u mountpoint # Linux
19 umount mountpoint # OS X, FreeBSD
20
22 SSHFS allows you to mount a remote filesystem using SSH (more pre‐
23 cisely, the SFTP subsystem). Most SSH servers support and enable this
24 SFTP access by default, so SSHFS is very simple to use - there's noth‐
25 ing to do on the server-side.
26 By default, file permissions are ignored by SSHFS. Any user that can
28 access the filesystem will be able to perform any operation that the
29 remote server permits - based on the credentials that were used to con‐
30 nect to the server. If this is undesired, local permission checking can
31 be enabled with -o default_permissions.
32 By default, only the mounting user will be able to access the filesys‐
34 tem. Access for other users can be enabled by passing -o allow_other.
35 In this case you most likely also want to use -o default_permissions.
36 It is recommended to run SSHFS as regular user (not as root). For this
38 to work the mountpoint must be owned by the user. If username is omit‐
39 ted SSHFS will use the local username. If the directory is omitted,
40 SSHFS will mount the (remote) home directory. If you need to enter a
41 password sshfs will ask for it (actually it just runs ssh which ask for
42 the password if needed).
43
45 -o opt,[opt...]
46 mount options, see below for details. A a variety of SSH options
47 can be given here as well, see the manual pages for sftp(1) and
48 ssh_config(5).
49 -h, --help
51 print help and exit.
52 -V, --version
54 print version information and exit.
55 -d, --debug
57 print debugging information.
58 -p PORT
60 equivalent to '-o port=PORT'
61 -f do not daemonize, stay in foreground.
63 -s Single threaded operation.
65 -C equivalent to '-o compression=yes'
67 -F ssh_configfile
69 specifies alternative ssh configuration file
70 -1 equivalent to '-o ssh_protocol=1'
72 -o reconnect
74 automatically reconnect to server if connection is interrupted.
75 Attempts to access files that were opened before the reconnec‐
76 tion will give errors and need to be re-opened.
77 -o delay_connect
79 Don't immediately connect to server, wait until mountpoint is
80 first accessed.
81 -o sshfs_sync
83 synchronous writes. This will slow things down, but may be use‐
84 ful in some situations.
85 -o no_readahead
87 Only read exactly the data that was requested, instead of specu‐
88 latively reading more to anticipate the next read request.
89 -o sync_readdir
91 synchronous readdir. This will slow things down, but may be use‐
92 ful in some situations.
93 -o workaround=LIST
95 Enable the specified workaround. See the Caveats section below
96 for some additional information. Possible values are:
97 rename Emulate overwriting an existing file by deleting and re‐
99 naming.
100 renamexdev
102 Make rename fail with EXDEV instead of the default EPERM
103 to allow moving files across remote filesystems.
104 truncate
106 Work around servers that don't support truncate by coping
107 the whole file, truncating it locally, and sending it
108 back.
109 fstat Work around broken servers that don't support fstat() by
111 using stat instead.
112 buflimit
114 Work around OpenSSH "buffer fillup" bug.
115 createmode
117 Work around broken servers that produce an error when
118 passing a non-zero mode to create, by always passing a
119 mode of 0.
120 -o idmap=TYPE
122 How to map remote UID/GIDs to local values. Possible values are:
123 none no translation of the ID space (default).
125 user map the UID/GID of the remote user to UID/GID of the
127 mounting user.
128 file translate UIDs/GIDs based upon the contents of --uidfile
130 and --gidfile.
131 -o uidfile=FILE
133 file containing username:uid mappings for -o idmap=file
134 -o gidfile=FILE
136 file containing groupname:gid mappings for -o idmap=file
137 -o nomap=TYPE
139 with idmap=file, how to handle missing mappings:
140 ignore don't do any re-mapping
142 error return an error (default)
144 -o ssh_command=CMD
146 execute CMD instead of 'ssh'
147 -o ssh_protocol=N
149 ssh protocol to use (default: 2)
150 -o sftp_server=SERV
152 path to sftp server or subsystem (default: sftp)
153 -o directport=PORT
155 directly connect to PORT bypassing ssh
156 -o passive
158 communicate over stdin and stdout bypassing network. Useful for
159 mounting local filesystem on the remote side. An example using
160 dpipe command would be dpipe /usr/lib/openssh/sftp-server = ssh
161 RemoteHostname sshfs :/directory/to/be/shared ~/mnt/src -o pas‐
162 sive
163 -o disable_hardlink
165 With this option set, attempts to call link(2) will fail with
166 error code ENOSYS.
167 -o transform_symlinks
169 transform absolute symlinks on remote side to relative symlinks.
170 This means that if e.g. on the server side /foo/bar/com is a
171 symlink to /foo/blub, SSHFS will transform the link target to
172 ../blub on the client side.
173 -o follow_symlinks
175 follow symlinks on the server, i.e. present them as regular
176 files on the client. If a symlink is dangling (i.e, the target
177 does not exist) the behavior depends on the remote server - the
178 entry may appear as a symlink on the client, or it may appear as
179 a regular file that cannot be accessed.
180 -o no_check_root
182 don't check for existence of 'dir' on server
183 -o password_stdin
185 read password from stdin (only for pam_mount!)
186 -o dir_cache=BOOL
188 Enables (yes) or disables (no) the SSHFS directory cache. The
189 directory cache holds the names of directory entries. Enabling
190 it allows readdir(3) system calls to be processed without net‐
191 work access.
192 -o dcache_max_size=N
194 sets the maximum size of the directory cache.
195 -o dcache_timeout=N
197 sets timeout for directory cache in seconds.
198 -o dcache_{stat,link,dir}_timeout=N
200 sets separate timeout for {attributes, symlinks, names} in the
201 directory cache.
202 -o dcache_clean_interval=N
204 sets the interval for automatic cleaning of the directory cache.
205 -o dcache_min_clean_interval=N
207 sets the interval for forced cleaning of the directory cache
208 when full.
209 -o direct_io
211 This option disables the use of page cache (file content cache)
212 in the kernel for this filesystem. This has several affects:
213 1. Each read() or write() system call will initiate one or more
215 read or write operations, data will not be cached in the ker‐
216 nel.
217 2. The return value of the read() and write() system calls will
219 correspond to the return values of the read and write opera‐
220 tions. This is useful for example if the file size is not
221 known in advance (before reading it). e.g. /proc filesystem
222 -o max_conns=N
224 sets the maximum number of simultaneous SSH connections to use.
225 Each connection is established with a separate SSH process. The
226 primary purpose of this feature is to improve the responsiveness
227 of the file system during large file transfers. When using more
228 than once connection, the password_stdin and passive options can
229 not be used, and the buflimit workaround is not supported.
230 In addition, SSHFS accepts several options common to all FUSE file sys‐
232 tems. These are described in the mount.fuse3 manpage (look for "gen‐
233 eral", "libfuse specific", and "high-level API" options).
234
236 Hardlinks
237 If the SSH server supports the hardlinks extension, SSHFS will allow
238 you to create hardlinks. However, hardlinks will always appear as indi‐
239 vidual files when seen through an SSHFS mount, i.e. they will appear to
240 have different inodes and an st_nlink value of 1.
241 Rename
243 Some SSH servers do not support atomically overwriting the destination
244 when renaming a file. In this case you will get an error when you at‐
245 tempt to rename a file and the destination already exists. A workaround
246 is to first remove the destination file, and then do the rename. SSHFS
247 can do this automatically if you call it with -o workaround=rename.
248 However, in this case it is still possible that someone (or something)
249 recreates the destination file after SSHFS has removed it, but before
250 SSHFS had the time to rename the old file. In this case, the rename
251 will still fail.
252 Permission denied when moving files across remote filesystems
254 Most SFTP servers return only a generic "failure" when failing to re‐
255 name across filesystem boundaries (EXDEV). sshfs normally converts
256 this generic failure to a permission denied error (EPERM). If the op‐
257 tion -o workaround=renamexdev is given, generic failures will be con‐
258 sidered EXDEV errors which will make programs like mv(1) attempt to ac‐
259 tually move the file after the failed rename.
260 SSHFS hangs for no apparent reason
262 In some cases, attempts to access the SSHFS mountpoint may freeze if no
263 filesystem activity has occurred for some time. This is typically
264 caused by the SSH connection being dropped because of inactivity with‐
265 out SSHFS being informed about that. As a workaround, you can try to
266 mount with -o ServerAliveInterval=15. This will force the SSH connec‐
267 tion to stay alive even if you have no activity.
268 SSHFS hangs after the connection was interrupted
270 By default, network operations in SSHFS run without timeouts, mirroring
271 the default behavior of SSH itself. As a consequence, if the connection
272 to the remote host is interrupted (e.g. because a network cable was re‐
273 moved), operations on files or directories under the mountpoint will
274 block until the connection is either restored or closed altogether
275 (e.g. manually). Applications that try to access such files or direc‐
276 tories will generally appear to "freeze" when this happens.
277 If it is acceptable to discard data being read or written, a quick
279 workaround is to kill the responsible sshfs process, which will make
280 any blocking operations on the mounted filesystem error out and thereby
281 "unfreeze" the relevant applications. Note that force unmounting with
282 fusermount -zu, on the other hand, does not help in this case and will
283 leave read/write operations in the blocking state.
284 For a more automatic solution, one can use the -o ServerAliveInter‐
286 val=15 option mentioned above, which will drop the connection after not
287 receiving a response for 3 * 15 = 45 seconds from the remote host. By
288 also supplying -o reconnect, one can ensure that the connection is
289 re-established as soon as possible afterwards. As before, this will
290 naturally lead to loss of data that was in the process of being read or
291 written at the time when the connection was interrupted.
292
294 To mount an SSHFS filesystem from /etc/fstab, simply use sshfs as the
295 file system type. (For backwards compatibility, you may also use
296 fuse.sshfs).
297
299 The mount.fuse(8) manpage.
300
302 If you need help, please ask on the <fuse-sshfs@lists.sourceforge.net>
303 mailing list (subscribe at
304 https://lists.sourceforge.net/lists/listinfo/fuse-sshfs).
305 Please report any bugs on the GitHub issue tracker at
307 https://github.com/libfuse/libfuse/issues.
308
310 SSHFS is currently maintained by Nikolaus Rath <Nikolaus@rath.org>, and
311 was created by Miklos Szeredi <miklos@szeredi.hu>.
312 This man page was originally written by Bartosz Fenski <‐
314 fenio@debian.org> for the Debian GNU/Linux distribution (but it may be
315 used by others).
316 SSHFS(1)