GC !__DragonFly__ section.
[dragonfly.git] / 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}