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       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
33       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
37       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

OPTIONS

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
50       -h, --help
51              print help and exit.
52
53       -V, --version
54              print version information and exit.
55
56       -d, --debug
57              print debugging information.
58
59       -p PORT
60              equivalent to '-o port=PORT'
61
62       -f     do not daemonize, stay in foreground.
63
64       -s     Single threaded operation.
65
66       -C     equivalent to '-o compression=yes'
67
68       -F ssh_configfile
69              specifies alternative ssh configuration file
70
71       -1     equivalent to '-o ssh_protocol=1'
72
73       -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
78       -o delay_connect
79              Don't immediately connect to server, wait  until  mountpoint  is
80              first accessed.
81
82       -o sshfs_sync
83              synchronous  writes. This will slow things down, but may be use‐
84              ful in some situations.
85
86       -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
90       -o sync_readdir
91              synchronous readdir. This will slow things down, but may be use‐
92              ful in some situations.
93
94       -o workaround=LIST
95              Enable the specified workaround. See the Caveats  section  below
96              for some additional information. Possible values are:
97
98              rename Emulate  overwriting  an  existing  file  by deleting and
99                     renaming.
100
101              renamexdev
102                     Make rename fail with EXDEV instead of the default  EPERM
103                     to allow moving files across remote filesystems.
104
105              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
110              fstat  Work  around broken servers that don't support fstat() by
111                     using stat instead.
112
113              buflimit
114                     Work around OpenSSH "buffer fillup" bug.
115
116              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
121       -o idmap=TYPE
122              How to map remote UID/GIDs to local values. Possible values are:
123
124              none   no translation of the ID space (default).
125
126              user   map the UID/GID of the remote  user  to  UID/GID  of  the
127                     mounting user.
128
129              file   translate  UIDs/GIDs based upon the contents of --uidfile
130                     and --gidfile.
131
132       -o uidfile=FILE
133              file containing username:uid mappings for -o idmap=file
134
135       -o gidfile=FILE
136              file containing groupname:gid mappings for -o idmap=file
137
138       -o nomap=TYPE
139              with idmap=file, how to handle missing mappings:
140
141              ignore don't do any re-mapping
142
143              error  return an error (default)
144
145       -o ssh_command=CMD
146              execute CMD instead of 'ssh'
147
148       -o ssh_protocol=N
149              ssh protocol to use (default: 2)
150
151       -o sftp_server=SERV
152              path to sftp server or subsystem (default: sftp)
153
154       -o directport=PORT
155              directly connect to PORT bypassing ssh
156
157       -o slave
158              communicate over stdin and stdout bypassing network
159
160       -o disable_hardlink
161              With this option set, attempts to call link(2)  will  fail  with
162              error code ENOSYS.
163
164       -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
170       -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
177       -o no_check_root
178              don't check for existence of 'dir' on server
179
180       -o password_stdin
181              read password from stdin (only for pam_mount!)
182
183       -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
189       -o dcache_max_size=N
190              sets the maximum size of the directory cache.
191
192       -o dcache_timeout=N
193              sets timeout for directory cache in seconds.
194
195       -o dcache_{stat,link,dir}_timeout=N
196              sets  separate timeout for {attributes, symlinks, names} in  the
197              directory cache.
198
199       -o dcache_clean_interval=N
200              sets the interval for automatic cleaning of the directory cache.
201
202       -o dcache_min_clean_interval=N
203              sets the interval for forced cleaning  of  the  directory  cache
204              when full.
205
206       -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
210              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
214              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
219       -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
227       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

CAVEATS / WORKAROUNDS

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
238   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
249   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
257   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
265   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
274       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
281       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

MOUNTING FROM /ETC/FSTAB

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

SEE ALSO

295       The mount.fuse(8) manpage.
296

GETTING HELP

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

AUTHORS

306       SSHFS is currently maintained by Nikolaus Rath <Nikolaus@rath.org>, and
307       was created by Miklos Szeredi <miklos@szeredi.hu>.
308
309       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
313
314
315
316                                                                      SSHFS(1)
Impressum