Add shadow manpages for k5login.5 and k5identity.5

Add shadow manpages dot.k5login and dot.k5identity for k5login.5 and
k5identity.5.  Stop generating .k5login.5 and .k5identity.5 from
sphinx (these will be taken care of by make install in src/man).  Add
generated k5identity.5.

Add SYNOPSIS sections to k5login.5 and k5identity.5 to make it more
clear that the filenames start with a dot.

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25653 dc483132-0cff-0310-8789-dd5450dbe970

diff --git a/doc/Makefile b/doc/Makefile
index abe953423f25efcda5eb85b2925e2ca337801cf2..0b8cd45d7176340679822a303f3c9882c8dcd327 100644 (file)
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -158,9 +158,10 @@ tgz::
 ../NOTICE: notice.texinfo definitions.texinfo copyright.texinfo
        makeinfo --plaintext -o $@ notice.texinfo
 
-RSTMAN=k5login.5 k5srvutil.1 kadmin.1 kadmind.8 kdb5_ldap_util.8 kdb5_util.8 \
-       kdc.conf.5 kdestroy.1 kinit.1 klist.1 kpasswd.1 kprop.8 kpropd.8 \
-       kproplog.8 krb5.conf.5 krb5kdc.8 ksu.1 kswitch.1 ktutil.1 kvno.1
+RSTMAN=k5identity.5 k5login.5 k5srvutil.1 kadmin.1 kadmind.8 kdb5_ldap_util.8 \
+       kdb5_util.8 kdc.conf.5 kdestroy.1 kinit.1 klist.1 kpasswd.1 kprop.8 \
+       kpropd.8 kproplog.8 krb5.conf.5 krb5kdc.8 ksu.1 kswitch.1 ktutil.1 \
+       kvno.1
 
 # The file editing loop deletes some trailing whitespace that the
 # docutils manpage writer outputs near the end of its output files.

diff --git a/doc/rst_source/conf.py b/doc/rst_source/conf.py
index 802c4e8734995390df7ccbba51fc960dc3b8dacd..4fc17142059f8a99618f1e24b7c2ac49f0019e89 100644 (file)
--- a/doc/rst_source/conf.py
+++ b/doc/rst_source/conf.py
@@ -225,10 +225,8 @@ man_pages = [
     ('krb_users/user_commands/kpasswd', 'kpasswd', u'change a user\'s Kerberos password', [u'MIT'], 1),
     ('krb_users/user_commands/kvno', 'kvno', u'print key version numbers of Kerberos principals', [u'MIT'], 1),
     ('krb_users/user_commands/ksu', 'ksu', u'Kerberized super-user', [u'MIT'], 1),
-    ('krb_users/user_commands/k5login', '.k5login', u'', [u'MIT'], 5),
-    ('krb_users/user_commands/k5login', 'k5login', u'.k5login - Kerberos V5 acl file for host access', [u'MIT'], 5),
-    ('krb_users/user_commands/k5identity', '.k5identity', u'', [u'MIT'], 5),
-    ('krb_users/user_commands/k5identity', 'k5identity', u'.k5identity - Kerberos V5 client principal selection rules', [u'MIT'], 5),
+    ('krb_users/user_commands/k5login', 'k5login', u'Kerberos V5 acl file for host access', [u'MIT'], 5),
+    ('krb_users/user_commands/k5identity', 'k5identity', u'Kerberos V5 client principal selection rules', [u'MIT'], 5),
     ('krb_admins/admin_commands/krb5kdc', 'krb5kdc', u'Kerberos V5 KDC', [u'MIT'], 8),
     ('krb_admins/admin_commands/kadmin_local', 'kadmin', u'Kerberos V5 database administration program', [u'MIT'], 1),
     ('krb_admins/admin_commands/kprop', 'kprop', u'propagate a Kerberos V5 principal database to a slave server', [u'MIT'], 8),

diff --git a/doc/rst_source/krb_users/user_commands/k5identity.rst b/doc/rst_source/krb_users/user_commands/k5identity.rst
index f6cdda352d1437e12aea499862ebdbc0d7048915..a1d030b59c5d7c0d87e1f811cde5f65007017dfa 100644 (file)
--- a/doc/rst_source/krb_users/user_commands/k5identity.rst
+++ b/doc/rst_source/krb_users/user_commands/k5identity.rst
@@ -1,5 +1,9 @@
-.k5identity - Kerberos V5 client principal selection rules
-===============================================================
+Kerberos V5 client principal selection rules
+============================================
+
+SYNOPSIS
+--------
+**~/.k5identity**
 
 DESCRIPTION
 -------------

diff --git a/doc/rst_source/krb_users/user_commands/k5login.rst b/doc/rst_source/krb_users/user_commands/k5login.rst
index 4e4764443163155fb683a7aa212d6fa1cfe21853..9cfeb2ba8c4cdaa6443ce34110ef6b54d2a7d657 100644 (file)
--- a/doc/rst_source/krb_users/user_commands/k5login.rst
+++ b/doc/rst_source/krb_users/user_commands/k5login.rst
@@ -1,5 +1,9 @@
-.k5login - Kerberos V5 acl file for host access
-===================================================
+Kerberos V5 acl file for host access
+====================================
+
+SYNOPSIS
+--------
+**~/.k5login**
 
 DESCRIPTION
 --------------

diff --git a/src/man/Makefile.in b/src/man/Makefile.in
index 5df02a0d287dbe6b171fcb0c1d0aa420404a7fa2..e439f56c4b53f86e68199bae15a783b656388377 100644 (file)
--- a/src/man/Makefile.in
+++ b/src/man/Makefile.in
@@ -23,6 +23,8 @@ install-clientman::
        $(INSTALL_DATA) $(srcdir)/kvno.1 ${DESTDIR}$(CLIENT_MANDIR)/kvno.1
 
 install-fileman::
+       $(INSTALL_DATA) $(srcdir)/dot.k5identity.5 ${DESTDIR}$(FILE_MANDIR)/.k5identity.5
+       $(INSTALL_DATA) $(srcdir)/k5identity.5 ${DESTDIR}$(FILE_MANDIR)/k5identity.5
        $(INSTALL_DATA) $(srcdir)/dot.k5login.5 ${DESTDIR}$(FILE_MANDIR)/.k5login.5
        $(INSTALL_DATA) $(srcdir)/k5login.5 ${DESTDIR}$(FILE_MANDIR)/k5login.5
        $(INSTALL_DATA) $(srcdir)/kdc.conf.5 ${DESTDIR}$(FILE_MANDIR)/kdc.conf.5
@@ -53,6 +55,9 @@ install-clientcat::
        $(GROFF_MAN) $(srcdir)/kvno.1 > ${DESTDIR}$(CLIENT_CATDIR)/kvno.1
 
 install-filecat::
+       $(GROFF_MAN) $(srcdir)/k5identity.5 > ${DESTDIR}$(FILE_CATDIR)/k5identity.5
+       ($(RM) ${DESTDIR}$(FILE_CATDIR)/.k5identity.5; \
+               $(LN_S) $(FILE_CATDIR)/k5identity.5 ${DESTDIR}$(FILE_CATDIR)/.k5identity.5)
        $(GROFF_MAN) $(srcdir)/k5login.5 > ${DESTDIR}$(FILE_CATDIR)/k5login.5
        ($(RM) ${DESTDIR}$(FILE_CATDIR)/.k5login.5; \
                $(LN_S) $(FILE_CATDIR)/k5login.5 ${DESTDIR}$(FILE_CATDIR)/.k5login.5)

diff --git a/src/man/dot.k5identity.5 b/src/man/dot.k5identity.5
new file mode 100644 (file)
index 0000000..8af572a
--- /dev/null
+++ b/src/man/dot.k5identity.5
@@ -0,0 +1 @@
+.so man5/k5identity.5

diff --git a/src/man/k5identity.5 b/src/man/k5identity.5
new file mode 100644 (file)
index 0000000..677fa58
--- /dev/null
+++ b/src/man/k5identity.5
@@ -0,0 +1,103 @@
+.TH "K5IDENTITY" "5" "January 13, 2012" "0.0.1" "MIT Kerberos"
+.SH NAME
+k5identity \- Kerberos V5 client principal selection rules
+.
+.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
+..
+.\" Man page generated from reStructeredText.
+.
+.SH SYNOPSIS
+.sp
+\fB~/.k5identity\fP
+.SH DESCRIPTION
+.sp
+The \fI.k5identity\fP  file, which resides in a user\(aqs home directory,
+contains a list of rules for selecting a client principals based on
+the server being accessed. These rules are used to choose a credential
+cache within the cache collection when possible.
+.sp
+Blank lines and lines beginning with \(aq#\(aq are ignored.  Each line has the form:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+principal field=value ...
+.UNINDENT
+.UNINDENT
+.sp
+If the server principal meets all of the field constraints, then principal
+is chosen as the client principal.  The following fields are recognized:
+.INDENT 0.0
+.TP
+.B \fBrealm\fP
+.sp
+If the realm of the server principal is known, it is matched
+against \fIvalue\fP, which may be a pattern using shell wildcards.
+For host\-based server principals, the realm will generally only
+be known if there is a \fIdomain_realm\fP section
+in \fIkrb5.conf\fP with a mapping for the hostname.
+.TP
+.B \fBservice\fP
+.sp
+If the server principal is a host\-based principal,
+its service component is matched against \fIvalue\fP, which may be
+a pattern using shell wildcards.
+.TP
+.B \fBhost\fP
+.sp
+If the server principal is a host\-based principal,
+its hostname component is converted to lower case and matched
+against \fIvalue\fP, which may be a pattern using shell wildcards.
+.sp
+If  the server principal matches the constraints of multiple lines
+in the .k5identity file, the principal from the first matching line is used.
+If no line  matches, credentials will be selected some other way,
+such as the realm heuristic or the current primary cache.
+.UNINDENT
+.SH EXAMPLE
+.sp
+The following example .k5identity file selects the client principal
+alice@KRBTEST.COM if the server principal is within that realm,
+the principal alice/root@EXAMPLE.COM if the server host is within
+a servers subdomain, and the principal alice/mail@EXAMPLE.COM
+when accessing the IMAP service on mail.example.com:
+.sp
+.nf
+.ft C
+alice@KRBTEST.COM       realm=KRBTEST.COM
+alice/root@EXAMPLE.COM  host=*.servers.example.com
+alice/mail@EXAMPLE.COM  host=mail.example.com service=imap
+.ft P
+.fi
+.SH SEE ALSO
+.sp
+kerberos(1), krb5.conf(5)
+.SH AUTHOR
+MIT
+.SH COPYRIGHT
+2011, MIT
+.\" Generated by docutils manpage writer.
+.

diff --git a/src/man/k5login.5 b/src/man/k5login.5
index ca00b9b0a0a3d06852a42f1ef65fcd3bd0bde05b..76aba1adde63323158e48ae795d95bef541105e1 100644 (file)
--- a/src/man/k5login.5
+++ b/src/man/k5login.5
@@ -1,4 +1,4 @@
-.TH "K5LOGIN" "5" "January 06, 2012" "0.0.1" "MIT Kerberos"
+.TH "K5LOGIN" "5" "January 13, 2012" "0.0.1" "MIT Kerberos"
 .SH NAME
 k5login \- Kerberos V5 acl file for host access
 .
@@ -30,26 +30,34 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .\" Man page generated from reStructeredText.
 .
+.SH SYNOPSIS
+.sp
+\fB~/.k5login\fP
 .SH DESCRIPTION
 .sp
-The \fI.k5login\fP file, which resides in a user\(aqs home directory, contains a list of the Kerberos principals.
-Anyone with valid tickets for a principal in the file is allowed host access with the UID of the user in whose home directory the file resides.
-One common use is to place a \fI.k5login\fP file in root\(aqs home directory, thereby granting system administrators remote root access to the host via Kerberos.
+The \fI.k5login\fP file, which resides in a user\(aqs home directory,
+contains a list of the Kerberos principals.
+Anyone with valid tickets for a principal in the file is allowed host access
+with the UID of the user in whose home directory the file resides.
+One common use is to place a \fI.k5login\fP file in root\(aqs home directory,
+thereby granting system administrators remote root access to the host via Kerberos.
 .SH EXAMPLES
 .sp
-Suppose the user "alice" had a \fI.k5login\fP file in her home directory containing the following line:
+Suppose the user \fIalice\fP had a \fI.k5login\fP file in her home directory containing the following line:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-bob@FUBAR.ORG
+bob@FOOBAR.ORG
 .UNINDENT
 .UNINDENT
 .sp
-This  would  allow  "bob"  to use any of the Kerberos network applications, such as telnet(1), rlogin(1), rsh(1), and rcp(1),
-to access alice\(aqs account, using bob\(aqs Kerberos tickets.
+This would allow \fIbob\fP to use any of the Kerberos network applications,
+such as telnet(1), rlogin(1), rsh(1), and rcp(1),
+to access \fIalice\fP\(aqs account, using \fIbob\fP\(aqs Kerberos tickets.
 .sp
-Let us further suppose that "alice" is a system administrator.
-Alice and the other system administrators would have  their  principals in root\(aqs \fI.k5login\fP file on each host:
+Let us further suppose that \fIalice\fP is a system administrator.
+Alice and the other system administrators would have their principals
+in root\(aqs \fI.k5login\fP file on each host:
 .INDENT 0.0
 .INDENT 3.5
 .sp
@@ -59,10 +67,12 @@ joeadmin/root@BLEEP.COM
 .UNINDENT
 .UNINDENT
 .sp
-This  would  allow either system administrator to log in to these hosts using their Kerberos tickets instead of having to type the root password.
-Note that because "bob" retains the Kerberos tickets for his own principal, "bob@FUBAR.ORG",
-he would not have  any  of  the privileges that require alice\(aqs tickets, such as root access to any of the site\(aqs hosts,
-or the ability to change alice\(aqs password.
+This would allow either system administrator to log in to these hosts
+using their Kerberos tickets instead of having to type the root password.
+Note that because \fIbob\fP retains the Kerberos tickets for his own principal,
+"bob@FOOBAR.ORG", he would not have any of the privileges that require \fIalice\fP\(aqs tickets,
+such as root access to any of the site\(aqs hosts,
+or the ability to change \fIalice\fP\(aqs password.
 .SH SEE ALSO
 .sp
 telnet(1), rlogin(1), rsh(1), rcp(1), ksu(1), telnetd(8), klogind(8)