Red Hat Training
A Red Hat training course is available for Red Hat Satellite
Server Administration Guide
Administering a Red Hat Satellite 6 Server.
Edition 1.0
Red Hat Satellite Documentation Team
satellite-doc-list@redhat.com
Abstract
Chapter 1. Accessing Red Hat Satellite
1.1. Logging in to Red Hat Satellite
Procedure 1.1. Installing the Katello Root CA Certificate
- Browse to
http://HOSTNAME/pub
- Select katello-server-ca.crt.
- Import the certificate into your browser.
Procedure 1.2. To Log in to Satellite:
- Access the Satellite Server using a web browser pointed to the following address:
https://HOSTNAME/
To identify your host name, use thehostname
command at the prompt:# hostname
Important
An untrusted connection warning appears on your web browser when accessing Satellite for the first time. Accept the self-signed certificate and add the Satellite URL as a security exception to override the settings. This procedure might differ depending 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
- Enter the user name and password created during the configuration process. If a user was not created during the configuration process, the default user name is admin. If you have forgotten the password of the default administrative account, admin, see Section 1.2, “Changing the Password in Red Hat Satellite”.
When you have successfully logged in, you are taken to the Satellite dashboard. The dashboard contains an overview of the Satellite and the hosts registered. For more information, see Using the Red Hat Satellite Content Dashboard and Searching and Bookmarking in the Red Hat Host Configuration Guide.
Table 1.1. Navigation Tabs
Navigation Tabs | Description |
---|---|
Default Organization | Clicking this tab changes the organization and location. If no organization or location is selected, the default organization is Any Organization and the default location is Any Location. Use this tab to change 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. |
Warning
1.2. Changing the Password in Red Hat Satellite
Procedure 1.3. To Change Your Red Hat Satellite Password:
- Click your user name at the top right corner.
- Select My Account from the menu.
- In the Password field, type in a new password.
- In the Verify field, type in the new password again.
- Click the Submit button to save your new password.
Resetting the Password in Red Hat Satellite
# foreman-rake permissions:reset Reset to user: admin, password: qwJxBptxb7Gfcjj5
Chapter 2. Starting and Stopping Red Hat Satellite
katello-service
command to manage Satellite services from the command line. This is useful when upgrading Satellite or when creating a backup, see the Red Hat Satellite Installation Guide for details on these use cases.
satellite-installer
command, all Satellite services are started and enabled automatically. View the list of these services by executing:
# katello-service list
# katello-service status
# katello-service stop
# katello-service start
# katello-service restart
Chapter 3. Configuring Organizations, Locations and Life Cycle Environments
Figure 3.1. Example Topology for Red Hat Satellite 6
3.1. Organizations
Important
3.1.1. Creating an Organization
Procedure 3.1. To Create an Organization:
- Navigate to Administer → Organizations.
- Click New Organization.
- In the Name field, insert the name of the new organization.
- In the Label field, insert the label of the new organization.
- In the Description field, insert a description of the new organization.
- Click Submit.
- 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.
- Specify the configuration details of the organization such as Capsule Servers, subnets or compute resources. You can modify these settings later as described in Section 3.1.4, “Editing an Organization”.
- Click Submit.
3.1.2. Creating an Organization Debug Certificate
Procedure 3.2. To Create a New Organization Debug Certificate:
- Navigate to Administer → Organizations.
- Select an organization for which you want to generate a debug certificate.
- Click Generate and Download. This generates a debug certificate.
- Save the certificate file in a secure location.
Note
3.1.3. Using an Organization Debug Certificate
curl
utility only requires extracting the certificate and key into separate files.
Procedure 3.3. To Use an Organization Debug Certificate in Firefox:
- Create and download an organization certificate as described in Procedure 3.2, “To Create a New Organization Debug Certificate:”.
- Open the X.509 certificate, for example, for the default organization:
$
vi 'Default Organization-key-cert.pem'
- Copy the contents of the file from
-----BEGIN RSA PRIVATE KEY-----
to-----END RSA PRIVATE KEY-----
inclusive, into a file calledkey.pem
. - Copy the contents of the file from
-----BEGIN CERTIFICATE-----
to-----END CERTIFICATE-----
inclusive, into a file calledcert.pem
. - Enter a command as follows to create a PKCS12 format certificate and enter a password or 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: - Using the preferences tab, import the resulting
pfx
file into your browser: Navigate to Edit → Preferences → Advanced Tab. Select View Certificates in the Certificates view to open the Certificate Manager. On the Your Certificates tab, click Import and select thepfx
file to load. You will be prompted for the password or phrase used when making the certificate. - Enter a URL in the following format into your browser's address bar to begin browsing for repositories:
http://satellite.example.com/pulp/repos/organization_label
Pulp uses the organization label so the URL must use the organization label too.
Procedure 3.4. To Use an Organization Debug Certificate with curl:
- Create and download an organization certificate as described in Procedure 3.2, “To Create a New Organization Debug Certificate:”.
- Open the X.509 certificate, for example, for the default organization:
$
vi 'Default Organization-key-cert.pem'
- Copy the contents of the file from
-----BEGIN RSA PRIVATE KEY-----
to-----END RSA PRIVATE KEY-----
inclusive, into a file calledkey.pem
. - Copy the contents of the file from
-----BEGIN CERTIFICATE-----
to-----END CERTIFICATE-----
inclusive, into a file calledcert.pem
. - Find a valid URL for a repository. You can use the browsing method described in the previous procedure or use the web UI. For example, using the web UI, navigate to Content → Products and select a Product by name. On the Repositories tab, select a repository by name and look for the Published At entry.
- To use
curl
to access a repository, use a command as follows:$
Ensure the paths tocurl -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/
cert.pem
andkey.pem
are the correct absolute paths otherwise the command will fail silently.
3.1.4. Editing an Organization
Procedure 3.5. To Edit an Organization:
- Navigate to Administer → Organizations.
- Click the name of the organization to be edited.
- Select the resource to edit from the list on the left.
- Click the name of the desired items to add them to the Selected Items list.
- Click Submit.
Note
3.1.5. Removing an Organization
Procedure 3.6. To Remove an Organization:
- Navigate to Administer → Organizations.
- Select Delete from the drop-down menu to the right of the name of the organization you want to remove.
- An alert box appears:
Delete Organization?
- Click OK to delete the organization.
3.2. Locations
Important
3.2.1. Creating a Location
Procedure 3.7. To Create a Location:
- Navigate to Administer → Locations.
- Click New Location.
- Insert the name of the new location in the Name field. If you want to create a nested location, select a Parent location from the drop-down menu. Optionally, specify a Description of the location. Click Submit.
- 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.
- Specify the configuration details of the location such as Capsule Servers, subnets or compute resources. You can modify these settings later as described in Section 3.2.2, “Editing a Location”.
- Click Submit.
3.2.2. Editing a Location
Procedure 3.8. To Edit a Location:
- Navigate to Administer → Locations.
- Click the name of the location to be edited.
- Select the resource to edit from the list on the left.
- Click the name of the desired items to add them to the Selected Items list.
- Click Submit.
3.2.3. Removing a Location
Procedure 3.9. To Remove a Location:
- Navigate to Administer → Locations.
- Select Delete from the drop-down menu to the right of the name of the location you want to remove.An alert box appears:
Delete Location?
- Click OK.
3.3. Life Cycle Environments
Figure 3.2. An Environment Path Containing Four Environments
3.3.1. Creating Life Cycle Environments
Procedure 3.10. To Create a Life Cycle Environment:
- Select an organization from the menu in the top left hand corner.
- Click Content → Life Cycle Environments and then click New Environment Path.
- Insert a name and a label (automatically fills in the Name field input) for the life cycle environment. The Description field is optional.
- Click Save to create the environment.
3.3.2. Adding Life Cycle Environments to a Red Hat Satellite Capsule Server
Important
hammer
commands on the Satellite Server.
Procedure 3.11. To Add Environments to the Satellite Capsule Server:
- Log in to the Satellite Server CLI as root.
- Choose the desired Red Hat Satellite Capsule Server from the list and take note of its
id
:# hammer capsule list
The Satellite Capsule Server's details can be verified using the command:# hammer capsule info --id capsule_id_number
- Verify the list of life cycle environments available for the Red Hat Capsule Server and note down the
environment id
:# hammer capsule content available-lifecycle-environments --id capsule_id_number
Where:available-lifecycle-environments
are life cycle environments that are available to the Satellite Capsule but are currently not attached to the Satellite Capsule.
- Add the life cycle environment to the Satellite Capsule Server:
# hammer capsule content add-lifecycle-environment --id capsule_id_number --environment-id environment_id_number
Where:- capsule_id_number stands for the Satellite Capsule Server's identification number.
- environment_id_number stands for the life cycle environment's identification number.
Repeat this step for every life cycle environment to be added to the Capsule Server. - Synchronize the content from the Satellite Server's environment to the Satellite Capsule Server:
# hammer capsule content synchronize --id capsule_id_number
When an external Satellite Capsule Server has various life cycle environments, and only one life cycle environment needs to be synchronized, it is possible to target a specific environment by specifying the environment identification number:# hammer capsule content synchronize --id external_capsule_id_number --environment-id environment_id_number
3.3.3. Promoting Content Views
Procedure 3.12. To Promote a Content View:
- On the main menu, click Content → Content Views.
- In the Name column, click the name of the Content View that you want to promote.
- On the Versions tab, identify the latest version, and click Promote.
- Identify the promotion path where you want to promote the Content View, select the appropriate life cycle environment, and click Promote Version.
- After the promotion has completed, the Versions tab updates to display the new status of your Content Views.
3.3.4. Removing Life Cycle Environments From Satellite Server
Procedure 3.13. To Remove a Life Cycle Environment:
- On the main menu, click Content → Life Cycle Environments.
- Click the name of the life cycle environment that you want to remove, and then click Remove Environment.
- In the confirmation dialog box, click Remove to remove the environment.
Note
3.3.5. Removing Life Cycle Environments from Capsule Server
- When life cycle environments are no longer relevant to the host systems
- When life cycle environments have been incorrectly added to Capsule Server
Procedure 3.14. To remove a life cycle environment from Capsule Server:
- Log in to the Satellite Server CLI as the root user.
- 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
- Verify the list of life cycle environments currently attached to the Capsule Server and take note of the
environment id
:# hammer capsule content lifecycle-environments --id capsule_id_number
- Remove the life cycle environment from Capsule Server:
# hammer capsule content remove-lifecycle-environment --id capsule_id_number --environment-id environment_id
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 Capsule Server. - Synchronize the content from the Satellite Server's environment to Capsule Server:
# hammer capsule content synchronize --id capsule_id_number
3.4. Viewing Import History
Procedure 3.15. To View an Import History:
- Click Content → Red Hat Subscriptions.
- Click the Manage Manifest button.
- Click the Import History tab.
Chapter 4. Users and Roles
4.1. Creating and Managing Users
4.1.1. Creating a User
Procedure 4.1. To Create a User:
- Navigate to Administer → Users and then click New User.
- On the User tab, enter the required details.
- On the Locations tab, select the required locations for this user.
- On the Organizations tab, select organizations accessible to this user. The current active organization is selected by default. If you specify multiple organizations, you can select the default organization for user login from the drop-down list.
- On the Roles tab, select the required roles for this user. Active roles are displayed in the right panel.
- Click Submit to create the user.
4.1.2. Editing a User
Procedure 4.2. To Edit an Existing User:
- Navigate to Administer → Users.
- Click the user name of the user to be altered. General information about the user will appear on the right.
- In the User tab, you can modify the user's user name, first name, surname, email address, default location, default organization, language, and password.
- In the Locations tab, you can modify the user's assigned locations.
- In the Organizations tab, you can modify the user's assigned organizations.
- In the Roles tab, you can modify the user's assigned roles.
- Click Save to save your changes.
4.1.3. Assigning Roles to a User
Procedure 4.3. To Assign a Role to a User:
- Navigate to Administer → Users. If a user account created is not listed, check that you are 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.
- Click the user name of the user that you want to modify. General information about the user appears on the right.
- Click the Locations tab, and select a location if none is assigned.
- Click the Organizations tab, and check that an organization is assigned.
- Click the Roles tab to display the list of available role assignments.
- Select role you want to assign to the user in the Roles list. The list contains the predefined roles, as well as any custom roles, see Table 4.1, “Predefined Roles Available in Red Hat Satellite”. Alternatively, select the Administrator check box to assign all available permissions to the selected user.
- Click Save.
4.1.4. Configuring Email Notifications
Important
Procedure 4.4. To Configure Email Notifications:
- Navigate to Administer → Users.
- Click the Username of the user you want to edit.
- On the User tab, check the Email address field. Ensure that it contains a valid email address. The address will be associated with the user account, and the notifications selected in the following steps will be sent there.
- Click the Email Preferences tab and select Mail enabled to enable email notifications.
- Select the notifications you want the user to receive.
- Audit summary is a summary of all activity audited by the Satellite Server. To enable these notifications, select the frequency of emails from the drop-down list that offers Daily, Weekly, or Monthly updates. Enter a query in the associated query 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 hosts managed by the user. To enable these notifications, select the frequency of emails from the drop-down list that offers Daily, Weekly, or Monthly updates.
- OpenSCAP policy summary is a summary of OpenSCAP policy reports and their results. 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. It contains a summary of errata applicable and installable to hosts registered to the promoted Content View. This allows you to monitor what updates have been applied to which hosts. To enable these notifications, select Subscribe from the drop-down menu.
- Puppet error state is a notification sent after a host reports an error related to Puppet. 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, or Monthly updates.
- Sync errata is a notification sent only after synchronizing a repository. It contains a summary of new errata introduced by the synchronization. To enable these notifications, select Subscribe from the drop-down menu.
- Click Submit.
To test email delivery to the email address associated with a user account, open the Satellite web UI, navigate to Administer → Users, click on the user name, click the Email Preferences tab and click Test email. A test email message is then sent immediately to the user's email address. If it does not arrive, first verify the user's email address, then the Satellite Server's email configuration, after which you may need to examine firewall and mail server logs.
To verify that your subscription to selected email notifications is valid, you can have all periodic notifications sent to you on request. Note that it will trigger all notifications scheduled for the specified frequency, and affect all users who have subscribed to it. Sending on request notifications to individual users is currently not supported.
# foreman-rake reports:frequency
- daily
- weekly
- monthly
4.1.5. Removing a User
Procedure 4.5. To Remove a User:
- On the main menu, click Administer → Users to open the Users page.
- Click the Delete link to the right of the user name you want to delete.
- In the alert box, click OK to delete the user.
4.2. Creating User Groups
Procedure 4.6. To Create a User Group:
- Navigate to Administer → User groups to view the user groups on your Satellite.
- Click New User Group.
- On the User group tab, specify the name of the new user group and select group members from the list of users. To include a previously-created user group, select the check box next to the name of the group to be added.
- 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.
- Click Submit to create the user group.
4.3. Creating and Managing Roles
Table 4.1. Predefined Roles Available in Red Hat Satellite
Role | Permissions Provided by Role[a] |
---|---|
Anonymous | The set of permissions that every user is granted, irrespective of any other roles. |
Discovery manager | View, provision, edit, and destroy discovered hosts and manage discovery rules. |
Discovery reader | View hosts and discovery rules. |
Boot disk access | Download the boot disk. |
Red Hat Access Logs | View the log viewer and the logs. |
Manager | A most extensive set of permissions, the majority of actions from each resource type is enabled. |
Edit partition tables | 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. |
[a]
The exact set of allowed actions associated with predefined roles can be viewed by the privileged user as described in Section 4.3.3, “Viewing Permissions of a Role”.
|
4.3.1. Creating a Role
Procedure 4.7. To Create a Role:
- Navigate to Administer → Roles.
- Click New Role.
- Provide a Name for the role.
- Click Submit to save your new role.
Note
4.3.2. Adding Permissions to a Role
Procedure 4.8. To Add Permissions to a Role:
- Navigate to Administer → Roles.
- Select Add Filter from the drop-down list to the right of the required role.
- Select the Resource type from the drop-down list. The (Miscellaneous) group gathers permissions that are not associated with any resource group.
- Click the permissions you want to select from the Permission list.
- Select whether the permission is Unlimited. This option is selected by default, which means that the permission is applied on all resources of the selected type. When you disable the Unlimited check box, the Search field activates. In this field you can specify further filtering with use of the Red Hat Satellite 6 search syntax. See Section 4.4, “Granular Permission Filtering” for details.
- Click Next.
- Click Submit to save changes.
4.3.3. Viewing Permissions of a Role
Procedure 4.9. To View Permissions Associated with a Role:
- Navigate to Administer → Roles.
- Click Filters to the right of the required role to get to the Filters page.
Procedure 4.10. To Create a Complete Permission Table:
- Ensure that the required packages are installed. Execute the following command on the Satellite Server:
# yum install tfm-rubygem-foreman*
- 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)
The above syntax creates a table of permissions and saves it to the/tmp/table.html
file. - 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>
- Open
/tmp/table.html
in a web browser to view the table.
4.3.4. Removing a Role
Procedure 4.11. To Remove a Role:
- Navigate to Administer → Roles.
- Select Delete from the drop-down list to the right of the role to be deleted.
- In an alert box that appears, click OK to delete the role.
4.4. Granular Permission Filtering
field_name operator value
- field_name marks the field to be queried. The range of available field names depends on the resource type. For example, the Partition Table resource type offers family, layout, and name as query parameters.
- operator specifies the type of comparison between field_name and value. See Table 4.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. Two types of wildcard characters are supported: underscore (_) provides single character replacement, while percent sign (%) replaces zero or more characters.
Table 4.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. |
hostgroup = host-editors
Dev
Note
Example 4.1. Creating an Organization-specific Manager Role
- Navigate to Administer → Roles.
- 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 example org-1 Manager.
- Click Filters next to org-1 Manager to view the filters associated with the role. All filters are marked as unlimited.
- For each filter, click Edit.
- If the filter contains the Organizations tab, navigate to it. Otherwise it is a global setting that cannot be limited.
- On the Organizations tab, select org-1. Click Submit.
- The restricted filters are no longer marked as unlimited. Users assigned with the org-1 Manager role can now perform management tasks only in the selected organization.
Chapter 5. Backup and Disaster Recovery
5.1. Backing up Satellite Server or Capsule Server
katello-backup
script. Backing up to a separate location is recommended. Backing up to a separate storage device on a separate system is highly recommended. As no Satellite services will 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 other administrators for the same time. This is particularly important when administrators are working in different locations and time zones.
- When creating a snapshot or conventional backup, stop all services (Do not do this if using the
katello-backup
script):#
katello-service stop
Start the services after creating a snapshot or conventional backup:#
katello-service start
katello-backup
script to make and restore backups. To see the usage statement, enter a command as follows:
# katello-backup --help
katello-backup
creates a time-stamped subdirectory in the backup directory you specify. The katello-backup
script does not overwrite backups and the correct directory or subdirectory has to be selected when restoring from a backup or an incremental backup. The script will stop and restart services as required.
Known Issues
katello-backup
script has the following known issues:
- In Satellite 6.2.7 and earlier:
- The script does not support using the same directory multiple times for a full backup. Update to Satellite 6.2.8 or newer if possible. Alternatively, use a new directory every time or move the previous backup to a safe location until the new backup has completed successfully.
- If an existing directory is used as the backup target directory, the script will change the group to the
postgres
group. This can have unexpected consequences if other processes are also using the directory. Update to Satellite 6.2.8 or newer if possible. Alternatively, use a new directory or subdirectory exclusively for backups.
- In Satellite 6.2.8 and earlier, using the
--online-backup
option leaves Satellite services down. Update to Satellite 6.2.9 or newer if possible. Additionally, until Red Hat Bug 1432013 is resolved, use only the/tmp/
or/var/tmp/
directory to create online backups. - In Satellite 6.2.9 and earlier, using the
--incremental
option created full backups. This was fixed in Red Hat Bug 1445989 included in the asynchronous erratum RHBA-2017:1234 - Bug Fix Advisory. On Satellite 6.2.9, apply the erratum or upgrade to a newer version if possible.
Checking the Satellite or Capsule Version
# yum info satellite
Procedure 5.1. To Perform a Full Backup of Satellite Server or Capsule Server:
- Ensure your backup location has enough disk space to contain a copy of the following directories:
/etc/
/var/lib/pulp/
/var/lib/mongodb/
/var/lib/pgsql/
In Satellite 6.2.7 and earlier, the backup target directory must be a new directory or subdirectory created exclusively for backups. You can use thedu -sh directory_name
command to check the space used by a directory. - Request other users of Satellite Server or Capsule Server to save any changes and warn them that for the duration of the backup, no Satellite services will be available. Ensure that no other tasks are scheduled for the same time as the backup.
- Run the backup script:
#
katello-backup backup_directory
Thekatello-backup
script stops all services which could impact the backup, performs the backup, then restarts the required services. If the target directory does not exist when trying to create a backup file the script will create it.Note
From Satellite 6.2.13 thekatello-backup
script prompts for confirmation that the backup is to proceed. To run the backup without being prompted, add parameter--assumeyes
.This process can take a long time to complete, due to the amount of data to copy.
Procedure 5.2. To Perform a Backup without Pulp Content:
- Ensure your backup location has enough disk space to contain a copy of the following directories:
/etc/
/var/lib/mongodb/
/var/lib/pgsql/
You can use thedu -sh directory_name
command to check the space used by a directory. - Request other users of Satellite Server or Capsule Server to save any changes and warn them that for the duration of the backup, no Satellite services will be available. Ensure that no other tasks are scheduled for the same time as the backup.
- Run the backup script:
#
katello-backup --skip-pulp-content backup_directory
Thekatello-backup
script stops all services which could impact the backup, performs the backup, then restarts the required services. If the target directory does not exist when trying to create a backup file the script will create it.Note
From Satellite 6.2.13 thekatello-backup
script prompts for confirmation that the backup is to proceed. To run the backup without being prompted, add parameter--assumeyes
.
Procedure 5.3. To Perform an Incremental Backup:
- Ensure your backup location 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/
You can use thedu -sh directory_name
command to check the space used by a directory. - Request other users of Satellite Server or Capsule Server to save any changes and warn them that for the duration of the backup, no Satellite services will be available. Ensure that no other tasks are scheduled for the same time as the backup.
- Run the backup script:With Pulp content:
#
katello-backup backup_directory --incremental backup_directory/previous_time-stamped_subdirectory
Without Pulp content:#
katello-backup backup_directory --skip-pulp-content --incremental backup_directory/previous_time-stamped_subdirectory
Thekatello-backup
script stops all services which could impact the backup, performs the backup, then restarts the required services. If the target directory does not exist when trying to create a backup file the script will create it. It is possible to make incremental backups using a backup older than the previous backup as a starting point, but with a corresponding increase in time to make the backup.Note
From Satellite 6.2.13 thekatello-backup
script prompts for confirmation that the backup is to proceed. To run the backup without being prompted, add parameter--assumeyes
.
Procedure 5.4. To Perform an Online Backup:
Note
/tmp/
or /var/tmp/
directory to create online backups.
Important
--online-backup
option keeps all services running which means there is a possibility that data can be modified while the backup is being made. There is a basic check to see if the databases were modified during the backup. If this occurs, the script starts the database portion of the backup again. This check is rudimentary and cannot ensure with 100% certainty that there were no modifications to the databases while the backup script was running. This check can also result in repeated loops if there is continuous modification occurring to the databases.
--online-backup
method in production, ensure that no modifications occur during the backup.
- Ensure you have updated to Satellite 6.2.9 or later. To check the version of Satellite 6, use a command as follows:
#
yum info satellite
- Ensure your backup location has enough disk space to contain a copy of the following directories:
/etc/
/var/lib/pulp/
/var/lib/mongodb/
/var/lib/pgsql/
You can use thedu -sh directory_name
command to check the space used by a directory. - Request other users of Satellite Server or Capsule Server to save any changes and ask them not to make changes to repositories and Content Views for the duration of the backup. Ensure that no other tasks, such as synchronizing of repositories, are scheduled for the same time as the backup.
- Run the backup script:
#
katello-backup --online-backup /tmp/backup_directory
Note
From Satellite 6.2.13 thekatello-backup
script prompts for confirmation that the backup is to proceed. To run the backup without being prompted, add parameter--assumeyes
.
Example 5.1. A Weekly Full Backup Followed by Daily Incremental Backups
#!/bin/bash -e DESTINATION=/var/backup if [[ $(date +%w) == 0 ]]; then katello-backup $DESTINATION --assumeyes else LAST=$(ls -td -- $DESTINATION/*/ | head -n 1) katello-backup $DESTINATION --incremental "$LAST" --assumeyes fi exit 0
--assumeyes
parameter only if your Satellite version is 6.2.13 and higher.
5.2. Restoring Satellite Server or Capsule Server from a Backup
Prerequisites
- Ensure you are restoring to the correct instance. The Red Hat Satellite instance must have the same host name, configuration, and be the same major version as the original system.
- Run the
katello-restore
script asroot
. - All SELinux contexts must be correct. Enter the following command to restore the correct SELinux contexts:
#
restorecon -Rnv /
Procedure 5.5. To Restore Satellite Server or Capsule Server from a Full Backup:
- Install Satellite 6 using the procedures in the Red Hat Satellite 6 Installation Guide[1].
- Copy the backup data to the Satellite's local file system. Use
/tmp/
or/var/tmp/
. Ensure you have enough space to store this data on the base system of Satellite Server or Capsule Server as well as enough space after the restoration to contain all the data in the/etc/
and/var/
directories contained within the backup.You can use thedu -sh directory_name
command to check the space used by a directory and thedf -h directory_name
command to check for free space. Add the--total
option to sum the results from more than one directory. - Run the restoration script:
#
katello-restore backup_directory
Where backup_directory is the time-stamped directory or subdirectory containing the backed-up data. The target directory will be read from the configuration files contained within the archive. If the target directory does not exist when trying to recover, it will give an error and ask for the correct directory. The restore process can take a long time to complete, due to the amount of data to copy. Where incremental backups exist, see Procedure 5.6, “To Restore Satellite Server or Capsule Server from an Incremental Backup:”.
Procedure 5.6. To Restore Satellite Server or Capsule Server from an Incremental Backup:
- Install Satellite 6 using the procedures in the Red Hat Satellite 6 Installation Guide[2].
- Restore the last full backup as described in Procedure 5.5, “To Restore Satellite Server or Capsule Server from a Full Backup:”.
- 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 the base system of Satellite Server or Capsule Server as well as enough space after the restoration to contain all the data in the/etc/
and/var/
directories contained within the backup. - Run the restoration script:
#
katello-restore backup_directory_X
Where backup_directory_X is a time-stamped directory or subdirectory containing an incremental backup. Restore the incremental backups in the same sequence that they were made. For example: backup_directory_1, backup_directory_2. The target directory will be read from the configuration files contained within the archive. If the target directory does not exist when trying to recover, it will give an error and ask for the correct directory.
5.3. Backing up and Restoring Capsule Server Using a Snapshot
- Using the
katello-backup
script as described in Section 5.1, “Backing up Satellite Server or Capsule Server”. Thekatello-backup
script is convenient if your Capsule Server is a physical machine. You can also use the script if your Capsule Server is a virtual machine but it creates only a backup of the data and not the machine itself. - Using the conventional backup methods as described in System Backup and Recovery in the Red Hat Enterprise Linux 7 System Administrator's Guide.
- Using the snapshot as described below.
Note
katello-backup
script):
# katello-service stop
# katello-service start
certs-tar
, alternately create new ones. Follow the procedures in Installing Capsule Server in the Red Hat Satellite 6 Installation Guide until you see in the web UI that the Capsule Server is connected to the Satellite Server. Then synchronize from the Satellite Server as described below.
Procedure 5.7. Synchronizing an External Capsule
- To synchronize an external Capsule, select the relevant organization and location in the web UI, or choose Any Organization and Any Location.
- Navigate to Infrastructure → Capsules and click the name of the Capsule to synchronize.
- On the Overview tab, select Synchronize.
5.4. Renaming a Satellite Server or Capsule Server
katello-change-hostname
script. Red Hat Satellite contains references to the host's name and these changes are made using the script. Renaming a Satellite Server affects itself, all Capsule Servers and all hosts registered to it. Renaming a Capsule Server affects itself and all hosts registered to it.
Warning
Warning
katello-change-hostname
script. If the system host name has been changed before running this script, the script will fail when searching for the old host name.
5.4.1. Renaming a Satellite Server
Prerequisites
- (Optional) If the Satellite Server has a custom X.509 certificate installed, a new certificate must be obtained in the host's new name. When all hosts are re-registered to the Satellite Server, the new certificate is installed. For more information on obtaining a custom X.509 certificate, see Configuring Satellite Server with a Custom Server Certificate in the Installation Guide.
- Ensure the system host name has not been changed before running the
katello-change-hostname
script. If the system host name has been changed, you must revert it to the original host name by using thehostnamectl set-hostname
command. - Backup the Satellite Server. The
katello-change-hostname
script makes irreversible changes to the Satellite Server. If the renaming process is not successful, you must restore it from backup. For more information, see Chapter 5, Backup and Disaster Recovery.
Procedure 5.8. Rename a Satellite Server
- On the Satellite Server, run the
katello-change-hostname
script, providing the host's new name, and Satellite credentials.# katello-change-hostname new_satellite --username admin \ --password password
The message**** Hostname change complete! ****
confirms that the rename completed successfully. - (Optional) If you have obtained a new X.509 certificate for the Satellite Server's new host name, run the Satellite installation script to install the certificate. For more information on installing a custom X.509 certificate, see Configuring Satellite Server with a Custom Server Certificate in the Installation Guide.
- On all Capsule Servers and hosts registered to the Satellite Server, reinstall the bootstrap RPM and re-register them to the Satellite Server. Substitute the example organization and environment values with those matching your environment.
# yum remove -y katello-ca-consumer*
# rpm -Uvh http://new-satellite.example.com/pub/katello-ca-consumer-latest.noarch.rpm
# subscription-manager register --org="Default_Organization" \ --environment="Library" \ --force
Use of the Red Hat Satellite remote execution feature is recommended for this step. For details, see Running Jobs on Satellite Hosts in the Host Configuration Guide. - Reattach subscriptions to all Capsule Servers and hosts registered to the Satellite Server, then refresh the subscription.
# subscription-manager refresh
# yum repolist
Use of the Red Hat Satellite remote execution feature is recommended for this step. For details, see Running Jobs on Satellite Hosts in the Host Configuration Guide. - On all Capsule Servers, re-run the Satellite installation script to update references to the new host name.
# satellite-installer --capsule-parent-fqdn new-satellite.example.com \ --foreman-proxy-foreman-base-url https://new-satellite.example.com \ --foreman-proxy-trusted-hosts new-satellite.example.com
5.4.2. Renaming a Capsule Server
Prerequisites
- (Optional) New X.509 custom certificate files for the Capsule Server. For more information on obtaining a custom X.509 certificate, see Configuring Capsule Server with a Custom Server Certificate in the Installation Guide.
- Backup the Capsule Server. The
katello-change-hostname
script makes irreversible changes to the Capsule Server. If the renaming process is not successful, you must restore it from backup.Red Hat Satellite does not provide a native backup method for a Capsule Server. For more information, see Chapter 5, Backup and Disaster Recovery.
Procedure 5.9. Rename a Capsule Server
- On the Satellite Server, create a new certificates archive file.
- If you are using the default Satellite Server certificate:
# capsule-certs-generate --capsule-fqdn "new-capsule.example.com" \ --certs-tar "new-capsule.example.com-certs.tar"
- If you are using a custom X.509 certificate on the Capsule Server, see Create the Capsule Server's Certificate Archive File in the Installation Guide.
- On the Satellite Server, copy the certificates archive file to the Capsule Server, providing the
root
user’s password when prompted. In this example the archive file is copied to theroot
user’s home directory, but you may prefer to copy it elsewhere.# scp /root/new-capsule.example.com-certs.tar root@capsule.example.com:
- On the Capsule Server, run the
katello-change-hostname
script, providing the host's new name, Satellite credentials, and certificates archive filename.# katello-change-hostname new_capsule --username admin \ --password password \ --certs-tar new-capsule.example.com-certs.tar
The message**** Hostname change complete! ****
confirms that the rename completed successfully. - (Optional) If you have obtained a new X.509 certificate in the Capsule Server's new host name, run the Satellite installation script to install the certificate. For more information on installing a custom X.509 certificate, see Configuring Satellite Server with a Custom Server Certificate in the Installation Guide.
- On all hosts registered to the Capsule Server, reinstall the bootstrap RPM and re-register them to the Capsule Server. Substitute the example organization and environment values with those matching your environment.
# yum remove -y katello-ca-consumer*
# rpm -Uvh http://new-capsule.example.com/pub/katello-ca-consumer-latest.noarch.rpm
# subscription-manager register --org="Default_Organization" \ --environment="Library" \ --force
Use of the Red Hat Satellite remote execution feature is recommended for this step. For details, see Running Jobs on Satellite Hosts in the Host Configuration Guide. - Reattach subscriptions to all hosts registered to the Capsule Server, then refresh the subscription.
# subscription-manager refresh
# yum repolist
Use of the Red Hat Satellite remote execution feature is recommended for this step. For details, see Running Jobs on Satellite Hosts in the Host Configuration Guide. - Edit the Capsule Server's name.
- In the Satellite web UI, navigate to Infrastructure → Capsules.
- Find the Capsule Server in the list, and click Edit in that row.
- Edit the Name and URL fields to match the Capsule Server's new host name, then click Submit.
- On your DNS server, add a record for the Capsule Server's new host name, and delete the record for the previous host name.
Chapter 6. Maintaining a Red Hat Satellite Server
6.1. Logging and Reporting
Table 6.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 Hat Enterprise Linux 7, respectively.
|
/var/log/messages
|
Various other log messages related to pulp, rhsm, and goferd.
|
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.
6.2. Enabling Debug Logging
/etc/foreman/settings.yaml
file.
Set the Logging Level to "debug"
By default, the logging level is set toinfo
, as in the following::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 toerror
is not recommended.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
Restart Katello Services
#
katello-service restart
:app: :enabled: true :ldap: :enabled: false :permissions: :enabled: false :sql: :enabled: false
6.3. Collecting Information from Log Files
Table 6.2. Log Collecting Utilities
Command
|
Description
|
---|---|
foreman-debug |
The
foreman-debug command collects configuration and log file data for Red Hat Satellite, its back-end services, and system information. 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 .
Additionally, the
foreman-debug command exports tasks run during the last 60 days. By default, the output tar file is located at /tmp/task-export-xxx.tar.xz . If the file is missing, see the file /tmp/task-export.log to learn why task export was unsuccessful.
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 and diagnostic information from a Red Hat Enterprise Linux system, such as the running kernel version, loaded modules, and system and service configuration files. The command also runs external programs (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 see https://access.redhat.com/solutions/3592: What is a sosreport and how can I create one?.
The
sosreport command calls the foreman-debug -g and times out after 500 seconds. If your Satellite Server has large log files or many Satellite tasks, support engineers may require the output of sosreport and foreman-debug when you open a support case.
|
Important
foreman-debug
and sosreport
remove security information such as passwords, tokens, and keys while collecting information. However, the tar files can still contain sensitive information about the Red Hat Satellite Server. Red Hat recommends that you send this information directly to the intended recipient and not to a public target.
6.4. Using Log Files in Support Cases
- Section 6.5.5, “Creating Support Cases Using the Red Hat Access Plug-in”: How to open a support case from the Satellite web UI
- https://access.redhat.com/articles/38363: How to open and manage a support case on the Customer Portal
6.5. Accessing Customer Portal Services from Red Hat Satellite
- 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 these log snippets to the Red Hat Customer Portal diagnostic tool chain.
- Support: Access your open support cases, modify an open support case and open a new support case from within the Satellite web UI.
Note
6.5.1. Searching for Solutions in the Red Hat Access Plug-in
Procedure 6.1. To Search for Solutions from the Red Hat Satellite Server:
- In the upper right, click Red Hat Access → Search.
- If necessary, log in to the Red Hat Customer Portal. In the main panel on the upper right, click Log In.
Note
To access Red Hat Customer Portal resources, you must log in with your Red Hat Customer Portal user identification and password. - In the Red Hat Search field, enter your search query. Search results display in the left-hand Recommendations list.
- In the Recommendations list, click a solution. The solution article displays in the main panel.
6.5.2. Using Logs in the Red Hat Access Plug-in
Procedure 6.2. To Use the Logs Diagnostic Tool from the Red Hat Satellite Server:
- In the upper right, click Red Hat Access → Logs.
- If necessary, log in to the Red Hat Customer Portal. In the main panel on the upper right, click Log In.
Note
To access Red Hat Customer Portal resources, you must log in with your Red Hat Customer Portal user identification and password. - In the left file tree, select a log file and click the file name.
- Click Select File. A pop-up window displays the log file contents.
- In the log file, highlight any text sections you want diagnosed. The Red Hat Diagnose button displays.
- Click Red Hat Diagnose. The system sends the highlighted information to the Red Hat Customer Portal, and provides solutions that closely match the provided log information.
- If a solution does the following:
- Matches the problem, click the solution and follow the required steps to troubleshoot the issue.
- Does not match the problem, click Open a New Support Case. The support case is populated with the highlighted text from the log file. See Section 6.5.5, “Creating Support Cases Using the Red Hat Access Plug-in”.
6.5.3. Viewing Existing Support Cases Using the Red Hat Access Plug-in
Procedure 6.3. To View Existing Support Cases from the Red Hat Satellite Server:
- In the upper right, click Red Hat Access → Support → My Cases.
- If necessary, log in to the Red Hat Customer Portal. In the main panel on the upper right, click Log In.
Note
To access Red Hat Customer Portal resources, you must log in with your Red Hat Customer Portal user identification and password. - To search for a specific support case from existing cases, do any of the following:
- In the Search field, provide a key word or phrase.
- From the drop-down list, choose a specific Case Group. Your organization has defined Case Groups inside the Red Hat Customer Portal.
- Choose a Case Status.
- From the results, choose a specific support case and click the Case ID. The support case is ready to view.
6.5.4. Modifying Support Cases Using the Red Hat Access Plug-in
Procedure 6.4. To Update Support Cases from the Red Hat Satellite Server Web UI:
- Complete the instructions from Section 6.5.3, “Viewing Existing Support Cases Using the Red Hat Access Plug-in”
- 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 easier to identify.
Note
File names must be less than 80 characters and the maximum file size for attachments 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 discuss with Global Support Services. After adding information, click Add Comment.
6.5.5. Creating Support Cases Using the Red Hat Access Plug-in
Procedure 6.5. To Create a New Support Case Using the Red Hat Satellite Server:
- In the upper right, click Red Hat Access → Support → New Case.
- If necessary, log in to the Red Hat Customer Portal. In the main panel on the upper right, click Log In.
Note
To access Red Hat Customer Portal resources, you must log in with your Red Hat Customer Portal user identification and password. - The Product and Product Version fields are automatically populated. Complete the other 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 the main panel. - Click Next.
- 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 associated with the support case. Select Case Groups in Red Hat Satellite. Create Case Groups within the Customer Portal.
- 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 also attach the output of
foreman-debug
. - File names must be less than 80 characters and the maximum file size for attachments uploaded using the web UI is 250 MB. Use FTP for larger files.
- Click Submit. The system uploads the case to the Customer Portal, and provides a case number for your reference.
6.6. Using Red Hat Insights with Satellite Server
6.7. Monitoring Satellite Server in the Web UI
- System Status, including Capsules, Available Providers, Compute Resources, and Plug-ins
- Support information
- System Information
- Backend System Status
- Installed packages
- In the upper right corner of the Satellite Server web UI, click Administer → About.
Note
Chapter 7. Monitoring Capsule Servers
7.1. Viewing General Capsule Information
- Is the Capsule Server running?
- This is indicated by a green icon in the Status column. A red icon indicates an inactive Capsule, use the
service foreman-proxy restart
command on the Capsule Server to activate it. - What services are enabled on the Capsule Server?
- In the Features column you can verify if the Capsule for example provides a DHCP service or acts as a Pulp node. Capsule features can be enabled during installation or configured 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 only Capsules belonging to the currently selected organization are displayed. To list all Capsules, select Any Organization from the context menu in the top left corner.
- Which hosts are managed by the Capsule Server?
- The number of associated hosts is displayed next to the Hosts managed label. Click the 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 remaining storage space available on the Capsule can be ascertained.
7.2. Monitoring Services
7.3. Monitoring Puppet
- A summary of Puppet events, an overview of latest Puppet runs, and the synchronization status of associated hosts at the General sub-tab.
- A list of Puppet environments at the Environments sub-tab.
- 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. Here you 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 by clicking New or delete one by clicking Delete.
Chapter 8. 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 8.1, “Using LDAP”. Though you can use LDAP to connect to an IdM or AD server, the setup does not support server discovery, cross-forest trusts, or single sign-on with Kerberos on Satellite's web UI.
- Using Red Hat Enterprise Linux Identity Management (IdM) server as an external identity provider. IdM deals with the management of individual identities, their credentials and privileges used in a networking environment. For more information see Section 8.2, “Using Identity Management”.
- Using Active Directory (AD) integrated with IdM through cross-forest Kerberos trust as an external identity provider. For more information see Section 8.3.1, “Using Active Directory with Cross-Forest Trust”.
- Using direct AD as an external identity provider. For more information see Section 8.3.2, “Using Active Directory Directly”.
8.1. Using LDAP
8.1.1. Configure TLS for Secure LDAP (LDAPS)
Note
TLS
to establish a secure LDAP connection (LDAPS), first obtain certificates used by the LDAP server you are connecting to and mark them as trusted on the base operating system of your Satellite Server as described below. If your LDAP server uses a certificate chain with intermediate certificate authorities, all of the root and intermediate certificates in the chain must be trusted, so ensure all certificates are obtained. If you do not require secure LDAP at this time, proceed to Procedure 8.1, “To Configure LDAP Authentication:”.
Obtain the Certificate from the LDAP Server
TLS
on Satellite 6.2 for information on creating and exporting a CA certificate from an Active Directory server.
/tmp/example.crt
. The filename extensions .cer
and .crt
are only conventions and can refer to DER binary or PEM ASCII format certificates.
Trust the Certificate from the LDAP Server
/etc/pki/tls/certs/
directory.
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/
root
to trust the example.crt certificate obtained from the LDAP server:
# ln -s example.crt /etc/pki/tls/certs/$(openssl x509 -noout -hash -in /etc/pki/tls/certs/example.crt).0
httpd
service:
- On Red Hat Enterprise Linux 6:
# service httpd restart
- On Red Hat Enterprise Linux 7:
# systemctl restart httpd
8.1.2. Configuring Red Hat Satellite to Use LDAP
Procedure 8.1. To Configure LDAP Authentication:
- Set the allow Network Information System (NIS) service boolean to true to prevent SELinux from stopping outgoing LDAP connections:
- For Red Hat Enterprise Linux 6:
# setsebool -P allow_ypbind on
- For Red Hat Enterprise Linux 7:
# setsebool -P nis_enabled on
- Navigate to Administer → LDAP Authentication.
- Click New authentication source.
- On the LDAP server tab, enter the LDAP server's name, host name, port, and server type. The default port is 389, the default server type is POSIX (alternatively you can select FreeIPA or Active Directory depending on the type of authentication server). For
TLS
encrypted connections, select the LDAPS check box to enable encryption. The port should change to 636, which is the default for LDAPS. - On the Account tab, enter the account information and domain name details. See Section 8.1.3, “LDAP Setting Descriptions and Examples” for descriptions and examples.
- On the Attribute mappings tab, map LDAP attributes to Satellite attributes. You can map Login name, First name, Surname, Email address, and Photo attributes. See Section 8.1.3, “LDAP Setting Descriptions and Examples” for examples.
- On the Locations tab, select locations from the left table. Selected locations will be assigned to users created from the LDAP authentication source, and available after their first login.
- On the Organizations tab, select organizations from the left table. Selected organizations will be assigned to users created from the LDAP authentication source, and available after their first login.
- Click Submit.
8.1.3. LDAP Setting Descriptions and Examples
Table 8.1. Account Tab Settings
Setting | Description |
---|---|
Account 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 the full 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 a literal string. The value is accessed when the variable is expanded.
The variable cannot be used with external user groups from an LDAP source because Satellite needs to retrieve the group list without the user 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
$login variable.
|
Base DN |
The top level domain name of the LDAP directory.
|
Groups base DN |
The top level domain name of the LDAP directory tree that contains groups.
|
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 first time, Satellite user accounts are created automatically for them. Users will see a
Permissions Denied warning and need to contact their Satellite administrator to have their user account associated with roles.
|
Usergroup sync |
If this option is selected, the user group membership of a user is automatically synchronized when the user logs in, which ensures the membership is always up to date. If this option is cleared, Satellite relies on a Cron job to regularly synchronize group membership (every 30 minutes by default). See Procedure 8.6, “To Configure an External User Group:” for further context.
|
Table 8.2. Example Settings for Active Directory LDAP Connection
Setting | Example value |
---|---|
Account username | DOMAIN\redhat |
Account password | P@ssword |
Base DN | DC=example,DC=COM |
Groups Base DN | CN=Users,DC=example,DC=com |
Login name attribute | userPrincipalName |
First name attribute | givenName |
Surname attribute | sn |
Email address attribute |
Note
userPrincipalName
allows the use of whitespace in usernames. The login name attribute sAMAccountName
(which is not listed in the table above) provides backwards compatibility with legacy Microsoft systems. sAMAccountName
does not allow the use of whitespace in usernames.
Table 8.3. Example Settings for FreeIPA or Red Hat Identity Management LDAP Connection
Setting | Example value |
---|---|
Account username | uid=redhat,cn=users,cn=accounts,dc=example,dc=com |
Base DN | dc=example,dc=com |
Groups Base DN | cn=groups,cn=accounts,dc=example,dc=com |
Login name attribute | uid |
First name attribute | givenName |
Surname attribute | sn |
Email address attribute |
Table 8.4. Example Settings for POSIX (OpenLDAP) LDAP Connection
Setting | Example value |
---|---|
Account username | uid=redhat,ou=users,dc=example,dc=com |
Base DN | dc=example,dc=com |
Groups Base DN | cn=employee,ou=userclass,dc=example,dc=com |
Login name attribute | uid |
First name attribute | givenName |
Surname attribute | sn |
Email address attribute |
8.2. Using Identity Management
8.2.1. Using Identity Management Directly
Prerequisites
Procedure 8.2. To Configure IdM Authentication on the Satellite Server:
- On the IdM server, create a host entry for the Satellite Server and generate a one-time password, for example:
# ipa host-add --random hostname
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 7 Linux Domain Identity, Authentication, and Policy Guide[5]. - 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 Linux Domain Identity, Authentication, and Policy Guide[6]. - 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. - If the Satellite Server is running on Red Hat Enterprise Linux 7, execute the following command:
# subscription-manager repos --enable rhel-7-server-optional-rpms
The installer is dependent on packages which, on Red Hat Enterprise Linux 7, are in the optional repositoryrhel-7-server-optional-rpms
. On Red Hat Enterprise Linux 6 all necessary packages are in thebase
repository. - 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 an existing Satellite installation. - Restart Katello services:
# katello-service restart
Procedure 8.3. To Configure HBAC:
- Create HBAC service and rule on the IdM server and link them together. The following examples use the PAM service name satellite-prod. Execute the following commands on the IdM server:
$ ipa hbacsvc-add satellite-prod $ ipa hbacrule-add allow_satellite_prod $ ipa hbacrule-add-service allow_satellite_prod --hbacsvcs=satellite-prod
- Add the user who is to have access to the service satellite-prod, and the host name of the 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. - To check the status of the rule, execute:
$ ipa hbacrule-find satellite-prod $ ipa hbactest --user=username --host=the-satellite-fqdn --service=satellite-prod
- Ensure the allow_all rule is disabled on the IdM server. For instructions on how to do so without disrupting other services see the How to configure HBAC rules in IdM article on the Red Hat Customer Portal[8].
- Configure the IdM integration with the Satellite Server as described in Procedure 8.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
8.2.2. Using Identity Management with LDAP Authentication
8.3. Using Active Directory
8.3.1. Using Active Directory with Cross-Forest Trust
- To enable the HBAC feature, create an external group and add the AD group to it. Add the new external group to a POSIX group. Use this POSIX group in a HBAC rule.
- Configure sssd to transfer additional attributes of AD users. Add these attributes to the nss 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
8.3.2. Using Active Directory Directly
Note
Prerequisites
# yum install gssproxy nfs-utils
Procedure 8.4. To Enroll the Satellite Server with the AD Server:
- Install the required packages:
# yum install sssd adcli realmd ipa-python
- Enroll the Satellite Server with the AD server. You may need to have administrator permissions to perform the following command:
# realm join -v EXAMPLE.ORG
satellite-installer
command. This can be done for already installed Satellite or during the Satellite installation. Note that the Apache user must not have access to the keytab file. Also take note of the effective user ID of the Apache user (that can be found by executing id apache
). The following procedure uses the example UID 48.
Procedure 8.5. To Configure Direct AD Integration with GSS-proxy:
- Create the
/etc/ipa/default.conf
file with the following content:[global] server = unused realm = EXAMPLE.ORG
- Create the
/etc/net-keytab.conf
file with the following content:[global] workgroup = EXAMPLE realm = EXAMPLE.ORG kerberos method = system keytab security = ads
- Create the
/etc/gssproxy/00-http.conf
file with the following content:[service/HTTP] mechs = krb5 cred_store = keytab:/etc/krb5.keytab cred_store = ccache:/var/lib/gssproxy/clients/krb5cc_%U euid = 48
- Insert the following line at the beginning of the
/etc/krb5.conf
file:includedir /var/lib/sss/pubconf/krb5.include.d/
- Enable IPA authentication in Satellite:
# satellite-installer --foreman-ipa-authentication=true
- Start and enable the
gssproxy
service:# systemctl restart gssproxy.service # systemctl enable gssproxy.service
- Configure Apache HTTPD Server to use the
gssproxy
service:- Create 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
- Start and enable the
httpd
service:# systemctl restart httpd.service
With a running Apache HTTP Server, users making HTTP requests against the server are authenticated if the client has a valid Kerberos ticket.
Note
access_provider = ad ad_gpo_access_control = enforcing ad_gpo_map_service = +foreman
8.3.3. Using Active Directory with LDAP Authentication
8.4. Configuring External User Groups
Prerequisites
- If using an LDAP source, make sure the LDAP authentication is correctly configured. Navigate to Administer → LDAP Authentication to view and modify the existing sources. For instructions on how to create an LDAP source, see Section 8.1, “Using LDAP”. Take note of the LDAP group names you want to use.
Note
If you are using external user groups from an LDAP source, you cannot use the$login
variable as a substitute for the account user name. You need to use either an anonymous or dedicated service user. - If your Satellite is enrolled with the IdM or AD server as described in Chapter 8, Configuring External Authentication, take note of the external group names you want to use. To find the group membership of external users, execute the
id
command on Satellite:# id username
Here, username is the name of the external group member. Note that Satellite allows you to configure external groups only after at least one external user authenticates for the first time. Also, at least one user must exist in the external authentication source.
Procedure 8.6. To Configure an External User Group:
- Navigate to Administer → User Groups. Click New User Group.
- On the User group tab, specify the name of the new user group. Do not select any users as they will be added automatically when refreshing the external user group.
- 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.
- On the External groups tab, click Add external user group and select an authentication source from the Auth source drop-down menu.Specify the exact name of the LDAP or external group in the Name field.
- Click Submit.
Important
foreman-rake ldap:refresh_usergroups
or by refreshing the external user groups through the web UI.
8.5. External Authentication for Provisioned Hosts
8.5.1. Configuring a Red Hat Satellite Server or Capsule Server for IdM Realm Support
Prerequisites
- A Satellite Server is registered to the content delivery network, an independent Capsule Server is registered to the Satellite Server.
- A realm or domain provider such as Red Hat Identity Management is configured.
Procedure 8.7. To configure the Satellite Server or Capsule Server for IdM Realm Support:
- On the Satellite Server or Capsule Server, install the following packages:
# yum install ipa-client foreman-proxy ipa-admintools
- Configure the Satellite Server (or Capsule Server) as an IdM client:
# ipa-client-install
- Create a realm-capsule user and the relevant roles in Red Hat Identity Management on the Satellite Server or Capsule Server:
# foreman-prepare-realm admin realm-capsule
Running foreman-prepare-realm will prepare an IdM server for use with the Capsule Server. It creates a dedicated role with the permissions needed for Satellite, creates a user with that role and retrieves the keytab file. You will need your Identity Management server configuration details on this step.If the command successfully executes, you should be able to see the following command output:Keytab successfully retrieved and stored in: freeipa.keytab Realm Proxy User: realm-capsule Realm Proxy Keytab: /root/freeipa.keytab
Note
To configure Satellite Server and at least one external Capsule Server for IdM Realm support with the same principal and realm, you must copy the/root/freeipa.keytab
file to all the previously joined Capsule Servers after running theforeman-prepare-realm
script.# scp /root/freeipa.keytab your_username@capsule.example.com:/etc/foreman-proxy/freeipa.keytab
- Move the
/root/freeipa.keytab
to the/etc/foreman-proxy
directory and set the ownership settings to the user foreman-proxy:# mv /root/freeipa.keytab /etc/foreman-proxy # chown foreman-proxy:foreman-proxy /etc/foreman-proxy/freeipa.keytab
- Configure the realm based on whether you are using Satellite Server or Capsule Server:
- 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 'realm-capsule@EXAMPLE.COM' \ --foreman-proxy-realm-provider freeipa
Note
You can also run these options when you first configure the Red Hat Satellite Server. - 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 'realm-capsule@EXAMPLE.COM' \ --realm-provider freeipa
- Make sure that the most updated versions of the ca-certificates package is installed and trust the IdM Certificate Authority:
# cp /etc/ipa/ca.crt /etc/pki/ca-trust/source/anchors/ipa.crt # update-ca-trust enable # update-ca-trust
- (Optional) If you are configuring IdM on an already existing Satellite Server or Capsule Server, the following steps should also be taken to make sure that the configuration changes take effect:
- Restart the foreman-proxy service:
# service foreman-proxy restart
- Log in to the Satellite Server and click Infrastructure → Capsules.
- Click on the drop-down menu on the right-hand side of the Capsule Server you have configured for IdM and choose Refresh Features.
- Finally, create a new realm entry in the Satellite Server user interface:
- Click Infrastructure → Realms and on the right-hand corner of the main page, click New Realm.
- Fill in the fields in the following subtabs:
- On the Realm subtab, provide the realm name, the type of realm to use and the realm proxy.
- On the Locations subtab, choose the locations where the new realm is intended for use.
- On the Organizations subtab, choose the organizations where the new realm is intended for use.
- Click Submit.
8.5.2. Adding Hosts to an IdM Host Group
Note
Procedure 8.8. To Add Hosts to an IdM Host Group:
- On the IdM server, create a host group:
# ipa hostgroup-add hostgroup_name Description: hostgroup_description ---------------------------- Added hostgroup "hostgroup_name" ---------------------------- Host-group: hostgroup_name Description: hostgroup_description
Where:- hostgroup_name is the host group's name.
- hostgroup_description is the host group's description.
- Create an automembership rule:
# ipa automember-add --type=hostgroup automember_rule ---------------------------------- Added automember rule "automember_rule" ---------------------------------- Automember Rule: automember_rule
Where:automember-add
flags the group as an automember group.--type=hostgroup
identifies that the target group is a host group, not a user group.- automember_rule is the name you wish to identify the automember rule by.
- Define an automembership condition based on the userclass attribute:
# ipa automember-add-condition --key=userclass --type=hostgroup --inclusive-regex=^webserver hostgroup_name ---------------------------------- Added condition(s) to "hostgroup_name" ---------------------------------- Automember Rule: automember_rule Inclusive Regex: userclass=^webserver ---------------------------- Number of conditions added 1 ----------------------------
Where:automember-add-condition
allows you to add regular expression conditions to identify group members.--key=userclass
specifies the key attribute as userclass.--type=hostgroup
identifies that the target group is a host group, not a user group.--inclusive-regex=
^webserver is a regular expression pattern to identify matching values.- hostgroup_name is the target host group's name.
Chapter 9. Customizing Satellite Server
9.1. Adding Additional Plug-ins
root
:
# yum search rubygem-foreman
Loaded 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 integration
tfm-rubygem-foreman_abrt.noarch : Display reports from Automatic Bug Reporting Tool in Foreman
tfm-rubygem-foreman_bootdisk.noarch : Create boot disks to provision hosts with Foreman
output truncated
To view the currently installed plug-ins, enter as root
:
# yum list installed | grep rubygem-foreman
root
:
# yum install rubygem-foreman_scap_client.noarch
Restart the Foreman service for the plug-in to be registered:
# touch ~foreman/tmp/restart.txt
Important
Adding Plug-ins from the Foreman Repository
$ rpm -q foreman
foreman-1.7.2.53-1.el7sat.noarch
# /etc/yum.repos.d/foreman-plugins.repo
[foreman-plugins]
name=Foreman plugins
baseurl=http://yum.theforeman.org/plugins/1.10/elX/x86_64/
enabled=1
gpgcheck=0
Where X is 6
or 7
for Red Hat Enterprise Linux 6 or 7 respectively. Change the version number in the URL to match the Foreman release in use. Note the packages are not currently GPG signed.
- Find the package for the plug-in with the search function. For example, to search for a plug-in with the word "discovery" in the name:
#
Alternately check the plug-in documentation for the name of the plug-in.yum search discovery
- Install the package, for example:
#
yum install tfm-rubygem-foreman_discovery
- Restart the Foreman service for the plug-in to be registered:
#
touch ~foreman/tmp/restart.txt
9.2. Using Foreman Hooks
Note
root
:
# yum install tfm-rubygem-foreman_hooks
Loaded plugins: product-id, search-disabled-repos, subscription-manager
Package tfm-rubygem-foreman_hooks-0.3.9-2.el7sat.noarch already installed and latest version
Nothing to do
/usr/share/foreman/config/hooks/
. A subdirectory must be created for each Foreman object, with further subdirectories created for each event name. A Foreman 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
# mkdir -p /usr/share/foreman/config/hooks/host/managed/before_provision/
install
command as follows to ensure the SELinux context is correct: install hook_script /usr/share/foreman/config/hooks/object/event/hook_scriptAlternately, if you created the script directly in the event subdirectory then apply the SELinux context 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 Hat Enterprise Linux 7. Keep in mind that the script is running confined, therefore some actions might be denied by SELinux. Check for actions denied by SELinux by running aureport -a
or looking in /var/log/audit/audit.log
.
audit2allow
utility:
- On Red Hat Enterprise Linux 6, see Fixing Problems[12].
- On Red Hat Enterprise Linux 7, see Fixing Problems[13].
Procedure 9.1. Creating a Foreman Hook to Use the logger Command
- Create the directory structure on the Satellite Server base system:
#
mkdir -p /usr/share/foreman/config/hooks/host/managed/before_provision/
- Create the script as follows:
#
The numeric prefix 10 to the file namevi /usr/share/foreman/config/hooks/host/managed/before_provision/10_logger.sh
#!/bin/bash/ logger $1 $2_logger.sh
determines the order of execution for scripts in the same subdirectory. Change this prefix to suit your needs. - Change the script owner to
foreman
:#
chown foreman:foreman 10_logger.sh
- Change the script permissions to allow execution by the user:
#
chmod u+x 10_logger.sh
- Ensure the SELinux context is correct on all files in the
/usr/share/foreman/config/hooks
directory:#
restorecon -RvF /usr/share/foreman/config/hooks/
- To enable the
foreman
user to use thelogger
command, add the following rule to the/etc/sudoers
file:#
vi /etc/sudoers
foreman ALL=(ALL) NOPASSWD:/usr/bin/logger - Restart the Foreman service for the hook to be registered:
#
touch ~foreman/tmp/restart.txt
/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 with Foreman hooks, for example "active_record" or "habtm". These are most commonly used:
- host
- report
9.2.1. Orchestration Events
- create
- update
- destroy
9.2.2. Rails Events
- after_create
- before_create
- after_destroy
- before_destroy
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.
9.2.3. Execution of hooks
foreman
user. The first argument is always the event name, enabling scripts to be symbolically linked into multiple event directories. The second argument is the string representation of the object that was hooked, for example the host name for a host: ~foreman/config/hooks/host/managed/create/50_register_system.sh create foo.example.com
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 which would block the Foreman thread.
echo '{"host":{"name":"foo.example.com"}}' \ | ~foreman/config/hooks/host/managed/create/50_register_system.sh \ create foo.example.com