sbin/mount_umap/umap_manual

   1
   2 \appendix
   3 \section{The umap Layer} \label{sect:umap}
   4
   5 \subsection{Introduction}
   6
   7 Normally, the file system is expected to span a single administrative domain.
   8 An administrative domain, for these purposes, is a machine or set of
   9 machines that share common password file information, usually through
  10 the yellow pages mechanism.  File hierarchies that span more
  11 than one domain leads to certain problems, since the same numerical
  12 UID in one domain may correspond to a different user in another domain.
  13 If the system administrator is very careful to ensure that both domains
  14 contain identical user ID information, the umap layer can be used to
  15 run between those domains without changes
  16
  17 The umap layer is a file system layer that sits on top of the normal
  18 file layer.  The umap layer maps Unix-style UIDs from
  19 one domain into the UIDs in the other domain.  By setting up the mappings
  20 properly, the same user with different UIDs in two domains can be seen
  21 as the same user, from the system point of view, or, conversely, two
  22 different users with the same UID in the two domains can be distinguished.
  23
  24 First, we define some terms.  ``User'' refers to the human (or daemon) that
  25 has privileges to login, run programs, and access files.  ``UID''refers to
  26 the numerical identifier that uniquely identifies the user within a
  27 single domain.  ``Login name'' refers to the character string the user
  28 types to log into the system.  ``GID'' refers to the numerical group
  29 identifier used by Unix systems to identify groups of users.  ``Group
  30 name'' is the character string name attached to a particular GID in the
  31 local {\sf /etc/groups} file or the yellow pages groups file.
  32
  33 In order for the umap layer to work properly, all users
  34 in either domain must have password file entries in both domains.
  35 They do not, however, have to have the same numerical UID, nor even the
  36 same character string login name (the latter is highly recommended,
  37 if possible, however).  Any user not having a UID in one domain will be
  38 treated as the special user NOBODY by the other domain, probably with
  39 undesirable consequences.  Any user not owning any files in the shared
  40 sub-trees need not be given a UID in the other domain.
  41
  42 Groups work similarly.  The umap layer can translate group ID's between
  43 domains in the same manner as UID's.  Again, any group that wishes to
  44 participate must have a group ID in both domains,
  45 though it need not be the same GID in both.  If a group in one domain is not
  46 known in the other domain, that group will be treated as being NULLGROUP.
  47 The umap layer has no provisions for enrolling UID's from other domains
  48 as group members, but, since each user from each domain must have some
  49 UID in every domain, the UID in the local domain can be used to enroll
  50 the user in the local groups.
  51
  52 NOBODY and NULLGROUP are special reserved UID's and GID's, respectively.
  53 NOBODY is user 32767.  NULLGROUP is group 65534.  If the system administrator
  54 wants to have an appropriate text string appear when these UID's are
  55 encountered by programs like {\sf ls -l}, he should add these values to
  56 the password and {\sf /etc/groups} file, or to the appropriate yellow pages.
  57 If these IDs are already in use in that domain, different values can be
  58 used for NOBODY and NULLGROUP, but that will require a recompilation of
  59 the umap layer code and, as a result, the entire kernel.  These
  60 values are defined in the {\sf umap\_info.h} file, kept with the rest of the
  61 umap source code.
  62
  63 When the umap layer is in use, one of the participating domains is declared
  64 to be the master.  All UID and GID information stored for participating files
  65 will be stored in vnodes using its mappings, no matter what site the copies of
  66 the files are stored at.  The master domain therefore need not run a copy
  67 of the umap layer, as it already has all of the correct mappings.  All
  68 other domains must run a umap layer on top of any other layers they use.
  69
  70 \subsection{Setting Up a umap Layer}
  71
  72 The system administrator of a system needing to use the umap layer
  73 must take several actions.
  74 First, he must create files containing the necessary UID
  75 and GID mappings.  There is a separate file for user and group IDs.  The
  76 format of the files is the same.  The first line contains the total number
  77 of entries in the file.  Each subsequent line contains one mapping.  A
  78 mapping line consists of two numerical UIDs, separated by white space.
  79 The first is the UID of a user on the local machine.  The second is the
  80 UID for the same user on the master machine.  The maximum number of users
  81 that can be mapped for a single shared sub-tree is 64.  The maximum number of
  82 groups that can be mapped for a single sub-tree is 16.  These constants
  83 are set in the {\sf umap\_info.h} file, and can be changed, but changing them
  84 requires recompilation.  Separate mapping files can be used for each shared
  85 subtree, or the same mapping files can be shared by several sub-trees.
  86
  87 Below is a sample UID mapping file.  There are four entries.  UID 5 is mapped
  88 to 5, 521 to 521, and 7000 to 7000.  UID 2002 is mapped to 604.  On this
  89 machine, the UID's for users 5, 521, and 7000 are the same as on the master,
  90 but UID 2002 is for a user whose UID on the master machine is 604.  All
  91 files in the sub-tree belonging to that user have UID 604 in their inodes,
  92 even on this machine, but the umap layer will ensure that anyone running
  93 under UID 2002 will have all files in this sub-tree owned by 604 treated as if
  94 they were owned by 2002.  An {\sf ls -l} on a file owned by 604 in this sub-tree
  95 will show the login name associated with UID 2002 as the owner.
  96
  97 \noindent4\newline
  98 5 5\newline
  99 521 521\newline
 100 2002 604\newline
 101 7000 7000\newline
 102
 103 The user and group mapping files should be owned by the root user, and
 104 should be writable only by that user.  If they are not owned by root, or
 105 are writable by some other user, the umap mounting command will abort.
 106
 107 Normally, the sub-tree is grafted directly into the place in
 108 the file hierarchy where the it should appear to users. Using the umap
 109 layer requires that the sub-tree be grafted somewhere else, and
 110 the umap layer be mounted in the desired position in the file hierarchy.
 111 Depending on the situation, the underlying sub-tree can be wherever is
 112 convenient.
 113
 114 \subsection{Troubleshooting umap Layer Problems}
 115
 116 The umap layer code was not built with special convenience or
 117 robustness in mind, as it is expected to be superseded with a better
 118 user ID mapping strategy in the near future.  As a result, it is not
 119 very forgiving of errors in being set up.  Here are some possible
 120 problems, and what to do about them.
 121
 122 \begin{itemize}
 123
 124
 125 \item{Problem: A file belongs to NOBODY, or group NULLGROUP.
 126
 127 Fixes: The mapping files don't know about this file's real user or group.
 128 Either they are not in the mapping files, or the counts on the number of
 129 entries in the mapping files are too low, so entries at the end (including
 130 these) are being ignored.  Add the entries or fix the counts, and either
 131 unmount and remount the sub-tree, or reboot.}
 132
 133 \item{Problem: A normal operation does not work.
 134
 135 Fixes: Possibly, some mapping has not been set properly.  Check to
 136 see which files are used by the operation and who they appear to be
 137 owned by.  If they are owned by NOBODY or some other suspicious user,
 138 there may be a problem in the mapping files.  Be sure to check groups,
 139 too.  As above, if the counts of mappings in the mapping files are lower
 140 than the actual numbers of pairs, pairs at the end of the file will be
 141 ignored.  If any changes are made in the mapping files, you will need to
 142 either unmount and remount or reboot before they will take effect.
 143
 144 Another possible problem can arise because not all Unix utilities
 145 rely exclusively on numeric UID for identification.  For instance,
 146 SCCS saves the login name in files.  If a user's login name on two machines
 147 isn't the same, SCCS may veto an operation even though Unix file permissions,
 148 as checked by the umap layer, may say it's OK.  There's not much to be
 149 done in such cases, unless the login name can be changed or one fiddles
 150 improperly with SCCS information.  There may be other, undiscovered cases
 151 where similar problems arise, some of which may be even harder to handle.}
 152
 153 \item{Problem: Someone has access permissions he should not have.
 154
 155 Fixes: This is probably caused by a mistake in the mapping files.  Check
 156 both user and group mapping files.  If any changes are made in the mapping
 157 files, you will need to unmount and remount the sub-tree or reboot before they
 158 will take effect.}
 159
 160 \item{Problem: {\sf ls -l} (or a similar program) shows the wrong user for a file.
 161
 162 Fixes: Probably a mistake in the mapping files.  In particular, if
 163 two local UIDs are mapped to a single master UID, stat calls will assign
 164 ownership to the first local UID occurring in the file, which may or may
 165 not be what was intended.  (Generally speaking, mapping two local UIDs to
 166 a single master UID is a bad idea, but the software will not prevent it.
 167 Similarly, mapping a single local UID to two master UIDs is a bad idea,
 168 but will not be prevented.  In this case, only the first mapping of the
 169 local UID will be done.  The second, and all subsequent ones, will be
 170 ignored.) If any changes are made in the mapping files, you will need to
 171 unmount and remount the sub-tree or reboot before they will take effect.}
 172
 173 \end{itemize}
 174
 175 \end{document}