Chapter 41. Managing Hosts in IdM CLI
Chapter 41. Managing Hosts in IdM CLI This chapter introduces hosts and host entries in Identity Management (IdM), and the following operations performed when managing hosts and host entries in IdM CLI: Host Enrollment Adding IdM host entries Deleting IdM host entries Re-enrolling hosts Renaming hosts Disabling hosts Re-enabling hosts Delegating access to hosts and services The chapter also contains an overview table of the prerequisites, the context, and the consequences of these operations. 41.1. Hosts in IdM Identity Management (IdM) manages these identities: Users Services Hosts A host represents a machine. As an IdM identity, a host has an entry in the IdM LDAP, that is the 389 Directory Server instance of the IdM server. The host entry in IdM LDAP is used to establish relationships between other hosts and even services within the domain. These relationships are part of delegating authorization and control to hosts within the domain. Any host can be used in host-based access control (HBAC) rules. IdM domain establishes a commonality between machines, with common identity information, common policies, and shared services. Any machine that belongs to a domain functions as a client of the domain, which means it uses the services that the domain provides. IdM domain provides three main services specifically for machines: DNS Kerberos Certificate management Hosts in IdM are closely connected with the services running on them: Service entries are associated with a host. A host stores both the host and the service Kerberos principals. 41.2. Host enrollment This section describes enrolling hosts as IdM clients and what happens during and after the enrollment. The section compares the enrollment of IdM hosts and IdM users. The section also outlines alternative types of authentication available to hosts. Enrolling a host consists of: Creating a host entry in IdM LDAP: possibly using the ipa host-add command in IdM CLI, or the equivalent IdM Web UI operation . Configuring IdM services on the host, for example the System Security Services Daemon (SSSD), Kerberos, and certmonger, and joining the host to the IdM domain. The two actions can be performed separately or together. If performed separately, they allow for dividing the two tasks between two users with different levels of privilege. This is useful for bulk deployments. The ipa-client-install command can perform the two actions together. The command creates a host entry in IdM LDAP if that entry does not exist yet, and configures both the Kerberos and SSSD services for the host. The command brings the host within the IdM domain and allows it to identify the IdM server it will connect to. If the host belongs to a DNS zone managed by IdM, ipa-client-install adds DNS records for the host too. The command must be run on the client. 41.3. User privileges required for host enrollment The host enrollment operation requires authentication to prevent an unprivileged user from adding unwanted machines to the IdM domain. The privileges required depend on several factors, for example: If a host entry is created separately from running ipa-client-install If a one-time password (OTP) is used for enrollment User privileges for optionally manually creating a host entry in IdM LDAP The user privilege required for creating a host entry in IdM LDAP using the ipa host-add CLI command or the IdM Web UI is Host Administrators . The Host Administrators privilege can be obtained through the IT Specialist role. User privileges for joining the client to the IdM domain Hosts are configured as IdM clients during the execution of the ipa-client-install command. The level of credentials required for executing the ipa-client-install command depends on which of the following enrolling scenarios you find yourself in: The host entry in IdM LDAP does not exist. For this scenario, you need a full administrator's credentials or the Host Administrators role. A full administrator is a member of the admins group. The Host Administrators role provides privileges to add hosts and enroll hosts. For details about this scenario, see Installing a client using user credentials: interactive installation . The host entry in IdM LDAP exists. For this scenario, you need a limited administrator's credentials to execute ipa-client-install successfully. The limited administrator in this case has the Enrollment Administrator role, which provides the Host Enrollment privilege. For details, Installing a client using user credentials: interactive installation . The host entry in IdM LDAP exists, and an OTP has been generated for the host by a full or limited administrator. For this scenario, you can install an IdM client as an ordinary user if you run the ipa-client-install command with the --password option, supplying the correct OTP. For details, see Installing a client by using a one-time password: Interactive installation . After enrollment, IdM hosts authenticate every new session to be able to access IdM resources. Machine authentication is required for the IdM server to trust the machine and to accept IdM connections from the client software installed on that machine. After authenticating the client, the IdM server can respond to its requests. 41.4. Enrollment and authentication of IdM hosts and users: comparison There are many similarities between users and hosts in IdM, some of which can be observed during the enrollment stage as well as those that concern authentication during the deployment stage. The enrollment stage ( User and host enrollment ): An administrator can create an LDAP entry for both a user and a host before the user or host actually join IdM: for the stage user, the command is ipa stageuser-add ; for the host, the command is ipa host-add . A file containing a key table or, abbreviated, keytab, a symmetric key resembling to some extent a user password, is created during the execution of the ipa-client-install command on the host, resulting in the host joining the IdM realm. Analogically, a user is asked to create a password when they activate their account, therefore joining the IdM realm. While the user password is the default authentication method for a user, the keytab is the default authentication method for a host. The keytab is stored in a file on the host. Table 41.1. User and host enrollment Action User Host Pre-enrollment USD ipa stageuser-add user_name [--password] USD ipa host-add host_name [--random] Activating the account USD ipa stageuser-activate user_name USD ipa-client install [--password] (must be run on the host itself) The deployment stage ( User and host session authentication ): When a user starts a new session, the user authenticates using a password; similarly, every time it is switched on, the host authenticates by presenting its keytab file. The System Security Services Daemon (SSSD) manages this process in the background. If the authentication is successful, the user or host obtains a Kerberos ticket granting ticket (TGT). The TGT is then used to obtain specific tickets for specific services. Table 41.2. User and host session authentication User Host Default means of authentication Password Keytabs Starting a session (ordinary user) USD kinit user_name [switch on the host] The result of successful authentication TGT to be used to obtain access to specific services TGT to be used to obtain access to specific services TGTs and other Kerberos tickets are generated as part of the Kerberos services and policies defined by the server. The initial granting of a Kerberos ticket, the renewing of the Kerberos credentials, and even the destroying of the Kerberos session are all handled automatically by the IdM services. Alternative authentication options for IdM hosts Apart from keytabs, IdM supports two other types of machine authentication: SSH keys. The SSH public key for the host is created and uploaded to the host entry. From there, the System Security Services Daemon (SSSD) uses IdM as an identity provider and can work in conjunction with OpenSSH and other services to reference the public keys located centrally in IdM. Machine certificates. In this case, the machine uses an SSL certificate that is issued by the IdM server's certificate authority and then stored in IdM's Directory Server. The certificate is then sent to the machine to present when it authenticates to the server. On the client, certificates are managed by a service called certmonger . 41.5. Host Operations The most common operations related to host enrollment and enablement, and the prerequisites, the context, and the consequences of performing those operations are outlined in the following sections. Table 41.3. Host operations part 1 Action What are the prerequisites of the action? When does it make sense to run the command? How is the action performed by a system administrator? What command(s) does he run? Enrolling a client see Preparing the system for Identity Management client installation in Installing Identity Management When you want the host to join the IdM realm. Enrolling machines as clients in the IdM domain is a two-part process. A host entry is created for the client (and stored in the 389 Directory Server instance) when the ipa host-add command is run, and then a keytab is created to provision the client. Both parts are performed automatically by the ipa-client-install command. It is also possible to perform those steps separately; this allows for administrators to prepare machines and IdM in advance of actually configuring the clients. This allows more flexible setup scenarios, including bulk deployments. Disabling a client The host must have an entry in IdM. The host needs to have an active keytab. When you want to remove the host from the IdM realm temporarily, perhaps for maintenance purposes. ipa host-disable host_name Enabling a client The host must have an entry in IdM. When you want the temporarily disabled host to become active again. ipa-getkeytab Re-enrolling a client The host must have en entry in IdM. When the original host has been lost but you have installed a host with the same host name. ipa-client-install --keytab or ipa-client-install --force-join Un-enrolling a client The host must have an entry in IdM. When you want to remove the host from the IdM realm permanently. ipa-client-install --uninstall Table 41.4. Host operations part 2 Action On which machine can the administrator run the command(s)? What happens when the action is performed? What are the consequences for the host's functioning in IdM? What limitations are introduced/removed? Enrolling a client In the case of a two-step enrollment: ipa host-add can be run on any IdM client; the second step of ipa-client-install must be run on the client itself By default this configures SSSD to connect to an IdM server for authentication and authorization. Optionally one can instead configure the Pluggable Authentication Module (PAM) and the Name Switching Service (NSS) to work with an IdM server over Kerberos and LDAP. Disabling a client Any machine in IdM, even the host itself The host's Kerberos key and SSL certificate are invalidated, and all services running on the host are disabled. Enabling a client Any machine in IdM. If run on the disabled host, LDAP credentials need to be supplied. The host's Kerberos key and the SSL certificate are made valid again, and all IdM services running on the host are re-enabled. Re-enrolling a client The host to be re-enrolled. LDAP credentials need to be supplied. A new Kerberos key is generated for the host, replacing the one. Un-enrolling a client The host to be un-enrolled. The command unconfigures IdM and attempts to return the machine to its state. Part of this process is to unenroll the host from the IdM server. Unenrollment consists of disabling the principal key on the IdM server. The machine principal in /etc/krb5.keytab ( host/<fqdn>@REALM ) is used to authenticate to the IdM server to unenroll itself. If this principal does not exist then unenrollment will fail and an administrator will need to disable the host principal ( ipa host-disable <fqdn> ). 41.6. Host entry in IdM LDAP An Identity Management (IdM) host entry contains information about the host and what attributes it can contain. An LDAP host entry contains all relevant information about the client within IdM: Service entries associated with the host The host and service principal Access control rules Machine information, such as its physical location and operating system Note Note that the IdM Web UI Identity Hosts tab does not show all the information about a particular host stored in the IdM LDAP. Host entry configuration properties A host entry can contain information about the host that is outside its system configuration, such as its physical location, MAC address, keys, and certificates. This information can be set when the host entry is created if it is created manually. Alternatively, most of this information can be added to the host entry after the host is enrolled in the domain. Table 41.5. Host Configuration Properties UI Field Command-Line Option Description Description --desc = description A description of the host. Locality --locality = locality The geographic location of the host. Location --location = location The physical location of the host, such as its data center rack. Platform --platform = string The host hardware or architecture. Operating system --os = string The operating system and version for the host. MAC address --macaddress = address The MAC address for the host. This is a multi-valued attribute. The MAC address is used by the NIS plug-in to create a NIS ethers map for the host. SSH public keys --sshpubkey = string The full SSH public key for the host. This is a multi-valued attribute, so multiple keys can be set. Principal name (not editable) --principalname = principal The Kerberos principal name for the host. This defaults to the host name during the client installation, unless a different principal is explicitly set in the -p . This can be changed using the command-line tools, but cannot be changed in the UI. Set One-Time Password --password = string This option sets a password for the host which can be used in bulk enrollment. - --random This option generates a random password to be used in bulk enrollment. - --certificate = string A certificate blob for the host. - --updatedns This sets whether the host can dynamically update its DNS entries if its IP address changes. 41.7. Adding IdM host entries from IdM CLI Follow this procedure to add host entries in Identity Management (IdM) using the command line (CLI). Host entries are created using the host-add command. This commands adds the host entry to the IdM Directory Server. Consult the ipa host manpage by typing ipa help host in your CLI to get the full list of options available with host-add . There are a few different scenarios when adding a host to IdM: At its most basic, specify only the client host name to add the client to the Kerberos realm and to create an entry in the IdM LDAP server: If the IdM server is configured to manage DNS, add the host to the DNS resource records using the --ip-address option. Example 41.1. Creating Host Entries with Static IP Addresses If the host to be added does not have a static IP address or if the IP address is not known at the time the client is configured, use the --force option with the ipa host-add command. Example 41.2. Creating Host Entries with DHCP For example, laptops may be preconfigured as IdM clients, but they do not have IP addresses at the time they are configured. Using --force essentially creates a placeholder entry in the IdM DNS service. When the DNS service dynamically updates its records, the host's current IP address is detected and its DNS record is updated. 41.8. Deleting host entries from IdM CLI Use the host-del command to delete host records. If your IdM domain has integrated DNS, use the --updatedns option to remove the associated records of any kind for the host from the DNS: 41.9. Re-enrolling an Identity Management client This section describes the different way you can re-enroll an Identity Management client. 41.9.1. Client re-enrollment in IdM During the re-enrollment, the client generates a new Kerberos key and SSH keys, but the identity of the client in the LDAP database remains unchanged. After the re-enrollment, the host has its keys and other information in the same LDAP object with the same FQDN as previously, before the machine's loss of connection with the IdM servers. Important You can only re-enroll clients whose domain entry is still active. If you uninstalled a client (using ipa-client-install --uninstall ) or disabled its host entry (using ipa host-disable ), you cannot re-enroll it. You cannot re-enroll a client after you have renamed it. This is because in Identity Management, the key attribute of the client's entry in LDAP is the client's hostname, its FQDN . As opposed to re-enrolling a client, during which the client's LDAP object remains unchanged, the outcome of renaming a client is that the client has its keys and other information in a different LDAP object with a new FQDN . Therefore, the only way to rename a client is to uninstall the host from IdM, change the host's hostname, and install it as an IdM client with a new name. For details on how to rename a client, see Renaming Identity Management client systems . What happens during client re-enrollment During re-enrollment, Identity Management: Revokes the original host certificate Creates new SSH keys Generates a new keytab 41.9.2. Re-enrolling a client by using user credentials: Interactive re-enrollment Follow this procedure to re-enroll an Identity Management client interactively by using the credentials of an authorized user. Re-create the client machine with the same host name. Run the ipa-client-install --force-join command on the client machine: The script prompts for a user whose identity will be used to re-enroll the client. This could be, for example, a hostadmin user with the Enrollment Administrator role: Additional resources See Installing a client by using user credentials: Interactive installation in Installing Identity Management . 41.9.3. Re-enrolling a client by using the client keytab: Non-interactive re-enrollment You can re-enroll an Identity Management (IdM) client non-interactively by using the krb5.keytab keytab file of the client system from the deployment. For example, re-enrollment using the client keytab is appropriate for an automated installation. Prerequisites You have backed up the keytab of the client from the deployment on another system. Procedure Re-create the client machine with the same host name. Copy the keytab file from the backup location to the re-created client machine, for example its /tmp/ directory. Important Do not put the keytab in the /etc/krb5.keytab file as old keys are removed from this location during the execution of the ipa-client-install installation script. Use the ipa-client-install utility to re-enroll the client. Specify the keytab location with the --keytab option: Note The keytab specified in the --keytab option is only used when authenticating to initiate the re-enrollment. During the re-enrollment, IdM generates a new keytab for the client. 41.9.4. Testing an Identity Management client after installation The command line informs you that the ipa-client-install was successful, but you can also do your own test. To test that the Identity Management client can obtain information about users defined on the server, check that you are able to resolve a user defined on the server. For example, to check the default admin user: To test that authentication works correctly, su - as another IdM user: 41.10. Renaming Identity Management client systems The following sections describe how to change the host name of an Identity Management client system. Warning Renaming a client is a manual procedure. Do not perform it unless changing the host name is absolutely required. Renaming an Identity Management client involves: Preparing the host. For details, see Preparing an IdM client for its renaming . Uninstalling the IdM client from the host. For details, see Uninstalling an Identity Management client . Renaming the host. For details, see Renaming the host system . Installing the IdM client on the host with the new name. For details, see Installing an Identity Management client in Installing Identity Management .. Configuring the host after the IdM client installation. For details, see Re-adding services, re-generating certificates, and re-adding host groups . 41.10.1. Preparing an IdM client for its renaming Before uninstalling the current client, make note of certain settings for the client. You will apply this configuration after re-enrolling the machine with a new host name. Identify which services are running on the machine: Use the ipa service-find command, and identify services with certificates in the output: In addition, each host has a default host service which does not appear in the ipa service-find output. The service principal for the host service, also called a host principal , is host/ old-client-name.example.com . For all service principals displayed by ipa service-find old-client-name.example.com , determine the location of the corresponding keytabs on the old-client-name.example.com system: Each service on the client system has a Kerberos principal in the form service_name/host_name@REALM , such as ldap/ old-client-name.example.com@EXAMPLE.COM . Identify all host groups to which the machine belongs. 41.10.2. Uninstalling an Identity Management client Uninstalling a client removes the client from the Identity Management domain, along with all of the specific Identity Management configuration of system services, such as System Security Services Daemon (SSSD). This restores the configuration of the client system. Procedure Run the ipa-client-install --uninstall command: Remove the DNS entries for the client host manually from the server: For each identified keytab other than /etc/krb5.keytab , remove the old principals: On an IdM server, remove the host entry. This removes all services and revokes all certificates issued for that host: 41.10.3. Renaming the host system Rename the machine as required. For example: You can now re-install the Identity Management client to the Identity Management domain with the new host name. 41.10.4. Re-adding services, re-generating certificates, and re-adding host groups Procedure You can re-add services, re-generate certificates, and re-add host groups on your Identity Management (IdM) server. On the Identity Management server, add a new keytab for every service identified in the Preparing an IdM client for its renaming . Generate certificates for services that had a certificate assigned in the Preparing an IdM client for its renaming . You can do this: Using the IdM administration tools Using the certmonger utility Re-add the client to the host groups identified in the Preparing an IdM client for its renaming . 41.11. Disabling and Re-enabling Host Entries This section describes how to disable and re-enable hosts in Identity Management (IdM). 41.11.1. Disabling Hosts Complete this procedure to disable a host entry in IdM. Domain services, hosts, and users can access an active host. There can be situations when it is necessary to remove an active host temporarily, for maintenance reasons, for example. Deleting the host in such situations is not desired as it removes the host entry and all the associated configuration permanently. Instead, choose the option of disabling the host. Disabling a host prevents domain users from accessing it without permanently removing it from the domain. Procedure Disable a host using the host-disable command. Disabling a host kills the host's current, active keytabs. For example: As a result of disabling a host, the host becomes unavailable to all IdM users, hosts and services. Important Disabling a host entry not only disables that host. It disables every configured service on that host as well. 41.11.2. Re-enabling Hosts Follow this procedure to re-enable a disabled IdM host. Disabling a host killed its active keytabs, which removed the host from the IdM domain without otherwise touching its configuration entry. Procedure To re-enable a host, use the ipa-getkeytab command, adding: the -s option to specify which IdM server to request the keytab from the -p option to specify the principal name the -k option to specify the file to which to save the keytab. For example, to request a new host keytab from server.example.com for client.example.com , and store the keytab in the /etc/krb5.keytab file: Note You can also use the administrator's credentials, specifying -D "uid=admin,cn=users,cn=accounts,dc=example,dc=com" . It is important that the credentials correspond to a user allowed to create the keytab for the host. If the ipa-getkeytab command is run on an active IdM client or server, then it can be run without any LDAP credentials ( -D and -w ) if the user has a TGT obtained using, for example, kinit admin . To run the command directly on the disabled host, supply LDAP credentials to authenticate to the IdM server. 41.12. Delegating access to hosts and services By delegating access to hosts and services within an IdM domain, you can retrieve keytabs and certificates for another host or service. Each host and service has a managedby entry that lists what hosts and services can manage it. By default, a host can manage itself and all of its services. You can configure a host to manage other hosts, or services on other hosts within the IdM domain. Note When you delegate authority of a host to another host through a managedby entry, it does not automatically grant management rights for all services on that host. You must perform each delegation independently. Host and service delegation 41.12.1. Delegating service management You can delegate permissions to a host to manage a service on another host within the domain. When you delegate permissions to a host to manage another host, it does not automatically include permissions to manage its services. You must delegate service management independently. Procedure Delegate the management of a service to a specific host by using the service-add-host command: You must specify the service principal using the principal argument and the hosts with control using the --hosts option. For example: Once the host is delegated authority, the host principal can be used to manage the service: To generate a certificate for the delegated service, create a certificate request on the host with the delegated authority: Use the cert-request utility to submit the certificate request and load the certification information: Additional resources Managing certificates for users, hosts, and services using the integrated IdM CA 41.12.2. Delegating host management You can delegate authority for a host to manage another host by using the host-add-managedby utility. This creates a managedby entry. After the managedby entry is created, the managing host can retrieve a keytab for the host it manages. Procedure Log in as the admin user: Add the managedby entry. For example, this delegates authority over client2 to client1 : Obtain a ticket as the host client1 : Retrieve a keytab for client2 : 41.12.3. Accessing delegated services When a client has delegated authority, it can obtain a keytab for the principal on the local machine for both services and hosts. With the kinit command, use the -k option to load a keytab and the -t option to specify the keytab. The principal format is <principal>/hostname@REALM . For a service, replace <principal> with the service name, for example HTTP. For a host, use host as the principal. Procedure To access a host: To access a service:
ipa host-add client1.example.com ipa host-add --ip-address=192.168.166.31 client1.example.com ipa host-add --force client1.example.com ipa host-del --updatedns client1.example.com ipa-client-install --force-join User authorized to enroll computers: hostadmin Password for hostadmin @ EXAMPLE.COM : ipa-client-install --keytab /tmp/krb5.keytab [user@client1 ~]USD id admin uid=1254400000(admin) gid=1254400000(admins) groups=1254400000(admins) [user@client1 ~]USD su - idm_user Last login: Thu Oct 18 18:39:11 CEST 2018 from 192.168.122.1 on pts/0 [idm_user@client1 ~]USD ipa service-find old-client-name.example.com find / -name "*.keytab" ipa hostgroup-find old-client-name.example.com ipa-client-install --uninstall ipa dnsrecord-del Record name: old-client-client Zone name: idm.example.com No option to delete specific record provided. Delete all? Yes/No (default No): true ------------------------ Deleted record "old-client-name" ipa-rmkeytab -k /path/to/keytab -r EXAMPLE.COM ipa host-del client.example.com hostnamectl set-hostname new-client-name.example.com ipa service-add service_name/new-client-name kinit admin ipa host-disable client.example.com ipa-getkeytab -s server.example.com -p host/client.example.com -k /etc/krb5.keytab -D "cn=directory manager" -w password ipa service-add-host principal --hosts=<hostname> ipa service-add HTTP/web.example.com ipa service-add-host HTTP/web.example.com --hosts=client1.example.com kinit -kt /etc/krb5.keytab host/client1.example.com ipa-getkeytab -s server.example.com -k /tmp/test.keytab -p HTTP/web.example.com Keytab successfully retrieved and stored in: /tmp/test.keytab kinit -kt /etc/krb5.keytab host/client1.example.com openssl req -newkey rsa:2048 -subj '/CN=web.example.com/O=EXAMPLE.COM' -keyout /etc/pki/tls/web.key -out /tmp/web.csr -nodes Generating a 2048 bit RSA private key .............................................................+++ ............................................................................................+++ Writing new private key to '/etc/pki/tls/private/web.key' ipa cert-request --principal=HTTP/web.example.com web.csr Certificate: MIICETCCAXqgA...[snip] Subject: CN=web.example.com,O=EXAMPLE.COM Issuer: CN=EXAMPLE.COM Certificate Authority Not Before: Tue Feb 08 18:51:51 2011 UTC Not After: Mon Feb 08 18:51:51 2016 UTC Serial number: 1005 kinit admin ipa host-add-managedby client2.example.com --hosts=client1.example.com kinit -kt /etc/krb5.keytab host/client1.example.com ipa-getkeytab -s server.example.com -k /tmp/client2.keytab -p host/client2.example.com Keytab successfully retrieved and stored in: /tmp/client2.keytab kinit -kt /etc/krb5.keytab host/ipa.example.com@EXAMPLE.COM kinit -kt /etc/httpd/conf/krb5.keytab HTTP/ipa.example.com@EXAMPLE.COM