ipa-join(1)

💖 ipa-join(1) — the manual page, but make it a group chat 💖

okay bestie, sit down, we're learning ipa-join today and honestly? it's giving main character energy. this is from the IPA Manual Pages and it's literally about joining a machine to an IPA realm and grabbing a keytab for the host service principal. no cap. 🦋

✨ NAME ✨

ipa-join — join a machine to an IPA realm and get a keytab for the host service principal 🎀

✨ SYNOPSIS ✨

ipa-join [-d|--debug] [-q|--quiet] [-u|--unenroll] [-h|--hostname
hostname] [-s|--server hostname] [-k|--keytab filename] [-w|--bindpw
password] [-b|--basedn basedn] [-?|--help] [--usage]

✨ DESCRIPTION ✨

so basically 💅 — this joins a host to an IPA realm and retrieves a kerberos keytab for the host service principal, or it unenrolls an already-enrolled host from an IPA server. both. she does both.

kerberos keytabs are used by services (like sshd, iconic behavior) to perform kerberos authentication. a keytab is a file with one or more secrets (or keys) for a kerberos principal. that's it. that's the whole vibe.

the ipa-join command will create and retrieve a service principal for host/foo.example.com@EXAMPLE.COM and place it by default into /etc/krb5.keytab. where it lands can be overridden with the -k option, because we love options. 🌸

the IPA server to contact is set in /etc/ipa/default.conf by default and can be overridden using the -s,--server option.

now. in order to join, the machine needs to be authenticated. this can happen in one of two ways:

• Authenticate using the current kerberos principal
• Provide a password to authenticate with

if a client host has already been joined to the IPA realm, the ipa-join command will fail. 😭 the host will need to be removed from the server using ipa host-del FQDN in order to join the client to the realm. that's the rule, bestie.

this command is normally executed by the ipa-client-install command as part of the enrollment process. it's not out here freelancing, she's on a team. 👑

the reverse is unenrollment. unenrolling a host removes the Kerberos key on the IPA server. this prepares the host to be re-enrolled. this uses the host principal stored in /etc/krb5.conf to authenticate to the IPA server to perform the unenrollment.

PLEASE NOTE 🙈 — while the ipa-join option removes the client from the domain, it does not actually uninstall the client or properly remove all of the IPA-related configuration. the only way to uninstall a client completely is to use ipa-client-install --uninstall (see ipa-client-install(1)). so don't be out here thinking she cleaned up. she did not. she removed one thing and dipped.

✨ OPTIONS ✨

• -h, --hostname hostname — the hostname of this server (FQDN). by default the canonical name from getaddrinfo(3) for gethostname(2) is used. 🫶
• -s, --server server — the hostname of the IPA server (FQDN). note that by default there is no /etc/ipa/default.conf, so in most cases it needs to be supplied. yes really. bring your own. 💀
• -k, --keytab keytab-file — the keytab file where to append the new key (will be created if it does not exist). default: /etc/krb5.keytab ✨
• -w, --bindpw password — the password to use if not using Kerberos to authenticate. use a password of this particular host (one time password created on IPA server). 🔥
• -b, --basedn basedn — the basedn of the IPA server (of the form dc=example,dc=com). this is only needed when not using Kerberos to authenticate and anonymous binds are disallowed in the IPA LDAP server. 🌈
• -f, --force — force enrolling the host even if host entry exists. chaotic but valid. 💅
• -u, --unenroll — unenroll this host from the IPA server. no keytab entry is removed in the process (see ipa-rmkeytab(1)). 👑
• -q, --quiet — quiet mode. only errors are displayed. shhh. 🤫
• -d, --debug — print the raw RPC output in GSSAPI mode. nerd mode activated, respectfully. 🧚
• -?, --help — help 💜
• --usage — usage 💜

✨ EXAMPLES ✨

join IPA domain and retrieve a keytab with kerberos credentials. 🎀

# kinit admin
# ipa-join

join IPA domain and retrieve a keytab using a one-time password. 🍓

# ipa-join -w secret123

join IPA domain and save the keytab in another location. 🦋

# ipa-join -k /tmp/host.keytab

✨ EXIT STATUS ✨

the exit status is 0 on success, nonzero on error. here's the whole roster, no skips, no shortcuts:

• 0 Success ✅
• 1 Kerberos context initialization failed
• 2 Incorrect usage
• 3 Out of memory
• 4 Invalid service principal name
• 5 No Kerberos credentials cache
• 6 No Kerberos principal and no bind DN and password
• 7 Failed to open keytab
• 8 Failed to create key material
• 9 Setting keytab failed
• 10 Bind password required when using a bind DN
• 11 Failed to add key to keytab
• 12 Failed to close keytab
• 13 Host is already enrolled
• 14 LDAP failure
• 15 Incorrect bulk password
• 16 Host name must be fully-qualified
• 17 RPC fault
• 18 Principal not found in host entry
• 19 Unable to generate Kerberos credentials cache
• 20 Unenrollment result not in RPC response
• 21 Failed to get default Kerberos realm
• 22 Unable to auto-detect fully-qualified hostname

✨ SEE ALSO ✨

ipa-rmkeytab(1) ipa-client-install(1) — go read those too, bestie, they're part of the lore. 📚

and that's the whole page!! this one's from the IPA crew, dated Oct 8 2009 (vintage, honestly, she's been slaying since 2009), so if you ever need to remember her, that's where she lives. ily, go join a realm responsibly 💖✨🎀🦋🌸💅🫶