From 3caf0f9645b12679751689633ea3596a88701fbe Mon Sep 17 00:00:00 2001 From: Tom Yu Date: Fri, 13 Jan 2012 20:47:26 +0000 Subject: [PATCH] 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 --- doc/Makefile | 7 +- doc/rst_source/conf.py | 6 +- .../krb_users/user_commands/k5identity.rst | 8 +- .../krb_users/user_commands/k5login.rst | 8 +- src/man/Makefile.in | 5 + src/man/dot.k5identity.5 | 1 + src/man/k5identity.5 | 103 ++++++++++++++++++ src/man/k5login.5 | 38 ++++--- 8 files changed, 151 insertions(+), 25 deletions(-) create mode 100644 src/man/dot.k5identity.5 create mode 100644 src/man/k5identity.5 diff --git a/doc/Makefile b/doc/Makefile index abe953423..0b8cd45d7 100644 --- 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 802c4e873..4fc171420 100644 --- 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 f6cdda352..a1d030b59 100644 --- 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 4e4764443..9cfeb2ba8 100644 --- 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 5df02a0d2..e439f56c4 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 000000000..8af572af1 --- /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 000000000..677fa5889 --- /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 ca00b9b0a..76aba1add 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) -- 2.26.2