usr.sbin/mount_portalfs/mount_portalfs.8

   1 .\"
   2 .\" Copyright (c) 1993, 1994
   3 .\"     The Regents of the University of California.  All rights reserved.
   4 .\" 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 .\" 4. 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 .\" $FreeBSD$
  35 .\"
  36 .Dd March 11, 2005
  37 .Dt MOUNT_PORTALFS 8
  38 .Os
  39 .Sh NAME
  40 .Nm mount_portalfs
  41 .Nd mount the portal daemon
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl o Ar options
  45 .Ar /etc/portal.conf
  46 .Ar mount_point
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility attaches an instance of the portal daemon
  51 to the global file system namespace.
  52 The conventional mount point is
  53 .Pa /p .
  54 .\" .PA /dev .
  55 This command is normally executed by
  56 .Xr mount 8
  57 at boot time.
  58 .Pp
  59 The options are as follows:
  60 .Bl -tag -width indent
  61 .It Fl o
  62 Options are specified with a
  63 .Fl o
  64 flag followed by a comma separated string of options.
  65 See the
  66 .Xr mount 8
  67 man page for possible options and their meanings.
  68 .El
  69 .Pp
  70 The portal daemon provides an
  71 .Em open
  72 service.
  73 Objects opened under the portal mount point are
  74 dynamically created by the portal daemon according
  75 to rules specified in the named configuration file.
  76 Using this mechanism allows descriptors such as sockets
  77 to be made available in the file system namespace.
  78 .Pp
  79 The portal daemon works by being passed the full pathname
  80 of the object being opened.
  81 The daemon creates an appropriate descriptor according
  82 to the rules in the configuration file, and then passes the descriptor back
  83 to the calling process as the result of the open system call.
  84 .Sh NAMESPACE
  85 By convention, the portal daemon divides the namespace into sub-namespaces,
  86 each of which handles objects of a particular type.
  87 .Pp
  88 The following sub-namespaces are currently implemented:
  89 .Pa fs ,
  90 .Pa pipe ,
  91 .Pa tcp ,
  92 and
  93 .Pa tcplisten .
  94 .Pp
  95 The
  96 .Pa fs
  97 namespace opens the named file, starting back at the root directory.
  98 This can be used to provide a controlled escape path from
  99 a chrooted environment.
 100 .Pp
 101 The
 102 .Pa pipe
 103 namespace executes the named command, starting back at the root directory.
 104 The command's arguments can be provided after the command's name,
 105 by separating them with spaces or tabs.
 106 Files opened for reading in the
 107 .Pa pipe
 108 namespace will receive their input from the command's standard output;
 109 files opened for writing will send the data of write operations
 110 to the command's standard input.
 111 .Pp
 112 The
 113 .Pa tcp
 114 namespace takes a slash separated hostname and a port and
 115 creates an open TCP/IP connection.
 116 .Pp
 117 The
 118 .Pa tcplisten
 119 namespace takes a slash separated hostname and port and creates a TCP/IP
 120 socket bound to the given hostname-port pair.
 121 The hostname may be
 122 specified as "ANY" to allow any other host to connect to the socket.
 123 A
 124 port number of 0 will dynamically allocate a port, this can be
 125 discovered by calling
 126 .Xr getsockname 2
 127 with the returned file descriptor.
 128 Privileged ports can only be bound to
 129 by the super-user.
 130 .Sh "CONFIGURATION FILE"
 131 The configuration file contains a list of rules.
 132 Each rule takes one line and consists of two or more
 133 whitespace separated fields.
 134 A hash (``#'') character causes the remainder of a line to
 135 be ignored.
 136 Blank lines are ignored.
 137 .Pp
 138 The first field is a pathname prefix to match
 139 against the requested pathname.
 140 If a match is found, the second field
 141 tells the daemon what type of object to create.
 142 Subsequent fields are passed to the creation function.
 143 .Bd -literal
 144 # @(#)portal.conf       5.1 (Berkeley) 7/13/92
 145 tcplisten/      tcplisten tcplisten/
 146 tcp/            tcp tcp/
 147 fs/             file fs/
 148 pipe/           pipe pipe/
 149 .Ed
 150 .Sh FILES
 151 .Bl -tag -width /p/* -compact
 152 .It Pa /p/*
 153 .El
 154 .Sh EXAMPLES
 155 Display the greeting of the
 156 .Fx
 157 .Tn SMTP
 158 server.
 159 .Pp
 160 .Dl "head -1 /p/tcp/mx1.freebsd.org/smtp"
 161 .Pp
 162 Implement a (single-threaded) echo server:
 163 .Bd -literal -offset indent
 164 while :
 165 do
 166     (exec 3<>/p/tcplisten/ANY/echo && cat -u <&3 >&3)
 167 done
 168 .Ed
 169 .Pp
 170 Gather data from two sources.
 171 Verify that two remote files are identical:
 172 .Bd -literal -offset indent
 173 diff -q '/p/pipe/usr/bin/fetch -o - \\
 174         ftp://ftp1.freebsd.org/pub/FreeBSD/README.TXT' \\
 175     '/p/pipe/usr/bin/fetch -o - \\
 176         ftp://ftp2.freebsd.org/pub/FreeBSD/README.TXT'
 177 .Ed
 178 .Pp
 179 Scatter data to two sinks.
 180 Record a remote
 181 .Tn CD
 182 .Tn ISO
 183 image and calculate its checksum:
 184 .Bd -literal -offset indent
 185 fetch -o - ftp://ftp5.freebsd.org/.../disc.iso |
 186 tee '/p/pipe/usr/local/bin/cdrecord -' |
 187 md5
 188 .Ed
 189 .Pp
 190 Create an
 191 .Tn XML
 192 view of the password file:
 193 .Bd -literal -offset indent
 194 ln -s '/p/pipe/usr/local/bin/passwd2xml /etc/passwd' \\
 195     /etc/passwd.xml"
 196 .Ed
 197 .Sh SEE ALSO
 198 .Xr mount 2 ,
 199 .Xr unmount 2 ,
 200 .Xr fstab 5 ,
 201 .Xr mount 8
 202 .Rs
 203 .%A "W. Richard Stevens"
 204 .%A "Jan-Simon Pendry"
 205 .%T "Portals in 4.4BSD"
 206 .%B "USENIX 1995 Technical Conference Proceedings"
 207 .%O "Berkeley, CA"
 208 .%I "Peter Honeyman"
 209 .Re
 210 .Sh HISTORY
 211 The
 212 .Nm
 213 utility first appeared in
 214 .Bx 4.4 .
 215 .Sh CAVEATS
 216 This file system may not be NFS-exported.