krb5 commit: Modernize kerberos(7)
Greg Hudson
ghudson at mit.edu
Wed Oct 24 11:53:20 EDT 2018
https://github.com/krb5/krb5/commit/cdccdefa2d74d3abf5a8ae126e423af9d467d34f
commit cdccdefa2d74d3abf5a8ae126e423af9d467d34f
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.
ticket: 8755
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