3 \section{The umap Layer} \label{sect:umap}
5 \subsection{Introduction}
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
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.
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.
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.
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.
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
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.
70 \subsection{Setting Up a umap Layer}
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.
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.
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.
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
114 \subsection{Troubleshooting umap Layer Problems}
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.
125 \item{Problem: A file belongs to NOBODY, or group NULLGROUP.
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.}
133 \item{Problem: A normal operation does not work.
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.
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.}
153 \item{Problem: Someone has access permissions he should not have.
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
160 \item{Problem: {\sf ls -l} (or a similar program) shows the wrong user for a file.
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.}