From 2319336ac1f52e56d2549bd83ff40a3e7b2f281a Mon Sep 17 00:00:00 2001 From: Robbie Harwood 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