From 30e55883bd4822d4d3af061d646e7b1044880d52 Mon Sep 17 00:00:00 2001 From: Florence Blanc-Renaud Date: Tue, 7 Nov 2017 09:31:19 +0100 Subject: [PATCH] ipa-getkeytab man page: add more details about the -r option The man page does not provide enough information about replicated environments and the use of the -r option. This fix adds an example how to use the same keytab on 2 different hosts, and points to ipa {service/host}-allow-retrieve-keytab. Fixes: https://pagure.io/freeipa/issue/7237 Reviewed-By: Alexander Bokovoy --- client/man/ipa-getkeytab.1 | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/client/man/ipa-getkeytab.1 b/client/man/ipa-getkeytab.1 index 08f6ec40d362b88a974e6ec735ed37c271e01882..39ff0d5da85b5a641328a512feeb06bc9c1ab9d7 100644 --- a/client/man/ipa-getkeytab.1 +++ b/client/man/ipa-getkeytab.1 @@ -44,10 +44,15 @@ provided, so the principal name is just the service name and hostname (ldap/foo.example.com from the example above). +ipa-getkeytab is used during IPA client enrollment to retrieve a host service principal and store it in /etc/krb5.keytab. It is possible to retrieve the keytab without Kerberos credentials if the host was pre\-created with a one\-time password. The keytab can be retrieved by binding as the host and authenticating with this one\-time password. The \fB\-D|\-\-binddn\fR and \fB\-w|\-\-bindpw\fR options are used for this authentication. + \fBWARNING:\fR retrieving the keytab resets the secret for the Kerberos principal. This renders all other keytabs for that principal invalid. +When multiple hosts or services need to share the same key (for instance in high availability or load balancing clusters), the \fB\-r\fR option must be used to retrieve the existing key instead of generating a new one (please refer to the EXAMPLES section). + +Note that the user or host calling \fBipa-getkeytab\fR needs to be allowed to generate the key with \fBipa host\-allow\-create\-keytab\fR or \fBipa service\-allow\-create\-keytab\fR, +and the user or host calling \fBipa-getkeytab \-r\fR needs to be allowed to retrieve the keytab for the host or service with \fBipa host\-allow\-retrieve\-keytab\fR or \fBipa service\-allow\-retrieve\-keytab\fR. -This is used during IPA client enrollment to retrieve a host service principal and store it in /etc/krb5.keytab. It is possible to retrieve the keytab without Kerberos credentials if the host was pre\-created with a one\-time password. The keytab can be retrieved by binding as the host and authenticating with this one\-time password. The \fB\-D|\-\-binddn\fR and \fB\-w|\-\-bindpw\fR options are used for this authentication. .SH "OPTIONS" .TP \fB\-p principal\-name\fR @@ -118,16 +123,44 @@ keytab must have access to the keys for this operation to succeed. Add and retrieve a keytab for the NFS service principal on the host foo.example.com and save it in the file /tmp/nfs.keytab and retrieve just the des\-cbc\-crc key. +.nf # ipa\-getkeytab \-p nfs/foo.example.com \-k /tmp/nfs.keytab \-e des\-cbc\-crc +.fi Add and retrieve a keytab for the ldap service principal on the host foo.example.com and save it in the file /tmp/ldap.keytab. +.nf # ipa\-getkeytab \-s ipaserver.example.com \-p ldap/foo.example.com \-k /tmp/ldap.keytab +.fi Retrieve a keytab using LDAP credentials (this will typically be done by \fBipa\-join(1)\fR when enrolling a client using the \fBipa\-client\-install(1)\fR command: +.nf # ipa\-getkeytab \-s ipaserver.example.com \-p host/foo.example.com \-k /etc/krb5.keytab \-D fqdn=foo.example.com,cn=computers,cn=accounts,dc=example,dc=com \-w password +.fi + +Add and retrieve a keytab for a clustered HTTP service deployed on client1.example.com and client2.example.com (already enrolled), using the client-frontend.example.com host name: + +.nf + # ipa host-add client-frontend.example.com --ip-address 10.1.2.3 + # ipa service-add HTTP/client-frontend.example.com + # ipa service-allow-retrieve-keytab HTTP/client-frontend.example.com --hosts={client1.example.com,client2.example.com} + # ipa server-allow-create-keytab HTTP/client-frontend.example.com --hosts=client1.example.com +.fi + + On client1, generate and retrieve a new keytab for client-frontend.example.com: +.nf + # kinit -k + # ipa-getkeytab -p HTTP/client-frontend.example.com -k /tmp/http.keytab + +.fi + On client2, retrieve the existing keytab for client-frontend.example.com: +.nf + # kinit -k + # ipa-getkeytab -r -p HTTP/client-frontend.example.com -k /tmp/http.keytab +.fi + .SH "EXIT STATUS" The exit status is 0 on success, nonzero on error. -- 2.13.6