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 In addition, SSHFS accepts several options common to all FUSE file sys‐
201 tems. These are described in the mount.fuse manpage (look for "gen‐
202 eral", "libfuse specific", and "high-level API" options).
203
205 Hardlinks
206 If the SSH server supports the hardlinks extension, SSHFS will allow
207 you to create hardlinks. However, hardlinks will always appear as indi‐
208 vidual files when seen through an SSHFS mount, i.e. they will appear to
209 have different inodes and an st_nlink value of 1.
210 Rename
212 Some SSH servers do not support atomically overwriting the destination
213 when renaming a file. In this case you will get an error when you
214 attempt to rename a file and the destination already exists. A work‐
215 around is to first remove the destination file, and then do the rename.
216 SSHFS can do this automatically if you call it with -o work‐
217 around=rename. However, in this case it is still possible that someone
218 (or something) recreates the destination file after SSHFS has removed
219 it, but before SSHFS had the time to rename the old file. In this case,
220 the rename will still fail.
221 Permission denied when moving files across remote filesystems
223 Most SFTP servers return only a generic "failure" when failing to
224 rename across filesystem boundaries (EXDEV). sshfs normally converts
225 this generic failure to a permission denied error (EPERM). If the
226 option -o workaround=renamexdev is given, generic failures will be con‐
227 sidered EXDEV errors which will make programs like mv(1) attempt to
228 actually move the file after the failed rename.
229 SSHFS hangs for no apparent reason
231 In some cases, attempts to access the SSHFS mountpoint may freeze if no
232 filesystem activity has occured for some time. This is typically caused
233 by the SSH connection being dropped because of inactivity without SSHFS
234 being informed about that. As a workaround, you can try to mount with
235 -o ServerAliveInterval=15. This will force the SSH connection to stay
236 alive even if you have no activity.
237 SSHFS hangs after the connection was interrupted
239 By default, network operations in SSHFS run without timeouts, mirroring
240 the default behavior of SSH itself. As a consequence, if the connection
241 to the remote host is interrupted (e.g. because a network cable was
242 removed), operations on files or directories under the mountpoint will
243 block until the connection is either restored or closed altogether
244 (e.g. manually). Applications that try to access such files or direc‐
245 tories will generally appear to "freeze" when this happens.
246 If it is acceptable to discard data being read or written, a quick
248 workaround is to kill the responsible sshfs process, which will make
249 any blocking operations on the mounted filesystem error out and thereby
250 "unfreeze" the relevant applications. Note that force unmounting with
251 fusermount -zu, on the other hand, does not help in this case and will
252 leave read/write operations in the blocking state.
253 For a more automatic solution, one can use the -o ServerAliveInter‐
255 val=15 option mentioned above, which will drop the connection after not
256 receiving a response for 3 * 15 = 45 seconds from the remote host. By
257 also supplying -o reconnect, one can ensure that the connection is
258 re-established as soon as possible afterwards. As before, this will
259 naturally lead to loss of data that was in the process of being read or
260 written at the time when the connection was interrupted.
261
263 To mount an SSHFS filesystem from /etc/fstab, simply use sshfs` as the
264 file system type. (For backwards compatibility, you may also use
265 ``fuse.sshfs).
266
268 The mount.fuse(8) manpage.
269
271 If you need help, please ask on the <fuse-sshfs@lists.sourceforge.net>
272 mailing list (subscribe at
273 https://lists.sourceforge.net/lists/listinfo/fuse-sshfs).
274 Please report any bugs on the GitHub issue tracker at
276 https://github.com/libfuse/libfuse/issues.
277
279 SSHFS is currently maintained by Nikolaus Rath <Nikolaus@rath.org>, and
280 was created by Miklos Szeredi <miklos@szeredi.hu>.
281 This man page was originally written by Bartosz Fenski <‐
283 fenio@debian.org> for the Debian GNU/Linux distribution (but it may be
284 used by others).
285 SSHFS(1)