From 2319336ac1f52e56d2549bd83ff40a3e7b2f281a Mon Sep 17 00:00:00 2001

From: Robbie Harwood <rharwood@redhat.com>

Date: Mon, 15 Oct 2018 13:20:30 -0400

Subject: [PATCH] Modernize kerberos(7)

Update environment variable descriptions, using env_variables.rst as a

guide.  Replace the content in env_variables.rst with a pointer to

documentation at kerberos(7) so that we don't break external links and

don't duplicate content.

Replace references to rlogin.  Clarify and modernize other language.

ticket: 8755

(cherry picked from commit cdccdefa2d74d3abf5a8ae126e423af9d467d34f)

---

 doc/admin/env_variables.rst       |  44 +------------

 doc/user/user_config/kerberos.rst | 106 ++++++++++++++++++------------

 src/man/kerberos.man              | 104 +++++++++++++++++------------

 3 files changed, 128 insertions(+), 126 deletions(-)

diff --git a/doc/admin/env_variables.rst b/doc/admin/env_variables.rst

index 0c146d3e3..a2d15bea8 100644

--- a/doc/admin/env_variables.rst

+++ b/doc/admin/env_variables.rst

@@ -1,46 +1,4 @@

 Environment variables

 =====================

-The following environment variables can be used during runtime:

-

-**KRB5_CONFIG**

-    Main Kerberos configuration file.  Multiple filenames can be

-    specified, separated by a colon; all files which are present will

-    be read.  (See :ref:`mitK5defaults` for the default path.)

-

-**KRB5_KDC_PROFILE**

-    KDC configuration file.  (See :ref:`mitK5defaults` for the default

-    name.)

-

-**KRB5_KTNAME**

-    Default keytab file name.  (See :ref:`mitK5defaults` for the

-    default name.)

-

-**KRB5_CLIENT_KTNAME**

-    Default client keytab file name.  (See :ref:`mitK5defaults` for

-    the default name.)

-

-**KRB5CCNAME**

-    Default name for the credentials cache file, in the form *type*\:\

-    *residual*.  The type of the default cache may determine the

-    availability of a cache collection.  For instance, a default cache

-    of type ``DIR`` causes caches within the directory to be present

-    in the global cache collection.

-

-**KRB5RCACHETYPE**

-    Default replay cache type.  Defaults to ``dfl``.  A value of

-    ``none`` disables the replay cache.

-

-**KRB5RCACHEDIR**

-    Default replay cache directory.  (See :ref:`mitK5defaults` for the

-    default location.)

-

-**KPROP_PORT**

-    :ref:`kprop(8)` port to use.  Defaults to 754.

-

-**KRB5_TRACE**

-    Filename for trace-logging output (introduced in release 1.9).

-    For example, ``env KRB5_TRACE=/dev/stdout kinit`` would send

-    tracing information for kinit to ``/dev/stdout``.  Some programs

-    may ignore this variable (particularly setuid or login system

-    programs).

+This content has moved to :ref:`kerberos(7)`.

diff --git a/doc/user/user_config/kerberos.rst b/doc/user/user_config/kerberos.rst

index 6c4453b3b..56412f099 100644

--- a/doc/user/user_config/kerberos.rst

+++ b/doc/user/user_config/kerberos.rst

@@ -8,12 +8,12 @@ DESCRIPTION

 The Kerberos system authenticates individual users in a network

 environment.  After authenticating yourself to Kerberos, you can use

-Kerberos-enabled programs without having to present passwords.

+Kerberos-enabled programs without having to present passwords or

+certificates to those programs.

-If you enter your username and :ref:`kinit(1)` responds with this

-message:

+If you receive the following response from :ref:`kinit(1)`:

-kinit(v5): Client not found in Kerberos database while getting initial

+kinit: Client not found in Kerberos database while getting initial

 credentials

 you haven't been registered as a Kerberos user.  See your system

@@ -25,10 +25,13 @@ is the **instance**, which in the case of a user is usually null.

 Some users may have privileged instances, however, such as ``root`` or

 ``admin``.  In the case of a service, the instance is the fully

 qualified name of the machine on which it runs; i.e. there can be an

-rlogin service running on the machine ABC, which is different from the

-rlogin service running on the machine XYZ.  The third part of a

-Kerberos name is the **realm**.  The realm corresponds to the Kerberos

-service providing authentication for the principal.

+ssh service running on the machine ABC (ssh/ABC@REALM), which is

+different from the ssh service running on the machine XYZ

+(ssh/XYZ@REALM).  The third part of a Kerberos name is the **realm**.

+The realm corresponds to the Kerberos service providing authentication

+for the principal.  Realms are conventionally all-uppercase, and often

+match the end of hostnames in the realm (for instance, host01.example.com

+might be in realm EXAMPLE.COM).

 When writing a Kerberos name, the principal name is separated from the

 instance (if not null) by a slash, and the realm (if not the local

@@ -43,64 +46,72 @@ of valid Kerberos names::

 When you authenticate yourself with Kerberos you get an initial

 Kerberos **ticket**.  (A Kerberos ticket is an encrypted protocol

 message that provides authentication.)  Kerberos uses this ticket for

-network utilities such as rlogin and rcp.  The ticket transactions are

-done transparently, so you don't have to worry about their management.

+network utilities such as ssh.  The ticket transactions are done

+transparently, so you don't have to worry about their management.

-Note, however, that tickets expire.  Privileged tickets, such as those

-with the instance ``root``, expire in a few minutes, while tickets

-that carry more ordinary privileges may be good for several hours or a

-day, depending on the installation's policy.  If your login session

-extends beyond the time limit, you will have to re-authenticate

-yourself to Kerberos to get new tickets.  Use the :ref:`kinit(1)`

-command to re-authenticate yourself.

+Note, however, that tickets expire.  Administrators may configure more

+privileged tickets, such as those with service or instance of ``root``

+or ``admin``, to expire in a few minutes, while tickets that carry

+more ordinary privileges may be good for several hours or a day.  If

+your login session extends beyond the time limit, you will have to

+re-authenticate yourself to Kerberos to get new tickets using the

+:ref:`kinit(1)` command.

-If you use the kinit command to get your tickets, make sure you use

-the kdestroy command to destroy your tickets before you end your login

-session.  You should put the kdestroy command in your ``.logout`` file

-so that your tickets will be destroyed automatically when you logout.

-For more information about the kinit and kdestroy commands, see the

-:ref:`kinit(1)` and :ref:`kdestroy(1)` manual pages.

+Some tickets are **renewable** beyond their initial lifetime.  This

+means that ``kinit -R`` can extend their lifetime without requiring

+you to re-authenticate.

+

+If you wish to delete your local tickets, use the :ref:`kdestroy(1)`

+command.

 Kerberos tickets can be forwarded.  In order to forward tickets, you

 must request **forwardable** tickets when you kinit.  Once you have

 forwardable tickets, most Kerberos programs have a command line option

-to forward them to the remote host.

+to forward them to the remote host.  This can be useful for, e.g.,

+running kinit on your local machine and then sshing into another to do

+work.  Note that this should not be done on untrusted machines since

+they will then have your tickets.

 ENVIRONMENT VARIABLES

 ---------------------

 Several environment variables affect the operation of Kerberos-enabled

-programs.  These inclide:

+programs.  These include:

 **KRB5CCNAME**

-    Specifies the location of the credential cache, in the form

-    *TYPE*:*residual*.  If no *type* prefix is present, the **FILE**

-    type is assumed and *residual* is the pathname of the cache file.

-    A collection of multiple caches may be used by specifying the

-    **dir** type and the pathname of a private directory (which must

-    already exist).  The default cache file is /tmp/krb5cc_*uid*,

-    where *uid* is the decimal user ID of the user.

+    Default name for the credentials cache file, in the form

+    *TYPE*:*residual*.  The type of the default cache may determine

+    the availability of a cache collection.  ``FILE`` is not a

+    collection type; ``KEYRING``, ``DIR``, and ``KCM`` are.

+

+    If not set, the value of **default_ccache_name** from

+    configuration files (see **KRB5_CONFIG**) will be used.  If that

+    is also not set, the default *type* is ``FILE``, and the

+    *residual* is the path /tmp/krb5cc_*uid*, where *uid* is the

+    decimal user ID of the user.

 **KRB5_KTNAME**

-    Specifies the location of the keytab file, in the form

+    Specifies the location of the default keytab file, in the form

     *TYPE*:*residual*.  If no *type* is present, the **FILE** type is

-    assumed and *residual* is the pathname of the keytab file.  The

-    default keytab file is ``/etc/krb5.keytab``.

+    assumed and *residual* is the pathname of the keytab file.  If

+    unset, |keytab| will be used.

 **KRB5_CONFIG**

     Specifies the location of the Kerberos configuration file.  The

-    default is ``/etc/krb5.conf``.

+    default is |sysconfdir|\ ``/krb5.conf``.  Multiple filenames can

+    be specified, separated by a colon; all files which are present

+    will be read.

 **KRB5_KDC_PROFILE**

     Specifies the location of the KDC configuration file, which

     contains additional configuration directives for the Key

     Distribution Center daemon and associated programs.  The default

-    is ``/usr/local/var/krb5kdc/kdc.conf``.

+    is |kdcdir|\ ``/kdc.conf``.

 **KRB5RCACHETYPE**

     Specifies the default type of replay cache to use for servers.

-    Valid types include **dfl** for the normal file type and **none**

-    for no replay cache.

+    Valid types include ``dfl`` for the normal file type and ``none``

+    for no replay cache.  The default is ``dfl``.

 **KRB5RCACHEDIR**

     Specifies the default directory for replay caches used by servers.

@@ -110,7 +121,17 @@ programs.  These inclide:

 **KRB5_TRACE**

     Specifies a filename to write trace log output to.  Trace logs can

     help illuminate decisions made internally by the Kerberos

-    libraries.  The default is not to write trace log output anywhere.

+    libraries.  For example, ``env KRB5_TRACE=/dev/stderr kinit``

+    would send tracing information for :ref:`kinit(1)` to

+    ``/dev/stderr``.  The default is not to write trace log output

+    anywhere.

+

+**KRB5_CLIENT_KTNAME**

+    Default client keytab file name.  If unset, |ckeytab| will be

+    used).

+

+**KPROP_PORT**

+    :ref:`kprop(8)` port to use.  Defaults to 754.

 Most environment variables are disabled for certain programs, such as

 login system programs and setuid programs, which are designed to be

@@ -133,6 +154,7 @@ AUTHORS

 | Steve Miller, MIT Project Athena/Digital Equipment Corporation

 | Clifford Neuman, MIT Project Athena

 | Greg Hudson, MIT Kerberos Consortium

+| Robbie Harwood, Red Hat, Inc.

 HISTORY

 -------

@@ -144,5 +166,5 @@ by the MIT Kerberos Consortium.

 RESTRICTIONS

 ------------

-Copyright 1985, 1986, 1989-1996, 2002, 2011 Masachusetts Institute of

-Technology

+Copyright 1985, 1986, 1989-1996, 2002, 2011, 2018 Masachusetts

+Institute of Technology

diff --git a/src/man/kerberos.man b/src/man/kerberos.man

index 7b2b5d932..026f4604a 100644

--- a/src/man/kerberos.man

+++ b/src/man/kerberos.man

@@ -34,12 +34,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]

 .sp

 The Kerberos system authenticates individual users in a network

 environment.  After authenticating yourself to Kerberos, you can use

-Kerberos\-enabled programs without having to present passwords.

+Kerberos\-enabled programs without having to present passwords or

+certificates to those programs.

 .sp

-If you enter your username and kinit(1) responds with this

-message:

+If you receive the following response from kinit(1):

 .sp

-kinit(v5): Client not found in Kerberos database while getting initial

+kinit: Client not found in Kerberos database while getting initial

 credentials

 .sp

 you haven\(aqt been registered as a Kerberos user.  See your system

@@ -51,10 +51,13 @@ is the \fBinstance\fP, which in the case of a user is usually null.

 Some users may have privileged instances, however, such as \fBroot\fP or

 \fBadmin\fP\&.  In the case of a service, the instance is the fully

 qualified name of the machine on which it runs; i.e. there can be an

-rlogin service running on the machine ABC, which is different from the

-rlogin service running on the machine XYZ.  The third part of a

-Kerberos name is the \fBrealm\fP\&.  The realm corresponds to the Kerberos

-service providing authentication for the principal.

+ssh service running on the machine ABC (\fI\%ssh/ABC@REALM\fP), which is

+different from the ssh service running on the machine XYZ

+(\fI\%ssh/XYZ@REALM\fP).  The third part of a Kerberos name is the \fBrealm\fP\&.

+The realm corresponds to the Kerberos service providing authentication

+for the principal.  Realms are conventionally all\-uppercase, and often

+match the end of hostnames in the realm (for instance, host01.example.com

+might be in realm EXAMPLE.COM).

 .sp

 When writing a Kerberos name, the principal name is separated from the

 instance (if not null) by a slash, and the realm (if not the local

@@ -77,63 +80,71 @@ cbrown/root@FUBAR.ORG

 When you authenticate yourself with Kerberos you get an initial

 Kerberos \fBticket\fP\&.  (A Kerberos ticket is an encrypted protocol

 message that provides authentication.)  Kerberos uses this ticket for

-network utilities such as rlogin and rcp.  The ticket transactions are

-done transparently, so you don\(aqt have to worry about their management.

+network utilities such as ssh.  The ticket transactions are done

+transparently, so you don\(aqt have to worry about their management.

 .sp

-Note, however, that tickets expire.  Privileged tickets, such as those

-with the instance \fBroot\fP, expire in a few minutes, while tickets

-that carry more ordinary privileges may be good for several hours or a

-day, depending on the installation\(aqs policy.  If your login session

-extends beyond the time limit, you will have to re\-authenticate

-yourself to Kerberos to get new tickets.  Use the kinit(1)

-command to re\-authenticate yourself.

+Note, however, that tickets expire.  Administrators may configure more

+privileged tickets, such as those with service or instance of \fBroot\fP

+or \fBadmin\fP, to expire in a few minutes, while tickets that carry

+more ordinary privileges may be good for several hours or a day.  If

+your login session extends beyond the time limit, you will have to

+re\-authenticate yourself to Kerberos to get new tickets using the

+kinit(1) command.

 .sp

-If you use the kinit command to get your tickets, make sure you use

-the kdestroy command to destroy your tickets before you end your login

-session.  You should put the kdestroy command in your \fB\&.logout\fP file

-so that your tickets will be destroyed automatically when you logout.

-For more information about the kinit and kdestroy commands, see the

-kinit(1) and kdestroy(1) manual pages.

+Some tickets are \fBrenewable\fP beyond their initial lifetime.  This

+means that \fBkinit \-R\fP can extend their lifetime without requiring

+you to re\-authenticate.

+.sp

+If you wish to delete your local tickets, use the kdestroy(1)

+command.

 .sp

 Kerberos tickets can be forwarded.  In order to forward tickets, you

 must request \fBforwardable\fP tickets when you kinit.  Once you have

 forwardable tickets, most Kerberos programs have a command line option

-to forward them to the remote host.

+to forward them to the remote host.  This can be useful for, e.g.,

+running kinit on your local machine and then sshing into another to do

+work.  Note that this should not be done on untrusted machines since

+they will then have your tickets.

 .SH ENVIRONMENT VARIABLES

 .sp

 Several environment variables affect the operation of Kerberos\-enabled

-programs.  These inclide:

+programs.  These include:

 .INDENT 0.0

 .TP

 \fBKRB5CCNAME\fP

-Specifies the location of the credential cache, in the form

-\fITYPE\fP:\fIresidual\fP\&.  If no \fItype\fP prefix is present, the \fBFILE\fP

-type is assumed and \fIresidual\fP is the pathname of the cache file.

-A collection of multiple caches may be used by specifying the

-\fBdir\fP type and the pathname of a private directory (which must

-already exist).  The default cache file is /tmp/krb5cc_*uid*,

-where \fIuid\fP is the decimal user ID of the user.

+Default name for the credentials cache file, in the form

+\fITYPE\fP:\fIresidual\fP\&.  The type of the default cache may determine

+the availability of a cache collection.  \fBFILE\fP is not a

+collection type; \fBKEYRING\fP, \fBDIR\fP, and \fBKCM\fP are.

+.sp

+If not set, the value of \fBdefault_ccache_name\fP from

+configuration files (see \fBKRB5_CONFIG\fP) will be used.  If that

+is also not set, the default \fItype\fP is \fBFILE\fP, and the

+\fIresidual\fP is the path /tmp/krb5cc_*uid*, where \fIuid\fP is the

+decimal user ID of the user.

 .TP

 \fBKRB5_KTNAME\fP

-Specifies the location of the keytab file, in the form

+Specifies the location of the default keytab file, in the form

 \fITYPE\fP:\fIresidual\fP\&.  If no \fItype\fP is present, the \fBFILE\fP type is

-assumed and \fIresidual\fP is the pathname of the keytab file.  The

-default keytab file is \fB/etc/krb5.keytab\fP\&.

+assumed and \fIresidual\fP is the pathname of the keytab file.  If

+unset, \fB@KTNAME@\fP will be used.

 .TP

 \fBKRB5_CONFIG\fP

 Specifies the location of the Kerberos configuration file.  The

-default is \fB/etc/krb5.conf\fP\&.

+default is \fB@SYSCONFDIR@\fP\fB/krb5.conf\fP\&.  Multiple filenames can

+be specified, separated by a colon; all files which are present

+will be read.

 .TP

 \fBKRB5_KDC_PROFILE\fP

 Specifies the location of the KDC configuration file, which

 contains additional configuration directives for the Key

 Distribution Center daemon and associated programs.  The default

-is \fB/usr/local/var/krb5kdc/kdc.conf\fP\&.

+is \fB@LOCALSTATEDIR@\fP\fB/krb5kdc\fP\fB/kdc.conf\fP\&.

 .TP

 \fBKRB5RCACHETYPE\fP

 Specifies the default type of replay cache to use for servers.

 Valid types include \fBdfl\fP for the normal file type and \fBnone\fP

-for no replay cache.

+for no replay cache.  The default is \fBdfl\fP\&.

 .TP

 \fBKRB5RCACHEDIR\fP

 Specifies the default directory for replay caches used by servers.

@@ -143,7 +154,17 @@ or \fB/var/tmp\fP if \fBTMPDIR\fP is not set.

 \fBKRB5_TRACE\fP

 Specifies a filename to write trace log output to.  Trace logs can

 help illuminate decisions made internally by the Kerberos

-libraries.  The default is not to write trace log output anywhere.

+libraries.  For example, \fBenv KRB5_TRACE=/dev/stderr kinit\fP

+would send tracing information for kinit(1) to

+\fB/dev/stderr\fP\&.  The default is not to write trace log output

+anywhere.

+.TP

+\fBKRB5_CLIENT_KTNAME\fP

+Default client keytab file name.  If unset, \fB@CKTNAME@\fP will be

+used).

+.TP

+\fBKPROP_PORT\fP

+kprop(8) port to use.  Defaults to 754.

 .UNINDENT

 .sp

 Most environment variables are disabled for certain programs, such as

@@ -161,6 +182,7 @@ kadmind(8), kdb5_util(8), krb5kdc(8)

 Steve Miller, MIT Project Athena/Digital Equipment Corporation

 Clifford Neuman, MIT Project Athena

 Greg Hudson, MIT Kerberos Consortium

+Robbie Harwood, Red Hat, Inc.

 .fi

 .sp

 .SH HISTORY

@@ -170,8 +192,8 @@ contributions from many outside parties.  It is currently maintained

 by the MIT Kerberos Consortium.

 .SH RESTRICTIONS

 .sp

-Copyright 1985, 1986, 1989\-1996, 2002, 2011 Masachusetts Institute of

-Technology

+Copyright 1985, 1986, 1989\-1996, 2002, 2011, 2018 Masachusetts

+Institute of Technology

 .SH AUTHOR

 MIT

 .SH COPYRIGHT