opt/sshfs-fuse/sshfs.1

.\" Man page generated from reStructuredText.
.
.TH SSHFS 1 "" "" "User Commands"
.SH NAME
SSHFS \- filesystem client based on SSH
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
To mount a filesystem:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sshfs [user@]host:[dir] mountpoint [options]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If \fIhost\fP is a numeric IPv6 address, it needs to be enclosed in square
brackets.
.sp
To unmount it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fusermount3 \-u mountpoint   # Linux
umount mountpoint           # OS X, FreeBSD
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
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\(aqs
nothing to do on the server\-side.
.sp
SSHFS uses FUSE (Filesystem in Userspace) and should work on any
operating system that provides a FUSE implementation. Currently,
this includes Linux, FreeBSD and Mac OS X.
.sp
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).
.SH OPTIONS
.INDENT 0.0
.TP
.B \-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 \fIsftp(1)\fP and
\fIssh_config(5)\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-h\fP,\fB  \-\-help
print help and exit.
.TP
.B \-V\fP,\fB  \-\-version
print version information and exit.
.TP
.B \-d\fP,\fB  \-\-debug
print debugging information.
.TP
.BI \-p \ PORT
equivalent to \(aq\-o port=PORT\(aq
.TP
.B \-f
do not daemonize, stay in foreground.
.TP
.B \-s
Single threaded operation.
.TP
.B \-C
equivalent to \(aq\-o compression=yes\(aq
.TP
.BI \-F \ ssh_configfile
specifies alternative ssh configuration file
.TP
.B \-1
equivalent to \(aq\-o ssh_protocol=1\(aq
.TP
.BI \-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.
.TP
.BI \-o \ delay_connect
Don\(aqt immediately connect to server, wait until mountpoint is first
accessed.
.TP
.BI \-o \ sshfs_sync
synchronous writes. This will slow things down, but may be useful
in some situations.
.TP
.BI \-o \ no_readahead
Only read exactly the data that was requested, instead of
speculatively reading more to anticipate the next read request.
.TP
.BI \-o \ sync_readdir
synchronous readdir. This will slow things down, but may be useful
in some situations.
.UNINDENT
.INDENT 0.0
.TP
.B \-o workaround=LIST
Enable the specified workaround. See the \fICaveats\fP section below
for some additional information. Possible values are:
.INDENT 7.0
.TP
.B rename
Emulate overwriting an existing file by deleting and
renaming.
.TP
.B renamexdev
Make rename fail with EXDEV instead of the default EPERM
to allow moving files across remote filesystems.
.TP
.B truncate
Work around servers that don\(aqt support truncate by
coping the whole file, truncating it locally, and sending it
back.
.TP
.B fstat
Work around broken servers that don\(aqt support \fIfstat()\fP by
using \fIstat\fP instead.
.TP
.B buflimit
Work around OpenSSH "buffer fillup" bug.
.TP
.B createmode
Work around broken servers that produce an error when passing a
non\-zero mode to create, by always passing a mode of 0.
.UNINDENT
.TP
.B \-o idmap=TYPE
How to map remote UID/GIDs to local values. Possible values are:
.INDENT 7.0
.TP
.B none
no translation of the ID space (default).
.TP
.B user
map the UID/GID of the remote user to UID/GID of the
mounting user.
.TP
.B file
translate UIDs/GIDs based upon the contents of \fI\-\-uidfile\fP
and \fI\-\-gidfile\fP\&.
.UNINDENT
.TP
.B \-o uidfile=FILE
file containing \fBusername:uid\fP mappings for \fI\-o idmap=file\fP
.TP
.B \-o gidfile=FILE
file containing \fBgroupname:gid\fP mappings for \fI\-o idmap=file\fP
.TP
.B \-o nomap=TYPE
with idmap=file, how to handle missing mappings:
.INDENT 7.0
.TP
.B ignore
don\(aqt do any re\-mapping
.TP
.B error
return an error (default)
.UNINDENT
.TP
.B \-o ssh_command=CMD
execute CMD instead of \(aqssh\(aq
.TP
.B \-o ssh_protocol=N
ssh protocol to use (default: 2)
.TP
.B \-o sftp_server=SERV
path to sftp server or subsystem (default: sftp)
.TP
.B \-o directport=PORT
directly connect to PORT bypassing ssh
.UNINDENT
.INDENT 0.0
.TP
.BI \-o \ slave
communicate over stdin and stdout bypassing network
.TP
.BI \-o \ disable_hardlink
With this option set, attempts to call \fIlink(2)\fP will fail with
error code ENOSYS.
.TP
.BI \-o \ transform_symlinks
transform absolute symlinks on remote side to relative
symlinks. This means that if e.g. on the server side
\fB/foo/bar/com\fP is a symlink to \fB/foo/blub\fP, SSHFS will
transform the link target to \fB\&../blub\fP on the client side.
.TP
.BI \-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.
.TP
.BI \-o \ no_check_root
don\(aqt check for existence of \(aqdir\(aq on server
.TP
.BI \-o \ password_stdin
read password from stdin (only for pam_mount!)
.UNINDENT
.INDENT 0.0
.TP
.B \-o dir_cache=BOOL
Enables (\fIyes\fP) or disables (\fIno\fP) the SSHFS directory cache.  The
directory cache holds the names of directory entries. Enabling it
allows \fIreaddir(3)\fP system calls to be processed without network
access.
.TP
.B \-o dcache_max_size=N
sets the maximum size of the directory cache.
.TP
.B \-o dcache_timeout=N
sets timeout for directory cache in seconds.
.TP
.B \-o dcache_{stat,link,dir}_timeout=N
sets separate timeout for {attributes, symlinks, names} in  the
directory cache.
.TP
.B \-o dcache_clean_interval=N
sets the interval for automatic cleaning of the directory cache.
.TP
.B \-o dcache_min_clean_interval=N
sets the interval for forced cleaning of the directory cache
when full.
.UNINDENT
.INDENT 0.0
.TP
.BI \-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
.IP "System Message: ERROR/3 (../sshfs.rst:, line 210)"
Unexpected indentation.
.INDENT 7.0
.INDENT 3.5
write operations, data will not be cached in the kernel.
.UNINDENT
.UNINDENT
.IP "System Message: WARNING/2 (../sshfs.rst:, line 211)"
Block quote ends without a blank line; unexpected unindent.
.INDENT 7.0
.IP 2. 3
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
.UNINDENT
.UNINDENT
.sp
In addition, SSHFS accepts several options common to all FUSE file
systems. These are described in the \fImount.fuse\fP manpage (look
for "general", "libfuse specific", and "high\-level API" options).
.SH CAVEATS / WORKAROUNDS
.SS Hardlinks
.sp
If the SSH server supports the \fIhardlinks\fP 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 \fIst_nlink\fP value of 1.
.SS Rename
.sp
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 \fI\-o
workaround=rename\fP\&. 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.
.SS Permission denied when moving files across remote filesystems
.sp
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 \fB\-o
workaround=renamexdev\fP is given, generic failures will be considered EXDEV
errors which will make programs like \fImv(1)\fP attempt to actually move the
file after the failed rename.
.SS SSHFS hangs for no apparent reason
.sp
In some cases, attempts to access the SSHFS mountpoint may freeze if
no filesystem activity has occured 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 \fB\-o ServerAliveInterval=15\fP\&. This will force the SSH
connection to stay alive even if you have no activity.
.SS SSHFS hangs after the connection was interrupted
.sp
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.
.sp
If it is acceptable to discard data being read or written, a quick workaround
is to kill the responsible \fBsshfs\fP process, which will make any blocking
operations on the mounted filesystem error out and thereby "unfreeze" the
relevant applications. Note that force unmounting with \fBfusermount \-zu\fP, on
the other hand, does not help in this case and will leave read/write operations
in the blocking state.
.sp
For a more automatic solution, one can use the \fB\-o ServerAliveInterval=15\fP
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 \fB\-o
reconnect\fP, 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.
.SH MOUNTING FROM /ETC/FSTAB
.sp
To mount an SSHFS filesystem from \fB/etc/fstab\fP, simply use \fBsshfs\(ga
as the file system type. (For backwards compatibility, you may also
use \(ga\(gafuse.sshfs\fP).
.SH SEE ALSO
.sp
The \fImount.fuse(8)\fP manpage.
.SH GETTING HELP
.sp
If you need help, please ask on the <\fI\%fuse\-sshfs@lists.sourceforge.net\fP>
mailing list (subscribe at
\fI\%https://lists.sourceforge.net/lists/listinfo/fuse\-sshfs\fP).
.sp
Please report any bugs on the GitHub issue tracker at
\fI\%https://github.com/libfuse/libfuse/issues\fP\&.
.SH AUTHORS
.sp
SSHFS is currently maintained by Nikolaus Rath <\fI\%Nikolaus@rath.org\fP>,
and was created by Miklos Szeredi <\fI\%miklos@szeredi.hu\fP>.
.sp
This man page was originally written by Bartosz Fenski
<\fI\%fenio@debian.org\fP> for the Debian GNU/Linux distribution (but it may
be used by others).
.\" Generated by docutils manpage writer.
.