Red Hat NETWORK PROXY SERVER 4.0 - User manual

RHN Proxy Server 4.0
Installation Guide

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

Table of Contents
1. Introduction....................................................................................................................1
1.1. Red Hat Network ..............................................................................................1
1.2. RHN Proxy Server ............................................................................................1
1.3. Terms to Understand .........................................................................................2
1.4. How it Works ....................................................................................................3
2. Requirements..................................................................................................................7
2.1. Software Requirements .....................................................................................7
2.2. Hardware Requirements....................................................................................8
2.3. Disk Space Requirements .................................................................................8
2.4. Additional Requirements ..................................................................................9
3. Example Topologies .....................................................................................................11
3.1. Single Proxy Topology ...................................................................................11
3.2. Multiple Proxy Horizontally Tiered Topology ...............................................12
3.3. Multiple Proxy Vertically Tiered Topology ....................................................12
3.4. Proxies with RHN Satellite Server .................................................................13
4. Installation ....................................................................................................................15
4.1. Base Install......................................................................................................15
4.2. RHN Proxy Server Installation Process ..........................................................15
5. RHN Package Manager ...............................................................................................27
5.1. Creating a Private Channel .............................................................................27
5.2. Uploading Packages ........................................................................................27
5.3. Command Line Options ..................................................................................29
6. Troubleshooting............................................................................................................31
6.1. Managing the Proxy Service ...........................................................................31
6.2. Log Files .........................................................................................................31
6.3. Questions and Answers...................................................................................32
6.4. General Problems............................................................................................33
6.5. Host Not Found/Could Not Determine FQDN ...............................................33
6.6. Connection Errors ...........................................................................................34
6.7. Caching Issues ................................................................................................34
6.8. Proxy Debugging by Red Hat .........................................................................35
A. Sample RHN Proxy Server Configuration File ........................................................37
Index.................................................................................................................................. 39

Chapter 1.
Introduction
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 per-
formance of their systems. To use RHN, system administrators register the software and
hardware profiles, known as System Profiles, of their client systems with Red Hat Network.
When a client system requests package updates, only the applicable packages for the client
are returned (based upon the software profile stored on the RHN Servers).
Advantages of using Red Hat Network include:
•Scalability — with Red Hat Network, a single system administrator can set up and main-
tain hundreds or thousands of Red Hat systems more easily, accurately, and quickly than
they could maintain a single system without Red Hat Network.
•Standard Protocols — standard protocols are used to maintain security and increase
capability. For example, XML-RPC gives Red Hat Network the ability to do much more
than merely download files.
•Security — all communication between registered systems and Red Hat Network takes
place over secure Internet connections.
•View Errata Alerts — easily view Errata Alerts for all your client systems through one
website.
•Scheduled Actions — use the website to schedule actions, including Errata Updates,
package installs, and software profile updates.
•Simplification — maintaining Red Hat systems becomes a simple, automated process.
1.2. RHN Proxy Server
An RHN Proxy Server is a service deployed within a corporate network with advanced Red
Hat Network functionality, such as a package-caching mechanism for reduced bandwidth
usage and customizable channels enabling custom package deployment.
This service allows a business or corporation to cache RPM Updates on an internal, cen-
trally located RHN Proxy Server and have the client systems download the updates from

2 Chapter 1. Introduction
that server instead of from one of the RHN Servers 1over the Internet. The clients’ System
Profiles and user information are stored on the secure, central RHN Servers, which also
serve the RHN website (rhn.redhat.com). The Proxy acts as a go-between for client sys-
tems and Red Hat Network (or an RHN Satellite Server). Only the package files are stored
on the RHN Proxy Server. Every transaction is authenticated, and the Red Hat Update
Agent checks the GPG signature of each package retrieved from the local RHN Proxy
Server.
In addition to storing official Red Hat packages, the RHN Proxy Server can be configured
to deliver an organization’s own custom packages from private RHN channels, using the
RHN Package Manager. For instance, an organization could develop its own software,
package it in an RPM, sign it with its own GPG signature, and have the local RHN Proxy
Server update all the individual systems in the network with the latest versions of the
custom software.
Advantages of using RHN Proxy Server include:
•Scalability — there can be multiple local RHN Proxy Servers within one organization.
•Security — an end-to-end secure connection is maintained: from the client systems, to
the local RHN Proxy Server, to the Red Hat Network servers.
•Saves time — packages are delivered significantly faster over a local area network than
the Internet.
•Saves bandwidth — packages are downloaded from the RHN File servers only once (per
local Proxy Server’s caching mechanism) instead of downloading each package to each
client system.
•Saves disk space on individual systems — one large disk array is required instead of
extra disk space on all the client systems.
•Customized updates — create a truly automated package delivery system for custom
software packages, as well as official Red Hat packages required for the client systems.
Custom private RHN channels allow an organization to automate delivery of in-house
packages.
•Customized configuration — restrict or grant updates to specific architectures and OS
versions.
•Only one Internet connection required — the client systems connect only through the
HTTP-enabled Proxy Server and therefore do not need a connection to the external net-
work (Internet), but only require access to the Local Area Network to which the RHN
Proxy Server is connected. Only the RHN Proxy Server needs an Internet connection to
contact the RHN Servers, unless the RHN Proxy Server is using a RHN Satellite Server,
in which case only the RHN Satellite Server requires an Internet connection.
1. Throughout this document, replace RHN Server with RHN Satellite Server if the RHN Proxy
Server connects to a RHN Satellite Server instead.

Chapter 1. Introduction 3
1.3. Terms to Understand
Before understanding RHN Proxy Server, it is important to become familiar with the fol-
lowing 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 — Organization Administrator is a user role with the high-
est level of control over an organization’s Red Hat Network account. Members with this
role can add other users, other 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 management capabilities. Users with this role are capable of creating channels
and assigning packages to channels. This role can be assigned by an Organization Ad-
ministrator 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 use-
ful for troubleshooting the RHN Proxy Server. Tracebacks are automatically generated
when a critical error occurs and are mailed to the individual(s) designated in the RHN
Proxy Server’s configuration file.
For more detailed explanations of these terms and others, refer to the Red Hat Network
Reference Guide available at http://www.redhat.com/docs/.
1.4. How it Works
The Red Hat Update Agent on the client systems does not directly contact a Red Hat Net-
work Server. Instead, the client (or clients) connects to an RHN Proxy Server that connects
to the Red Hat Network Servers or to a RHN Satellite Server. Thus, the client systems do
not need direct access to the Internet. They need access only to the RHN Proxy Server.

4 Chapter 1. Introduction
Important
Red Hat strongly recommends that clients connected to RHN Proxy Server be running
the latest update of Red Hat Enterprise Linux to ensure proper connectivity.
By default, a client is authenticated directly by Red Hat Network Servers. Using an RHN
Proxy Server, authentication works similarly except that the RHN Proxy Server provides
route information as well. After a successful authentication, the Red Hat Network Server
informs the RHN Proxy Server that it is permitted to execute a specific action for the client.
The RHN Proxy Server downloads all of the updated packages (if they are not already
present in its cache) and delivers them to the client system.
Requests from the Red Hat Update Agent on the client systems are still authenticated on
the server side, but package delivery is significantly faster since the packages are cached in
the HTTP Proxy Caching Server or the RHN Proxy Server (for local packages); the RHN
Proxy Server and client system are connected via the LAN and are limited only by the
speed of the local network.
Authentication is done in the following order:
1. The client performs a login action at the beginning of a client session. This login is
passed through one or more RHN Proxy Servers until it reaches a Red Hat Network
Server.
2. The Red Hat Network Server attempts to authenticate the client. If authentication is
successful, the server then passes back a session token via the chain of RHN Proxy
Servers. This token, which has a signature and expiration, contains user information,
including subscribe-to channels, username, etc.
3. Each RHN Proxy Server caches this token on its local file system in
/var/cache/rhn/. Caching reduces some of the overhead of authenticating with
Red Hat Network Servers and greatly improves the performance of Red Hat
Network.
4. This session token is passed back to the client machine and is used in subsequent
actions on Red Hat Network.
From the client’s point of view, there is no difference between an RHN Proxy Server and
a Red Hat Network Server. From the Red Hat Network Server’s point of view, an RHN
Proxy Server is a special type of RHN client. Clients are thus not affected by the route a
request takes to reach a Red Hat Network Server. All the logic is implemented in the RHN
Proxy Servers and Red Hat Network Servers.
Optionally the RHN Package Manager can be installed and configured to serve custom
packages written specifically for the organization. These are not official Red Hat pack-
ages. After creating a private RHN channel, the custom RPM packages are associated
with the private channel by uploading the package headers to the RHN Servers. Only the
headers are uploaded, not the actual package files. The headers are required because they

Chapter 1. Introduction 5
contain crucial RPM information, such as software dependencies, that allows RHN to auto-
mate package installation. The actual custom RPM packages are stored on the RHN Proxy
Server and sent to the client systems from inside the organization’s local area network.
Configuring a computer network to use RHN Proxy Servers is straightforward. The Red
Hat Network applications on the client systems must be configured to connect to the RHN
Proxy Server instead of the Red Hat Network Servers. Refer to the RHN Client Configu-
ration Guide for details. On the proxy side, one has to specify the next proxy in the chain
(which will eventually end with a Red Hat Network Server). If the RHN Package Manager
is used, the client systems must be subscribed to the private RHN channel.

6 Chapter 1. Introduction

Chapter 2.
Requirements
These requirements must be met before installation. To install RHN Proxy Server version
3.6 or later from RHN Satellite Server, the Satellite itself must be version 3.6 or later.
2.1. Software Requirements
To perform an installation, the following software-related components must be available:
•Base operating system — RHN Proxy Server is supported with Red Hat Enterprise
Linux AS 3 Update 5 or later, or Red Hat Enterprise Linux AS 4 only. The operat-
ing system can be installed from disc, local ISO image, kickstart, or any of the methods
supported by Red Hat.
Important
If you plan to obtain Monitoring-level service, you must install your RHN Proxy Server
on Red Hat Enterprise Linux AS 3 Update 5 or Red Hat Enterprise Linux AS 4. These
are the only supported base operating systems for Proxies serving Monitoring-entitled
systems.
Each version of Red Hat Enterprise Linux AS requires a certain package set to support
RHN Proxy Server. Anything more can cause errors during installation. Therefore, Red
Hat recommends obtaining the desired package set in the following ways:
Note
For kickstarting either Red Hat Enterprise Linux AS 4 or Red Hat Enterprise Linux AS
3 Update 5, specify the following package group: @ Base
For installing Red Hat Enterprise Linux AS 4 or Red Hat Enterprise Linux AS 3 Update
5 via CD or ISO image, select the following package group: Minimal
Warning
Security-enhanced Linux (SELinux) must be disabled in Red Hat Enterprise Linux AS
4 prior to installation of RHN Proxy Server. To do this during CD or ISO image instal-
lation, select Disabled when presented with options for SELinux support. To do this

8 Chapter 2. Requirements
for kickstart installation, include the command selinux --disabled or wait for the in-
stall to complete, edit the /etc/selinux/config file to read SELINUX=disabled and
reboot the system.
•An available RHN Proxy Server entitlement within your Red Hat Network account.
•An available Provisioning entitlement within your Red Hat Network account (which
should come packaged with your RHN Proxy Server entitlement).
•Access to the Red Hat Network Tools channel for the installed version of Red Hat En-
terprise Linux AS.
•All rhncfg* packages installed on the Proxy (from the RHN Tools channel).
•Either the rhns-certs-tools package installed on the Proxy (from the RHN Tools
channel) or the secure sockets layer (SSL) CA certificate password used to generate the
parent server certificate (such as on an RHN Satellite Server).
•Configuration of the system to accept remote commands and configuration management
through Red Hat Network. Refer to Section 4.2 RHN Proxy Server Installation Process
for instructions.
2.2. Hardware Requirements
The following hardware configuration is required for the RHN Proxy Server:
•Pentium III processor, 1.26GHz, 512K cache or equivalent
•512 MB of memory
•3 GB storage for base install of Red Hat Enterprise Linux AS
•6 GB storage per distribution/channel
The load on the Apache HTTP Server is directly related to the frequency with which client
systems connect to the Proxy, so if you reduce the default interval of four hours (or 240
minutes) as set in the /etc/sysconfig/rhn/rhnsd configuration file of the client sys-
tems, you will increase the load on this component significantly.
2.3. Disk Space Requirements
The caching mechanism used by RHN Proxy Server is the Squid HTTP proxy, which saves
significant bandwidth for the clients. It should have a reasonable amount of space available.
The cached packages are stored in /var/spool/squid. The required free space allotment
is 6 GB storage per distribution/channel.
If the RHN Proxy Server is configured to distribute custom, or local packages, make sure
that the /var mount point on the system storing local packages has sufficient disk space

Chapter 2. Requirements 9
to hold all of the custom packages, which are stored in /var/spool/rhn-proxy. The
required disk space for local packages depends on the number of custom packages served.
2.4. Additional Requirements
The following additional requirements must be met before the RHN Proxy Server installa-
tion can be considered complete:
•Full Access
Client systems need full network access to the RHN Proxy Server services and ports.
•Firewall Rules
The RHN Proxy Server solution can be firewalled from the Internet, but it must be able to
issue outbound connections to the Internet on ports 80 and 443. In addition, if the Proxy
will be connected to an RHN Satellite Server that will be configured to push actions to
client systems and the Proxy, you must allow inbound connections on port 5222.
•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 are reasonably
close together so the SSL certificate does not expire before or during use. It is recom-
mended Network Time Protocol (NTP) be used to synchronize the clocks.
•Fully Qualified Domain Name (FQDN)
The system upon which the RHN Proxy Server will be installed must resolve its own
FQDN properly.
•A Red Hat Network Account
Customers who will be connecting to the central Red Hat Network Servers to receive
incremental updates will need an 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 Proxy
Server, this includes usernames and passwords for the Organization Administrator ac-
count and SSL certificate generation. Red Hat strongly recommends this information be
copied onto two separate floppy disks, printed out on paper, and stored in a fireproof
safe.
•Distribution Locations
Since the Proxy forwards virtually all local HTTP requests to the central RHN Servers,
you must take care to put files destined for distribution (such as in a kickstart installation
tree) in the non-forwarding location on the Proxy: /var/www/html/pub/. Files placed

10 Chapter 2. Requirements
in this directory can be downloaded directly from the Proxy. This can be especially
useful for distributing GPG keys or establishing installation trees for kickstarts.
In addition, Red Hat recommends the system running the code not be publicly available.
No users but the system administrators should have shell access to these machines. All
unnecessary services should be disabled. You can use ntsysv or chkconfig to disable
services.
Finally, you should have the following technical documents in hand for use in roughly this
order:
1. The RHN Proxy Server Installation Guide — This guide, which you are now reading,
provides the essential steps necessary to get an RHN Proxy 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, reg-
ister 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 Proxy Server can be configured in multiple ways. Select one method depending
on the following factors:
1. The total number of client systems to be served by the
2. The maximum number of clients expected to connect concurrently to the RHN Proxy
Server.
3. The number of custom packages and channels to be served by the RHN Proxy Server.
4. 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 Proxy Topology
The simplest configuration is to use a single RHN Proxy Server to serve your entire net-
work. This configuration is adequate to service a small group of clients and a network that
would benefit from caching Red Hat RPMs and storing custom packages on a local server.
The disadvantage of using one RHN Proxy Server is that performance will be compromised
as the number of clients requesting packages grows.
Figure 3-1. Single Proxy Topology

12 Chapter 3. Example Topologies
3.2. Multiple Proxy Horizontally Tiered Topology
For larger networks, a more distributed method may be needed, such as having multiple
RHN Proxy Servers all connecting to Red Hat Network individually. This horizontally
tiered configuration balances the load of client requests while enabling each Proxy to si-
multaneously synchronize with RHN.
A disadvantage of this horizontal structure is that custom packages loaded to an individual
Proxy must be distributed to its sibling servers. This situation can be addressed in one of
two ways:
•Either, the rsync file transfer program can be used to synchronize packages between the
Proxies, or
•a Network File System (NFS) share can be established between the Proxies and the
custom channel repository.
Either of these solutions will allow any client of any RHN Proxy Servers to have all custom
packages delivered to them.
Figure 3-2. Multiple Proxy Horizontally Tiered Topology
3.3. Multiple Proxy Vertically Tiered Topology
An alternative method for multiple RHN Proxy Servers is to establish a primary Proxy
that the others connect to for RPMs from Red Hat Network and custom packages created
locally. In essence, the secondary Proxies act as clients of the primary. This alleviates the

Chapter 3. Example Topologies 13
need to establish synchronization between the RHN Proxy Servers as they use the up2date
functionality inherent with the product.
Like the horizontally tiered configuration, this vertical method allows any client of any
RHN Proxy Servers to have all custom packages delivered to them. The Proxy merely
looks in its repository to see if it can find the package on its filesystem. If not, it then
makes the attempt from the next level up.
This vertically tiered configuration ensures the secondary Proxies depend upon the primary
for updates from RHN, as well as for custom packages. Also, custom channels and pack-
ages must be placed on the primary Proxy only, to ensure distribution to the child Proxies.
Finally, the configuration files of the secondary Proxies must point to the primary, instead
of directly at Red Hat Network.
Figure 3-3. Multiple Proxy Vertically Tiered Topology
3.4. Proxies with RHN Satellite Server
In addition to the methods described in detail within this chapter, customers also have the
option of using RHN Proxy Server in conjunction with RHN Satellite Server. This works
similarly to the vertically tiered Proxy configuration but increases capacity significantly, as
Satellites can serve a much greater number of client systems.
For a thorough description of this combination, refer to the Example Topologies chapter of
the RHN Satellite Server Installation Guide. Linking the two products’ SSL certificates is

14 Chapter 3. Example Topologies
described in the RHN Client Configuration Guide. To find out how channels and packages
are shared between them, refer to the RHN Channel Management Guide.

Chapter 4.
Installation
This chapter describes the initial installation of the RHN Proxy Server. It presumes the pre-
requisites listed in Chapter 2 Requirements have been met. However, if you are upgrading
to a newer version of RHN Proxy Server, contact your Red Hat representative for assis-
tance.
4.1. Base Install
The RHN Proxy 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 partition that will be used to store packages, according
to the hardware requirements set forth earlier. The default location for cached Red
Hat packages is /var/spool/squid, while custom packages are located in
/var/spool/rhn-proxy.
•Install the packages required by RHN Proxy Server and only those packages. You must
install only the base packages as others will cause the RHN Proxy Server installation
to fail Refer to Section 2.1 Software Requirements for the method to obtain the correct
package group needed for each version of Red Hat Enterprise Linux AS.
Important
If you plan to obtain Monitoring-level service, you must install your RHN Proxy Server
on Red Hat Enterprise Linux AS 3 Update 5 or Red Hat Enterprise Linux AS 4. These
are the only supported base operating systems for Proxies serving Monitoring-entitled
systems.
•Enable Network Time Protocol (NTP) on the Proxy 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 Proxy Server Installation Process
The following instructions describe the RHN Proxy Server installation process:

16 Chapter 4. Installation
1. Register the newly installed Red Hat Enterprise Linux AS system with Red Hat Net-
work (either the central RHN Servers or your RHN Satellite Server) using the orga-
nizational account containing the RHN Proxy Server entitlement with the command:
up2date --register.
2. Grant the system a Provisioning entitlement by visiting the RHN Website (or the
fully qualified domain name of the Satellite serving the Proxy), logging in as the Or-
ganization Administrator, navigating to the Systems ⇒System Entitlements page,
checking the box of system on which the RHN Proxy Server is to be installed and
clicking the Add Provisioning button.
3. Ensure the system is subscribed to the Red Hat Network Tools channel for its base
operating system by clicking the name of the system and navigating to the System
⇒System Details ⇒Channels ⇒Software subtab. If the Red Hat Network Tools
channel is not selected, please select it and subscribe the system to this channel by
clicking on the Change Subscriptions button.
4. Install all the rhncfg packages by navigating to the System ⇒System Details ⇒
Packages ⇒Install subtab and searching for rhncfg using the Filter by Package
Name text search box. In the resulting list, select all the packages and install them.
5. If you will be enabling secure sockets layer (SSL) encryption on the Proxy and con-
necting to the central RHN Servers, install the rhns-certs-tools package from
the same Red Hat Network Tools channel and use the RHN SSL Maintenance Tool
to generate the tar file required later. Refer to the SSL Certificates chapter of the RHN
Client Configuration Guide for instructions.
If you will be enabling SSL encryption on the Proxy and connecting to an RHN
Satellite Server or another RHN Proxy Server with SSL, you will also need the CA
certificate password used for the parent system.
6. Log into the system through a terminal as root and run the rhn_check command to
immediately initiate the scheduled package installation.
7. Once the packages have been installed, as confirmed through the System Details
⇒Events tab, prepare the system to accept remote commands and configuration
management with the following command:
/usr/bin/rhn-actions-control --enable-all
8. Within the RHN website, navigate to the System Details ⇒Proxy subtab.
Warning
Please note the RHN Proxy Server installation may replace the squid.conf and
httpd.conf configuration files on the system to ease upgrades later. If you have
edited these files and want to preserve them, they are rotated in place and can be
retrieved after installation.