From 30e55883bd4822d4d3af061d646e7b1044880d52 Mon Sep 17 00:00:00 2001

From: Florence Blanc-Renaud <flo@redhat.com>

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 <abokovoy@redhat.com>

---

 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