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_others.
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
99 renaming.
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 slave
158 communicate over stdin and stdout bypassing network
159 -o disable_hardlink
161 With this option set, attempts to call link(2) will fail with
162 error code ENOSYS.
163 -o transform_symlinks
165 transform absolute symlinks on remote side to relative symlinks.
166 This means that if e.g. on the server side /foo/bar/com is a
167 symlink to /foo/blub, SSHFS will transform the link target to
168 ../blub on the client side.
169 -o follow_symlinks
171 follow symlinks on the server, i.e. present them as regular
172 files on the client. If a symlink is dangling (i.e, the target
173 does not exist) the behavior depends on the remote server - the
174 entry may appear as a symlink on the client, or it may appear as
175 a regular file that cannot be accessed.
176 -o no_check_root
178 don't check for existence of 'dir' on server
179 -o password_stdin
181 read password from stdin (only for pam_mount!)
182 -o dir_cache=BOOL
184 Enables (yes) or disables (no) the SSHFS directory cache. The
185 directory cache holds the names of directory entries. Enabling
186 it allows readdir(3) system calls to be processed without net‐
187 work access.
188 -o dcache_max_size=N
190 sets the maximum size of the directory cache.
191 -o dcache_timeout=N
193 sets timeout for directory cache in seconds.
194 -o dcache_{stat,link,dir}_timeout=N
196 sets separate timeout for {attributes, symlinks, names} in the
197 directory cache.
198 -o dcache_clean_interval=N
200 sets the interval for automatic cleaning of the directory cache.
201 -o dcache_min_clean_interval=N
203 sets the interval for forced cleaning of the directory cache
204 when full.
205 -o direct_io
207 This option disables the use of page cache (file content cache)
208 in the kernel for this filesystem. This has several affects:
209 1. Each read() or write() system call will initiate one or more
211 read or write operations, data will not be cached in the ker‐
212 nel.
213 2. The return value of the read() and write() system calls will
215 correspond to the return values of the read and write opera‐
216 tions. This is useful for example if the file size is not
217 known in advance (before reading it). e.g. /proc filesystem
218 -o max_conns=N
220 sets the maximum number of simultaneous SSH connections to use.
221 Each connection is established with a separate SSH process. The
222 primary purpose of this feature is to improve the responsiveness
223 of the file system during large file transfers. When using more
224 than once connection, the password_stdin and slave options can
225 not be used, and the buflimit workaround is not supported/
226 In addition, SSHFS accepts several options common to all FUSE file sys‐
228 tems. These are described in the mount.fuse3 manpage (look for "gen‐
229 eral", "libfuse specific", and "high-level API" options).
230
232 Hardlinks
233 If the SSH server supports the hardlinks extension, SSHFS will allow
234 you to create hardlinks. However, hardlinks will always appear as indi‐
235 vidual files when seen through an SSHFS mount, i.e. they will appear to
236 have different inodes and an st_nlink value of 1.
237 Rename
239 Some SSH servers do not support atomically overwriting the destination
240 when renaming a file. In this case you will get an error when you
241 attempt to rename a file and the destination already exists. A work‐
242 around is to first remove the destination file, and then do the rename.
243 SSHFS can do this automatically if you call it with -o work‐
244 around=rename. However, in this case it is still possible that someone
245 (or something) recreates the destination file after SSHFS has removed
246 it, but before SSHFS had the time to rename the old file. In this case,
247 the rename will still fail.
248 Permission denied when moving files across remote filesystems
250 Most SFTP servers return only a generic "failure" when failing to
251 rename across filesystem boundaries (EXDEV). sshfs normally converts
252 this generic failure to a permission denied error (EPERM). If the
253 option -o workaround=renamexdev is given, generic failures will be con‐
254 sidered EXDEV errors which will make programs like mv(1) attempt to
255 actually move the file after the failed rename.
256 SSHFS hangs for no apparent reason
258 In some cases, attempts to access the SSHFS mountpoint may freeze if no
259 filesystem activity has occured for some time. This is typically caused
260 by the SSH connection being dropped because of inactivity without SSHFS
261 being informed about that. As a workaround, you can try to mount with
262 -o ServerAliveInterval=15. This will force the SSH connection to stay
263 alive even if you have no activity.
264 SSHFS hangs after the connection was interrupted
266 By default, network operations in SSHFS run without timeouts, mirroring
267 the default behavior of SSH itself. As a consequence, if the connection
268 to the remote host is interrupted (e.g. because a network cable was
269 removed), operations on files or directories under the mountpoint will
270 block until the connection is either restored or closed altogether
271 (e.g. manually). Applications that try to access such files or direc‐
272 tories will generally appear to "freeze" when this happens.
273 If it is acceptable to discard data being read or written, a quick
275 workaround is to kill the responsible sshfs process, which will make
276 any blocking operations on the mounted filesystem error out and thereby
277 "unfreeze" the relevant applications. Note that force unmounting with
278 fusermount -zu, on the other hand, does not help in this case and will
279 leave read/write operations in the blocking state.
280 For a more automatic solution, one can use the -o ServerAliveInter‐
282 val=15 option mentioned above, which will drop the connection after not
283 receiving a response for 3 * 15 = 45 seconds from the remote host. By
284 also supplying -o reconnect, one can ensure that the connection is
285 re-established as soon as possible afterwards. As before, this will
286 naturally lead to loss of data that was in the process of being read or
287 written at the time when the connection was interrupted.
288
290 To mount an SSHFS filesystem from /etc/fstab, simply use sshfs` as the
291 file system type. (For backwards compatibility, you may also use
292 ``fuse.sshfs).
293
295 The mount.fuse(8) manpage.
296
298 If you need help, please ask on the <fuse-sshfs@lists.sourceforge.net>
299 mailing list (subscribe at
300 https://lists.sourceforge.net/lists/listinfo/fuse-sshfs).
301 Please report any bugs on the GitHub issue tracker at
303 https://github.com/libfuse/libfuse/issues.
304
306 SSHFS is currently maintained by Nikolaus Rath <Nikolaus@rath.org>, and
307 was created by Miklos Szeredi <miklos@szeredi.hu>.
308 This man page was originally written by Bartosz Fenski <‐
310 fenio@debian.org> for the Debian GNU/Linux distribution (but it may be
311 used by others).
312 SSHFS(1)