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

4 files changed, 133 insertions, 14 deletions

diff --git a/src/man/Makefile.in b/src/man/Makefile.in
index 5df02a0d28..e439f56c4b 100644
--- 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
index 0000000000..8af572af16
--- /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
index 0000000000..677fa5889c
--- /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 ca00b9b0a0..76aba1adde 100644
--- 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)