diff options
author | rgrimes <rgrimes@FreeBSD.org> | 1994-05-26 06:35:07 +0000 |
---|---|---|
committer | rgrimes <rgrimes@FreeBSD.org> | 1994-05-26 06:35:07 +0000 |
commit | d038e02fd667ab6c02875840105798aaa7029504 (patch) | |
tree | b555a2b228429d62f4946ae1a7e68c33012e1b03 /sbin/mount_umap/umap_manual | |
parent | e3cfc8ce61f788739c66445d903f8beacb40c93d (diff) | |
download | FreeBSD-src-d038e02fd667ab6c02875840105798aaa7029504.zip FreeBSD-src-d038e02fd667ab6c02875840105798aaa7029504.tar.gz |
BSD 4.4 Lite sbin Sources
Note: XNSrouted and routed NOT imported here, they shall be imported with
usr.sbin.
Diffstat (limited to 'sbin/mount_umap/umap_manual')
-rw-r--r-- | sbin/mount_umap/umap_manual | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/sbin/mount_umap/umap_manual b/sbin/mount_umap/umap_manual new file mode 100644 index 0000000..059939f --- /dev/null +++ b/sbin/mount_umap/umap_manual @@ -0,0 +1,175 @@ + +\appendix +\section{The umap Layer} \label{sect:umap} + +\subsection{Introduction} + +Normally, the file system is expected to span a single administrative domain. +An administrative domain, for these purposes, is a machine or set of +machines that share common password file information, usually through +the yellow pages mechanism. File hierarchies that span more +than one domain leads to certain problems, since the same numerical +UID in one domain may correspond to a different user in another domain. +If the system administrator is very careful to ensure that both domains +contain identical user ID information, The umap layer can be used to +run between those domains without changes + +The umap layer is a file system layer that sits on top of the normal +file layer. The umap layer maps Unix-style UIDs from +one domain into the UIDs in the other domain. By setting up the mappings +properly, the same user with different UIDs in two domains can be seen +as the same user, from the system point of view, or, conversely, two +different users with the same UID in the two domains can be distinguished. + +First, we define some terms. ``User'' refers to the human (or daemon) that +has privileges to login, run programs, and access files. ``UID''refers to +the numerical identifier that uniquely identifies the user within a +single domain. ``Login name'' refers to the character string the user +types to log into the system. ``GID'' refers to the numerical group +identifier used by Unix systems to identify groups of users. ``Group +name'' is the character string name attached to a particular GID in the +local {\sf /etc/groups} file or the yellow pages groups file. + +In order for the umap layer to work properly, all users +in either domain must have password file entries in both domains. +They do not, however, have to have the same numerical UID, nor even the +same character string login name (the latter is highly recommended, +if possible, however). Any user not having a UID in one domain will be +treated as the special user NOBODY by the other domain, probably with +undesirable consequences. Any user not owning any files in the shared +sub-trees need not be given a UID in the other domain. + +Groups work similarly. The umap layer can translate group ID's between +domains in the same manner as UID's. Again, any group that wishes to +participate must have a group ID in both domains, +though it need not be the same GID in both. If a group in one domain is not +known in the other domain, that group will be treated as being NULLGROUP. +The umap layer has no provisions for enrolling UID's from other domains +as group members, but, since each user from each domain must have some +UID in every domain, the UID in the local domain can be used to enroll +the user in the local groups. + +NOBODY and NULLGROUP are special reserved UID's and GID's, respectively. +NOBODY is user 32767. NULLGROUP is group 65534. If the system administrator +wants to have an appropriate text string appear when these UID's are +encountered by programs like {\sf ls -l}, he should add these values to +the password and {\sf /etc/groups} file, or to the appropriate yellow pages. +If these IDs are already in use in that domain, different values can be +used for NOBODY and NULLGROUP, but that will require a recompilation of +the umap layer code and, as a result, the entire kernel. These +values are defined in the {\sf umap\_info.h} file, kept with the rest of the +umap source code. + +When the umap layer is in use, one of the participating domains is declared +to be the master. All UID and GID information stored for participating files +will be stored in vnodes using its mappings, no matter what site the copies of +the files are stored at. The master domain therefore need not run a copy +of the umap layer, as it already has all of the correct mappings. All +other domains must run a umap layer on top of any other layers they use. + +\subsection{Setting Up a umap Layer} + +The system administrator of a system needing to use the umap layer +must take several actions. +First, he must create files containing the necessary UID +and GID mappings. There is a separate file for user and group IDs. The +format of the files is the same. The first line contains the total number +of entries in the file. Each subsequent line contains one mapping. A +mapping line consists of two numerical UIDs, separated by white space. +The first is the UID of a user on the local machine. The second is the +UID for the same user on the master machine. The maximum number of users +that can be mapped for a single shared sub-tree is 64. The maximum number of +groups that can be mapped for a single sub-tree is 16. These constants +are set in the {\sf umap\_info.h} file, and can be changed, but changing them +requires recompilation. Separate mapping files can be used for each shared +subtree, or the same mapping files can be shared by several sub-trees. + +Below is a sample UID mapping file. There are four entries. UID 5 is mapped +to 5, 521 to 521, and 7000 to 7000. UID 2002 is mapped to 604. On this +machine, the UID's for users 5, 521, and 7000 are the same as on the master, +but UID 2002 is for a user whose UID on the master machine is 604. All +files in the sub-tree belonging to that user have UID 604 in their inodes, +even on this machine, but the umap layer will ensure that anyone running +under UID 2002 will have all files in this sub-tree owned by 604 treated as if +they were owned by 2002. An {\sf ls -l} on a file owned by 604 in this sub-tree +will show the login name associated with UID 2002 as the owner. + +\noindent4\newline +5 5\newline +521 521\newline +2002 604\newline +7000 7000\newline + +The user and group mapping files should be owned by the root user, and +should be writable only by that user. If they are not owned by root, or +are writable by some other user, the umap mounting command will abort. + +Normally, the sub-treeis grafted directly into the place in +the file hierarchy where the it should appear to users.Using the umap +layer requires that the sub-tree be grafted somewhere else, and +the umap layer be mounted in the desired position in the file hierarchy. +Depending on the situation, the underlying sub-tree can be wherever is +convenient. + +\subsection{Troubleshooting umap Layer Problems} + +The umap layer code was not built with special convenience or +robustness in mind, as it is expected to be superseded with a better +user ID mapping strategy in the near future. As a result, it is not +very forgiving of errors in being set up. Here are some possible +problems, and what to do about them. + +\begin{itemize} + + +\item{Problem: A file belongs to NOBODY, or group NULLGROUP. + +Fixes: The mapping files don't know about this file's real user or group. +Either they are not in the mapping files, or the counts on the number of +entries in the mapping files are too low, so entries at the end (including +these) are being ignored. Add the entries or fix the counts, and either +unmount and remount the sub-tree, or reboot.} + +\item{Problem: A normal operation does not work. + +Fixes: Possibly, some mapping has not been set properly. Check to +see which files are used by the operation and who they appear to be +owned by. If they are owned by NOBODY or some other suspicious user, +there may be a problem in the mapping files. Be sure to check groups, +too. As above, if the counts of mappings in the mapping files are lower +than the actual numbers of pairs, pairs at the end of the file will be +ignored. If any changes are made in the mapping files, you will need to +either unmount and remount or reboot before they will take effect. + +Another possible problem can arise because not all Unix utilities +rely exclusively on numeric UID for identification. For instance, +SCCS saves the login name in files. If a user's login name on two machines +isn't the same, SCCS may veto an operation even though Unix file permissions, +as checked by the umap layer, may say it's OK. There's not much to be +done in such cases, unless the login name can be changed or one fiddles +improperly with SCCS information. There may be other, undiscovered cases +where similar problems arise, some of which may be even harder to handle.} + +\item{Problem: Someone has access permissions he should not have. + +Fixes: This is probably caused by a mistake in the mapping files. Check +both user and group mapping files. If any changes are made in the mapping +files, you will need to unmount and remount the sub-tree or reboot before they +will take effect.} + +\item{Problem: {\sf ls -l} (or a similar program) shows the wrong user for a file. + +Fixes: Probably a mistake in the mapping files. In particular, if +two local UIDs are mapped to a single master UID, stat calls will assign +ownership to the first local UID occurring in the file, which may or may +not be what was intended. (Generally speaking, mapping two local UIDs to +a single master UID is a bad idea, but the software will not prevent it. +Similarly, mapping a single local UID to two master UIDs is a bad idea, +but will not be prevented. In this case, only the first mapping of the +local UID will be done. The second, and all subsequent ones, will be +ignored.) If any changes are made in the mapping files, you will need to +unmount and remount the sub-tree or reboot before they will take effect.} + +\end{itemize} + +\end{document} |