sshfs(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | CAVEATS / WORKAROUNDS | MOUNTING FROM /ETC/FSTAB | SEE ALSO | GETTING HELP | AUTHORS | COLOPHON

SSHFS(1)                      User Commands                     SSHFS(1)

NAME         top

       SSHFS - filesystem client based on SSH

SYNOPSIS         top

       To mount a filesystem:

          sshfs [user@]host:[dir] mountpoint [options]

       If host is a numeric IPv6 address, it needs to be enclosed in
       square brackets.

       To unmount it:

          fusermount3 -u mountpoint   # Linux
          umount mountpoint           # OS X, FreeBSD

DESCRIPTION         top

       SSHFS allows you to mount a remote filesystem using SSH (more
       precisely, the SFTP subsystem). Most SSH servers support and
       enable this SFTP access by default, so SSHFS is very simple to
       use - there's nothing to do on the server-side.

       By default, file permissions are ignored by SSHFS. Any user that
       can access the filesystem will be able to perform any operation
       that the remote server permits - based on the credentials that
       were used to connect to the server. If this is undesired, local
       permission checking can be enabled with -o default_permissions.

       By default, only the mounting user will be able to access the
       filesystem. Access for other users can be enabled by passing -o
       allow_other. In this case you most likely also want to use -o
       default_permissions.

       It is recommended to run SSHFS as regular user (not as root).
       For this to work the mountpoint must be owned by the user.  If
       username is omitted SSHFS will use the local username. If the
       directory is omitted, SSHFS will mount the (remote) home
       directory.  If you need to enter a password sshfs will ask for it
       (actually it just runs ssh which ask for the password if needed).

OPTIONS         top

       -o opt,[opt...]
              mount options, see below for details. A a variety of SSH
              options can be given here as well, see the manual pages
              for sftp(1) and ssh_config(5).

       -h, --help
              print help and exit.

       -V, --version
              print version information and exit.

       -d, --debug
              print debugging information.

       -p PORT
              equivalent to '-o port=PORT'

       -f     do not daemonize, stay in foreground.

       -s     Single threaded operation.

       -C     equivalent to '-o compression=yes'

       -F ssh_configfile
              specifies alternative ssh configuration file

       -1     equivalent to '-o ssh_protocol=1'

       -o reconnect
              automatically reconnect to server if connection is
              interrupted. Attempts to access files that were opened
              before the reconnection will give errors and need to be
              re-opened.

       -o delay_connect
              Don't immediately connect to server, wait until mountpoint
              is first accessed.

       -o sshfs_sync
              synchronous writes. This will slow things down, but may be
              useful in some situations.

       -o no_readahead
              Only read exactly the data that was requested, instead of
              speculatively reading more to anticipate the next read
              request.

       -o sync_readdir
              synchronous readdir. This will slow things down, but may
              be useful in some situations.

       -o workaround=LIST
              Enable the specified workaround. See the Caveats section
              below for some additional information. Possible values
              are:

              rename Emulate overwriting an existing file by deleting
                     and renaming.

              renamexdev
                     Make rename fail with EXDEV instead of the default
                     EPERM to allow moving files across remote
                     filesystems.

              truncate
                     Work around servers that don't support truncate by
                     coping the whole file, truncating it locally, and
                     sending it back.

              fstat  Work around broken servers that don't support
                     fstat() by using stat instead.

              buflimit
                     Work around OpenSSH "buffer fillup" bug.

              createmode
                     Work around broken servers that produce an error
                     when passing a non-zero mode to create, by always
                     passing a mode of 0.

       -o idmap=TYPE
              How to map remote UID/GIDs to local values. Possible
              values are:

              none   no translation of the ID space (default).

              user   map the UID/GID of the remote user to UID/GID of
                     the mounting user.

              file   translate UIDs/GIDs based upon the contents of
                     --uidfile and --gidfile.

       -o uidfile=FILE
              file containing username:uid mappings for -o idmap=file

       -o gidfile=FILE
              file containing groupname:gid mappings for -o idmap=file

       -o nomap=TYPE
              with idmap=file, how to handle missing mappings:

              ignore don't do any re-mapping

              error  return an error (default)

       -o ssh_command=CMD
              execute CMD instead of 'ssh'

       -o ssh_protocol=N
              ssh protocol to use (default: 2)

       -o sftp_server=SERV
              path to sftp server or subsystem (default: sftp)

       -o directport=PORT
              directly connect to PORT bypassing ssh

       -o vsock=CID:PORT
              directly connect using a vsock to CID:PORT bypassing ssh

       -o passive
              communicate over stdin and stdout bypassing network.
              Useful for mounting local filesystem on the remote side.
              An example using dpipe command would be dpipe
              /usr/lib/openssh/sftp-server = ssh RemoteHostname sshfs
              :/directory/to/be/shared ~/mnt/src -o passive

       -o disable_hardlink
              With this option set, attempts to call link(2) will fail
              with error code ENOSYS.

       -o transform_symlinks
              transform absolute symlinks on remote side to relative
              symlinks. This means that if e.g. on the server side
              /foo/bar/com is a symlink to /foo/blub, SSHFS will
              transform the link target to ../blub on the client side.

       -o follow_symlinks
              follow symlinks on the server, i.e. present them as
              regular files on the client. If a symlink is dangling
              (i.e, the target does not exist) the behavior depends on
              the remote server - the entry may appear as a symlink on
              the client, or it may appear as a regular file that cannot
              be accessed.

       -o no_check_root
              don't check for existence of 'dir' on server

       -o password_stdin
              read password from stdin (only for pam_mount!)

       -o dir_cache=BOOL
              Enables (yes) or disables (no) the SSHFS directory cache.
              The directory cache holds the names of directory entries.
              Enabling it allows readdir(3) system calls to be processed
              without network access.

       -o dcache_max_size=N
              sets the maximum size of the directory cache.

       -o dcache_timeout=N
              sets timeout for directory cache in seconds.

       -o dcache_{stat,link,dir}_timeout=N
              sets separate timeout for {attributes, symlinks, names} in
              the directory cache.

       -o dcache_clean_interval=N
              sets the interval for automatic cleaning of the directory
              cache.

       -o dcache_min_clean_interval=N
              sets the interval for forced cleaning of the directory
              cache when full.

       -o direct_io
              This option disables the use of page cache (file content
              cache) in the kernel for this filesystem.  This has
              several affects:

              1. Each read() or write() system call will initiate one or
                 more read or write operations, data will not be cached
                 in the kernel.

              2. The return value of the read() and write() system calls
                 will correspond to the return values of the read and
                 write operations. This is useful for example if the
                 file size is not known in advance (before reading it).
                 e.g. /proc filesystem

       -o max_conns=N
              sets the maximum number of simultaneous SSH connections to
              use. Each connection is established with a separate SSH
              process.  The primary purpose of this feature is to
              improve the responsiveness of the file system during large
              file transfers. When using more than once connection, the
              password_stdin and passive options can not be used, and
              the buflimit workaround is not supported.

       In addition, SSHFS accepts several options common to all FUSE
       file systems. These are described in the mount.fuse manpage (look
       for "general", "libfuse specific", and "high-level API" options).

CAVEATS / WORKAROUNDS         top

   Hardlinks
       If the SSH server supports the hardlinks extension, SSHFS will
       allow you to create hardlinks. However, hardlinks will always
       appear as individual files when seen through an SSHFS mount, i.e.
       they will appear to have different inodes and an st_nlink value
       of 1.

   Rename
       Some SSH servers do not support atomically overwriting the
       destination when renaming a file. In this case you will get an
       error when you attempt to rename a file and the destination
       already exists. A workaround is to first remove the destination
       file, and then do the rename. SSHFS can do this automatically if
       you call it with -o workaround=rename. However, in this case it
       is still possible that someone (or something) recreates the
       destination file after SSHFS has removed it, but before SSHFS had
       the time to rename the old file. In this case, the rename will
       still fail.

   Permission denied when moving files across remote filesystems
       Most SFTP servers return only a generic "failure" when failing to
       rename across filesystem boundaries (EXDEV).  sshfs normally
       converts this generic failure to a permission denied error
       (EPERM).  If the option -o workaround=renamexdev is given,
       generic failures will be considered EXDEV errors which will make
       programs like mv(1) attempt to actually move the file after the
       failed rename.

   SSHFS hangs for no apparent reason
       In some cases, attempts to access the SSHFS mountpoint may freeze
       if no filesystem activity has occurred for some time. This is
       typically caused by the SSH connection being dropped because of
       inactivity without SSHFS being informed about that. As a
       workaround, you can try to mount with -o ServerAliveInterval=15.
       This will force the SSH connection to stay alive even if you have
       no activity.

   SSHFS hangs after the connection was interrupted
       By default, network operations in SSHFS run without timeouts,
       mirroring the default behavior of SSH itself. As a consequence,
       if the connection to the remote host is interrupted (e.g. because
       a network cable was removed), operations on files or directories
       under the mountpoint will block until the connection is either
       restored or closed altogether (e.g. manually).  Applications that
       try to access such files or directories will generally appear to
       "freeze" when this happens.

       If it is acceptable to discard data being read or written, a
       quick workaround is to kill the responsible sshfs process, which
       will make any blocking operations on the mounted filesystem error
       out and thereby "unfreeze" the relevant applications. Note that
       force unmounting with fusermount -zu, on the other hand, does not
       help in this case and will leave read/write operations in the
       blocking state.

       For a more automatic solution, one can use the -o
       ServerAliveInterval=15 option mentioned above, which will drop
       the connection after not receiving a response for 3 * 15 = 45
       seconds from the remote host. By also supplying -o reconnect, one
       can ensure that the connection is re-established as soon as
       possible afterwards. As before, this will naturally lead to loss
       of data that was in the process of being read or written at the
       time when the connection was interrupted.

MOUNTING FROM /ETC/FSTAB         top

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

SEE ALSO         top

       The mount.fuse(8) manpage.

GETTING HELP         top

       If you need help, please ask on the <‐
       [email protected]> mailing list (subscribe at
       https://lists.sourceforge.net/lists/listinfo/fuse-sshfs ).

       Please report any bugs on the GitHub issue tracker at
       https://github.com/libfuse/libfuse/issues .

AUTHORS         top

       SSHFS is currently maintained by Nikolaus Rath <‐
       [email protected]>, and was created by Miklos Szeredi <‐
       [email protected]>.

       This man page was originally written by Bartosz Fenski <‐
       [email protected]> for the Debian GNU/Linux distribution (but it
       may be used by others).

COLOPHON         top

       This page is part of the sshfs (SSH Filesystem) project.
       Information about the project can be found at 
       ⟨https://github.com/libfuse/sshfs⟩.  If you have a bug report for
       this manual page, see ⟨https://github.com/libfuse/sshfs/issues⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://github.com/libfuse/sshfs.git⟩ on 2024-06-14.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2024-02-27.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

                                                                SSHFS(1)