Red Hat Satellite 6.2 Server Administration Guide

Red Hat Satellite DocumentationTeam

Red Hat Satellite 6.2Server Administration Guide

Administering a Red Hat Satellite 6 Server.Edition 1.0

Red Hat Satellite 6.2 Server Administration Guide

Administering a Red Hat Satellite 6 Server.Edition 1.0

Red Hat Satellite Documentation [email protected]

Legal NoticeCopyright © 2016 Red Hat.

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 versionof it, you must provide attribution to Red Hat, Inc. and provide a link to the original. Ifthe 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 toassert, 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, theInfinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United Statesand other countries.

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

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

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

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

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

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

All other trademarks are the property of their respective owners.

AbstractThe Red Hat Satellite 6 Server Administration Guide provides instructions on how toconfigure and administer a Red Hat Satellite 6 Server. Before continuing with thisworkflow you must have successfully installed a Red Hat Satellite 6 Server and anyrequired Capsule Servers.

http://creativecommons.org/licenses/by-sa/3.0/

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Table of ContentsChapter 1. Accessing Red Hat Satellite

1.1. Logging in to Red Hat Satellite1.2. Changing the Password in Red Hat Satellite

Chapter 2. Starting and Stopping Red Hat Satellite

Chapter 3. Configuring a Self-Registered Satellite3.1. Registering a Satellite to Itself

Chapter 4. Configuring Organizations, Locations and Life Cycle Environments4.1. Organizations4.2. Locations4.3. Life Cycle Environments4.4. Viewing Import History

Chapter 5. Users and Roles5.1. Creating and Managing Users5.2. Creating User Groups5.3. Creating and Managing Roles5.4. Granular Permission Filtering

Chapter 6. Backup and Disaster Recovery6.1. Backing up Red Hat Satellite Server6.2. Restoring Red Hat Satellite Server from a Backup

Chapter 7. Maintaining a Red Hat Satellite Server7.1. Logging and Reporting7.2. Enabling Debug Logging7.3. Collecting Information from Log Files7.4. Using Log Files in Support Cases7.5. Accessing Customer Portal Services from Red Hat Satellite7.6. Using Red Hat Insights with Satellite Server

Chapter 8. Monitoring Capsule Servers8.1. Viewing General Capsule Information8.2. Monitoring Services8.3. Monitoring Puppet

Chapter 9. Configuring External Authentication9.1. Using LDAP9.2. Using Identity Management9.3. Using Active Directory9.4. Configuring External User Groups9.5. External Authentication for Provisioned Hosts

Chapter 10. Customizing Satellite Server10.1. Adding Additional Plug-ins10.2. Using Foreman Hooks

223

5

66

1010141518

1919222225

282830

33333334353639

40404040

424246485253

585859

Table of Contents

1

Chapter 1. Accessing Red Hat Satellite

1.1. Logging in to Red Hat Satellite

After Red Hat Satellite has been installed and configured, use the web user interface to log into Satellite for further configuration.

Procedure 1.1. To Log in to Satellite:

1. Access the Satellite Server using a web browser pointed to the following address:

https://HOSTNAME/

To identify your host name, use the hostname command at the prompt:

# hostname

Important

An untrusted connection warning appears on your web browser when accessingSatellite for the first time. Accept the self-signed certificate and add the SatelliteURL as a security exception to override the settings. This procedure might differdepending on the browser being used.

Only do this if you are sure that the Satellite URL is a trusted source.

Figure 1.1. Untrusted Connection Warning

2. Enter the user name and password created during the configuration process. If a userwas not created during the configuration process, the default user name is admin.

Server Administration Guide

2

Result

When you have successfully logged in, you are taken to the Satellite dashboard. The dashboardcontains an overview of the Satellite and the hosts registered.

The main navigation tabs are as follows:

Table 1.1. Navigation Tabs

Navigation Tabs DescriptionDefault Organization

Clicking this tab changes the organization and location. If noorganization or location is selected, the default organization is AnyOrganization and the default location is Any Location. Use this tab tochange to different values.

Monitor Provides summary dashboards and reports.Content Provides content management tools. This includes Content Views,

Activation Keys, and Life Cycle Environments.Containers Provides container management tools.Hosts Provides host inventory and provisioning configuration tools.Configure Provides general configuration tools and data including Host Groups

and Puppet data.Infrastructure Provides tools on configuring how Satellite 6 interacts with the

environment.Red Hat Insights Provides Red Hat Insights management tools.Administer Provides advanced configuration for settings such as Users and RBAC,

as well as general settings.User Name Provides user administration where users can edit their personal

information.

Note

If you have forgotten the administrative password, log on to the Satellite command-lineinterface to reset the administration user and password:

# foreman-rake permissions:resetReset to user: admin, password: qwJxBptxb7Gfcjj5

This will reset the password of the default user admin to the one printed on thecommand line. Change this password upon logging in to prevent any security issues fromoccurring.

1.2. Changing the Password in Red Hat Satellite

These steps show how to change your password.

Procedure 1.2. To Change Your Red Hat Satellite Password:

1. Click your user name at the top right corner.

Chapter 1. Accessing Red Hat Satellite

3

2. Select My Account from the menu.

3. In the Password field, type in a new password.

4. In the Verify field, type in the new password again.

5. Click the Submit button to save your new password.


4

Chapter 2. Starting and Stopping Red Hat SatelliteSatellite provides the katello-service command to manage Satellite services from thecommand line. This is useful when upgrading Satellite or when creating a backup, see theRed Hat Satellite Installation Guide for details on these use cases.

After installing Satellite with the satellite-installer command, all Satellite services arestarted and enabled automatically. View the list of these services by executing:

# katello-service list

To see the status of running services, execute:

# katello-service status

To stop all Satellite services, execute:

# katello-service stop

To start all Satellite services, execute:

# katello-service start

To restart all Satellite services, execute:

# katello-service restart

Chapter 2. Starting and Stopping Red Hat Satellite

5

https://access.redhat.com/documentation/en/red-hat-satellite/6.2/single/installation-guide/

Chapter 3. Configuring a Self-Registered SatelliteA Red Hat Satellite server is normally registered to the Red Hat Customer Portal, then activatedas a Satellite Server and gets new content from the Red Hat Customer Portal. A self-registeredRed Hat Satellite 6 Server is registered to itself rather than the Red Hat Customer Portal.

Once a Red Hat Satellite 6 server is installed, there are several advantages to registering it as aclient to itself:

The same life cycle management procedures can be applied to the Satellite 6 server itselfthat have been applied to the rest of the managed estate.

By subscribing the Satellite 6 server to its own content views, it will receive the sameupdates on the same schedule as the rest of the managed hosts.

You can use virt-who by using a self-registered Satellite Server, but you can also install andconfigure virt-who without self-registration. For more information, see the Red Hat SatelliteVirtual Instances Guide.

There are also several limitations of a self-registered Satellite server:

A self-registered Satellite server cannot test package updates by using life-cycleenvironments. It is essential to make a full backup of a self-registered Satellite server beforedoing an upgrade to untested packages.

Not all puppet modules are supported by a self-registered Satellite server. When applyingpuppet modules to a self-registered Satellite server ensure that they will not create anunsupported configuration.

3.1. Registering a Satellite to Itself

Before a self-registered Satellite can be configured to get updates from itself, the Satellitesubscription must be added to the Satellite’s manifest. When the subscription is in themanifest, the appropriate Satellite repositories can be synchronized into the Satellite.

Procedure 3.1. To Register a Satellite to Itself:

1. If the Satellite is already registered to the Red Hat Customer Portal, unregister theSatellite from the Red Hat Customer Portal using the following commands:

# subscription-manager remove --all# subscription-manager unregister

2. The Satellite subscription on the Red Hat Customer Portal is now available and can betransferred into the Satellite's manifest. For further information on Manifests see theContent Management Guide.

Transfer the subscription to the Satellite's manifest:

a. Navigate to https://access.redhat.com and click SUBSCRIPTIONS on the mainmenu at the top of the page.

b. Scroll down to the Red Hat Subscription Management section, and click Satellite under Subscription Management Applications.

c. Select the required Satellite server by clicking its host name in the table.


6

https://access.redhat.com/documentation/en/red-hat-satellite/6.2/single/virtual-instances-guide

https://access.redhat.com

d. Click Attach a subscription and select subscriptions you want to attach.Specify the quantity for each subscription, and click Attach Selected.

3. Refresh the manifest on the Satellite Server:

a. Log in to the Satellite server.

b. Ensure that the correct organization is selected.

c. Click Content → Red Hat Subscriptions and then click Manage Manifest at theupper right of the page.

d. In the Subscription Manifest section, click Actions and under the Subscription Manifest subsection, click Refresh Manifest.

4. Enable Red Hat repositories using the Satellite web UI:

a. Click Content → Red Hat Repositories.

b. Navigate to the required repositories. Click each repository set from which youwant to select repositories and select the check box for each required repository.The repository is automatically enabled.

For Red Hat Enterprise Linux 6 the repositories that need to be enabled are:

Red Hat Enterprise Linux 6 Server RPMs x86_64 6Server

Red Hat Satellite 6.2 for RHEL 6 Server RPMs x86_64

rhel-6-server-satellite-6.2-rpms

Red Hat Software Collections RPMs for Red Hat Enterprise Linux 6 Serverx86_64 6Server

Red Hat Enterprise Linux 6 Server - Satellite Tools 6.2 RPMs x86_64 Repository

rhel-6-server-satellite-tools-6.2-rpms

For Red Hat Enterprise Linux 7 the repositories that need to be enabled are:

Red Hat Enterprise Linux 7 Server RPMs x86_64 6Server

Red Hat Satellite 6.2 for RHEL 7 Server RPMs x86_64

rhel-7-server-satellite-6.2-rpms

Red Hat Software Collections RPMs for Red Hat Enterprise Linux 7 Serverx86_64 6Server

Red Hat Enterprise Linux 7 Server - Satellite Tools 6.2 RPMs x86_64 Repository

rhel-7-server-satellite-tools-6.2-rpms

5. Synchronize the Satellite server:

a. Navigate to Content → Sync Status. Based on the subscriptions andrepositories enabled, the list of product repositories available for synchronizationis displayed.

b. Click the arrow next to the product name to see available content.

c. Select the content you want to synchronize.

Chapter 3. Configuring a Self-Registered Satellite

7

d. Click Synchronize Now to starting synchronizing. The status of thesynchronization process will appear in the Result column. If synchronization issuccessful, Sync complete will appear in the Result column. If synchronizationfailed, Error syncing will appear.

Note

Content synchronization can take a long time. The length of time requireddepends on the speed of disk drives, network connection speed, and the amountof content selected for synchronization.

6. Optionally, create a content view to represent the Satellite server. This will allow theSatellite to follow the same life cycle management procedures as the rest of the contenton the server. For further information about content views see the Using Content Viewschapter in the Red Hat Satellite 6.2 Host Configuration Guide.

a. To create a content view:

i. Log into the web UI as a Satellite administrator.

ii. Click Content → Content Views.

iii. Click Create New View.

iv. Specify the Name of the content view. The Label field is automaticallypopulated when the Name field is filled out. Optionally, provide adescription of the content view.

v. Click Save.

b. Edit the content view to add the Red Hat Enterprise Linux server and Satelliterepositories:

i. Click Content → Content Views and choose the Content View to addrepositories to.

ii. Click Yum Content and select Repositories from the drop-down menu.From the submenu, click Add.

iii. Select the required repositories to add and click Add Repositories. Therequired repositories for a self-registered Satellite are all the repositoriesfor the Satellite itself, any supporting repositories and the repository forthe Base OS. The repositories required for a self-registered Satellite arelisted in Step 4 of this procedure.

7. Download and install the required certificates by running:

# rpm -Uvh /var/www/html/pub/katello-ca-consumer-latest.noarch.rpm

8. Register the Satellite Server, and attach the appropriate entitlements. When registeringthe Satellite Server, you must specify the organization to which the server belongs, andthe life cycle environment. To confirm the available organizations and life cycleenvironments, in the Satellite web UI navigate to Hosts → New host and select thedrop-down list for these values.


8

https://access.redhat.com/documentation/en/red-hat-satellite/6.2/paged/host-configuration-guide/chapter-2-using-content-views

# subscription-manager register --org=organization --environment=environment

Example 3.1.

# subscription-manager register --org=ExampleCompany --environment=Library

You will be prompted for your Red Hat Satellite user name and password. The SatelliteServer administrator can configure new users. See Chapter 5, Users and Roles for moreinformation.

9. Find the pool IDs for the Satellite and for Red Hat Enterprise Linux by running thefollowing command:

# subscription-manager list --available

10. Attach the entitlements by running the following command:

# subscription-manager attach --pool Red_Hat_Satellite_Pool_ID --pool Red_Hat_Enterprise_Linux_ID

A content host has now been created for the Satellite server inside of the Satelliteserver.

11. Enable the repositories required for the Satellite server by running the followingcommand:

# subscription-manager repos --enable=repository-to-be-enabled

See Step 4 of this procedure for the list of repositories that need to be enabled.

12. Install the Katello Agent package to allow errata management and package installationthrough the Satellite web UI. The katello-agent package depends on the gofer packagethat provides the goferd service. The goferd service must be enabled so that theRed Hat Satellite Server or Capsule Server can provide information about errata that areapplicable for content hosts.

To install the katello-agent run the following command:

# yum install katello-agent

The goferd service is started and enabled automatically after successful installation ofkatello-agent.

Chapter 3. Configuring a Self-Registered Satellite

9

Chapter 4. Configuring Organizations, Locations andLife Cycle EnvironmentsRed Hat Satellite 6 takes a consolidated approach to Organization and Location management.System administrators define multiple Organizations and multiple Locations in a single SatelliteServer. For example, a company might have three Organizations (Finance, Marketing, andSales) across three countries (United States, United Kingdom, and Japan). In this example, theSatellite Server manages all Organizations across all geographical Locations, creating ninedistinct contexts for managing systems. In addition, users can define specific locations and nestthem to create a hierarchy. For example, Satellite administrators might divide the United Statesinto specific cities, such as Boston, Phoenix, or San Francisco.

Figure 4.1. Example Topology for Red Hat Satellite 6

The main Satellite Server retains the management function, while the content andconfiguration is synchronized between the main Satellite Server and a Satellite Capsule Serverassigned to certain locations.

4.1. Organizations

Organizations divide hosts into logical groups based on ownership, purpose, content, securitylevel, or other divisions.

Multiple organizations can be viewed, created, and managed within the web UI. Software andhost entitlements can be allocated across many organizations, and access to thoseorganizations controlled.


10

Each organization must be created and used by a single Red Hat customer account, howevereach account can manage multiple organizations. Subscription manifests can only be importedinto a single organization and Satellite will not upload a certificate that has already beenuploaded into a different organization.

By default, Red Hat Satellite will have one organization already created, called "DefaultOrganization", which can be modified to suit your own installation, or deleted. The organizationname has a corresponding label Default_Organization.

Important

If a new user is not assigned a default organization their access will be limited. To grantsystems rights to users, assign them to a default organization and have them log out andlog back in again.

4.1.1. Creating an Organization

These steps show how to create a new organization.

Procedure 4.1. To Create an Organization:

1. Navigate to Administer → Organizations.

2. Click New Organization.

3. In the Name field, insert the name of the new organization.

4. In the Label field, insert the label of the new organization.

5. In the Description field, insert a description of the new organization.

6. Click Submit.

7. Select the hosts to assign to the new organization.

Click Assign All to assign all hosts with no organization to the new organization.

Click Manually Assign to manually select and assign the hosts with no organization.

Click Proceed to Edit to skip assigning hosts.

8. Specify the configuration details of the organization such as Capsule Servers, subnets orcompute resources. You can modify these settings later as described in Section 4.1.4,“Editing an Organization”.

9. Click Submit.

4.1.2. Creating an Organization Debug Certificate

These steps show how to generate and download a debug certificate for an organization. Debugcertificates enable you to browse all content from an organization's repositories and arerequired for exporting provisioning templates.

Procedure 4.2. To Create a New Organization Debug Certificate:


Chapter 4. Configuring Organizations, Locations and Life Cycle Environments

11

2. Select an organization for which you want to generate a debug certificate.

3. Click Generate and Download. This generates a debug certificate.

4. Save the certificate file in a secure location.

Note

Debug Certificates are automatically generated for provisioning template downloads ifthey do not already exist in the organization for which they are being downloaded.

4.1.3. Using an Organization Debug Certificate

You can view an organization's repository content using a browser or using the API if you have adebug certificate for that organization. The previous section describes creating anddownloading the certificate which is in the X.509 format. To use a browser you must firstconvert the X.509 certificate to a format your browser supports and then import the certificate.The curl utility only requires extracting the certificate and key into separate files.

Procedure 4.3. To Use an Organization Debug Certificate in Firefox:

1. Create and download an organization certificate as described in Procedure 4.2, “ToCreate a New Organization Debug Certificate:”.

2. Open the X.509 certificate, for example, for the default organization:

$ vi 'Default Organization-key-cert.pem'

3. Copy the contents of the file from -----BEGIN RSA PRIVATE KEY----- to -----END RSA PRIVATE KEY----- inclusive, into a file called key.pem.

4. Copy the contents of the file from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- inclusive, into a file called cert.pem.

5. Enter a command as follows to create a PKCS12 format certificate and enter a passwordor phrase when prompted:

$ openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -export -in cert.pem -inkey key.pem -out organization_label.pfx -name 'organization_name'Enter Export Password:Verifying - Enter Export Password:

6. Using the preferences tab, import the resulting pfx file into your browser: Navigate toEdit → Preferences → Advanced Tab. Select View Certificates in the Certificatesview to open the Certificate Manager. On the Your Certificates tab, click Import andselect the pfx file to load. You will be prompted for the password or phrase used whenmaking the certificate.

7. Enter a URL in the following format into your browser's address bar to begin browsingfor repositories:

http://satellite.example.com/pulp/repos/organization_label


12

Pulp uses the organization label so the URL must use the organization label too.

Procedure 4.4. To Use an Organization Debug Certificate with curl:

1. Create and download an organization certificate as described in Procedure 4.2, “ToCreate a New Organization Debug Certificate:”.

2. Open the X.509 certificate, for example, for the default organization:

$ vi 'Default Organization-key-cert.pem'

3. Copy the contents of the file from -----BEGIN RSA PRIVATE KEY----- to -----END RSA PRIVATE KEY----- inclusive, into a file called key.pem.

4. Copy the contents of the file from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- inclusive, into a file called cert.pem.

5. Find a valid URL for a repository. You can use the browsing method described in theprevious procedure or use the web UI. For example, using the web UI, navigate toContent → Products and select a Product by name. On the Repositories tab, select arepository by name and look for the Published At entry.

6. To use curl to access a repository, use a command as follows:

$ curl -k --cert cert.pem --key key.pem http://satellite.example.com/pulp/repos/Default_Organization/Library/content/dist/rhel/server/7/7Server/x86_64/sat-tools/6.2/os/

Ensure the paths to cert.pem and key.pem are the correct absolute paths otherwise thecommand will fail silently.

4.1.4. Editing an Organization

Procedure 4.5. To Edit an Organization:


2. Click the name of the organization to be edited.

3. Select the resource to edit from the list on the left.

4. Click the name of the desired items to add them to the Selected Items list.

5. Click Submit.

Note

Users with administrator privileges are not listed under the Users tab when editing anorganization.

4.1.5. Removing an Organization

Procedure 4.6. To Remove an Organization:


13


2. Select Delete from the drop-down menu to the right of the name of the organizationyou want to remove.

3. An alert box appears:

Delete Organization?

4. Click OK to delete the organization.

4.2. Locations

Locations divide organizations into logical groups based on geographical location. Each locationis created and used by a single Red Hat customer account, although each account can managemultiple locations and organizations.

The Red Hat Satellite installation process creates one location, called Default Location, whichyou can modify to suit your own needs. If a new user is not assigned a default location theiraccess will be limited. To grant system rights to users, assign a default location and have themlog out and log in again.

Important

You cannot delete the default location, but you can rename it to suit your needs. Satellitereturns an error message if you try to delete the default location using either the web UIor the command line.

4.2.1. Creating a Location

These steps show how to create a location.

Procedure 4.7. To Create a Location:

1. Navigate to Administer → Locations.

2. Click New Location.

3. Insert the name of the new location in the Name field. If you want to create a nestedlocation, select a Parent location from the drop-down menu. Optionally, specify a Description of the location. Click Submit.

4. Select the hosts to assign to the new location.

Click Assign All to assign all hosts with no location to the new location.

Click Manually Assign to manually select and assign the hosts with no location.

Click Proceed to Edit to skip assigning hosts.

5. Specify the configuration details of the location such as Capsule Servers, subnets orcompute resources. You can modify these settings later as described in Section 4.2.2,“Editing a Location”.

6. Click Submit.


14

4.2.2. Editing a Location

Procedure 4.8. To Edit a Location:


2. Click the name of the location to be edited.

3. Select the resource to edit from the list on the left.

4. Click the name of the desired items to add them to the Selected Items list.

5. Click Submit.

4.2.3. Removing a Location

These steps show how to remove an existing location.

Procedure 4.9. To Remove a Location:


2. Select Delete from the drop-down menu to the right of the name of the location youwant to remove.

An alert box appears:

Delete Location?

3. Click OK.

4.3. Life Cycle Environments

Application life cycles are divided into life cycle environments, which represent each stage ofthe application life cycle. Life cycle environments are linked to form an environment path. Youcan promote content along the environment path to the next life cycle environment whenrequired. For example, if development ends on a particular version of an application, you canpromote this version to the testing environment and start development on the next version.


15

Figure 4.2. An Environment Path Containing Four Environments

4.3.1. Creating Life Cycle Environments

This procedure describes how to create a life cycle environment in Red Hat Satellite.

Procedure 4.10. To Create a Life Cycle Environment:

1. Select an organization from the menu in the top left hand corner.

2. Click Content → Life Cycle Environments and then click New Environment Path.

3. Insert a name and a label (automatically fills in the Name field input) for the life cycleenvironment. The Description field is optional.

4. Click Save to create the environment.

4.3.2. Promoting Content Views

After you have created a content view and an environment path consisting of two or more lifecycle environments, you can promote the content view from one environment to the next asrequired. This means that the most recent version of the content view that exists in a specifiedenvironment will be promoted, or copied, to the next environment in the life cycle environmentpath.

You can promote a content view to any environment where that version does not exist. Thesystem automatically suggests the next environment in the life cycle environment path, butyou can override this and promote to a different environment if required.

Procedure 4.11. To Promote a Content View:

1. On the main menu, click Content → Content Views.

2. In the Name column, click the name of the content view that you want to promote.

3. On the Versions tab, identify the latest version, and click Promote.

4. Identify the promotion path where you want to promote the content view, select theappropriate life cycle environment, and click Promote Version.


16

5. After the promotion has completed, the Versions tab updates to display the new statusof your content views.

4.3.3. Removing Life Cycle Environments From Satellite Server

This procedure describes how to remove a life cycle environment from Red Hat Satellite.

Procedure 4.12. To Remove a Life Cycle Environment:

1. On the main menu, click Content → Life Cycle Environments.

2. Click the name of the life cycle environment that you want to remove, and then click Remove Environment.

3. In the confirmation dialog box, click Remove to remove the environment.

Note

You can only delete the latest environment in an environment path. For example, if threeenvironments exist in the order Library, Dev, and Prod, you need to delete Prod beforeyou can delete Dev. You cannot delete the Library environment.

4.3.4. Removing Life Cycle Environments from Capsule Server

There are multiple reasons to remove life cycle environments from Capsule Server. Forexample:

When life cycle environments are no longer relevant to the host systems

When life cycle environments have been incorrectly added to Capsule Server

Procedure 4.13. To remove a life cycle environment from Capsule Server:

1. Log in to the Satellite Server CLI as the root user.

2. Choose the desired Capsule Server from the list and take note of its id:

# hammer capsule list

The Capsule Server's details can be verified using the command:

# hammer capsule info --id capsule_id_number

3. Verify the list of life cycle environments currently attached to the Capsule Server andtake note of the environment id:

# hammer capsule content lifecycle-environments --id capsule_id_number

4. Remove the life cycle environment from Capsule Server:

# hammer capsule content remove-lifecycle-environment --id capsule_id_number --environment-id environment_id


17

Where:

capsule_id_number is Capsule Server's identification number.

environment_id is the life cycle environment's identification number.

Repeat this step for every life cycle environment to be removed from the CapsuleServer.

5. Synchronize the content from the Satellite Server's environment to Capsule Server:

# hammer capsule content synchronize --id capsule_id_number

4.4. Viewing Import History

These steps show how to view an import history in Red Hat Satellite.

Procedure 4.14. To View an Import History:

1. Click Content → Red Hat Subscriptions.

2. Click the Manage Manifest button.

3. Click the Import History tab.


18

Chapter 5. Users and RolesA User defines a set of details for individuals using the system. Users can be associated withorganizations and environments, so that when they create new entities, the default settings areautomatically used. Users can also have one or more roles attached, which grants them rightsto view and manage organizations and environments. See Section 5.1, “Creating and ManagingUsers” for more information on working with users.

You can manage permissions of several users at once by organizing them into user groups. Usergroups themselves can be further grouped to create a hierarchy of permissions. SeeSection 5.2, “Creating User Groups” for more information on creating user groups.

Roles define a set of permissions and access levels. Each role contains one on more permissionfilters that specify the actions allowed for the role. Actions are grouped according to theResource type. Once a role has been created, users and user groups can be associated withthat role. This way, you can assign the same set of permissions to large groups of users.Red Hat Satellite provides a set of predefined roles and also enables creating custom roles andpermission filters as described in Section 5.3, “Creating and Managing Roles”.

5.1. Creating and Managing Users

For the administrator, Red Hat Satellite provides the ability to create, modify, and removeusers. Also, it is possible to configure access permissions through assigning roles to users.

5.1.1. Creating a User

The following steps show how to create a user:

Procedure 5.1. To Create a User:

1. Navigate to Administer → Users and then click New User.

2. On the User tab, enter the required details.

3. On the Locations tab, select the required locations for this user.

4. On the Organizations tab, select organizations accessible to this user. The currentactive organization is selected by default. If you specify multiple organizations, you canselect the default organization for user login from the drop-down list.

5. On the Roles tab, select the required roles for this user. Active roles are displayed inthe right panel.

6. Click Submit to create the user.

5.1.2. Editing a User

The following steps show how to edit details of an existing user:

Procedure 5.2. To Edit an Existing User:

1. Navigate to Administer → Users.

2. Click the user name of the user to be altered. General information about the user willappear on the right.

Chapter 5. Users and Roles

19

3. In the User tab, you can modify the user's user name, first name, surname, emailaddress, default location, default organization, language, and password.

4. In the Locations tab, you can modify the user's assigned locations.

5. In the Organizations tab, you can modify the user's assigned organizations.

6. In the Roles tab, you can modify the user's assigned roles.

7. Click Save to save your changes.

5.1.3. Assigning Roles to a User

By default, a new user has no roles assigned. The following procedure describes how to assignone or more roles to a user. You can select from predefined roles, or define a custom role asdescribed in Section 5.3.1, “Creating a Role”. You can apply a similar procedure to user groups.

Procedure 5.3. To Assign a Role to a User:

1. Navigate to Administer → Users. If a user account created is not listed, check that youare currently viewing the right organization. To list all users in Satellite, click Default Organization and then Any Organization. The organization view is changed to Any Context.

2. Click the user name of the user that you want to modify. General information about theuser appears on the right.

3. Click the Locations tab, and select a location if none is assigned.

4. Click the Organizations tab, and check that an organization is assigned.

5. Click the Roles tab to display the list of available role assignments.

6. Select role you want to assign to the user in the Roles list. The list contains thepredefined roles, as well as any custom roles, see Table 5.1, “Predefined Roles Availablein Red Hat Satellite”. Alternatively, select the Administrator check box to assign allavailable permissions to the selected user.

7. Click Save.

To view the roles assigned to any user, click the Roles tab; the assigned roles are listed under Selected items. To remove a role, from the Selected items, click a role name and it will beremoved.

5.1.4. Configuring Email Notifications

Email notification is a per-user setting, with no email notifications enabled by default. If youwant email notifications sent to a group's email address, instead of an individual's emailaddress, create a user account with the group's email address and minimal Satellitepermissions, then subscribe the user account to the desired notification types.

For general information on configuring outgoing Satellite emails, see the Red Hat SatelliteInstallation Guide.


20

https://access.redhat.com/documentation/en/red-hat-satellite/6.2/single/installation-guide/#configuring_satellite_outgoing_emails

Note

To receive email notifications, the user account must have a valid email address. Toconfirm the email address associated with a user account, navigate to Administer →Users and check the Email address field.

Procedure 5.4. To Configure Email Notifications:

1. Navigate to Administer → Users.

2. Click the Username of the user you want to edit.

3. Click the Email Preferences tab and select Mail enabled to enable email notifications.

4. Select the notifications you want the user to receive.

Audit summary is a summary of all activity audited by the Satellite Server. Toenable these notifications, select the frequency of emails from the drop-down listthat offers Daily, Weekly, or Monthly updates. Enter a query in the associatedquery field to narrow the audit activity included.

Host built is a notification sent when a host is built. To enable these notifications,select Subscribe from the drop-down menu.

Host errata advisory is a summary of applicable and installable errata for hostsmanaged by the user. To enable these notifications, select the frequency of emailsfrom the drop-down list that offers Daily, Weekly, or Monthly updates.

OpenSCAP policy summary is a summary of OpenSCAP policy reports and theirresults. To enable these notifications, select the frequency of emails from the drop-down list that offers Daily, Weekly, or Monthly updates.

Promote errata is a notification sent only after a content view promotion. Itcontains a summary of errata applicable and installable to hosts registered to thepromoted content view. This allows you to monitor what updates have been appliedto which hosts. To enable these notifications, select Subscribe from the drop-downmenu.

Puppet error state is a notification sent after a host reports an error related toPuppet. To enable these notifications, select Subscribe from the drop-down menu.

Puppet summary is a summary of Puppet reports. To enable these notifications,select the frequency of emails from the drop-down list that offers Daily, Weekly, orMonthly updates.

Sync errata is a notification sent only after synchronizing a repository. It contains asummary of new errata introduced by the synchronization. To enable thesenotifications, select Subscribe from the drop-down menu.

5. Click Submit.

Testing email delivery

To test email delivery to the email address associated with a user account, open the Satelliteweb UI, navigate to Administer → Users, click on the user name, click the Email Preferences


21

tab and click Test email. A test email message is then sent immediately to the user's emailaddress. If it does not arrive, first verify the user's email address, then the Satellite Server'semail configuration, after which you may need to examine firewall and mail server logs.

5.1.5. Removing a User

The following procedure describes how to remove an existing user.

Procedure 5.5. To Remove a User:

1. On the main menu, click Administer → Users to open the Users page.

2. Click the Delete link to the right of the user name you want to delete.

3. In the alert box, click OK to delete the user.

5.2. Creating User Groups

With Red Hat Satellite, you can assign permissions to groups of users. You can also create usergroups as collections of other user groups. If using an external authentication source, you canmap Satellite user groups to external user groups as described in Section 9.4, “ConfiguringExternal User Groups”.

User groups are defined in an organizational context, meaning that you must select anorganization before you can access user groups.

Procedure 5.6. To Create a User Group:

1. Navigate to Administer → User groups to view the user groups on your Satellite.

2. Click New User Group.

3. On the User group tab, specify the name of the new user group and select groupmembers from the list of users. To include a previously-created user group, select thecheck box next to the name of the group to be added.

4. On the Roles tab, select the roles you want to assign to the user group. Alternatively,select the Administrator check box to assign all available permissions.

5. Click Submit to create the user group.

5.3. Creating and Managing Roles

Red Hat Satellite provides a set of predefined roles with permissions sufficient for standardtasks, as listed in Table 5.1, “Predefined Roles Available in Red Hat Satellite”. It is also possibleto configure custom roles, and assign one or more permission filters to them. Permission filtersdefine the actions allowed for a certain resource type. Certain Satellite plug-ins create rolesautomatically.

Table 5.1. Predefined Roles Available in Red Hat Satellite

Role Permissions Provided by Role Anonymous The set of permissions that every user is granted, irrespective of any

other roles.

[a]


22

Discoverymanager

View, provision, edit, and destroy discovered hosts and managediscovery rules.

Discovery reader View hosts and discovery rules.Boot disk access Download the boot disk.Red Hat AccessLogs

View the log viewer and the logs.

Manager A most extensive set of permissions, the majority of actions from eachresource type is enabled.

Edit partitiontables

View, create, edit and destroy partition tables.

View hosts View hosts.Edit hosts View, create, edit, destroy, and build hosts.Viewer A passive role that provides the ability to view the configuration of

every element of the Satellite structure, logs, and statistics.Site manager A restrained version of the Manager role.Tasks manager View and edit Satellite tasks.Tasks reader View Satellite tasks.

Role Permissions Provided by Role

5.3.1. Creating a Role

The following steps show how to create a role.

Procedure 5.7. To Create a Role:

1. Navigate to Administer → Roles.

2. Click New Role.

3. Provide a Name for the role.

4. Click Submit to save your new role.

To serve its purpose, a role must contain permissions. After creating a role, proceed toSection 5.3.2, “Adding Permissions to a Role”.

Note

Cloning an existing role is a time-saving method of role creation, especially if you want tocreate a new role that is a variation of an existing permission set. To clone a role,navigate to Administer → Roles and select Clone from the drop-down list to the right ofthe role to be copied. Select the name for the new role and alter the permissions asneeded.

5.3.2. Adding Permissions to a Role

The following steps show how to add permissions to a role.

Procedure 5.8. To Add Permissions to a Role:

[a] The exact set of allowed actions associated with predefined roles can be viewed by the privilegeduser as described in Section 5.3.3, “Viewing Permissions of a Role”.


23


2. Select Add Filter from the drop-down list to the right of the required role.

3. Select the Resource type from the drop-down list. The (Miscellaneous) group gatherspermissions that are not associated with any resource group.

4. Click the permissions you want to select from the Permission list.

5. Select whether the permission is Unlimited. This option is selected by default, whichmeans that the permission is applied on all resources of the selected type. When youdisable the Unlimited check box, the Search field activates. In this field you can specifyfurther filtering with use of the Red Hat Satellite 6 search syntax. See Section 5.4,“Granular Permission Filtering” for details.

6. Click Next.

7. Click Submit to save changes.

5.3.3. Viewing Permissions of a Role

The following procedure shows how to view permissions assigned to an existing role.

Procedure 5.9. To View Permissions Associated with a Role:


2. Click Filters to the right of the required role to get to the Filters page.

The Filters page contains a table of permissions assigned to a role grouped by the resourcetype. It is also possible to generate a complete table of permissions and actions that you canuse on your Satellite system. See Procedure 5.10, “To Create a Complete Permission Table:” forinstructions.

Procedure 5.10. To Create a Complete Permission Table:

1. Ensure that the required packages are installed. Execute the following command on theSatellite Server:

# yum install tfm-rubygem-foreman*

2. Start the Satellite console with the following command:

# foreman-rake console

Insert the following code into the console:

f = File.open('/tmp/table.html', 'w')

result = Foreman::AccessControl.permissions.sort {|a,b| a.security_block <=> b.security_block}.collect do |p| actions = p.actions.collect { |a| "<li>#{a}</li>" } "<tr><td>#{p.name}</td><td><ul>#{actions.join('')}</ul></td><td>#{p.resource_type}</td></tr>"end.join("\n")

f.write(result)


24

The above syntax creates a table of permissions and saves it to the /tmp/table.htmlfile.

3. Press Ctrl+D to exit the Satellite console. Insert the following text at the first line of /tmp/table.html:

<table border="1"><tr><td>Permission name</td><td>Actions</td><td>Resource type</td></tr>

Append the following text at the end of /tmp/table.html:

</table>

4. Open /tmp/table.html in a web browser to view the table.

5.3.4. Removing a Role

The following steps show how to remove an existing role.

Procedure 5.11. To Remove a Role:


2. Select Delete from the drop-down list to the right of the role to be deleted.

3. In an alert box that appears, click OK to delete the role.

5.4. Granular Permission Filtering

As mentioned in Section 5.3.2, “Adding Permissions to a Role”, Red Hat Satellite provides theability to limit the configured user permissions to selected instances of a resource type. Thesegranular filters are queries to the Satellite database and are supported by the majority ofresource types.

To create a granular filter, specify a query in the Search field on the Edit Filter page.Deselect the Unlimited check box for the field to be active. Queries have the following form:

field_name operator value

Where:

field_name marks the field to be queried. The range of available field names depends on theresource type. For example, the Partition Table resource type offers family, layout, and nameas query parameters.

operator specifies the type of comparison between field_name and value. See Table 5.2,“Supported Operators for Granular Search” for an overview of applicable operators.

value is the value used for filtering. This can be for example a name of an organization. Twotypes of wildcard characters are supported: underscore (_) provides single characterreplacement, while percent sign (%) replaces zero or more characters.


25

For most resource types, the Search field provides a drop-down list suggesting the availableparameters. This list appears after placing the cursor in the search field. For many resourcetypes, it is also possible to combine the queries by using the and and or operators.

Table 5.2. Supported Operators for Granular Search

Operator Description= Is equal to. An equality comparison that is case-sensitive for text fields.!= Is not equal to. An inversion of the = operator.~ Like. A case-insensitive occurrence search for text fields.!~ Not like. An inversion of the ~ operator.^ In. A case-sensitive search for text fields containing a certain string.!^ Not in. An inversion of the ^ operator.>, >= Greater than, greater than or equal to. Supported for numerical fields

only.<, <= Less than, less than or equal to. Supported for numerical fields only.

For example, the following query applies any permissions specified for the Host resource typeonly to hosts in the group named host-editors.

hostgroup = host-editors

You can also limit permissions to a selected environment. To do so, specify the environmentname in the Search field, for example:

Dev

As an administrator, you can allow selected users to make changes in a certain part of theenvironment path. The above filter allows you to work with content while it is in thedevelopment stage of the application life cycle, but the content becomes inaccessible once ispushed to production.

Note

Satellite does not apply search conditions to create actions. For example, limiting thecreate_locations action with name = "Default Location" expression in the search field willnot prevent the user from assigning a custom name to the newly created location.

You can limit user permissions to a certain organization or location with use of the permissionfilter. However, resource types provide a GUI alternative in form of Locations and Organizations tabs. On these tabs, you can select from the list of available organizations andlocations. See Example 5.1, “Creating an Organization-specific Manager Role”.

Example 5.1. Creating an Organization-specific Manager Role

This example shows how to create a manager role restricted to a single organization namedorg-1.


2. Clone the existing Manager role. Select Clone from the drop-down list next to the Filters button. You are then prompted to insert a name for the cloned role, for


26

example org-1 Manager.

3. Click Filters next to org-1 Manager to view the filters associated with the role. Allfilters are marked as unlimited.

4. For each filter, click Edit.

5. If the filter contains the Organizations tab, navigate to it. Otherwise it is a globalsetting that cannot be limited.

6. On the Organizations tab, select org-1. Click Submit.

7. The restricted filters are no longer marked as unlimited. Users assigned with the org-1Manager role can now perform management tasks only in the selected organization.


27

Chapter 6. Backup and Disaster RecoveryThis chapter describes the minimum and typical backup and restore procedures required toensure continuity of your Red Hat Satellite deployment and associated data in the event of adisaster. If your deployment uses custom configurations you should take these into accountwhen planning your backup and disaster recovery policy.

6.1. Backing up Red Hat Satellite Server

This section describes the process required to create a complete backup of your SatelliteServer and all associated data. Backing up to a separate location is recommend. Backing up toa separate storage device on a separate system is highly recommend. As no Satellite serviceswill be available during the backup, the backup can be scheduled for a quiet time (for example,using cron).

Note

When planning a scheduled backup, ensure that no other tasks are scheduled by otheradministrators for the same time. This is particularly important when administrators areworking in different locations and time zones.

Red Hat Satellite 6.2 adds options to the katello-backup script to perform incrementalbackups, on-line backups, and intermediate backups excluding Pulp content. To see the usagestatement, enter a command as follows:

# katello-backup --help

Procedure 6.1. To Back up Your Red Hat Satellite Server:

1. This procedure performs a full off-line backup. Ensure your backup location has enoughdisk space to contain a copy of all of the following directories:

/etc/

/var/lib/pulp/

/var/lib/mongodb/

/var/lib/pgsql/

This can be a considerable amount of space so plan accordingly.

2. Request other Satellite Server users to save any changes and warn them that for theduration of the backup, no Satellite services will be available. Check that no other tasksare scheduled for the same time as the backup.

3. Run the backup script:

# katello-backup backup_directory

The katello-backup script stops all services which could impact the backup, performsthe backup, then restarts the required services. If the target directory does not existwhen trying to create a backup file the script will create it.


28

This process can take a long time to complete, due to the amount of data to copy.

Procedure 6.2. To Perform a Backup without Pulp Content:

This procedure performs an off-line backup but excludes the contents of the Pulp directory. Thisbackup is useful for debugging purposes and is only intended to provide access to configurationfiles without spending time backing up the Pulp database. You cannot restore from a directorythat does not contain Pulp content.

Ensure your backup location has enough disk space to contain a copy of all of the followingdirectories:

/etc/

/var/lib/mongodb/

/var/lib/pgsql/



# katello-backup --skip-pulp-content backup_directory

The katello-backup script stops all services which could impact the backup, performsthe backup, then restarts the required services.

Procedure 6.3. To Perform an Incremental Backup:

This procedure performs an off-line backup of any changes since a previous backup. Use a fullbackup as a reference to make the first incremental backup of a sequence. Ensure your backuplocation has enough disk space to contain a copy of all changes in the following directories:

/etc/

/var/lib/pulp/

/var/lib/mongodb/

/var/lib/pgsql/



# katello-backup new_backup_directory --incremental previous_backup_directory

The katello-backup script stops all services which could impact the backup, performsthe backup, then restarts the required services. It is possible to make incrementalbackups using a backup older than the previous backup as a starting point, but with acorresponding increase in time to make the backup. Keep at least the last known goodfull backup and a complete sequence of incremental backups to restore from.

Chapter 6. Backup and Disaster Recovery

29

Procedure 6.4. To Perform an Online Backup:

This procedure performs a full backup but the time consuming backup of the Pulp directory isperformed on-line to reduce the time Satellite services are unavailable. Configuration files anddatabases are backed up off-line first. Ensure your backup location has enough disk space tocontain a copy of all the following directories:

/etc/

/var/lib/pulp/

/var/lib/mongodb/

/var/lib/pgsql/

1. Request other Satellite Server users to save any changes and warn them that for theinitial part of the backup, no Satellite services will be available. Check that no othertasks are scheduled for the same time as the backup.

Important

While performing an on-line backup, it is important that nothing is changed in theSatellite that affects the Pulp database, such as changes to Content Views andsynchronizing of repositories, or the result will be an incomplete backup of thePulp database.


# katello-backup --online-backup backup_directory

The katello-backup script with the --online-backup option first stops all serviceswhich could impact the backup, backs up the configuration files and databases, restartsthe required services, and then performs the more time consuming backup of the Pulpdirectory.

6.2. Restoring Red Hat Satellite Server from a Backup

This section describes how to fully restore a Red Hat Satellite Server from the backup datacreated as a result of following the steps in Section 6.1, “Backing up Red Hat Satellite Server”.This process restores the backup on the same server that generated the backup. If the originalsystem is unavailable, provision the same configuration with the same settings (in particular,the host name must be the same).


30

Important

The following process describes a full Red Hat Satellite restoration. This process deletesall data from the target Satellite instance. Ensure that you address the followingconditions:

You are restoring to the correct instance. The Red Hat Satellite instance must havethe same configuration, package versions, and errata as the original system.All commands are executed as root in the directory where the archives were createdduring the backup process.All SELinux contexts are correct. Run the following command to restore the correctSELinux contexts:

# restorecon -Rnv /

Procedure 6.5. To Restore Red Hat Satellite from a Full Backup:

1. Install Satellite 6 using the procedures in the Red Hat Satellite 6 Installation Guide .

2. Copy the backup data to the Satellite's local file system, for example, /var/tmp/satellite-backup/. Ensure you have enough space to store this data on theSatellite Server as well as enough space after the restoration to contain all the data inthe /etc/ and /var/ directories contained within the backup.

3. Run the restoration script:

# katello-restore backup_directory

Where backup_directory is the directory containing the backed-up data. The targetdirectory will be read from the configuration files. If the target directory does not existwhen trying to recover, it will give an error and ask for the correct directory. Thisprocess can take a long time to complete, due to the amount of data to copy. Whereincremental backups exist, see Procedure 6.6, “To Restore Red Hat Satellite from anIncremental Backup:”.

When this process completes, all services should be running and the Satellite Server should beavailable for use.

Procedure 6.6. To Restore Red Hat Satellite from an Incremental Backup:

1. Install Satellite 6 using the procedures in the Red Hat Satellite 6 Installation Guide .

2. Restore the last full backup as described in Procedure 6.5, “To Restore Red Hat Satellitefrom a Full Backup:”.

3. Copy the backup data to the Satellite's local file system, for example, /var/tmp/satellite-backup/. Ensure you have enough space to store this data on theSatellite Server as well as enough space after the restoration to contain all the data inthe /etc/ and /var/ directories contained within the backup.

4. Run the restoration script:

# katello-restore backup_directory_X

[1]

[2]

Chapter 6. Backup and Disaster Recovery

31



Where backup_directory_X is a directory containing an incremental backup. Restore theincremental backups in the same sequence that they were made. For example:backup_directory_1, backup_directory_2.

When this process completes, all services should be running and the Satellite Server should beavailable for use.

[1] https://access.redhat.com/documentation/en/red-hat-satellite/6.2/single/installation-guide/

[2] https://access.redhat.com/documentation/en/red-hat-satellite/6.2/single/installation-guide/


32

Chapter 7. Maintaining a Red Hat Satellite ServerThis chapter provides information on how to maintain a Red Hat Satellite Server, includinginformation on relevant log files, how to enable debug logging, how to open a support case andattach the relevant log tar files, and how to use Red Hat Insights to proactively diagnosesystems.

7.1. Logging and Reporting

Red Hat Satellite provides system information in the form of notifications and log files.

Table 7.1. Log Files for Reporting and Troubleshooting

Log File Description of Log File Content/var/log/candlepin Subscription management/var/log/foreman Foreman/var/log/foreman-proxy Foreman proxy/var/log/httpd Apache HTTP server/var/log/foreman-installer/satellite Satellite installer/var/log/foreman-installer/capsule Capsule Server installer/var/log/libvirt Virtualization API/var/log/mongodb Satellite database/var/log/pulp Celerybeat and Celery startup request

messages. After startup is complete,messages are logged to /var/log/messages.

/var/log/puppet Configuration management/var/log/rhsm Subscription management/var/log/tomcat6 and /var/log/tomcat Apache web server messages for Red Hat

Enterprise Linux 6 and Red HatEnterprise Linux 7, respectively.

/var/log/messages Various other log messages related to pulp,rhsm, and goferd.

You can also use the foreman-tail command to follow many of the log files related to Satellite.You can run foreman-tail -l to list the processes and services that it follows.

On Red Hat Enterprise Linux 7, you can use the journal for more extensive logging information.See Using the Journal for more information.

7.2. Enabling Debug Logging

This section describes how to enable debug logging to provide detailed debugging informationfor Satellite 6.2. Debug logging provides the most detailed log information and can help withtroubleshooting issues that can arise with Satellite 6.2 and its components. It is also possible toenable or disable individual loggers for selective logging.

To enable debug logging, modify the /etc/foreman/settings.yaml file.

1. Set the Logging Level to "debug"

By default, the logging level is set to info, as in the following:

[3]

Chapter 7. Maintaining a Red Hat Satellite Server

33

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System_Administrators_Guide/s1-Using_the_Journal.html

:logging: :level: info

Alter these lines so that they look like this:

:logging: :level: debug

Warning

Until BZ#1325939 is resolved, setting the sql logging level to error is notrecommended.

2. Select Individual Logging Types

By default, the end of /etc/foreman/settings.yaml looks like this:

# Individual logging types can be toggled on/off here:loggers:

Alter the /etc/foreman/settings.yaml file so that it looks like this:

:loggers: :ldap: :enabled: true :permissions: :enabled: true :sql: :enabled: true

3. Restart Katello Services


Complete List of Loggers with their Default Values

:app: :enabled: true:ldap: :enabled: false:permissions: :enabled: false:sql: :enabled: false

7.3. Collecting Information from Log Files

There are two utilies available to collect information from log files.


34

https://bugzilla.redhat.com/show_bug.cgi?id=1325939

Table 7.2. Log Collecting Utilities

Command Descriptionforeman-debug The foreman-debug command collects configuration and log file

data for Red Hat Satellite, its back-end services, and systeminformation. This information is collected and written to a tar file.

By default, the output tar file is located at /tmp/foreman-debug-xxx.tar.xz. For more information, run foreman-debug --help.

There is no timeout when running this command.

sosreport The sosreport command is a tool that collects configuration anddiagnostic information from a Red Hat Enterprise Linux system,such as the running kernel version, loaded modules, and systemand service configuration files. The command also runs externalprograms (for example: foreman-debug -g) to collect Satellite-specific information, and stores this output in a tar file.

By default, the output tar file is located at /var/tmp/sosreport-XXX-20171002230919.tar.xz. For more information, run sosreport --help or seehttps://access.redhat.com/solutions/3592: What is a sosreportand how can I create one?.

The sosreport command calls the foreman-debug -g and timesout after 500 seconds. If your Satellite Server has large log filesor many Satellite tasks, support engineers may require theoutput of sosreport and foreman-debug when you open asupport case.

Important

Both foreman-debug and sosreport remove security information such as passwords,tokens, and keys while collecting information. However, the tar files can still containsensitive information about the Red Hat Satellite Server. Red Hat recommends that yousend this information directly to the intended recipient and not to a public target.

7.4. Using Log Files in Support Cases

You can use the log files and other information described in this chapter to do your owntroubleshooting, or you can capture these and many more files, as well as diagnostic andconfiguration information, to send to Red Hat Support if you need further assistance.

There are two methods to open a support case with Red Hat Support. You can open a supportcase directly from the Satellite web UI or from the Customer Portal.

Section 7.5.5, “Creating Support Cases Using the Red Hat Access Plug-in”: How to open asupport case from the Satellite web UI

https://access.redhat.com/articles/38363: How to open and manage a support case on theCustomer Portal


35

https://access.redhat.com/solutions/3592

https://access.redhat.com/articles/38363

7.5. Accessing Customer Portal Services from Red HatSatellite

The Red Hat Access pre-installed plug-in lets you access several Red Hat Customer Portalservices from within the Satellite web UI.

The Red Hat Access plug-in provides the following services:

Search: Search solutions in the Customer Portal from within the Satellite web UI.

Logs: Send specific parts (snippets) of the log files to assist in problem solving. Send theselog snippets to the Red Hat Customer Portal diagnostic tool chain.

Support: Access your open support cases, modify an open support case and open a newsupport case from within the Satellite web UI.

Note

To access Red Hat Customer Portal resources, you must log in with your Red HatCustomer Portal user identification and password.

7.5.1. Searching for Solutions in the Red Hat Access Plug-in

The Red Hat Access plug-in provides search capabilities that look through the solutionsdatabase available in the Red Hat Customer Portal.

Procedure 7.1. To Search for Solutions from the Red Hat Satellite Server:

1. In the upper right, click Red Hat Access → Search.

2. If necessary, log in to the Red Hat Customer Portal. In the main panel on the upperright, click Log In.

Note


3. In the Red Hat Search field, enter your search query. Search results display in the left-hand Recommendations list.

4. In the Recommendations list, click a solution. The solution article displays in the mainpanel.

7.5.2. Using Logs in the Red Hat Access Plug-in

The log file viewer lets you view the log files and isolate log snippets. You can also send the logsnippets through the Customer Portal diagnostic tool chain to assist with problem solving.

Procedure 7.2. To Use the Logs Diagnostic Tool from the Red Hat Satellite Server:

1. In the upper right, click Red Hat Access → Logs.


36


Note


3. In the left file tree, select a log file and click the file name.

4. Click Select File. A pop-up window displays the log file contents.

5. In the log file, highlight any text sections you want diagnosed. The Red Hat Diagnosebutton displays.

6. Click Red Hat Diagnose. The system sends the highlighted information to the Red HatCustomer Portal, and provides solutions that closely match the provided log information.

7. If a solution does the following:

Matches the problem, click the solution and follow the required steps to troubleshootthe issue.

Does not match the problem, click Open a New Support Case. The support case ispopulated with the highlighted text from the log file. See Section 7.5.5, “CreatingSupport Cases Using the Red Hat Access Plug-in”.

7.5.3. Viewing Existing Support Cases Using the Red Hat Access Plug-in

You can view your existing support case from your Red Hat Satellite Server using the Red HatAccess Plug-in.

Procedure 7.3. To View Existing Support Cases from the Red Hat Satellite Server:

1. In the upper right, click Red Hat Access → Support → My Cases.


Note


3. To search for a specific support case from existing cases, do any of the following:

a. In the Search field, provide a key word or phrase.

b. From the drop-down list, choose a specific Case Group. Your organization hasdefined Case Groups inside the Red Hat Customer Portal.

c. Choose a Case Status.


37

4. From the results, choose a specific support case and click the Case ID. The support caseis ready to view.

7.5.4. Modifying Support Cases Using the Red Hat Access Plug-in

You can update your existing support cases from your Red Hat Satellite Server using the RedHat Access Plug-in.

Procedure 7.4. To Update Support Cases from the Red Hat Satellite Server Web UI:

1. Complete the instructions from Section 7.5.3, “Viewing Existing Support Cases Using theRed Hat Access Plug-in”

2. In the support case, scroll down to the marked sections to do the following:

Attachments: - Attach a local file from the system. Add a file name to make it easierto identify.

Note

File names must be less than 80 characters and the maximum file size forattachments uploaded using the web UI is 250 MB. Use FTP for larger files.

Case Discussion: - Add any updated information about the case you wish to discusswith Global Support Services. After adding information, click Add Comment.

7.5.5. Creating Support Cases Using the Red Hat Access Plug-in

You can create a new support case from your Red Hat Satellite Server using the Red Hat AccessPlug-in.

Procedure 7.5. To Create a New Support Case Using the Red Hat Satellite Server:

1. In the upper right, click Red Hat Access → Support → New Case.


Note


3. The Product and Product Version fields are automatically populated. Complete theother relevant fields, as follows:

Summary — Provide a brief summary of the issue.

Description — Write a detailed description of the issue.

Based on the summary provided, recommendations for possible solutions display in themain panel.


38

4. Click Next.

5. Choose the appropriate options, as follows:

Severity — Select the ticket urgency as 4 (low), 3 (normal), 2 (high), or 1 (urgent).

Case Group — Based on who needs to be notified, create case groups associatedwith the support case. Select Case Groups in Red Hat Satellite. Create Case Groupswithin the Customer Portal.

6. Attach the output of sosreport and any required files. Add a file description and click Attach.

Note

If you have large log files or many Satellite tasks, it is recommended to alsoattach the output of foreman-debug.File names must be less than 80 characters and the maximum file size forattachments uploaded using the web UI is 250 MB. Use FTP for larger files.

7. Click Submit. The system uploads the case to the Customer Portal, and provides a casenumber for your reference.

The Red Hat Knowledgebase article https://access.redhat.com/articles/445443: Red Hat Access:Red Hat Support Tool has additional information, examples, and video tutorials.

7.6. Using Red Hat Insights with Satellite Server

Red Hat Insights enables you to proactively diagnose systems and downtime related to securityexploits, performance degradation and stability failures. You can use the dashboard to quicklyidentify key risks to stability, security, or performance. You can sort by category, view details ofthe impact and resolution, and then determine what systems are affected.

Red Hat Insights is installed by default on Satellite Server. Before using Insights with SatelliteServer, go to Red Hat Insights and click Satellite 6 for the pre-installation checks and toregister your Satellite Servers.

[3] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System_Administrators_Guide/s1-Using_the_Journal.html


39

https://access.redhat.com/articles/445443

https://access.redhat.com/products/red-hat-insights/#getstarted

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System_Administrators_Guide/s1-Using_the_Journal.html

Chapter 8. Monitoring Capsule ServersThe following section shows how to use the Satellite web UI to find Capsule informationvaluable for maintenance and troubleshooting.

8.1. Viewing General Capsule Information

Navigate to Infrastructure → Capsules to view a table of Capsule Servers registered to theSatellite Server. The information contained in the table answers the following questions:

Is the Capsule Server running?

This is indicated by a green icon in the Status column. A red icon indicates an inactiveCapsule, use the service foreman-proxy restart command on the Capsule Serverto activate it.

What services are enabled on the Capsule Server?

In the Features column you can verify if the Capsule for example provides a DHCPservice or acts as a Pulp node. Capsule features can be enabled during installation orconfigured in addition, see the Red Hat Satellite Installation Guide for details.

What organizations and locations is the Capsule Server assigned to?

A Capsule server can be assigned to multiple organizations and locations, but onlyCapsules belonging to the currently selected organization are displayed. To list allCapsules, select Any Organization from the context menu in the top left corner.

After changing the Capsule configuration, select Refresh from the drop-down menu in the Actions column to make sure the Capsule table is up to date.

Click the Capsule name to view further details. At the Overview tab, you can find the sameinformation as in the Capsule table. In addition, you can answer to the following questions:

Which hosts are managed by the Capsule Server?

The number of associated hosts is displayed next to the Hosts managed label. Clickthe number to view the details of associated hosts.

How much storage space is available on the Capsule Server?

The amount of storage space occupied by the Pulp content in /var/lib/pulp, /var/lib/pulp/content, and /var/lib/mongodb is displayed. Also the remainingstorage space available on the Capsule can be ascertained.

8.2. Monitoring Services

Navigate to Infrastructure → Capsules and click the name of the selected Capsule. At the Services tab, you can find basic information on Capsule services, such as the list of DNSdomains, or the number of Pulp workers. The appearance of the page depends on whatservices are enabled on the Capsule Server. Services providing more detailed statusinformation can have dedicated tabs at the Capsule page (see Section 8.3, “MonitoringPuppet”).

8.3. Monitoring Puppet


40

https://access.redhat.com/documentation/en/red-hat-satellite/6.2/paged/installation-guide/chapter-4-installing-capsule-server

Navigate to Infrastructure → Capsules and click the name of the selected Capsule. At the Puppet tab you can find the following:

A summary of Puppet events, an overview of latest Puppet runs, and the synchronizationstatus of associated hosts at the General sub-tab.

A list of Puppet environments at the Environments sub-tab.

At the Puppet CA tab you can find the following:

A certificate status overview and the number of autosign entries at the General sub-tab.

A table of CA certificates associated with the Capsule at the Certificates sub-tab. Hereyou can inspect the certificate expiry data, or cancel the certificate by clicking Revoke.

A list of autosign entries at the Autosign entries sub-tab. Here you can create an entry byclicking New or delete one by clicking Delete.

Chapter 8. Monitoring Capsule Servers

41

Chapter 9. Configuring External AuthenticationBy using external authentication you can derive user and user group permissions from usergroup membership in an external identity provider. Therefore, you do not have to create theseusers and maintain their group membership manually on the Satellite Server. Red Hat Satellitesupports four general scenarios for configuring external authentication:

Using Lightweight Directory Access Protocol (LDAP) server as an external identity provider.LDAP is a set of open protocols used to access centrally stored information over a network.For more information, see Section 9.1, “Using LDAP”. Though you can use LDAP to connectto an IdM or AD server, the setup does not support server discovery, cross-forest trusts, orsingle sign-on with Kerberos on Satellite's web UI.

Using Red Hat Enterprise Linux Identity Management (IdM) server as an external identityprovider. IdM deals with the management of individual identities, their credentials andprivileges used in a networking environment. For more information see Section 9.2, “UsingIdentity Management”.

Using Active Directory (AD) integrated with IdM through cross-forest Kerberos trust as anexternal identity provider. For more information see Section 9.3.1, “Using Active Directorywith Cross-Forest Trust”.

Using direct AD as an external identity provider. For more information see Section 9.3.2,“Using Active Directory Directly”.

The above scenarios are about providing access to the Satellite Server. In addition, hostsprovisioned with Satellite can also be integrated with IdM realms. Red Hat Satellite has a realmfeature that will automatically manage the life cycle of any system registered to a realm ordomain provider. See Section 9.5, “External Authentication for Provisioned Hosts” for moreinformation.

9.1. Using LDAP

9.1.1. Configure TLS for Secure LDAP (LDAPS)

Note

Though direct LDAP integration is covered in this section, Red Hat recommends that youuse SSSD and configure it against IdM, AD, or an LDAP server. These preferredconfigurations are explained elsewhere in this guide.

If you require Red Hat Satellite to use TLS to establish a secure LDAP connection (LDAPS), firstobtain certificates used by the LDAP server you are connecting to and mark them as trusted onthe base operating system of your Satellite Server as described below. If your LDAP server usesa certificate chain with intermediate certificate authorities, all of the root and intermediatecertificates in the chain must be trusted, so ensure all certificates are obtained. If you do notrequire secure LDAP at this time, proceed to Procedure 9.1, “To Configure LDAPAuthentication:”.

Obtain the Certificate from the LDAP Server


42

If you use Active Directory Certificate Services, export the Enterprise PKI CA Certificate usingthe Base-64 encoded X.509 format. See How to configure Active Directory authentication with TLS on Satellite 6.2 for information on creating and exporting a CA certificate from an ActiveDirectory server.

Download the LDAP server certificate to a temporary location on the Red Hat Enterprise Linuxsystem where the Satellite Server is installed and remove it when finished. For example, /tmp/example.crt. The filename extensions .cer and .crt are only conventions and can referto DER binary or PEM ASCII format certificates.

Trust the Certificate from the LDAP Server

Red Hat Satellite Server requires the CA certificates for LDAP authentication to be individualfiles in /etc/pki/tls/certs/ directory.

Use the install command to install the imported certificate into the /etc/pki/tls/certs/directory with the correct permissions.

# install /tmp/example.crt /etc/pki/tls/certs/

Enter the following command as root to trust the example.crt certificate obtained from theLDAP server:

# ln -s example.crt /etc/pki/tls/certs/$(openssl x509 -noout -hash -in /etc/pki/tls/certs/example.crt).0

Restart the httpd service:

On Red Hat Enterprise Linux 6:

# service httpd restart

On Red Hat Enterprise Linux 7:

# systemctl restart httpd

9.1.2. Configuring Red Hat Satellite to Use LDAP

Follow this procedure to configure LDAP authentication using the web UI. Note that if you needsingle sign-on functionality with Kerberos on Satellite's web UI, you should use IdM and ADexternal authentication instead. See Section 9.2, “Using Identity Management” or Section 9.3,“Using Active Directory” for more information on those options.

Procedure 9.1. To Configure LDAP Authentication:

1. Set the allow Network Information System (NIS) service boolean to true to preventSELinux from stopping outgoing LDAP connections:

For Red Hat Enterprise Linux 6:

# setsebool -P allow_ypbind on

For Red Hat Enterprise Linux 7:

Chapter 9. Configuring External Authentication

43


# setsebool -P nis_enabled on

2. Navigate to Administer → LDAP Authentication.

3. Click New authentication source.

4. On the LDAP server tab, enter the LDAP server's name, host name, port, and servertype. The default port is 389, the default server type is POSIX (alternatively you canselect FreeIPA or Active Directory depending on the type of authentication server). For TLS encrypted connections, select the LDAPS check box to enable encryption. The portshould change to 636, which is the default for LDAPS.

5. On the Account tab, enter the account information and domain name details. SeeSection 9.1.3, “LDAP Setting Descriptions and Examples” for descriptions and examples.

6. On the Attribute mappings tab, map LDAP attributes to Satellite attributes. You canmap Login name, First name, Surname, Email address, and Photo attributes. SeeSection 9.1.3, “LDAP Setting Descriptions and Examples” for examples.

7. Click Submit.

The Satellite Server is now configured to use the LDAP server. If you did not select Automatically create accounts in Satellite, see Section 5.1.1, “Creating a User” tocreate user accounts manually. If you selected the option, LDAP users can now log in toSatellite using their LDAP accounts and passwords. After they log in for the first time, you canthen assign the individual user accounts organizations and roles. Alternatively, to have useraccounts associated with an organization automatically, navigate to Administer →Organizations. Select an organization, click the User tab, and select All users. You will stillneed to assign roles manually. See Section 5.1.3, “Assigning Roles to a User” to assign useraccounts appropriate roles in Satellite.

9.1.3. LDAP Setting Descriptions and Examples

The following table provides a description for each setting in the Account tab.

Table 9.1. Account Tab Settings

Setting DescriptionAccount username The LDAP user who has read access to the LDAP server. User name is

not required if the server allows anonymous reading, otherwise use thefull path to the user's object. For example:

uid=$login,cn=users,cn=accounts,dc=example,dc=com

The $login variable stores the username entered on the login page as aliteral string. The value is accessed when the variable is expanded.

The variable cannot be used with external user groups from an LDAPsource because Satellite needs to retrieve the group list without theuser logging in. Use either an anonymous, or dedicated service user.

Account password The LDAP password for the user defined in the Account username field.This field can remain blank if the Account username is using the $loginvariable.

Base DN The top level domain name of the LDAP directory.


44

Groups base DN The top level domain name of the LDAP directory tree that containsgroups.

LDAP filter A filter to restrict LDAP queries.Automatically create accounts in Satellite

If this option is selected, when LDAP users log in to Satellite for the firsttime, Satellite user accounts are created automatically for them. Userswill see a Permissions Denied warning and need to contact theirSatellite administrator to have their user account associated with roles.

Usergroup sync If this option is selected, the user group membership of a user isautomatically synchronized when the user logs in, which ensures themembership is always up to date. If this option is cleared, Satellite relieson a Cron job to regularly synchronize group membership (every 30minutes by default). See Procedure 9.6, “To Configure an External UserGroup:” for further context.

Setting Description

The following tables show example settings for different types of LDAP connections. All of theexamples below use a dedicated service account called redhat that has bind, read, and searchpermissions on the user and group entries. Note that LDAP attribute names are case sensitive.

Table 9.2. Example Settings for Active Directory LDAP Connection

Setting Example valueAccount username DOMAIN\redhatAccount password P@sswordBase DN DC=example,DC=COMGroups Base DN CN=Users,DC=example,DC=comLogin nameattribute

userPrincipalName

First nameattribute

givenName

Surname attribute snEmail addressattribute

mail

Note

userPrincipalName allows the use of whitespace in usernames. The login nameattribute sAMAccountName (which is not listed in the table above) provides backwardscompatibility with legacy Microsoft systems. sAMAccountName does not allow the use ofwhitespace in usernames.

Table 9.3. Example Settings for FreeIPA or Red Hat Identity Management LDAPConnection

Setting Example valueAccount username uid=redhat,cn=users,cn=accounts,dc=example,dc=comBase DN dc=example,dc=comGroups Base DN cn=groups,cn=accounts,dc=example,dc=comLogin nameattribute

uid


45

First nameattribute

givenName


mail

Setting Example value

Table 9.4. Example Settings for POSIX (OpenLDAP) LDAP Connection

Setting Example valueAccount username uid=redhat,ou=users,dc=example,dc=comBase DN dc=example,dc=comGroups Base DN cn=employee,ou=userclass,dc=example,dc=comLogin nameattribute

uid

First nameattribute

givenName


mail

9.2. Using Identity Management

Select from one of the following methods:

Section 9.2.1, “Using Identity Management Directly”

Section 9.2.2, “Using Identity Management with LDAP Authentication”

9.2.1. Using Identity Management Directly

This section shows how to integrate Red Hat Satellite Server with an IdM server and how toenable host-based access control.

Prerequisites

The Satellite Server has to run on Red Hat Enterprise Linux 7.1 or Red Hat Enterprise Linux 6.6or later.

The examples in this chapter assume separation between IdM and Satellite configuration.However, if you have administrator privileges for both servers, you can configure IdM asdescribed in Red Hat Enterprise Linux 7 Linux Domain Identity, Authentication, and Policy Guide

.

The base operating system of the Satellite Server must be enrolled in the IdM domain by theIdM administrator of your organization.

Procedure 9.2. To Configure IdM Authentication on the Satellite Server:

1. On the IdM server, create a host entry for the Satellite Server and generate a one-timepassword, for example:

# ipa host-add --random hostname

[4]


46

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html-single/Linux_Domain_Identity_Authentication_and_Policy_Guide/index.html#ldi-install

Note

The generated one-time password must be used on the client to complete IdM-enrollment.

For more information on host configuration properties, see Red Hat Enterprise Linux 7Linux Domain Identity, Authentication, and Policy Guide .

2. Create an HTTP service for the Satellite Server, for example:

# ipa service-add servicename/hostname

For more information on managing services, see Red Hat Enterprise Linux 7 LinuxDomain Identity, Authentication, and Policy Guide .

3. On the Satellite Server, execute the following command as root to configure IdM-enrollment:

# ipa-client-install --password OTP

Replace OTP with the one-time password provided by the IdM administrator.

4. If the Satellite Server is running on Red Hat Enterprise Linux 7, execute the followingcommand:

# subscription-manager repos --enable rhel-7-server-optional-rpms

The installer is dependent on packages which, on Red Hat Enterprise Linux 7, are in theoptional repository rhel-7-server-optional-rpms. On Red Hat Enterprise Linux 6 allnecessary packages are in the base repository.

5. Execute the following command:

# satellite-installer --foreman-ipa-authentication=true

This command is not limited to a fresh Satellite installation; you can use it to modify anexisting Satellite installation.

6. Restart Katello services:


External users can now log in to Satellite using their IdM credentials. They can now choose toeither log in to the Satellite Server directly using their username and password or takeadvantage of the configured Kerberos single sign on and obtain a ticket on their client machineand be logged in automatically. The two-factor authentication with one-time password (2FAOTP) is also supported. If the user in IdM is configured for 2FA, and the Satellite Server isrunning on Red Hat Enterprise Linux 7, this user can also authenticate to Satellite with a OTP.Optionally proceed to the next procedure to confgiure host-based access control (HBAC).

HBAC rules define which machine within the domain an IdM user is allowed to access. You can

[5]

[6]


47

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/host-attr.html

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/services.html

configure HBAC on the IdM server to prevent selected users from accessing the Satellite Server.With this approach, you can prevent Satellite from creating database entries for users that arenot allowed to log in. For more information on HBAC, see the Red Hat Enterprise Linux 7 LinuxDomain Identity, Authentication, and Policy Guide

Procedure 9.3. To Configure HBAC:

1. Create HBAC service and rule on the IdM server and link them together. The followingexamples use the PAM service name satellite-prod. Execute the following commands onthe IdM server:

$ ipa hbacsvc-add satellite-prod$ ipa hbacrule-add allow_satellite_prod$ ipa hbacrule-add-service allow_satellite_prod --hbacsvcs=satellite-prod

2. Add the user who is to have access to the service satellite-prod, and the host name ofthe Satellite Server:

$ ipa hbacrule-add-user allow_satellite_prod --user=username$ ipa hbacrule-add-host allow_satellite_prod --hosts=the-satellite-fqdn

Alternatively, host groups and user groups can be added to the allow_satellite_prod rule.

3. To check the status of the rule, execute:

$ ipa hbacrule-find satellite-prod$ ipa hbactest --user=username --host=the-satellite-fqdn --service=satellite-prod

4. Ensure the allow_all rule is disabled on the IdM server. For instructions on how to do sowithout disrupting other services see the How to configure HBAC rules in IdM article onthe Red Hat Customer Portal .

5. Configure the IdM integration with the Satellite Server as described in Procedure 9.2,“To Configure IdM Authentication on the Satellite Server:”. On the Satellite Server,define the PAM service as root:

# satellite-installer --foreman-pam-service=satellite-prod

9.2.2. Using Identity Management with LDAP Authentication

To attach Identity Management as an external authentication source with no single sign-onsupport, see Section 9.1, “Using LDAP” for more information.

9.3. Using Active Directory

Select from one of the following methods:

Section 9.3.1, “Using Active Directory with Cross-Forest Trust”

Section 9.3.2, “Using Active Directory Directly”

[7]

[8]


48

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/configuring-host-access.html


Section 9.3.3, “Using Active Directory with LDAP Authentication”

9.3.1. Using Active Directory with Cross-Forest Trust

Kerberos can create cross-forest trust that defines a relationship between two otherwiseseparate domain forests. A domain forest is a hierarchical structure of domains; both AD andIdM constitute a forest. With a trust relationship enabled between AD and IdM, users of AD canaccess Linux hosts and services using a single set of credentials. For more information on cross-forest trusts, see Red Hat Enterprise Linux Windows Integration Guide .

From the Satellite point of view, the configuration process is the same as integration with IdMserver without cross-forest trust configured. The Satellite Server has to be enrolled in the IPMdomain and integrated as described in Section 9.2, “Using Identity Management”. On the IdMserver, the following additional steps are required:

1. To enable the HBAC feature, create an external group and add the AD group to it. Addthe new external group to a POSIX group. Use this POSIX group in a HBAC rule.

2. Configure sssd to transfer additional attributes of AD users. Add these attributes to thenss and domain sections in /etc/sssd/sssd.conf. For example:

[nss]user_attributes=+mail, +sn, +givenname

[domain/EXAMPLE]ldap_user_extra_attrs=mail, sn, givenname

9.3.2. Using Active Directory Directly

This section shows how to use direct Active Directory (AD) as an external authentication sourcefor the Satellite Server. Direct AD integration means that the Satellite Server is joined directlyto the AD domain where the identity is stored. The recommended setup consists of two steps:first enroll Satellite with AD as described in Procedure 9.4, “To Enroll the Satellite Server withthe AD Server:”, then finalize the AD integration with use of GSS-proxy as described inProcedure 9.5, “To Configure Direct AD Integration with GSS-proxy:”.

The traditional process of Kerberos authentication in Apache requires the Apache process tohave read access to the keytab file. GSS-Proxy allows you to implement stricter privilegeseparation for the Apache server by removing access to the keytab file while preservingKerberos authentication functionality. When using AD as an external authentication source forSatellite, it is recommended to implement GSS-proxy, because the keys in the keytab file arethe same as the host keys.

Note

The AD integration requires the Red Hat Satellite Server to be deployed on Red HatEnterprise Linux 7.1.

Perform the following procedures on Red Hat Enterprise Linux that acts as a base operatingsystem for your Satellite Server. For the examples in this section EXAMPLE.ORG is the Kerberosrealm for the AD domain. By completing the procedures, users that belong to theEXAMPLE.ORG realm can log in to the Satellite Server.

[9]


49

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Windows_Integration_Guide/active-directory-trust.html

Prerequisites

Ensure that GSS-proxy and nfs-utils are installed:

# yum install gssproxy nfs-utils

Procedure 9.4. To Enroll the Satellite Server with the AD Server:

1. Install the required packages:

# yum install sssd adcli realmd ipa-python

2. Enroll the Satellite Server with the AD server. You may need to have administratorpermissions to perform the following command:

# realm join -v EXAMPLE.ORG

After enrolling Satellite with the AD server, you can configure the direct AD integration withGSS-proxy using the satellite-installer command. This can be done for already installedSatellite or during the Satellite installation. Note that the Apache user must not have access tothe keytab file. Also take note of the effective user ID of the Apache user (that can be found byexecuting id apache). The following procedure uses the example UID 48.

Procedure 9.5. To Configure Direct AD Integration with GSS-proxy:

1. The satellite-installer command is by default set for the IdM integration. Changethis setting by creating the /etc/ipa/default.conf file with the following content:

[global]server = unusedrealm = EXAMPLE.ORG

2. Create the /etc/net-keytab.conf file with the following content:

[global]workgroup = EXAMPLErealm = EXAMPLE.ORGkerberos method = system keytabsecurity = ads

3. Create a keytab file for HTTP using the following command:

# KRB5_KTNAME=FILE:/etc/gssproxy/http.keytab net ads keytab add HTTP -U administrator -d3 -s /etc/net-keytab.conf

This command fetches the HTTP service keytab file from the AD server and stores it at /etc/gssproxy/http.keytab. Make sure this file is owned by the root user and group:

# chown root:root /etc/gssproxy/http.keytab

4. Insert the following line at the beginning of the /etc/krb5.conf file:

includedir /var/lib/sss/pubconf/krb5.include.d/


50

5. Create an empty keytab file at /etc/httpd/conf/http.keytab:

# touch /etc/httpd/conf/http.keytab

6. Execute the following command:

# satellite-installer --foreman-ipa-authentication=true

7. Start and enable the gssproxy service:

# systemctl restart gssproxy.service# systemctl enable gssproxy.service

8. Configure the Apache server to use GSS-proxy by creating the /etc/systemd/system/httpd.service file with the following content:

.include /lib/systemd/system/httpd.service[Service]Environment=GSS_USE_PROXY=1

Apply changes to the service:

# systemctl daemon-reload

9. Start and enable the httpd service:

# systemctl restart httpd.service

With a running Apache server, users making HTTP requests against the server areauthenticated if the client has a valid Kerberos ticket.

Users can now configure Kerberos SSO in their browsers to be able to log in without filling inaccess credentials in the Satellite GUI. For more information on configuring the Firefox browsersee the Red Hat Enterprise Linux System-Level Authentication Guide. Users of the InternetExplorer browser have to add the Satellite Server to the list of Local Intranet or Trusted sites,and turn on the Enable Integrated Windows Authentication setting. See the Internet Explorerdocumentation for details.


51

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System-Level_Authentication_Guide/Configuring_Applications_for_SSO.html#Configuring_Firefox_to_use_Kerberos_for_SSO

Note

With direct AD integration, HBAC through IdM is not available. As an alternative, you canuse Group Policy Objects (GPO) that enable administrators to centrally manage policies inAD environments. To ensure correct GPO to PAM service mapping, use the following sssdconfiguration:

access_provider = adad_gpo_access_control = enforcingad_gpo_map_service = +satellite-prod

Here, satellite-prod is the PAM service name. For more information on GPOs, please referto the Red Hat Enterprise Linux Windows Integration Guide .

9.3.3. Using Active Directory with LDAP Authentication

To attach Active Directory as an external authentication source with no single sign-on support,see Section 9.1, “Using LDAP” for more information. For an example configuration, see How toconfigure Active Directory authentication with TLS on Satellite 6.

9.4. Configuring External User Groups

Users authenticated through external sources are automatically created on the Satellite Serverthe first time they log in. This does not apply to external user groups that must be mapped touser groups created manually in the Satellite GUI. Members of the external user group thenautomatically become members of the Satellite user group and receive the associatedpermissions.

Prerequisites

The configuration of external user groups depends on the type of external authentication:

If using an LDAP source, make sure the LDAP authentication is correctly configured. Navigateto Administer → LDAP Authentication to view and modify the existing sources. Forinstructions on how to create an LDAP source, see Section 9.1, “Using LDAP”. Take note ofthe LDAP group names you want to use.

Note

If you are using external user groups from an LDAP source, you cannot use the $loginvariable as a substitute for the account user name. You need to use either ananonymous or dedicated service user.

If your Satellite is enrolled with the IdM or AD server as described in Chapter 9, ConfiguringExternal Authentication, take note of the external group names you want to use. To find thegroup membership of external users, execute the id command on Satellite:

# id username

[10]


52

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Windows_Integration_Guide/sssd-gpo.html


Here, username is the name of the external group member. Note that Satellite allows you toconfigure external groups only after at least one external user authenticates for the firsttime. Also, at least one user must exist in the external authentication source.

Procedure 9.6. To Configure an External User Group:

1. Navigate to Administer → User Groups. Click New User Group.

2. On the User group tab, specify the name of the new user group. Do not select anyusers as they will be added automatically when refreshing the external user group.

3. On the Roles tab, select the roles you want to assign to the user group. Alternatively,select the Administrator check box to assign all available permissions.

4. On the External groups tab, click Add external user group and select anauthentication source from the Auth source drop-down menu.

Specify the exact name of the LDAP or external group in the Name field.

5. Click Submit.

Important

You can set the LDAP source to synchronize user group membership automatically onuser login. If this option is not set, LDAP user groups are refreshed automatically througha scheduled task (cron job) synchronizing the LDAP Authentication source (every 30minutes by default). If the user groups in the LDAP Authentication source change in thelapse of time between scheduled tasks, the user can be assigned to incorrect externaluser groups. This is corrected automatically when the scheduled task runs. You can alsorefresh the LDAP source manually by executing foreman-rake ldap:refresh_usergroups or by refreshing the external user groups through the web UI.

External user groups based on IdM or AD are refreshed only when a group member logsin to Satellite. It is not possible to alter user membership of external user groups in theSatellite GUI, such changes are overwritten on the next group refresh. To assignadditional permissions to an external user, add this user to an internal user group thathas no external mapping specified. Then assign the required roles to this group.

9.5. External Authentication for Provisioned Hosts

This section shows how to configure IdM integration to authenticate provisioned hosts. Firstconfigure the Satellite or Capsule Server for IdM realm support, then add hosts to the IdM realmgroup.

9.5.1. Configuring a Red Hat Satellite Server or Capsule Server for IdMRealm Support

To use IdM for provisioned hosts, first configure the Red Hat Satellite Server or Red Hat SatelliteCapsule Server.

Prerequisites


53

A Satellite Server is registered to the content delivery network, an independent CapsuleServer is registered to the Satellite Server.

A realm or domain provider such as Red Hat Identity Management is configured.

Procedure 9.7. To configure the Satellite Server or Capsule Server for IdM RealmSupport:

1. On the Satellite Server or Capsule Server, install the following packages:

# yum install ipa-client foreman-proxy ipa-admintools

2. Configure the Satellite Server (or Capsule Server) as an IdM client:

# ipa-client-install

3. Create a realm-capsule user and the relevant roles in Red Hat Identity Management onthe Satellite Server or Capsule Server:

# foreman-prepare-realm admin realm-capsule

Running foreman-prepare-realm will prepare an IdM server for use with the CapsuleServer. It creates a dedicated role with the permissions needed for Satellite, creates auser with that role and retrieves the keytab file. You will need your IdentityManagement server configuration details on this step.

If the command successfully executes, you should be able to see the followingcommand output:

Keytab successfully retrieved and stored in: freeipa.keytabRealm Proxy User: realm-capsuleRealm Proxy Keytab: /root/freeipa.keytab

4. Move the /root/freeipa.keytab to the /etc/foreman-proxy directory and set theownership settings to the user foreman-proxy:

# mv /root/freeipa.keytab /etc/foreman-proxy# chown foreman-proxy:foreman-proxy /etc/foreman-proxy/freeipa.keytab

5. Configure the realm based on whether you are using Satellite Server or Capsule Server:

A. If you are using the integrated capsule Server in the Satellite Server, use satellite-installer to configure the realm:

# satellite-installer --foreman-proxy-realm true \--foreman-proxy-realm-keytab /etc/foreman-proxy/freeipa.keytab \--foreman-proxy-realm-principal '[email protected]' \--foreman-proxy-realm-provider freeipa


54

Note

You may also run these options when you first configure the Red Hat SatelliteServer.

B. If you are using an independent Capsule Server, use satellite-installer --scenario-capsule to configure the realm:

# satellite-installer --scenario-capsule --realm true \--realm-keytab /etc/foreman-proxy/freeipa.keytab \--realm-principal '[email protected]' \--realm-provider freeipa

6. Make sure that the most updated versions of the ca-certificates package is installed andtrust the IdM Certificate Authority:

# cp /etc/ipa/ca.crt /etc/pki/ca-trust/source/anchors/ipa.crt# update-ca-trust enable# update-ca-trust

7. (Optional) If you are configuring IdM on an already existing Satellite Server or CapsuleServer, the following steps should also be taken to make sure that the configurationchanges take effect:

a. Restart the foreman-proxy service:

# service foreman-proxy restart

b. Log in to the Satellite Server and click Infrastructure → Capsules.

c. Click on the drop-down menu on the right-hand side of the Capsule Server youhave configured for IdM and choose Refresh Features.

8. Finally, create a new realm entry in the Satellite Server user interface:

a. Click Infrastructure → Realms and on the right-hand corner of the main page,click New Realm.

b. Fill in the fields in the following subtabs:

a. On the Realm subtab, provide the realm name, the type of realm to useand the realm proxy.

b. On the Locations subtab, choose the locations where the new realm isintended for use.

c. On the Organizations subtab, choose the organizations where the newrealm is intended for use.

c. Click Submit.

The Satellite Server or Capsule Server is now ready to provision hosts that automaticallyregister to IdM. The next section will detail the steps on how to automatically add hosts to anIdM host group.


55

9.5.2. Adding Hosts to an IdM Host Group

Red Hat Enterprise Linux Identity Management (IdM) supports the ability to set up automaticmembership rules based on a system's attributes. Red Hat Satellite's realm feature providesadministrators with the ability to map the Red Hat Satellite host groups to the IdM parameter"userclass" which allow administrators to configure automembership.

When nested host groups are used, they are sent to the IdM server as they are displayed in theRed Hat Satellite User Interface. For example, "Parent/Child/Child".

Note

The Satellite Server or Capsule Server sends updates to the IdM server, howeverautomembership rules are only applied at initial registration.

Procedure 9.8. To Add Hosts to an IdM Host Group:

1. On the IdM server, create a host group:

# ipa hostgroup-add hostgroup_nameDescription: hostgroup_description----------------------------Added hostgroup "hostgroup_name"----------------------------Host-group: hostgroup_nameDescription: hostgroup_description

Where:

a. hostgroup_name is the host group's name.

b. hostgroup_description is the host group's description.

2. Create an automembership rule:

# ipa automember-add --type=hostgroup automember_rule----------------------------------Added automember rule "automember_rule"----------------------------------Automember Rule: automember_rule

Where:

a. automember-add flags the group as an automember group.

b. --type=hostgroup identifies that the target group is a host group, not a usergroup.

c. automember_rule is the name you wish to identify the automember rule by.

3. Define an automembership condition based on the userclass attribute:

# ipa automember-add-condition --key=userclass --type=hostgroup --inclusive-regex=^webserver hostgroup_name----------------------------------


56

Added condition(s) to "hostgroup_name"----------------------------------Automember Rule: automember_ruleInclusive Regex: userclass=^webserver----------------------------Number of conditions added 1----------------------------

Where:

a. automember-add-condition allows you to add regular expression conditions toidentify group members.

b. --key=userclass specifies the key attribute as userclass.

c. --type=hostgroup identifies that the target group is a host group, not a usergroup.

d. --inclusive-regex=^webserver is a regular expression pattern to identifymatching values.

e. hostgroup_name is the target host group's name.

When a system is added to the Satellite Server's hostgroup_name host group, it will nowautomatically be added to the Identity Management server's "hostgroup_name" host group aswell. IdM host groups allow for Host-Based Access Controls (HBAC), sudo policies and other IdMfunctions.

[4] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/linux-manual.html

[5] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/host-attr.html

[6] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/services.html

[7] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/configuring-host-access.html

[8] https://access.redhat.com/solutions/67895

[9] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Windows_Integration_Guide/active-directory-trust.html

[10] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Windows_Integration_Guide/sssd-gpo.html


57

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html-single/Linux_Domain_Identity_Authentication_and_Policy_Guide/index.html#ldi-install

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/host-attr.html

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/services.html

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Linux_Domain_Identity_Authentication_and_Policy_Guide/configuring-host-access.html


https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Windows_Integration_Guide/active-directory-trust.html

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Windows_Integration_Guide/sssd-gpo.html

Chapter 10. Customizing Satellite ServerRed Hat Satellite Server can be extended by the addition of user interface plug-ins and by theuse of hooks triggered by orchestration and Rails events. Some plug-ins are installed by defaultbut additional plug-ins can be installed as RPM packages from the Red Hat repositories andfrom upstream. Red Hat supports the API but not upstream plug-ins themselves. Some hooksare provided as RPM packages and more hooks can be created as shell scripts. This enablessystem administrator's familiar with shell scripts to extend the Satellite's capabilities withouthaving to use Ruby and Rails.

10.1. Adding Additional Plug-ins

To list the plug-ins available from the configured repositories, enter as root:

# yum search rubygem-foremanLoaded plugins: product-id, search-disabled-repos, subscription-manager=================== N/S matched: rubygem-foreman ==============================tfm-rubygem-foreman-redhat_access.noarch : Foreman engine to access Red Hat knowledge base and manage support cases.tfm-rubygem-foreman-tasks.noarch : Tasks support for Foreman with Dynflow integrationtfm-rubygem-foreman_abrt.noarch : Display reports from Automatic Bug Reporting Tool in Foremantfm-rubygem-foreman_bootdisk.noarch : Create boot disks to provision hosts with Foremanoutput truncated

To view the currently installed plug-ins, enter as root:

# yum list installed | grep rubygem-foreman

To add a new plug-in, install the package and then restart Foreman. For example, to install theSCAP client plug-in, enter as root:

# yum install rubygem-foreman_scap_client.noarch

Restart the Foreman service for the plug-in to be registered:

# touch ~foreman/tmp/restart.txt

The Foreman website has additional plug-ins Popular Plugins . Note that Red Hat supportsthe plug-in API but not upstream plug-ins themselves.

Adding Plug-ins from the Foreman Repository

The Foreman repositories are available at yum.theforeman.org/plugins. Separate repositoriesare available for each Foreman release, containing plug-ins that are compatible with thatparticular version. Ensure you install plug-ins compatible with the version of Foreman on yoursystem. To determine the Foreman release in use, enter:

[11]


58

http://theforeman.org/plugins/#1.1PopularPlugins

yum.theforeman.org/plugins

$ rpm -q foremanforeman-1.7.2.53-1.el7sat.noarch

Configure the Foreman repository as follows:

# /etc/yum.repos.d/foreman-plugins.repo[foreman-plugins]name=Foreman pluginsbaseurl=http://yum.theforeman.org/plugins/1.10/elX/x86_64/enabled=1gpgcheck=0

Where X is 6 or 7 for Red Hat Enterprise Linux 6 or 7 respectively. Change the version numberin the URL to match the Foreman release in use. Note the packages are not currently GPGsigned.

1. Find the package for the plug-in with the search function. For example, to search for aplug-in with the word "discovery" in the name:

# yum search discovery

Alternately check the plug-in documentation for the name of the plug-in.

2. Install the package, for example:

# yum install tfm-rubygem-foreman_discovery

3. Restart the Foreman service for the plug-in to be registered:


10.2. Using Foreman Hooks

Foreman's host orchestration can be extended by means of hooks so that additional tasks canbe executed. A Foreman hook enables triggering a script (any executable can be used) when anorchestration event occurs, such as when a host is created or when provisioning of a host hascompleted. In addition, hooks can be made into standard Rails callbacks for any Foremanobject, all with scripts.

Note

Foreman hooks can modify workflows in Satellite and therefore you might be requestedto remove all hooks in order to get support from Red Hat. Foreman hooks also need to beremoved before upgrading, and then reinstated after you have confirmed Satellite isworking as expected.

Foreman hooks are provided by the tfm-rubygem-foreman_hooks package, which is installed bydefault. If required, to ensure the package is installed and up to date enter as root:

# yum install tfm-rubygem-foreman_hooksLoaded plugins: product-id, search-disabled-repos, subscription-manager

Chapter 10. Customizing Satellite Server

59

Package tfm-rubygem-foreman_hooks-0.3.9-2.el7sat.noarch already installed and latest versionNothing to do

Foreman hooks are stored in /usr/share/foreman/config/hooks/. A subdirectory must becreated for each Foreman object, with further subdirectories created for each event name. AForeman object can be a host or network interface. The path to the hook is as follows:

/usr/share/foreman/config/hooks/object/event/hook_script

For example, to create a subdirectory for hooks to be activated after the host has completedits operating system installation, enter a command as follows:

# mkdir -p /usr/share/foreman/config/hooks/host/managed/before_provision/

If you download a script, and the appropriately named directory has been created already, thenuse the install command as follows to ensure the SELinux context is correct:

install hook_script /usr/share/foreman/config/hooks/object/event/hook_script

Alternately, if you created the script directly in the event subdirectory then apply the SELinuxcontext by entering as root:

# restorecon -RvF /usr/share/foreman/config/hooks

The SELinux context is bin_t on Red Hat Enterprise Linux 6 and foreman_hook_t on Red HatEnterprise Linux 7. Keep in mind that the script is running confined, therefore some actionsmight be denied by SELinux. Check for actions denied by SELinux by running aureport -a orlooking in /var/log/audit/audit.log.

For further information on debugging SELinux problems and using the audit2allow utility:

On Red Hat Enterprise Linux 6, see Fixing Problems .

On Red Hat Enterprise Linux 7, see Fixing Problems .

Procedure 10.1. Creating a Foreman Hook to Use the logger Command

This hook script creates additional log messages each time Foreman provisions a new server.

1. Create the directory structure on the Satellite Server base system:

# mkdir -p /usr/share/foreman/config/hooks/host/managed/before_provision/

2. Create the script as follows:

# vi /usr/share/foreman/config/hooks/host/managed/before_provision/10_logger.sh#!/bin/bash/logger $1 $2

[12]

[13]


60

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Security-Enhanced_Linux/sect-Security-Enhanced_Linux-Troubleshooting-Fixing_Problems.html

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/SELinux_Users_and_Administrators_Guide/sect-Security-Enhanced_Linux-Troubleshooting-Fixing_Problems.html

The numeric prefix 10 to the file name _logger.sh determines the order of executionfor scripts in the same subdirectory. Change this prefix to suit your needs.

3. Change the script owner to foreman:

# chown foreman:foreman 10_logger.sh

4. Change the script permissions to allow execution by the user:

# chmod u+x 10_logger.sh

5. Ensure the SELinux context is correct on all files in the /usr/share/foreman/config/hooks directory:

# restorecon -RvF /usr/share/foreman/config/hooks/

6. To enable the foreman user to use the logger command, add the following rule to the /etc/sudoers file:

# vi /etc/sudoersforeman ALL=(ALL) NOPASSWD:/usr/bin/logger

7. Restart the Foreman service for the hook to be registered:


Every Foreman or Rail object can have a hook. See the /usr/share/app/models/ directory or,to get a full list of available models, enter the following commands:

# foreman-rake console> ActiveRecord::Base.descendants.collect(&:name).collect(&:underscore).sort=> ["audited/adapters/active_record/audit", "compute_resource", "container",output truncated

This command output also lists some technical tables which are unlikely to be used withForeman hooks, for example "active_record" or "habtm". These are most commonly used:

host

report

10.2.1. Orchestration Events

Foreman supports orchestration tasks for hosts and network interfaces, referred to as objects,when the object is created, updated, and destroyed. These tasks are shown to the user in theweb UI. If they fail, they will automatically trigger a rollback of the action. Orchestration hookscan be given a priority, therefore it is possible to order them before or after built-inorchestration steps (before a DNS record is deployed for example).

To add a hook to an event, use the following event names:

create

update


61

destroy

10.2.2. Rails Events

For hooks on anything apart from hosts and NICs (which support orchestration, as above) thenthe standard Rails events can be used. Every event has a "before" and "after" hook and theseare the most interesting events provided:

after_create

before_create

after_destroy

before_destroy

The host object has two additional callbacks that you can use:

host/managed/after_build triggers when a host is put into build mode.

host/managed/before_provision triggers when a host completes the OS install.

For the full list of Rails events, see the Constants section at the bottom of the Ruby on RailsActiveRecord::Callbacks documentation.

10.2.3. Execution of hooks

Hooks are executed in the context of the Foreman server, so usually under the foreman user.The first argument is always the event name, enabling scripts to be symbolically linked intomultiple event directories. The second argument is the string representation of the object thatwas hooked, for example the host name for a host:

~foreman/config/hooks/host/managed/create/50_register_system.sh create foo.example.com

A JSON representation of the hook object will be passed in on standard input. This JSON isgenerated by the v2 API views. A utility to read this with jgrep is provided in examples/hook_functions.sh and sourcing this utility script will be enough for most users.Otherwise, closing standard input is recommend to prevent the pipe buffer from filling whichwould block the Foreman thread.

echo '{"host":{"name":"foo.example.com"}}' \ | ~foreman/config/hooks/host/managed/create/50_register_system.sh \ create foo.example.com

Every hook within the event directory is executed in alphabetical order. For orchestrationhooks, an integer prefix in the hook filename will be used as the priority value, therebyinfluencing when it is executed in relation to DNS, DHCP, VM creation, and other tasks.

10.2.4. Hook Failures and Rollback

If a hook fails, exits with a non-zero return code, the event is logged. For Rails events,execution of other hooks will continue. For orchestration events, a failure will halt the actionand rollback will occur. If another orchestration action fails, the hook might be called again torollback its action. In that case the first argument will change as appropriate, so it must be

[14]


62

http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html

obeyed by the script (for example, a "create" hook will be called with "destroy" if it has to berolled back later).

[11] http://projects.theforeman.org/projects/foreman/wiki/List_of_Plugins

[12] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Security-Enhanced_Linux/sect-Security-Enhanced_Linux-Troubleshooting-Fixing_Problems.html

[13] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/SELinux_Users_and_Administrators_Guide/sect-Security-Enhanced_Linux-Troubleshooting-Fixing_Problems.html

[14] http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html


63

http://projects.theforeman.org/projects/foreman/wiki/List_of_Plugins

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Security-Enhanced_Linux/sect-Security-Enhanced_Linux-Troubleshooting-Fixing_Problems.html

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/SELinux_Users_and_Administrators_Guide/sect-Security-Enhanced_Linux-Troubleshooting-Fixing_Problems.html

http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html

Red Hat Satellite 6.2 Server Administration Guide

Documents

Transcript of Red Hat Satellite 6.2 Server Administration Guide