.\"	$NetBSD: mount_psshfs.8,v 1.27 2014/06/25 23:22:18 szptvlfn Exp $
.\"
.\" Copyright (c) 2007-2009 Antti Kantee.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd January 7, 2010
.Dt MOUNT_PSSHFS 8
.Os
.Sh NAME
.Nm mount_psshfs
.Nd sshfs implementation for puffs
.Sh SYNOPSIS
.Nm
.Op Ar options
.Ar user@host[:path]
.Ar mount_point
.Sh DESCRIPTION
The
.Nm
utility can be used to mount a file system using the ssh sftp
subprotocol, making a remote directory hierarchy appear in the
local directory tree.
This functionality is commonly known as
.Em sshfs .
.Pp
The mandatory parameters are the target host name and local mount
point.
The target host parameter can optionally contain a username whose
credentials will be used by the remote sshd, and a relative or
absolute path for the remote mount point's root.
If no user is given, the credentials of the user issuing the mount
command are used.
If no path is given, the user's home directory on the remote machine
will be used.
.Pp
The following command line options are available:
.Pp
.Bl -tag -width xxx
.It Fl c Ar nconnect
Opens
.Ar nconnect
connections to the server.
Currently, the value has to be 1 or 2.
If 2 is specified, a second connection is opened for the reading
and writing of data, while directory operations are performed on
their own connection.
This can greatly increase directory operation performance (ls,
mkdir, etc.) if
.Nm
completely saturates the available bandwidth by doing bulk data copying.
The default is 1.
.It Fl e
Makes the mounted file system NFS exportable.
If this option is used, it is very important to understand that
.Nm
can not provide complete support for NFS due to the limitations in
the backend.
Files are valid only for the time that
.Nm
is running and in the event of e.g. a server crash, all client retries
to access files will fail.
.It Fl F Ar configfile
Pass a configuration file to
.Xr ssh 1 .
This will make it ignore the system-wide
.Pa /etc/ssh/ssh_config
configuration file and use
.Pa configfile
instead of
.Pa ~/.ssh/config .
.It Fl g Ar manglegid
Converts remote
.Ar manglegid
to the effective gid of the file server and vice versa.
See
.Fl u .
.It Fl o Ar [no]option
This flag can be used to give standard mount options and options
to puffs.
.It Fl O Ar sshopt=value
Pass an option to
.Xr ssh 1 ,
for example
.Fl O Ar Port=22 .
For a list of valid options, see
.Xr ssh_config 5 .
.It Fl p
Preserve connection.
This option makes
.Nm
to try to reconnect to the server if the connection fails.
The option is very experimental and does not preserve open files
or retry current requests and should generally only be used if the
trade-offs are well understood.
.It Fl r Ar max_reads
Limits maximum outstanding read requests for each node to
.Ar max_reads .
This can be used to improve interactive performance on low-bandwidth links
when also performing bulk data reads.
.It Fl s
This flag can be used to make the program stay on top.
The default is to detach from the terminal and run in the background.
.It Fl t Ar timeout
By default
.Nm
caches directory contents and node attributes for 30 seconds before
re-fetching from the server to check if anything has changed on
the server.
This option is used to adjust the timeout period to
.Ar timeout
seconds.
A value of 0 means the cache is never valid; \-1 means it is
valid indefinitely.
It is possible to force a re-read regardless of timeout status by sending
.Dv SIGHUP
to the
.Nm
process.
.Pp
Note: the file system will still free nodes when requested by the
kernel and will lose all cached information in doing so.
How frequently this happens depends on system activity and the total
number of available vnodes in the system (kern.maxvnodes).
.It Fl u Ar mangleuid
Converts remote
.Ar mangleuid
to the effective uid of the file server and vice versa.
This is a simple special case of the functionality of
.Xr mount_umap 8 .
For example: you mount remote me@darkmoon as the local user "me".
If the uid of "me" on the local system is 101 and on
darkmoon it is 202, you would use
.Fl u
.Ar 202
to see files owned by 202 on darkmoon as owned by 101 when browsing the
mount point.
Apart from the cosmetic effect, this makes things like
"chown me file" work.
See
.Fl g .
.El
.Sh EXAMPLES
The following example illustrates how to mount the directory
.Em /usr
on server
.Em bigiron
as user
.Em abc
on local directory
.Em /mnt
with ssh transport compression enabled:
.Bd -literal -offset indent
mount_psshfs -O Compression=yes abc@bigiron:/usr /mnt
.Ed
.Pp
It is possible to use
.Xr fstab 5
for psshfs mounts, with SSH public key authentication:
.Pp
.Dl "abc@bigiron:/usr /mnt psshfs rw,noauto,-O=BatchMode=yes,-O=IdentityFile=/root/.ssh/id_rsa,-t=-1"
.Sh SEE ALSO
.Xr sftp 1 ,
.Xr puffs 3 ,
.Xr puffs 4 ,
.Xr fstab 5 ,
.Xr ssh_config 5 ,
.Xr mount 8 ,
.Xr sshd 8
.Sh HISTORY
The
.Nm
utility first appeared in
.Nx 5.0 .
It was inspired by FUSE sshfs.
.Sh CAVEATS
Permissions are not handled.
Do not expect the file system to behave except for a single user.
.Pp
Depending on if the server supports the
.Xr sftp 1
statvfs protocol extension,
free disk space may be displayed for the mount by
.Xr df 1 .
This information reflects the status at the server's mountpoint
and may differ for subdirectories under the mount root.