Client Configuration Guide
Configuring, registering, and updating your Red Hat Enterprise Linux clients with Red Hat Satellite
Abstract
Chapter 1. Introduction
Chapter 2. Configuring Client Applications
Important
- Red Hat Update Agent - This is the update mechanism for Red Hat channels. Use of the Update Agent differs for certain operating systems:
- On Red Hat Enterprise Linux 5, 6, and 7 - As a
yum
plugin (yum-rhn-plugin
) - On Red Hat Enterprise Linux 3 and 4 - As a standalone application (
up2date
)
- Red Hat Network Registration Client (rhn_register) - This is the mechanism to register clients. By default,
rhn_register
registers to the main Red Hat Network servers. You need to reconfigure client systems to register to Red Hat Satellite or Red Hat Proxy.
Important
yum
command on Red Hat Enterprise Linux 5, 6, and 7 uses SSL for communication with remote repositories. Consequently, you should ensure that firewalls allow connections over port 443.
serverURL
from https
to http
in the /etc/sysconfig/rhn/up2date
file. Similarly, to use Red Hat Network's Monitoring feature and probes requiring the Red Hat Network Monitoring Daemon, client systems must allow connections on port 4545 (or port 22, if it is using sshd
instead).
2.1. Registering Clients with Red Hat Satellite Server
rhn_register
command to register a system with Red Hat Satellite. Ensure you replace the example host names and domain names with those that apply to your configuration.
Procedure 2.1. To Use rhn_register to Register a System with Red Hat Satellite:
- Change into the
/usr/share/rhn/
directory and download the SSL certificate to the client:# cd /usr/share/rhn/
# wget http://satellite.example.com/pub/RHN-ORG-TRUSTED-SSL-CERT
- Edit the
/etc/sysconfig/rhn/up2date
file and ensure that it contains the following entries:serverURL=https://satellite.example.com/XMLRPC noSSLServerURL=http://satellite.example.com/XMLRPC sslCACert=/usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT
- Use the
rhn_register
command to register the machine:# rhn_register
2.2. Using Activation Keys to Register Clients with Red Hat Satellite
Procedure 2.2. To Use Activation Keys to Register a System with Red Hat Satellite:
- Generate an activation key. See "Using Activation Keys" in the Red Hat Satellite Getting Started Guide.)
- Import custom GPG keys.
- Download and install the SSL Certificate RPM from the
/pub/
directory of the Red Hat Proxy or Red Hat Satellite. For example (update the URL to suit your environment):# rpm -Uvh http://satellite.example.com/pub/rhn-org-trusted-ssl-cert-1.0-1.noarch.rpm
- Register the system with the Red Hat Proxy or Red Hat Satellite:
# rhnreg_ks --activationkey mykey --serverUrl https://satellite.example.com/XMLRPC --sslCACert=/usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT
bootstrap.sh
) that Satellite generates. The bootstrap script, available for both Red Hat Satellite Server and Red Hat Proxy Server, is such a script. Script generation is discussed more in detail in 4.1.1. Using Red Hat Network Bootstrap to Register a System of the Getting Started Guide.
wget http://satellite.example.com/pub/bootstrap/bootstrap.sh
Important
2.3. Updating the Configuration Files Manually
serverURL
and noSSLServerURL
settings in the /etc/sysconfig/rhn/up2date
configuration file (as root). Replace the default Red Hat Network URL with the fully qualified domain name (FQDN) of the Proxy or Satellite. For example:
serverURL[comment]=Remote server URL serverURL=https://your_primary.your_domain.com/XMLRPC noSSLServerURL[comment]=Remote server URL without SSL noSSLServerURL=http://your_primary.your_domain.com/XMLRPC
Warning
httpProxy
setting in /etc/sysconfig/rhn/up2date
does not refer to the Red Hat Proxy. It is used to configure an optional HTTP proxy for the client. With a Red Hat Proxy in place, the httpProxy
setting must be blank (not set to any value).
2.4. Implementing Server Failover
Procedure 2.3. To Implement Server Failover:
- Ensure that you are running Red Hat Enterprise Linux 5, 6, or 7. For Red Hat Enterprise Linux 3 or 4, use the latest version of
up2date
. - Manually add the secondary servers to the
serverURL
andnoSSLServerURL
settings in the/etc/sysconfig/rhn/up2date
configuration file (as root). - Add the fully qualified domain names (FQDN) of Red Hat Proxy or Red Hat Satellite immediately after the primary server, separated by a semicolon (;). Your client will attempt to connect to these servers in the order provided here. Include as many servers as necessary. For example:
serverURL[comment]=Remote server URL serverURL=https://satellite.example.com/XMLRPC; https://your_secondary.your_domain.com/XMLRPC; noSSLServerURL[comment]=Remote server URL without SSL noSSLServerURL=http://satellite.example.com/XMLRPC; http://your_secondary.your_domain.com/XMLRPC;
2.5. Enabling Staging Content
- A faster installation than without staging content.
- The ability to spread out client requests to the Satellite server.
- Less time needed for the installation and upgrade of client packages.
Red Hat Enterprise Linux 5.6 or later, or Red Hat Enterprise Linux 6.1 or later, is required on the client.
/etc/sysconfig/rhn/up2date
in your text editor. Make the file includes the following lines:
stagingContent[comment]=Retrieve content of future actions in advance stagingContent=1 ... stagingContentWindow[comment]=How much forward we should look for future actions. In hours stagingContentWindow=24
stagingContent=0 stagingContentWindow=24
Chapter 3. SSL Infrastructure
Note
3.1. A Brief Introduction to SSL
Note
- Certificate Authority (CA) SSL private key and public certificate: only one set per organization generally generated. The public certificate is digitally signed by its private key. The public certificate is distributed to every system.
- Web server SSL private key and public certificate: one set per application server. The public certificate is digitally signed by both its private key and the CA SSL private key. It is often referred to as a Web server's key set; this is because there is an intermediary SSL certificate request that is generated. The details of what this is used for are not important to this discussion. All three are deployed to a Red Hat Satellite Server.
Important
3.2. The Red Hat Satellite SSL Maintenance Tool
rhn-ssl-tool
. This tool is available as part of the spacewalk-certs-tools
package. This package can be found within the software channels for the latest Red Hat Proxy Server and Red Hat Satellite Server (as well as the Red Hat Satellite Server ISO). The Red Hat Satellite SSL Tool enables organizations to generate their own Certificate Authority SSL key pair, as well as Web server SSL key sets (sometimes called key pairs).
Note
spacewalk-certs-tools
, which contains rhn-ssl-tool
, can be installed and run on any current Red Hat Enterprise Linux system with minimal requirements. This is offered as a convenience for administrators who want to manage their SSL infrastructure from their workstation or another system other than their Satellite or Proxy servers.
- When updating the Certificate Authority (CA) public certificate.
- When installing a Red Hat Proxy Server 3.6 or later that connects to the central Red Hat Satellite Servers as its top-level service. The hosted service, for security reasons, cannot be a repository for the CA SSL key and certificate, which is private to the organization.
- When reconfiguring the Satellite or Proxy infrastructure to use SSL where it previously did not.
- When adding multiple Red Hat Satellite Servers to the Red Hat Satellite infrastructure. Consult with a Red Hat representative for instructions regarding this.
- During installation of a Red Hat Satellite Server. All SSL settings are configured during the installation process. The SSL keys and certificate are built and deployed automatically.
- During installation of a Red Hat Proxy Server 3.6 or later if connected to a Red Hat Satellite Server 3.6 or later as its top-level service. The Red Hat Satellite Server contains all of the SSL information needed to configure, build and deploy the Red Hat Proxy Server's SSL keys and certificates.
/pub
directory of each server. This public certificate is used by the client systems to connect to the Red Hat Satellite Server. See Section 3.3, “Deploying the CA SSL Public Certificate to Clients” for more information.
3.2.1. Generating SSL Certificates
ssl-build
tree from an archive to the /root
directory and utilize the configuration tools provided within the Red Hat Satellite Server's website.
- Install the spacewalk-certs-tools package on a system within the organization, perhaps but not necessarily the Red Hat Satellite Server or Red Hat Proxy Server.
- Create a single Certificate Authority SSL key pair for the organization and install the resulting RPM or public certificate on all client systems. See Section 3.2.3, “Generating the Certificate Authority SSL Key Pair” for more information.
- Create a Web server SSL key set for each of the Proxy and Satellite servers to be deployed and install the resulting RPM files on the Red Hat Satellite servers.
- Restart the
httpd
service:# service httpd restart
- Back up the SSL build tree - consisting of the primary build directory and all subdirectories and files - to removable media, such as a CD or DVD. (Disk space requirements are insignificant.)
- Verify and then store that archive in a safe location, such as the one described for backups in the Additional Requirements sections of either the Proxy or Satellite installation guide.
- Record and secure the CA password for future use.
- Delete the build tree from the build system for security purposes, but only after the entire Satellite infrastructure is in place and configured.
Note
When additional Web server SSL key sets are needed, restore the build tree on a system running the Red Hat Satellite SSL Maintenance Tool and repeat steps 3 through 7.
3.2.2. Red Hat Satellite SSL Maintenance Tool Options
rhn-ssl-tool
for general help.--help:
rhn-ssl-tool
for Certificate Authority help.--gen-ca --help:
rhn-ssl-tool
for Web server help.--gen-server --help:
man rhn-ssl-tool
) for more information.
3.2.3. Generating the Certificate Authority SSL Key Pair
/root/ssl-build
(or /etc/sysconfig/rhn/ssl
for older Satellite and Proxy servers). To generate a CA SSL key pair, run the following command.
Important
# rhn-ssl-tool --gen-ca \ --password=MY_CA_PASSWORD \ --dir="/root/ssl-build" \ --set-state="North Carolina" \ --set-city="Raleigh" \ --set-org="Example Inc." \ --set-org-unit="SSL CA Unit"
RHN-ORG-PRIVATE-SSL-KEY:
the CA SSL private key.RHN-ORG-TRUSTED-SSL-CERT:
the CA SSL public certificate.rhn-org-trusted-ssl-cert-VER-REL.noarch.rpm:
the RPM prepared for distribution to client systems.This file contains the CA SSL public certificate (above) and installs it as/usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT
rhn-ca-openssl.cnf:
the SSL CA configuration file.latest.txt:
lists the latest versions of the relevant files.
3.2.4. Generating Web Server SSL Key Sets
--set-hostname
is therefore different for each server.
/root/ssl-build/MACHINE_NAME
. To generate a server certificate, run the following command.
Important
# rhn-ssl-tool --gen-server \ --password=MY_CA_PASSWORD \ --dir="/root/ssl-build" \ --set-state="MY_STATE" \ --set-city="MY_CITY" --set-org="Example Inc." \ --set-org-unit="MY_ORG_UNIT" \ --set-email="admin@example.com" \ --set-hostname="machinename.example.com"
server.key:
the Web server's SSL private server key.server.csr:
the Web server's SSL certificate request.server.crt:
the web server's SSL public certificate.rhn-org-httpd-ssl-key-pair-MACHINE_NAME-VER-REL.noarch.rpm:
the RPM prepared for distribution to Satellite and Proxy Servers. Its associatedsrc.rpm
file is also generated.This RPM file contains theserver.key,
server.csr,
andserver.crt
files. These files are installed in the following directories:/etc/httpd/conf/ssl.key/server.key
/etc/httpd/conf/ssl.csr/server.csr
/etc/httpd/conf/ssl.crt/server.crt
rhn-server-openssl.cnf:
the Web server's SSL configuration file.latest.txt:
lists the latest versions of the relevant files.
httpd
service.
# service httpd restart
3.3. Deploying the CA SSL Public Certificate to Clients
/var/www/html/pub/
directory of the Satellite or Proxy Server.
wget
or curl
commands to download the CA SSL public certificate to a client system.
Important
# curl -O http://proxy-or-sat.example.com/pub/RHN-ORG-TRUSTED-SSL-CERT
# wget http://proxy-or-sat.example.com/pub/RHN-ORG-TRUSTED-SSL-CERT
/pub
directory, you can use the rpm
command to install the package. For example:
# rpm -Uvh http://proxy-or-sat.example.com/pub/rhn-org-trusted-ssl-cert-VER-REL.noarch.rpm
3.4. Configuring Client Systems to Use Certificates
/usr/share/rhn
directory.
Chapter 4. Reporting Software Failures
4.1. Installing Software Failure Reporting Tools
Procedure 4.1. To Use the Software Failure Reporting Functionality:
- Log into your client system as the
root
user. - Install the spacewalk-abrt package on your client systems. This package installs the abrt package as a dependency.
# yum install spacewalk-abrt
Note
Neither the abrt nor spacewalk-abrt packages are available for Red Hat Enterprise Linux 5.
4.2. Using Software Failure Reporting Tools
- The configuration file for ABRT:
/etc/libreport/events.d/spacewalk.conf
- The
spacewalk-abrt
utility:/usr/bin/spacewalk-abrt
abrt
daemon to use the /usr/bin/spacewalk-abrt
utility to automatically report every software failure that occurs on the system to your Satellite server. This is a fully automated process and ordinarily does not require any human intervention.
4.3. Manually Reporting Software Failures
spacewalk-abrt
utility to manually report software failures to your Satellite server. The following procedure shows how to perform a manually send a software failure report.
Procedure 4.2. To manually report software failures
- Use the
abrt-cli list
parameter to display a list of existing failure reports.# abrt-cli list @0 Directory: /var/tmp/abrt/ccpp-2013-02-28-15:48:50-8820 count: 2 executable: /usr/bin/python2.7 package: python-2.7.3-13.fc16 time: Thu 28 Feb 2013 03:48:50 PM CET uid: 0 @1 Directory: /var/tmp/abrt/oops-2013-02-27-14:16:03-8107-1 count: 3 package: kernel time: Wed 27 Feb 2013 02:16:03 PM CET
- After you have identified the failure that you want to report, use the
--report
option to send the report to the Satellite server.# spacewalk-abrt --report /var/tmp/abrt/ccpp-2013-02-28-15:48:50-8820
- To manually report all of the software failures that have occurred on your system, use the
--sync
option:# spacewalk-abrt --sync
4.4. Creating Software Failures for Testing
kill
command to send a signal 11
argument (segmentation fault) to an example process:
# abrt-cli list # sleep 600 & [1] 17564 # kill -11 17564 # [1]+ Segmentation fault (core dumped) sleep 600 # # abrt-cli list @0 Directory: /var/spool/abrt/ccpp-2013-05-14-04:56:17-17564 count: 1 executable: /bin/sleep package: coreutils-8.4-19.el6 time: Tue 14 May 2013 04:56:17 EDT uid: 0 #
Appendix A. Revision History
Revision History | |||
---|---|---|---|
Revision 1.1-0 | Wed Feb 1 2017 | ||
|