Page 1
RHN Satellite Server 4.0.5
Installation Guide
Page 2
RHN Satellite Server 4.0.5: Installation Guide
Copyright © 2001 - 2005 Red Hat, Inc.
Red Hat, Inc.
1801 Varsity Drive
Raleigh NC 27606-2072 USA
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588
Research Triangle Park NC 27709 USA
RHNsatellite(EN)-4.0.5-RHI (2005-04-20T13:40)
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 security@redhat.com key is:
CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E
Page 3
Table of Contents
1. Introduction....................................................................................................................1
1.1. Red Hat Network ..............................................................................................1
1.2. RHN Satellite Server.........................................................................................2
1.3. Terms to Understand .........................................................................................2
1.4. How it Works ....................................................................................................3
1.5. Summary of Steps .............................................................................................5
2. Requirements.................................................................................................................. 9
2.1. Software Requirements .....................................................................................9
2.1.1. Red Hat Enterprise Linux AS 4 Packages .........................................9
2.1.2. Red Hat Enterprise Linux AS 3 Update 5 Packages ........................10
2.2. Hardware Requirements..................................................................................11
2.3. Database Requirements ...................................................................................13
2.4. Additional Requirements ................................................................................14
3. Example Topologies .....................................................................................................17
3.1. Single Satellite Topology ................................................................................17
3.2. Multiple Satellite Horizontally Tiered Topology ............................................18
3.3. Satellite-Proxy Vertically Tiered Topology ....................................................19
4. Installation ....................................................................................................................21
4.1. Base Install......................................................................................................21
4.2. RHN Satellite Server Installation Program................................................21
4.3. Sendmail Configuration ..................................................................................37
4.4. MySQL Installation ........................................................................................38
5. Entitlements..................................................................................................................39
5.1. Receiving the Certificate .................................................................................39
5.2. Uploading the RHN Entitlement Certificate ...................................................40
5.3. Managing the RHN Certificate with RHN Satellite Activate .......................40
5.3.1. Command Line Entitlement Options ...............................................41
5.3.2. Activating the Satellite .....................................................................41
6. Importing and Synchronizing .....................................................................................43
6.1. Exporting with RHN Satellite Exporter .......................................................43
6.1.1. rhn-satellite-exporter..........................................................43
6.1.2. Exporting..........................................................................................45
6.2. Importing with RHN Satellite Synchronization Tool ..................................45
6.2.1. satellite-sync ...........................................................................46
6.2.2. Preparing for Import from Local Media ..........................................49
6.2.3. Running the Import ..........................................................................49
6.3. Synchronizing .................................................................................................51
6.3.1. Synchronizing Errata and Packages Directly via RHN ...................52
6.3.2. Synchronizing Errata and Packages via Local Media ......................52
Page 4
7. Troubleshooting............................................................................................................53
7.1. Log Files .........................................................................................................53
7.2. General Problems ............................................................................................54
7.3. Host Not Found/Could Not Determine FQDN ...............................................55
7.4. Connection Errors ...........................................................................................56
7.5. Satellite Debugging by Red Hat .....................................................................57
8. Maintenance .................................................................................................................59
8.1. Managing the Satellite Service .......................................................................59
8.2. Updating the Satellite ......................................................................................59
8.3. Backing Up the Satellite .................................................................................60
8.4. Using RHN DB Control ................................................................................61
8.4.1. DB Control Options .........................................................................61
8.4.2. Backing up the Database..................................................................62
8.4.3. Verifying the Backup .......................................................................63
8.4.4. Restoring the Database ....................................................................63
8.5. Cloning the Satellite with Embedded DB .......................................................64
8.6. Establishing Redundant Satellites with Stand-Alone DB ...............................64
8.7. Conducting Satellite-Specific Tasks ...............................................................66
8.7.1. Using the Tools menu ......................................................................66
8.7.2. Deleting Users..................................................................................68
8.8. Automating Synchronization ..........................................................................69
8.9. Implementing PAM Authentication ................................................................70
8.10. Enabling Push to Clients ...............................................................................71
A. Sample RHN Satellite Server Configuration File.....................................................73
Index..................................................................................................................................75
Page 5
Chapter 1.
Introduction
RHN Satellite Server provides a solution to organizations requiring absolute control over
and privacy of the maintenance and package deployment of their servers. It allows Red
Hat Network customers the greatest flexibility and power in keeping servers secure and
updated.
Two types of RHN Satellite Server are available: One with a stand-alone database on a
separate machine and one with an embedded database installed on the same machine as
the Satellite. This guide describes the installation of both types of Satellite.
Although the two types of RHN Satellite Server are functionally similar, some differences
do exist. These variations are primarily isolated to hardware requirements, installation
steps, and maintenance activities. They may also appear during troubleshooting. This guide
identifies distinctions between the Satellite types by marking the differing instructions as
either Stand-Alone Database or Embedded Database.
1.1. Red Hat Network
Red Hat Network (RHN) is the environment for system-level support and management of
Red Hat systems and networks of systems. Red Hat Network brings together the tools,
services, and information repositories needed to maximize the reliability, security, and performance of their systems. To use RHN, system administrators register the software and
hardware profiles, known as System Profiles, of their client systems with Red Hat Network.
When a client system requests package updates, only the applicable packages for the client
are returned (based upon the software profile stored on the RHN Servers).
Advantages of using Red Hat Network include:
• Scalability — with Red Hat Network, a single system administrator can set up and main-
tain hundreds or thousands of Red Hat systems more easily, accurately, and quickly than
they could maintain a single system without Red Hat Network.
• Standard Protocols — standard protocols are used to maintain security and increase
capability. For example, XML-RPC gives Red Hat Network the ability to do much more
than merely download files.
• Security — all communication between registered systems and Red Hat Network takes
place over secure Internet connections.
• View Errata Alerts — easily view Errata Alerts for all your client systems through one
website.
Page 6
2 Chapter 1. Introduction
• Scheduled Actions — use the website to schedule actions, including Errata Updates,
package installs, and software profile updates.
• Simplification — maintaining Red Hat systems becomes a simple, automated process.
1.2. RHN Satellite Server
RHN Satellite Server allows organizations to utilize the benefits of Red Hat Network without having to provide public Internet access to their servers or other client systems. System
Profiles are stored locally on the customer’s RHN Satellite Server. The Red Hat Network
website is served from a local Web server and is not accessible from the Internet. All package management tasks, including Errata Updates, are performed through the local area
network.
Advantages of using RHN Satellite Server include:
• Security — an end-to-end secure connection is maintained from the client systems to
the RHN Satellite Server without connecting to the public Internet.
• Efficiency — packages are delivered significantly faster over a local area network.
• Control — clients’ System Profiles are stored on the local RHN Satellite Server, not on
the central Red Hat Network Servers.
• Customized updates — create a truly automated package delivery system for custom
software packages required by client systems, as well as Red Hat packages. Custom
channels allow fine-grained control of the delivery of custom packages.
• Access control — system administrators can be restricted to access only those systems
within their maintenance responsibilities.
• Bandwidth management — the bandwidth used for transactions between the clients and
the RHN Satellite Server is controlled by the organization on the local area network;
RHN Satellite Server clients do not have to compete with other clients accessing the
central Red Hat Network file servers.
• Scalability — RHN Satellite Server may oversee an entire organization’s servers in com-
bination with RHN Proxy Server.
1.3. Terms to Understand
Before understanding RHN Satellite Server, it is important to become familiar with the
following Red Hat Network terms:
• Channel — A channel is a list of software packages. There are two types of channels:
base channels and child channels. A base channel consists of a list of packages based on
Page 7
Chapter 1. Introduction 3
a specific architecture and Red Hat release. A child channel is a channel associated with
a base channel that contains extra packages.
• Organization Administrator — An Organization Administrator is a user role with the
highest level of control over an organization’s Red Hat Network account. Members of
this role can add other users, systems, and system groups to the organization as well
as remove them. A Red Hat Network organization must have at least one Organization
Administrator.
• Software Channel Administrator — A Channel Administrator is a user role with full
access to channel management capabilities. Users with this role are capable of creating
channels, assigning packages to channels, cloning channels, and deleting channels. This
role can be assigned by an Organization Administrator through the Users tab of the RHN
website.
• Red Hat Update Agent — The Red Hat Update Agent is the Red Hat Network client
application (up2date) that allows users to retrieve and install new or updated packages
for the client system on which the application is run.
• Traceback — A traceback is a detailed description of "what went wrong" that is useful
for troubleshooting the RHN Satellite Server. Tracebacks are automatically generated
when a critical error occurs and are mailed to the individual(s) designated in the RHN
Satellite Server’s configuration file.
For more detailed explanations of these terms and others, refer to the Red Hat Network
Reference Guide.
1.4. How it Works
RHN Satellite Server consists of the following components:
• Database — for the Stand-Alone Database, this may be the organization’s existing
database or, preferably, a separate machine. RHN Satellite Server 4.0.5 supports Oracle
9i R2. For the Embedded Database, the database comes bundled with RHN Satellite
Server and is installed on the same machine as the Satellite during the installation
process.
• RHN Satellite Server — core "business logic" and entry point for Red Hat Update
Agent running on client systems. The RHN Satellite Server also includes an Apache
HTTP Server (serving XML-RPC requests).
• RHN Satellite Server Web interface — advanced system, system group, user, and chan-
nel management interface.
• RPM Repository — package repository for Red Hat RPM packages and custom RPM
packages identified by the organization.
• Management Tools:
• Database and file system synchronization tools
Page 8
4 Chapter 1. Introduction
• RPM importing tools
• Channel maintenance tools (Web-based)
• Errata management tools (Web-based)
• User management tools (Web-based)
• Client system and system grouping tools (Web-based)
• Red Hat Update Agent on the client systems
The Red Hat Update Agent on the client systems must be reconfigured to retrieve updates from the organization’s internal RHN Satellite Server instead of the central Red Hat
Network Servers. After this one-time reconfiguration, client systems may retrieve updates
locally using the Red Hat Update Agent, or system administrators may schedule actions
through the RHN Satellite Server website.
Red Hat strongly recommends that clients connected to RHN Satellite Server be running
the latest update of Red Hat Enterprise Linux to ensure proper connectivity.
When a client requests updates, the organization’s internal RHN Satellite Server queries its
database, authenticates the client system, identifies the updated packages available for the
client system, and sends the requested RPMs back to the client system. Depending upon
the client’s preferences, the package may also be installed. If the packages are installed,
the client system sends an updated package profile to the database on the RHN Satellite
Server; those packages are removed from the list of outdated packages for the client.
The organization can configure the website for the RHN Satellite Server to be accessible
from the local area network only or from both the local area network and the Internet.
The Satellite’s version of the RHN website allows full control over client systems, system
groups, and users.
The RHN Satellite Server management tools are used to synchronize the RHN Satellite
Server database and package repository with Red Hat Network. The RHN Satellite Server
import tool allows the system administrator to include custom RPM packages in the package repository.
RHN Satellite Server can be used in conjunction with RHN Proxy Server to deliver a distributed, self-contained Red Hat Network deployment for the organization. For example,
an organization can maintain one RHN Satellite Server in a secure location. Red Hat systems with local network access to the RHN Satellite Server can connect to it. Other remote
offices can maintain RHN Proxy Server installations that connect to the RHN Satellite
Server. The different locations inside the organization must be networked, but this can be a
private network; an Internet connection is not required for any of the systems. Refer to the
RHN Proxy Server Installation Guide for more information.
Page 9
Chapter 1. Introduction 5
Figure 1-1. Using RHN Satellite Server and RHN Proxy Server Together
1.5. Summary of Steps
Implementing a fully functional RHN Satellite Server requires more than installing software and a database. Client systems must be configured to use the Satellite. Custom packages and channels should be created for optimal use. Since these tasks extend beyond the
basic installation, they are covered in detail in other guides, as well as this RHN Satellite
Server Installation Guide. For a full list of the necessary technical documents, refer to
Chapter 2 Requirements.
For this reason, this section seeks to provide a definitive list of all required and recommended steps, from evaluation through custom package deployment. They should take
place in roughly this order:
1. After an evaluation, you contact your Red Hat sales representative to purchase RHN
Satellite Server.
2. Your Red Hat contact sends you an RHN Entitlement Certificate via email.
Page 10
6 Chapter 1. Introduction
3. Your Red Hat contact creates a Satellite-entitled account on the RHN website and
sends you the login information.
4. Log into the RHN website (rhn.redhat.com) and download the distribution ISOs for
Red Hat Enterprise Linux AS 3 or 4 and RHN Satellite Server 4.0.5. These can be
found within the Downloads tab of the respective Channel Details pages. Refer to
the RHN Reference Guide for instructions.
5. While still logged into the RHN website, download the Channel Content ISOs to
be served by your Satellite, also available through the Downloads tab of your Satellite’s Channel Details page. These Channel Content ISOs differ from the distribution
ISOs previously mentioned in that they contain metadata necessary for parsing and
serving packages by Satellite.
6. If installing a Stand-Alone Database, prepare your database instance using the formula provided in Chapter 2 Requirements.
7. Install Red Hat Enterprise Linux AS and then RHN Satellite Server 4.0.5 on the
Satellite machine.
8. Create the first user account on the Satellite by opening the Satellite’s hostname in a
Web browser and clicking Create Account. This will be the Satellite Administrator’s
(also referred to as the Organization Administrator) account.
9. Use the RHN Satellite Synchronization Tool to import the channels and associated
packages into the Satellite.
10. Register a representative machine for each distribution type, or channel (Red Hat
Enterprise Linux AS 2.1, 3, 4), to the Satellite.
11. Copy (using SCP) the rhn_register and up2date configuration files from the
/etc/sysconfig/rhn/ directory of each machine individually to the /pub/ di-
rectory on the Satellite. The rhn-org-trusted-ssl-cert-*.noarch.rpm will
already be there.
12. Download and install from the Satellite the configuration files and
rhn-org-trusted-ssl-cert-*.noarch.rpm on the remaining client systems
of the same distribution type. Repeat this and the previous step until all distribution
types are complete.
13. Through the Satellite’s website, create an Activation Key for each distribution
aligned to the appropriate base channel. At this point, system groups and child
channels may also be predefined.
14. Run the Activation Key from the command line (rhnreg_ks) of each client system.
Note that this step can be scripted to batch register and reconfigure all remaining
client systems in a distribution.
15. Record all relevant usernames, passwords and other login information and store in
multiple secure places.
16. Now that the Satellite is populated with standard Red Hat channels and packages and
all clients are connected to it, you may begin creating and serving custom channels
Page 11
Chapter 1. Introduction 7
and packages. Once the custom RPMs are developed, you can import them into the
Satellite using RHN Push and add custom channels in which to store them through
the Satellite’s website. Refer to the RHN Channel Management Guide for details.
Page 12
8 Chapter 1. Introduction
Page 13
Chapter 2.
Requirements
These requirements must be met before installation.
2.1. Software Requirements
To perform an installation, the following software components must be available:
• Base operating system — RHN Satellite Server is supported with Red Hat Enterprise
Linux AS 3 Update 5 or later, or Red Hat Enterprise Linux AS 4 only. The operating
system can be installed from disc, local ISO image, kickstart, or any of the methods
supported by Red Hat, but must contain certain packages not included in a standard
installation.
• Satellite installation disc or ISO — this contains the RHN Satellite Server Installation
Program.
• Channel content — All software packages and data exported for all entitled Red Hat
channels. This content may be loaded directly on the Satellite after installation using the
RHN Satellite Synchronization Tool or obtained from your Red Hat representative if
synchronization is not possible, such as in a disconnected environment.
Each version of Red Hat Enterprise Linux AS requires additional packages to support
RHN Satellite Server. The following sections identify Red Hat’s recommended methods
for obtaining the desired package set for each version of Red Hat Enterprise Linux AS.
Installing packages other than those specified can lead to package conflicts.
2.1.1. Red Hat Enterprise Linux AS 4 Packages
To install RHN Satellite Server on Red Hat Enterprise Linux AS 4 and newer, first obtain
the required packages in one of the following ways.
Warning
Security-enhanced Linux (SELinux) must be disabled or in permissive mode prior to installation of RHN Satellite Server. To do this during CD or ISO image installation, select
Permissive when presented with options for SELinux support. To do this for kickstart
installation, include the command selinux --permissive or wait for the install to complete, edit the /etc/selinux/config file to read SELINUX=permissive and reboot the
system.
Page 14
10 Chapter 2. Requirements
More in-depth coverage of SELinux is available at http://www.redhat.com/docs/. You may
also refer to the Red Hat Knowledgebase article on SELinux and RHN Satellite Server at
http://kbase.redhat.com/faq/.
When installing Red Hat Enterprise Linux AS 4 via CD or ISO image, select the following
package groups:
• Development Tools
• Legacy Software Development
After operating system installation, register the system with RHN and use the Red Hat
Update Agent to install the outstanding packages with the following command:
up2date newt-perl perl-DateManip perl-libxml-enno perl-Parse-Yapp \
perl-Time-HiRes PyXML ntp
Once updated, delete the Red Hat Enterprise Linux AS 4 system profile from RHN, as it
will be reregistered during Satellite installation.
When kickstarting Red Hat Enterprise Linux AS 4, specify the following packages and
groups:
• @ Base
• @ Compatibility Arch Support
• @ Development Tools
• @ Legacy Software Development
• newt-perl
• perl-DateManip
• perl-libxml-enno
• perl-Parse-Yapp
• perl-Time-HiRes
• PyXML
• ntp
2.1.2. Red Hat Enterprise Linux AS 3 Update 5 Packages
To install RHN Satellite Server on Red Hat Enterprise Linux AS 3 Update 5, first obtain
the required packages in one of the following ways.
Page 15
Chapter 2. Requirements 11
When installing Red Hat Enterprise Linux AS 3 Update 5 via CD or ISO image, select the
following package groups:
• Web Server
• Mail Server
• Development Tools
• Legacy Software Development
Then after operating system installation, register the system with RHN and use the Red
Hat Update Agent to install the outstanding packages with the following command:
up2date perl-CGI perl-libwww-perl perl-URI perl-XML-Parser perl-DateManip \
perl-XML-Dumper perl-libxml-enno perl-Parse-Yapp perl-XML-Encoding ntp
Once updated, delete the Red Hat Enterprise Linux AS 3 Update 5 system profile from
RHN, as it will be reregistered during Satellite installation.
When kickstarting Red Hat Enterprise Linux AS 3 Update 5, specify the following packages and groups:
• @ Base
• @ Server
• @ Development Tools
• @ Legacy Software Development
• perl-CGI
• perl-Time-HiRes
• ntp
2.2. Hardware Requirements
The following hardware configuration is required for the two types of RHN Satellite
Server:
Stand-Alone Database Embedded Database
Required - Pentium IV processor, 2.4GHz,
512K cache or equivalent
Required - Pentium IV processor, 2.4GHz,
512K cache or equivalent
Page 16
12 Chapter 2. Requirements
Stand-Alone Database Embedded Database
Recommended - Pentium IV processor,
2.4GHz dual processor, 512K cache or
equivalent
Recommended - Pentium IV processor,
2.4GHz dual processor, 512K cache or
equivalent
Required - 2 GB of memory Required - 2 GB of memory
Recommended - 4 GB of memory Strongly recommended - 4 GB of memory
3 GB storage for base install of Red Hat
Enterprise Linux AS
3 GB storage for base install of Red Hat
Enterprise Linux AS
6 GB storage per channel, in the
/var/satellite/ directory by default
but configurable at install
6 GB storage per channel, in the
/var/satellite/ directory by default
but configurable at install
Recommended - an external SAN for more
reliable backups
Recommended - an external SAN for more
reliable backups
12 GB storage for the database repository,
in the /rhnsat partition (local storage
only)
Strongly recommended - a SCSI drive
connected to a level 5 RAID
Separate partition (or better, a separate set
of physical disks) for storing backups. This
can be any directory specifiable at backup
time.
Table 2-1. Stand-Alone Database and Embedded Database Satellite Hardware Requirements
The following hardware configuration is required for the Stand-Alone Database:
• Two processors
• 2 GB of memory
See Section 2.3 Database Requirements for instructions on estimating the tablespace of the
database and setting its environment variables.
Keep in mind, the frequency with which client systems connect to the Satellite is directly
related to load on the Apache HTTP Server and the database. Reducing the default interval
of four hours (or 240 minutes) as set in the /etc/sysconfig/rhn/rhnsd configuration
file of the client systems significantly increases the load on those components.
Additional hardware requirements include:
• The Stand-Alone Database must not run on the same server as the RHN Satellite Server.
Page 17
Chapter 2. Requirements 13
• The package repository may be any large storage device easily and securely accessed
by the other components. The space requirements depend on the number of packages
that will be stored. Default Red Hat channels contain approximately 3 GB of packages
each, and that size grows with each synchronization; customers must also account for the
space requirements of packages in their own private channels. Whatever storage solution
the customer chooses, its mount point may be defined during the installation process.
If you are installing RHN Satellite Server with Embedded Database, skip to
Section 2.4 Additional Requirements.
2.3. Database Requirements
This section applies only to RHN Satellite Server with Stand-Alone Database as the requirements for the Embedded Database are included in the Satellite machine’s hardware
requirements. Red Hat supports RHN Satellite Server 4.0.5 installations in conjunction
with Oracle 9i R2. The Stand-Alone Database must not run on the same server as the RHN
Satellite Server.
A single 6 GB tablespace is recommended as more than sufficient for most installations. It
is possible for many customers to function with a smaller tablespace. An experienced Oracle database administrator (DBA) will be necessary to assess sizing issues. The following
formula should be used to determine the required size of your database:
• 192 KB per client system
• 64 MB per channel
For instance, an RHN Satellite Server containing 10 channels serving 10,000 systems
would require 1.92 GB for its clients and 640 MB for its channels. If custom channels
are to be established for testing and staging of packages, they must be included in this
formula.
Keep in mind, the database storage needs may grow rapidly, depending upon the variance
of the following factors:
• The number of public Red Hat packages imported (typical: 5000)
• The number of private packages to be managed (typical: 500)
• The number of systems to be managed (typical: 1000)
• The number of packages installed on the average system (typical: 500)
Although you should be generous in your database sizing estimates, you must consider
that size affects the time to conduct backups and adds load to other system resources. If the
database is shared, its hardware and spacing are entirely dependent on what else is using
it.
Page 18
14 Chapter 2. Requirements
The Oracle database should have a user assigned to RHN Satellite Server with full DDL
and DML access to that user’s default tablespace. The user needs standard connection
information for the database at the time of installation.
The precise access levels required by the Oracle user are as follows:
• ALTER SESSION
• CREATE SEQUENCE
• CREATE SYNONYM
• CREATE TABLE
• CREATE VIEW
• CREATE PROCEDURE
• CREATE TRIGGER
• CREATE TYPE
• CREATE SESSION
Additional database requirements include:
• Security Identifier (SID)
• Listener Port
• Username
• Uniform Extent Size
• Auto Segment Space Management
• UTF-8 character set
The disk layout on the database machine is independent of the RHN Satellite Server and
entirely up to the customer.
2.4. Additional Requirements
The following additional requirements must be met before the RHN Satellite Server installation:
• Full Access
Client systems need full network access to the RHN Satellite Server solution’s services
and ports.
•
Firewall Rules
Page 19
Chapter 2. Requirements 15
RHN strongly recommends firewalling the RHN Satellite Server solution from the Internet. However, it must be able to issue outbound connections to rhn.redhat.com, xmlrpc.rhn.redhat.com and satellite.rhn.redhat.com on ports 80 and 443.
•
Synchronized System Times
There is great time sensitivity when connecting to a Web server running SSL (Secure
Sockets Layer); it is imperative that the time settings on the clients and server be reasonably close together so the SSL certificate does not expire before or during use. For
this reason, Red Hat requires the Satellite and all client systems to use Network Time
Protocol (NTP). This also applies to the separate database machine in RHN Satellite
Server with Stand-Alone Database, which must also be set to the same time zone as the
Satellite.
• Fully Qualified Domain Name (FQDN)
The system upon which the RHN Satellite Server will be installed must resolve its own
FQDN properly. If this is not the case, cookies will not work properly on the website.
• Functioning Domain Name Service (DNS)
For the RHN Satellite Server’s domain name to be resolved by its clients, it and they
must all be linked to a working DNS server in the customer environment.
•
An Entitlement Certificate
The customer will receive, via email from the sales representative, a signed Entitlement
Certificate explaining the services provided by Red Hat through RHN Satellite Server.
This certificate will be required during the installation process.
• A Red Hat Network Account
Customers who connect to the central Red Hat Network Servers to receive incremental
updates must have an external account with Red Hat Network. This account should be
set up at the time of purchase with the sales representative.
• Backups of Login Information
It is imperative that customers keep track of all primary login information. For RHN
Satellite Server, this includes usernames and passwords for the Organization Administrator account on rhn.redhat.com, the primary administrator account on the Satellite
itself, SSL certificate generation, and database connection (which also requires a SID,
or net service name). Red Hat strongly recommends this information be copied onto two
separate floppy disks, printed out on paper, and stored in a fireproof safe.
In addition to these requirements, it is recommended that the RHN Satellite Server be
configured in the following manner:
• The entire RHN Satellite Server solution should be protected by a firewall if the Satellite
accesses or is accessed via the Internet. An Internet connection is not required for RHN
Page 20
16 Chapter 2. Requirements
Satellite Servers running in completely disconnected environments. This feature instead
uses Channel Content ISOs that can be downloaded to a separate system to synchronize
the Satellite with the central Red Hat Network Servers. All other RHN Satellite Servers
should be synchronized directly over the Internet.
•
All unnecessary ports should be firewalled off. Client systems connect to RHN
Satellite Server over ports 80 and 443 only. In addition, if you plan to enable
the pushing of actions from the Satellite to client systems, as described in
Section 8.10 Enabling Push to Clients, you must allow inbound connections on port
5222. Finally, if the Satellite will also push to an RHN Proxy Server, you must also
allow inbound connections on port 5269.
• No system components should be directly, publicly available. No user other than the
system administrators should have shell access to these machines.
•
All unnecessary services should be disabled using ntsysv or chkconfig.
•
The httpd service should be enabled.
•
If the Satellite serves Monitoring-entitled systems and you wish to acknowledge via
email the alert notifications you receive, you must configure sendmail to properly handle
incoming mail as described in Section 4.3 Sendmail Configuration.
Finally, you should have the following technical documents in hand for use in roughly this
order:
1. The RHN Satellite Server Installation Guide — This guide, which you are now reading, provides the essential steps necessary to get an RHN Satellite Server up and
running.
2. The RHN Client Configuration Guide — This guide explains how to configure the
systems to be served by an RHN Proxy Server or RHN Satellite Server. (This will
also likely require referencing The RHN Reference Guide, which contains steps for
registering and updating systems.)
3. The RHN Channel Management Guide — This guide identifies in great detail the
recommended methods for building custom packages, creating custom channels, and
managing private Errata.
4. The RHN Reference Guide — This guide describes how to create RHN accounts, register and update systems, and use the RHN website to its utmost potential. This guide
will probably come in handy throughout the installation and configuration process.
Page 21
Chapter 3.
Example Topologies
The RHN Satellite Server can be configured in multiple ways. Select one method depending on the following factors:
• The total number of client systems to be served by the RHN Satellite Server.
• The maximum number of clients expected to connect concurrently to the RHN Satellite
Server.
• The number of custom packages and channels to be served by the RHN Satellite Server.
• The number of RHN Satellite Servers being used in the customer environment.
• The number of RHN Proxy Servers being used in the customer environment.
The rest of this chapter describes possible configurations and explains their benefits.
3.1. Single Satellite Topology
The simplest configuration is to use a single RHN Satellite Server to serve your entire
network. This configuration is adequate to service a medium-size group of clients and
network.
The disadvantage of using one RHN Satellite Server is that performance will be compromised as the number of clients requesting packages grows.
Page 22
18 Chapter 3. Example Topologies
Figure 3-1. Single Satellite Topology
3.2. Multiple Satellite Horizontally Tiered Topology
For very large networks, a more distributed method may be needed, such as having multiple
RHN Satellite Servers in a horizontally tiered configuration and balancing the load of client
requests.
It is possible to synchronize content between RHN Satellites using the
rhn-satellite-exporter and satellite-sync -m commands. This feature is
discussed in detail in Section 6.1.1 rhn-satellite-exporter.
Additional maintenance is the biggest disadvantage of this horizontal structure.
Page 23
Chapter 3. Example Topologies 19
Figure 3-2. Multiple Satellite Horizontally Tiered Topology
3.3. Satellite-Proxy Vertically Tiered Topology
An alternative method to balance load is to install RHN Proxy Servers below a RHN Satellite Server. These Proxies connect to the Satellite for RPMs from Red Hat Network and
custom packages created locally. In essence, the Proxies act as clients of the Satellite.
This vertically tiered configuration requires that channels and RPMs be created only on the
RHN Satellite Server. In this manner, the Proxies inherit and then serve packages from a
central location. For details, refer to the RHN Channel Management Guide.
Similarly, you should make the Proxies’ SSL certificates clients of the Satellite while also
setting them to serve the client systems. This process is described in the RHN Client Con-
figuration Guide.
Page 24
20 Chapter 3. Example Topologies
Figure 3-3. Satellite-Proxy Vertically Tiered Topology
Page 25
Chapter 4.
Installation
This chapter describes the initial installation of the RHN Satellite Server. It presumes the
prerequisites listed in Chapter 2 Requirements have been met. If you are instead upgrading to a newer version of RHN Satellite Server, contact your Red Hat representative for
assistance.
4.1. Base Install
The RHN Satellite Server is designed to run on the Red Hat Enterprise Linux AS operating
system. Therefore, the first phase is to install the base operating system, either from disc,
ISO image, or kickstart. During and after operating system installation, make sure you:
•
Allocate plenty of space to the partitions storing data. The default location for channel
packages is /var/satellite/. For RHN Satellite Server with Embedded Database,
remember the database RPMs go in the /opt/ partition, while the database itself is built
in /rhnsat/. Refer to Section 2.2 Hardware Requirements for precise specifications.
• Install all packages required by RHN Satellite Server. Refer to
Section 2.1 Software Requirements for packages and package groups needed for each
version of Red Hat Enterprise Linux AS.
• Enable Network Time Protocol (NTP) on the Satellite and separate database, if it exists,
and select the appropriate time zone. All client systems should already be running the
ntpd daemon and be set to the correct time zone.
• Due to potential complications, it is strongly advised that the /home/ partition is locally
mounted.
4.2. RHN Satellite Server Installation Program
The following instructions describe how to run the RHN Satellite Server Installation
Program:
1. Log into the machine as root.
2. Insert the RHN Satellite Server CD containing the installation files or download the
ISO image from the RHN website.
3. Create a directory in /mnt/ to store the files with the command:
Page 26
22 Chapter 4. Installation
mkdir /mnt/cdrom/
4. If you are installing from CD and it is not mounted automatically, mount it using the
command:
mount /dev/cdrom /mnt/cdrom
If you are installing from an ISO, mount the file from within the directory containing
it using the command:
mount iso_filename /mnt/cdrom -o loop
The rest of the instructions assume it is mounted in /mnt/cdrom/.
5.
Ensure that the RHN Entitlement Certificate has been loaded onto the Satellite. It
can be named anything and located in any directory. The installation program will
ask you for its contents or location. Also, make sure your account has been granted
the necessary entitlements to conduct the installation. For instance, a new Satellite
will require both a Management or Provisioning entitlement for Red Hat Enterprise
Linux AS and an RHN Satellite Server entitlement.
Warning
Users should note that the RHN Satellite Server Installation Program updates
the kernel, as well as all required packages.
6. Launch the RHN Satellite Server Installation Program as root with the command:
/mnt/cdrom/install.sh
This script runs through the pre-installation process without user intervention. See
Figure 4-1 This takes between 20 and 30 minutes.
Page 27
Chapter 4. Installation 23
Figure 4-1. Pre-Installation
It will first update the system and then install the RHN Satellite Server packages,
GPG keys, database, and default configuration. It will then restart key services, such
as httpd.
7. After the system is back up, open a Web browser and go to the fully qualified domain
name (FQDN) of the RHN Satellite Server. The Administrator Email Address page
appears.
Page 28
24 Chapter 4. Installation
Figure 4-2. Administrator Email Address
8.
The Administrator Email Address page requires an email address to receive administrative correspondence. Ideally, this address serves multiple people in your organization to ensure delivery. Keep in mind, this address receives all mail generated
by the Satellite, including potentially large quantities of error-related tracebacks. To
stem this flow, consider establishing mail filters that capture messages with a subject
of "RHN TRACEBACK from hostname". Click Continue. The Database Config-
uration page appears for RHN Satellite Server with Stand-Alone Database, while the
Database Schema page appears for RHN Satellite Server with Embedded Database.
Page 29
Chapter 4. Installation 25
Figure 4-3. Database Configuration
9.
The Database Configuration page collects information required for the Satellite
with Stand-Alone Database to connect to its database. For Satellite with Embedded
Database installation, skip to the Database Schema page description. For Satellite
with Stand-Alone Database, consult your database administrator for the appropriate values. When finished, click Test DB Connection. The Database Schema page
appears.
Page 30
26 Chapter 4. Installation
Figure 4-4. Database Schema
10.
No input is required on the Database Schema page other than your consent. Click
Continue to populate the database. This too can take a while. The Database Population page appears to help you track the progress.
Figure 4-5. Database Population
Page 31
Chapter 4. Installation 27
11.
The Database Population page displays a link when population is complete. Click
Configuration to continue. The RHN Configuration page appears.
Figure 4-6. RHN Configuration
12.
The RHN Configuration page enables you to change the way the Satellite communicates with Red Hat Network. You may alter the Satellite’s hostname and the
location or mount point of the package repository. Typically, the defaults will do. If
you intend to monitor systems with this Satellite, select both the Enable monitoring
backend and Enable monitoring scout checkboxes.
In addition, this page allows you to configure the Satellite to use an HTTP proxy.
To do this, complete all associated fields. Note that references to protocol such
as http:// or https:// should not be included in the HTTP proxy server field.
Insert only the hostname and port in the format "hostname:port", such as
Page 32
28 Chapter 4. Installation
my.corporate.gateway.example.com:3128. When finished, click
Continue. The Monitoring Configuration page appears.
Figure 4-7. Monitoring Configuration
13.
The Monitoring Configuration page captures email routing information used in
monitoring. This is required only if you intend to receive alert notifications from
probes. If you do, provide the mail server (exchanger) and domain to be used. Note
that sendmail must be configured to handle email redirects of notifications. Refer to
Section 4.3 Sendmail Configuration for instructions. When finished, click Continue.
The RHN Registration page appears.
Page 33
Chapter 4. Installation 29
Figure 4-8. RHN Registration
14.
The RHN Registration page enables you to register the Satellite with Red Hat Network, allowing it to get updates and software channel package data directly. To register the Satellite, ensure its system profile name is correct (usually the hostname)
and complete the RHN Username and RHN Password fields with the account information provided by your sales representative or established previously by you.
This account must be entitled for RHN Satellite Server.
To skip this step, such as for Satellites that will operate in disconnected mode, click
either the continue link or button. If you do not register the Satellite, the RHN Satel-
lite Synchronization Tool cannot be used to populate software channels. Contact
your Red Hat representative to obtain the packages and updates manually. When
finished, click Continue. The RHN Satellite Entitlement Certificate page appears.
Page 34
30 Chapter 4. Installation
Figure 4-9. RHN Satellite Entitlement Certificate
15.
The RHN Satellite Entitlement Certificate page gathers your RHN Entitlement
Certificate either by obtaining its location or collecting its contents. To identify the
certificate’s path, click Browse, navigate to the file, and select it. To input its
contents, open your certificate in a text editor, copy all lines, and paste them
directly into the large text field at the bottom. Red Hat recommends using the
file locator as it is less error prone. Click Validate Certificate to continue. If
you receive errors related to DNS, ensure your Satellite is configured correctly.
Refer to Section 7.3 Host Not Found/Could Not Determine FQDN. The Satellite
Synchronization page appears next.
Page 35
Chapter 4. Installation 31
Figure 4-10. Satellite Synchronization
16.
The Satellite Synchronization page allows you to initially populate your Satellite
with software channel metadata. This is possible during installation only if you chose
to register your Satellite with RHN. To synchronize, select the Perform Satellite
Sync checkbox and click Continue. After the installation, you will still need to populate the channels with packages. Refer to Chapter 6 Importing and Synchronizing
for instructions. The SSL Certificate page appears next.
Page 36
32 Chapter 4. Installation
Figure 4-11. SSL Certificate
17.
The SSL Certificate page collects information necessary to create the Secure Sockets Layer (SSL) certificate used by the Satellite and its client machines. In addition,
you may manage your SSL infrastructure using the RHN SSL Maintenance Tool.
Refer to the SSL Certificates chapter of the RHN Client Configuration Guide for
instructions.
Create an SSL Certificate Authority (CA) password and complete the rest of the
fields with your and your organization’s information. As always, ensure this informa-
Page 37
Chapter 4. Installation 33
tion exists on the backups of login information described in Chapter 2 Requirements.
The CA Cert Common Name field may already be populated with the name of the
host machine. This may need to be altered if you’re using multiple RHN Servers in
tandem.
Use the Expiration fields at the bottom to establish usage limits for the Certificate
Authority and the certificate. The public certificate will be placed in the
/var/www/html/pub/ directory on the Satellite where it can be downloaded from
and installed on all client systems. Once finished, click Generate Cert. The
Bootstrap Script page appears next.
Figure 4-12. Bootstrap Script
18.
The Bootstrap Script page allows you to create a script for redirecting client systems from the central RHN Servers to the Satellite. This script, to be placed in the
/var/www/html/pub/bootstrap/ directory of the Satellite, significantly reduces
the effort involved in reconfiguring all systems, which by default obtain packages
Page 38
34 Chapter 4. Installation
from the central RHN Servers. The required fields are pre-populated with values
derived from previous installation steps. Ensure this information is accurate.
Checkboxes offer options for including built-in security SSL and GNU Privacy
Guard (GPG) features, both of which are advised. In addition, you may enable
remote command acceptance and remote configuration management of the
systems to be bootstrapped here. Both features are useful for completing client
configuration. Finally, if you are using an HTTP proxy server, complete the related
fields. When finished, click Generate Bootstrap Script. The Installation
Complete page appears.
Figure 4-13. Installation Complete
19.
The Installation Complete page marks the end of the initial Satellite installation and
configuration. Click Done to reboot the system and create the Satellite Administrator
account. The Satellite Restart page appears.
Page 39
Chapter 4. Installation 35
Figure 4-14. Satellite Restart
20.
The Satellite Restart page requires no user input and merely provides a placeholder
while the system is rebooted. Once finished, the browser window is redirected to the
Satellite Administrator page.
Page 40
36 Chapter 4. Installation
Figure 4-15. Satellite Administrator
21.
The Satellite Administrator page enables you to create the Organization
Administrator account on the Satellite. This master account can conduct any task
available to all other user levels, as well as create other user accounts. As always,
ensure this information exists on the backups of login information described
in Chapter 2 Requirements. When finished, click Create Login. The Account
Created page appears.
Page 41
Chapter 4. Installation 37
Figure 4-16. Account Created
22. The Account Created page signals the end of the installation and configuration pro-
cess. You may now begin to import software packages and reconfigure client systems
to use the Satellite. Refer to Chapter 6 Importing and Synchronizing and the RHN
Client Configuration Guide (available under Help) respectively, for instructions.
4.3. Sendmail Configuration
If your RHN Satellite Server will serve Monitoring-entitled systems and you wish to acknowledge via email the alert notifications you receive, you must configure sendmail to
properly handle incoming mail. This is required by the email redirect feature, which allows
you to stop notifying users about a Monitoring-related event with a single reply.
Important
Some more restrictive corporate mail configurations will not allow mail to be sent from
an address that is not recognized as valid. Therefore, it may be necessary to configure
rogerthat01@{mail domain} as a valid email address in your corporate environment. Check with your mail systems administrator.
To configure sendmail correctly, run the following commands as root. First, create a symbolic link allowing sendmail to run the notification enqueuer with the following command:
ln -s /opt/notification/scripts/ack_enqueuer.pl /etc/smrsh/.
Page 42
38 Chapter 4. Installation
Next, edit the /etc/aliases file on the mail server and add the following line:
rogerthat01: | /etc/smrsh/ack_enqueuer.pl
Next, edit the /etc/mail/sendmail.mc file and change:
"DAEMON_OPTIONS(‘Port=smtp,Addr=127.0.0.1, Name=MTA’)dnl"
to:
"DAEMON_OPTIONS(‘Port=smtp, Name=MTA’)dnl"
Then, have the alias processed like so:
newaliases
Finally, update the sendmail-cf package:
up2date sendmail-cf
Note, disconnected installs must obtain this package from the ISO.
Restart sendmail:
service sendmail restart
4.4. MySQL Installation
This sections is applicable only if your RHN Satellite Server will serve Monitoring-entitled
systems and you wish to run MySQL probes against them. Refer to the Probes appendix
of the RHN Reference Guide for a list of available probes.
If you do wish to run MySQL probes, subscribe the Satellite to the Red Hat Enterprise
Linux AS Extras channel and install the mysql-server package either through the RHN
website or up2date.
Two extra packages will also be downloaded in the transaction. These are needed for the
mysql-server package to be installed and run successfully. Once finished, your Satellite
may be used to schedule MySQL probes.
Page 43
Chapter 5.
Entitlements
The RHN Satellite Server, like RHN itself, provides all services to customers through the
setting of entitlements. For RHN, entitlements are purchased by customers as needed; however, for RHN Satellite Server, entitlements are contractually agreed-upon beforehand, and
they are set at installation time. All public channels are automatically available; the private
channels that should also be made available through the Satellite are determined by the
RHN Entitlement Certificate.
The RHN Entitlement Certificate, which contains the precise set of entitlements attributed
to your organization, is provided by your Red Hat representative. Red Hat reserves the right
to compare the contents of that RHN Entitlement Certificate with the database’s entitlement
settings at any time to ensure compliance with the terms of the customer’s contract with
Red Hat.
The steps referenced in this section are typically carried out by the RHN Satellite Server
Installation Program itself and do not need to be repeated during initial installation. Instead, they are listed here for use by customers who have received a new RHN Entitlement
Certificate, such as one reflecting an increase in the number of entitlements.
5.1. Receiving the Certificate
The RHN Entitlement Certificate is an XML document that looks something like this:
<?xml version="1.0" encoding="UTF-8"?>
<rhn-cert version="0.1">
<rhn-cert-field name="product">RHN-SATELLITE-001</rhn-cert-field>
<rhn-cert-field name="owner">Clay’s Precious Satellite</rhn-cert-field>
<rhn-cert-field name="issued">2005-01-11 00:00:00</rhn-cert-field>
<rhn-cert-field name="expires">2005-03-11 00:00:00</rhn-cert-field>
<rhn-cert-field name="slots">30</rhn-cert-field>
<rhn-cert-field name="provisioning-slots">30</rhn-cert-field>
<rhn-cert-field name="nonlinux-slots">30</rhn-cert-field>
<rhn-cert-field name="channel-families" quantity="10" family="rhel-cluster"/>
<rhn-cert-field name="channel-families" quantity="30" family="rhel-ws-extras"/>
<rhn-cert-field name="channel-families" quantity="10" family="rhel-gfs"/>
<rhn-cert-field name="channel-families" quantity="10" family="rhel-es-extras"/>
<rhn-cert-field name="channel-families" quantity="40" family="rhel-as"/>
<rhn-cert-field name="channel-families" quantity="30" family="rhn-tools"/>
<rhn-cert-field name="satellite-version">3.6</rhn-cert-field>
<rhn-cert-field name="generation">2</rhn-cert-field>
<rhn-cert-signature>
-----BEGIN PGP SIGNATURE----Version: Crypt::OpenPGP 1.03
Page 44
40 Chapter 5. Entitlements
iQBGBAARAwAGBQJCAG7yAAoJEJ5yna8GlHkysOkAn07qmlUrkGKs7/5yb8H/nboG
mhHkAJ9wdmqOeKfcBa3IUDL53oNMEBP/dg==
=0Kv7
-----END PGP SIGNATURE-----
</rhn-cert-signature>
</rhn-cert>
Note
Do not try to use this RHN Entitlement Certificate; it is just an example.
The initial RHN Entitlement Certificate is generated by a member of the RHN team and
emailed to a consultant or customer prior to installation. This process helps guarantee that
we do not inadvertently install any RHN Satellite Servers that the RHN team does not
know about.
Save the XML file to the Satellite machine in preparation for activation.
5.2. Uploading the RHN Entitlement Certificate
If your RHN Satellite Server is connected to the Internet, you have the option of uploading
your new RHN Entitlement Certificate through the RHN website. To do this:
1. Log into https://rhn.redhat.com with your organization’s Satellite-entitled account.
2. Click Systems in the top navigation bar and then the name of the RHN Satellite
Server. You may also find the Satellite through the Satellite line item within the
Channels category.
3. In the System Details page, click the Satellite subtab and examine the existing certificate. Ensure you have a backup of this file by copying and pasting its contents into
a text editor.
4. Click Deactivate Satellite License at the bottom of the page. Then click Confirm
Deactivation. You will receive a message describing the deactivation at the top of
the page.
5. You may then browse to the location of your new RHN Entitlement Certificate or
paste its contents into the text field provided. When done, click Update Certificate.
Your Satellite now has access to additional channels and client entitlements outlined in
the new certificate. You may now synchronize it with the central RHN Servers. Refer to
Chapter 6 Importing and Synchronizing .
Page 45
Chapter 5. Entitlements 41
5.3. Managing the RHN Certificate with RHN Satellite
Activate
For disconnected Satellites or customers who prefer to work locally, Red Hat provides
a command line tool for managing your RHN Entitlement Certificate and activating the
Satellite using that certificate: RHN Satellite Activate (rhn-satellite-activate).
This is included with the Satellite installation as part of the rhns-satellite-tools
package.
5.3.1. Command Line Entitlement Options
The rhn-satellite-activate tool offers a handful of command line options for activating a Satellite using its RHN Entitlement Certificate:
Option Description
-h, --help Display the help screen with a list of options.
--sanity-only Confirm certificate sanity. Does not activate the
Satellite locally or remotely.
--disconnected Activates locally but not on remote RHN
Servers.
--rhn-cert=/PATH/TO/CERT Uploads new certificate and activates the
Satellite based upon the other options passed (if
any).
--systemid=/PATH/TO/SYSTEMID For testing only - Provides an alternative system
ID by path and file. The system default is used
if not specified.
--no-ssl For testing only - Disable SSL.
Table 5-1. RHN Entitlement Certificate Options
To use these options, insert the option and the appropriate value, if needed, after the
rhn-satellite-activate command. Refer to Section 5.3.2 Activating the Satellite.
5.3.2. Activating the Satellite
You should use the options in Table 5-1 to accomplish the following tasks in this order:
1. Validate the RHN Entitlement Certificate’s sanity (or usefulness).
Page 46
42 Chapter 5. Entitlements
2. Activate the Satellite locally by inserting the RHN Entitlement Certificate into the
local database.
3. Activate the Satellite remotely by inserting the RHN Entitlement Certificate into the
central RHN (remote) database. This is typically accomplished during local activation but may require a second step if you chose the --disconnected option.
Here are some examples depicting use of the tool and these options.
To validate an RHN Entitlement Certificate’s sanity only:
rhn-satellite-activate --sanity-only --rhn-cert=/path/to/demo.xml
To validate an RHN Entitlement Certificate and populate the local database:
rhn-satellite-activate --disconnected --rhn-cert=/path/to/demo.xml
To validate an RHN Entitlement Certificate and populate both the local and the RHN
database:
rhn-satellite-activate --rhn-cert=/path/to/demo.xml
Once you run this final command, the Satellite is running and able to serve
packages locally and synchronize with the central RHN Servers. Refer to
Chapter 6 Importing and Synchronizing .
Page 47
Chapter 6.
Importing and Synchronizing
After installing the RHN Satellite Server, you must provide it with the packages and channels to be served to client system. This chapter explains how to import that data and keep
it up to date whether the content is from RHN’s central servers, local media, or from one
Satellite within your organization to another.
Two tools, RHN Satellite Exporter and RHN Satellite Synchronization Tool, come installed as part of the rhns-sat-tools package.
6.1. Exporting with RHN Satellite Exporter
The RHN Satellite Exporter (rhn-satellite-exporter) tool exports Satellite content
in an XML format that can then be imported into another identical Satellite. The content
is exported into a directory specified by the user with the -d option. Once that directory
has been transported to another Satellite, the RHN Satellite Synchronization Tool may
be used to import the contents, synchronizing two Satellites.
6.1.1. rhn-satellite-exporter
The RHN Satellite Exporter can export the following content:
• Channel Families
• Architectures
• Channel metadata
• Blacklists
• RPMs
• RPM metadata
• Errata
• Kickstarts
The amount of time it takes rhn-satellite-exporter to export data is dependent
on the number and size of the channels being exported. Using the --no-packages,
--no-kickstarts, --no-errata, and --no-rpms options reduces the amount of time
required for rhn-satellite-exporter to run, but will also prevent potentially useful
information from being exported. For that reason, these options should only be used when
you are certain that you will not need the content that they exclude. Additionally, you
must use the matching options for satellite-sync when importing the data. For
Page 48
44 Chapter 6. Importing and Synchronizing
example, if you use --no-kickstarts with rhn-satellite-exporter you must use
satellite-sync’s --no-kickstarts option when importing the data.
When exporting an RHN base channel, you must also export the tools channel associated
with that base channel in order to kickstart machines to the distribution in the base channel.
For instance, if you export rhel-i386-as-4 you must also export the rhn-tools-rhel-4-as-
i386 channel in order to kickstart machines to Red Hat Enterprise Linux 4 AS. This is
because the tools channels contain the auto-kickstart packages that install packages for
kickstarting a machine through the Satellite.
The RHN Satellite Exporter offers several command line options. To use them, insert the
option and appropriate value after the rhn-satellite-exporter command.
Option Description
-d, --dir= Place the exported information into this
directory.
-cCHANNEL_LABEL,
--channel=CHANNEL_LABEL
Process data for this specific channel
(specified by label) only. NOTE: the
channel’s *label* is NOT the same as the
channel’s *name*.
--list-channels List all available channels and exit.
--list-steps List all of the steps that
rhn-satellite-exporter takes while exporting
data. These can be used as values for
--step.
-p --print-configuration Print the configuration and exit.
--print-report Print a report to the terminal when the
export is complete.
--print-report Print a report to the terminal when the
export is complete.
--no-rpms Do not retrieve actual RPMs.
--no-packages Do not export RPM metadata.
--no-errata Do not process Errata information.
--no-kickstarts Do not process kickstart data (provisioning
only).
--debug-level=LEVEL_NUMBER Override the amount of messaging sent to
log files and generated on the screen set in
/etc/rhn/rhn.conf, 0-6 (2 is default).
Page 49
Chapter 6. Importing and Synchronizing 45
Option Description
--email Email a report of what was exported and
what errors may have occurred.
--traceback-mail Alternative email address for --email.
--db=DB Include alternate database connect string:
username/password@SID.
Table 6-1.
6.1.2. Exporting
To perform a RHN Satellite Exporter export, the following prerequisites must be met:
• The RHN Satellite Server installation must have been performed successfully.
• There must be sufficient disk space in the directory specified in the --dir option to
contain the exported contents.
Although it is not a requirement for the export to succeed, the export will be most useful
with performed on a Satellite that has populated channels.
6.1.2.1. Running the Export
First, be sure to configure the Satellite in the manner that you would either like to duplicate
in another Satellite or back up to a storage solution. Second, select the contents you would
like to export. You can choose not to export RPMs, errata, or kickstarts by using the options
mentioned in Section 6.1.1 rhn-satellite-exporter. Finally, execute the command
as root. The following is an example command:
rhn-satellite-exporter --dir=/var/rhn-sat-export --no-errata
When finished, the export directory may be moved to another Satellite or a storage solution
using rsync or scp -r.
6.2. Importing with RHN Satellite Synchronization Tool
Before distributing packages via RHN Satellite Server, the packages must first be uploaded
to the Satellite. This section describes the process for importing packages and other channel
data.
Page 50
46 Chapter 6. Importing and Synchronizing
Important
To populate custom channels correctly, you must first populate at least one Red Hat base
channel. The RHN Satellite Synchronization Tool creates the necessary directory struc-
tures and permissions; without these, the custom channel tools will not work properly. For
this reason, you should use these instructions to set up your base channel(s) and then
refer to the RHN Channel Management Guide for steps to establish custom channels.
To perform the RHN Satellite Server import, the following prerequisites must be met:
• The RHN Satellite Server installation must have been performed successfully.
• The Red Hat Network Channel Content ISOs or RHN Satellite Exporter data must be
available, or the Satellite must have access to the Internet and the RHN website.
Although it is possible to conduct the import directly from the RHN website, this should
be done only if Channel Content ISOs are not available. It takes a long time to populate a
channel from scratch over the Internet. For this reason, Red Hat urges you to use ISOs, if
they are available, for initial import.
6.2.1. satellite-sync
The RHN Satellite Synchronization Tool enables an RHN Satellite Server to update its
database metadata and RPM packages with those of RHN’s central servers, another Satellite within your organization, or local media. To launch it, execute the following command
as root:
satellite-sync
This tool can be used in a a closed environment, such as the one created with a disconnected
install, or it may obtain data directly over the Internet. Closed environment imports can
get their data from downloaded ISOs or from the XML data generated by RHN Satellite
Exporter.
The RHN Satellite Synchronization Tool works incrementally, or in steps. For it to ob-
tain Errata information, it must first know the packages contained. For the packages to be
updated, the tool must first identify the associated channel(s). For this reason, the RHN
Satellite Synchronization Tool performs its actions in the following order:
1. channel-families — Import/synchronize channel family (architecture) data.
2. channels — Import/synchronize channel data.
3. rpms — Import/synchronize RPMs.
4. packages — Import/synchronize full package data for those RPMs retrieved successfully.
Page 51
Chapter 6. Importing and Synchronizing 47
5. errata — Import/synchronize Errata information.
Each of these steps can be initiated individually for testing purposes with the effect of forcing the tool to stop when that step is complete. All steps that precede it, however, will have
taken place. Therefore, calling the rpms step will automatically ensure the channels and
channel-families steps take place first. To initiate an individual step, use the --step
option, like so:
satellite-sync --step=rpms
In addition to --step, the RHN Satellite Synchronization Tool offers many other com-
mand line options. To use them, insert the option and the appropriate value after the
satellite-sync command when launching import/synchronization.
Option Description
-h, --help Display this list of options and exit.
-d=, --db=DB Include alternate database connect
string: username/password@SID.
-m=, --mount-point=MOUNT_POINT Import/sync from local media
mounted to the Satellite. To be used
in closed environments (such as
those created during disconnected
installs).
--list-channels List all available channels and exit.
-c=, --channel=CHANNEL_LABEL Process data for this channel only.
Multiple channels can be included
by repeating the option. If no
channels are specified, all channels
on the Satellite will be freshened.
-p, --print-configuration Print the current configuration and
exit.
--no-ssl Not Advisable - Turn off SSL.
--step=STEP_NAME Perform the sync process only to the
step specified. Typically used in
testing.
--no-rpms Do not retrieve actual RPMs.
--no-packages Do not process full package data.
--no-errata Do not process Errata information.
Page 52
48 Chapter 6. Importing and Synchronizing
Option Description
--no-kickstarts Do not process kickstart data
(provisioning only).
--force-all-packages Forcibly process all package data
without conducting a diff.
--debug-level=LEVEL_NUMBER Override the amount of messaging
sent to log files and generated on the
screen set in /etc/rhn/rhn.conf,
0-6 (2 is default).
--email Email a report of what was
imported/synchronized to the
designated recipient of traceback
email.
--traceback-mail=TRACEBACK_MAIL Direct sync output (from --email)
to this email address.
-s=, --server=SERVER Include the hostname of an
alternative server to connect to for
synchronization.
--http-proxy=HTTP_PROXY Add an alternative HTTP proxy
server in the form hostname:port.
--http-proxy-username=PROXY_USERNAME Include the username for the
alternative HTTP proxy server.
--http-proxy-password=PROXY_PASSWORD Include the password for the
alternative HTTP proxy server.
--ca-cert=CA_CERT Use an alternative SSL CA
certificate by including the full path
and filename.
--systemid=SYSTEM_ID For debugging only - Include path to
alternative digital system ID.
--systemid=SYSTEM_ID For debugging only - Include path to
alternative digital system ID.
--batch-size=BATCH_SIZE For debugging only - Set maximum
batch size in percent for
XML/database-import processing.
Open man satellite-sync for more
information.
Table 6-2. Satellite Import/Sync Options
Page 53
Chapter 6. Importing and Synchronizing 49
If no options are included, satellite-sync synchronizes all channels that already exist
in the Satellite’s database. By default, the --step (all steps) option is enabled.
Keep in mind that the --channel option requires the channel label, not its name.
For instance, use "rhel-i386-as-3" not "Red Hat Enterprise Linux 3 i386." Use the
--list-channels option to obtain a list of all channels by label. All displayed channels
are available for importing and synchronizing.
6.2.2. Preparing for Import from Local Media
Channel Content ISOs are special collections that contain both packages and XML dumps
of metadata. The ISO images can be downloaded from the RHN website on a machine connected to the Internet and then transferred to the Satellite. After logging in, click Channels
in the top navigation bar and then the name of the channel for your version of RHN Satellite Server. Click the Downloads tab and use the instructions on the page to obtain the
Channel Content ISOs, available by version of Red Hat Enterprise Linux. If the desired
Channel Content ISOs do not appear, ensure your RHN Entitlement Certificate has been
uploaded to RHN and correctly identifies the target channels.
Channel Content ISOs are mounted and then copied to a temporary repository directory.
Before mounting the ISOs, ensure the temporary repository has enough disk space to copy
all the contents into a single directory. For a single channel, the approximate required space
is 3 GB. The process to copy Channel Content ISOs is to mount each one, copy its contents
to the temporary repository, and then unmount the ISO. Each channel consists of several
ISOs. Once finished, the administrator should delete the temporary directory and all of its
contents. Follow these steps:
1. Log into the machine as root.
2. Insert the first Channel Content ISO that has been burned to disc.
3. Create a directory in /mnt/ to store the file(s) with the command:
mkdir /mnt/import/
4. Mount the ISO file from within the directory containing it using the command:
mount iso_filename /mnt/import -o loop
5. Create a target directory for the files, such as:
mkdir /var/rhn-sat-import/
6. This sample command assumes the administrator wants to copy the contents of the
ISO (mounted in /mnt/import/) into /var/rhn-sat-import/:
cp -ruv /mnt/import/* /var/rhn-sat-import/
7. Then unmount /mnt/import in preparation for the next CD or ISO:
umount /mnt/import
8. Repeat these steps for each Channel Content ISO of every channel to be imported.
Page 54
50 Chapter 6. Importing and Synchronizing
6.2.3. Running the Import
The rhns-satellite-tools package provides the satellite-sync program for managing all package, channel, and errata imports and synchronizations.
The following process assumes in the previous step the user has copied all data to
/var/rhn-sat-import.
The first step in importing channels into the database is listing the channels available for
import. This is accomplished with the command:
satellite-sync --list-channels --mount-point /var/rhn-sat-import
The next step is to initiate the import of a specific channel. Do this using a channel label
presented in the previous list. The command will look like:
satellite-sync -c rhel-i386-as-3 --mount-point /var/rhn-sat-import
If you are importing content that was exported from another Satellite, be sure to use the -m
or --mount-point option of satellite-sync and include the directory that contains
the exported content.
Note
Importing package data can take up to two hours per channel. You may begin registering
systems to channels as soon as they appear in the RHN Satellite Server’s website. No
packages are necessary for registration, although updates cannot be retrieved from the
Satellite until the channel is completely populated.
You may repeat this step for each channel or include them all within a single command by
passing each channel label preceded by an additional -c flag, like so:
satellite-sync -c channel-label-1 -c channel-label-2 --mount-point /var/rhn-sat-import
This conducts the following tasks in this order:
1. Populating the tables describing common features for channels (channel
families). This can also be accomplished individually by passing the
--step=channel-families option to satellite-sync.
2. Creating a particular channel in the database and importing the metadata describing
the channel. Individually, use the --step=channels option.
3. Moving the RPM packages from the temporary repository into their final location.
Individually, use the --step=rpms option.
Page 55
Chapter 6. Importing and Synchronizing 51
4. Parsing the header metadata for each package in the channel, uploading the package
data, and associating it with the channel. Individually, use the --step=packages
option.
5. Identifying Errata associated with the packages and including them in the repository.
Individually, use the --step=errata option.
After running the preceding sample command, the population of the channel should be
complete. All of the packages should have been moved out of the repository; this can be
verified with the command cd /var/rhn-sat-import/; ls -alR | grep rpm. If
all RPMs have been installed and moved to their permanent locations, then this count will
be zero, and the administrator may safely remove the temporary repository (in this case,
/var/rhn-sat-import/).
6.3. Synchronizing
An update channel is only as useful as the freshness of the information in that channel.
Since the RHN Satellite Server is designed to be a standalone environment, any update
advisories published by RHN must be manually imported and synchronized by the administrator of the RHN Satellite Server.
During synchronization over the Internet, the RHN Satellite Synchronization Tool per-
forms the following steps:
1. Connects over SSL to central RHN Servers, authenticates itself as an RHN Satellite Server, and triggers an export of RHN data — unless a local mount point for
RHN-exported data is specified, in which case no connection is necessary. Refer
to Section 6.3.2 Synchronizing Errata and Packages via Local Media for an expla-
nation.
2. Examines the export and identifies differences between the RHN Satellite Server
data set and the exported RHN data set. For a particular channel, the following information is analyzed:
• Channel metadata
• Metadata of all packages in that channel
• Metadata for all Errata that affect that channel
Note
All analysis is performed on the RHN Satellite Server; the central RHN Servers
deliver only an export of its channel information and remain ignorant of any details
regarding the RHN Satellite Server.
Page 56
52 Chapter 6. Importing and Synchronizing
3. After the analysis of the export data, any differences are imported into the RHN
Satellite Server database. Please note that importing new packages may take variable
lengths of time. For a large update, an import can take many hours.
The satellite-sync command can be used in two modes: via RHN and via local media.
6.3.1. Synchronizing Errata and Packages Directly via RHN
For customers who want to sync data as frequently as possible and who can initiate connections outside of their own environments, the satellite sync can be run over the Internet
through SSL. This is the default setting for the satellite sync script. For example:
satellite-sync -c rhel-i386-as-3
This connects to central Red Hat Network Servers and performs the process described
above. Multiple channels can be included by repeating the option. If no channels are specified, all channels on the Satellite will be refreshed.
6.3.2. Synchronizing Errata and Packages via Local Media
For customers who cannot connect their Satellite directly to RHN, Red
Hat recommends downloading Channel Content ISOs to a separate,
Internet-connected system and then transferring them to the Satellite. Refer to
Section 6.2.2 Preparing for Import from Local Media for instructions on downloading the
ISOs. For ease of import, we recommend that the data be copied from media directly into
a common repository through a command such as the following:
cp -rv /mnt/cdrom/* /var/rhn-sat-sync/
Then, the following command:
satellite-sync -c rhel-i386-as-3 --mount-point
/var/rhn-sat-sync
This can be used to perform the sync process described above, using the dump files in
/var/rhn-sat-sync to perform the necessary comparisons and imports. See
Section 6.2.3 Running the Import for precise steps.
Page 57
Chapter 7.
Troubleshooting
This chapter provides tips for determining the cause of and resolving the most common
errors associated with RHN Satellite Server. If you need additional help, contact Red Hat
Network support at https://rhn.redhat.com/help/contact.pxt. Log in using your Satelliteentitled account to see your full list of options.
In addition, you may package configuration information and logs from
the Satellite and send them to Red Hat for further diagnosis. Refer to
Section 7.5 Satellite Debugging by Red Hat for instructions.
7.1. Log Files
Virtually every troubleshooting step should start with a look at the associated log file or
files. These provide invaluable information about the activity that has taken place on the
device or within the application that can be used to monitor performance and ensure proper
configuration. See Table 7-1 for the paths to all relevant log files:
Component/Task Log File Location
Apache HTTP Server /var/log/httpd/ directory
RHN Satellite Server /var/log/rhn/ directory
RHN Satellite Server
Installation Program
/var/log/rhn_satellite_install.log
Database installation -
Embedded Database
/var/log/rhn/rhn-database-installation.log
Database population /var/log/rhn/populate_db.log
RHN Satellite
Synchronization Tool
/var/log/rhn/rhn_server_satellite.log
Monitoring infrastructure /home/nocpulse/var/ directory
Monitoring notifications /opt/notification/var/ directory
RHN DB Control - Embedded
Database
/var/log/rhn_database.log
RHN Task Engine
(taskomatic)
/var/log/messages
Page 58
54 Chapter 7. Troubleshooting
Component/Task Log File Location
Red Hat Update Agent /var/log/up2date
XML-RPC transactions /var/log/rhn/rhn_server_xmlrpc.log
Table 7-1. Log Files
7.2. General Problems
To begin troubleshooting general problems, examine the log file or files related to the
component exhibiting failures. A useful exercise is to issue the tail -f command for all
log files and then run up2date --list. You should then examine all new log entries for
potential clues.
A common issue is full disk space. An almost sure sign of this is the appearance of halted
writing in the log files. If logging stopped during a write, such as mid-word, you likely
have filled disks. To confirm this, run this command and check the percentages in the
Use% column:
df -h
In addition to log files, you can obtain valuable information by retrieving the status of your
RHN Satellite Server and its various components. This can be done with the command:
service rhn-satellite status
In addition, you can obtain the status of components such as the Apache HTTP Server and
the RHN Task Engine individually. For instance, to view the status of the Apache HTTP
Server, run the command:
service httpd status
If the Apache HTTP Server isn’t running, entries in your /etc/hosts file may be incorrect. Refer to Section 7.3 Host Not Found/Could Not Determine FQDN for a description
of this problem and possible solutions.
To obtain the status of the RHN Task Engine, run the command:
service taskomatic status
For more information, see Section 8.7.1.1 Maintaining the RHN Task Engine.
To obtain the status of the Satellite’s Embedded Database, if it exists, run the command:
service rhn-database status
To determine the version of your database schema, run the command:
Page 59
Chapter 7. Troubleshooting 55
rhn-schema-version
To derive the character set types of your Satellite’s database, run the command:
rhn-charsets
If the administrator is not getting email from the RHN Satellite Server, confirm the correct
email addresses have been set for traceback_mail in /etc/rhn/rhn.conf.
If the traceback mail is marked from dev-null@rhn.redhat.com and you would like the
address to be valid for your organization, include the web.default_mail_from option
and appropriate value in /etc/rhn/rhn.conf.
If importing/synchronizing a channel fails and you can’t recover it in any other way, run
this command to delete the cache:
rm -rf temporary-directory
Note that Section 6.2.2 Preparing for Import from Local Media suggested that this tempo-
rary directory be /var/rhn-sat-import/.
Next, restart the importation or synchronization.
If up2date or the push capability of the RHN Satellite Server ceases to function, it is
possible that old log files may be at fault. Stop the jabberd daemon before removing these
files. To do so, issue the following commands as root:
service jabberd stop
cd /var/lib/jabberd
rm -f _db*
service jabberd start
7.3. Host Not Found/Could Not Determine FQDN
Because RHN configuration files rely exclusively on fully qualified domain names
(FQDN), it is imperative key applications are able to resolve the name of the RHN
Satellite Server into an IP address. Red Hat Update Agent, Red Hat Network
Registration Client, and the Apache HTTP Server are particularly prone to this problem
with the RHN applications issuing errors of "host not found" and the Web server stating
"Could not determine the server’s fully qualified domain name" upon failing to start.
This problem typically originates from the /etc/hosts file. You may confirm this by
examining /etc/nsswitch.conf, which defines the methods and the order by which
domain names are resolved. Usually, the /etc/hosts file is checked first, followed by
Network Information Service (NIS) if used, followed by DNS. One of these has to succeed
for the Apache HTTP Server to start and the RHN client applications to work.
Page 60
56 Chapter 7. Troubleshooting
To resolve this problem, identify the contents of the /etc/hosts file. It may look like
this:
127.0.0.1 this_machine.example.com this_machine localhost.localdomain \
localhost
First, in a text editor, remove the offending machine information, like so:
127.0.0.1 localhost.localdomain.com localhost
Then, save the file and attempt to re-run the RHN client applications or the Apache HTTP
Server. If they still fail, explicitly identify the IP address of the Satellite in the file, such as:
127.0.0.1 localhost.localdomain.com localhost
123.45.67.8 this_machine.example.com this_machine
Replace the value here with the actual IP address of the Satellite. This should resolve the
problem. Keep in mind, if the specific IP address is stipulated, the file will need to be
updated when the machine obtains a new address.
7.4. Connection Errors
A common connection problem, indicated by SSL_CONNECT errors, is the result of a
Satellite being installed on a machine whose time had been improperly set. During the
Satellite installation process, SSL certificates are created with inaccurate times. If the Satellite’s time is then corrected, the certificate start date and time may be set in the future,
making it invalid.
To troubleshoot this, check the date and time on the clients and the Satellite with the following command:
date
The results should be nearly identical for all machines and within the "notBefore" and
"notAfter" validity windows of the certificates. Check the client certificate dates and times
with the following command:
openssl x509 -dates -noout -in /usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT
Check the Satellite server certificate dates and times with the following command:
openssl x509 -dates -noout -in /etc/httpd/conf/ssl.crt/server.crt
By default, the server certificate has a one-year life while client certificates are good for 10
years. If you find the certificates are incorrect, you can either wait for the valid start time,
if possible, or create new certificates, preferably with all system times set to GMT.
Page 61
Chapter 7. Troubleshooting 57
The following measures can be used to troubleshoot general connection errors:
• Attempt to connect to the RHN Satellite Server’s database at the command line using
the correct connection string as found in /etc/rhn/rhn.conf:
sqlplus username/password@sid
• Ensure the RHN Satellite Server is using Network Time Protocol (NTP) and set to the
appropriate time zone. This also applies to all client systems and the separate database
machine in RHN Satellite Server with Stand-Alone Database.
• Confirm the correct package:
rhn-org-httpd-ssl-key-pair-MACHINE_NAME-VER-REL.noarch.rpm
is installed on the RHN Satellite Server and the corresponding
rhn-org-trusted-ssl-cert-*.noarch.rpm or raw CA SSL public (client)
certificate is installed on all client systems.
• Verify the client systems are configured to use the appropriate certificate.
• If also using one or more RHN Proxy Servers, ensure each Proxy’s SSL certificates are
prepared correctly. The Proxy should have both its own server SSL key-pair and CA SSL
public (client) certificate installed, since it will serve in both capacities. Refer to the SSL
Certificates chapter of the RHN Client Configuration Guide for specific instructions.
• Make sure client systems are not using firewalls of their own, blocking required ports as
identified in Section 2.4 Additional Requirements.
7.5. Satellite Debugging by Red Hat
If you’ve exhausted these troubleshooting steps or want to defer them to Red Hat Network
professionals, Red Hat recommends you take advantage of the strong support that comes
with RHN Satellite Server. The most efficient way to do this is to aggregate your Satellite’s
configuration parameters, log files, and database information and send this package directly
to Red Hat.
RHN provides a command line tool explicitly for this purpose: The Satellite Diagnostic
Info Gatherer, commonly known by its command satellite-debug. To use this tool,
issue the command as root. You will see the pieces of information collected and the single
tarball created, like so:
[root@miab root]# satellite-debug
Collecting and packaging relevant diagnostic information.
Warning: this may take some time...
* copying configuration information
* copying logs
* querying RPM database (versioning of RHN Satellite, etc.)
* querying schema version and database character sets
* get diskspace available
* timestamping
Page 62
58 Chapter 7. Troubleshooting
* creating tarball (may take some time): /tmp/satellite-debug.tar.bz2
* removing temporary debug tree
Debug dump created, stored in /tmp/satellite-debug.tar.bz2
Deliver the generated tarball to your RHN contact or support channel.
Once finished, email the new file from the /tmp/ directory to your Red Hat representative
for immediate diagnosis.
Page 63
Chapter 8.
Maintenance
Because of the RHN Satellite Server’s unique closed environment, its users are provided
with abilities not available to any other Red Hat Network customers. In addition, the Satellite itself also requires maintenance. This chapter discusses the procedures that should be
followed to carry out administrative functions outside of standard use, as well as to apply
patches to the RHN Satellite Server.
8.1. Managing the Satellite Service
Since the RHN Satellite Server consists of a multitude of individual components, Red Hat
provides a master service that allows you to stop, start, or retrieve status information from
the various services in the appropriate order: rhn-satellite. This helper service accepts
all of the typical commands:
service rhn-satellite start
service rhn-satellite stop
service rhn-satellite restart
service rhn-satellite status
Use the rhn-satellite service to shut down and bring up the entire RHN Satellite Server
and retrieve status messages from all of its services at once.
8.2. Updating the Satellite
If any critical updates are made to RHN Satellite Server, they will be released in the form
of an Erratum for the RHN Satellite Server.
For RHN Satellite Server systems that may be connected to the Internet, the best method for
applying these Errata Updates is using the Red Hat Update Agent via Red Hat Network.
Since the RHN Satellite Server is subscribed to Red Hat Network during initial installation,
the user should be able to run up2date -u on the RHN Satellite Server or use the website
at https://rhn.redhat.com to apply the updates.
Important
Apache RPMs do not restart the httpd service upon installation. Therefore, after conducting a full update of an RHN Satellite Server (such as with the command up2date -uf),
Apache may fail. To avoid this, make sure you restart the httpd service after upgrading it.
Page 64
60 Chapter 8. Maintenance
For RHN Satellite Server systems that may not be connected to the Internet, the packages
themselves may be retrieved using a customer account at https://rhn.redhat.com. Then, they
can be applied manually by the customer according to instructions in the Errata Advisory.
Warning
It is very important to read the Errata Advisory before applying any RHN Satellite Server
Errata Updates. Additional configuration steps may be required to apply certain RHN
Satellite Server updates, especially if they involve the database. In such cases, the advisory will contain specific and detailed information about necessary steps that may be
required.
If instead of installing new Satellite packages, you are attempting to update the server’s
RHN Entitlement Certificate, such as to increase its number of client systems, refer to
Chapter 5 Entitlements for instructions.
8.3. Backing Up the Satellite
Backing up an RHN Satellite Server can be done in several ways. Regardless of the method
chosen, the associated database also needs to be backed up. For the Stand-Alone Database,
consult your organization’s database administrator. For the Embedded Database, refer to
Section 8.4 Using RHN DB Control for a complete description of this process and the options available.
Here are the minimum files and directories Red Hat recommends backing up:
• /rhnsat/ - Embedded Database only (never to be backed up while the database is
running - refer to Section 8.4.2 Backing up the Database)
• /etc/sysconfig/rhn/
• /etc/rhn/
• /etc/tnsnames.ora
• /etc/httpd/
• /var/www/rhns/
• /var/www/html/pub/
• /var/satellite/redhat/1/ - custom RPMs
• /etc/pxtdb.conf - pertains only to RHN Satellite Server 1.1.x.
Page 65
Chapter 8. Maintenance 61
If possible, back up /var/satellite/, as well. In case of failure, this
will save lengthy download time. Since /var/satellite/ (specifically
/var/satellite/redhat/NULL/) is primarily a duplicate of Red Hat’s RPM
repository, it can be regenerated with satellite-sync. Red Hat recommends the
entire /var/satellite/ tree be backed up. In the case of disconnected satellites,
/var/satellite/ must be backed up.
Backing up only these files and directories would require reinstalling the RHN
Satellite Server ISO RPMs and reregistering the Satellite. In addition, Red
Hat packages would need to be resynchronized using the satellite-sync
tool. Finally, you would have to reinstall the /etc/sysconfig/rhn/ssl/\
rhn-org-httpd-ssl-key-pair-MACHINE_NAME-VER-REL.noarch.rpm.
Another method would be to back up all of the files and directories mentioned above but
reinstall the RHN Satellite Server without reregistering it. During the installation, cancel
or skip the RHN registration and SSL certificate generation sections.
The final and most comprehensive method would be to back up the entire machine. This
would save time in downloading and reinstalling but would require additional disk space
and back up time.
8.4. Using RHN DB Control
RHN Satellite Server with Embedded Database requires a utility for managing that
database. Red Hat provides just such a tool: RHN DB Control. This command line utility
allows you to do everything from make, verify, and restore backups to obtain database
status and restart it when necessary. You must be the oracle user to invoke RHN DB
Control. To begin, switch to the oracle user:
su - oracle
Next, issue the following command:
db-control option
8.4.1. DB Control Options
RHN DB Control offers many command line options. To use them, as oracle insert the
option and the appropriate value, if needed, after the db-control command.
Option Description
help Lists these db-control options with
additional details.
Page 66
62 Chapter 8. Maintenance
Option Description
backup DIRNAME Backs up the database to the directory specified.
examine DIRNAME Examines the contents of a backup directory.
Returns the timestamp of backup creation and
reports on its contents.
extend Increase the RHN Oracle tablespace
report Reports on current usage of database space.
restore DIRNAME Restores the database from backup kept in
DIRNAME. Database must be stopped for this
command to run successfully.
start Starts the database instance. This can also be
accomplished by issuing the service
rhn-database start command as root.
status Shows the current status of the database, either
"running" or "offline".
stop Stops the database instance. This can also be
accomplished by issuing the service
rhn-database stop command as root.
tablesizes Show space report for each table
verify DIRNAME Verifies the contents of the backup kept in
DIRNAME. This command checks the
md5sums of each of the files kept in the backup.
Table 8-1. RHN DB Control Options
8.4.2. Backing up the Database
Red Hat recommends performing nightly backups of the Embedded Database and moving
the resulting directory to another system via NFS, SCP, FTP, etc. Preferably, this backup
system resides off-site. To conduct a backup, shut down the database and related services
first by issuing the following commands in this order as root:
service httpd stop
service taskomatic stop
service rhn-database stop
Then switch to the oracle user and issue this command to initiate the backup:
Page 67
Chapter 8. Maintenance 63
db-control backup DIRNAME
Backup files are stored in the directory specified. Note that this is a cold backup; the
database must be stopped before running this command. This process takes several minutes. The first backup is a good indicator of how long subsequent backups will take.
Once the backup is complete, return to root user mode and restart the database and related
services with these commands in this order:
service rhn-database start
service taskomatic start
service httpd start
You should then copy that backup to another system using rsync or another file-transfer
utility. Red Hat strongly recommends scheduling the backup process automatically using
cron jobs. For instance, back up the system at 3 a.m. and then copy the backup to the
separate repository (partition, disk, or system) at 6 a.m.
8.4.3. Verifying the Backup
Backing up the Embedded Database is useful only if you can ensure the integrity of the resulting backup. RHN DB Control provides two methods for reviewing backups, one brief,
one more detailed. To conduct a quick check of the backup’s timestamp and determine any
missing files, issue this command as oracle:
db-control examine DIRNAME
To conduct a more thorough review, including checking the md5sum of each of the files in
the backup, issue this command as oracle:
db-control verify DIRNAME
8.4.4. Restoring the Database
RHN DB Control makes Embedded Database restoration a relatively simple process. As
in the creation of backups, you will need to shut down the database and related services
first by issuing the following commands in this order as root:
service httpd stop
service taskomatic stop
service rhn-database stop
Then switch to the oracle user and issue this command, including the directory containing
the backup, to begin the restoration:
Page 68
64 Chapter 8. Maintenance
db-control restore DIRNAME
This not only restores the Embedded Database but first verifies the contents of the backup
directory using md5sums. Once the restoration is complete, return to root user mode and
restart the database and related services with these commands in this order:
service rhn-database start
service taskomatic start
service httpd start
8.5. Cloning the Satellite with Embedded DB
You may limit outages caused by hardware or other failures by cloning the Satellite with
Embedded Database in its entirety. The secondary Satellite machine can be prepared for
use if the primary fails. To clone the Satellite, perform these tasks:
1. Install RHN Satellite Server with Embedded Database (and a base install of Red Hat
Enterprise Linux AS) on a separate machine, skipping the SSL Certificate generation
step.
2. Back up the primary Satellite’s database daily using the commands described in
Section 8.4.2 Backing up the Database. If this is done, only changes made the day
of the failure will be lost.
3. Establish a mechanism to copy the backup to the secondary Satellite and keep these
repositories synchronized using a file transfer program such as rsync. If you’re using
a SAN, copying isn’t necessary.
4. Use RHN DB Control’s restore option to import the duplicate data.
5. If the primary Satellite fails, transfer the SSL certificates from it to the secondary.
Refer to the Sharing Certificates section of the RHN Client Configuration Guide for
precise instructions.
6. Change DNS to point to the new machine or configure your load balancer appropriately.
8.6. Establishing Redundant Satellites with Stand-Alone
DB
In keeping with the cloning option available to Satellite with Embedded Database, you may
limit outages on Satellites with Stand-Alone Database by preparing redundant Satellites.
Unlike cloning a Satellite with Embedded Database, redundant Satellites with Stand-Alone
Page 69
Chapter 8. Maintenance 65
Database may be run as active, as well as standby. This is entirely up to your network
topology and is independent of the steps listed here.
To establish this redundancy, first install the primary Satellite normally, except the value
specified in the Common Name field for the SSL certificate must represent your highavailability configuration, rather than the hostname of the individual server. Then:
1. Prepare the Stand-Alone Database for failover using Oracle’s recommendations for
building a fault-tolerant database. Consult your database administrator.
2. Install RHN Satellite Server with Stand-Alone Database (and a base install of Red
Hat Enterprise Linux AS) on a separate machine, skipping the database configuration, database schema, SSL certificate, and bootstrap script generation steps. Include
the same RHN account and database connection information provided during the
initial Satellite install and register the new Satellite.
If your original SSL certificate does not take your high-availability solution into
account, you may create a new one with a more appropriate Common Name value
now. In this case, you may also generate a new bootstrap script that captures this new
value.
3. After installation, copy the following files from the primary Satellite to the secondary
Satellite:
• /etc/rhn/rhn.conf
• /etc/tnsnames.ora
• /var/www/rhns/server/secret/rhnSecret.py
4. Copy and install the server-side SSL certificate RPMs from the primary Satellite to
the secondary. Refer to the Sharing Certificates section of the RHN Client Config-
uration Guide for precise instructions. Remember, the Common Name value must
represent the combined Satellite solution, not a single machine’s hostname.
If you generated a new SSL certificate during Satellite installation that included a
new Common Name value, copy the SSL certificate RPMs from the secondary to
the primary Satellite and redistribute the client-side certificate. If you also created
another bootstrap script, you may use this to install the certificate on client systems.
5. If you did not create a new bootstrap script, copy the contents of
/var/www/html/pub/bootstrap/ from the primary Satellite to the secondary. If
you did generate a new one, copy that directory’s contents to the primary Satellite.
6. Turn off the RHN Task Engine on the secondary Satellite with the following com-
mand:
/sbin/service taskomatic stop
Page 70
66 Chapter 8. Maintenance
You may use custom scripting or other means to establish automatic start-up/failover
of the RHN Task Engine on the secondary Satellite. Regardless, it will need to be
started upon failover.
7. Share channel package data (by default located in /var/satellite) between the
Satellites over some type of networked storage device. This eliminates data replication and ensures a consistent store of data for each Satellite.
8. Make the various Satellites available on your network via Common Name and a
method suiting your infrastructure. Options include round-robin DNS, a network
load balancer, and a reverse-proxy setup.
8.7. Conducting Satellite-Specific Tasks
Using a RHN Satellite Server is quite similar to using the hosted version of Red Hat Network. For this reason, you should consult the RHN Reference Guide to obtain detailed instructions to standard tasks, such as editing System Profiles and updating packages. Tasks
directly related to managing custom channels and Errata are covered in the RHN Chan-
nel Management Guide. This section seeks to explain activities available only to Satellite
customers.
8.7.1. Using the Tools menu
In addition to the standard categories available to all users through the top navigation bar,
Satellite Organization Administrators also have access to a Tools menu. Clicking this opens
the RHN Internal Tools page.
Page 71
Chapter 8. Maintenance 67
Figure 8-1. Internal Tools
To refresh the view of channels that have been updated but do not yet reflect those modifications on the Satellite website, click the Update Errata cache now link on this page.
8.7.1.1. Maintaining the RHN Task Engine
The default display shows the status of the RHN Task Engine. This tool is a daemon that
runs on the Satellite server itself and performs routine operations, such as database cleanup,
Errata mailings, etc., that must be performed in the background. The page displays the
execution times for various activities carried out by the daemon.
Administrators should ensure the RHN Task Engine stays up and running. If this daemon
hangs for any reason, it can be restarted using it’s filename, taskomatic. As root, run the
command:
/sbin/service taskomatic restart
Page 72
68 Chapter 8. Maintenance
Other service commands can also be used, including start, stop, and status.
8.7.1.2. Accessing the String Manager
The Tools menu also offers a String Manager function. This page allows you to edit
footers, headers and other universal information displayed in emails, error messages and
elsewhere.
8.7.2. Deleting Users
Because of the isolated environment in which RHN Satellite Servers operate, Satellite customers have been granted the ability to delete users. To access this functionality, click
Users in the top navigation bar of the RHN website. In the resulting User List, click the
name of the user to be removed. This takes you to the User Details page. Click the delete
user link at the top-right corner of the page.
Figure 8-2. User Deletion
Page 73
Chapter 8. Maintenance 69
A confirmation page appears explaining that this removal is permanent. To continue, click
Delete User at the bottom-right corner of the page.
Note
The Organization Administrator role must be removed from the user’s profile before deleting the user from the RHN Satellite Server. Failing to do so causes the delete operation
to fail.
The Organization Administrator role may be removed by any Organization Administrator
(provided they are not the sole Organization Administrator for the organization) by clicking
on the Users tab and then visiting the Details sub-tab.
Figure 8-3. User Delete Confirmation
Many other options exist for managing users. You can find instructions for them in the
RHN website chapter of the RHN Reference Guide.
Page 74
70 Chapter 8. Maintenance
8.8. Automating Synchronization
Manually synchronizing the RHN Satellite Server repository with Red Hat Network can be
a time-intensive task. United States business hours tend to be the peak usage time for Red
Hat Network, so synchronization at that time may be slow. For these reasons, Red Hat encourages you to automate synchronization at other times to better balance load and ensure
quick synchronization. Continental United States business hours are roughly 8:00 AM to
9:00 PM EST (UTC -5), due to four time zones, Monday through Friday. These hours may
vary seasonally by one hour. Further, Red Hat strongly recommends that synchronization
occur randomly for best performance.
This automation can be set easily by the addition of a simple cron job. To do this, edit the
crontab as root:
crontab -e
This opens the crontab in a text editor, by default Vi. Another editor can be used by first
changing the EDITOR variable, like so: export EDITOR=gedit.
Once opened, use the first five fields (minute, hour, day, month, and weekday) to schedule the synchronization. Remember, hours use military time. Edit the crontab to include
random synchronization, like so:
0 1 * * * perl -le ’sleep rand 9000’ && satellite-sync --email >/dev/null \
2>/dev/null
This particular job will run randomly between 1:00 a.m. and 3:30 a.m. system time each
night and redirect stdout and stderr from cron to prevent duplicating the more easily
read message from satellite-sync. Options other than --email can also be included.
Refer to Table 6-2 for the full list of options. Once you exit from the editor, the modified
crontab is installed immediately.
8.9. Implementing PAM Authentication
As security measures become increasingly complex, administrators must be given tools
that simplify their management. For this reason, RHN Satellite Server supports networkbased authentication systems via Pluggable Authentication Modules (PAM). PAM is a suite
of libraries that helps system administrators integrate the Satellite with a centralized authentication mechanism, thus eliminating the need for remembering multiple passwords.
RHN Satellite Server supports LDAP, Kerberos, and other network-based authentication
systems via PAM. To enable the Satellite to use PAM and your organization’s authentication infrastructure, complete the following tasks.
Set up a PAM service file (usually /etc/pam.d/rhn-satellite) and have the Satellite
use it by adding the following line to /etc/rhn/rhn.conf:
pam_auth_service = rhn-satellite
Page 75
Chapter 8. Maintenance 71
This assumes the PAM service file is named rhn-satellite.
To enable a user to authenticate against PAM, select the checkbox labeled Pluggable Au-
thentication Modules (PAM). It is positioned below the password and password confirmation fields on the Create User page.
As an example, to authenticate against Kerberos one could put the following in
/etc/pam.d/rhn-satellite:
#%PAM-1.0
auth required /lib/security/pam_env.so
auth sufficient /lib/security/pam_krb5.so no_user_check
auth required /lib/security/pam_deny.so
account required /lib/security/pam_krb5.so no_user_check
Please note that changing the password on the RHN website changes only the local password on the RHN Satellite Server, which may not be used at all if PAM is enabled for that
user. In the above example, for instance, the Kerberos password will not be changed.
8.10. Enabling Push to Clients
In addition to allowing client systems to regularly poll the Satellite for scheduled actions,
you may enable the Satellite to immediately initiate those tasks on Provisioning-entitled
systems. This bypasses the typical delay between scheduling an action and the client system checking in with RHN to retrieve it.
Important
SSL must be employed between the Satellite and its clients systems for this feature to
work. If the SSL certificates are not available, the daemon on the client system fails to
connect.
To take advantage of this feature, you must first configure your firewall rules to allow
connections on the required port(s), as described in Section 2.4 Additional Requirements.
Then you must install the osa-dispatcher package, which can be found in the RHN
Satellite Server software channel for the Satellite within the central RHN website. Once
installed, start the service on the Satellite as root using the command:
service osa-dispatcher start
Finally, install the osad package on all client systems to receive pushed actions. The package can be found within the RHN Tools child channel for the systems on the RHN Satellite
Server. Once installed, start the service on the client systems as root using the command:
Page 76
72 Chapter 8. Maintenance
service osad start
Like other services, osa-dispatcher and osad accept stop, restart, and status
commands, as well.
Keep in mind, this feature depends on the client system recognizing the fully qualified
domain name (FQDN) of the Satellite. This name and not the IP address of the server
must be used when configuring the Red Hat Update Agent. Refer to the RHN Client
Configuration Guide for details.
Now when you schedule actions from the Satellite on any of the push-enabled systems, the
task will begin immediately rather than wait for the system to check in.
Page 77
Appendix A.
Sample RHN Satellite Server Configuration
File
The /etc/rhn/rhn.conf configuration file for the RHN Satellite Server provides a
means for you to establish key settings. Be warned, however, that errors inserted into this
file may cause Satellite failures. So make configuration changes with caution.
You should be particularly concerned with the following parameters: traceback_mail, default_db, and server.satellite.http_proxy. Review the sample and its comments, beginning
with a hash mark (#), for additional details.
#/etc/rhn/rhn.conf example for an RHN Satellite
#----------------------------------------------
# Destination of all tracebacks, such as crash information, etc.
traceback_mail = test@pobox.com, test@redhat.com
# Location of RPMs (Red Hat and custom) served by the RHN Satellite
mount_point = /var/satellite
# Corporate gateway (hostname:PORT):
server.satellite.http_proxy = corporate_gateway.example.com:8080
server.satellite.http_proxy_username =
server.satellite.http_proxy_password =
# Database connection information username/password@SID
default_db = test01/test01@test01
### DON’T TOUCH ANY OF THE FOLLOWING ###
web.satellite = 1
web.session_swap_secret_1 = ea6c79f71cfcf307d567fed583c393b9
web.session_swap_secret_2 = 01dee83a7b7f27157f5335744eb02327
web.session_swap_secret_3 = 4e89e7697ce663149ca9e498cbc08b4f
web.session_swap_secret_4 = a0fed2d77a950fc9a800b450a45e89d2
web.session_secret_1 = 24bc562e04c9b93f5be94f793738e104
web.session_secret_2 = 7667a7c2db311b1ea04271ecc1b82314
web.session_secret_3 = 442e7dc4f06f63eba9a0408d499c6a8d
web.session_secret_4 = 587a0db47856f685d989095629a9bd6f
encrypted_passwords = 1
web.param_cleansers = RHN::Cleansers->cleanse
Page 78
74 Appendix A. Sample RHN Satellite Server Configuration File
web.base_acls = RHN::Access
web.default_taskmaster_tasks = RHN::Task::SessionCleanup,
RHN::Task::ErrataQueue,
RHN::Task::ErrataEngine,
RHN::Task::DailySummary,
RHN::Task::SummaryPopulation,
RHN::Task::RHNProc,
RHN::Task::PackageCleanup
web.rhn_gpg_backend_module = RHN::GPG::OpenPGP
web.restrict_mail_domains =
Page 79
Index
Symbols
/etc/nsswitch.conf, 55
/etc/rhn/rhn.conf, 55
A
Administrator Email Address, 24
advantages, 2
Apache, 59
Apache HTTP, 3
automating Satellite synchronization, 70
B
backing up the RHN Satellite Server, 60
Bootstrap Script, 33
location on Satellite
/var/www/html/pub/bootstrap/, 33
C
channel
definition, 2
channel content
import process, 49
channel package
default location
/var/satellite/, 21
chkconfig, 16
cloning satellite, 64
connection errors, 56
D
Database Configuration, 25
Database Population, 27
database RPMs
default location
/opt/, 21
Database Schema, 26
db-control
options, 61
db-control use, 61
disable services
ntsysv
chkconfig, 16
disconnected mode, 29
E
embedded database
default location
/rhnsat/, 21
enabling push to clients, 71
entitlement certificate, 15, 22
F
firewall rules, 14
G
general problems, 54
GPG keys, 23
H
host not found error
could not determine FQDN, 55
how it works, 3
HTTP proxy, 27
httpd, 16
Page 80
76
I
implementing PAM authentication, 70
import
channel content
process, 49
importing
satellite data, 43
importing data
placing Errata in repository, 51
populating the channel, 50
running the import, 50
installation
base, 21
MySQL, 38
of RHN Satellite Server, 21
sendmail, 37
Installation Complete, 34
installation task list, 5
L
log files, 53
table, 53
M
maintenance, 59
Monitoring Configuration, 28
mysql-server, 38
N
Network Time Protocol, 15
ntsysv, 16
O
Oracle 9i R2, 3
Organization Administrator, 36
definition, 2
osa-dispatcher, 71
osad, 71
P
port 443, 14
port 5222, 16
port 5269, 16
port 80, 14
R
Red Hat Network
introduction, 1
Red Hat Update Agent
definition, 2
redundant satellite, 64
requirements, 9
additional, 14
database, 13
hardware, 11
software, 9
software - Enterprise Linux 3, 10
software - Enterprise Linux 4, 9
RHN
components, 3
RHN Configuration , 27
RHN DB Control
backup, 62
options, 61
restore, 63
verify, 63
RHN Entitlement Certificate
options, 41
RHN Entitlement Certificates, 39
receiving, 39
RHN Password, 29
RHN Registration, 29
RHN Satellite Activate, 41
RHN Satellite Entitlement Certificate, 30
RHN Satellite Server entitlement, 22
RHN Satellite Synchronization Tool, 29, 45
options, 47
RHN SSL Maintenance Tool, 32
RHN Task Engine, 67, 68
RHN Username, 29
rhn-satellite
Page 81
77
service, 59
rhn-satellite-activate, 41
activating, 41
options, 41
rhn.conf
sample file, 73
rhns-satellite-tools, 41, 50
rogerthat01@{mail domain}, 37
S
Satellite Administrator, 36
satellite redundancy, 64
Satellite Restart, 35
Satellite Synchronization, 31
satellite-debug, 57
satellite-sync, 50, 52
--step=channel-families, 50
--step=channels, 50
--step=rpms, 50
cron job, 70
sendmail, 16, 28
Software Channel Administrator
definition, 2
SSL Certificate, 32
SSL public certificate
location on Satellite
/var/www/html/pub/, 33
summary of steps, 5
synchronizing
keeping channel data in sync, 51
satellite data, 43
T
terms to understand, 2
tool use, 66
topologies, 17
multiple satellites horizontally tiered, 18
satellite and proxies vertically tiered, 19
single satellite, 17
traceback, 3
definition, 2
troubleshooting, 53
/etc/hosts, 54
Embedded Database, 54
full disk space, 54
SSL_CONNECT errors, 56
traceback email address, 55
U
updating the RHN Satellite Server, 59
Page 82
Loading...