Client Configuration Guide
Red Hat Network
Abstract
Chapter 1. Introduction
Note
Chapter 2. Client Applications
Important
2.1. Deploying the Latest Red Hat Network Client RPMs
up2date) and Red Hat Network Registration Client (rhn_register) are prerequisites for using much of Red Hat Network's enterprise functionality. It is crucial to install them on client systems before attempting to use RHN Proxy Server or RHN Satellite Server in your environment.
up2date and rhn_register (if RHEL 2.1) do not need to be performed. Those client tools should have no issues connecting to your RHN Satellite or Proxy environment. The discussion below assumes that the "out of box" up2date and rhn_register are not the latest and do not work for your environment.
up2date and rhn_register for the first time by an administrator assuming the machines don't already have a working RHN. The administrator has populated the /var/www/html/pub/ directory with a copy of the up2date and rhn_register (for RHEL 2.1 systems) RPMs that his client systems need, and then has simply deployed those RPMs onto his client systems with a simple rpm -Uvh command. Run from a client, this command installs the RPMs to that client, assuming the domain name, paths, and RPM versions are correct:
rpm -Uvh\http://your_proxy_or_sat.your_domain.com/pub/rhn_register-2.9.12-1.2.1AS.i386.rpm\http://your_proxy_or_sat.your_domain.com/pub/rhn_register-gnome-2.9.12-1.2.1AS.i386.rpm\http://your_proxy_or_sat.your_domain.com/pub/up2date-2.9.14-1.2.1AS.i386.rpm\http://your_proxy_or_sat.your_domain.com/pub/up2date-gnome-2.9.14-1.2.1AS.i386.rpm
2.2. Configuring the Client Applications
up2date) and possibly the Red Hat Network Registration Client (rhn_register) to redirect it from Red Hat Network to their RHN Satellite Server or RHN Proxy Server.
Important
up2date uses SSL only. For this reason, users should ensure that their firewalls allow connections over port 443. To bypass SSL, change the protocol for serverURL from https to http in /etc/sysconfig/rhn/up2date. Similarly, to use RHN's Monitoring feature and probes requiring the Red Hat Network Monitoring Daemon, note that client systems must allow connections on port 4545 (or port 22, if using sshd instead).
up2date --configure, and manually updating the configuration files. (To see how virtually all reconfiguration can be scripted, see Chapter 6, Manually Scripting the Configuration.)
2.2.1. Registering with Activation Keys
- Generate an Activation Key as described in the Activation Keys section of the Red Hat Update Agent chapter within the RHN Management Reference Guide
- Import custom GPG keys.
- Download and install the SSL Certificate RPM from the
/pub/directory of the RHN Proxy Server or RHN Satellite Server. The command for this step could look something like this:rpm -Uvh\http://your-satellite.com/pub/rhn-org-trusted-ssl-cert-1.0-1.noarch.rpm - Register the system with your RHN Proxy Server or RHN Satellite Server. The command for this step could look something like:
rhnreg_ks --activationkey mykey --serverUrlhttps://your-satellite.com/XMLRPC
wget -0 - http://your-satellite-DQDN/pub/bootstrap.sh | bash \ && rhnreg_ks --activation-key my_key --serverUrl \ https://your-satellite-FQDN/XMLRPC Warning
rhn_register to up2date. Therefore, the SSL certificate information on those systems must be set manually. All other settings, such as the server URL, transfer properly.
2.2.2. Using the --configure Option
application_filename --configure
up2date --configure Select a Red Hat Network Server to use replace the default value with the fully qualified domain name (FQDN) of the RHN Satellite Server or RHN Proxy Server, such as https://your_proxy_or_sat.your_domain.com/XMLRPC. Retain the /XMLRPC at the end. When finished, click .

Figure 2.1. Red Hat Update Agent GUI Configuration
up2date --configure from launching. This may be resolved, however, by editing the value in the up2date configuration file. Refer to Section 2.2.3, “Updating the Configuration Files Manually” for precise instructions.
Warning
/usr/bin/rhn_register --configure Select a Red Hat Network server to use replace the default value with the fully qualified domain name (FQDN) of the RHN Satellite Server or RHN Proxy Server, such as https://your_proxy_or_sat.your_domain.com/XMLRPC. Retain the /XMLRPC at the end. Click OK when finished.

Figure 2.2. Red Hat Network Registration Client GUI Configuration
rhn_register does not display the server field, and you cannot upgrade to a later version, you may enter the domain name of your RHN Satellite Server or RHN Proxy Server directly into the rhn_register configuration file. Refer to Section 2.2.3, “Updating the Configuration Files Manually” for precise instructions.
2.2.3. Updating the Configuration Files Manually
serverURL and noSSLServerURL settings in the /etc/sysconfig/rhn/up2date configuration file (as root). Replace the default Red Hat Network URL with the fully qualified domain name (FQDN) for the RHN Proxy Server or RHN Satellite Server. For example:
serverURL[comment]=Remote server URL serverURL=https://your_primary.your_domain.com/XMLRPC noSSLServerURL[comment]=Remote server URL without SSL noSSLServerURL=http://your_primary.your_domain.com/XMLRPC
Warning
httpProxy setting in /etc/sysconfig/rhn/up2date does not refer to the RHN Proxy Server. It is used to configure an optional HTTP proxy for the client. With an RHN Proxy Server in place, the httpProxy setting must be blank (not set to any value).
Note
rhn_register on client systems so they can recognize new certificates. This RPM should be available in /var/spool/up2date on your proxy system after running up2date for the Proxy.
serverURL and noSSLServerURL options in the /etc/sysconfig/rhn/rhn_register configuration file (as root). Replace the default Red Hat Network URL with the fully qualified domain name (FQDN) for the RHN Proxy Server or RHN Satellite Server. For example:
serverURL[comment]=Remote server URL serverURL=https://your_proxy_or_sat.your_domain.com/XMLRPC noSSLServerURL[comment]=Remote server URL without SSL noSSLServerURL=http://your_proxy_or_sat.your_domain.com/XMLRPC
2.2.4. Implementing Server Failover
up2date-4.2.38, the Red Hat Update Agent can be configured to seek updates from a series of RHN Servers. This can be especially helpful in sustaining constant updates if your primary RHN Proxy Server or RHN Satellite Server may be taken offline.
up2date. Then manually add the secondary servers to the serverURL and noSSLServerURL settings in the /etc/sysconfig/rhn/up2date configuration file (as root). Add the fully qualified domain names (FQDN) for the Proxy or Satellite immediately after the primary server, separated by a semicolon (;). For example:
serverURL[comment]=Remote server URL serverURL=https://your_primary.your_domain.com/XMLRPC; \ https://your_secondary.your_domain.com/XMLRPC; noSSLServerURL[comment]=Remote server URL without SSL noSSLServerURL=http://your_primary.your_domain.com/XMLRPC; \ https://your_secondary.your_domain.com/XMLRPC;
2.3. Configuring the Red Hat Network Alert Notification Tool with Satellite
- Ensure that your RHN Satellite Server is version 3.4 or later and that you have the
rhns-appletpackage installed on the Satellite. The package can be found in the RHN Satellite software channel for versions 3.4 and newer. - Retrieve the
rhn-applet-actionspackage withup2dateor through the Red Hat Network Tools software channel. Install the package on all Red Hat Enterprise Linux 3 and newer client systems to be notified of custom updates with the Red Hat Network Alert Notification Tool. The client systems must be entitled to the Management or Provisioning service levels. - Within the Satellite's version of the RHN website, go to the System Details page for each system and click the link within the RHN Applet area to redirect the Red Hat Network Alert Notification Tool to the Satellite.
Chapter 3. SSL Infrastructure
3.1. A Brief Introduction To SSL
Note
- Certificate Authority (CA) SSL private key and public certificate — only one set per organization generally generated. The public certificate is digitally signed by its private key. The public certificate is distributed to every system.
- Web server SSL private key and public certificate — one set per application server. The public certificate is digitally signed by both its private key and the CA SSL private key. We often refer to a Web server's key set; this is because there is an intermediary SSL certificate request that is generated. The details of what this is used for are not important to this discussion. All three are deployed to an RHN Server.
Important
3.2. The Red Hat Network SSL Maintenance Tool
rhn-ssl-tool. This tool is available as part of the rhns-certs-tools package. This package can be found within the software channels for the the latest RHN Proxy Server and RHN Satellite Server (as well as the RHN Satellite Server ISO). Red Hat Network SSL Maintenance Tool enables you to generate your own Certificate Authority SSL key pair, as well as Web server SSL key sets (sometimes called key pairs).
Note
rhns-certs-tools, which contains rhn-ssl-tool, can be installed and run on any current Red Hat Enterprise Linux system with minimal requirements. This is offered as a convenience for administrators who wish to manage their SSL infrastructure from their workstation or another system other than their RHN Server(s).
- When updating your CA public certificate - this is rare.
- When installing an RHN Proxy Server version 3.6 or later that connects to the central RHN Servers as its top-level service - the hosted service, for security reasons, cannot be a repository for your CA SSL key and certificate, which is private to your organization.
- When reconfiguring your RHN infrastructure to use SSL where it previously did not.
- When adding RHN Proxy Servers of versions prior to 3.6 into your RHN infrastructure.
- When adding multiple RHN Satellite Servers to your RHN infrastructure - consult with a Red Hat representative for instructions regarding this.
- During installation of an RHN Satellite Server - all SSL settings are configured during the installation process. The SSL keys and certificate are built and deployed automatically.
- During installation of an RHN Proxy Server version 3.6 or later if connected to an RHN Satellite Server version 3.6 or later as its top-level service - the RHN Satellite Server contains all of the SSL information needed to configure, build and deploy the RHN Proxy Server's SSL keys and certificates.
/pub directory of each server. This public certificate is used by the client systems to connect to the RHN Server. Refer to Section 3.3, “Deploying the CA SSL Public Certificate to Clients” for more information.
3.2.1. SSL Generation Explained
rhns-certs-tools package installed. Portability exists in a build structure that can be stored anywhere for safe keeping and then installed wherever the need arises.
ssl-build tree from an archive to the /root directory and utilize the configuration tools provided within the RHN Satellite Server's website.
- Install the
rhns-certs-toolspackage on a system within your organization, perhaps but not necessarily the RHN Satellite Server or RHN Proxy Server. - Create a single Certificate Authority SSL key pair for your organization and install the resulting RPM or public certificate on all client systems.
- Create a Web server SSL key set for each of the Proxies and Satellites to be deployed and install the resulting RPMs on the RHN Servers, restarting the
httpdservice afterwards:/sbin/service httpd restart - Archive the SSL build tree - consisting of the primary build directory and all subdirectories and files - to removable media, such as a floppy disk. (Disk space requirements are insignificant.)
- Verify and then store that archive in a safe location, such as the one described for backups in the Additional Requirements sections of either the Proxy or Satellite installation guide.
- Record and secure the CA password for future use.
- Delete the build tree from the build system for security purposes, but only once the entire RHN infrastructure is in place and configured.
- When additional Web server SSL key sets are needed, restore the build tree on a system running the Red Hat Network SSL Maintenance Tool and repeat steps 3 through 7.
3.2.2. Red Hat Network SSL Maintenance Tool Options
rhn-ssl-tool --help (general), rhn-ssl-tool --gen-ca --help (Certificate Authority), and rhn-ssl-tool --gen-server --help (Web server). The manual page for rhn-ssl-tool is also quite detailed and available to assist: man rhn-ssl-tool.
--gen-ca argument:
Table 3.1. SSL Certificate Authority (CA) Options (rhn-ssl-tool --gen-ca --help)
| Option | Description |
|---|---|
--gen-ca | Generate a Certificate Authority (CA) key pair and public RPM. This must be issued with any of the remaining options in this table. |
-h, --help | Display the help screen with a list of base options specific to generating and managing a Certificate Authority. |
-f, --force | Forcibly create a new CA private key and/or public certificate. |
-p=, --password=PASSWORD | The CA password. You will be prompted for this if it's missing. Record it in a safe manner. |
-d=, --dir=BUILD_DIRECTORY | Required for most commands - The directory where certificates and RPMs are built. The default is ./ssl-build. |
--ca-key=FILENAME | The CA private key filename. The default is RHN-ORG-PRIVATE-SSL-KEY. |
--ca-cert=FILENAME | The CA public certificate filename. The default is RHN-ORG-TRUSTED-SSL-CERT. |
--cert-expiration=CA_CERT_EXPIRE | The expiration date of the public CA certificate. The default is the number of days until one day prior to epoch rollover (or 01-18-2038). |
--set-country=COUNTRY_CODE | The two-letter country code. The default is US. |
--set-state=STATE_OR_PROVINCE | The state or province of the CA. The default is ''. |
--set-city=CITY_OR_LOCALITY | The city or locality. The default is ''. |
--set-org=ORGANIZATION | The company or organization, such as Red Hat. The default is Example Corp. Inc. |
--set-org-unit=SET_ORG_UNIT | The organizational unit, such as RHN. The default is ''. |
--set-common-name=HOSTNAME | Not typically set for the CA. - The common name. |
--set-email=EMAIL | Not typically set for the CA. - The email address. |
--rpm-packager=PACKAGER | Packager of the generated RPM, such as "RHN Admin (rhn-admin@example.com)." |
--rpm-vendor=VENDOR | Vendor of the generated RPM, such as "IS/IT Example Corp." |
-v, --verbose | Display verbose messaging. Accumulative - added "v"s result in increasing detail. |
--ca-cert-rpm=CA_CERT_RPM | Rarely changed - RPM name that houses the CA certificate (the base filename, not filename-version-release.noarch.rpm). |
--key-only | Rarely used - Generate only a CA private key. Review --gen-ca --key-only --help for more information. |
--cert-only | Rarely used - Generate only a CA public certificate. Review --gen-ca --cert-only --help for more information. |
--rpm-only | Rarely used - Generate only an RPM for deployment. Review --gen-ca --rpm-only --help for more information. |
--no-rpm | Rarely used - Conduct all CA-related steps except RPM generation. |
--gen-server argument:
Table 3.2. SSL Web Server Options (rhn-ssl-tool --gen-server --help)
| Option | Description |
|---|---|
--gen-server | Generate the Web server's SSL key set, RPM and tar archive. This must be issued with any of the remaining options in this table. |
-h, --help | Display the help screen with a list of base options specific to generating and managing a server key-pair. |
-p=, --password=PASSWORD | The CA password. You will be prompted for this if it's missing. Record it in a safe manner. |
-d=, --dir=BUILD_DIRECTORY | Required for most commands - The directory where certificates and RPMs are built. The default is ./ssl-build. |
--server-key=FILENAME | The Web server's SSL private key filename. The default is server.key. |
--server-cert-req=FILENAME | The Web server's SSL certificate request filename. The default is server.csr. |
--server-cert=FILENAME | The Web server's SSL certificate filename. The default is server.crt. |
--startdate=YYMMDDHHMMSSZ | The start date for server certificate validity in the example format: year, month, date, hour, minute, second (two characters per value). Z stands for Zulu and is required. The default is one week before generation. |
--cert-expiration=SERVER_CERT_EXPIRE | The expiration date of the server certificate. The default is the number of days until one day prior to epoch rollover (or 01-18-2038). |
--set-country=COUNTRY_CODE | The two-letter country code. The default is US. |
--set-state=STATE_OR_PROVINCE | The state or province. The default is North Carolina. |
--set-city=CITY_OR_LOCALITY | The city or locality. The default is Raleigh. |
--set-org=ORGANIZATION | The company or organization, such as Red Hat. The default is Example Corp. Inc. |
--set-org-unit=SET_ORG_UNIT | The organizational unit, such as RHN. The default is unit. |
--set-hostname=HOSTNAME | The hostname of the RHN Server to receive the key. The default is dynamically set to the build machine's hostname. |
--set-email=EMAIL | The email address of the certificate contact. The default is admin@example.corp. |
--rpm-packager=PACKAGER | Packager of the generated RPM, such as "RHN Admin (rhn-admin@example.com)." |
--rpm-vendor=VENDOR | Vendor of the generated RPM, such as "IS/IT Example Corp." |
-v, --verbose | Display verbose messaging. Accumulative - added "v"s result in increasing detail. |
--key-only | Rarely used - Generate only a server private key. Review --gen-server --key-only --help for more information. |
--cert-req-only | Rarely used - Generate only a server certificate request. Review --gen-server --cert-req-only --help for more information. |
--cert-only | Rarely used - Generate only a server certificate. Review --gen-server --cert-only --help for more information. |
--rpm-only | Rarely used - Generate only an RPM for deployment. Review --gen-server --rpm-only --help for more information. |
--no-rpm | Rarely used - Conduct all server-related steps except RPM generation. |
--server-rpm=SERVER_RPM | Rarely changed - RPM name that houses the Web server's SSL key set (the base filename, not filename-version-release.noarch.rpm). |
--server-tar=SERVER_TAR | Rarely changed - Name of .tar archive of the Web server's SSL key set and CA public certificate that is used solely by the hosted RHN Proxy Server installation routines (the base filename, not filename-version-release.tar). |
3.2.3. Generating the Certificate Authority SSL Key Pair
/root/ssl-build (or /etc/sysconfig/rhn/ssl for older Satellites and Proxies). To generate a CA SSL key pair, issue a command like this:
rhn-ssl-tool --gen-ca --password=MY_CA_PASSWORD --dir="/root/ssl-build"\--set-state="North Carolina" --set-city="Raleigh" --set-org="Example Inc."\--set-org-unit="SSL CA Unit"
RHN-ORG-PRIVATE-SSL-KEY— the CA SSL private keyRHN-ORG-TRUSTED-SSL-CERT— the CA SSL public certificaterhn-org-trusted-ssl-cert-VER-REL.noarch.rpm— the RPM prepared for distribution to client systems. It contains the CA SSL public certificate (above) and installs it in this location:/usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERTrhn-ca-openssl.cnf— the SSL CA configuration filelatest.txt— always lists the latest versions of the relevant files.
3.2.4. Generating Web Server SSL Key Sets
--set-hostname is different for each server. In other words, a distinct set of SSL keys and certificates must be generated and installed for every distinct RHN server hostname.
/root/ssl-build/MACHINE_NAME. To generate server certificates, issue a command like this:
rhn-ssl-tool --gen-server --password=MY_CA_PASSWORD --dir="/root/ssl-build"\--set-state="North Carolina" --set-city="Raleigh" --set-org="Example Inc."\--set-org-unit="IS/IT" --set-email="admin@example.com"\--set-hostname="rhnbox1.example.com
server.key— the Web server's SSL private server keyserver.csr— the Web server's SSL certificate requestserver.crt— the web server's SSL public certificaterhn-org-httpd-ssl-key-pair-MACHINE_NAME-VER-REL.noarch.rpm— the RPM prepared for distribution to RHN Servers. Its associated src.rpm file is also generated. This RPM contains the above three files. It will install them in these locations:/etc/httpd/conf/ssl.key/server.key/etc/httpd/conf/ssl.csr/server.csr/etc/httpd/conf/ssl.crt/server.crt
- rhn-server-openssl.cnf — the Web server's SSL configuration file
latest.txt— always lists the latest versions of the relevant files.
httpd service must be restarted after installation:
/sbin/service httpd restart 3.3. Deploying the CA SSL Public Certificate to Clients
/var/www/html/pub/ directory of the RHN Server.
http://proxy-or-sat.example.com/pub/.
wget or curl. For example:
curl -Ohttp://proxy-or-sat.example.com/pub/RHN-ORG-TRUSTED-SSL-CERT
wgethttp://proxy-or-sat.example.com/pub/RHN-ORG-TRUSTED-SSL-CERT
/pub directory, it can be installed on a client system directly:
rpm -Uvh\http://proxy-or-sat.example.com/pub/rhn-org-trusted-ssl-cert-VER-REL.noarch.rpm
3.4. Configuring Client Systems
/usr/share/rhn directory.
Chapter 4. Importing Custom GPG Keys
cp /some/path/YOUR-RPM-GPG-KEY /var/www/html/pub/
wget -O- -q http://your_proxy_or_sat.your_domain.com/pub/YOUR-RPM-GPG-KEY-O- option sends results to standard output while the -q option sets Wget to run in quiet mode. Remember to replace the YOUR-RPM-GPG-KEY variable with the filename of your key.
rpm --import /path/to/YOUR-RPM-GPG-KEY
gpg $(up2date --gpg-flags) --import /path/to/YOUR-RPM-GPG-KEYChapter 5. Using RHN Bootstrap
/usr/bin/rhn-bootstrap, serves that purpose and comes installed by default on both RHN Satellite Server and RHN Proxy Server.
- Redirect client applications to the RHN Proxy or Satellite
- Import custom GPG keys
- Install SSL certificates
- Register the system to RHN and particular system groups and channels with the help of activation keys
- Perform miscellaneous post-configuration activities, including updating packages, performing reboots, and altering RHN configuration
bootstrap.sh is automatically placed in the /var/www/html/pub/bootstrap/ directory of the RHN Server. From there it can be downloaded and run on all client systems. Note that some preparation and post-generation editing is required, as identified in the following sections. Refer to Section 5.4, “RHN Bootstrap Options” for the tool's complete list of options. Finally, refer to the Appendix A, Sample Bootstrap Script for an example script.
5.1. Preparation
rhn-bootstrap) depends on other components of the Red Hat Network infrastructure to properly configure client systems, those components must be prepared before script generation. The following list identifies suggested initial measures:
- Generate activation keys to be called by the script(s). Activation keys can be used to register Red Hat Enterprise Linux systems, entitle them to an RHN service level, and subscribe them to specific channels and system groups, all in one action. Note that you must have Management entitlements available to use an activation key, while inclusion of multiple activation keys at once requires Provisioning entitlements. Generate activation keys through the Activation Keys page within the Systems category of the RHN website (either the central RHN Servers for Proxy or the fully qualified domain name of the Satellite). Refer to the Red Hat Update Agent and RHN Website chapters of the RHN Reference Guide for instructions on creation and use.
- Red Hat recommends your RPMs be signed by a custom GNU Privacy Guard (GPG) key. Make the key available so you may refer to it from the script. Generate the key as described in the RHN Channel Management Guide and place the key in the
/var/www/html/pub/directory of the RHN Server, per Chapter 4, Importing Custom GPG Keys. - If you wish to use the script to deploy your CA SSL public certificate, have the certificate or the package (RPM) containing that certificate available on that RHN Server and include it during script generation with the
--ssl-certoption. Refer to Chapter 3, SSL Infrastructure for details. - Have the values ready to develop one or many bootstrap scripts, depending on the variety of systems to be reconfigured. Since RHN Bootstrap provides a full set of reconfiguration options, you may use it to generate different bootstrap scripts to accommodate each type of system. For instance,
bootstrap-web-servers.shmight be used to reconfigure your Web servers, whilebootstrap-app-servers.shcan handle the application servers. Consult Section 5.4, “RHN Bootstrap Options” for the complete list.
5.2. Generation
rhn-bootstrap command followed by the desired options and values. If no options are included, a bootstrap.sh file is created in the bootstrap/ subdirectory that contains the essential values derived from the server, including hostname, the SSL certificate, it if exists, SSL and GPG settings, and a call for the client-config-overrides.txt file.
- Use the
--activation-keysoption to include keys, taking into account the entitlement requirements identified in Section 5.1, “Preparation”. - Use the
--gpg-keyoption to identify the key path and filename during script generation. Otherwise, use the--no-gpgoption to turn off this verification on client systems. Red Hat recommends retaining this security measure. - Include the
--allow-config-actionsflag to enable remote configuration management on all client systems touched by the script. This feature is useful in reconfiguring multiple systems simultaneously. - Include the
--allow-remote-commandsflag to enable remote script use on all client systems. Like configuration management, this feature aids in reconfiguring multiple systems.
rhn-bootstrap --activation-keys KEY1,KEY2\--gpg-key /var/www/html/pub/MY_CORPORATE_PUBLIC_KEY\--allow-config-actions\--allow-remote-commands
5.3. Script Use
/var/www/html/pub/bootstrap/ directory and run the following command, altering the hostname and name of the script as needed to suit the system type:
catbootstrap-EDITED-NAME.sh|sshroot@CLIENT_MACHINE1/bin/bash
wget or curl to retrieve and run the script from every client system. Log into each client machine and issue the following command, altering script and hostname accordingly:
wget -qO -\https://your-satellite.example.com/pub/bootstrap/bootstrap-EDITED-NAME.sh\ |/bin/bash
curl:
curl -Sks\https://your-satellite.example.com/pub/bootstrap/bootstrap-EDITED-NAME.sh\ |/bin/bash
5.4. RHN Bootstrap Options
rhn-bootstrap --help or reviewing its man page.
Table 5.1. RHN Bootstrap Options
| Option | Description |
|---|---|
-h, --help | Display the help screen with a list of options specific to generating the bootstrap script. |
--activation-keys=ACTIVATION_KEYS | activation key(s) as defined in the RHN website with multiple entries separated by a comma and no space |
--overrides=OVERRIDES | Configuration overrides filename. The default is client-config-overrides.txt. |
--script=SCRIPT | The bootstrap script filename. The default is bootstrap.sh. |
--hostname=HOSTNAME | The fully qualified domain name (FQDN) of the server to which client systems will connect. |
--ssl-cert=SSL_CERT | The path to your organization's public SSL certificate, either a package or a raw certificate. It will be copied to the --pub-tree option. A value of "" will force a search of --pub-tree. |
--gpg-key=GPG_KEY | The path to your organization's public GPG key, if used. It will be copied to the location specified by the --pub-tree option. |
--http-proxy=HTTP_PROXY | The HTTP proxy setting for the client systems in the form hostname:port. A value of "" disables this setting. |
--http-proxy-username=HTTP_PROXY_USERNAME | If using an authenticating HTTP proxy, specify a username. A value of "" disables this setting. |
--http-proxy-password=HTTP_PROXY_PASSWORD | If using an authenticating HTTP proxy, specify a password. |
--allow-config-actions | Boolean; including this option sets the system to allow all configuration actions via RHN. This requires installing certain rhncfg-* packages, possibly through an activation key. |
--allow-remote-commands | Boolean; including this option sets the system to allow arbitrary remote commands via RHN. This requires installing certain rhncfg-* packages, possibly through an activation key. |
--no-ssl | Not recommended - Boolean; including this option turns SSL off on the client system. |
--no-gpg | Not recommended - Boolean; including this option turns GPG checking off on the client system. |
--no-up2date | Not recommended - Boolean; including this option ensures up2date will not run once the system has been bootstrapped. |
--pub-tree=PUB_TREE | Change not recommended - The public directory tree where the CA SSL certificate and package will land; the bootstrap directory and scripts. The default is /var/www/html/pub/. |
--force | Not recommended - Boolean; including this option forces bootstrap script generation despite warnings. |
-v, --verbose | Display verbose messaging. Accumulative; -vvv causes extremely verbose messaging. |
Chapter 6. Manually Scripting the Configuration
rhn_register does not exist on Red Hat Enterprise Linux 3 or later:
# First, install the latest client RPMs to the system. rpm -Uvh \ http://proxy-or-sat.example.com.com/pub/rhn_register-2.8.27-1.7.3.i386.rpm \ http://proxy-or-sat.example.com.com/pub/rhn_register-gnome-2.8.27-1.7.3.i386.rpm \ http://proxy-or-sat.example.com.com/pub/up2date-3.0.7-1.i386.rpm \ http://proxy-or-sat.example.com.com/pub/up2date-gnome-3.0.7-1.i386.rpm # Second, reconfigure the clients to talk to the correct server. perl -p -i -e 's/s/www\.rhns\.redhat\.com/proxy-or-sat\.example\.com/g' \ /etc/sysconfig/rhn/rhn_register \ /etc/sysconfig/rhn/up2date # Third, install the SSL client certificate for your company's # RHN Satellite Server or RHN Proxy Server. rpm -Uvh http://proxy-or-sat.example.com/pub/rhn-org-trusted-ssl-cert-*.noarch.rpm # Fourth, reconfigure the clients to use the new SSL certificate. perl -p -i -e 's/^sslCA/#sslCA/g;' \ /etc/sysconfig/rhn/up2date /etc/sysconfig/rhn/rhn_register echo "sslCACert=/usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT" \ >> /etc/sysconfig/rhn/up2date echo "sslCACert=/usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT" \ >> /etc/sysconfig/rhn/rhn_register # Fifth, download the GPG key needed to validate custom packages. wget -O - -q http://proxy-or-sat.example.com.com/pub/YOUR-RPM-GPG-KEY # Sixth, import that GPG key to your GPG keyring. rpm --import /path/to/YOUR-RPM-GPG-KEY
gpg $(up2date --gpg-flags) --import/path/to/YOUR-RPM-GPG-KEY
/pub/ directory of the server, running wget -O- on it, and piping the output to a shell session, one may run the entire bootstrap process with a single command from each client:
wget -O -http://proxy-or-sat.example.com.com/pub/bootstrap_script|bash
Warning
Chapter 7. Implementing Kickstart
rhnreg_ks utility that comes with the up2date and rhn_register RPMs. This chapter discusses the proper use of rhnreg_ks to register systems.
rhnreg_ks utility uses activation keys to register, entitle, and subscribe systems to specified channels in one swift motion. To find out more about activation keys, refer to the Red Hat Update Agent and RHN Website chapters of the Red Hat Network Management Reference Guide.
# Generic 7.2 kickstart for laptops in the Widget Corporation (widgetco) # Standard kickstart options for a network-based install. For an # explanation of these options, consult the Red Hat Linux Customization # Guide. lang en_US langsupport --default en_US en_US keyboard defkeymap network --bootproto dhcp install url --url ftp://ftp.widgetco.com/pub/redhat/linux/7.2/en/os/i386 zerombr yes clearpart --all part /boot --size 128 --fstype ext3 --ondisk hda part / --size 2048 --grow --fstype ext3 --ondisk hda part /backup --size 1024 --fstype ext3 --ondisk hda part swap --size 512 --ondisk hda bootloader --location mbr timezone America/New_York rootpw --iscrypted $1$78Jnap82Hnd0PsjnC8j3sd2Lna/Hx4. auth --useshadow --enablemd5 --krb5realm .COM --krb5kdc auth.widgetco.com \ --krb5adminserver auth.widgetco.com mouse --emulthree genericps/2 xconfig --card "S3 Savage/MX" --videoram 8192 --resolution 1024x768 \ --depth 16 --defaultdesktop=GNOME --startxonboot --noprobe \ --hsync 31.5-48.5 --vsync 40-70 reboot # Define a standard set of packages. Note: Red Hat Network client # packages are found in Base. This is quite a minimal set of packages; # your mileage may vary. %packages @ Base @ Utilities @ GNOME @ Laptop Support @ Dialup Support @ Software Development @ Graphics and Image Manipulation @ Games and Entertainment @ Sound and Multimedia Support # Now for the interesting part. %post ( # Note that we run the entire %post section as a subshell for logging. # Remember that nifty one-line command for the bootstrap script that we # went through? This is an ideal place for it. And assuming that the # script has been properly configured, it should prepare the system # fully for usage of local Red Hat Network Servers. wget -O- http://proxy-or-sat.example.com/pub/bootstrap_script | /bin/bash # The following is an example of the usage of rhnreg_ks, the kickstart # utility for rhn_register. This demonstrates the usage of the # --activationkey flag, which describes an activation key. For example, # this activation key could be set up in the Web interface to join this # system to the "Laptops" group and the local Widgetco "Laptop Software" # channel. Note that this section applies only to Proxy users, as this # step is handled by the Satellite bootstrap script. # # For more information about activation keys, consult the Red Hat Network # Management Reference Guide. /usr/sbin/rhnreg_ks --activationkey=6c933ea74b9b002f3ac7eb99619d3374 # End the subshell and capture any output to a post-install log file. ) 1>/root/post_install.log 2>&1
Appendix A. Sample Bootstrap Script
/var/www/html/pub/bootstrap/bootstrap.sh script generated by the RHN Satellite Server installation program provides the ability to reconfigure client systems to access your RHN Server easily. It is available to both RHN Satellite Server and RHN Proxy Server customers through the RHN Bootstrap tool. After modifying the script for your particular use, it can be run on each client machine.
#!/bin/bash echo "RHN Server Client bootstrap script v3.6" # This file was autogenerated. Minor manual editing of this script (and # possibly the client-config-overrides.txt file) may be necessary to complete # the bootstrap setup. Once customized, the bootstrap script can be triggered # in one of two ways (the first is preferred): # # (1) centrally, from the RHN Server via ssh (i.e., from the # RHN Server): # cd /var/www/html/pub/bootstrap/ # cat bootstrap-<edited_name>.sh | ssh root@<client-hostname> /bin/bash # # ...or... # # (2) in a decentralized manner, executed on each client, via wget or curl: # wget -qO- # https://<hostname>/pub/bootstrap/bootstrap-<edited_name>.sh \ # | /bin/bash # ...or... # curl -Sks # https://<hostname>/pub/bootstrap/bootstrap-<edited_name>.sh \ # | /bin/bash # SECURITY NOTE: # Use of these scripts via the two methods discussed is the most expedient # way to register machines to your RHN Server. Since "wget" is used # throughout the script to download various files, a "Man-in-the-middle" # attack is theoretically possible. # # The actual registration process is performed securely via SSL, so the risk # is minimized in a sense. This message merely serves as a warning. # Administrators need to appropriately weigh their concern against the # relative security of their internal network. # PROVISIONING/KICKSTART NOTE: # If provisioning a client, ensure the proper CA SSL public certificate is # configured properly in the post section of your kickstart profiles (the # RHN Satellite or hosted web user interface). # UP2DATE/RHN_REGISTER VERSIONING NOTE: # This script will not work with very old versions of up2date and # rhn_register. echo echo echo "MINOR MANUAL EDITING OF THIS FILE MAY BE REQUIRED!" echo echo "If this bootstrap script was created during the initial installation" echo "of an RHN Satellite, the ACTIVATION_KEYS, and ORG_GPG_KEY values will" echo "probably *not* be set (see below). If this is the case, please do the" echo "following:" echo " - copy this file to a name specific to its use." echo " (e.g., to bootstrap-SOME_NAME.sh - like bootstrap-web-servers.sh.)" echo " - on the website create an activation key or keys for the system(s) to" echo " be registered." echo " - edit the values of the VARIABLES below (in this script) as" echo " appropriate:" echo " - ACTIVATION_KEYS needs to reflect the activation key(s) value(s)" echo " from the website. XKEY or XKEY,YKEY" echo " - ORG_GPG_KEY needs to be set to the name of the corporate public" echo " GPG key filename (residing in /var/www/html/pub) if appropriate." echo echo "Verify that the script variable settings are correct:" echo " - CLIENT_OVERRIDES should be only set differently if a customized" echo " client-config-overrides-VER.txt file was created with a different" echo " name." echo " - ensure the value of HOSTNAME is correct." echo " - ensure the value of ORG_CA_CERT is correct." echo echo "Enable this script: comment (with #'s) this block (or, at least just" echo "the exit below)" echo exit 1 # can be edited, but probably correct (unless created during initial install): # NOTE: ACTIVATION_KEYS *must* be used to bootstrap a client machine. ACTIVATION_KEYS=insert_activation_key_here ORG_GPG_KEY=insert_org_gpg_pub_key_here # can be edited, but probably correct: CLIENT_OVERRIDES=client-config-overrides.txt HOSTNAME=your_rhn_server_host.example.com ORG_CA_CERT=RHN-ORG-TRUSTED-SSL-CERT ORG_CA_CERT_IS_RPM_YN=0 USING_SSL=1 USING_GPG=1 REGISTER_THIS_BOX=1 ALLOW_CONFIG_ACTIONS=0 ALLOW_REMOTE_COMMANDS=0 FULLY_UPDATE_THIS_BOX=1 # # ----------------------------------------------------------------------------- # DO NOT EDIT BEYOND THIS POINT ----------------------------------------------- # ----------------------------------------------------------------------------- # # an idea from Erich Morisse (of Red Hat). # use either wget *or* curl # Also check to see if the version on the # machine supports the insecure mode and format # command accordingly. if [ -x /usr/bin/wget ] ; then output=`/usr/bin/wget --no-check-certificate 2>&1` error=`echo $output | grep "unrecognized option"` if [ -z "$error" ] ; then FETCH="/usr/bin/wget -q -r -nd --no-check-certificate" else FETCH="/usr/bin/wget -q -r -nd" fi else if [ -x /usr/bin/curl ] ; then output=`/usr/bin/curl -k 2>&1` error=`echo $output | grep "is unknown"` if [ -z "$error" ] ; then FETCH="/usr/bin/curl -SksO" else FETCH="/usr/bin/curl -SsO" fi fi fi HTTP_PUB_DIRECTORY=http://${HOSTNAME}/pub HTTPS_PUB_DIRECTORY=https://${HOSTNAME}/pub if [ $USING_SSL -eq 0 ] ; then HTTPS_PUB_DIRECTORY=${HTTP_PUB_DIRECTORY} fi echo echo "UPDATING RHN_REGISTER/UP2DATE CONFIGURATION FILES" echo "-------------------------------------------------" echo "* downloading necessary files" echo " client_config_update.py..." rm -f client_config_update.py $FETCH ${HTTPS_PUB_DIRECTORY}/bootstrap/client_config_update.py echo " ${CLIENT_OVERRIDES}..." rm -f ${CLIENT_OVERRIDES} $FETCH ${HTTPS_PUB_DIRECTORY}/bootstrap/${CLIENT_OVERRIDES} if [ ! -f "client_config_update.py" ] ; then echo "ERROR: client_config_update.py was not downloaded" exit 1 fi if [ ! -f "${CLIENT_OVERRIDES}" ] ; then echo "ERROR: ${CLIENT_OVERRIDES} was not downloaded" exit 1 fi echo "* running the update scripts" if [ -f "/etc/sysconfig/rhn/rhn_register" ] ; then echo " . rhn_register config file" /usr/bin/python -u client_config_update.py /etc/sysconfig/rhn/rhn_register \ ${CLIENT_OVERRIDES} fi echo " . up2date config file" /usr/bin/python -u client_config_update.py /etc/sysconfig/rhn/up2date \ ${CLIENT_OVERRIDES} if [ ! -z "$ORG_GPG_KEY" ] ; then echo echo "* importing organizational GPG key" rm -f ${ORG_GPG_KEY} $FETCH ${HTTPS_PUB_DIRECTORY}/${ORG_GPG_KEY} # get the major version of up2date res=$(rpm -q --queryformat '%{version}' up2date | sed -e 's/\..*//g') if [ $res -eq 2 ] ; then gpg $(up2date --gpg-flags) --import $ORG_GPG_KEY else rpm --import $ORG_GPG_KEY fi fi echo echo "* attempting to install corporate public CA cert" if [ $USING_SSL -eq 1 ] ; then if [ $ORG_CA_CERT_IS_RPM_YN -eq 1 ] ; then rpm -Uvh ${HTTP_PUB_DIRECTORY}/${ORG_CA_CERT} else rm -f ${ORG_CA_CERT} $FETCH ${HTTP_PUB_DIRECTORY}/${ORG_CA_CERT} mv ${ORG_CA_CERT} /usr/share/rhn/ fi fi echo echo "REGISTRATION" echo "------------" # Should have created an activation key or keys on the RHN Server's # website and edited the value of ACTIVATION_KEYS above. # # If you require use of several different activation keys, copy this file and # change the string as needed. # if [ -z "$ACTIVATION_KEYS" ] ; then echo "*** ERROR: in order to bootstrap RHN clients, an activation key or keys" echo " must be created in the RHN web user interface, and the" echo " corresponding key or keys string (XKEY,YKEY,...) must be mapped to" echo " the ACTIVATION_KEYS variable of this script." exit 1 fi if [ $REGISTER_THIS_BOX -eq 1 ] ; then echo "* registering" /usr/sbin/rhnreg_ks --force --activationkey "$ACTIVATION_KEYS" echo echo "*** this system should now be registered, please verify ***" echo else echo "* explicitely not registering" fi echo echo "OTHER ACTIONS" echo "------------------------------------------------------" if [ $FULLY_UPDATE_THIS_BOX -eq 1 ] ; then echo "up2date up2date; up2date -p; up2date -uf (conditional)" else echo "up2date up2date; up2date -p" fi echo "but any post configuration action can be added here. " echo "------------------------------------------------------" if [ $FULLY_UPDATE_THIS_BOX -eq 1 ] ; then echo "* completely updating the box" else echo "* ensuring up2date itself is updated" fi /usr/sbin/up2date up2date /usr/sbin/up2date -p if [ $FULLY_UPDATE_THIS_BOX -eq 1 ] ; then /usr/sbin/up2date -uf fi echo "-bootstrap complete-" Appendix B. Revision History
| Revision History | |||
|---|---|---|---|
| Revision 2.0-1.400 | 2013-12-18 | ||
| |||
| Revision 2.0-1 | Fri Nov 1 2013 | ||
| |||
Index
Symbols
- --configure
- use of, Using the --configure Option
A
- activation keys
- registering with, Registering with Activation Keys
B
- bootstrap.sh
- preparation and use, Using RHN Bootstrap
- sample file, Sample Bootstrap Script
C
- client applications
- configuration of, Configuring the Client Applications
- installation of, Deploying the Latest Red Hat Network Client RPMs
- client configuration
- Red Hat Network Registration Client , Using the --configure Option
- Red Hat Update Agent , Using the --configure Option
- configuration
- manual, Updating the Configuration Files Manually
- scripting completely, Manually Scripting the Configuration
- server failover, Implementing Server Failover
G
- GPG keys
- importing of, Importing Custom GPG Keys
K
- kickstart
- use of, Implementing Kickstart
R
- Red Hat Network Alert Notification Tool
- configuration for Satellite, Configuring the Red Hat Network Alert Notification Tool with Satellite
- Red Hat Network Registration Client
- configuring to use RHN Proxy Server or RHN Satellite Server, Updating the Configuration Files Manually
- Red Hat Network SSL Maintenance Tool
- generating the CA, Generating the Certificate Authority SSL Key Pair
- generating the server certificate, Generating Web Server SSL Key Sets
- generation explained, SSL Generation Explained
- options, Red Hat Network SSL Maintenance Tool Options
- rhn-ssl-tool , The Red Hat Network SSL Maintenance Tool
- Red Hat Update Agent
- configuring to use RHN Proxy Server or RHN Satellite Server, Updating the Configuration Files Manually
- RHN Bootstrap
- command line options, RHN Bootstrap Options
- generating the script, Generation
- preparing, Preparation
- using, Using RHN Bootstrap
- using the script, Script Use
- rhn-ssl-tool
- generating the CA, Generating the Certificate Authority SSL Key Pair
- generating the server certificate, Generating Web Server SSL Key Sets
- generation explained, SSL Generation Explained
- options, Red Hat Network SSL Maintenance Tool Options
- Red Hat Network SSL Maintenance Tool , The Red Hat Network SSL Maintenance Tool
S
- SSL (Secure Sockets Layer)
- introduction, A Brief Introduction To SSL
- SSL certificates
- configuration of, Configuring Client Systems
- generating, The Red Hat Network SSL Maintenance Tool
- installation of, Deploying the CA SSL Public Certificate to Clients
