Red Hat NETWORK SATELLITE 5.3.0 - CHANNEL MANAGEMENT User manual

Red Hat Network
Satellite 5.3.0
Client Configuration Guide
Red Hat Network Satellite

Client Configuration Guide
Red Hat Network Satellite 5.3.0 Client Configuration Guide
Red Hat Network Satellite
Edition 5.3.0
Copyright © 2009 Red Hat, Inc. This material may only be distributed subject to the terms and
conditions set forth in the Open Publication License, V1.0 or later (the latest version of the OPL is
presently available at http://www.opencontent.org/openpub/).
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.
1801 Varsity Drive
Raleigh, NC 27606-2072 USA
Phone: [phone]
Phone: [phone]
Fax: [phone]
PO Box 13588 Research Triangle Park, NC 27709 USA

iii
1. Introduction 1
2. Client Applications 3
2.1. Deploying the Latest Red Hat Network Client RPMs ....................................................... 3
2.2. Configuring the Client Applications ................................................................................ 4
2.2.1. Registering with Activation Keys ......................................................................... 4
2.2.2. The up2date --configure Option ................................................................. 5
2.2.3. Updating the Configuration Files Manually .......................................................... 6
2.2.4. Implementing Server Failover ............................................................................. 7
2.3. The Package Updater Applet ........................................................................................ 7
2.4. 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 ............................................................... 12
3.2.3. Generating the Certificate Authority SSL Key Pair .............................................. 15
3.2.4. Generating Web Server SSL Key Sets .............................................................. 16
3.3. Deploying the CA SSL Public Certificate to Clients ....................................................... 17
3.4. Configuring Client Systems ......................................................................................... 17
4. Importing Custom GPG Keys 19
5. Using RHN Bootstrap 21
5.1. Preparation ................................................................................................................ 21
5.2. Generation ................................................................................................................. 22
5.3. Script Use .................................................................................................................. 23
5.4. RHN Bootstrap Options ............................................................................................. 23
6. Manually Scripting the Configuration 27
7. Implementing Kickstart 29
A. Sample Bootstrap Script 31
B. Revision History 37
Index 39

iv

Chapter 1.
1
Introduction
This best practices guide is intended to help customers of RHN Satellite Server and RHN Proxy
Server configure their client systems more easily.
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 instead,
many of these settings must be altered. Altering client settings for a system or two may be relatively
simple. A large enterprise environment, containing hundreds or thousands of systems, will likely
benefit from the mass reconfiguration steps described here.
Due to the complexity of this undertaking, customers may utilize a pre-populated script that automates
many of the tasks necessary to access their Satellite or Proxy server; refer to Chapter 5, Using RHN
Bootstrap for details. Red Hat believes that understanding the implications of these changes is helpful
and therefore describes the manual steps for reconfiguration in the opening 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
impossible to predict all 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.
Note
Unix client configuration information may be found in the RHN Satellite Server Reference
Guide in the Unix Support chapter.

2

Chapter 2.
3
Client Applications
In order to utilize most enterprise-class features of Red Hat Network, such as registering with a RHN
Satellite, configuration of the latest client applications is required. Obtaining these applications before
the client has registered with Red Hat Network can be difficult. This paradox is especially problematic
for customers migrating large numbers of older systems to Red Hat Network. This chapter identifies
techniques to resolve this dilemma.
Important
Red Hat strongly recommends that clients connected to a RHN Proxy Server or RHN
Satellite Server be running the latest update of Red Hat Enterprise Linux to ensure proper
connectivity.
Additionally, if client firewalls are configured, ports 80 and 443 should be open for proper
functionality with Red Hat Network.
2.1. Deploying the Latest Red Hat Network Client RPMs
The Package Updater (pup), yum, and Red Hat Network Registration Client (rhn_register)
on Red Hat Enterprise Linux 5 (up2date on earlier versions of Red Hat Enterprise Linux) 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.
There are several sensible approaches to accomplish this update of the RHN client software. One of
which involves storing the RPMs in a location that is accessible by all client systems and deploying
the packages with the simplest command possible. In nearly all cases, a manual deployment of yum,
pup, and rhn_register (up2date if earlier version of Red Hat Enterprise Linux) do not need to
be performed. Those client tools should have no issues connecting to your RHN Satellite or Proxy
environment. These discussion below assumes that the "out of box" yum, pup, and rhn_register
(or up2date) are not the latest and do not work for your environment.
Remember, only systems running Red Hat Enterprise Linux 5 systems must have registered with RHN
in firstboot after installation or use the rhn_register. Systems running Red Hat Enterprise Linux 3
and 4 can use the registration functionality built into the Red Hat Update Agent.
This document presumes that the customer has installed at least one RHN Satellite Server and/or
RHN Proxy Server on their network. The example below demonstrates a simple approach of deploying
yum, pup, and rhn_register (or up2date) 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 yum, pup, and rhn_register (or up2date) RPMs that the client
systems need, and then has simply deployed those RPMs onto the 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-
setup-0.4.17-8.el5.i386.rpm \
http://your_proxy_or_sat.your_domain.com/pub/yum-3.2.8-9.el5.i386.rpm \

Chapter 2. Client Applications
4
http://your_proxy_or_sat.your_domain.com/pub/pirut-1.3.28-13.3l5.noarch.rpm
Keep in mind that the architecture (in this case, i386) may need to be altered depending on the
systems to be served.
2.2. Configuring the Client Applications
Not every customer must connect securely to a RHN Satellite Server or RHN Proxy Server within
their organization. Not every customer needs to build and deploy a GPG key for custom packages.
(Both of these topics are explained in detail later.) Every customer who uses RHN Satellite Server or
RHN Proxy Server must reconfigure the Red Hat Update Agent (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
Although this is not configurable, note that the port used by the up2date is 80 for HTTP
and 443 for secure HTTP (HTTPS). By default, yum on Red Hat Enterprise Linux 5 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).
By default, the rhn_register and up2date refer to the main Red Hat Network Servers. Users must
reconfigure client systems to refer to their RHN Satellite Server or RHN Proxy Server.
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.
The next sections describe three methods of configuring the client systems to access your RHN
Satellite Server or RHN Proxy Server: using an Activation Key, 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
Red Hat recommends using activation keys for registering and configuring client systems that access
RHN Proxy Server or RHN Satellite Server. Activation keys can be used to register, entitle, and
subscribe systems in a batch. Refer to the section "Activation Keys" in the RHN Satellite Server
Reference Guide for more information on activation keys.
Registering with an activation key has four basic steps:
1. Generate an Activation Key.
2. Import custom GPG keys.
3. 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:

The up2date --configure Option
5
rpm -Uvh\ http://your-satellite.com/pub/rhn-org-trusted-ssl-
cert-1.0-1.noarch.rpm
4. 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 --serverUrl https://your-satellite.com/
XMLRPC
Alternatively, most of the above steps can be combined in a shell script that includes the following
lines:
wget -0 - http://your-satellite-DQDN/pub/bootstrap.sh | bash \ &&
rhnreg_ks --activation-key my_key --serverUrl \ https://your-satellite-
FQDN/XMLRPC
The bootstrap script, generated at installation and available for both RHN Satellite Server and RHN
Proxy Server, is such a script. The script and the RHN Bootstrap that generates it are discussed in
detail in Chapter 5, Using RHN Bootstrap.
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. 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. The up2date --configure Option
The Red Hat Update Agent in Red Hat Enterprise Linux 3 and 4 provides an interface for configuring
various settings. For full listings of these settings, refer to the up2date manual page (man up2date
at a command line).
To reconfigure the Red Hat Update Agent, issue the following command as root:
up2date --configure
You are presented with a dialog box offering various settings that may be reconfigured. In the General
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.
When finished, click OK.

Chapter 2. Client Applications
6
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.
Warning
Systems running Red Hat Enterprise Linux 3 or 4 have registration functionality built
into the Red Hat Update Agent and therefore do not install the Red Hat Network
Registration Client. Systems on Red Hat Enterprise Linux 5 do not use up2date, and
need rhn_register to register their systems to RHN or Satellite and yum and pup to
update their packages.
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 Update Agent by editing the application's configuration file.
To configure 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

Implementing Server Failover
7
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
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).
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 if your
primary RHN Proxy Server or RHN Satellite Server may be taken offline.
To use this feature, first ensure that you are running the required version of 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;
Connection to the servers is 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. The Package Updater Applet
Red Hat Enterprise Linux 5 features a running program on the graphical desktop panel that
periodically checks for updates from the RHN or Satellite server and will alert users when a new
update is available.

Chapter 2. Client Applications
8
Figure 2.2. Package Updater Applet
The Package Updater Applet stays in the notification tray of the desktop panel and checks for new
updates periodically. The applet also allows you to perform a few package maintenance tasks from the
applet by clicking the notification icon and choosing from the following actions:
• Refresh — Check RHN or the Satellite for new updates
• View Updates — launches the Package Updater application so that you can see any available
updates in more detail and configure the updates to your specifications
• Apply Updates — Download and Install all updated packages.
• Quit — close the applet
2.4. Configuring the Red Hat Network Alert Notification Tool
with Satellite
The Red Hat Network Alert Notification Tool, the round icon in the panel of your Red Hat Enterprise
Linux 3 or 4 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. You must ensure
the RHN Satellite Server is configured to support this feature. (RHN Proxy Server supports the
applet without modification of client or server.) The steps to configure the Red Hat Network Alert
Notification Tool are as follows:
1. Ensure that your RHN Satellite Server is version 3.4 or later and that you 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. Retrieve the rhn-applet-actions package with up2date or 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.
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.
9
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 installation. In addition, a separate
command line utility, the RHN SSL Maintenance Tool, exists for this 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 the complexity involved in setting up and maintaining this public-key
infrastructure (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 are 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
generate 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

Chapter 3. SSL Infrastructure
10
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 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 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). RHN 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).
This tool is only a build tool. It generates all of 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 cases in which the tool is required:
• 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.
Here are the cases in which the tool is not required:

SSL Generation Explained
11
• 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.
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, become familiar with its
usage.
3.2.1. SSL Generation Explained
The primary benefits of using the RHN SSL Maintenance Tool are security, flexibility, and portability.
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 that has 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 an 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, complete the following high-level tasks in
roughly this 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 httpd service 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.

Chapter 3. SSL Infrastructure
12
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 to assist: man
rhn-ssl-tool.
The two tables below break down the options by their related task, either CA or Web server SSL key
set generation.
This set of options must be preceded by the --gen-ca 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 ''.

RHN SSL Maintenance Tool Options
13
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 ''.
--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).
--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)
The following set of options must be preceded by the --gen-server argument:
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.

Chapter 3. SSL Infrastructure
14
Option Description
-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 [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.

Generating the Certificate Authority SSL Key Pair
15
Option Description
--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)
3.2.3. Generating the Certificate Authority SSL Key Pair
Before creating the SSL key set required by the Web server, you must generate a Certificate Authority
(CA) SSL key pair. A CA SSL public certificate is distributed to client systems of the 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
following 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

Chapter 3. SSL Infrastructure
16
•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 must 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" --set-email="[email protected]" \
--set-hostname="rhnbox1.example.com
Replace the example values with those appropriate for your organization. This will result in the
following 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
•/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
the httpd service must be restarted after installation:
/sbin/service httpd restart