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_other.
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 re‐
99                     naming.
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 passive
158              communicate over stdin and stdout bypassing network. Useful  for
159              mounting  local filesystem on the remote side.  An example using
160              dpipe command would be dpipe /usr/lib/openssh/sftp-server =  ssh
161              RemoteHostname  sshfs :/directory/to/be/shared ~/mnt/src -o pas‐
162              sive
163
164       -o disable_hardlink
165              With this option set, attempts to call link(2)  will  fail  with
166              error code ENOSYS.
167
168       -o transform_symlinks
169              transform absolute symlinks on remote side to relative symlinks.
170              This means that if e.g. on the server  side  /foo/bar/com  is  a
171              symlink  to  /foo/blub,  SSHFS will transform the link target to
172              ../blub on the client side.
173
174       -o follow_symlinks
175              follow symlinks on the server,  i.e.  present  them  as  regular
176              files  on  the client. If a symlink is dangling (i.e, the target
177              does not exist) the behavior depends on the remote server -  the
178              entry may appear as a symlink on the client, or it may appear as
179              a regular file that cannot be accessed.
180
181       -o no_check_root
182              don't check for existence of 'dir' on server
183
184       -o password_stdin
185              read password from stdin (only for pam_mount!)
186
187       -o dir_cache=BOOL
188              Enables (yes) or disables (no) the SSHFS directory  cache.   The
189              directory  cache  holds the names of directory entries. Enabling
190              it allows readdir(3) system calls to be processed  without  net‐
191              work access.
192
193       -o dcache_max_size=N
194              sets the maximum size of the directory cache.
195
196       -o dcache_timeout=N
197              sets timeout for directory cache in seconds.
198
199       -o dcache_{stat,link,dir}_timeout=N
200              sets  separate timeout for {attributes, symlinks, names} in  the
201              directory cache.
202
203       -o dcache_clean_interval=N
204              sets the interval for automatic cleaning of the directory cache.
205
206       -o dcache_min_clean_interval=N
207              sets the interval for forced cleaning  of  the  directory  cache
208              when full.
209
210       -o direct_io
211              This  option disables the use of page cache (file content cache)
212              in the kernel for this filesystem.  This has several affects:
213
214              1. Each read() or write() system call will initiate one or  more
215                 read or write operations, data will not be cached in the ker‐
216                 nel.
217
218              2. The return value of the read() and write() system calls  will
219                 correspond  to the return values of the read and write opera‐
220                 tions. This is useful for example if the  file  size  is  not
221                 known in advance (before reading it).  e.g. /proc filesystem
222
223       -o max_conns=N
224              sets  the maximum number of simultaneous SSH connections to use.
225              Each connection is established with a separate SSH process.  The
226              primary purpose of this feature is to improve the responsiveness
227              of the file system during large file transfers. When using  more
228              than once connection, the password_stdin and passive options can
229              not be used, and the buflimit workaround is not supported.
230
231       In addition, SSHFS accepts several options common to all FUSE file sys‐
232       tems.  These  are  described in the mount.fuse3 manpage (look for "gen‐
233       eral", "libfuse specific", and "high-level API" options).
234

CAVEATS / WORKAROUNDS

236   Hardlinks
237       If the SSH server supports the hardlinks extension,  SSHFS  will  allow
238       you to create hardlinks. However, hardlinks will always appear as indi‐
239       vidual files when seen through an SSHFS mount, i.e. they will appear to
240       have different inodes and an st_nlink value of 1.
241
242   Rename
243       Some  SSH servers do not support atomically overwriting the destination
244       when renaming a file. In this case you will get an error when  you  at‐
245       tempt to rename a file and the destination already exists. A workaround
246       is to first remove the destination file, and then do the rename.  SSHFS
247       can  do  this  automatically  if you call it with -o workaround=rename.
248       However, in this case it is still possible that someone (or  something)
249       recreates  the  destination file after SSHFS has removed it, but before
250       SSHFS had the time to rename the old file. In  this  case,  the  rename
251       will still fail.
252
253   Permission denied when moving files across remote filesystems
254       Most  SFTP  servers return only a generic "failure" when failing to re‐
255       name across filesystem boundaries  (EXDEV).   sshfs  normally  converts
256       this  generic failure to a permission denied error (EPERM).  If the op‐
257       tion -o workaround=renamexdev is given, generic failures will  be  con‐
258       sidered EXDEV errors which will make programs like mv(1) attempt to ac‐
259       tually move the file after the failed rename.
260
261   SSHFS hangs for no apparent reason
262       In some cases, attempts to access the SSHFS mountpoint may freeze if no
263       filesystem  activity  has  occurred  for  some  time. This is typically
264       caused by the SSH connection being dropped because of inactivity  with‐
265       out  SSHFS  being  informed about that. As a workaround, you can try to
266       mount with -o ServerAliveInterval=15. This will force the  SSH  connec‐
267       tion to stay alive even if you have no activity.
268
269   SSHFS hangs after the connection was interrupted
270       By default, network operations in SSHFS run without timeouts, mirroring
271       the default behavior of SSH itself. As a consequence, if the connection
272       to the remote host is interrupted (e.g. because a network cable was re‐
273       moved), operations on files or directories under  the  mountpoint  will
274       block  until  the  connection  is  either restored or closed altogether
275       (e.g. manually).  Applications that try to access such files or  direc‐
276       tories will generally appear to "freeze" when this happens.
277
278       If  it  is  acceptable  to  discard data being read or written, a quick
279       workaround is to kill the responsible sshfs process,  which  will  make
280       any blocking operations on the mounted filesystem error out and thereby
281       "unfreeze" the relevant applications. Note that force  unmounting  with
282       fusermount  -zu, on the other hand, does not help in this case and will
283       leave read/write operations in the blocking state.
284
285       For a more automatic solution, one can  use  the  -o  ServerAliveInter‐
286       val=15 option mentioned above, which will drop the connection after not
287       receiving a response for 3 * 15 = 45 seconds from the remote  host.  By
288       also  supplying  -o  reconnect,  one  can ensure that the connection is
289       re-established as soon as possible afterwards.  As  before,  this  will
290       naturally lead to loss of data that was in the process of being read or
291       written at the time when the connection was interrupted.
292

MOUNTING FROM /ETC/FSTAB

294       To mount an SSHFS filesystem from /etc/fstab, simply use sshfs  as  the
295       file  system  type.  (For  backwards  compatibility,  you  may also use
296       fuse.sshfs).
297

SEE ALSO

299       The mount.fuse(8) manpage.
300

GETTING HELP

302       If you need help, please ask on the  <fuse-sshfs@lists.sourceforge.net>
303       mailing                list                (subscribe                at
304       https://lists.sourceforge.net/lists/listinfo/fuse-sshfs).
305
306       Please   report   any   bugs   on   the   GitHub   issue   tracker   at
307       https://github.com/libfuse/libfuse/issues.
308

AUTHORS

310       SSHFS is currently maintained by Nikolaus Rath <Nikolaus@rath.org>, and
311       was created by Miklos Szeredi <miklos@szeredi.hu>.
312
313       This  man  page  was  originally   written   by   Bartosz   Fenski   <‐
314       fenio@debian.org>  for the Debian GNU/Linux distribution (but it may be
315       used by others).
316
317
318
319
320                                                                      SSHFS(1)
Impressum