Rename doc subdirectories

We like these names better, and they match the PDF document filenames.

admins -> admin
appldev -> appdev
users -> user

and catch up where the names are used elsewhere.

The relay/ directory has been removed, with its contents moved to the
top level in build_this.rst and a new about.rst.

The section headers for kadmind, krb5kdc, sserver, kpasswd, kswitch,
and sclient are misdetected as conflict markers.
bigredbutton: whitespace

ticket: 7433
tags: pullup

3 files changed, 131 insertions, 0 deletions

diff --git a/doc/user/user_config/index.rst b/doc/user/user_config/index.rst
new file mode 100644
index 000000000..6b3d4393b
--- /dev/null
+++ b/doc/user/user_config/index.rst
@@ -0,0 +1,12 @@
+User config files
+=================
+
+The following files in your home directory can be used to control the
+behavior of Kerberos as it applies to your account (unless they have
+been disabled by your host's configuration):
+
+.. toctree::
+   :maxdepth: 1
+
+   k5login.rst
+   k5identity.rst
diff --git a/doc/user/user_config/k5identity.rst b/doc/user/user_config/k5identity.rst
new file mode 100644
index 000000000..21c340eab
--- /dev/null
+++ b/doc/user/user_config/k5identity.rst
@@ -0,0 +1,66 @@
+.. _.k5identity(5):
+
+.k5identity
+===========
+
+DESCRIPTION
+-----------
+
+The .k5identity file, which resides in a user's home directory,
+contains a list of rules for selecting a client principals based on
+the server being accessed.  These rules are used to choose a
+credential cache within the cache collection when possible.
+
+Blank lines and lines beginning with ``#`` are ignored.  Each line has
+the form:
+
+    *principal* *field*\=\ *value* ...
+
+If the server principal meets all of the field constraints, then
+principal is chosen as the client principal.  The following fields are
+recognized:
+
+**realm**
+    If the realm of the server principal is known, it is matched
+    against *value*, which may be a pattern using shell wildcards.
+    For host-based server principals, the realm will generally only be
+    known if there is a :ref:`domain_realm` section in
+    :ref:`krb5.conf(5)` with a mapping for the hostname.
+
+**service**
+    If the server principal is a host-based principal, its service
+    component is matched against *value*, which may be a pattern using
+    shell wildcards.
+
+**host**
+    If the server principal is a host-based principal, its hostname
+    component is converted to lower case and matched against *value*,
+    which may be a pattern using shell wildcards.
+
+    If the server principal matches the constraints of multiple lines
+    in the .k5identity file, the principal from the first matching
+    line is used.  If no line matches, credentials will be selected
+    some other way, such as the realm heuristic or the current primary
+    cache.
+
+
+EXAMPLE
+-------
+
+The following example .k5identity file selects the client principal
+``alice@KRBTEST.COM`` if the server principal is within that realm,
+the principal ``alice/root@EXAMPLE.COM`` if the server host is within
+a servers subdomain, and the principal ``alice/mail@EXAMPLE.COM`` when
+accessing the IMAP service on ``mail.example.com``:
+
+ ::
+
+    alice@KRBTEST.COM       realm=KRBTEST.COM
+    alice/root@EXAMPLE.COM  host=*.servers.example.com
+    alice/mail@EXAMPLE.COM  host=mail.example.com service=imap
+
+
+SEE ALSO
+--------
+
+kerberos(1), :ref:`krb5.conf(5)`
diff --git a/doc/user/user_config/k5login.rst b/doc/user/user_config/k5login.rst
new file mode 100644
index 000000000..00f5a5a3a
--- /dev/null
+++ b/doc/user/user_config/k5login.rst
@@ -0,0 +1,53 @@
+.. _.k5login(5):
+
+.k5login
+========
+
+DESCRIPTION
+-----------
+
+The .k5login file, which resides in a user's home directory, contains
+a list of the Kerberos principals.  Anyone with valid tickets for a
+principal in the file is allowed host access with the UID of the user
+in whose home directory the file resides.  One common use is to place
+a .k5login file in root's home directory, thereby granting system
+administrators remote root access to the host via Kerberos.
+
+
+EXAMPLES
+--------
+
+Suppose the user ``alice`` had a .k5login file in her home directory
+containing the following line:
+
+ ::
+
+    bob@FOOBAR.ORG
+
+This would allow ``bob`` to use Kerberos network applications, such as
+ssh(1), to access ``alice``'s account, using ``bob``'s Kerberos
+tickets.
+
+Let us further suppose that ``alice`` is a system administrator.
+Alice and the other system administrators would have their principals
+in root's .k5login file on each host:
+
+ ::
+
+    alice@BLEEP.COM
+
+    joeadmin/root@BLEEP.COM
+
+This would allow either system administrator to log in to these hosts
+using their Kerberos tickets instead of having to type the root
+password.  Note that because ``bob`` retains the Kerberos tickets for
+his own principal, ``bob@FOOBAR.ORG``, he would not have any of the
+privileges that require ``alice``'s tickets, such as root access to
+any of the site's hosts, or the ability to change ``alice``'s
+password.
+
+
+SEE ALSO
+--------
+
+kerberos(1)