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