GC !__DragonFly__ section.
[dragonfly.git] / sbin / mount_umap / mount_umap.8
CommitLineData
984263bc
MD
1.\" Copyright (c) 1992, 1993, 1994
2.\" The Regents of the University of California. All rights reserved.
3.\" All rights reserved.
4.\"
5.\" This code is derived from software donated to Berkeley by
6.\" Jan-Simon Pendry and from John Heidemann of the UCLA Ficus project.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\" 3. All advertising materials mentioning features or use of this software
17.\" must display the following acknowledgement:
18.\" This product includes software developed by the University of
19.\" California, Berkeley and its contributors.
20.\" 4. Neither the name of the University nor the names of its contributors
21.\" may be used to endorse or promote products derived from this software
22.\" without specific prior written permission.
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" @(#)mount_umap.8 8.4 (Berkeley) 5/1/95
37.\" $FreeBSD: src/sbin/mount_umap/mount_umap.8,v 1.10.2.3 2001/12/20 16:44:17 ru Exp $
1de703da 38.\" $DragonFly: src/sbin/mount_umap/Attic/mount_umap.8,v 1.2 2003/06/17 04:27:33 dillon Exp $
984263bc
MD
39.\"
40.Dd May 1, 1995
41.Dt MOUNT_UMAP 8
42.Os
43.Sh NAME
44.Nm mount_umap
45.Nd sample file system layer
46.Sh SYNOPSIS
47.Nm
48.Op Fl o Ar options
49.Fl u Ar uid-mapfile
50.Fl g Ar gid-mapfile
51.Ar target
52.Ar mount-point
53.Sh DESCRIPTION
54The
55.Nm
56command is used to mount a sub-tree of an existing file system
57that uses a different set of uids and gids than the local system.
58Such a file system could be mounted from a remote site via NFS or
59it could be a file system on removable media brought from some
60foreign location that uses a different password file.
61.Pp
62The
63.Nm
64command uses a set of files provided by the user to make correspondences
65between uids and gids in the sub-tree's original environment and
66some other set of ids in the local environment. For instance, user
67smith might have uid 1000 in the original environment, while having
68uid 2000 in the local environment. The
69.Nm
70command allows the subtree from smith's original environment to be
71mapped in such a way that all files with owning uid 1000 look like
72they are actually owned by uid 2000.
73.Pp
74The options are as follows:
75.Bl -tag -width indent
76.It Fl o
77Options are specified with a
78.Fl o
79flag followed by a comma separated string of options.
80See the
81.Xr mount 8
82man page for possible options and their meanings.
83.It Ar target
84Should be the current location of the sub-tree in the
85local system's name space.
86.It Ar mount-point
87Should be a directory
88where the mapped subtree is to be placed.
89.It Fl u Ar uid-mapfile
90.It Fl g Ar gid-mapfile
91Describe the mappings to be made between identifiers.
92Briefly, the format of these files is a count of the number of
93mappings on the first line, with each subsequent line containing
94a single mapping. Each of these mappings consists of an id in
95the local environment and the corresponding id from the original environment,
96separated by white space.
97.Ar Uid-mapfile
98should contain all uid
99mappings, and
100.Ar gid-mapfile
101should contain all gid mappings.
102Any uids not mapped in
103.Ar uid-mapfile
104will be treated as user NOBODY,
105and any gids not mapped in
106.Ar gid-mapfile
107will be treated as group
108NULLGROUP. At most 64 uids can be mapped for a given subtree, and
109at most 16 groups can be mapped by a given subtree.
110.El
111.Pp
112The mapfiles can be located anywhere in the file hierarchy, but they
113must be owned by root, and they must be writable only by root.
114.Nm Mount_umap
115will refuse to map the sub-tree if the ownership or permissions on
116these files are improper. It will also balk if the count of mappings
117in the first line of the map files is not correct.
118.Pp
119The layer created by the
120.Nm
121command is meant to serve as a simple example of file system layering.
122It is not meant for production use. The implementation is not very
123sophisticated.
124.Sh SEE ALSO
125.Xr mount 8 ,
126.Xr mount_null 8
127.Sh BUGS
128THIS FILESYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK)
129AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. USE AT YOUR
130OWN RISK. BEWARE OF DOG. SLIPPERY WHEN WET.
131.Pp
132This code also needs an owner in order to be less dangerous - serious
133hackers can apply by sending mail to
134.Aq hackers@FreeBSD.org
135and announcing
136their intent to take it over.
137.Sh HISTORY
138The
139.Nm
140utility first appeared in
141.Bx 4.4 .