sbin/mount_umap/mount_umap.8

   1 .\"     $NetBSD: mount_umap.8,v 1.18 2005/01/31 05:19:19 erh Exp $
   2 .\"
   3 .\" Copyright (c) 1992, 1993, 1994
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\" All rights reserved.
   6 .\"
   7 .\" This code is derived from software donated to Berkeley by
   8 .\" Jan-Simon Pendry and from John Heidemann of the UCLA Ficus project.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)mount_umap.8        8.4 (Berkeley) 5/1/95
  35 .\"
  36 .Dd March 6, 2001
  37 .Dt MOUNT_UMAP 8
  38 .Os
  39 .Sh NAME
  40 .Nm mount_umap
  41 .Nd user and group ID remapping file system layer
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl o Ar options
  45 .Fl g Ar gid-mapfile
  46 .Fl u Ar uid-mapfile
  47 .Ar target
  48 .Ar mount-point
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 command is used to mount a sub-tree of an existing file system
  53 that uses a different set of uids and gids than the local system.
  54 Such a file system could be mounted from a remote site via NFS,
  55 a local file system on removable media brought from some foreign
  56 location that uses a different user/group database, or could be
  57 a local file system for another operating system which does not
  58 support Unix-style user/group IDs, or which uses a different
  59 numbering scheme.
  60 .Pp
  61 Both
  62 .Ar target
  63 and
  64 .Ar mount-point
  65 are converted to absolute paths before use.
  66 .Pp
  67 The options are as follows:
  68 .Bl -tag -width indent
  69 .It Fl g Ar gid-mapfile
  70 Use the group ID mapping specified in
  71 .Ar gid-mapfile .
  72 This flag is required.
  73 .It Fl o
  74 Options are specified with a
  75 .Fl o
  76 flag followed by a comma separated string of options.
  77 See the
  78 .Xr mount 8
  79 man page for possible options and their meanings.
  80 .It Fl u Ar uid-mapfile
  81 Use the user ID mapping specified in
  82 .Ar uid-mapfile .
  83 This flag is required.
  84 .El
  85 .Pp
  86 The
  87 .Nm
  88 command uses a set of files provided by the user to make correspondences
  89 between uids and gids in the sub-tree's original environment and
  90 some other set of ids in the local environment.
  91 For instance, user smith might have uid 1000 in the original environment,
  92 while having uid 2000 in the local environment.
  93 The
  94 .Nm
  95 command allows the subtree from smith's original environment to be
  96 mapped in such a way that all files with owning uid 1000 look like
  97 they are actually owned by uid 2000.
  98 .Pp
  99 .Em target
 100 should be the current location of the sub-tree in the
 101 local system's name space.
 102 .Em mount-point
 103 should be a directory
 104 where the mapped subtree is to be placed.
 105 .Em uid-mapfile
 106 and
 107 .Em gid-mapfile
 108 describe the mappings to be made between identifiers.
 109 .Pp
 110 The format of the user and group ID mapping files is very simple.
 111 The first line of the file is the total number of mappings present
 112 in the file.
 113 The remaining lines each consist of two numbers: the
 114 ID in the mapped subtree and the ID in the original subtree.
 115 .Pp
 116 For example, to map uid 1000 in the original subtree to uid 2000
 117 in the mapped subtree:
 118 .Bd -unfilled -offset indent
 119 1
 120 2000 1000
 121 .Ed
 122 .Pp
 123 For user IDs in the original subtree for which no mapping exists,
 124 the user ID will be mapped to the user
 125 .Dq nobody .
 126 For group IDs in the original subtree for which no mapping exists,
 127 the group ID will be mapped to the group
 128 .Dq nobody .
 129 .Pp
 130 There is a limit of 64 user ID mappings and 16 group ID mappings.
 131 .Pp
 132 The mapfiles can be located anywhere in the file hierarchy, but they
 133 must be owned by root, and they must be writable only by root.
 134 .Nm
 135 will refuse to map the sub-tree if the ownership or permissions on
 136 these files are improper.
 137 It will also report an error if the count
 138 of mappings in the first line of the map files is not correct.
 139 .Sh SEE ALSO
 140 .Xr mount 8 ,
 141 .Xr mount_null 8
 142 .Sh HISTORY
 143 The
 144 .Nm
 145 utility first appeared in
 146 .Bx 4.4 .
 147 .Sh BUGS
 148 The implementation is not very sophisticated.