Proxy Installation Guide

Red Hat Satellite 5.6

Configuring, registering, and updating your Red Hat Enterprise Linux clients with Red Hat Satellite Proxy Server

Edition 1

John Ha

Red Hat Engineering Content Services

Lana Brindley

Red Hat Engineering Content Services

Daniel Macpherson

Red Hat Engineering Content Services

Athene Chan

Red Hat Engineering Content Services

David O'Brien

Red Hat Engineering Content Services

Megan Lewis

Red Hat Engineering Content Services

Legal Notice

Abstract

This document provides guidance on installing, configuring, and updating a Red Hat Satellite Proxy Server. For further information, see the Red Hat Satellite Getting Started Guide and the Red Hat Satellite Installation Guide.

Preface

Red Hat Network provides system-level support and management of Red Hat systems and networks. It brings together the tools, services, and information repositories needed to maximize the reliability, security, and performance of Red Hat systems. To use Red Hat Network, system administrators register 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.

Red Hat Satellite (Satellite) allows organizations to use the benefits of Red Hat Network without having to provide public Internet access to their servers or other client systems. System profiles are stored locally on the Satellite server. The Satellite website is served from a local web server and is only accessible to systems that can reach the Satellite. All package management tasks, including errata updates, are performed through the Satellite server.

Satellite provides a solution for organizations that require absolute control over and privacy of the maintenance and package deployment of their servers. It allows Red Hat Network customers the greatest flexibility and power in keeping systems secure and updated. Modules can be added to the Satellite server to provide extra functionality.

Chapter 1. Introduction

1.1. Red Hat Satellite Proxy Server

Red Hat Satellite Proxy Server is a package-caching mechanism that reduces the bandwidth requirements for Red Hat Satellite and enables custom package deployment. Satellite Proxy customers cache RPM packages, such as Errata Updates from Red Hat or custom packages generated by their organization, on an internal, centrally-located server. Client systems then receive these updates from Red Hat Satellite Proxy rather than by accessing the Internet individually.

Although the packages are served by Red Hat Satellite Proxy, clients' system profiles and user information are stored on a secure, central Red Hat Satellite Server. The Satellite Proxy acts as a go-between for client systems and the Red Hat Satellite Server. Only the package files are stored on the Satellite Proxy. Every transaction is authenticated, and the Red Hat Update Agent checks the GPG signature of each package retrieved from the local Satellite Proxy.

In addition to storing official Red Hat packages, the Satellite Proxy Server can be configured to deliver an organization's own custom packages from private channels. For example, an organization could develop its own software, package it in an RPM, sign it with its own GPG signature, and have the local Satellite Proxy Server update all of the individual systems in the network with the latest versions of the custom software.

Advantages of using Satellite Proxy Server include:

Scalability: one organization can support multiple local Red Hat Satellite Proxies.
Security: a secure connection is maintained from the client systems to the local Satellite Proxy, and from there to the Red Hat Satellite servers.
Saves time: packages are delivered significantly faster over a local area network than the Internet.
Saves bandwidth: packages are only downloaded once from Red Hat Satellite (using the local Satellite Proxy Server's caching mechanism), instead of downloading each package separately to each client system.
Customized updates: create an automated package delivery system for custom software packages, as well as official Red Hat packages required for the client systems. Customized, private Red Hat Satellite channels allow an organization to automate delivery of in-house packages.
Customized configuration: restrict or grant updates to specific architectures and operating system versions.

1.2. Architecture and Operations

The Red Hat Update Agent or Package Updater on the client systems does not directly contact a Red Hat Satellite Server. Instead, the client (or clients) connects in turn to a Satellite Proxy Server that connects to a Red Hat Satellite Server. Thus, the client systems do not need direct access to the Internet. They need access only to the Satellite Proxy Server.

Important

Red Hat strongly recommends that clients connected to a Satellite Proxy server be running the latest update of Red Hat Enterprise Linux to ensure proper connectivity.

Clients that access a Red Hat Satellite Proxy are still authenticated by Red Hat Satellite but in this case the Satellite Proxy provides both authentication and route information to Red Hat Satellite. After a successful authentication, the Red Hat Satellite Server informs the Satellite Proxy server that it is permitted to execute a specific action for the client. The Satellite 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 because the packages are cached in the HTTP Proxy Caching Server or the Satellite Proxy server (for local packages). The Satellite Proxy server and client system are connected over the LAN and transfer speeds are limited only by the speed of the local network.

The authentication process proceeds as follows:

The client performs a login action at the beginning of a client session. This login is passed through one or more Satellite Proxy Servers until it reaches a Red Hat Satellite server.
The Red Hat Satellite server attempts to authenticate the client. If authentication is successful, the server returns a session token through the chain of Satellite Proxy Servers. This token, which has a signature and expiration time, contains user information, such as channel subscriptions, username, and so on.
Each Satellite Proxy Server caches this token on its local file system in the /var/cache/rhn/ directory. Caching reduces some of the overhead of authenticating with Red Hat Satellite servers and greatly improves the performance of Red Hat Satellite.
This session token is sent to the client machine and is used in subsequent actions on Red Hat Satellite.

From the client's perspective, there is no difference between a Satellite Proxy Server and a Red Hat Satellite server. From the Red Hat Satellite server's perspective, a Satellite Proxy Server is a special type of Red Hat client. Clients are thus not affected by the route that a request takes to reach a Red Hat Satellite server. All of the logic is implemented in the Satellite Proxy Servers and Red Hat Satellite servers.

The Red Hat Network Package Manager can also 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 Red Hat Satellite channel, the custom RPM packages are associated with that channel by uploading the package headers to the Red Hat Satellite 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 Red Hat Satellite to automate package installation. The actual custom RPM packages are stored on the Satellite Proxy Server and sent to the client systems from inside the organization's local area network.

Configuring a computer network to use Satellite Proxy Servers is straightforward. The Red Hat Satellite applications on the client systems must be configured to connect to the Satellite Proxy Server instead of a Red Hat Satellite server. See the Client Configuration Guide for details. On the proxy side, you need to specify the next proxy in the chain (which eventually ends with a Red Hat Satellite server). If the Red Hat Package Manager is used, the client systems must be subscribed to the private Red Hat channel.

1.3. Important Terms

To better understand Red Hat Satellite Proxy, it is important to become familiar with the following Red Hat Satellite 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 Satellite account. Members with this role can add and remove other users, other systems, and system groups to the organization. Each Red Hat Satellite organization requires at least one Organization Administrator.
Channel Administrator: A Channel Administrator is a user role with full access to channel management capabilities. Channel Administrators can create channels and assign packages to channels. Organization Administrators can use the Users tab on the Red Hat Satellite website to assign this role to other users.
Red Hat Update Agent: The Red Hat Update Agent is the Red Hat Network client application (yum) that allows users to retrieve and install new or updated packages on the client system.
Traceback: A traceback is a detailed error description that is useful for troubleshooting the Satellite Proxy. Traceback files are automatically generated when a critical error occurs, and they are then emailed to the individuals designated in the Satellite Proxy's configuration file.

See the Red Hat Reference Guide and the Help page on the Satellite Web user interface for more information.

Chapter 2. Requirements

This chapter focuses on the prerequisites for installing Red Hat Satellite Proxy Server. If the Satellite Proxy connects to a Satellite Server, the version of that Satellite Server must be greater than or equal to the version of the Satellite Proxy that is being installed. For example, Satellite Proxy Server 5.6 requires Satellite Server 5.6 or later.

2.1. Software Requirements

To perform an installation, the following software-related components must be available:

Base operating system: Satellite Proxy is supported on Red Hat Enterprise Linux 5 and 6. The operating system can be installed using any of the methods supported by Red Hat.
Important
Red Hat Satellite Proxy Server does not currently run on Red Hat Enterprise Linux 7. Satellite Proxy can manage Red Hat Enterprise Linux 7 clients, but only when used with Satellite 5.6. Satellite Proxy cannot manage Red Hat Enterprise Linux 7 clients in a Red Hat Satellite Proxy-only environment.
Satellite Proxy can be installed on Red Hat Enterprise Linux 5 and 6 in any virtualized environment supported by Red Hat, including Xen, KVM, and VMware.
In production deployments, Red Hat recommends that you deploy Satellite Proxy as the sole application running on the underlying physical hardware to avoid contention issues. Also, be aware that functional support for virtualized environments does not always equal the performance of running on physical hardware, so carefully consider the virtualized environment of choice and any recommended tuning guidelines.
Note
Each purchased Satellite Proxy includes one supported instance of Red Hat Enterprise Linux Server. Satellite Proxy must be installed onto a fresh installation of Enterprise Linux where Satellite Proxy is the only application and service provided by the operating system. Using the Red Hat Enterprise Linux operating system included in Satellite Proxy to run other daemons, applications, or services within the environment is not supported.
Each version of Red Hat Enterprise Linux requires a certain package set to support Satellite Proxy. 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 from CD or ISO image, select the following package group: Minimal
An available Satellite Proxy entitlement within the Satellite Server account.
An available Provisioning entitlement within the Satellite Server account (which should come packaged with the Satellite Proxy entitlement).
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 Satellite Proxy.
All rhncfg* packages installed on the Satellite Proxy (from the Red Hat Network Tools channel).
Either the spacewalk-certs-tools package installed on the Satellite Proxy (from the Red Hat Network Tools channel) for Hosted users, or the secure sockets layer (SSL) CA certificate password used to generate the parent server certificate for 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. See Section 3.2, “Red Hat Satellite Proxy Server Installation Process” for instructions.

2.2. Hardware Requirements

The following hardware configuration is required for the Satellite Proxy:

A Pentium IV Processor or equivalent
2G of memory required; 4G of memory recommended
At least 5 GB storage for base install of Red Hat Enterprise Linux
6 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 Satellite Proxy. If the default interval of four hours (or 240 minutes) as set in the /etc/sysconfig/rhn/rhnsd configuration file of the client systems is reduced, the load on this component increases significantly.

Note

The installation procedure configures the caching abilities to be optimized for resources available. Provide more memory and disk space prior to installation to increase active caching within Red Hat Satellite Proxy.

2.3. Disk Space Requirements

The caching mechanism used by Satellite Proxy 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 Satellite Proxy 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.

2.4. Additional Requirements

The following additional requirements must be met before the Satellite Proxy installation can be considered complete:

Full Access

Client systems need full network access to the Satellite Proxy services and ports.

Firewall Rules

Red Hat strongly recommends setting up a firewall between the Satellite Proxy and the Internet. However, depending on your Satellite Proxy implementation, you need to open several TCP ports in this firewall:

Table 2.1. Ports to Open on the Satellite Proxy
Port	Direction	Reason
80	Outbound	The Satellite Proxy uses this port to reach your Satellite URL.
80	Inbound	Client requests arrive using either HTTP or HTTPS.
443	Inbound	Client requests arrive using either HTTP or HTTPS.
443	Outbound	The Satellite Proxy uses this port to reach the Satellite URL.
4545	Outbound	If your Satellite Proxy is connected to a Satellite Server, Monitoring makes connections to `rhnmd` running on client systems through this TCP port, if Monitoring is enabled and probes are configured to registered systems.
5222	Inbound	Allows `osad` client connections to the `jabberd` daemon on the Satellite Proxy when using Red Hat Network Push technology.
5269	Outbound	If the Satellite Proxy is connected a Satellite Server, this port must be open to allow server-to-server connections using `jabberd` for Red Hat Network Push Technology.

Synchronized System Times

Time sensitivity is a significant factor when connecting to a Web server running SSL (Secure Sockets Layer); it is imperative the time settings on the clients and server are close together so that the SSL certificate does not expire before or during use. It is recommended that Network Time Protocol (NTP) be used to synchronize the clocks.

Fully Qualified Domain Name (FQDN)

The system upon which the Satellite Proxy is installed must resolve its own FQDN properly.

Backups of Login Information

It is imperative that customers keep track of all primary login information. For Satellite Proxy, this includes user names and passwords for the Organization Administrator account and SSL certificate generation. Red Hat strongly recommends this information be copied onto two separate back-up disks (CD/DVD/removable hard drives), printed out on paper, and stored in a safe place.

Distribution Locations

Because the Satellite Proxy forwards virtually all local HTTP requests to the central Red Hat Network servers, take care in putting files destined for distribution (such as in a kickstart installation tree) in the non-forwarding location on the Satellite Proxy: /var/www/html/pub/. Files placed in this directory can be downloaded directly from the Satellite Proxy. This can be especially useful for distributing GPG keys or establishing installation trees for kickstart files.

Red Hat recommends that the system running the code should not be publicly available. Only system administrators should have shell access to these machines. All unnecessary services should be disabled. Use ntsysv or chkconfig to disable services.

Chapter 3. Installing Red Hat Satellite Proxy

This chapter describes the initial installation of Red Hat Satellite Proxy Server. It presumes the prerequisites listed in Chapter 2, Requirements have been met. However, if you are upgrading to a later version of Red Hat Satellite Proxy Server, contact your Red Hat representative for assistance.

3.1. Base Install

Red Hat Satellite Proxy Server is designed to run on the Red Hat Enterprise Linux operating system. Therefore, the first step is to install the base operating system. During and after the operating system installation process, ensure that you:

Allocate sufficient space to the partition that will be used to store packages according to the hardware requirements prescribed earlier. The default location for cached Red Hat packages is /var/spool/squid; custom packages are located in /var/spool/rhn-proxy.
Note
The installation program automatically calculates the available space on the partition where /var/spool/squid is mounted and allocates up to 60 per cent of the free space for use by Satellite Proxy.
Ensure the firewall rules are updated to meet the requirements stated in Section 2.4, “Additional Requirements”. Modify your iptables settings and restart the service.
Install the packages required by Red Hat Satellite Proxy Server.
Important
Install only the base Satellite Proxy packages as installing additional packages might cause the Satellite Proxy installation to fail.
See Section 2.1, “Software Requirements” for how to obtain the correct package group needed for each version of Red Hat Enterprise Linux.
Enable Network Time Protocol (NTP) and select the appropriate time zone on the Satellite Proxy and on all client systems.

3.2. Red Hat Satellite Proxy Server Installation Process

The following instructions describe the Satellite Proxy installation process:

Procedure 3.1. Configuring the Base System

Log in as the root user on the intended Satellite Proxy system.
Use the rhn_register command to register the newly-installed Red Hat Enterprise Linux system with either Red Hat Network or Red Hat Satellite Server, using the organizational account containing the Satellite Proxy entitlement.
Subscribe the client to the Red Hat Network Tools channel.
Install the Satellite Proxy installation package. This package contains the main script that leads you through the actual Satellite Proxy installation.
```
# yum install spacewalk-proxy-installer
```

Installing the Red Hat Satellite Proxy Server

The command-line installation program guides you through the actual Satellite Proxy installation process. This program presents a series of prompts regarding Satellite Proxy installation and initial configuration details, such as installation options and SSL certificate generation. You need root access to the server to perform this step.

Important

Before you running the installation script, the Satellite Proxy requires SSL files from your Satellite Server. Create the /root/ssl-build directory:

# mkdir /root/ssl-build

Then copy the public certificate and CA certificate from the desired Red Hat Satellite to the new directory:

# scp 'root@www.satellite.com:/root/ssl-build/{RHN-ORG-PRIVATE-SSL-KEY,RHN-ORG-TRUSTED-SSL-CERT,rhn-ca-openssl.cnf}' /root/ssl-build

Alternatively, append the --force-own-ca option when you run the installation script.

Run the following installation script to install Red Hat Satellite Proxy Server:

# configure-proxy.sh

Note

You can press Enter at any prompt to use the default response enclosed in brackets. Alternatively, use the --non-interactive option with the installation script if you want to use default answers without any user interaction.

Gathering Satellite Proxy Server Installation Information

The installation script requests details about the Satellite Proxy installation specific to the machine where you are performing the installation.

Satellite Proxy version to activate [5.6]:: Request for confirmation of the version of Satellite Proxy to install.
Red Hat Network Parent [satserver.example.com]:: The Satellite Server domain name or address of the system that serves content to the Satellite Proxy.
Traceback email []:: A comma-separated list of email addresses to which error-related traceback messages are sent, usually the email of the Satellite Proxy administrator.

Configuring SSL and Satellite Proxy Details

The installation script also requests information necessary for generating an SSL certificate, and for configuring an HTTP proxy if required. Red Hat recommends using SSL to secure traffic to and from the Satellite Proxy Server.

Use SSL [Y/n]:

Press Enter or type y to configure the Satellite Proxy to use SSL.

CA Chain [/usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT]:

Press Enter to use the default path for the Certificate Authority (CA) Chain.

If the Satellite Proxy is communicating with Red Hat Satellite, then this value is usually /usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT. Otherwise, custom SSL certificates must be located in the /usr/share/rhn/ directory.

HTTP Proxy []:

If the Satellite Proxy server connects through an HTTP proxy, enter the proxy host name and port number, for example, corporate.proxy.example.com:3128

Enter the details necessary to generate a valid SSL server certificate. Example 3.1, “Example Generation of an SSL Certificate” demonstrates generating such a certificate.

Example 3.1. Example Generation of an SSL Certificate

Regardless of whether you enabled SSL for the connection to the Satellite Proxy Parent
Server, you will be prompted to generate an SSL certificate.
This SSL certificate will allow client systems to connect to this Spacewalk Proxy
securely. See the Spacewalk Proxy Installation Guide for more information.
Organization: Example Company
Organization Unit [proxy1.example.com]:
Common Name: proxy1.example.com
City: New York
State: New York
Country code: US
Email [admin@example.com]:

Performing Post-installation Tasks

After the main Satellite Proxy installation tasks have been completed, the installation program performs a number of additional tasks, such as prompting for installation of monitoring support, creating configuration channels, and restarting modified daemons.

You do not have monitoring installed. Do you want to install it? Will run 'yum install spacewalk-proxy-monitoring'. [Y/n]:

Confirm whether or not you want to install Monitoring support on the Satellite Proxy server.

Configure SSL

The configure-proxy.sh program configures SSL, and prompts you to create a Certificate Authority password and confirm it before generating the SSL keys and the public certificate. Example 3.2, “Example Generation of CA Key and Public Certificate” demonstrates generating a CA key and public certificate.

Example 3.2. Example Generation of CA Key and Public Certificate

Generating CA key and public certificate:
CA password:
CA password confirmation:
Copying CA public certificate to /var/www/html/pub for distribution to clients:
Generating SSL key and public certificate:
CA password:
Backup made: 'rhn-ca-openssl.cnf' --> 'rhn-ca-openssl.cnf.1'
Rotated: rhn-ca-openssl.cnf --> rhn-ca-openssl.cnf.1
Installing SSL certificate for Apache and Jabberd:
Preparing packages for installation...
rhn-org-httpd-ssl-key-pair-proxy1.example-1.0-1

Create Configuration Channel

The installation program also requests confirmation that you want to create a configuration channel based on the configuration files created while running configure-proxy.sh.

The installation program creates a Satellite Server configuration channel based on the name of the system (the sysID) where the Satellite Proxy is installed (in the following example, the sysID is 1000010000), and collects the various httpd, SSL, squid, and jabberd server files that will comprise the configuration channel for the Satellite Proxy server.

An example of this configuration is shown in Example 3.3, “Example of Creating a Configuration Channel”.

Example 3.3. Example of Creating a Configuration Channel

Create and populate configuration channel rhn_proxy_config_1000010000? [Y]:
Using server name satserver.example.com
Red Hat Network username: admin
Password:
Creating config channel rhn_proxy_config_1000010000
Config channel rhn_proxy_config_1000010000 created
using server name satserver.example.com
Pushing to channel rhn_proxy_config_1000010000:
Local file /etc/httpd/conf.d/ssl.conf -> remote file /etc/httpd/conf.d/ssl.conf
Local file /etc/rhn/rhn.conf -> remote file /etc/rhn/rhn.conf
Local file /etc/rhn/cluster.ini -> remote file /etc/rhn/cluster.ini
Local file /etc/squid/squid.conf -> remote file /etc/squid/squid.conf
Local file /etc/httpd/conf.d/cobbler-proxy.conf -> remote file /etc/httpd/conf.d/cobbler-proxy.conf
Local file /etc/httpd/conf.d/rhn_proxy.conf -> remote file /etc/httpd/conf.d/rhn_proxy.conf
Local file /etc/httpd/conf.d/rhn_broker.conf -> remote file /etc/httpd/conf.d/rhn_broker.conf
Local file /etc/httpd/conf.d/rhn_redirect.conf -> remote file /etc/httpd/conf.d/rhn_redirect.conf
Local file /etc/jabberd/c2s.xml -> remote file /etc/jabberd/c2s.xml
Local file /etc/jabberd/sm.xml -> remote file /etc/jabberd/sm.xml

Restart services

The final step of the installation process is to restart all of the Satellite Proxy-related services. The installation program exits when this step is completed.

Example 3.4. Restarting all Satellite Proxy Server-related Services

Enabling Satellite Proxy
Shutting down rhn-proxy...
Shutting down Jabber router:                               [  OK  ]
Stopping httpd:                                            [  OK  ]
Stopping squid:                                            [  OK  ]
Done.
Starting rhn-proxy...
init_cache_dir /var/spool/squid... Starting squid: .       [  OK  ]
Starting httpd:                                            [  OK  ]
Starting Jabber services                                   [  OK  ]
Done.

3.3. Automating Satellite Proxy Server Installation

To automate some of the process of installing Satellite Proxy on your systems, the configure-proxy.sh script allows administrators to create answer files that contain predetermined responses to prompts in the installation program.

The following is an example answer file that contains predetermined answers related to version number, the Satellite Server that serves as the parent server, SSL, and other configuration parameters. See the configure-proxy.sh manual page (man configure-proxy.sh) for more information about creating and using answer files.

# example of answer file for configure-proxy.sh
# for full list of possible option see
# man configure-proxy.sh

VERSION=5.6
RHN_PARENT=rhn-satellite.example.com
TRACEBACK_EMAIL=jsmith@example.com
USE_SSL=1
SSL_ORG="Red Hat"
SSL_ORGUNIT="Spacewalk"
SSL_CITY=Raleigh
SSL_STATE=NC
SSL_COUNTRY=US
INSTALL_MONITORING=N
ENABLE_SCOUT=N
CA_CHAIN=/usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT
POPULATE_CONFIG_CHANNEL=Y

Using Answer Files to Automate Installation

Use the --answer-file option with the configure-proxy.sh script to use an answer file to help automate your Satellite Proxy installation, as shown in the following example. Replace the example answers_file.txt file name with the path to your answer file.

# configure-proxy.sh --answer-file=/path/to/answers_file.txt

Chapter 4. Configuring Satellite Proxy to Use CNAME Records

One of the features of Red Hat Satellite Proxy is the ability to take advantage of CNAME records, or aliases, instead of the canonical host name. This feature is useful if there are network issues that prevent communication with Red Hat Satellite Proxy using its normal host name or configuration.

4.1. Prerequisites

To use CNAME records with your Red Hat Satellite Proxy Server installation, you need to:

Ensure that the required CNAME records have been configured for the server.
Add the CNAME records to the Satellite Proxy server configuration.
Create a new multi-host certificate and install it on the Satellite Proxy.

4.2. Adding CNAME Records to the Satellite Proxy Server Configuration

This section describes how to add your Satellite Proxy server's CNAME records to the Satellite Proxy server configuration, and have those CNAMEs recognized as valid options within the Satellite Proxy web interface.

Note

This document does not cover how to set up DNS CNAME records for the machine where your Satellite Proxy server is installed. Contact your system or DNS administrator to ensure the required CNAME records are correctly set up.

Procedure 4.1. To Configure Your Satellite Proxy Server to Use CNAME Records:

Add the following line to the /etc/rhn/rhn.conf file:
valid_cnames_<systemID of Proxy server> = cname1,cname2,cname3
Run the following command to restart the Tomcat service:
```
# service tomcat6 restart
```

After the Tomcat service has restarted, refresh the Satellite Proxy server web interface and you should see the CNAMEs listed on the Hardware tab of the System Details page.

Before you can use these CNAMEs, however, you need to create a new set of certificates, and configure the Satellite Proxy to use these certificates. This is because the original certificate is only valid for the canonical host name; you need to create new certificates that are valid for each CNAME. This is covered in Section 4.3, “Generating and Using Multi-host SSL Certificates”.

4.3. Generating and Using Multi-host SSL Certificates

You need to generate multi-host SSL certificates to take advantage of the ability to use CNAME records on the Satellite Proxy server. You also need to update the rhn-ca-openssl.cnf file to ensure that the Satellite Proxy server is aware of and uses these certificates.

Procedure 4.2. To Update the SSL Configuration File to use Multi-host Certificates:

Edit the /root/ssl-build/rhn-ca-openssl.cnf file and locate the [CA_default] section.
Ensure the entry copy_extensions = copy exists and is not commented out.
Save and close the file.

Important

You need to complete the above step before you run configure-proxy.sh with SSL_CNAME set, or the installation will fail.

You also need to update your answers file so that the Satellite Proxy configuration will use the new SSL certificates created previously.

Procedure 4.3. To Update the Answers File to Use Multi-host SSL Certificates:

Edit the answers.txt file that you created for the initial Satellite Proxy installation. If you did not create such a file, you can find an example setup in /usr/share/doc/spacewalk-setup-<version>/answers.txt.
Ensure the following line exists, and is not commented out:
```
SSL_CNAME = (cname01 cname02 cname03)
```
Run the configure-proxy.sh script with the --answer-file option to generate the multi-host SSL certificate. For example:
```
# configure-proxy.sh --answer-file=</path/to/answers.txt>
```
Note
You can run the configure-proxy.sh script multiple times to test or update configurations, as required.

Chapter 5. Upgrading a Red Hat Proxy Server Installation

This chapter describes how to upgrade your Proxy Server installation. These instructions assume that you have a fully functional Proxy Server and its required entitlements.

5.1. Prerequisites

The latest version of Red Hat Satellite Proxy Server requires:

Red Hat Enterprise Linux 5 (64-bit only) or Red Hat Enterprise Linux 6 (64-bit only).
Removal of the previous Proxy server's system profile from the parent Satellite server.

5.2. Upgrading Your Proxy Installation

Back up your existing Proxy server. If applicable, restore the SSL build direction from the backup to the directory /root/ssl-build.
Register the Proxy to the parent Satellite. Make sure that the Proxy is subscribed to both the Red Hat Enterprise Linux Server base channel and the Red Hat Network Tools child channel.
Install the spacewalk-proxy-installer package from the Red Hat Network Tools child channel:
```
# yum install spacewalk-proxy-installer
```
Install the latest version of Proxy, as documented in Section 3.2, “Red Hat Satellite Proxy Server Installation Process”.
Note
If the Proxy server is registered to Red Hat Satellite, and the Proxy previously managed custom channels, restore the custom package repository from the pre-upgrade backup. The permissions and ownership will also need to be set up properly.
```
# chmod 0750 /var/spool/rhn-proxy
# chown apache:apache /var/spool/rhn-proxy
# mkdir -m 0750 -p /var/spool/rhn-proxy/list
# chown apache:apache /var/spool/rhn-proxy/list
```
The default custom package repository is usually /var/spool/rhn-proxy.
After the installation, update the server to the latest errata updates:
```
# yum update
```
Restart the Proxy Server services and test the Proxy Server's functionality:
```
# /usr/sbin/rhn-proxy restart
```

Appendix A. Sample Satellite Proxy Server Configuration File

The /etc/rhn/rhn.conf configuration file for the Satellite Proxy provides a means for administrators to establish key settings. Take care when making any changes, however, because any configuration errors in this file may cause Satellite Proxy failures.

If you are also using a Red Hat Satellite server, pay close attention to the traceback_mail and proxy.rhn_parent parameters. Review the sample and its comments (comments are identified by a hash mark (#) in column 1), for additional details.

Important

You can add the use_ssl option to rhn.conf for testing purposes. Set its value to 0 to turn off SSL between the Satellite Proxy and the upstream server. Be aware that this greatly compromises security. Reset this option to its default value of 1 to re-enable SSL, or remove the line from the configuration file.

# Automatically generated RHN Management Proxy Server configuration file.
# -------------------------------------------------------------------------

# SSL CA certificate location
proxy.ca_chain = /usr/share/rhn/RHNS-CA-CERT

# Corporate HTTP proxy, format: corp_gateway.example.com:8080
proxy.http_proxy =

# Password for that corporate HTTP proxy
proxy.http_proxy_password =

# Username for that corporate HTTP proxy
proxy.http_proxy_username =

# Location of locally built, custom packages
proxy.pkg_dir = /var/spool/rhn-proxy

# Hostname of RHN Server or RHN Satellite
proxy.rhn_parent = rhn.redhat.com

# Destination of all tracebacks, etc.
traceback_mail = user0@domain.com, user1@domain.com

Appendix B. Revision History

Revision History

Revision 3-23.401

Thu Aug 20 2015

Dan Macpherson

Mass publication of all Satellite 5.6 books

Revision 3-23.400

2013-10-31

Rüdiger Landmann

Rebuild with publican 4.0.0

Revision 3-23

Fri Sep 27 2013

Dan Macpherson

Final version of documentation suite

Revision 3-22

Thu Sep 12 2013

Dan Macpherson

Minor changes

Revision 3-21

Wed Sep 11 2013

Dan Macpherson

Implemented QE feedback for BZ#1001363

Revision 3-20

Wed Sep 11 2013

Dan Macpherson

Added initial steps for Proxy Installation as per BZ#1001360

Revision 3-19

Wed Sep 11 2013

Dan Macpherson

Change to Product and BookID

Revision 3-18

Wed Sep 11 2013

Dan Macpherson

Updating requirements

Revision 3-17

Tue Sep 10 2013

Dan Macpherson

Revised Subtitle, Abstract and Preface for all Guides

Revision 3-16

Thu Aug 29 2013

Dan Macpherson

First implementation of QE Review feedback

Revision 3-15

Sun Jul 28 2013

Dan Macpherson

Removing references to Red Hat Network usage of Proxy as per Technical Review

Revision 3-14

Sun Jul 28 2013

Dan Macpherson

Second implementation of tech review feedback

Revision 3-13

Wed Jul 24 2013

Dan Macpherson

Corrections for BZ#987245

Revision 3-12

Tue Jul 23 2013

Dan Macpherson

First implementation of tech review feedback

Revision 3-11

Wed July 12 2013

Dan Macpherson

Final beta updates

Revision 3-10

Wed July 12 2013

Dan Macpherson

Beta documentation update

Revision 3-9

Wed July 12 2013

Dan Macpherson

Beta documentation update

Revision 3-8

Wed July 11 2013

Dan Macpherson

Beta documentation creation

Revision 3-7

Wed July 11 2013

Megan Lewis

Updated preface.

Updated section on base installation.

Revision 3-6

Wed Jun 26 2013

David O'Brien

Updated requirements.

Updated section on how Proxy Server works.

Updated graphics for section on topologies.

Major update to section on installing Proxy Server.

Add section on using cnames.

Revision 3-5

Wed Sept 19 2012

Dan Macpherson

Final packaging for 5.5

Revision 3-4

Wed Jul 4 2012

Athene Chan

Prepared for 5.5 release

Technical review changes incorporated

BZ#491007 Added Chapter on Upgrade Install

Revision 3-0

Wed Jul 4 2012

Athene Chan

Prepared for 5.5 release

Technical review changes incorporated

BZ#491007 Added Chapter on Upgrade Install

Revision 2-5

Thu Jan 5 2012

Lana Brindley

BZ#682996 - Installation chapter - Update instructions

BZ#705755 - Package manager chapter - Additional info

BZ#722193 - Requirements chapter - Fixed error

BZ#729617 - Installation chapter - Fixed error

BZ#729663 - Installation chapter - Added admonition

Revision 2-4

Mon Aug 15 2011

Lana Brindley

Folded z-stream release into y-stream

Revision 2-3

Wed Jun 22 2011

Lana Brindley

BZ#713527 - Added RHEL 6 references

Revision 2-2

Wed Jun 15 2011

Lana Brindley

Prepared for publication

Revision 2-1

Fri May 27 2011

Lana Brindley

Updates from translators

Revision 2-0

Fri May 6 2011

Lana Brindley

Prepared for translation

Revision 1-9

Wed April 27 2011

Lana Brindley

BZ#653844 - QE Review

Revision 1-8

Mon Feb 7 2011

Lana Brindley

BZ#646176 - Installation

Legal Notice

This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Proxy Installation Guide

Configuring, registering, and updating your Red Hat Enterprise Linux clients with Red Hat Satellite Proxy Server

John Ha

Lana Brindley

Daniel Macpherson

Athene Chan

David O'Brien

Megan Lewis

Preface

Chapter 1. Introduction

1.1. Red Hat Satellite Proxy Server

1.2. Architecture and Operations

1.3. Important Terms

Chapter 2. Requirements

2.1. Software Requirements

2.2. Hardware Requirements

2.3. Disk Space Requirements

2.4. Additional Requirements

Chapter 3. Installing Red Hat Satellite Proxy

3.1. Base Install

3.2. Red Hat Satellite Proxy Server Installation Process

3.3. Automating Satellite Proxy Server Installation

Chapter 4. Configuring Satellite Proxy to Use CNAME Records

4.1. Prerequisites

4.2. Adding CNAME Records to the Satellite Proxy Server Configuration

4.3. Generating and Using Multi-host SSL Certificates

Chapter 5. Upgrading a Red Hat Proxy Server Installation

5.1. Prerequisites

5.2. Upgrading Your Proxy Installation

Appendix A. Sample Satellite Proxy Server Configuration File

Appendix B. Revision History

Legal Notice

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links