From df8c8cc7cd18fa94c920c4763545b6fd93a21fcd Mon Sep 17 00:00:00 2001

From: Robbie Harwood <rharwood@redhat.com>

Date: Tue, 9 Oct 2018 17:05:10 -0400

Subject: [PATCH] Bring back general kerberos man page

Restore the content of kerberos(1) as it stood in

0f81e372a2830c9170f6e08dfa956841d0ebdfb1.  Convert to ReST to match

the other man pages, and install it as the more appropriate

kerberos(7).

Build kerberos(7) and check it in to avoid breaking the build.

ticket: 8755 (new)

tags: pullup

target_version: 1.16-next

(cherry picked from commit c38197ee9808503f86ccffd4a2bd94389e17df0b)

---

 doc/conf.py                       |   1 +

 doc/user/user_config/index.rst    |   1 +

 doc/user/user_config/kerberos.rst | 148 ++++++++++++++++++++++++

 src/Makefile.in                   |   4 +-

 src/config/pre.in                 |   2 +

 src/man/Makefile.in               |  14 ++-

 src/man/kerberos.man              | 180 ++++++++++++++++++++++++++++++

 7 files changed, 345 insertions(+), 5 deletions(-)

 create mode 100644 doc/user/user_config/kerberos.rst

 create mode 100644 src/man/kerberos.man

diff --git a/doc/conf.py b/doc/conf.py

index 3ee2df630..68dad781f 100644

--- a/doc/conf.py

+++ b/doc/conf.py

@@ -292,6 +292,7 @@ man_pages = [

     ('user/user_commands/krb5-config', 'krb5-config', u'tool for linking against MIT Kerberos libraries', [u'MIT'], 1),

     ('user/user_config/k5login', 'k5login', u'Kerberos V5 acl file for host access', [u'MIT'], 5),

     ('user/user_config/k5identity', 'k5identity', u'Kerberos V5 client principal selection rules', [u'MIT'], 5),

+    ('user/user_config/kerberos', 'kerberos', u'Overview of using Kerberos', [u'MIT'], 7),

     ('admin/admin_commands/krb5kdc', 'krb5kdc', u'Kerberos V5 KDC', [u'MIT'], 8),

     ('admin/admin_commands/kadmin_local', 'kadmin', u'Kerberos V5 database administration program', [u'MIT'], 1),

     ('admin/admin_commands/kprop', 'kprop', u'propagate a Kerberos V5 principal database to a slave server', [u'MIT'], 8),

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

index 6b3d4393b..ad0dc1a72 100644

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

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

@@ -8,5 +8,6 @@ been disabled by your host's configuration):

 .. toctree::

    :maxdepth: 1

+   kerberos.rst

    k5login.rst

    k5identity.rst

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

new file mode 100644

index 000000000..6c4453b3b

--- /dev/null

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

@@ -0,0 +1,148 @@

+.. _kerberos(7):

+

+kerberos

+========

+

+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.

+

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

+message:

+

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

+credentials

+

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

+administrator.

+

+A Kerberos name usually contains three parts.  The first is the

+**primary**, which is usually a user's or service's name.  The second

+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.

+

+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

+realm) follows, preceded by an "@" sign.  The following are examples

+of valid Kerberos names::

+

+    david

+    jennifer/admin

+    joeuser@BLEEP.COM

+    cbrown/root@FUBAR.ORG

+

+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.

+

+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.

+

+ENVIRONMENT VARIABLES

+---------------------

+

+Several environment variables affect the operation of Kerberos-enabled

+programs.  These inclide:

+

+**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.

+

+**KRB5_KTNAME**

+    Specifies the location of the 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``.

+

+**KRB5_CONFIG**

+    Specifies the location of the Kerberos configuration file.  The

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

+

+**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``.

+

+**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.

+

+**KRB5RCACHEDIR**

+    Specifies the default directory for replay caches used by servers.

+    The default is the value of the **TMPDIR** environment variable,

+    or ``/var/tmp`` if **TMPDIR** is not set.

+

+**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.

+

+Most environment variables are disabled for certain programs, such as

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

+secure when run within an untrusted process environment.

+

+SEE ALSO

+--------

+

+:ref:`kdestroy(1)`, :ref:`kinit(1)`, :ref:`klist(1)`,

+:ref:`kswitch(1)`, :ref:`kpasswd(1)`, :ref:`ksu(1)`,

+:ref:`krb5.conf(5)`, :ref:`kdc.conf(5)`, :ref:`kadmin(1)`,

+:ref:`kadmind(8)`, :ref:`kdb5_util(8)`, :ref:`krb5kdc(8)`

+

+BUGS

+----

+

+AUTHORS

+-------

+

+| Steve Miller, MIT Project Athena/Digital Equipment Corporation

+| Clifford Neuman, MIT Project Athena

+| Greg Hudson, MIT Kerberos Consortium

+

+HISTORY

+-------

+

+The MIT Kerberos 5 implementation was developed at MIT, with

+contributions from many outside parties.  It is currently maintained

+by the MIT Kerberos Consortium.

+

+RESTRICTIONS

+------------

+

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

+Technology

diff --git a/src/Makefile.in b/src/Makefile.in

index e47bddcb1..91032361f 100644

--- a/src/Makefile.in

+++ b/src/Makefile.in

@@ -60,9 +60,9 @@ world:

 INSTALLMKDIRS = $(KRB5ROOT) $(KRB5MANROOT) $(KRB5OTHERMKDIRS) \

 		$(ADMIN_BINDIR) $(SERVER_BINDIR) $(CLIENT_BINDIR) \

 		$(ADMIN_MANDIR) $(SERVER_MANDIR) $(CLIENT_MANDIR) \

-		$(FILE_MANDIR) \

+		$(FILE_MANDIR) $(OVERVIEW_MANDIR) \

 		$(ADMIN_CATDIR) $(SERVER_CATDIR) $(CLIENT_CATDIR) \

-		$(FILE_CATDIR) \

+		$(FILE_CATDIR) $(OVERVIEW_CATDIR) \

 		$(KRB5_LIBDIR) $(KRB5_INCDIR) \

 		$(KRB5_DB_MODULE_DIR) $(KRB5_PA_MODULE_DIR) \

 		$(KRB5_AD_MODULE_DIR) \

diff --git a/src/config/pre.in b/src/config/pre.in

index f23c07d9d..a851c56c7 100644

--- a/src/config/pre.in

+++ b/src/config/pre.in

@@ -210,6 +210,8 @@ ADMIN_CATDIR = $(KRB5MANROOT)/cat8

 SERVER_CATDIR = $(KRB5MANROOT)/cat8

 CLIENT_CATDIR = $(KRB5MANROOT)/cat1

 FILE_CATDIR = $(KRB5MANROOT)/cat5

+OVERVIEW_MANDIR = $(KRB5MANROOT)/man7

+OVERVIEW_CATDIR = $(KRB5MANROOT)/cat7

 KRB5_LIBDIR = @libdir@

 KRB5_INCDIR = @includedir@

 MODULE_DIR = @libdir@/krb5/plugins

diff --git a/src/man/Makefile.in b/src/man/Makefile.in

index 4bc670bad..e3722b1cd 100644

--- a/src/man/Makefile.in

+++ b/src/man/Makefile.in

@@ -15,7 +15,7 @@ MANSUBS=k5identity.sub k5login.sub k5srvutil.sub kadm5.acl.sub kadmin.sub \

 	kadmind.sub kdb5_ldap_util.sub kdb5_util.sub kdc.conf.sub \

 	kdestroy.sub kinit.sub klist.sub kpasswd.sub kprop.sub kpropd.sub \

 	kproplog.sub krb5.conf.sub krb5-config.sub krb5kdc.sub ksu.sub \

-	kswitch.sub ktutil.sub kvno.sub sclient.sub sserver.sub

+	kswitch.sub ktutil.sub kvno.sub sclient.sub sserver.sub kerberos.sub

 docsrc=$(top_srcdir)/../doc

@@ -56,9 +56,11 @@ all: $(MANSUBS)

 clean:

 	rm -rf $(MANSUBS) rst_man

-install: install-clientman install-fileman install-adminman install-serverman

+install: install-clientman install-fileman install-adminman \

+	install-overviewman install-serverman

-install-catman: install-clientcat install-filecat install-admincat install-servercat

+install-catman: install-clientcat install-filecat install-admincat \

+	install-overviewcat install-servercat

 install-clientman:

 	$(INSTALL_DATA) k5srvutil.sub $(DESTDIR)$(CLIENT_MANDIR)/k5srvutil.1

@@ -85,6 +87,9 @@ install-fileman:

 	$(INSTALL_DATA) kdc.conf.sub $(DESTDIR)$(FILE_MANDIR)/kdc.conf.5

 	$(INSTALL_DATA) krb5.conf.sub $(DESTDIR)$(FILE_MANDIR)/krb5.conf.5

+install-overviewman:

+	$(INSTALL_DATA) kerberos.sub $(DESTDIR)$(OVERVIEW_MANDIR)/kerberos.7

+

 install-adminman:

 	$(INSTALL_DATA) $(srcdir)/kadmin.local.8 \

 		$(DESTDIR)$(ADMIN_MANDIR)/kadmin.local.8

@@ -127,6 +132,9 @@ install-filecat:

 	$(GROFF_MAN) kdc.conf.sub > $(DESTDIR)$(FILE_CATDIR)/kdc.conf.5

 	$(GROFF_MAN) krb5.conf.sub > $(DESTDIR)$(FILE_CATDIR)/krb5.conf.5

+install-overviewcat:

+	$(GROFF_MAN) kerberos.sub > $(DESTDIR)$(OVERVIEW_CATDIR)/kerberos.7

+

 install-admincat:

 	($(RM) $(DESTDIR)$(ADMIN_CATDIR)/kadmin.local.8; \

 		$(LN_S) $(CLIENT_CATDIR)/kadmin.1 \

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

new file mode 100644

index 000000000..7b2b5d932

--- /dev/null

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

@@ -0,0 +1,180 @@

+.\" Man page generated from reStructuredText.

+.

+.TH "KERBEROS" "7" " " "1.17" "MIT Kerberos"

+.SH NAME

+kerberos \- Overview of using Kerberos

+.

+.nr rst2man-indent-level 0

+.

+.de1 rstReportMargin

+\\$1 \\n[an-margin]

+level \\n[rst2man-indent-level]

+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]

+-

+\\n[rst2man-indent0]

+\\n[rst2man-indent1]

+\\n[rst2man-indent2]

+..

+.de1 INDENT

+.\" .rstReportMargin pre:

+. RS \\$1

+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]

+. nr rst2man-indent-level +1

+.\" .rstReportMargin post:

+..

+.de UNINDENT

+. RE

+.\" indent \\n[an-margin]

+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]

+.nr rst2man-indent-level -1

+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]

+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u

+..

+.SH DESCRIPTION

+.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.

+.sp

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

+message:

+.sp

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

+credentials

+.sp

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

+administrator.

+.sp

+A Kerberos name usually contains three parts.  The first is the

+\fBprimary\fP, which is usually a user\(aqs or service\(aqs name.  The second

+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.

+.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

+realm) follows, preceded by an "@" sign.  The following are examples

+of valid Kerberos names:

+.INDENT 0.0

+.INDENT 3.5

+.sp

+.nf

+.ft C

+david

+jennifer/admin

+joeuser@BLEEP.COM

+cbrown/root@FUBAR.ORG

+.ft P

+.fi

+.UNINDENT

+.UNINDENT

+.sp

+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.

+.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.

+.SH ENVIRONMENT VARIABLES

+.sp

+Several environment variables affect the operation of Kerberos\-enabled

+programs.  These inclide:

+.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.

+.TP

+\fBKRB5_KTNAME\fP

+Specifies the location of the 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\&.

+.TP

+\fBKRB5_CONFIG\fP

+Specifies the location of the Kerberos configuration file.  The

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

+.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\&.

+.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.

+.TP

+\fBKRB5RCACHEDIR\fP

+Specifies the default directory for replay caches used by servers.

+The default is the value of the \fBTMPDIR\fP environment variable,

+or \fB/var/tmp\fP if \fBTMPDIR\fP is not set.

+.TP

+\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.

+.UNINDENT

+.sp

+Most environment variables are disabled for certain programs, such as

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

+secure when run within an untrusted process environment.

+.SH SEE ALSO

+.sp

+kdestroy(1), kinit(1), klist(1),

+kswitch(1), kpasswd(1), ksu(1),

+krb5.conf(5), kdc.conf(5), kadmin(1),

+kadmind(8), kdb5_util(8), krb5kdc(8)

+.SH BUGS

+.SH AUTHORS

+.nf

+Steve Miller, MIT Project Athena/Digital Equipment Corporation

+Clifford Neuman, MIT Project Athena

+Greg Hudson, MIT Kerberos Consortium

+.fi

+.sp

+.SH HISTORY

+.sp

+The MIT Kerberos 5 implementation was developed at MIT, with

+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

+.SH AUTHOR

+MIT

+.SH COPYRIGHT

+1985-2018, MIT

+.\" Generated by docutils manpage writer.

+.