usr.sbin/puffs/mount_psshfs/mount_psshfs.8

   1 .\"     $NetBSD: mount_psshfs.8,v 1.22 2010/01/07 21:05:50 pooka Exp $
   2 .\"
   3 .\" Copyright (c) 2007-2009 Antti Kantee.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd January 7, 2010
  27 .Dt MOUNT_PSSHFS 8
  28 .Os
  29 .Sh NAME
  30 .Nm mount_psshfs
  31 .Nd sshfs implementation for puffs
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Op Ar options
  35 .Ar user@host[:path]
  36 .Ar mount_point
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 utility can be used to mount a file system using the ssh sftp
  41 subprotocol, making a remote directory hierarchy appear in the
  42 local directory tree.
  43 This functionality is commonly known as
  44 .Em sshfs .
  45 .Pp
  46 The mandatory parameters are the target host name and local mount
  47 point.
  48 The target host parameter can optionally contain a username whose
  49 credentials will be used by the remote sshd, and a relative or
  50 absolute path for the remote mount point's root.
  51 If no user is given, the credentials of the user issuing the mount
  52 command are used.
  53 If no path is given, the user's home directory on the remote machine
  54 will be used.
  55 .Pp
  56 The following command line options are available:
  57 .Pp
  58 .Bl -tag -width xxx
  59 .It Fl c Ar nconnect
  60 Opens
  61 .Ar nconnect
  62 connections to the server.
  63 Currently, the value has to be 1 or 2.
  64 If 2 is specified, a second connection is opened for the reading
  65 and writing of data, while directory operations are performed on
  66 their own connection.
  67 This can greatly increase directory operation performance (ls,
  68 mkdir, etc.) if
  69 .Nm
  70 completely saturates the available bandwidth by doing bulk data copying.
  71 The default is 1.
  72 .It Fl e
  73 Makes the mounted file system NFS exportable.
  74 If this option is used, it is very important to understand that
  75 .Nm
  76 can not provide complete support for NFS due to the limitations in
  77 the backend.
  78 Files are valid only for the time that
  79 .Nm
  80 is running and in the event of e.g. a server crash, all client retries
  81 to access files will fail.
  82 .It Fl F Ar configfile
  83 Pass a configuration file to
  84 .Xr ssh 1 .
  85 This will make it ignore the system-wide
  86 .Pa /etc/ssh/ssh_config
  87 configuration file and use
  88 .Pa configfile
  89 instead of
  90 .Pa ~/.ssh/config .
  91 .It Fl g Ar manglegid
  92 Converts remote
  93 .Ar manglegid
  94 to the effective gid of the file server and vice versa.
  95 See
  96 .Fl u .
  97 .It Fl o Ar [no]option
  98 This flag can be used to give standard mount options and options
  99 to puffs.
 100 .It Fl O Ar sshopt=value
 101 Pass an option to
 102 .Xr ssh 1 ,
 103 for example
 104 .Fl O Ar Port=22 .
 105 For a list of valid options, see
 106 .Xr ssh_config 5 .
 107 .It Fl p
 108 Preserve connection.
 109 This option makes
 110 .Nm
 111 to try to reconnect to the server if the connection fails.
 112 The option is very experimental and does not preserve open files
 113 or retry current requests and should generally only be used if the
 114 trade-offs are well understood.
 115 .It Fl r Ar max_reads
 116 Limits maximum outstanding read requests for each node to
 117 .Ar max_reads .
 118 This can be used to improve interactive performance on low-bandwidth links
 119 when also performing bulk data reads.
 120 .It Fl s
 121 This flag can be used to make the program stay on top.
 122 The default is to detach from the terminal and run in the background.
 123 .It Fl t Ar timeout
 124 By default
 125 .Nm
 126 caches directory contents and node attributes for 30 seconds before
 127 re-fetching from the server to check if anything has changed on
 128 the server.
 129 This option is used to adjust the timeout period to
 130 .Ar timeout
 131 seconds.
 132 A value 0 means the cache is never valid and \-1 means it is
 133 valid indefinitely.
 134 It is possible to force a re-read regardless of timeout status by sending
 135 .Dv SIGHUP
 136 to the
 137 .Nm
 138 process.
 139 .Pp
 140 Note: the file system will still free nodes when requested by the
 141 kernel and will lose all cached information in doing so.
 142 How frequently this happens depends on system activity and the total
 143 number of available vnodes in the system (kern.maxvnodes).
 144 .It Fl u Ar mangleuid
 145 Converts remote
 146 .Ar mangleuid
 147 to the effective uid of the file server and vice versa.
 148 This is a simple special case of the functionality of
 149 .Xr mount_umap 8 .
 150 For example: you mount remote me@darkmoon as the local user "me".
 151 If the uid of "me" on the local system is 101 and on
 152 darkmoon it is 202, you would use
 153 .Fl u
 154 .Ar 202
 155 to see files owned by 202 on darkmoon as owned by 101 when browsing the
 156 mount point.
 157 Apart from the cosmetic effect, this makes things like
 158 "chown me file" work.
 159 See
 160 .Fl g .
 161 .El
 162 .Sh EXAMPLES
 163 The following example illustrates how to mount the directory
 164 .Em /usr
 165 on server
 166 .Em bigiron
 167 as user
 168 .Em abc
 169 on local directory
 170 .Em /mnt
 171 with ssh transport compression enabled:
 172 .Bd -literal -offset indent
 173 mount_psshfs -O Compression=yes abc@bigiron:/usr /mnt
 174 .Ed
 175 .Pp
 176 It is possible to use
 177 .Xr fstab 5
 178 for psshfs mounts, with SSH public key authentication:
 179 .Pp
 180 .Dl "abc@bigiron:/usr /mnt psshfs rw,noauto,-O=BatchMode=yes,-O=IdentityFile=/root/.ssh/id_rsa,-t=-1"
 181 .Sh SEE ALSO
 182 .Xr sftp 1 ,
 183 .Xr puffs 3 ,
 184 .Xr puffs 4 ,
 185 .Xr fstab 5 ,
 186 .Xr ssh_config 5 ,
 187 .Xr mount 8 ,
 188 .Xr sshd 8
 189 .Sh HISTORY
 190 The
 191 .Nm
 192 utility first appeared in
 193 .Nx 5.0 .
 194 .Sh CAVEATS
 195 Permissions are not handled.
 196 Do not expect the file system to behave except for a single user.
 197 .Pp
 198 Depending on if the server supports the
 199 .Xr sftp 1
 200 stavfs protocol extension,
 201 free disk space may be displayed for the mount by
 202 .Xr df 1 .
 203 This information reflects the status at the server's mountpoint
 204 and may differ for subdiretories under the mount root.