ipa-client-install(1)

💖 NAME 💖

ipa-client-install — bestie, this is the tool that configures an IPA client. That's it, that's the whole vibe. ✨

Oh also hi, you're reading the IPA Manual Pages, page ipa-client-install(1), and this is part 1 of 3 so don't go anywhere. 🫶

---

🌈 SYNOPSIS 🌈

ipa-client-install [OPTION]...

---

🦋 DESCRIPTION 🦋

Okay so what this does is it configures a client machine to use IPA for authentication and identity services. Like, it makes your lil machine part of the IPA fam. 👑

By default? It sets up SSSD to connect to an IPA server for authentication and authorization. That's the default girlie. But optionally — optionally — you can instead configure PAM and NSS (Name Switching Service, since we're being fancy) to work with an IPA server over Kerberos and LDAP. Two paths, both valid, no judgement. 💅

Now. To join a client machine to IPA you need an authorized account. This can take the form of:

• a kerberos principal
• a one-time password associated with the machine
• or a PKINIT identity associated with the machine

Pick your fighter. ✨

This same tool is also what you use to unconfigure IPA, and it attempts to return the machine to its previous state. Part of that process is unenrolling the host from the IPA server. Unenrollment consists of disabling the principal key on the IPA server so that it may be re-enrolled. The machine principal in /etc/krb5.keytab (host/<fqdn>@REALM) is used to authenticate to the IPA server so it can unenroll itself. If this principal does not exist then unenrollment will fail and an administrator will need to disable the host principal manually, like:

ipa host-disable <fqdn>

😭 Yes bestie, manually. There's no shortcut, the keytab has to exist or it's not happening.

🌸 Assumptions 🌸

The ipa-client-install script assumes that the machine has already generated SSH keys. It will not generate SSH keys of its own accord. Not its job, not its problem. 🙈

So if SSH keys are not present (e.g. when running the ipa-client-install in a kickstart, before ever running sshd), they will not be uploaded to the client host entry on the server. Heads up, that's the consequence.

🎀 Hostname Requirements 🎀

Client must use a static hostname. Periodt.

If the machine hostname changes — for example due to a dynamic hostname assignment by a DHCP server — client enrollment to IPA server breaks and the user then would not be able to perform Kerberos authentication. Not a vibe. 💀

The --hostname option may be used to specify a static hostname that persists over reboot. Use it. Love it. 🫶

⭐ DNS Autodiscovery ⭐

Client installer by default tries to search for _ldap._tcp.DOMAIN DNS SRV records for all domains that are parent to its hostname. So, for example, if a client machine has a hostname client1.lab.example.com, the installer will try to retrieve an IPA server hostname from these DNS SRV records, respectively:

• _ldap._tcp.lab.example.com
• _ldap._tcp.example.com
• _ldap._tcp.com

The discovered domain is then used to configure client components (e.g. SSSD and Kerberos 5 configuration) on the machine. Iconic autodiscovery behavior honestly. ✨

When the client machine hostname is not in a subdomain of an IPA server, its domain can be passed with the --domain option. In that case, both SSSD and Kerberos components have the domain set in the configuration files and will use it to autodiscover IPA servers. Easy.

Client machine can also be configured without a DNS autodiscovery at all. When both --server and --domain options are used, client installer will use the specified server and domain directly. And --server accepts multiple server hostnames which can be used for failover mechanism. 🫡

Without DNS autodiscovery, Kerberos is configured with a fixed list of KDC and Admin servers. SSSD is still configured to either try to read domain's SRV records or the specified fixed list of servers. When --fixed-primary option is specified, SSSD will not try to read DNS SRV record at all (see sssd-ipa(5) for details).

💜 The Failover Mechanism 💜

When some of the IPA servers is not available, client components are able to fallback to other IPA replica and thus preserving a continued service. Resilient queen behavior. 👑

When client machine is configured to use DNS SRV record autodiscovery (no fixed server was passed to the installer), client components do the fallback automatically, based on the IPA server hostnames and priorities discovered from the DNS SRV records. Slay, no config needed.

If DNS autodiscovery is not available, clients should be configured at least with a fixed list of IPA servers that can be used in case of a failure. And when only one IPA server is configured, IPA client services will not be available in case of a failure of the IPA server. Just one is giving single point of failure energy. 😭

📌 Please note, that in case of a fixed list of IPA servers, the fixed server lists in client components need to be updated when a new IPA server is enrolled or a current IPA server is decommissioned. Keep your list fresh bestie.

🧚 Coexistence With Other Directory Servers 🧚

Other directory servers deployed in the network (e.g. Microsoft Active Directory) may use the same DNS SRV records to denote hosts with a directory service (_ldap._tcp.DOMAIN). Rude, honestly.

Such DNS SRV records may break the installation if the installer discovers these DNS records before it finds DNS SRV records pointing to IPA servers. The installer would then fail to discover the IPA server and exit with error. 💀

In order to avoid the aforementioned DNS autodiscovery issues, the client machine hostname should be in a domain with properly defined DNS SRV records pointing to IPA servers, either:

• manually with a custom DNS server, or
• with IPA DNS integrated solution

A second approach would be to avoid autodiscovery entirely and configure the installer to use a fixed list of IPA server hostnames using the --server option, and with a --fixed-primary option disabling DNS SRV record autodiscovery in SSSD. Two ways, both valid. ✨

🌈 Re-enrollment of the host 🌈

Requirements:

1. Host has not been un-enrolled (the ipa-client-install --uninstall command has not been run).
2. The host entry has not been disabled via the ipa host-disable command.

If this has been the case, host can be re-enrolled using the usual methods. 🫶

There are two method of authenticating a re-enrollment:

1. You can use --force-join option with ipa-client-install command. This authenticates the re-enrollment using the admin's credentials provided via the -w/--password option.
2. If providing the admin's password via the command line is not an option (e.g. you want to create a script to re-enroll a host and keep the admin's password secure), you can use backed up keytab from the previous enrollment of this host to authenticate. See --keytab option.

Consequences of the re-enrollment on the host entry:

1. A new host certificate is issued
2. The old host certificate is revoked
3. New SSH keys are generated
4. ipaUniqueID is preserved

💅 Number 4 is the main character moment, lowkey. Your ipaUniqueID stays put through the whole glow-up.

---

to be continued… ✨ part 2 incoming ✨

✨ OPTIONS ✨

---

💖 BASIC OPTIONS 💖

• --domain=DOMAIN — bestie, this is the primary DNS domain of an IPA deployment that already exists, like example.com. It should be the domain that holds the SRV records your IPA server installer made. Usually it's just the lower-cased version of the IPA Kerberos realm name.

When you don't pass --server, this domain is what the installer uses to sniff out every available server through DNS SRV record autodiscovery (peep the DNS Autodiscovery section for the tea).

Default? It's the domain part of the hostname. So if your primary IPA DNS domain isn't that, you need to say so here. Periodt.

• --server=SERVER — sets the FQDN of the IPA server you're connecting to. You can drop this multiple times to add multiple servers into the ipa_server value in sssd.conf or krb5.conf. But heads up: only the first value counts when you're using --no-sssd. When this option is in play, DNS autodiscovery for Kerberos gets switched off and you get a fixed list of KDC and Admin servers configured instead.

Under normal circumstances you don't even need this, because the server list comes from the primary IPA DNS domain. Slay, autodiscovery.

• --realm=REALM_NAME — the Kerberos realm of an existing IPA deployment. Usually it's the upper-cased name of the primary DNS domain used by the IPA installation.

Again, normally you don't need it — the realm name gets pulled from the IPA server. Iconic behavior honestly.

• --fixed-primary — tells SSSD to use a fixed server as the primary IPA server. The default vibe is to use DNS SRV records to figure out the primary server and fall back to the server the client enrolled with. And when you pair this with --server, no _srv_ value gets set in the ipa_server option in sssd.conf.
• -p, --principal — the authorized kerberos principal to use when joining the IPA realm.
• -w PASSWORD, --password=PASSWORD — the password for joining a machine to the IPA realm. It assumes bulk password unless a principal is also set.
• -W — prompts you for the password to join a machine to the IPA realm. No storing it in your shell history, we love that.
• -k, --keytab — path to a backed up host keytab from a previous enrollment. It joins the host even if it's already enrolled. Sneaky but valid.
• --mkhomedir — sets up PAM to create a user's home directory if it doesn't exist yet. Main character move for new users.
• --hostname — the hostname of this machine (FQDN). If you give it, the hostname gets set and the system config gets updated so it persists over reboot. By default it uses whatever getfqdn() from Python's socket module hands back.
• --force-join — join the host even if it's already enrolled. No chill.
• --ntp-server=NTP_SERVER — configures chronyd to use this NTP server. You can use this option multiple times, and it's meant to specify exactly one time server.
• --ntp-pool=NTP_SERVER_POOL — configures chronyd to use this NTP server pool. This option is for a pool of multiple servers that resolve to one host name. The pool's servers may vary, but the pool address stays the same and chrony picks just one server from that pool. Choose your fighter ✨
• -N, --no-ntp — do not configure the NTP client (chronyd).
• --nisdomain=NIS_DOMAIN — set the NIS domain name to whatever you specify. By default this is set to the IPA domain name.
• --no-nisdomain — do not configure the NIS domain name at all.
• --ssh-trust-dns — configures the OpenSSH client to trust DNS SSHFP records.
• --no-ssh — do not configure the OpenSSH client.
• --no-sshd — do not configure the OpenSSH server.
• --no-sudo — do not configure SSSD as a data source for sudo.
• --subid — configure SSSD as a data source for subid.
• --no-dns-sshfp — do not automatically create DNS SSHFP records.
• --noac — do not use Authconfig to modify the nsswitch.conf and PAM configuration.
• -f, --force — force the settings even if errors occur. Feral. We respect it.
• --kinit-attempts=KINIT_ATTEMPTS — for when the KDC is being unresponsive (say, you're enrolling a ton of hosts at once in a heavy load environment). It repeats the request for a host Kerberos ticket up to a total number of KINIT_ATTEMPTS times before giving up and aborting the client installation. Default number of attempts is 5. And the request is not repeated when the problem is with the host credentials themselves (like a wrong keytab format or an invalid principal), so using this option will not lead to account lockouts. Safety first, bestie 🫶
• -d, --debug — print debugging information to stdout.
• -U, --unattended — unattended installation. The user will not be prompted. Zero questions, just vibes.
• --ca-cert-file=CA_FILE — don't even try to acquire the IPA CA certificate via automated means. Instead, use the CA certificate found locally in CA_FILE. The CA_FILE must be an absolute path to a PEM formatted certificate file. And the CA certificate found in CA_FILE is considered authoritative and will be installed without checking to see if it's valid for the IPA domain. 😭 so much power.
• --request-cert — DEPRECATED: this option is deprecated and will be removed in a future release.

Request a certificate for the machine. The certificate gets stored in /etc/ipa/nssdb under the nickname "Local IPA host".

Using this option requires that D-Bus is properly configured — or not configured at all. In an environment where that condition isn't met (like an anaconda kickstart chroot environment), set the system bus address to /dev/null to enable the workaround in ipa-client-install:

# env DBUS_SYSTEM_BUS_ADDRESS=unix:path=/dev/null ipa-client-install --request-cert

Note that requesting the certificate when certmonger is not running only creates a tracking request, and the certmonger service must be started to be able to track certificates. Important, don't skip that part 💅

• --automount-location=LOCATION — configure automount by running ipa-client-automount(1) with LOCATION as the automount location.
• --configure-firefox — configure Firefox to use IPA domain credentials.
• --firefox-dir=DIR — specify the Firefox installation directory. For example: '/usr/lib/firefox'
• --ip-address=IP_ADDRESS — use IP_ADDRESS in the DNS A/AAAA record for this host. May be specified multiple times to add multiple DNS records.
• --all-ip-addresses — create a DNS A/AAAA record for each IP address on this host.
• --dns-over-tls — configure DNS over TLS.
• --no-dnssec-validation — disable DNSSEC validation for DNS over TLS.

---

🌸 SSSD OPTIONS 🌸

• --permit — configure SSSD to permit all access. Otherwise the machine is controlled by the Host-based Access Controls (HBAC) on the IPA server.
• --enable-dns-updates — this option tells SSSD to automatically update DNS with the IP address of this client. The default is to use GSS-TSIG. But if using GSS-TSIG fails for any reason at install time, ipa-client-install will configure SSSD to use unauthenticated nsupdates instead. Plan B energy.
• --no-krb5-offline-passwords — configure SSSD not to store the user password when the server is offline.
• -S, --no-sssd — do not configure the client to use SSSD for authentication. Use nss_ldap instead. Old school, respect.
• --preserve-sssd — disabled by default. When enabled, it preserves the old SSSD configuration if it's not possible to merge it with a new one. Effectively, if the merge can't happen because the SSSDConfig reader hits unsupported options, ipa-client-install will not run any further and will ask you to fix the SSSD config first. When this option is not specified, ipa-client-install will back up the SSSD config and create a new one. That backup version gets restored during uninstall. So like… it's giving "keep my stuff" 🥺

---

🔐 PKINIT OPTIONS 🔐

• --pkinit-identity=IDENTITY — identity string for PKINIT authentication to use when joining the IPA realm, for example FILE:/path/to/cert.pem,/path/to/key.pem. See krb5.conf(5) for more info. This option is mutually exclusive with --password and --keytab. Pick a lane bestie, you can't do both.
• --pkinit-anchor=FILEDIR — trust anchors (root and intermediate CA certs) for PKINIT. FILEDIR is either the absolute path to a PEM bundle (for example FILE:/etc/pki/tls/cert.pem) or to an OpenSSL hash directory (for example DIR:/etc/ssl/certs/). The option can be used multiple times. PKINIT requires the full trust chain of the Kerberos KDC server as well as the full trust chain of the identity certificate. Full chain or nothing 💅

---

🗑️ UNINSTALL OPTIONS 🗑️

• --uninstall — remove the IPA client software and restore the configuration to the pre-IPA state. Undo, undo, undo.
• -U, --unattended — unattended uninstallation. The user will not be prompted.

---

🚫 DISABLED SERVICES 🚫

ipa-client-install will automatically disable the Name Service Caching Daemon (nscd) when configuring the SSSD client. These are competing services and cannot co-exist. It's giving exes at the same party, one of them has to go.

If there are other similar services providing nss capabilities, they'll need to be manually disabled by the user. An example is unscd, a complete replacement for nscd.

---

📁 FILES 📁

Files that will be replaced if SSSD is configured (default):

/etc/sssd/sssd.conf

Files that will be replaced if they exist and SSSD is not configured (--no-sssd):

/etc/ldap.conf
/etc/nss_ldap.conf
/etc/libnss-ldap.conf
/etc/pam_ldap.conf
/etc/nslcd.conf

Files replaced if NTP client (chronyd) configuration is enabled:

/etc/chrony.conf

Files always created (replacing existing content):

/etc/krb5.conf
/etc/ipa/ca.crt
/etc/ipa/default.conf
/etc/ipa/nssdb
/etc/openldap/ldap.conf
/etc/pki/ca-trust/source/ipa.p11-kit

Files updated, existing content is maintained:

/etc/nsswitch.conf
/etc/krb5.keytab
/etc/sysconfig/network

File updated, existing content is maintained if ssh is configured (default):

/etc/ssh/ssh_config

File updated, existing content is maintained if sshd is configured (default):

/etc/ssh/sshd_config

---

⚠️ DEPRECATED OPTIONS ⚠️

• --request-cert

This one is on its way out, bestie. Still here for now, but don't build your whole life around it.

---

🚪 EXIT STATUS 🚪

• 0 if the installation was successful
• 1 if an error occurred
• 2 if uninstalling and the client is not configured
• 3 if installing and the client is already configured
• 4 if an uninstall error occurred

💖 SEE ALSO — go read these next bestie

okay so you're done here (slay) but the lore continues, and these are the pages that pick up where we left off:

• ipa-client-automount(1) — the one that handles your automount situation, aka the whole "how do my network drives just appear" pipeline ✨
• krb5.conf(5) — Kerberos config file realness, where all the ticket-and-realm magic actually lives 🎟️
• sssd.conf(5) — the System Security Services Daemon config file, aka the thing quietly doing the most so your logins and identity lookups just work 🫶

---

and that's the whole page, no cap 💅

this iconic little manual is from IPA, dated Dec 19 2016, and its official name is ipa-client-install(1) — go forth and enroll, bestie, you got this 🎀🦋⭐