freebsd-src/sbin/mount_umapfs/umap_manual

\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-tree is 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}