Red Hat NETWORK 3.7 - User manual

Red Hat Network 3.7
Client Configuration Guide

Red Hat Network 3.7: Client Configuration Guide
Copyright © 2001 - 2005 by Red Hat, Inc.
Red Hat, Inc.
1801 Varsity Drive
Raleigh NC 27606-2072 USA
Phone: [phone]
Phone: [phone]
Fax: [phone]
PO Box 13588
Research Triangle Park NC 27709 USA
RHNclient-config(EN)-3.7-RHI (2005-03-16T12:14)
Copyright © 2005 by Red Hat, Inc. This material may be distributed only subject to the terms and conditions set forth in the
Open Publication License, V1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/).
Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright
holder.
Distribution of the work or derivative of the work in any standard (paper) book form for commercial purposes is prohibited
unless prior permission is obtained from the copyright holder.
Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other
countries.
All other trademarks referenced herein are the property of their respective owners.
The GPG fingerprint of the [email protected] key is:
CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E

Table of Contents
1. Introduction..................................................................................................................................... 1
2. Client Applications.......................................................................................................................... 3
2.1. Deploying the Latest Red Hat Network Client RPMs ....................................................... 3
2.2. Configuring the Client Applications .................................................................................. 3
2.2.1. Registering with Activation Keys ....................................................................... 4
2.2.2. Using the --configure Option ........................................................................ 4
2.2.3. Updating the Configuration Files Manually ....................................................... 6
2.2.4. Implementing Server Failover............................................................................. 7
2.3. Configuring the Red Hat Network Alert Notification Tool with Satellite...................... 8
3. SSL Infrastructure.......................................................................................................................... 9
3.1. A Brief Introduction To SSL.............................................................................................. 9
3.2. The RHN SSL Maintenance Tool.................................................................................. 10
3.2.1. SSL Generation Explained................................................................................ 11
3.2.2. RHN SSL Maintenance Tool Options ............................................................ 11
3.2.3. Generating the Certificate Authority SSL Key Pair.......................................... 14
3.2.4. Generating Web Server SSL Key Sets .............................................................. 15
3.3. Deploying the CA SSL Public Certificate to Clients ....................................................... 16
3.4. Configuring Client Systems ............................................................................................. 16
4. Importing Custom GPG Keys...................................................................................................... 17
5. Using RHN Bootstrap ................................................................................................................... 19
5.1. Preparation ....................................................................................................................... 19
5.2. Generation........................................................................................................................ 20
5.3. Script Use......................................................................................................................... 20
5.4. RHN Bootstrap Options ................................................................................................. 21
6. Manually Scripting the Configuration........................................................................................ 23
7. Implementing Kickstart ............................................................................................................... 25
A. Sample Bootstrap Script.............................................................................................................. 27
Index................................................................................................................................................... 31

Chapter 1.
Introduction
This best practices guide is intended to help customers of RHN Satellite Server and RHN Proxy Server
more easily configure their client systems.
By default, all Red Hat Network client applications are configured to communicate with central Red
Hat Network Servers. When connecting clients to RHN Satellite Server or RHN Proxy Server, how-
ever, many of these settings must be altered. Altering client settings for a system or two may be
relatively simple. But a large enterprise environment, containing hundreds or thousands of systems,
will likely benefit from the mass reconfiguration steps described here.
Because of the complexity of this undertaking, customers have been given the option of generating and
using a pre-populated script that automates many of the tasks required to get your systems using your
RHN Server. Refer to Chapter 5 Using RHN Bootstrap for details. Nevertheless, Red Hat believes
you should understand the implications of these changes and therefore describes the manual steps for
reconfiguration in earlier chapters. Use your best judgement in determining the ideal solution for your
organization.
Although many of the commands provided within this guide can be applied as they appear, it is impos-
sible to predict all of the potential network configurations adopted by customers. Therefore, Red Hat
encourages you to use these commands as references that must take into account your organization’s
individual settings.

2 Chapter 1. Introduction

Chapter 2.
Client Applications
Most of the enterprise-class features of Red Hat Network have required changes to the Red Hat Net-
work client applications themselves. Of course, it’s difficult to get the latest versions of these applica-
tions until the systems are registered with Red Hat Network. This sort of chicken-and-egg problem is
especially problematic for customers who want to migrate large numbers of older systems to Red Hat
Network. This chapter identifies techniques that may be used to resolve this dilemma.
Important
Red Hat strongly recommends that clients connected to RHN Proxy Server or RHN Satellite Server
be running the latest update of Red Hat Enterprise Linux to ensure proper connectivity.
2.1. Deploying the Latest Red Hat Network Client RPMs
Since Red Hat Update Agent (up2date) and Red Hat Network Registration Client
(rhn_register) are prerequisites for using much of Red Hat Network’s enterprise functionality,
it’s crucial to install them before trying to use RHN Proxy Server or RHN Satellite Server in your
environment.
There are several sensible approaches to doing this, but they are all similar; each involves storing the
RPMs somewhere that is accessible by all client systems and deploying the packages with the simplest
command possible. This command will vary from organization to organization.
Remember, only systems running Red Hat Enterprise Linux 2.1 need to use the Red Hat Network
Registration Client to register with RHN. Systems running Red Hat Enterprise Linux 3 and later can
use the registration functionality built into the Red Hat Update Agent.
This document presumes that the customer has installed RHN Satellite Server and/or RHN Proxy
Server on the customer network. With either server type, the latest versions of both up2date and
rhn_register should have been downloaded and installed to the RHN Satellite Server or RHN
Proxy Server itself, as part of the importing process used to get the package repository populated and
up-to-date. Known working versions of both applications are placed in the /var/www/html/pub/
directory of the Proxy or Satellite.
Confirm the precise paths of the client packages before running the following command, as they may
not reside in the top-level /pub directory but instead in its subdirectories. When run from a client, this
command would then install these 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.8.27-1.7.3.i386.rpm \
http://your_proxy_or_sat.your_domain.com/pub/rhn_register-gnome-2.8.27-1.7.3.i386.rpm \
http://your_proxy_or_sat.your_domain.com/pub/up2date-3.0.7-1.i386.rpm \
http://your_proxy_or_sat.your_domain.com/pub/up2date-gnome-3.0.7-1.i386.rpm
Note the inclusion of the associated gnome RPMs. Keep in mind, the architecture (in this case, i386)
may need to be altered depending on the systems to be served.

4 Chapter 2. Client Applications
2.2. Configuring the Client Applications
Not every customer will need to connect securely to an RHN Satellite Server or RHN Proxy Server
within their organization. And not every customer will need to build and deploy a GPG key for custom
packages. (Both of these topics are explained in detail later.) But every customer who uses RHN Satel-
lite Server or RHN Proxy Server will need to reconfigure the Red Hat Update Agent (up2date) and
possibly the Red Hat Network Registration Client (rhn_register) to be directed to the Satellite
or Proxy.
Important
Although this isn’t configurable, users should still make note that the port used by the Red Hat Update
Agent is 443 for SSL (HTTPS) and 80 for non-SSL (HTTP). By default, up2date uses SSL only. For
this reason, users should ensure their firewalls allow connections over port 443. To bypass SSL, in
/etc/sysconfig/rhn/up2date change the protocol for serverURL from https to http. Similarly,
if you will be using RHN’s Monitoring feature and probes requiring the Red Hat Network Monitoring
Daemon, note that client systems will need to allow connections on port 4545 (or port 22, if they will
use sshd instead).
By default, the Red Hat Network Registration Client and the Red Hat Update Agent refer to the
main Red Hat Network Servers. Users must reconfigure client systems to refer to the RHN Satellite
Server or RHN Proxy Server. This can be done in three different ways: using the --configure op-
tion, updating the configuration file(s) manually, or scripting a change to multiple settings at once. To
see how virtually all reconfiguration can be scripted, see Chapter 6 Manually Scripting the Configu-
ration.
Note that the latest versions of the Red Hat Update Agent can be configured to accommodate several
RHN Servers, thereby providing failover protection in case the primary server is inaccessible. Refer
to Section 2.2.4 Implementing Server Failover for instructions on enabling this feature.
2.2.1. Registering with Activation Keys
Red Hat recommends using activation keys for registering and configuring client systems that will
be using RHN Proxy Server or RHN Satellite Server. Activation keys can be used to register, entitle,
and subscribe systems in a batch. Refer to the Activation Keys section of the Red Hat Update Agent
chapter within the RHN Management Reference Guide for instructions on use.
It is possible to incorporate activation keys into a scripted configuration process, such as the one
described in Chapter 6 Manually Scripting the Configuration. To do this, create a bootstrap.sh file
much like the one described, place it in the Proxy or Satellite’s /pub directory and combine it with
the rhnreg_ks utility. For example:
wget -O http://your-satellite-FQDN/pub/bootstrap.sh | bash \
&& rhnreg_ks --activation-key b0fa829d751aEXAMPLE6983a72c8346e \
--serverUrl https://your-satellite-FQDN/XMLRPC
Warning
Systems running Red Hat Enterprise Linux 2.1 and versions of Red Hat Linux prior to 8.0 may
experience problems using Activation Keys to migrate SSL certificate settings from rhn_register
to up2date. All other settings, such as the server URL, will be properly transferred. Therefore, the
SSL certificate information on those systems will have to be set manually.

Chapter 2. Client Applications 5
2.2.2. Using the --configure Option
Both the Red Hat Network Registration Client and the Red Hat Update Agent that ship with
Red Hat Enterprise Linux provide interfaces for configuring various settings. For full listings of these
settings, refer to the chapters dedicated to the applications in the RHN Management Reference Guide.
Each application offers a graphical user interface (GUI) for configuration that enables you to change
the settings required by RHN Proxy Server or RHN Satellite Server. The only requirement for using
this option is to have the client systems running the X Window System. The command to launch the
GUI configuration interface will look like:
application_filename --configure
To reconfigure the Red Hat Update Agent, as root, run the following command:
up2date --configure
You are presented with a dialog box offering various settings that may be reconfigured. In the Gen-
eral tab, under 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. Then click OK.
Figure 2-1. Red Hat Update Agent GUI Configuration
Make sure you enter the domain name of your RHN Satellite Server or RHN Proxy Server correctly.
Entering an incorrect domain or leaving the field blank may prevent 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.

6 Chapter 2. Client Applications
Warning
Systems running Red Hat Enterprise Linux 3 or newer have registration functionality built into the Red
Hat Update Agent and therefore do not have the Red Hat Network Registration Client installed.
Systems running Red Hat Enterprise Linux 2.1 (and versions of Red Hat Linux prior to 8.0) still need
to reconfigure and use the Red Hat Network Registration Client, as well as the Red Hat Update
Agent.
To reconfigure the Red Hat Network Registration Client, conduct an almost identical set of steps.
As root, run the following command:
rhn_register --configure
You are presented with a dialog box offering basic settings that may be reconfigured. Under
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. Then click OK.
Figure 2-2. Red Hat Network Registration Client GUI Configuration
If your version of 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
As an alternative to the GUI interface described in the previous section, users may also reconfigure the
Red Hat Network Registration Client and the Red Hat Update Agent by editing the applications’
configuration files.

Chapter 2. Client Applications 7
To configure the Red Hat Update Agent on the client systems connecting to the RHN Proxy Server
or RHN Satellite Server, edit the values of the 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_proxy_or_sat.your_domain.com/XMLRPC
noSSLServerURL[comment]=Remote server URL without SSL
noSSLServerURL=http://your_proxy_or_sat.your_domain.com/XMLRPC
Warning
The 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).
Skip this section if you are running Red Hat Enterprise Linux 3 later on the client system.
Note
You must use version 2.7.11 or higher of rhn_register on the client systems so they can recognize
new certificates. This RPM should be available in /var/spool/up2date on your proxy system after
you run up2date for the Proxy.
To configure the Red Hat Network Registration Client on the client systems connecting to the RHN
Proxy Server or RHN Satellite Server, edit the values of the serverURL and noSSLServerURL op-
tions 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
Beginning with 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 where
your primary RHN Proxy Server or RHN Satellite Server may be taken offline.
To use this feature, first ensure you are running the required version of up2date or later. 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:

8 Chapter 2. Client Applications
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
noSSLServerhttp://your_primary.your_domain.com/XMLRPC;https://your_secondary.your_domain.com/XMLRPC
The servers are attempted in the order provided here. You can include as many servers as you wish.
You may list the central RHN Servers, as well. This makes sense, however, only if the client systems
can reach the Internet.
2.3. Configuring the Red Hat Network Alert Notification Tool with
Satellite
The Red Hat Network Alert Notification Tool, that nifty round icon in the panel of your Red Hat
desktop, can be configured on systems running Red Hat Enterprise Linux 3 or later to recognize
updates available from custom channels on your RHN Satellite Server. In addition, you must ensure
the Satellite itself is prepared to support this feature. (RHN Proxy Server supports the applet without
modification of client or server.) Here’s the flow:
1. Ensure you’re running RHN Satellite Server 3.4 or later and have the rhns-applet package
installed on the Satellite. The package can be found in the RHN Satellite software channel for
versions 3.4 and newer.
2. Install the rhn-applet-actions package on all Red Hat Enterprise Linux 3 and newer sys-
tems to be notified of custom updates with the Red Hat Network Alert Notification Tool. The
systems must be entitled to the Management or Provisioning service levels. The package can be
retrieved with up2date or through the RHN Tools software channel.
3. 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.
The next time the applet is started, it will apply its new configuration and connect to the RHN Satellite
Server for updates.

Chapter 3.
SSL Infrastructure
For Red Hat Network customers, security concerns are of the utmost importance. One of the strengths
of Red Hat Network is its ability to process every single request over Secure Sockets Layer, or SSL.
To maintain this level of security, customers installing Red Hat Network within their infrastructures
must generate custom SSL keys and certificates.
Manual creation and deployment of SSL keys and certificates can be quite involved. Both the RHN
Proxy Server and the RHN Satellite Server allow you to build your own SSL keys and certificates
based on your own private Certificate Authority (CA) during their installation. In addition, a separate
command line utility, the RHN SSL Maintenance Tool, exists for this same purpose. Regardless,
these keys and certificates must then be deployed to all systems within your managed infrastructure.
In many cases, deployment of these SSL keys and certificates is automated for you. This chapter
describes efficient methods for conducting all of these tasks.
Please note that this chapter does not explain SSL in depth. The RHN SSL Maintenance Tool was
designed to hide much of complexity involved in setting up and maintaining this public-key infras-
tructure (PKI). For more information, please consult some of the many good references available at
your nearest bookstore.
3.1. A Brief Introduction To SSL
SSL, or Secure Sockets Layer, is a protocol that enables client-server applications to pass information
securely. SSL uses a system of public and private key pairs to encrypt communication passed between
clients and servers. Public certificates can be left accessible, while private keys must be secured.
It’s the mathematical relationship (a digital signature) between a private key and its paired public
certificate that makes this system work. Through this relationship, a connection of trust is established.
Note
Throughout this document we discuss SSL private keys and public certificates. Technically both can
be referred to as keys (public and private keys). But it is convention, when discussing SSL, to refer to
the public half of an SSL key pair (or key set) as the SSL public certificate.
An organization’s SSL infrastructure is generally made up of these SSL keys and certificates:
•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 is not important to this discussion. All three are
deployed to an RHN Server.
Here’s a scenario: If you have one RHN Satellite Server and five RHN Proxy Servers, you will gener-
ate one CA SSL key pair and six Web server SSL key sets. The CA SSL public certificate is distributed
to all systems and used by all clients to establish a connection to their respective upstream servers.
Each server has its own SSL key set that is specifically tied to that server’s hostname and generated
using its own SSL private key and the CA SSL private key in combination. This establishes a digitally

10 Chapter 3. SSL Infrastructure
verifiable association between the Web server’s SSL public certificate and the CA SSL key pair and
server’s private key. The Web server’s key set cannot be shared with other web servers.
Important
The most critical portion of this system is the CA SSL key pair. From that private key and public
certificate an administrator can regenerate any Web server’s SSL key set. This CA SSL key pair
must be secured. It is highly recommended that once the entire RHN infrastructure of servers is set
up and running, you archive the SSL build directory generated by this tool and/or the installers onto
separate media, write down the CA password, and secure the media and password in a safe place.
3.2. The RHN SSL Maintenance Tool
Red Hat Network provides a command line tool to ease management of your secure infrastructure: the
RHN SSL Maintenance Tool, commonly known by its command rhn-ssl-tool. This tool, which
resides in the rhns-certs-tools package within the software channels for the latest RHN Proxy
Server and RHN Satellite Server, (as well as the Satellite ISO) enables you to generate your own
Certificate Authority SSL key pair, as well as Web server SSL key sets (sometimes called key pairs).
This tool is only a build tool though. It generates all the SSL keys and certificates that are required. It
also packages the files in RPM format for quick distribution and installation on all client machines. It
does not deploy them, however. That is left to the administrator, or in many cases, automated by the
RHN Satellite Server.
Note
The 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).
Here are the use cases for when you need to use the tool:
•When updating your CA public certificate - 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 concerns, cannot be a repository for your
CA SSL key and certificate that 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.
Here are the use cases for when you do not need to use the tool:
•During installation of an RHN Satellite Server - all SSL settings are configured during the installa-
tion 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

Chapter 3. SSL Infrastructure 11
SSL information needed to configure, build and deploy the RHN Proxy Server’s SSL keys and
certificates.
The installation procedures of both the RHN Satellite Server and the RHN Proxy Server ensure the
CA SSL public certificate is deployed to the /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.
In short, if your organization’s RHN infrastructure deploys the latest version of RHN Satellite Server
as its top-level service, you will likely have little need to use the tool. Otherwise, you will have to be
familiar with its usage.
3.2.1. SSL Generation Explained
The primary benefits of using the RHN SSL Maintenance Tool are security, flexibility, and portabil-
ity. Security is achieved through the creation of distinct Web server SSL keys and certificates for each
RHN server, all signed by a single Certificate Authority SSL key pair created by your organization.
Flexibility is supplied by the tool’s ability to work on any machine with the 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.
Again, if your infrastructure’s top-level RHN Server is the most current RHN Satellite Server, the
most you may have to do is restore your ssl-build tree from archive to the /root directory and
utilize the configuration tools provided within the RHN Satellite Server’s website.
To make the best use of the RHN SSL Maintenance Tool, you should complete the following high-
level tasks in this rough order. Refer to the remaining sections for the required details:
1. Install the rhns-certs-tools package on a system within your organization, perhaps but not
necessarily the RHN Satellite Server or RHN Proxy Server.
2. Create a single Certificate Authority SSL key pair for your organization and install the resulting
RPM or public certificate on all client systems.
3. 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
4. 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.)
5. 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.
6. Record and secure the CA password for future use.
7. Delete the build tree from the build system for security purposes, but only once the entire RHN
infrastructure is in place and configured.
8. When additional Web server SSL key sets are needed, restore the build tree on a system running
the RHN SSL Maintenance Tool and repeat steps 3 through 7.
3.2.2. RHN SSL Maintenance Tool Options
The RHN SSL Maintenance Tool offers a plethora of command line options for generating your
Certificate Authority SSL key pair and managing your server SSL certificates and keys. The tool
offers essentially three command line option help listings: 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 for
assistance: man rhn-ssl-tool.

12 Chapter 3. SSL Infrastructure
The two tables here break down the options by their related task, either CA or Web server SSL key set
generation. The first set of options (CA) should be preceded by the --gen-ca argument, while the
second set (Web server) should be preceded by the --gen-server argument.
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 RHN. 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 ([email protected])."
--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).

Chapter 3. SSL Infrastructure 13
Option Description
--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.
Table 3-1. SSL Certificate Authority (CA) Options (rhn-ssl-tool --gen-ca --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_EXPIREThe 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.

14 Chapter 3. SSL Infrastructure
Option Description
--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 [email protected].
--rpm-packager=PACKAGER Packager of the generated RPM, such as "RHN
Admin ([email protected])."
--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).
Table 3-2. SSL Web Server Options (rhn-ssl-tool --gen-server --help)
To use these options, insert the option and the appropriate value, if needed, after the rhn-ssl-tool
command and base option, where the base option is either --gen-ca or --gen-server.
3.2.3. Generating the Certificate Authority SSL Key Pair
Before creating the SSL key set required by the Web server, you must have a Certificate Authority
(CA) SSL key pair generated. A CA SSL public certificate gets distributed to client systems of the

Chapter 3. SSL Infrastructure 15
Satellite or Proxy. The RHN SSL Maintenance Tool allows you to generate a CA SSL key pair if
needed and re-use it for all subsequent RHN server deployments.
The build process automatically creates the key pair and public RPM for distribution to clients. All CA
components end up in the build directory specified at the command line, typically /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"
Replace the example values with those appropriate for your organization. This will result in the fol-
lowing relevant files in the specified build directory:
•RHN-ORG-PRIVATE-SSL-KEY — the CA SSL private key
•RHN-ORG-TRUSTED-SSL-CERT — the CA SSL public certificate
•rhn-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-CERT
•rhn-ca-openssl.cnf — the SSL CA configuration file
•latest.txt — always lists the latest versions of the relevant files.
Once finished, you’re ready to distribute the RPM to client systems. Refer to Section 3.3 Deploying
the CA SSL Public Certificate to Clients.
3.2.4. Generating Web Server SSL Key Sets
Although you must have a CA SSL key pair already generated, you will likely generate web server
SSL key sets more frequently, especially if more than one Proxy or Satellite is deployed. Note that the
value for --set-hostname is different for each server. In other words, a distinct set of SSL keys and
certificates needs to be generated and installed for every distinct RHN server hostname.
The server certificate build process works much like CA SSL key pair generation with one exception:
All server components end up in subdirectories of the build directory that reflect the build system’s
machine name, such as /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" --email="[email protected]" \
--set-hostname="rhnbox1.example.com
Replace the example values with those appropriate for your organization. This will result in the fol-
lowing relevant files in a machine-specific subdirectory of the build directory:
•server.key — the Web server’s SSL private server key
•server.csr — the Web server’s SSL certificate request
•server.crt — the web server’s SSL public certificate
•rhn-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

16 Chapter 3. SSL Infrastructure
•/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.
Once finished, you’re ready to distribute and install the RPM on its respective RHN Server. Note that
httpd service must be restarted after installation:
/sbin/service httpd restart
3.3. Deploying the CA SSL Public Certificate to Clients
Both the RHN Proxy Server and RHN Satellite Server installation processes make client deployment
relatively easy by generating a CA SSL public certificate and RPM. These installation processes make
those publicly available by placing a copy of one or both into the /var/www/html/pub/ directory
of the RHN Server.
This public directory can be inspected easily by simply browsing to it via any web browser:
http://proxy_or_sat.domain.com/pub/.
The CA SSL public certificate in that directory can be downloaded to a client system using wget or
curl. For example:
curl -O http://proxy_or_sat.domain.com/pub/RHN-ORG-TRUSTED-SSL-CERT
wget http://proxy_or_sat.domain.com/pub/RHN-ORG-TRUSTED-SSL-CERT
Alternatively, if the CA SSL public certificate RPM resides in the /pub directory, it can be installed
on a client system directly:
rpm -Uvh http://proxy_or_sat.domain.com/pub/rhn-org-trusted-ssl-cert-VER-REL.noarch.rpm
Confirm the actual name of the certificate or RPM before running any of those commands.
3.4. Configuring Client Systems
Once the RPM or raw certificate has been deployed to a client system, the administrator of that system
must then alter the configuration files of the Red Hat Update Agent and the Red Hat Network
Registration Client (if necessary) to use the new CA SSL public certificate file and connect to the
appropriate RHN Proxy Server or RHN Satellite Server. The generally accepted location for that CA
SSL public certificate is in the /usr/share/rhn directory.
The RHN Proxy Server and RHN Satellite Server both have the RHN Bootstrap installed by default,
which can greatly reduce these repetitive steps and simplify the process of registering and configuring
client systems. Please refer Chapter 5 Using RHN Bootstrap for details.