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