fix mandoc(1) warnings in sbin/
[dragonfly.git] / sbin / mount_portal / mount_portal.8
CommitLineData
984263bc
MD
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.
dc71b7ab 17.\" 3. Neither the name of the University nor the names of its contributors
984263bc
MD
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: src/sbin/mount_portal/mount_portal.8,v 1.8.2.2 2001/12/20 16:41:47 ru Exp $
35.\"
36.Dd March 27, 1994
37.Dt MOUNT_PORTAL 8
38.Os
39.Sh NAME
40.Nm mount_portal
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
48The
49.Nm
50command attaches an instance of the portal daemon
51to the global filesystem namespace.
52The conventional mount point is
53.Pa /p .
54.\" .PA /dev .
55This command is normally executed by
56.Xr mount 8
57at boot time.
58.Pp
59The options are as follows:
60.Bl -tag -width indent
61.It Fl o
62Options are specified with a
63.Fl o
64flag followed by a comma separated string of options.
65See the
66.Xr mount 8
67man page for possible options and their meanings.
68.El
69.Pp
70The portal daemon provides an
71.Em open
72service.
73Objects opened under the portal mount point are
74dynamically created by the portal daemon according
75to rules specified in the named configuration file.
76Using this mechanism allows descriptors such as sockets
77to be made available in the filesystem namespace.
78.Pp
79The portal daemon works by being passed the full pathname
80of the object being opened.
81The daemon creates an appropriate descriptor according
82to the rules in the configuration file, and then passes the descriptor back
83to the calling process as the result of the open system call.
84.Sh NAMESPACE
85By convention, the portal daemon divides the namespace into sub-namespaces,
86each of which handles objects of a particular type.
87.Pp
88The following sub-namespaces are currently implemented:
89.Pa tcplisten ,
90.Pa tcp
91and
92.Pa fs .
93The
94.Pa tcplisten
95namespace takes a slash separated hostname and port and creates a TCP/IP
96socket bound to the given hostname-port pair.
97The hostname may be
98specified as "ANY" to allow any other host to connect to the socket.
99A
100port number of 0 will dynamically allocate a port, this can be
101discovered by calling
102.Xr getsockname 2
103with the returned file descriptor.
104Privileged ports can only be bound to
105by the super-user.
106The
107.Pa tcp
108namespace takes a hostname and a port (slash separated) and
109creates an open TCP/IP connection.
110The
111.Pa fs
112namespace opens the named file, starting back at the root directory.
113This can be used to provide a controlled escape path from
114a chrooted environment.
ec9265c3 115.Sh CONFIGURATION FILE
984263bc
MD
116The configuration file contains a list of rules.
117Each rule takes one line and consists of two or more
118whitespace separated fields.
119A hash (``#'') character causes the remainder of a line to
120be ignored. Blank lines are ignored.
121.Pp
122The first field is a pathname prefix to match
123against the requested pathname.
124If a match is found, the second field
125tells the daemon what type of object to create.
126Subsequent fields are passed to the creation function.
127.Bd -literal
128# @(#)portal.conf 5.1 (Berkeley) 7/13/92
129tcplisten/ tcplisten tcplisten/
130tcp/ tcp tcp/
131fs/ file fs/
132.Ed
133.Sh FILES
134.Bl -tag -width /p/* -compact
135.It Pa /p/*
136.El
137.Sh SEE ALSO
138.Xr mount 2 ,
139.Xr unmount 2 ,
140.Xr fstab 5 ,
141.Xr mount 8
984263bc
MD
142.Sh HISTORY
143The
144.Nm
145utility first appeared in
146.Bx 4.4 .
1f214455
FF
147.Sh CAVEATS
148This filesystem may not be NFS-exported.