krb5 commit [krb5-1.16]: Modernize kerberos(7)
Greg Hudson
ghudson at mit.edu
Tue Oct 30 12:26:04 EDT 2018
https://github.com/krb5/krb5/commit/ba3a85dc131e729706bf04c85c6210258e4ac09f
commit ba3a85dc131e729706bf04c85c6210258e4ac09f
Author: Robbie Harwood <rharwood at redhat.com>
Date: Mon Oct 15 13:20:30 2018 -0400
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.
(cherry picked from commit cdccdefa2d74d3abf5a8ae126e423af9d467d34f)
ticket: 8755
version_fixed: 1.16.2
doc/admin/env_variables.rst | 44 +--------------
doc/user/user_config/kerberos.rst | 110 ++++++++++++++++++++++---------------
src/man/kerberos.man | 108 ++++++++++++++++++++++--------------
3 files changed, 132 insertions(+), 130 deletions(-)
diff --git a/doc/admin/env_variables.rst b/doc/admin/env_variables.rst
index 0c146d3..a2d15be 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 6c4453b..56412f0 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 at REALM), which is
+different from the ssh service running on the machine XYZ
+(ssh/XYZ at 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.
-
-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.
-
-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.
+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. 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.
+
+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 7b2b5d9..026f460 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 at REALM\fP), which is
+different from the ssh service running on the machine XYZ
+(\fI\%ssh/XYZ at 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 at 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.
-.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.
-.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.
+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. 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
+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 at 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 at 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 at 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 at 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
More information about the cvs-krb5
mailing list