sbin/mount_portal/mount_portal.8

   1 .\"     $NetBSD: mount_portal.8,v 1.20 2005/01/31 05:19:19 erh Exp $
   2 .\"
   3 .\" Copyright (c) 1993, 1994
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software donated to Berkeley by
   7 .\" Jan-Simon Pendry.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)mount_portal.8      8.3 (Berkeley) 3/27/94
  34 .\"
  35 .Dd December 5, 2009
  36 .Dt MOUNT_PORTAL 8
  37 .Os
  38 .Sh NAME
  39 .Nm mount_portal
  40 .Nd mount the portal daemon
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl o Ar options
  44 .Ar /etc/portal.conf
  45 .Ar mount_point
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 command attaches an instance of the portal daemon
  50 to the global filesystem namespace.
  51 The conventional mount point is
  52 .Pa /p .
  53 The directory specified by
  54 .Ar mount_point
  55 is converted to an absolute path before use.
  56 This command is normally executed by
  57 .Xr mount 8
  58 at boot time.
  59 .Pp
  60 The options are as follows:
  61 .Bl -tag -width indent
  62 .It Fl o
  63 Options are specified with a
  64 .Fl o
  65 flag followed by a comma separated string of options.
  66 See the
  67 .Xr mount 8
  68 man page for possible options and their meanings.
  69 .El
  70 .Pp
  71 The portal daemon provides an
  72 .Em open
  73 service.
  74 Objects opened under the portal mount point are
  75 dynamically created by the portal daemon according
  76 to rules specified in the named configuration file.
  77 Using this mechanism allows descriptors such as sockets
  78 to be made available in the filesystem namespace.
  79 .Pp
  80 The portal daemon works by being passed the full pathname
  81 of the object being opened.
  82 The daemon creates an appropriate descriptor according
  83 to the rules in the configuration file, and then passes the descriptor back
  84 to the calling process as the result of the open system call.
  85 .Sh NAMESPACE
  86 By convention, the portal daemon divides the namespace into sub-namespaces,
  87 each of which handles objects of a particular type.
  88 .Pp
  89 Currently, four sub-namespaces are implemented:
  90 .Pa tcp ,
  91 .Pa fs ,
  92 .Pa rfilter
  93 and
  94 .Pa wfilter .
  95 The
  96 .Pa tcp
  97 namespace takes a hostname and a port (slash separated) and
  98 creates an open TCP/IP connection.
  99 The
 100 .Pa fs
 101 namespace opens the named file, starting back at the root directory.
 102 This can be used to provide a controlled escape path from
 103 a chrooted environment.
 104 .Pp
 105 The
 106 .Pa rfilter
 107 and
 108 .Pa wfilter
 109 namespaces open a pipe to a process, typically a data-filter such
 110 as compression or decompression programs.
 111 The
 112 .Pa rfilter
 113 namespace opens a read-only pipe, while the
 114 .Pa wfilter
 115 namespace opens a write-only pipe.
 116 See the
 117 .Sx EXAMPLES
 118 section below for more examples.
 119 .Sh CONFIGURATION FILE
 120 The configuration file contains a list of rules.
 121 Each rule takes one line and consists of two or more
 122 whitespace separated fields.
 123 A hash
 124 .Pq Dq #
 125 character causes the remainder of a line to be ignored.
 126 Blank lines are ignored.
 127 .Pp
 128 The first field is a pathname prefix to match
 129 against the requested pathname.
 130 If a match is found, the second field
 131 tells the daemon what type of object to create.
 132 Subsequent fields are passed to the creation function.
 133 .Pp
 134 The
 135 .Pa rfilter
 136 and
 137 .Pa wfilter
 138 namespaces have additional meanings for the remaining fields.
 139 The third field specifies a prefix that is to be stripped off of
 140 the passed name before passing it on to the pipe program.
 141 If the prefix does not match, no stripping is performed.
 142 The fourth argument specifies the program to use for the pipe.
 143 Any remaining fields are passed to the pipe program.
 144 If the string
 145 .Dq Li "%s"
 146 exists within these remaining fields, it will be replaced by the
 147 path after stripping is performed.
 148 If there is no field after the program name,
 149 .Dq Li "%s"
 150 will be assumed, to maintain similarity with the
 151 .Pa tcp
 152 and
 153 .Pa fs
 154 namespaces.
 155 .Sh FILES
 156 .Bl -tag -width /p/* -compact
 157 .It Pa /p/*
 158 .El
 159 .Sh EXAMPLES
 160 A tutorial and several examples are provided in
 161 .Pa /usr/share/examples/mount_portal .
 162 The following is an example configuration file.
 163 .Pp
 164 .Bd -literal
 165 # @(#)portal.conf       5.1 (Berkeley) 7/13/92
 166 tcp/            tcp tcp/
 167 fs/             file fs/
 168 echo/           rfilter echo/   echo %s
 169 echo_nostrip/   rfilter nostrip echo %s
 170 echo_noslash    rfilter echo_noslash    echo %s
 171 gzcat/          rfilter gzcat/ gzcat %s
 172 gzip/           wfilter gzip/   gzip \*[Gt] %s
 173 gzip9/          wfilter gzip9/  gzip -9 \*[Gt] %s
 174 ftp/            rfilter ftp/    ftp -Vo - %s
 175 ftp://          rfilter nostrip ftp -Vo - %s
 176 http://         rfilter nostrip ftp -Vo - %s
 177 bzcat/          rfilter bzcat/  bzcat %s
 178 nroff/          rfilter nroff/  nroff -man %s
 179 .Ed
 180 .Pp
 181 As is true with many other filesystems, a weird sense of humor is handy.
 182 .Pp
 183 Notice that after the keynames, like nroff/ and bzcat/, we
 184 typically use another slash.
 185 In reality, the
 186 .Nm
 187 process changes directory to
 188 .Pa / ,
 189 which makes the subsequent slash unnecessary.
 190 However, the extra slash provides a visual hint
 191 that we are not operating on an ordinary file.
 192 An alternative would be to change the configuration
 193 file to something like:
 194 .Bd -literal
 195 nroff%  rfilter nroff%  nroff -man
 196 .Ed
 197 .Pp
 198 One might then use
 199 .Bd -literal
 200 less /p/nroff%/usr/share/man/man8/mount_portal.8
 201 .Ed
 202 .Sh SEE ALSO
 203 .Xr mount 2 ,
 204 .Xr unmount 2 ,
 205 .Xr fstab 5 ,
 206 .Xr mount 8
 207 .Sh HISTORY
 208 The
 209 .Nm
 210 utility first appeared in
 211 .Bx 4.4 .
 212 The
 213 .Pa rfilter
 214 and
 215 .Pa wfilter
 216 capabilities first appeared in
 217 .Nx 1.5 .
 218 The portal kernel driver was removed and
 219 .Nm
 220 was converted to use
 221 .Xr puffs 3
 222 in
 223 .Nx 6.0 .
 224 .Sh BUGS
 225 This filesystem may not be NFS-exported.