4.2. Client Management

This chapter provides guidance to install and configure SIMP clients, via kickstart, with the resources supplied by the SIMP ISO.

This guide also assumes that your SIMP server is a yum package repository.

4.2.1. System Requirements

Client systems should meet the following minimum requirements:

  • Hardware/Virtual Machine (VM) : Capable of running RHEL 6 or 7 x86_64
  • RAM: 512 MB
  • HDD: 20 GB

4.2.2. Configuring the Puppet Master

Perform the following actions as root on the Puppet Master system prior to attempting to install a client.

4.2.2.1. Add the Kickstart server profile

In the Puppet server-specific hiera file (by default located at /etc/puppetlabs/code/environments/simp/hieradata/hosts/puppet.<your.domain>.yaml), add the simp::server::kickstart class.

---
classes:
  - simp::server::kickstart

This profile class adds management of bind_dns and named, as well as sets up the example provisioning script.

After adding the above class, run puppet: puppet agent -t.

4.2.2.2. Configure DNS

In SIMP, numerous and/or large configuration files are distributed via rsync by Puppet to minimize management cost. These managed files presently include DNS configuration files and can be found at /var/simp/environments/simp/rsync/<OSTYPE>/<MAJORRELEASE>/bind_dns/default.

This section is not a complete manual for named. For more complete documentation on how to set up named, see named(8) and named.conf(5).

The following configuration steps are for a SIMP-managed setup. However, you can use an existing DNS infrastructure.

  1. Navigate to /var/simp/environments/simp/rsync/<OSTYPE>/<MAJORRELEASE>/bind_dns/default
  2. Modify the named files to correctly reflect the environment.
    • The relevant files under bind_dns/default are as follows:
      • named/etc/named.conf
      • named/etc/zones/your.domain
      • named/var/named/forward/your.domain.db
      • named/var/named/reverse/0.0.10.db
    • Review named/etc/named.conf and update the following:
      • Update the IP for allow-query and allow-recursion
      • Delete any unnecessary zone stanzas (i.e. forwarding) if not necessary
      • Substitute in the FQDN of your domain for all occurrences of your.domain
    • Add clients to named/var/named/forward/your.domain.db and named/var/named/reverse/0.0.10.db and then rename these files to appropriately match your environment.
  3. Type puppet agent -t --tags named on the Puppet Master to apply the changes.
  4. Validate DNS and ensure the /etc/resolv.conf is updated appropriately.
  5. If an error about the rndc.key appears when starting named, see the Bind Documentation. Once you have resolved the issue, re-run the puppet command puppet agent -t on the Puppet Master to apply.

Note

You can adjust the list of clients in your named/var/named/forward/<your.domain>.db and named/var/named/reverse/<your reverse domain>.db files at any time. Just remember to run puppet agent -t --tags named on the Puppet Master to propagate these updates.

4.2.2.3. Configure DHCP

Perform the following actions as root on the Puppet Master system prior to attempting to install a client.

Open the /var/simp/environments/simp/rsync/<OSTYPE>/Global/dhcpd/dhcpd.conf file and edit it to suit the necessary environment.

Make sure the following is done in the dhcpd.conf :

  • The next-server setting in the pxeclients class block points to the IP Address of the TFTP server.
  • Create a Subnet block and edit the following:
    • Make sure the router and netmask are correct for your environment.
    • Enter the hardware ethernet and fixed-address for each client that will be kickstarted. For increased security, it is suggested that SIMP environments not allow clients to pick random IP Address in a subnet. The MAC address must be associated with and IP Address here. (You can add additional ones as needed.)
    • Enter the domain name for option domain-name
    • Enter the IP Address of the DNS server for option domain-name-servers

Save and close the file.

Run puppet agent -t on the Puppet Master to apply the changes.

4.2.2.4. Configure PXE Boot

Sample kickstart templates have been provided in the /var/www/ks directory on the SIMP server and on the SIMP DVD under /ks. Pre-boot images are located in the DVD under /images/pxeboot. If you have an existing Preboot Execution Environment (PXE) setup you can use these to PXE a SIMP client. Follow your own sites procedures for this.

In this section we describe how to configure the Kickstart and TFTP servers to PXE boot a SIMP client. (The DHCP server setup, also required for PXE booting, is discussed in and earlier chapter.)

Note

This example sets up a PXE boot for a system that is the same OS as the SIMP Server. If you are setting up a PXE boot for a different OS then you must make sure that the OS packages are available for all systems you are trying to PXE boot through YUM. There are notes throughout the instructions to help in setting multiple OS but they are not comprehensive. You should understand DHCP, KS, YUM and TFTP relationships for PXE booting before attempting this.

4.2.2.4.1. Setting Up Kickstart

This section describes how to configure the kickstart server.

  1. Locate the following files in the /var/www/ks directory
    • pupclient_x86_64.cfg
    • diskdetect.sh
  2. Open each of the files and follow the instructions provided within them to replace the variables. You need to know the IP Addresses of the YUM, Kickstart, and TFTPserver. (They default to the simp server in simp config).
    • pupclient_x86_64.cfg: Replace the variables noted at the top and generate and enter the passwords.
    • diskdetect.sh: The diskdetect.sh script is responsible for detecting the first active disk and applying a disk configuration. Edit this file to meet any necessary requirements or use this file as a starting point for further work. It will work as is for most systems as long as your disk device names are in the list.
  3. Type chown root.apache /var/www/ks/* to ensure that all files are owned by root and in the apache group.
  4. Type chmod 640 /var/www/ks/* to change the permissions so the owner can read and write the file and the apache group can only read.

Note

The URLs and locations in the file are setup for a default SIMP install. That means the same OS and version as the SIMP server, all servers in one location (on the SIMP server) and in specific directories. If you have installed these servers in a different location than the defaults, you may need to edit URLs or directories.

Note

If you want to PXE boot more than this operating system, make a copy of these files, name them appropriately and update URLS and links inside and anything else you may need. (You must know what you are doing before attempting this.) If you are booting more than one OS you must also make sure your YUM server has the OS packages for the other OSs. By default the YUM server on SIMP has the packages only for the version of OS installed on the SIMP server.

4.2.2.4.2. Setting up TFTP

This section describes the process of setting up static files and manifests for TFTP.

4.2.2.4.2.1. Static Files

Verify the static files are in the correct location:

Type cd /var/simp/environments/simp/rsync/<OSTYPE>/Global/tftpboot

(<OSTYPE> and <MAJORRELEASE> under rsync are the type and version of the SIMP server)

Verify there is a linux-install directory and cd to this directory.

Under the linux-install directory you should find a directory named OSTYPE-MAJORRELEASE.MINORRELEASE-ARCH and a link to this directory named OSTYPE-MAJORRELEASE-ARCH.

Under OSTYPE-MAJORRELEASE.MINORRELEASE-ARCH you should find the files:

  • initrd.img
  • vmlinuz

If these are not there then you must create the directories as needed and copy the files from /var/www/yum/<OSTYPE>/<MAJORRELEASE>/<ARCH>/images/pxeboot or from the images directory on the SIMP DVD.

Important

The link is what is used in the TFTP configuration files.

4.2.2.4.2.2. Manifest

Create a site manifest for the TFTP server on the Puppet server.

  1. Create the file /etc/puppetlabs/code/environments/simp/modules/site/manifests/tftpboot.pp. Use the source code example below.
    • Replace KSSERVER with the IP address of Kickstart server (or the code to look up the IP Address using Hiera).
    • Replace OSTYPE, MAJORRELEASE and ARCH with the correct values for the systems you will be PXE booting.
    • MODEL NAME is usually of the form OSTYPE-MAJORRELEASE-ARCH for consistency.
# for CentOS/RedHat 7
class site::tftpboot {
  include '::tftpboot'

  tftpboot::linux_model { 'el7_x86_64':
    kernel => 'OSTYPE-MAJORRELEASE-ARCH/vmlinuz',
    initrd => 'OSTYPE-MAJORRELEASE-ARCH/initrd.img',
    ks     => "https://KSSERVER/ks/pupclient_x86_64.cfg",
    extra  => "inst.noverifyssl ksdevice=bootif\nipappend 2"
  }

  ::tftpboot::assign_host { 'default': model => 'el7_x86_64' }
}
# For CentOS/RedHat 6
# Note the difference in the `extra` arguments here.
class site::tftpboot {
  include '::tftpboot'

  tftpboot::linux_model { 'el6_x86_64':
    kernel => 'OSTYPE-MAJORRELEASE-ARCH/vmlinuz',
    initrd => 'OSTYPE-MAJORRELEASE-ARCH/initrd.img',
    ks     => "https://KSSERVER/ks/pupclient_x86_64.cfg",
    extra  => "noverifyssl ksdevice=bootif\nipappend 2"
  }

  tftpboot::assign_host { 'default': model => 'el6_x86_64' }
}
  1. Add the tftpboot site manifest on your puppet server node via Hiera. Create the file (or edit if it exists): /etc/puppetlabs/code/environments/simp/hieradata/hosts/<tftp.server.fqdn>.yaml. (By default the TFTP server is the same as your puppet server so it should exist.) Add the following example code to that yaml file.
---
classes:
  - 'site::tftpboot'
  1. After updating the above file, type puppet agent -t --tags tftpboot on the Puppet server.

Note

To PXE boot more OSs, create, in the tftpboot.pp file, a tftpboot::linux_model block for each OS type using the extra directories and kickstart files created using the notes in previous sections. Point individual systems to them by adding assign_host lines with their MAC pointing to the appropriate model name.

4.2.2.5. Apply Certificates

All clients in a SIMP system must have Public Key Infrastructure (PKI) keypairs generated for the server. These keys reside in the /var/simp/environments/simp/site_files/pki_files/files/keydist directory on the SIMP server and are served to the clients over the puppet protocol.

Note

These keypairs are not the keys that the Puppet server uses for its operation. Do not get the two confused.

This section provides guidance on installing official certificates or, as an interim measure, generating certificates from the Fake (self-signing) Certificate Authority provided by SIMP.

4.2.2.5.1. Installing Official Certificates

Below are the steps to install official certificates for a SIMP client on the SIMP server:

  1. Copy the certificates received from a proper CA to the SIMP server.
  2. Add the keys for the node to /var/simp/environments/simp/site_files/pki_files/files/keydist.
  1. Type mkdir -p /var/simp/environments/simp/site_files/pki_files/files/keydist/***<Client System FQDN>***

  2. Type

    mv ***<Certificate Directory>***/***<FQDN>***.[pem|pub] \
    /var/simp/environments/simp/site_files/pki_files/files/keydist/***<FQDN>***
    
  3. Type chown -R root.puppet /var/simp/environments/simp/site_files/pki_files/files/keydist

  4. Type chmod -R u=rwX,g=rX,o-rwx /var/simp/environments/simp/site_files/pki_files/files/keydist

  1. Create and populate the /var/simp/environments/simp/site_files/pki_files/files/keydist/cacerts directory.
  1. Type cd /var/simp/environments/simp/site_files/pki_files/files/keydist
  2. Type mkdir cacerts and copy the root CA public certificates into cacerts in Privacy Enhanced Mail (PEM) format (one per file).
  3. Type cd cacerts
  4. Type for file in *.pem; do ln -s $file `openssl x509 -in $file -hash -noout`.0; done

4.2.2.5.2. Generating Certificates from the Fake CA

If server certificates have not or could not be obtained at the time of client installation, SIMP provides a way to create them for the system, so that it will work until proper certificates are provided.

Note

This option should not be used for any operational system that can use proper enterprise PKI certificates.

Below are the steps to generate the certificates using the SIMP-provided, Fake CA.

  1. Type cd /etc/puppetlabs/code/environments/simp/FakeCA
  2. Type vi togen
  3. Remove old entries from the file and add the Fully Qualified Domain Name (FQDN) of the systems (one per line) for which certificates will be created.

Note

To use alternate DNS names for the same system, separate the names with commas and without spaces.

For example, .name,alt.name1,alt.name2.

  1. Type wc cacertkey

Note

Ensure that the cacertkey file is not empty. If it is, enter text into the file; then save and close the file.

  1. Type ./gencerts_nopass.sh auto

Note

To avoid using the default Fake CA values, remove the auto statement from the ./gencerts_nopass.sh command.

Warning

If the clean.sh command is run after the certificates have been generated, you will not be able to generate new host certificates under the old CA. To troubleshoot certificate problems, see the Troubleshooting Certificate Issues section.

If issues arise while generating keys, type cd /etc/puppetlabs/code/environments/simp/FakeCA to navigate to the /etc/puppetlabs/code/environments/simp/FakeCA directory, then type ./clean.sh to start over.

After running the clean.sh script, type ./gencerts_nopass.sh to run the script again using the previous procedure table.

4.2.3. Setting Up the Client

The following lists the steps to PXE boot the system and set up the client.

  1. Set up your client’s BIOS or virtual settings to boot off the network.
  2. Make sure the MAC address of the client is set up in DHCP (see Configure DHCP for more info.)
  3. Restart the system.
  4. Once the client installs, reboots, and begins to bootstrap, it will check in for the first time.
  5. Puppet will not autosign puppet certificates by default and waitforcert is enabled. The client will check in every 30 seconds for a signed cert. Log on to the puppet server and run puppet cert sign <puppet.client.fqdn>.

Upon successful deployment of a new client, it is highly recommended that LDAP administrative accounts be created.

4.2.4. Troubleshooting Puppet Issues

If the client has been kickstarted, but is not communicating with the Puppet server, try the following options:

  • Check the forward and reverse DNS entries on the client and server; both must be correct. The nslookup command will help here.
  • Check the time on the systems. More than an hour’s difference will cause serious issues with certificates.
  • Remove /etc/puppetlabs/puppet/ssl on the client system; run puppet cert --clean ***<Client Host Name>*** on the Puppet server and try again.

4.2.5. Troubleshooting Certificate Issues

If host certificates do not appear to be working, ensure that all certificates verify against the installed CA certificates.

The table below lists the steps to determine which certificates are working and which are not.

  1. Navigate to /var/simp/environments/simp/site_files/pki_files/files/keydist

  2. Run find . -name “****<your.domain>*.pub” -exec openssl verify -CApath cacerts {} \;

    The screen displays ./<Host Name>.<Your.Domain>/<Hostname>.<Your.Domain>.pub: OK If anything other than OK appears for each host, analyze the error and ensure that the CA certificates are correct.

    If the TXT_DB error number 2 appears, revoke the certificate that is being regenerated. The table below lists the steps to revoke the certificate.

  3. Navigate to /var/simp/environments/simp/site_files/pki_files/files/keydist

  4. Run

    OPENSSL_CONF=default.cnf openssl ca -revoke \
    keydist/*<Host to Revoke>*/*<Host to Revoke>*.pub