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 SSHFS uses FUSE (Filesystem in Userspace) and should work on any oper‐
28 ating system that provides a FUSE implementation. Currently, this
29 includes Linux, FreeBSD and Mac OS X.
30 It is recommended to run SSHFS as regular user (not as root). For this
32 to work the mountpoint must be owned by the user. If username is omit‐
33 ted SSHFS will use the local username. If the directory is omitted,
34 SSHFS will mount the (remote) home directory. If you need to enter a
35 password sshfs will ask for it (actually it just runs ssh which ask for
36 the password if needed).
37
39 -o opt,[opt...]
40 mount options, see below for details. A a variety of SSH options
41 can be given here as well, see the manual pages for sftp(1) and
42 ssh_config(5).
43 -h, --help
45 print help and exit.
46 -V, --version
48 print version information and exit.
49 -d, --debug
51 print debugging information.
52 -p PORT
54 equivalent to '-o port=PORT'
55 -f do not daemonize, stay in foreground.
57 -s Single threaded operation.
59 -C equivalent to '-o compression=yes'
61 -F ssh_configfile
63 specifies alternative ssh configuration file
64 -1 equivalent to '-o ssh_protocol=1'
66 -o reconnect
68 automatically reconnect to server if connection is interrupted.
69 Attempts to access files that were opened before the reconnec‐
70 tion will give errors and need to be re-opened.
71 -o delay_connect
73 Don't immediately connect to server, wait until mountpoint is
74 first accessed.
75 -o sshfs_sync
77 synchronous writes. This will slow things down, but may be use‐
78 ful in some situations.
79 -o no_readahead
81 Only read exactly the data that was requested, instead of specu‐
82 latively reading more to anticipate the next read request.
83 -o sync_readdir
85 synchronous readdir. This will slow things down, but may be use‐
86 ful in some situations.
87 -o workaround=LIST
89 Enable the specified workaround. See the Caveats section below
90 for some additional information. Possible values are:
91 rename Emulate overwriting an existing file by deleting and
93 renaming.
94 renamexdev
96 Make rename fail with EXDEV instead of the default EPERM
97 to allow moving files across remote filesystems.
98 truncate
100 Work around servers that don't support truncate by coping
101 the whole file, truncating it locally, and sending it
102 back.
103 fstat Work around broken servers that don't support fstat() by
105 using stat instead.
106 buflimit
108 Work around OpenSSH "buffer fillup" bug.
109 createmode
111 Work around broken servers that produce an error when
112 passing a non-zero mode to create, by always passing a
113 mode of 0.
114 -o idmap=TYPE
116 How to map remote UID/GIDs to local values. Possible values are:
117 none no translation of the ID space (default).
119 user map the UID/GID of the remote user to UID/GID of the
121 mounting user.
122 file translate UIDs/GIDs based upon the contents of --uidfile
124 and --gidfile.
125 -o uidfile=FILE
127 file containing username:uid mappings for -o idmap=file
128 -o gidfile=FILE
130 file containing groupname:gid mappings for -o idmap=file
131 -o nomap=TYPE
133 with idmap=file, how to handle missing mappings:
134 ignore don't do any re-mapping
136 error return an error (default)
138 -o ssh_command=CMD
140 execute CMD instead of 'ssh'
141 -o ssh_protocol=N
143 ssh protocol to use (default: 2)
144 -o sftp_server=SERV
146 path to sftp server or subsystem (default: sftp)
147 -o directport=PORT
149 directly connect to PORT bypassing ssh
150 -o slave
152 communicate over stdin and stdout bypassing network
153 -o disable_hardlink
155 With this option set, attempts to call link(2) will fail with
156 error code ENOSYS.
157 -o transform_symlinks
159 transform absolute symlinks on remote side to relative symlinks.
160 This means that if e.g. on the server side /foo/bar/com is a
161 symlink to /foo/blub, SSHFS will transform the link target to
162 ../blub on the client side.
163 -o follow_symlinks
165 follow symlinks on the server, i.e. present them as regular
166 files on the client. If a symlink is dangling (i.e, the target
167 does not exist) the behavior depends on the remote server - the
168 entry may appear as a symlink on the client, or it may appear as
169 a regular file that cannot be accessed.
170 -o no_check_root
172 don't check for existence of 'dir' on server
173 -o password_stdin
175 read password from stdin (only for pam_mount!)
176 -o dir_cache=BOOL
178 Enables (yes) or disables (no) the SSHFS directory cache. The
179 directory cache holds the names of directory entries. Enabling
180 it allows readdir(3) system calls to be processed without net‐
181 work access.
182 -o dcache_max_size=N
184 sets the maximum size of the directory cache.
185 -o dcache_timeout=N
187 sets timeout for directory cache in seconds.
188 -o dcache_{stat,link,dir}_timeout=N
190 sets separate timeout for {attributes, symlinks, names} in the
191 directory cache.
192 -o dcache_clean_interval=N
194 sets the interval for automatic cleaning of the directory cache.
195 -o dcache_min_clean_interval=N
197 sets the interval for forced cleaning of the directory cache
198 when full.
199 -o direct_io
201 This option disables the use of page cache (file content cache)
202 in the kernel for this filesystem. This has several affects: 1.
203 Each read() or write() system call will initiate one or more
204 read or
205 System Message: ERROR/3 (../sshfs.rst:, line 210)
207 Unexpected indentation.
208 write operations, data will not be cached in the kernel.
209 System Message: WARNING/2 (../sshfs.rst:, line 211)
211 Block quote ends without a blank line; unexpected unindent.
212 2. The return value of the read() and write() system calls will
214 correspond to the return values of the read and write opera‐
215 tions. This is useful for example if the file size is not
216 known in advance (before reading it). e.g. /proc filesystem
217 In addition, SSHFS accepts several options common to all FUSE file sys‐
219 tems. These are described in the mount.fuse manpage (look for "gen‐
220 eral", "libfuse specific", and "high-level API" options).
221
223 Hardlinks
224 If the SSH server supports the hardlinks extension, SSHFS will allow
225 you to create hardlinks. However, hardlinks will always appear as indi‐
226 vidual files when seen through an SSHFS mount, i.e. they will appear to
227 have different inodes and an st_nlink value of 1.
228 Rename
230 Some SSH servers do not support atomically overwriting the destination
231 when renaming a file. In this case you will get an error when you
232 attempt to rename a file and the destination already exists. A work‐
233 around is to first remove the destination file, and then do the rename.
234 SSHFS can do this automatically if you call it with -o work‐
235 around=rename. However, in this case it is still possible that someone
236 (or something) recreates the destination file after SSHFS has removed
237 it, but before SSHFS had the time to rename the old file. In this case,
238 the rename will still fail.
239 Permission denied when moving files across remote filesystems
241 Most SFTP servers return only a generic "failure" when failing to
242 rename across filesystem boundaries (EXDEV). sshfs normally converts
243 this generic failure to a permission denied error (EPERM). If the
244 option -o workaround=renamexdev is given, generic failures will be con‐
245 sidered EXDEV errors which will make programs like mv(1) attempt to
246 actually move the file after the failed rename.
247 SSHFS hangs for no apparent reason
249 In some cases, attempts to access the SSHFS mountpoint may freeze if no
250 filesystem activity has occured for some time. This is typically caused
251 by the SSH connection being dropped because of inactivity without SSHFS
252 being informed about that. As a workaround, you can try to mount with
253 -o ServerAliveInterval=15. This will force the SSH connection to stay
254 alive even if you have no activity.
255 SSHFS hangs after the connection was interrupted
257 By default, network operations in SSHFS run without timeouts, mirroring
258 the default behavior of SSH itself. As a consequence, if the connection
259 to the remote host is interrupted (e.g. because a network cable was
260 removed), operations on files or directories under the mountpoint will
261 block until the connection is either restored or closed altogether
262 (e.g. manually). Applications that try to access such files or direc‐
263 tories will generally appear to "freeze" when this happens.
264 If it is acceptable to discard data being read or written, a quick
266 workaround is to kill the responsible sshfs process, which will make
267 any blocking operations on the mounted filesystem error out and thereby
268 "unfreeze" the relevant applications. Note that force unmounting with
269 fusermount -zu, on the other hand, does not help in this case and will
270 leave read/write operations in the blocking state.
271 For a more automatic solution, one can use the -o ServerAliveInter‐
273 val=15 option mentioned above, which will drop the connection after not
274 receiving a response for 3 * 15 = 45 seconds from the remote host. By
275 also supplying -o reconnect, one can ensure that the connection is
276 re-established as soon as possible afterwards. As before, this will
277 naturally lead to loss of data that was in the process of being read or
278 written at the time when the connection was interrupted.
279
281 To mount an SSHFS filesystem from /etc/fstab, simply use sshfs` as the
282 file system type. (For backwards compatibility, you may also use
283 ``fuse.sshfs).
284
286 The mount.fuse(8) manpage.
287
289 If you need help, please ask on the <fuse-sshfs@lists.sourceforge.net>
290 mailing list (subscribe at
291 https://lists.sourceforge.net/lists/listinfo/fuse-sshfs).
292 Please report any bugs on the GitHub issue tracker at
294 https://github.com/libfuse/libfuse/issues.
295
297 SSHFS is currently maintained by Nikolaus Rath <Nikolaus@rath.org>, and
298 was created by Miklos Szeredi <miklos@szeredi.hu>.
299 This man page was originally written by Bartosz Fenski <‐
301 fenio@debian.org> for the Debian GNU/Linux distribution (but it may be
302 used by others).
303 SSHFS(1)