Redhat NETWORK PROXY 5.3.0 User Manual
Red Hat Network
Proxy 5.3.0
Installation Guide
Red Hat Network Proxy
Installation Guide
Red Hat Network Proxy 5.3.0 Installation Guide
Red Hat Network Proxy
Edition 5.3.0
Copyright © 2008 Red Hat, Inc. This material may only be distributed subject to the terms and
conditions set forth in the Open Publication License, V1.0 or later with the restrictions noted below (the
latest version of the OPL is presently available at http://www.opencontent.org/openpub/).
Distribution of substantively modified versions of this document is prohibited without the explicit
permission of the copyright holder.
Distribution of the work or derivative of the work in any standard (paper) book form for commercial
purposes is prohibited unless prior permission is obtained from the copyright holder.
Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United
States and other countries.
All other trademarks referenced herein are the property of their respective owners.
The GPG fingerprint of the security@redhat.com key is:
CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E
1801 Varsity Drive
Raleigh, NC 27606-2072USAPhone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588Research Triangle Park, NC 27709USA
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 5
2.1. Software Requirements ................................................................................................ 5
2.2. Hardware Requirements ............................................................................................... 6
2.3. Disk Space Requirements ............................................................................................ 6
2.4. Additional Requirements ............................................................................................... 7
3. Example Topologies 9
3.1. Single Proxy Topology .................................................................................................. 9
3.2. Multiple Proxy Horizontally Tiered Topology ................................................................... 9
3.3. Multiple Proxy Vertically Tiered Topology ..................................................................... 10
3.4. Proxies with RHN Satellite Server ............................................................................... 11
4. Installation 13
4.1. Base Install ................................................................................................................ 13
4.2. RHN Proxy Server Installation Process ........................................................................ 13
4.2.1. The Answer File .............................................................................................. 17
5. RHN Package Manager 19
5.1. Creating a Private Channel ......................................................................................... 19
5.2. Uploading Packages ................................................................................................... 19
5.3. Command Line Options .............................................................................................. 20
6. Troubleshooting 23
6.1. Managing the Proxy Service ....................................................................................... 23
6.2. Log Files .................................................................................................................... 23
6.3. Questions and Answers .............................................................................................. 23
6.4. General Problems ...................................................................................................... 24
6.5. Host Not Found/Could Not Determine FQDN ............................................................... 25
6.6. Connection Errors ...................................................................................................... 25
6.7. Caching Issues .......................................................................................................... 26
6.8. Proxy Debugging by Red Hat ..................................................................................... 27
A. RHN Proxy Server Installation via Satellite Website 29
B. Sample RHN Proxy Server Configuration File 39
C. Revision History 41
Index 43
iii
iv
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 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
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 package-caching mechanism that reduces the bandwidth requirements
for RHN and enables custom package deployment. Proxy customers cache RPMs, such as Errata
Updates from Red Hat or custom RPMs generated by their organization, on an internal, centrallylocated server. Client systems then receive these updates from the Proxy rather than by accessing the
Internet individually.
Although the packages are served by the Proxy, clients' System Profiles and user information are
stored on the secure, central RHN Servers1, which also serve the RHN website (rhn.redhat.com). The
Proxy acts as a go-between for client systems 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
1
Throughout this document, "RHN" may refer to either RHN's Hosted site (http://rhn.redhat.com) or an RHN Satellite Server.
1
Chapter 1. Introduction
own GPG signature, and have the local RHN Proxy Server update all of 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 RHN only once (per local Proxy Server's
caching mechanism) instead of downloading each package to each client system.
• 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 — Because clients connect only to the RHN Proxy Server
and not the Internet, they require only a Local Area Network connection to the Proxy. 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.3. Terms to Understand
Before understanding RHN Proxy 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 that contains extra
packages.
Organization Administrator
An Organization Administrator is a user role with the highest level of control over an organization's
Red Hat Network account. Members 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 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 or yum) that
allows users to retrieve and install new or updated packages for the client system on which the
application is run.
2
How it Works
Traceback
A traceback is a detailed description of "what went wrong" that is useful for troubleshooting the
RHN Proxy Server. Tracebacks are automatically generated when a critical error occurs and are
emailed 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/manuals/satellite/ and the Help page on the Satellite
Web user interface.
1.4. How it Works
The Red Hat Update Agent or Package Updater on the client systems does not directly contact a
Red Hat Network Server. Instead, the client (or clients) connects in turn 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.
Important
Red Hat strongly recommends that clients connected to an RHN Proxy Server be
running the latest update of Red Hat Enterprise Linux to ensure proper connectivity.
Clients that access RHN directly are authenticated by the RHN servers. Clients that access an
RHN Proxy Server are still authenticated by RHN; however, in this case the Proxy provides both
authentication and route information to RHN. 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 or Package Updater 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 channel subscriptions,
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
3
Chapter 1. Introduction
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.
Any package that is not an official Red Hat package, including custom packages written specifically
for an organization, can only be served from a private software channel (also referred to as a custom
software channel). After creating a private RHN channel, the custom RPM packages are associated
with that 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 contain crucial RPM
information, such as software dependencies, that allows RHN to automate 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 Configuration Guide for details. On the proxy
side, one has to specify the next proxy in the chain (which eventually ends with a Red Hat Network
Server). If the RHN Package Manager is used, the client systems must be subscribed to the private
RHN channel.
4
Chapter 2.
Requirements
These requirements must be met before installation. To install RHN Proxy Server 5.3.0 from RHN
Satellite Server, the Satellite itself must be version 5.3.0.
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 4
or Red Hat Enterprise Linux 5. The operating system can be installed from disc, local ISO image,
kickstart, or any of the methods supported by Red Hat.
Each version of Red Hat Enterprise Linux requires a certain package set to support RHN
Proxy Server. Adding more packages can cause errors during installation. Therefore, Red Hat
recommends obtaining the desired package set in the following ways:
Note
For kickstarting, specify the following package group: @Base
For installing Red Hat Enterprise Linux via CD or ISO image, select the following
package group: Minimal
Warning
If you are running Red Hat Enterprise Linux AS 4, Security-enhanced Linux
(SELinux) must be disabled prior to installation of RHN Proxy Server. If you use Red
Hat Enterprise Linux 5 Server, SELinux can be left enabled when installing RHN
Proxy Server.
You can disable SELinux in one of several ways:
• During CD or ISO image installation, select Disabled when presented with
options for SELinux support.
• To do this for kickstart installation, include the command selinux --disabled
• After the installation is complete, edit the /etc/selinux/config file to read
SELINUX=disabled and reboot the system.
• Finally, you can use the system-config-securitylevel-tui command and
reboot the system.
• An available RHN Proxy Server entitlement within your RHN Satellite Server account.
• An available Provisioning entitlement within your RHN Satellite Server account (which should come
packaged with your RHN Proxy Server entitlement).
5
Chapter 2. Requirements
• Access to the Red Hat Network Tools channel for the installed version of Red Hat Enterprise
Linux. This channel includes the spacewalk-proxy-installer package that contains the
configure-proxy.sh installation program required to install RHN Proxy Server.
• 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) for
RHN Hosted users, or the secure sockets layer (SSL) CA certificate password used to generate the
parent server certificate for RHN Satellite Server users.
• Configuration of the system to accept remote commands and configuration management through
Red Hat Network if using the deprecated Web UI installation method. 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:
• A Pentium IV Processor or equivalent
• 512 MB of memory
• At least 5 GB storage for base install of Red Hat Enterprise Linux
• 25+ GB storage per distribution/channel
The load on the Apache Web server is directly related to the frequency with which client systems
connect to the Proxy. 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 systems, you will increase the load on
this component significantly.
Note
RHN Proxy Server does not support kickstart provisioning on multi-homed network
topologies. Kickstarts will not function properly on a Proxy server that has more than
one network interface.
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 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.
6
Additional Requirements
2.4. Additional Requirements
The following additional requirements must be met before the RHN Proxy Server installation can be
considered complete:
Full Access
Client systems need full network access to the RHN Proxy Server services and ports.
Firewall Rules
RHN strongly recommends firewalling the RHN Proxy Server solution from the Internet. However,
various TCP ports must be opened on the Proxy, depending on your implementation of RHN
Proxy Server:
Port Direction Reason
80 Outbound Proxy uses this port to reach
rhn.redhat.com, xmlrpc.rhn.redhat.com,
and your Satellite URL (depending on
whether RHN Proxy is talking to either
RHN Hosted or a Satellite Server).
80 Inbound Client requests come in via either http or
https
443 Inbound Client requests come in via either http or
https
443 Outbound Proxy uses this port to reach
rhn.redhat.com, xmlrpc.rhn.redhat.com,
and your Satellite URL (depending on
whether RHN Proxy is talking to either
RHN Hosted or a Satellite Server).
4545 Outbound If your Proxy is connected to an RHN
Satellite Server, Monitoring makes
connections to rhnmd running on client
systems via this TCP port, if Monitoring
is enabled and probes configured to
registered systems.
5222 Inbound Opening this port allows osad client
connections to the jabberd daemon
on the Proxy when using RHN Push
technology.
5269 Outbound If your Proxy is connected an RHN
Satellite Server, this port must be open to
allows server-to-server connections via
jabberd for RHN Push Technology.
Table 2.1. Ports to open on the Proxy
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 that SSL certificate does not expire before or during use. It is recommended that Network Time
Protocol (NTP) be used to synchronize the clocks.
7
Chapter 2. Requirements
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 must have a Red Hat Network account. The sales representative assists with the setup of
this account at the time of purchase.
Backups of Login Information
It is imperative that customers keep track of all primary login information. For RHN Proxy Server,
this includes usernames and passwords for the Organization Administrator account 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 nonforwarding location on the Proxy: /var/www/html/pub/. Files placed 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 that 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, 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.
8
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 RHN Proxy Server
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 network. 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
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 simultaneously 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:
• The rsync file transfer program can be used to synchronize packages between the Proxies
9
Chapter 3. Example Topologies
• 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 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 file system. If not, it then makes the attempt from the next level up.
This vertically tiered configuration ensures that the secondary Proxies depend upon the primary for
updates from RHN, as well as for custom packages. Also, custom channels and packages 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.
10
Figure 3.3. Multiple Proxy Vertically Tiered Topology
Proxies with RHN Satellite Server
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 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.
11
Loading...