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