1SSHFS(1)                         User Commands                        SSHFS(1)
2
3
4

NAME

6       SSHFS - filesystem client based on SSH
7

SYNOPSIS

9       To mount a filesystem:
10
11          sshfs [user@]host:[dir] mountpoint [options]
12
13       If  host  is  a numeric IPv6 address, it needs to be enclosed in square
14       brackets.
15
16       To unmount it:
17
18          fusermount3 -u mountpoint   # Linux
19          umount mountpoint           # OS X, FreeBSD
20

DESCRIPTION

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
27       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
31       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

OPTIONS

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
44       -h, --help
45              print help and exit.
46
47       -V, --version
48              print version information and exit.
49
50       -d, --debug
51              print debugging information.
52
53       -p PORT
54              equivalent to '-o port=PORT'
55
56       -f     do not daemonize, stay in foreground.
57
58       -s     Single threaded operation.
59
60       -C     equivalent to '-o compression=yes'
61
62       -F ssh_configfile
63              specifies alternative ssh configuration file
64
65       -1     equivalent to '-o ssh_protocol=1'
66
67       -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
72       -o delay_connect
73              Don't immediately connect to server, wait  until  mountpoint  is
74              first accessed.
75
76       -o sshfs_sync
77              synchronous  writes. This will slow things down, but may be use‐
78              ful in some situations.
79
80       -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
84       -o sync_readdir
85              synchronous readdir. This will slow things down, but may be use‐
86              ful in some situations.
87
88       -o workaround=LIST
89              Enable the specified workaround. See the Caveats  section  below
90              for some additional information. Possible values are:
91
92              rename Emulate  overwriting  an  existing  file  by deleting and
93                     renaming.
94
95              renamexdev
96                     Make rename fail with EXDEV instead of the default  EPERM
97                     to allow moving files across remote filesystems.
98
99              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
104              fstat  Work  around broken servers that don't support fstat() by
105                     using stat instead.
106
107              buflimit
108                     Work around OpenSSH "buffer fillup" bug.
109
110              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
115       -o idmap=TYPE
116              How to map remote UID/GIDs to local values. Possible values are:
117
118              none   no translation of the ID space (default).
119
120              user   map the UID/GID of the remote  user  to  UID/GID  of  the
121                     mounting user.
122
123              file   translate  UIDs/GIDs based upon the contents of --uidfile
124                     and --gidfile.
125
126       -o uidfile=FILE
127              file containing username:uid mappings for -o idmap=file
128
129       -o gidfile=FILE
130              file containing groupname:gid mappings for -o idmap=file
131
132       -o nomap=TYPE
133              with idmap=file, how to handle missing mappings:
134
135              ignore don't do any re-mapping
136
137              error  return an error (default)
138
139       -o ssh_command=CMD
140              execute CMD instead of 'ssh'
141
142       -o ssh_protocol=N
143              ssh protocol to use (default: 2)
144
145       -o sftp_server=SERV
146              path to sftp server or subsystem (default: sftp)
147
148       -o directport=PORT
149              directly connect to PORT bypassing ssh
150
151       -o slave
152              communicate over stdin and stdout bypassing network
153
154       -o disable_hardlink
155              With this option set, attempts to call link(2)  will  fail  with
156              error code ENOSYS.
157
158       -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
164       -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
171       -o no_check_root
172              don't check for existence of 'dir' on server
173
174       -o password_stdin
175              read password from stdin (only for pam_mount!)
176
177       -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
183       -o dcache_max_size=N
184              sets the maximum size of the directory cache.
185
186       -o dcache_timeout=N
187              sets timeout for directory cache in seconds.
188
189       -o dcache_{stat,link,dir}_timeout=N
190              sets  separate timeout for {attributes, symlinks, names} in  the
191              directory cache.
192
193       -o dcache_clean_interval=N
194              sets the interval for automatic cleaning of the directory cache.
195
196       -o dcache_min_clean_interval=N
197              sets the interval for forced cleaning  of  the  directory  cache
198              when full.
199
200       -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
206       System Message: ERROR/3 (../sshfs.rst:, line 210)
207              Unexpected indentation.
208                 write operations, data will not be cached in the kernel.
209
210       System Message: WARNING/2 (../sshfs.rst:, line 211)
211              Block quote ends without a blank line; unexpected unindent.
212
213              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
218       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

CAVEATS / WORKAROUNDS

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
229   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
240   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
248   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
256   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
265       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
272       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

MOUNTING FROM /ETC/FSTAB

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

SEE ALSO

286       The mount.fuse(8) manpage.
287

GETTING HELP

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
293       Please   report   any   bugs   on   the   GitHub   issue   tracker   at
294       https://github.com/libfuse/libfuse/issues.
295

AUTHORS

297       SSHFS is currently maintained by Nikolaus Rath <Nikolaus@rath.org>, and
298       was created by Miklos Szeredi <miklos@szeredi.hu>.
299
300       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
304
305
306
307                                                                      SSHFS(1)
Impressum