5.1.3. HOWTO Enroll Hosts into an IPA Domain

Hosts should be able to join an IPA domain with a few catches. SIMP already uses the login stack that IPA uses (PAM, SSSD), but it also optionally manages the same resources that IPA provides automation for. This includes:

Technology

Related SIMP Features

Related Tickets

sudoers

simp/simp and simp/sudo modules

SIMP-4898

autofs

optional simp/simp_nfs module

SIMP-4168

krb5

optional simp/krb5 module

SIMP-4167

The features in the above table may work in the future, but logins via sssd or LDAP should work without issue, now.

IPA should work in both the simp and simp_lite scenarios. There may be issues with logins if the simp/sssd module is not included.

5.1.3.1. Adding IPA Clients

Adding IPA clients requires two steps:

  1. Add the hosts on the IPA server, setting a one time password.

  2. Join each host to the IPA domain by running ipa-client-install on the host with the password generated in the previous step.

The second step is automated with the simp/simp_ipa module.

Note

Using ipa-client-install on EL6 with FIPS mode is not currently supported and will result in the following error message: Cannot install IPA client in FIPS mode

5.1.3.1.1. Add Hosts to IPA

There are two ways to complete this step:

  1. Use the IPA web interface, and take note of the one time password.

  2. Run ipa host-add on the command line and pre-generate the password.

Only option 2 will be covered here.

To add hosts from the command line:

  1. Log onto a machine that already has joined an IPA domain.

  2. kinit into an account with the appropriate privileges, (e.g., kinit admin).

  3. Use a script such as the example below, to add hosts in bulk:

    #!/opt/puppetlabs/puppet/bin/ruby
    
    # This scripts adds hosts to IPA using fqdn/IP address pairs listed in a
    # 'hosts' input file and generated passwords of the form
    #
    #   <fqdn>-<random string>
    #
    # The <random string> portion will be the same for all host passwords
    # in a specific run.
    #
    # The input file must contain lines formatted as follows:
    #
    #   <fqdn>,<IP address>
    #
    # such as
    #
    #   ws1.example.domain,192.168.1.3
    #
    require 'securerandom'
    
    unless File.exist?('hosts')
      $stderr.puts "ERROR: Could not find 'hosts' file."
      exit 1
    end
    
    password_suffix = SecureRandom.urlsafe_base64(8)
    puts 'Using one-time passwords of the form of <fqdn>-' + password_suffix
    
    File.readlines('hosts').each do |h|
      # skip comment lines and blank lines
      next if (h[0] == '#') || (h.strip.empty?)
    
      unless h.include?(',')
        $stderr.puts "WARN: Skipping malformed entry: '#{h.strip}'"
        next
      end
    
      fqdn, ip = h.split(',')
      fqdn.strip!
      ip.strip!
      unless !fqdn.empty? && ip && !ip.empty?
        $stderr.puts "WARN: Skipping malformed entry: '#{h.strip}'"
        next
      end
    
      cmd = "ipa host-add #{fqdn} --ip-address=#{ip} --password=#{fqdn}-#{password_suffix}"
      puts cmd
      unless system(cmd)
        $stderr.puts "ERROR:  Command failed '#{cmd}'"
        $stderr.puts 'Exiting!'
        exit 2
      end
    end
    

5.1.3.1.2. Join a Host to the IPA Domain

To join the host to the IPA domain, use simp_ipa::client::install from the simp/simp_ipa Puppet module, by setting the hieradata as shown in the examples below.

The following examples assume

  • the IPA server is ipa.example.domain with an IP address of 192.153.1.2

  • the IPA domain is example.domain

  • the IPA realm is EXAMPLE.DOMAIN.

# In the appropriate level hieradata file
---
simp::classes:
  # this will include this class in client node manifests
  - simp_ipa::client::install

simp_ipa::client::install::ensure: present

# Set this to the one-time password generated when the host was added to IPA.
# This example assumes you used the example script.
simp_ipa::client::install::password: "%{trusted.certname}-<OTP suffix>"

# Set this to the IPA server FQDN
simp_ipa::client::install::server: ipa.example.domain

# Set these to match your IPA domain and realm
simp_ipa::client::install::domain: example.domain
simp_ipa::client::install::realm: EXAMPLE.DOMAIN

In addition to the above settings, other settings may be needed, depending on the configuration of the IPA server and the environment:

---
# IPA uses both of these technologies, so they need to be enabled.
# SSSD is already enabled in the 'simp' and 'simp_lite' scenarios.
simp_options::sssd: true
simp_options::ldap: true

# These 4 parameters have to be set, even though they may be unused because
# IPA does not, natively, set up a BIND DN or a SYNC DN.  If your IPA server
# has those DNs and you are using a SIMP module that uses them (e.g.,
# simp-simp_gitlab), be sure to set them to the real values.  It is likely
# you will also have to set the commented out parameters as well!
simp_options::ldap::bind_pw: "A-Unused-LDAP-Bind-Password"
simp_options::ldap::bind_hash: "{SSHA}this-is-not-a-real-password-hash"
simp_options::ldap::sync_pw: "A-Unused-LDAP-Sync-Password"
simp_options::ldap::sync_hash: "{SSHA}this-is-not-a-real-password-hash"
#simp_options::ldap::base_dn: FILL-ME-IN-AS-NEEDED
#simp_options::ldap::bind_dn: FILL-ME-IN-AS-NEEDED
#simp_options::ldap::sync_dn: FILL-ME-IN-AS-NEEDED
#simp_options::ldap::root_dn: FILL-ME-IN-AS-NEEDED
#simp_options::ldap::master:  FILL-ME-IN-AS-NEEDED
#simp_options::ldap::uri:     [ FILL-ME-IN-AS-NEEDED ]

# If the IPA server is a DNS server, this will allow you to use the DNS
# SRV records to discover other IPA provided services, like LDAP and krb5.
simp_options::dns::servers:
  # IP address of IPA server
  - 192.153.1.2

# Other DNS-related settings that may fix issues that pop up.
simp_options::dns::search:
   # IPA domain
   - example.domain
   resolv::named_autoconf: false
   resolv::caching: false

   # IPA domain
   resolv::resolv_domain: example.domain

Next time Puppet runs, your node will be part of the IPA domain and appropriate logins should work.

5.1.3.2. IPA User Accounts

Once a host has been joined to the IPA domain following the instructions above, users should be able to login with SSSD or LDAP. However, there are a few nuances about user accounts that are worth noting:

  • Only users that are in an IPA group of type POSIX will be able to log into Linux systems. You may need to add such a group on the IPA server. For example, to add a POSIX group named posixusers via the command line:

    kinit admin
    # by default this will be a POSIX group
    ipa group-add posixusers --desc "A POSIX group for users"
    
  • The default UID and GID ranges are very high in IPA (generated randomly by default and can be in the low billions), so they are a lot higher than both the SIMP and SSSD default max. You have a couple of options on how to avoid this issue:

    • Set the start user and group number when you install the IPA server by using the --idstart command line option (e.g., ipa-server-install --idstart=5000)

    • Change the UID/GID ranges in the IPA GUI.

    • Set simp_options::uid::max to match that of your existing IPA server.

  • Users and groups still have to be added to PAM to be able to log in! You will need to allow access using the pam::access::rule define from the simp/pam Puppet module. For example, to allow access to the posixusers group created above:

    pam::access:rule { 'Allow IPA posixusers group into the system':
      users   => [ '(posixusers)' ],
      origins => [ $simp_options::trusted_nets ],
      comment => 'group for IPA users'
    }