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