RHN Satellite Server 3.6
Installation Guide
RHN Satellite Server 3.6: Installation Guide
Copyright © 2001 - 2004 by Red Hat, Inc.
RHNsatellite(EN)-3.6-RHI (2004-12-07T20:06)
Copyright © 2001 - 2004 by Red Hat, Inc.
Red Hat, Red Hat Network, the Red Hat "ShadowMan" logo, RPM, Maximum RPM, the RPM logo, Linux Library,
PowerTools, Linux Undercover, RHmember, RHmember More, Rough Cuts, Rawhide and all Red Hat-basedtrademarks and
logos are trademarks or registered trademarks of Red Hat, Inc. in the United States and other countries.
Linux is a registered trademark of Linus Torvalds.
All other trademarks and copyrights referred to are the property of their respectiveowners.
Table of Contents
1. Introduction.....................................................................................................................................1
1.1. Red Hat Network ............................................................................................................... 1
1.2. RHN Satellite Server.......................................................................................................... 1
1.3. Terms to Understand .......................................................................................................... 2
1.4. How it Works ..................................................................................................................... 2
1.5. Summary of Steps..............................................................................................................4
2. Requirements................................................................................................................................... 7
2.1. Software Requirements...................................................................................................... 7
2.2. Hardware Requirements.....................................................................................................8
2.3. Database Requirements...................................................................................................... 9
2.4. Additional Requirements ................................................................................................. 10
3. Example Topologies ......................................................................................................................13
3.1. Single Satellite Topology................................................................................................. 13
3.2. Multiple Satellite Horizontally Tiered Topology............................................................. 13
3.3. Satellite-Proxy Vertically Tiered Topology .....................................................................14
4. Installation..................................................................................................................................... 15
4.1. Base Install.......................................................................................................................15
4.2. RHN Satellite Server Installation Program .................................................................15
4.3. Sendmail Configuration ...................................................................................................26
5. Entitlements...................................................................................................................................29
5.1. Receiving the Certificate..................................................................................................29
5.2. Uploading the RHN Entitlement Certificate ....................................................................29
5.3. Managing the RHN Certificate with RHN Satellite Activate ........................................ 30
5.3.1. Command Line Entitlement Options ................................................................ 30
5.3.2. Activating the Satellite...................................................................................... 30
6. Importing and Synchronizing...................................................................................................... 33
6.1. RHN Satellite Synchronization Tool ............................................................................ 33
6.1.1. Import/Sync Steps .............................................................................................33
6.1.2. Import/Sync Options ......................................................................................... 33
6.1.3. Import/Sync Cache Refresh .............................................................................. 35
6.2. Importing..........................................................................................................................35
6.2.1. Prerequisites. ..................................................................................................... 36
6.2.2. Preparing for Import .........................................................................................36
6.2.3. Running the Import ........................................................................................... 37
6.3. Synchronizing ..................................................................................................................38
6.3.1. Synchronizing Errata and Packages Directly via RHN ....................................38
6.3.2. Synchronizing Errata and Packages via Local Media.......................................39
7. Troubleshooting............................................................................................................................. 41
7.1. Log Files .......................................................................................................................... 41
7.2. General Problems............................................................................................................. 41
7.3. Host Not Found/Could Not Determine FQDN ................................................................ 42
7.4. Connection Errors ............................................................................................................43
7.5. Caching Issues ................................................................................................................. 44
7.6. Satellite Debugging by Red Hat ......................................................................................44
8. Maintenance ..................................................................................................................................45
8.1. Managing the Satellite Service ........................................................................................45
8.2. Updating the Satellite. ...................................................................................................... 45
8.3. Backing Up the Satellite ..................................................................................................46
8.4. Using RHN DB Control .................................................................................................46
8.4.1. DB Control Options ..........................................................................................46
8.4.2. Backing up the Database................................................................................... 47
8.4.3. Verifying the Backup ........................................................................................48
8.4.4. Restoring the Database .....................................................................................48
8.5. Cloning the Satellite with Embedded DB ........................................................................ 48
8.6. Establishing Redundant Satellites with Stand-Alone DB................................................ 49
8.7. Conducting Satellite-Specific Tasks ................................................................................50
8.7.1. Using the Tools menu ....................................................................................... 50
8.7.2. Deleting Users...................................................................................................51
8.8. Automating Synchronization ...........................................................................................52
8.9. Implementing PAM Authentication. ................................................................................53
8.10. Enabling Push to Clients ................................................................................................54
A. Sample RHN Satellite Server Configuration File...................................................................... 55
Index...................................................................................................................................................57
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 exibility 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, but may also crop up during troubleshooting. This guide identifies distinctions between the
Satellite types by marking the differing instructions as either Embedded Database or Stand-Alone
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 maintain hun-
dreds or thousands of Red Hat systems more easily, accurately, and quickly than that same administrator 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.
• Scheduled Actions — use the website to schedule actions, including Errata Updates, package in-
stalls, 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. 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:
2 Chapter 1. Introduction
• 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 pack-
ages required by client systems, as well as official Red Hat packages. Custom channels allow finegrained 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 combination
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 a specific architecture
and Red Hat release. A child channel is a channel associated with a base channel but 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.
• Channel Administrator — A Channel Administrator is a user role with full access to channel man-
agement 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 trou-
bleshooting 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:
Chapter 1. Introduction 3
• Database — for the Stand-Alone Database, this may be the organization’s existing database or,
preferably, a separate machine. RHN Satellite Server 3.6 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 XMLRPC requests).
• RHN Satellite Server Web interface — advanced system, system group, user, and channel manage-
ment interface.
• RPM Repository — package repository for official Red Hat RPM packages and custom RPM pack-
ages identified by the organization.
• Management Tools:
• Database and filesystem synchronization tools
• 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.
Important
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
4 Chapter 1. Introduction
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.
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.
3. Your Red Hat contact creates a Satellite-entitled account on the RHN website and sends you the
login information.
4. You log into the RHN website (rhn.redhat.com) and download the distribution ISOs for Red
Hat Enterprise Linux AS and RHN Satellite Server 3.6. Remember, Monitoring requires Red
Hat Enterprise Linux AS 3. 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, you download the Channel Content ISOs to be served
by your Satellite, also available through the Downloads tab of your Satellite’s Channel Details
Chapter 1. Introduction 5
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, you prepare your database instance using the formula
provided in Chapter 2 Requirements.
7. You install Red Hat Enterprise Linux AS and then RHN Satellite Server 3.6 on the Satellite
machine.
8. You 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 account.
9. You use the RHN Satellite Synchronization Tool to import the channels and associated packages into the Satellite.
10. You register a representative machine for each distribution type, or channel (Red Hat Enterprise
Linux AS 2.1, 3), to the Satellite.
11. You copy (using SCP) the rhn_register and up2date configuration files from the
/etc/sysconfig/rhn/ directory of each machine individually to the /pub directory on the
Satellite. The rhn-org-trusted-ssl-cert-*.noarch.rpm will already be there.
12. You 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, you 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. You then 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. You should 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 and packages. Once the
custom RPMs are developed, you can import them into the Satellite using the RHN Push and
add custom channels to store them through the Satellite’s website. Refer to the RHN Channel
Management Guide for details.
6 Chapter 1. Introduction
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 2.1
Update 5 or later and Red Hat Enterprise Linux AS 3 Update 3 or later 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.
Important
If you plan to obtain Monitoring-level service, you must install your RHN Satellite Server on Red
Hat Enterprise Linux AS3 Update 3. This is the only supported base operating system for Satellites
serving Monitoring-entitled systems.
Each version of Red Hat Enterprise Linux AS requires additional packages to support RHN Satellite
Server. Although these requirements may be met by conducting an Everything install, Red Hat
this installs packages that if not properly managed could pose security hazards. For this reason, Red
Hat recommends obtaining the desired package set in the following ways:
For kickstarting Red Hat Enterprise Linux AS 3 Update 3, specify the following packages and
groups:
• @ Base
• @ Server
• @ Development Tools
• @ Legacy Software Development
• perl-CGI
• perl-Time-HiRes
For installing Red Hat Enterprise Linux AS 3 Update 3 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
Once updated, delete the Red Hat Enterprise Linux AS 3 Update 3 system profile from RHN, as it
will be reregistered during Satellite installation.
For kickstarting Red Hat Enterprise Linux AS 2.1 Update 5, specify the following package groups:
8 Chapter 2. Requirements
• @ Advanced Server
• @ Base
• @ Messaging and Web Tools
• @ Software Development
• @ Utilities
• @ Web Server
For installing Red Hat Enterprise Linux AS 2.1 Update 5 via CD or ISO image, select the following
package groups:
• Network Support
• Web Server
• Software Development
• Advanced Server
• Messaging and Web Tools
• Utilities
This satisfies the base operating system requirements. Unlike Red Hat Enterprise Linux AS 3 Update 3, you do not have to run up2date to install additional packages.
• 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 isn’t possible, such
as in a disconnected environment.
2.2. Hardware Requirements
The following hardware configuration is required for the two types of RHN Satellite Server:
Stand-Alone Database Embedded Database
Dell PowerEdge 1750 or equivalent Dell PowerEdge 2650 or equivalent
Two processors Two 2.4 GHz processors
Required - 512 MB of memory Required - 2 GB of memory
Recommended - 1 GB of memory Strongly recommended - 4 GB of memory
3 GB storage for base install of Red Hat
Enterprise Linux AS
5 GB storage per channel, in the
/var/satellite directory by default but
configurable at install
Recommended - an external SAN for more
reliable backups
3 GB storage for base install of Red Hat
Enterprise Linux AS
5 GB storage per channel, in the
/var/satellite directory by default but
configurable at install
Recommended - an external SAN for more
reliable backups
36 GB storage for the database repository, in the
/rhnsat partition (local storage only)
Chapter 2. Requirements 9
Stand-Alone Database Embedded Database
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:
• Dell PowerEdge 2650 or equivalent
• 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 in which client systems connect to the Satellite is directly related to load
on the Apache HTTP Server and the database. If you do reduce the default interval of four hours (or
240 minutes), as set in the /etc/sysconfig/rhn/rhnsd configuration file of the client systems,
you will increase the load on those components significantly.
Additional hardware requirements include:
• The Stand-Alone Database must not run on the same server as the RHN Satellite Server.
• 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 3.6 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 4 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.
10 Chapter 2. Requirements
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 need to consider that size
does affect the time to conduct backups and adds load to other system resources. If the database is
being shared, its hardware and spacing is entirely dependent on what else is using it.
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 will need 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
Chapter 2. Requirements 11
The RHN Satellite Server solution can be firewalled from the Internet, but it must be able to issue
outbound connections to rhn.redhat.com and xmlrpc.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 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 will be connecting to the central Red Hat Network Servers to receive incremental
updates will need 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 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 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 will be
accessing, or be accessed via the Internet. An Internet connection is not required for RHN Satellite
Servers running in completely disconnected environments as this feature instead uses update CDs
to synchronize the Satellite with the central Red Hat Network. 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 admin-
istrators should have shell access to these machines.
• All unnecessary services should be disabled using ntsysv or chkconfig.
• The httpd service should be enabled.
12 Chapter 2. Requirements
• If the Satellite 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 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.
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.
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 horizontally tiered configuration and balancing the load of client requests.
Additional maintenance is the biggest disadvantage of this horizontal structure.
14 Chapter 3. Example Topologies
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
that connect to the Satellite for RPMs from Red Hat Network and custom packages created locally. In
essence, the Proxies act as clients of the Satelllite.
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 actual client systems. This process is described in the RHN Client Configuration Guide.
Figure 3-3. Satellite-Proxy Vertically Tiered Topology
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.
Important
If you plan to obtain Monitoring-level service, you must install your RHN Satellite Server on Red
Hat Enterprise Linux AS 3. This is the only supported base operating system for Satellites serving
Monitoring-entitled systems. Do not install Satellite on Red Hat Enterprise Linux AS 2.1.
• 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.
• Disable the ipchains and iptables services after installation.
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:
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 download, 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.
16 Chapter 4. Installation
5. Ensure 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.
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.
Chapter 4. Installation 17
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 will receive all mail generated by the Satellite, including
sometimes 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 Configuration page appears for RHN Satellite Server with
Stand-Alone Database, while the Database Schema page appears for RHN Satellite Server
with Embedded Database.
Figure 4-3. Database Configuration
18 Chapter 4. Installation
9. The Database Configuration page collects information required for the Satellite with StandAlone Database to connect to its database. If this is Satelllite with Embedded Database, skip
to the Database Schema page description. For Satellite with Stand-Alone Database, consult
your database administrator for the appropriate values. Then click Test DB Connection. The
Database Schema page appears.
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 progress.
Figure 4-5. Database Population
11. The Database Population page displays a link when population is complete. Click Configuration to continue. The RHN Configuration page appears.
Chapter 4. Installation 19
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, its parent RHN server (to connect
to another Satellite, for instance) and the location, or mountpoint 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 server. 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 form hostname:port, such as my.corporate.gateway.example.com:3128.When
finished, click Continue. The Monitoring Configuration page appears.
20 Chapter 4. Installation
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.
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.
Chapter 4. Installation 21
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 Satellite 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.
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’s 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.
22 Chapter 4. Installation
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.
Chapter 4. Installation 23
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 information 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.
24 Chapter 4. Installation
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 from the central RHN
Servers. The required fields are prepopulated 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.
Chapter 4. Installation 25
Figure 4-13. Installation Complete
19. The Installation Complete page marks the end of the initial Satellite installation and configuration. Click Complete to reboot the system and create the Satellite Administrator account. The
Satellite Restart page appears.
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 Adminis-
trator page.
26 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.
Figure 4-16. Account Created
22. The Account Created page signals the end of the installation and configuration process. 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.
Chapter 4. Installation 27
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.
To configure sendmail correcly, edit the /etc/aliases file on the mail server as root and add the
following line:
rogerthat01: "| /opt/notification/scripts/ack_enqueuer.pl"
Then, also as root, edit the /etc/mail/sendmail.mc file, and change:
"FEATURE(‘smrsh’,‘/usr/sbin/smrsh’)dnl"
to:
"FEATURE(‘smrsh’,‘/bin/sh’)dnl"
and:
"DAEMON_OPTIONS(‘Port=smtp,Addr=127.0.0.1, Name=MTA’)dnl"
to:
"DAEMON_OPTIONS(‘Port=smtp, Name=MTA’)dnl"
Then, run these commands:
up2date sendmail-cf
Note, disconnected installs will need to add this package from the ISO.
m4 /etc/mail/sendmail.mc > /etc/mail/sendmail.cf
service sendmail restart
28 Chapter 4. Installation
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"Chip’s Emporium/rhn-cert-field
rhn-cert-field name="issued"Fri Apr 19 04:52:10 2002/rhn-cert-field
rhn-cert-field name="expires"Never/rhn-cert-field
rhn-cert-field name="slots"500/rhn-cert-field
rhn-cert-signature-----BEGIN PGP SIGNATURE----Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org
iD8DBQA8v9q6v7p5EWH7xWQRAkidAKCRQbrXOqeAUb 5F+MOHnFJ7Hj/7zwCgqSLM
mY3hNyF1PZ8aNBSGl3DMqos=
=1sCJ
-----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 an install. 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.
30 Chapter 5. Entitlements
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.
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.
Chapter 5. Entitlements 31
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).
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.
32 Chapter 5. Entitlements
Chapter 6.
Importing and Synchronizing
After installing the RHN Satellite Server, you must provide it the packages and channels to be served.
This chapter explains how to import that data and keep it up-to-date.
6.1. RHN Satellite Synchronization Tool
With the Satellite installation, Red Hat Network provides an application designed specifically to import and synchronize data - the RHN Satellite Synchronization Tool. This tool, which comes with the
rhns-satellite-tools package, enables an RHN Satellite Server to update its database metadata
and RPM packages with that of Red Hat. To launch it, as root execute the command:
satellite-sync
The tool can be used in a closed environment, such as the one created with a disconnected install,
or it may obtain data directly over the Internet. For disconnected importing and synchronization,
local media in the form of Red Hat Network Channel Content CDs are required. After installing and
mounting the discs, the sole difference in use will be the addition of the --mount-point option and
path to the files appended to every command. This will be covered in more detail in a moment.
6.1.1. Import/Sync Steps
The RHN Satellite Synchronization Tool works incrementally, or in steps. For it to obtain 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.
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, like so:
satellite-sync --step=rpms
6.1.2. Import/Sync Options
In addition to --step the RHN Satellite Synchronization Tool offers many other command line
options. To use them, insert the option and the appropriate value after the satellite-synccommand
when launching import/synchronization.
34 Chapter 6. Importing and Synchronizing
Option Description
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.
--no-kickstarts Do not process kickstart data (provisioning only).
--force-all-packages Forcibly process all package data without conducting
a diff.
--cache-refresh-level=LEVEL_NUMBERThe level of caching refresh for the Satellite, 0-6.
Refer to Section 6.1.3 Import/Sync Cache Refresh for
a complete description.
--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=HTTP_PROXY_USERNAMEInclude the username for the alternative HTTP proxy
server.
--http-proxy-password=HTTP_PROXY_PASSWORDInclude the password for the alternative HTTP proxy
server.
Chapter 6. Importing and Synchronizing 35
Option Description
--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-1. Satellite Import/Sync Options
If no options are included, satellite-sync will synchronize all channels that already exist in the
Satellite’s database. By default, the --cache-refresh-level=2 and --step (all steps) options are
enabled.
Keep in mind, when using the --channel option, you must specify 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 of these channels are available for importing and
synchronizing.
6.1.3. Import/Sync Cache Refresh
The RHN Satellite Synchronization Tool caches metadata used for the synchronization process.
This cache, which exists by default in /var/cache/rhn/, can be completely refreshed every time
the process is run, be partially refreshed, or be left in place entirely. The closer to a full refresh, the
slower the synchronization process.
The default setting is a cache refresh level of 2. This can be adjusted using the
--cache-refresh-level option. In the event that satellite-sync is called many times in a
short period of time, level 0 may be more appropriate. Here are the levels:
• 0 — Do not refresh unless something differs.
• 1 — Delete staging area so all short (indexing) package data is downloaded every time.
• 2 — Default behavior - Obtain short (indexing) package data and long package data.
• 3 — Always replace Errata information.
• 4 — Remove all caches upon sync completion.
• 5 — Remove all caches upon sync initialization.
• 6 — Remove all caches upon sync completion and initialization.
Increasing the cache level is useful in troubleshooting. If users suspect the cache is out of sync or
corrupt, they may increase the level incrementally in order to completely remove it and start anew.
Refer to Section 7.5 Caching Issues for manual clearing instructions.
6.2. Importing
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.
36 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 director y structures 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.
6.2.1. Prerequisites
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 CDs must be available, or the Satellite must have access
to the Internet and the RHN website.
6.2.2. Preparing for Import
Although it is possible to conduct the import directly from the RHN website, this should be done only
if Channel Content CDs (or 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 CDs, if they are available, for
initial import.
Channel Content CDs are special collections that contain both packages and XML dumps of metadata.
If the Channel Content CDs don’t accompany the Satellite Installation CD, the ISO images can be
downloaded from the RHN website. 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, designated as "channel" ISOs.
If the desired Channel Content ISOs don’t appear, ensure your RHN Entitlement Certificate has been
uploaded to RHN and correctly identifies the target channels.
Channel content, whether it comes in the form of physical discs or downloadable ISOs, is mounted and
then copied to a temporary repository directory. Before mounting the CDs/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 CDs/ISOs is to mount each one,
copy its contents to the temporary repository, and then unmount the CD/ISO. Repeat. Each channel
consists of several CDs/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 CD or 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. If you are installing from official CD and it is not mounted automatically, mount it using the
command:
mount /dev/cdrom /mnt/import
If you are installing from ISO, mount the 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/
Chapter 6. Importing and Synchronizing 37
6. This sample command assumes the administrator wants to copy the contents of the CD/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 Content CD or ISO of every channel to be imported.
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.
Note
The trailing backslash (\) in all subsequent command examples is a continuation character; it may
safely be omitted. Long versions of all options are used in the examples for clarity. You may use short
versions where available.
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
Note
Importing package data can take up to two hours per channel. But 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-1 --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.
38 Chapter 6. Importing and Synchronizing
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.
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. Identifing 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 performs 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 explanation.
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.
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.
Chapter 6. Importing and Synchronizing 39
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 freshened.
6.3.2. Synchronizing Errata and Packages via Local Media
For customers who cannot connect directly to RHN, the option of delivered, periodic updates of RHN
data is available. This data is delivered in CD or DVD. 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.
40 Chapter 6. Importing and Synchronizing
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 Satellite-entitled 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.6 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 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
Red Hat Update Agent /var/log/up2date
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 tail 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
42 Chapter 7. Troubleshooting
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 com-
mand:
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:
rhn-schema-version
To derive the character set types of your Satellite’s database, run the command:
rhn-charsets
If the administrator isn’t 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 suggested this temporary directory be
/var/rhn-sat-import/.
Then restart the importation or synchronization.
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.
Chapter 7. Troubleshooting 43
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 re-
solved. 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.
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.com 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/time on 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.
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.
44 Chapter 7. Troubleshooting
• Confirm the correct 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 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. In most cases, each RHN Proxy Server should have both the RHN Satellite Server’s
certificate and the client certificate installed, since it will serve in both capacities.
• Make sure client systems are not using firewalls of their own blocking required ports, as identified
in Section 2.4 Additional Requirements.
7.5. Caching Issues
If importing or synchronizing fails, and it isn’t related to connection errors, you should consider
clearing the cache. By default, the cache is located in /var/cache/rhn/. To clear it manually, issue
the command:
rm -fv /var/cache/rhn/*
In addition, you may set the cache refresh level for all importing and synchronizing using the
--cache-refresh-level option of satellite-sync. Setting this to its highest level removes
the cache entirely upon initialization and closure. Refer to Section 6.1.3 Import/Sync Cache Refresh
for information on the available levels.
7.6. 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 Gath-
erer, commonly known by its command satellite-debug. To use this tool, simply issue that com-
mand 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 charactersets
* get diskspace available
* timestamping
* 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.
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 will also require
maintenance. This chapter discusses the procedures that should be followed to carry out administrative
functions outside of standard use, as well as 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 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 Errata
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.
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.
46 Chapter 8. Maintenance
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.
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 and issue the
command:
su - oracle
db-control option
Chapter 8. Maintenance 47
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
backup DIRNAME Backs up the database to the directory specified.
examine DIRNAME Examines the contents of a backup directory. Returns
report Reports on current usage of database space.
restore DIRNAME Restores the database from backup kept in
start Starts the database instance. This can also be
status Shows the current status of the database, either
stop Stops the database instance. This can also be
verify DIRNAME Verifies the contents of the backup kept in
Table 8-1. RHN DB Control Options
details.
the timestamp of backup creation and reports on its
contents.
DIRNAME. Database must be stopped for this
command to run successfully.
accomplished by issuing the service
rhn-database start command as root.
"running" or "offline".
accomplished by issuing the service
rhn-database stop command as root.
DIRNAME. This command checks the md5sums of
each of the files kept in the backup.
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 either 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:
db-control backup DIRNAME
Backup files will be 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
will be a good indicator of how long subsequent backups will take.
48 Chapter 8. Maintenance
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:
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
Chapter 8. Maintenance 49
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 entirety. The secondary Satellite machine can be prepared for use if the primary fails. To
clone the Satellite, conduct 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 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 high-availability 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 setup and blow away tablespace
steps and the SSL certificate and bootstrap script generation steps. You should still 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 Configuration Guide for
precise instructions. Remember, the Common Name value must represent the combined Satellite solution, not a single machine’s hostname.
50 Chapter 8. Maintenance
If you generated a new SSL certificate during secondary Satellite installation to include a new
Common Name value, instead copy the 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 command:
/sbin/service taskomatic stop
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 reverseproxy 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 Channel 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.
Chapter 8. Maintenance 51
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
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.
52 Chapter 8. Maintenance
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
A confirmation page will appear explaining that this removal is permanent. To continue, click Delete
User at the bottom-right corner of the page.
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.
Chapter 8. Maintenance 53
8.8. Automating Synchronization
Manually synchronizing the RHN Satellite Server repository with Red Hat Network can be an arduous task. In addition, staff levels tend to be highest at peak usage times. For this reason, Red Hat
encourages you to automate synchronization in late evening or early morning to better balance load
and ensure quick synchronization. Further, Red Hat strongly recommends synchronization occur ran-
domly 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 Section 6.1.2 Im-
port/Sync Options 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 network-based 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
This assumes the PAM service file is named rhn-satellite.
Enable a certain user to authenticate against PAM. Do this by clicking the Use PAM Authentication
button on the User Details 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
54 Chapter 8. Maintenance
Please note that changing the password on the RHN website will change 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:
service osad start
Like other services, osa-dispatcher and osad accept stop, restart, and status commands, as
well.
Now when you schedule actions from the Satellite on any of the push-enabled systems, the task will
began immediately rather than wait for the system to check in.
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
web.base_acls = RHN::Access
web.default_taskmaster_tasks = RHN::Task::SessionCleanup,
web.rhn_gpg_backend_module = RHN::GPG::OpenPGP
web.restrict_mail_domains =
RHN::Task::ErrataQueue, RHN::Task::ErrataEngine,
RHN::Task::DailySummary, RHN::Task::SummaryPopulation,
RHN::Task::RHNProc, RHN::Task::PackageCleanup
56 Appendix A. Sample RHN Satellite Server Configuration File
Index
A
advantages, 1
automating Satellite synchronization, 53
L
log files, 41
M
maintenance, 45
B
backing up the RHN Satellite Server, 46
C
caching issues, 44
cloning satellite, 49
components, 2
connection errors, 43
D
db-control use, 46
E
enabling push to clients, 54
G
general problems, 41
H
host now found error
could not determine FQDN, 42
how it works, 2
I
implementing PAM authentication, 53
importing and synchronizing data, 33
importing data, 35
placing Errata in repository, 38
populating the channel, 38
preparing for, 36
prerequisites, 36
running the import, 37
installation
base, 15
of RHN Satellite Server, 15
sendmail, 27
installation task list, 4
R
Red Hat Network
introduction, 1
redundant satellite
satellite redundancy, 49
requirements, 7
additional, 10
database, 9
hardware, 8
software, 7
RHN DB Control
backup, 47
options, 47
restore, 48
verify, 48
RHN Entitlement Certificates, 29
receiving, 29
RHN Satellite Synchronization Tool, 33
RHN Task Engine, 51, 51
rhn-satellite
service, 45
rhn-satellite-activate
activating, 31
options, 30
rhn.conf
sample file, 55
rhns-satellite-tools, 37
S
satellite-debug, 44
satellite-sync, 37, 39
--step=channel-families, 37
--step=channels, 37
--step=rpms, 38
Satelllite Sync Tool
cache refresh, 35
options, 33
steps, 33
summary of steps, 4
synchronizing
keeping channel data is sync, 38
58
T
terms to understand, 2
tool use, 50
topologies, 13
multiple satellites horizontally tiered, 13
satellite and proxies vertically tiered, 14
single satellite, 13
traceback, 2
troubleshooting, 41
U
updating the RHN Satellite Server, 45
Loading...