1. Introduction to Content Management

In the context of Foreman, content is defined as the software installed on systems. This includes, but is not limited to, the base operating system, middleware services, and end-user applications. With Foreman, you can manage the various types of content at every stage of the software life cycle.

Important
 The Katello plug-in provides content management features to Foreman. You can only use this guide if you have the Katello plug-in installed.

Foreman manages the following content:

Red Hat Subscription management

This provides organizations with a method to store Red Hat content and organize it in various ways.

SUSE Subscription management

This provides organizations with a method to store SUSE content and organize it in various ways. Note that this requires the Foreman SCC Manager plug-in. For more information, see Managing SUSE Content.

Content management

This provides organizations with a method to store APT and YUM content and organize it in various ways.

2. Content Management Types Overview

With Foreman, you can manage the following content types:

RPM Packages

Import RPM packages from any repository, for example from Red Hat, SUSE, and custom repositories. Foreman server downloads the RPM files and stores them locally. You can use these repositories and their RPM files in Content Views.

DEB Packages

Import DEB packages from repositories, for example for Debian or Ubuntu. You can also import single DEB packages or synchronize custom repositories. You can use these repositories and their DEB files in Content Views.

Provisioning Templates

You can provision hosts running EL based on synchronized content and Debian, Ubuntu, or SUSE Linux Enterprise Server based on local installation media. Foreman contains predefined AutoYaST, kickstart, and Preseed templates as well as the ability to create your own, which are used to provision systems and customize the installation.

You can also manage other types of content in Foreman. For example:

ISO and KVM Images

Download and manage media for installation and provisioning. For example, Foreman downloads, stores, and manages ISO images and guest images for specific Red Hat Enterprise Linux and non-Red Hat operating systems.

OSTree

You can import OSTree branches and publish this content to an HTTP location for consumption by OSTree clients.

You can use the procedure to add content for any type of content you require, for example, SSL certificates and OVAL files.

3. Basic Content Management Workflow

This is a quick overview of the tasks involved in the basic content management workflow in Foreman. If you have installed Foreman with Katello and want to synchronize and manage Enterprise Linux content on your hosts, follow the steps in this chapter.

  • Create repository to mirror content from CentOS Stream.

  • Synchronize the Content.

  • Create Activation Keys.

  • Register Hosts to consume this content.

  • Manage RPMs on hosts using the katello-agent.

3.1. Creating Repositories to Synchronize

Use this procedure to discover available repositories in the CentOS Stream, then select the repositories to mirror into a product.

Procedure

  1. In the Foreman web UI, navigate to Content > Products.

  2. Click Repo Discovery.

  3. In the Repository Type field, select Yum Repositories.

  4. In the URL to Discover field, enter the CentOS Stream URL http://mirror.centos.org/centos/8-stream.

  5. Click Discover.

  6. Select /AppStream/x86_64/os/ and /BaseOS/x86_64/os/ repositories.

  7. Click Create Selected.

  8. In the Product field select New Product.

  9. In the Name field enter CentOS Stream or desired product name.

  10. Click Run Repository Creation.

To view your newly created product, navigate to Content > Products, and select the name of the new product.

3.2. Synchronizing Content from an Upstream Repository

Use the following procedure to mirror the contents of the upstream CentOS repositories.

Procedure

  1. In the Foreman web UI, navigate to Content > Products

  2. Select your new CentOS Stream product from the previous procedure.

  3. Locate the AppStream x86_64 os and BaseOS x86_64 os repositories.

  4. Select both repositories

  5. Click Sync Now

3.3. Creating an Activation Key

Use the following procedure to create an activation key that you can use to subscribe your hosts to content managed by Foreman.

  1. In the Foreman web UI, navigate to Content > Activation keys and click Create Activation Key.

  2. In the Name field, enter the name of the activation key.

  3. In the Description field, enter a description for the activation key.

  4. From the Environment list, select the Library.

  5. From the Content View list, select Default Organization View.

  6. Click Save.

  7. Click on the Subscriptions tab on the Activation Key’s details page.

  8. Click on the Add tab.

  9. Select all the product subscriptions in the table.

  10. Click Add Selected to save.

3.4. Registering a CentOS Stream Host to Foreman

Use the following procedure to register an existing CentOS Stream host to Foreman.

You can register hosts with Foreman using the host registration feature, the Foreman API, or Hammer CLI.

Procedure

  1. In the Foreman web UI, navigate to Hosts > Register Host.

  2. Click Generate to create the registration command.

  3. Click on the files icon to copy the command to your clipboard.

  4. Log in to the host you want register and run the previously generated command.

  5. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

CLI procedure

  1. Generate the host registration command using the Hammer CLI:

    # hammer host-registration generate-command \
--activation-keys "My_Activation_Key"

    If your hosts do not trust the SSL certificate of Foreman server, you can disable SSL validation by adding the --insecure flag to the registration command.

    # hammer host-registration generate-command \
--activation-keys "My_Activation_Key" \
--insecure true

  2. Log in to the host you want register and run the previously generated command.

  3. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

API procedure

  1. Generate the host registration command using the Foreman API:

    # curl -X POST https://foreman.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"] }}'

    If your hosts do not trust the SSL certificate of Foreman server, you can disable SSL validation by adding the --insecure flag to the registration command.

    # curl -X POST https://foreman.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"], "insecure": true }}'

    Use an activation key to simplify specifying the environments. For more information, see Managing Activation Keys in the Content Management guide.

    To enter a password as command line argument, use username:password syntax. Keep in mind this can save the password in the shell history.

    For more information about registration see Registering a Host to Foreman in Managing Hosts.

  2. Log in to the host you want register and run the previously generated command.

  3. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

3.5. Using Content Views

Foreman uses the concept of Content Views to create snapshots of a set of repositories and make them available to hosts registered to it. For example, if you want a group of hosts to have access to a specific version of a set of repositories, add those repositories to a Content View, publish and promote to a lifecycle environment. You can then register hosts to this Content View. These hosts have access only to repositories at the version specified in the Content View. This means that you can continue to update repositories on your server while your hosts still consume only the versions of the repositories that they are registered to. If you do not use Content Views and lifecycle environments, all your hosts consume content from the Default Content View and Library environment, which is a snapshot of the latest version of the content on your server. For more information about content management using Content Views and application lifecycles, see:

3.6. Creating a Content View

Use the following procedure to create a Content View.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views and click Create Content View.

  2. In the Name field, enter CentOS Content View.

  3. In the Description field, enter a description for the content view.

  4. In the Type field, select a Content View or a Composite Content View.

  5. Click Create Content View.

3.7. Adding Repositories

Use the following procedure to add the upstream CentOS repositories to your Content view.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views > Select CentOS Content View > Repositories > Select repository(ies).

  2. Click Add Repositories.

3.8. Publishing the Content View

Use the following procedure to publish the Content View.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views, and select your new Content View.

  2. Click on Publish New Version button on the top right of page.

  3. Click Save

3.9. Creating an Activation Key to Consume the Content View

Use the following procedure to create an activation key that you can use to subscribe your hosts to content managed by Foreman.

Procedure

  1. In the Foreman web UI, navigate to Content > Activation keys and click Create Activation Key.

  2. In the Name field, enter CentOS or the name of your new activation key.

  3. In the Description field, enter a description for the activation key.

  4. From the Environment list, select the Library.

  5. From the Content View list, select Centos Content View.

  6. Click Save.

  7. Click the Subscriptions tab on the Activation Key’s details page.

  8. Click the Add tab.

  9. Select your new CentOS Stream product in the table.

  10. Click Add Selected to save.

Use your activation key to register a host to the Content View. For more information on registering a host, see Registering a Host in the Managing Hosts guide.

3.10. Registering a CentOS Stream host to consume content from a published Content View

You can also register the host to the published Content View without an activation key using the following command:

# subscription-manager register \
--environment="Library/CentOS_Content_View"
--org="My_Organization" \

3.11. Managing the Lifecycle of the Content View

The default location of any new Content View is in the Library Environment. Optionally, you can add a new environment and promote your Content View to it. Use the following procedure to create a new Lifecycle Environment.

Procedure

  1. In the Foreman web UI, navigate to Content > Lifecycle Environments and click Create Environment Path.

  2. In the Name field, enter Production or the name of your new environment to add to the end of Library environment.

  3. In the Description field, add an optional description for your new lifecycle environment.

  4. Click Save.

3.12. Promoting your Content View to the New Lifecycle Environment

You can now promote your new Content View to the Production environment using the following procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views > Select your Content View.

  2. On the Versions tab, click Promote for desired version under the Actions column.

  3. Select Production lifecycle environment from the available promotion paths.

  4. Add an optional Description.

  5. Click Promote Version.

3.13. Registering a CentOS Stream host to consume content from a promoted Content View in the production environment

To register a host to consume content from the Content View in the Production lifecycle environment, enter the following command:

# subscription-manager register \
--environment="Production/CentOS_Content_View" \
--org="My_Organization"

4. Managing Red Hat Subscriptions

Foreman can import content from the Red Hat Content Delivery Network (CDN). Foreman requires a Red Hat subscription manifest to find, access, and download content from the corresponding repositories. You must have a Red Hat subscription manifest containing a subscription allocation for each organization on Foreman server. All subscription information is available in your Red Hat Customer Portal account.

Before you can complete the tasks in this chapter, you must create a Red Hat subscription manifest in the Customer Portal.

To create, manage, and export a Red Hat subscription manifest in the Customer Portal, see Using Manifests in the Using Red Hat Subscription Management guide.

Use this chapter to import a Red Hat subscription manifest and manage the manifest within the Foreman web UI.

Subscription Allocations and Organizations

You can manage more than one organization if you have more than one subscription allocation. Foreman requires a single allocation for each organization configured in Foreman server. The advantage of this is that each organization maintains separate subscriptions so that you can support multiple organizations, each with their own Red Hat accounts.

Future-Dated subscriptions

You can use future-dated subscriptions in a subscription allocation. When you add future-dated subscriptions to content hosts before the expiry date of the existing subscriptions, you can have uninterrupted access to repositories.

Manually attach the future-dated subscriptions to your content hosts before the current subscriptions expire. Do not rely on the auto-attach method because this method is designed for a different purpose and might not work. For more information, see Attaching Red Hat Subscriptions to Content Hosts.

4.1. Importing a Red Hat Subscription Manifest into Foreman server

Use the following procedure to import a Red Hat subscription manifest into Foreman server.

This is for users of the Katello plug-in and Red Hat operating systems only.

Prerequisites

  • You must have a Red Hat subscription manifest file exported from the Customer Portal. For more information, see Creating and Managing Manifests in Using Red Hat Subscription Management.

Procedure

  1. In the Foreman web UI, ensure the context is set to the organization you want to use.

  2. In the Foreman web UI, navigate to Content > Subscriptions and click Manage Manifest.

  3. In the Manage Manifest window, click Browse.

  4. Navigate to the location that contains the Red Hat subscription manifest file, then click Open. If the Manage Manifest window does not close automatically, click Close to return to the Subscriptions window.

CLI procedure

  1. Copy the Red Hat subscription manifest file from your client to Foreman server:

    $ scp ~/manifest_file.zip root@foreman.example.com:~/.

  2. Log in to Foreman server as the root user and import the Red Hat subscription manifest file:

    # hammer subscription upload \
--file ~/manifest_file.zip \
--organization "My_Organization"

You can now enable repositories and import Red Hat content. For more information, see Importing Content in the Content Management guide.

4.2. Locating a Red Hat Subscription

When you import a Red Hat subscription manifest into Foreman server, the subscriptions from your manifest are listed in the Subscriptions window. If you have a high volume of subscriptions, you can filter the results to find a specific subscription.

Prerequisite
Procedure

  1. In the Foreman web UI, ensure the context is set to the organization you want to use.

  2. In the Foreman web UI, navigate to Content > Subscriptions.

  3. In the Subscriptions window, click the Search field to view the list of search criteria for building your search query.

  4. Select search criteria to display further options.

  5. When you have built your search query, click the search icon.

For example, if you place your cursor in the Search field and select expires, then press the space bar, another list appears with the options of placing a >, <, or = character. If you select > and press the space bar, another list of automatic options appears. You can also enter your own criteria.

4.3. Adding Red Hat Subscriptions to Subscription Allocations

Use the following procedure to add Red Hat subscriptions to a subscription allocation in the Foreman web UI.

Prerequisite
Procedure

  1. In the Foreman web UI, ensure the context is set to the organization you want to use.

  2. In the Foreman web UI, navigate to Content > Subscriptions.

  3. In the Subscriptions window, click Add Subscriptions.

  4. On the row of each subscription you want to add, enter the quantity in the Quantity to Allocate column.

  5. Click Submit

4.4. Removing Red Hat Subscriptions from Subscription Allocations

Use the following procedure to remove Red Hat subscriptions from a subscription allocation in the Foreman web UI.

Note

Manifests must not be deleted. If you delete the manifest from the Red Hat Customer Portal or in the Foreman web UI, all of the entitlements for all of your content hosts will be removed.
Prerequisite
Procedure

  1. In the Foreman web UI, ensure the context is set to the organization you want to use.

  2. In the Foreman web UI, navigate to Content > Subscriptions.

  3. On the row of each subscription you want to remove, select the corresponding checkbox.

  4. Click Delete, and then confirm deletion.

4.5. Updating and Refreshing Red Hat Subscription Manifests

Every time that you change a subscription allocation, you must refresh the manifest to reflect these changes. For example, you must refresh the manifest if you take any of the following actions:

  • Renewing a subscription

  • Adjusting subscription quantities

  • Purchasing additional subscriptions

You can refresh the manifest directly in the Foreman web UI. Alternatively, you can import an updated manifest that contains the changes.

Procedure

  1. In the Foreman web UI, ensure the context is set to the organization you want to use.

  2. In the Foreman web UI, navigate to Content > Subscriptions.

  3. In the Subscriptions window, click Manage Manifest.

  4. In the Manage Manifest window, click Refresh.

4.6. Attaching Red Hat Subscriptions to Content Hosts

Using activation keys is the main method to attach subscriptions to content hosts during the provisioning process. However, an activation key cannot update an existing host. If you need to attach new or additional subscriptions, such as future-dated subscriptions, to one host, use the following procedure.

For more information about updating multiple hosts, see Updating Red Hat Subscriptions on Multiple Hosts.

For more information about activation keys, see Managing Activation Keys.

Foreman Subscriptions

In Foreman, you must maintain a Red Hat Enterprise Linux Foreman subscription, formerly known as Red Hat Enterprise Linux Smart Management, for every Red Hat Enterprise Linux host that you want to manage.

However, you are not required to attach Foreman subscriptions to each content host. Foreman subscriptions cannot attach automatically to content hosts in Foreman because they are not associated with any product certificates. Adding a Foreman subscription to a content host does not provide any content or repository access. If you want, you can add a Foreman subscription to a manifest for your own recording or tracking purposes.

Prerequisite

  • You must have a Red Hat subscription manifest file imported to Foreman server.

Procedure

  1. In the Foreman web UI, ensure the context is set to the organization you want to use.

  2. In the Foreman web UI, navigate to Hosts > Content Hosts.

  3. On the row of each content host whose subscription you want to change, select the corresponding checkbox.

  4. From the Select Action list, select Manage Subscriptions.

  5. Optionally, enter a key and value in the Search field to filter the subscriptions displayed.

  6. Select the checkbox to the left of the subscriptions that you want to add or remove and click Add Selected or Remove Selected as required.

  7. Click Done to save the changes.

CLI procedure

  1. Connect to Foreman server as the root user, and then list the available subscriptions:

    # hammer subscription list \
--organization-id 1

  2. Attach a subscription to the host:

    # hammer host subscription attach \
--host host_name \
--subscription-id subscription_id

4.7. Updating Red Hat Subscriptions on Multiple Hosts

Use this procedure for post-installation changes to multiple content hosts at the same time.

Procedure

  1. In the Foreman web UI, ensure the context is set to the organization you want to use.

  2. In the Foreman web UI, navigate to Hosts > Content Hosts.

  3. On the row of each content host whose subscription you want to change, select the corresponding checkbox.

  4. From the Select Action list, select Manage Subscriptions.

  5. Optionally, enter a key and value in the Search field to filter the subscriptions displayed.

  6. Select the checkbox to the left of the subscriptions to be added or removed and click Add Selected or Remove Selected as required.

  7. Click Done to save the changes.

5. Importing Content

This chapter outlines how you can import different types of content to Foreman. If you want to import RPMs, Files, or different content types to Foreman, it is done with largely the same procedures in this chapter.

For example, you can use the following chapters for information on specific types of content but the underlying procedures are the same:

5.1. Using Products and Repositories in Foreman

Content from upstream as well as from Canonical, Oracle, Red Hat, SUSE, and custom content in Foreman have similarities:

  • The relationship between a product and its repositories is the same and the repositories still require synchronization.

  • products require a subscription for clients to access, similar to subscriptions to Red Hat Products. Foreman creates a subscription for each product you create.

Red Hat Content is already organized into Products. For example, Red Hat Enterprise Linux Server is a Product in Foreman. The repositories for that Product consist of different versions, architectures, and add-ons. For Red Hat repositories, products are created automatically after enabling the repository. For more information, see Enabling Red Hat Repositories.

Other content can be organized into Products however you want. For example, you might create an EPEL (Extra Packages for Enterprise Linux) product and add an "EPEL 7 x86_64" repository to it.

5.2. Importing SSL Certificates

Before you synchronize content from an external source, you might need to import SSL certificates into your product. This might include client certs and keys or CA certificates for the upstream repositories you want to synchronize.

If you require SSL certificates and keys to download RPMs, you can add them to Foreman.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Credentials. In the Content Credentials window, click Create Content Credential.

  2. In the Name field, enter a name for your SSL certificate.

  3. From the Type list, select SSL Certificate.

  4. In the Content Credentials Content field, paste your SSL certificate, or click Browse to upload your SSL certificate.

  5. Click Save.

CLI procedure

  1. Copy the SSL certificate to your Foreman server:

    $ scp My_SSL_Certificate root@foreman.example.com:~/.

    Or download the SSL certificate to your Foreman server from an online source:

    $ wget -P ~ http://upstream-foreman.example.com/pub/katello-server-ca.crt

  2. Upload the SSL Certificate to Foreman:

    # hammer content-credential create \
--content-type cert \
--name "My_SSL_Certificate" \
--organization "My_Organization" \
--path ~/My_SSL_Certificate

5.3. Creating a Product

Create a product so that you can add repositories to the product. To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Products, click Create Product.

  2. In the Name field, enter a name for the product. Foreman automatically completes the Label field based on what you have entered for Name.

  3. Optional: From the GPG Key list, select the GPG key for the product.

  4. Optional: From the SSL CA Cert list, select the SSL CA certificate for the product.

  5. Optional: From the SSL Client Cert list, select the SSL client certificate for the product.

  6. Optional: From the SSL Client Key list, select the SSL client key for the product.

  7. Optional: From the Sync Plan list, select an existing sync plan or click Create Sync Plan and create a sync plan for your product requirements.

  8. In the Description field, enter a description of the product.

  9. Click Save.

CLI procedure

To create the product, enter the following command:

# hammer product create \
--name "My_Product" \
--sync-plan "Example Plan" \
--description "Content from My Repositories" \
--organization "My_Organization"

5.4. Adding RPM Repositories

Use this procedure to add RPM repositories in Foreman. To use the CLI instead of the Foreman web UI, see the CLI procedure.

The Products window in the Foreman web UI also provides a Repo Discovery function that finds all repositories from a URL and you can select which ones to add to your product. For example, you can use the Repo Discovery to search http://yum.postgresql.org/9.5/redhat/ and list all repositories for different Red Hat Enterprise Linux versions and architectures. This helps users save time importing multiple repositories from a single source.

Procedure

  1. In the Foreman web UI, navigate to Content > Products and select the product that you want to use, and then click New Repository.

  2. In the Name field, enter a name for the repository. Foreman automatically completes the Label field based on what you have entered for Name.

  3. Optional: In the Description field, enter a description for the repository.

  4. From the Type list, select yum as type of repository.

  5. Optional: From the Restrict to Architecture list, select an architecture. If you want to make the repository available to all hosts regardless of the architecture, ensure to select No restriction.

  6. Optional: From the Restrict to OS Version list, select the OS version. If you want to make the repository available to all hosts regardless of the OS version, ensure to select No restriction.

  7. Optional: In the Upstream URL field, enter the URL of the external repository to use as a source. Foreman supports three protocols: http://, https://, and file://. If you are using a file:// repository, you have to place it under /var/lib/pulp/sync_imports/ directory.

    If you do not enter an upstream URL, you can manually upload packages.

  8. Optional: Check the Ignore SRPMs checkbox to exclude source RPM packages from being synchronized to Foreman.

  9. Select the Verify SSL checkbox if you want to verify that the upstream repository’s SSL certificates are signed by a trusted CA.

  10. Optional: In the Upstream Username field, enter the user name for the upstream repository if required for authentication. Clear this field if the repository does not require authentication.

  11. Optional: In the Upstream Password field, enter the corresponding password for the upstream repository. Clear this field if the repository does not require authentication.

  12. Optional: In the Upstream Authentication Token field, provide the token of the upstream repository user for authentication. Leave this field empty if the repository does not require authentication.

  13. From the Download Policy list, select the type of synchronization Foreman server performs. For more information, see Download Policies Overview.

  14. From the Mirroring Policy list, select the type of content synchronization Foreman server performs. For more information, see Mirroring Policies Overview.

  15. Optional: In the Retain package versions field, enter the number of versions you want to retain per package.

  16. Optional: In the HTTP Proxy Policy field, select an HTTP proxy.

  17. From the Checksum list, select the checksum type for the repository.

  18. Optional: You can clear the Unprotected checkbox to require a subscription entitlement certificate for accessing this repository. By default, the repository is published through HTTP.

  19. Optional: From the GPG Key list, select the GPG key for the product.

  20. Optional: In the SSL CA Cert field, select the SSL CA Certificate for the repository.

  21. Optional: In the SSL Client cert field, select the SSL Client Certificate for the repository.

  22. Optional: In the SSL Client Key field, select the SSL Client Key for the repository.

  23. Click Save to create the repository.

CLI procedure

  1. Enter the following command to create the repository:

    # hammer repository create \
--arch "My_Architecture" \
--content-type "yum" \
--gpg-key-id My_GPG_Key_ID \
--name "My_Repository" \
--organization "My_Organization" \
--os-version "My_OS_Version" \
--product "My_Product" \
--publish-via-http true \
--url My_Upstream_URL

Continue to synchronize the repository.

5.5. Extracting GPG Public Key Fingerprints from a Release Files

You can use GPG public keys the verify the authenticity of APT repositories by verifying the signature of the Release file. This example verifies the signature for the Release file from Debian 11.

Procedure

  1. Download the Release and Release.gpg files:

    $ wget https://ftp.debian.org/debian/dists/bullseye/Release
$ wget https://ftp.debian.org/debian/dists/bullseye/Release.gpg

  2. Verify the signature:

    $ gpg --verify Release.gpg Release

  3. If you cannot verify the signature, import the missing GPG public keys based on the output of the command above:

    $ gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 0146DC6D4A0B2914BDED34DB648ACFD622F3D138
$ gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys A7236886F3CCCAAD148A27F80E98404D386FA1D9
$ gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys A4285295FC7B1A81600062A9605C66F00D6C9793

  4. Optional: Verify the signature again:

    $ gpg --verify Release.gpg Release

  5. Export the ASCII-armored GPG public keys to a file:

    $ gpg --armor --export 0146DC6D4A0B2914BDED34DB648ACFD622F3D138 A7236886F3CCCAAD148A27F80E98404D386FA1D9 A4285295FC7B1A81600062A9605C66F00D6C9793 > debian_11.txt

    Use this .txt file and upload it to Foreman as described below.

Continue to import the custom GPG public key into Foreman.

5.6. Adding DEB Repositories

Use this procedure to add DEB repositories in Foreman. To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Products and select the product that you want to use, and then click New Repository.

  2. In the Name field, enter a name for the repository. Foreman automatically completes the Label field based on what you have entered for Name.

  3. Optional: In the Description field, enter a description for the repository.

  4. From the Type list, select deb as type of repository.

  5. Optional: In the Upstream URL field, enter the URL of the external repository to use as a source. You can find the upstream URLs on Debian-based systems in /etc/apt/sources.list.

    If you do not enter an upstream URL, you can manually upload packages.

  6. In the Releases/Distributions field, set one or multiple releases separated by whitespace. The distributions specify the path from the repository root to the Release file. Repositories that omit the dists directory are using the deprecated flat repository structure. To synchronize a flat repository, you must specify exactly one distribution that ends with a /.

    For official Debian repositories, set a codename in the Releases/Distributions field, for example buster for Debian 10 or bullseye for Debian 11. Avoid using stable or testing because the codename they reference changes over time. This helps to avoid drastic changes once a new Debian version is released and the reference is changed. To keep things easy to manage and to avoid potential performance and network issues during synchronization, create one repository per release in Foreman. For official Ubuntu repositories, use the Ubuntu suite, for example focal or focal-updates.

  7. Optional: In the Components field, enter a component. This indicates the licensing terms of the software packages.

    In Debian, it is divided into main, contrib, and non-free. For official Debian or Ubuntu repositories, Foreman community recommends leaving this field empty to synchronize all available components. Note that some third party Debian repositories use the components in ways that may require setting an explicit selection.

    Caution

    Ensure that you enter both Releases and Components exactly as they are in an /etc/apt/sources.list file.

  8. Optional: In the Architectures field, enter one or multiple architectures. If you want to make the repository available to all hosts regardless of the architecture, ensure to select No restriction.

  9. Optional: Select the Verify SSL checkbox if you want to verify that the upstream repository’s SSL certificates are signed by a trusted CA.

  10. Optional: In the Upstream Username field, enter the user name for the upstream repository if required for authentication. Clear this field if the repository does not require authentication.

  11. Optional: In the Upstream Password field, enter the corresponding password for the upstream repository. Clear this field if the repository does not require authentication.

  12. Optional: In the Upstream Authentication Token field, provide the token of the upstream repository user for authentication. Leave this field empty if the repository does not require authentication.

  13. From the Download Policy list, select the type of synchronization Foreman server performs. For more information, see Download Policies Overview.

  14. From the Mirroring Policy list, select the type of content synchronization Foreman server performs. For more information, see Mirroring Policies Overview.

  15. Optional: In the HTTP Proxy Policy field, select an HTTP proxy.

  16. Optional: You can clear the Unprotected checkbox to require a subscription entitlement certificate for accessing this repository. By default, the repository is published through HTTP.

  17. Optional: From the GPG Key list, select the GPG key if you want to verify the signatures of the Release files associated with the Debian repository.

  18. Optional: In the SSL CA Cert field, select the SSL CA Certificate for the repository.

  19. Optional: In the SSL Client cert field, select the SSL Client Certificate for the repository.

  20. Optional: In the SSL Client Key field, select the SSL Client Key for the repository.

  21. Click Save to create the repository.

CLI procedure

  1. Enter the following command to create the repository:

    # hammer repository create \
--content-type "deb" \
--deb-architectures "My_DEB_Architectures" \
--deb-components "_My_DEB_Components" \
--deb-releases "My_DEB_Releases" \
--gpg-key-id "My_GPG_Key_ID" \
--name "_My_Repository" \
--organization "My_Organization" \
--product "My_Product" \
--publish-via-http true \
--url My_Upstream_URL

Continue to synchronize the repository.

5.7. Adding DEB Repository Example for Debian 11

This example creates a product and repositories for Debian 11.

Prerequisites

  1. Extract the GPG public keys from the Release file

  2. Import the content credentials into Foreman

Procedure

  1. In the Foreman web UI, navigate to Content > Products.

  2. Click Create Product to create a product named Debian 11. For more information, see Creating a Product.

  3. On the Repositories tab, click New Repository to create three repositories of type deb as follows:

    • Debian 11 main

      • URL: http://ftp.debian.org/debian/

      • Releases/Distributions: bullseye

      • Component: main

      • Architecture: amd64

    • Debian 11 updates

      • URL: http://ftp.debian.org/debian/

      • Releases/Distributions: bullseye-updates

      • Component: main

      • Architecture: amd64

    • Debian 11 security

      • URL: http://deb.debian.org/debian-security/

      • Releases/Distributions: bullseye-security

      • Component: main

      • Architecture: amd64

  4. Click Create Product to create a product named Debian 11 client. For more information, see Creating a Product.

  5. On the Repositories tab, click New Repository to create a repository of type deb as follows:

    • Debian 11 client

      • URL: https://apt.atix.de/Debian11/

      • Releases/Distributions: stable

      • Component: main

      • Architecture: amd64

5.8. Enabling Red Hat Repositories

If outside network access requires usage of an HTTP Proxy, configure a default HTTP Proxy for your server. See Adding a default HTTP Proxy

To select the repositories to synchronize, you must first identify the product that contains the repository, and then enable that repository based on the relevant release version and base architecture. For Red Hat Enterprise Linux 8, you must enable both AppStream and BaseOS repositories.

Repository Versioning

The difference between associating Red Hat Enterprise Linux operating system with either 7 Server repositories or 7.X repositories is that 7 Server repositories contain all the latest updates while Red Hat Enterprise Linux 7.X repositories stop getting updates after the next minor version release. Note that Kickstart repositories only have minor versions.

For Red Hat Enterprise Linux 8 Clients

To provision Red Hat Enterprise Linux 8 clients, you require the Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMS) and Red Hat Enterprise Linux 8 for x86_64 - BaseOS (RPMs) repositories.

For Red Hat Enterprise Linux 7 Clients

To provision Red Hat Enterprise Linux 7 clients, you require the Red Hat Enterprise Linux 7 Server (RPMs) repository.

Procedure

  1. In the Foreman web UI, navigate to Content > Red Hat Repositories.

  2. To find repositories, either enter the repository name, or toggle the Recommended Repositories button to the on position to view a list of repositories that you require.

  3. In the Available Repositories pane, click a repository to expand the repository set.

  4. Click the Enable icon next to the base architecture and release version that you want.

CLI procedure

  1. To search for your product, enter the following command:

    # hammer product list --organization "My_Organization"

  2. List the repository set for the product:

    # hammer repository-set list \
--product "Red Hat Enterprise Linux Server" \
--organization "My_Organization"

  3. Enable the repository using either the name or ID number. Include the release version, for example,7Server and base architecture, for example, x86_64. For example:

    # hammer repository-set enable \
--name "Red Hat Enterprise Linux 7 Server (RPMs)" \
--releasever "7Server" \
--basearch "x86_64" \
--product "Red Hat Enterprise Linux Server" \
--organization "My_Organization"

5.9. Synchronizing Repositories

Procedure

  1. In the Foreman web UI, navigate to Content > Products and select the product that contains the repositories that you want to synchronize.

  2. Select the repositories that you want to synchronize and click Sync Now.

To view the progress of the synchronization in the Foreman web UI, navigate to Content > Sync Status and expand the corresponding product or repository tree.

CLI procedure

  • Synchronize an entire Product:

    # hammer product synchronize \
--name "My_Product" \
--organization "My_Organization"

  • Synchronize an individual repository:

    # hammer repository synchronize \
--name "My_Repository" \
--organization "My_Organization" \
--product "My Product"

The synchronization duration depends on the size of each repository and the speed of your network connection. The following table provides estimates of how long it would take to synchronize content, depending on the available Internet bandwidth:

Single Package (10Mb) Minor Release (750Mb) Major Release (6Gb)

256 Kbps

5 Mins 27 Secs

6 Hrs 49 Mins 36 Secs

2 Days 7 Hrs 55 Mins

512 Kbps

2 Mins 43.84 Secs

3 Hrs 24 Mins 48 Secs

1 Day 3 Hrs 57 Mins

T1 (1.5 Mbps)

54.33 Secs

1 Hr 7 Mins 54.78 Secs

9 Hrs 16 Mins 20.57 Secs

10 Mbps

8.39 Secs

10 Mins 29.15 Secs

1 Hr 25 Mins 53.96 Secs

100 Mbps

0.84 Secs

1 Min 2.91 Secs

8 Mins 35.4 Secs

1000 Mbps

0.08 Secs

6.29 Secs

51.54 Secs

Create a sync plan to ensure updates on a regular basis. See Creating a Sync Plan.

5.9.1. Synchronizing All Repositories in an Organization

Use this procedure to synchronize all repositories within an organization.

Procedure

To synchronize all repositories within an organization, run the following Bash script on your Foreman server:

ORG="My_Organization"

for i in $(hammer --no-headers --csv repository list --organization $ORG --fields Id)
do
  hammer repository synchronize --id ${i} --organization $ORG --async
done

5.10. Download Policies Overview

Foreman provides multiple download policies for synchronizing RPM and DEB content. For example, you might want to download only the content metadata while deferring the actual content download for later.

Foreman server has the following policies:

Immediate

Foreman server downloads all metadata and packages during synchronization.

On Demand

Foreman server downloads only the metadata during synchronization. Foreman server only fetches and stores packages on the file system when Smart Proxies or directly connected clients request them. This setting has no effect if you set a corresponding repository on a Smart Proxy to Immediate because Foreman server is forced to download all the packages.

The On Demand policy acts as a Lazy Synchronization feature because they save time synchronizing content. The lazy synchronization feature must be used only for deb and yum repositories. You can add the packages to Content Views and promote to life cycle environments as normal.

Smart Proxy server has the following policies:

Immediate

Smart Proxy server downloads all metadata and packages during synchronization. Do not use this setting if the corresponding repository on Foreman server is set to On Demand as Foreman server is forced to download all the packages.

On Demand

Smart Proxy server only downloads the metadata during synchronization. Smart Proxy server fetches and stores packages only on the file system when directly connected clients request them. When you use an On Demand download policy, content is downloaded from Foreman server if it is not available on Smart Proxy server.

Inherit

Smart Proxy server inherits the download policy for the repository from the corresponding repository on Foreman server.

5.11. Changing the Default Download Policy

You can set the default download policy that Foreman applies to repositories that you create in all organizations.

Depending on whether it is a Red Hat, SUSE, or repository, Foreman uses separate settings. Changing the default value does not change existing settings.

Procedure

  1. In the Foreman web UI, navigate to Administer > Settings.

  2. Click the Content tab.

  3. Change the default download policy depending on your requirements:

    • To change the default download policy for a Red Hat repository, change the value of the Default Red Hat Repository download policy setting.

    • To change the default download policy for a non-Red Hat repository, change the value of the Default Custom Repository download policy setting.

CLI procedure

  • To change the default download policy for Red Hat repositories to one of immediate or on_demand, enter the following command:

    # hammer settings set \
--name default_redhat_download_policy \
--value immediate

  • To change the default download policy for a repository to one of immediate or on_demand, enter the following command:

    # hammer settings set \
--name default_download_policy \
--value immediate

5.12. Changing the Download Policy for a Repository

You can set the download policy for a repository.

Procedure

  1. In the Foreman web UI, navigate to Content > Products.

  2. Select the required product name.

  3. On the Repositories tab, click the required repository name, locate the Download Policy field, and click the edit icon.

  4. From the list, select the required download policy and then click Save.

CLI procedure

  1. List the repositories for an organization:

    # hammer repository list \
--organization-label My_Organization_Label

  2. Change the download policy for a repository to immediate or on_demand:

    # hammer repository update \
--download-policy immediate \
--name "My_Repository" \
--organization-label My_Organization_Label \
--product "My_Product"

5.13. Mirroring Policies Overview

Mirroring keeps the local repository exactly in synchronization with the upstream repository. If any content is removed from the upstream repository since the last synchronization, with the next synchronization, it will be removed from the local repository as well.

You can use mirroring policies for finer control over mirroring of repodata and content when synchronizing a repository. For example, if it is not possible to mirror the repodata for a repository, you can set the mirroring policy to mirror only content for this repository.

Foreman server has the following mirroring policies:

Additive

Neither the content nor the repodata is mirrored. Thus, only new content added since the last synchronization is added to the local repository and nothing is removed.

Content Only

Mirrors only content and not the repodata. Some repositories do not support metadata mirroring, in such cases you can set the mirroring policy to content only to only mirror the content.

Complete Mirroring

Mirrors content as well as repodata. This is the fastest method. This mirroring policy is only available for Yum content.

5.14. Changing the Mirroring Policy for a Repository

You can set the mirroring policy for a repository.

Procedure

  1. In the Foreman web UI, navigate to Content > Products.

  2. Select the product name.

  3. On the Repositories tab, click the repository name, locate the Mirroring Policy field, and click the edit icon.

  4. From the list, select a mirroring policy and click Save.

5.15. Uploading Content to RPM Repositories

You can upload individual RPMs and source RPMs to RPM repositories. You can upload RPMs using the Foreman web UI or the Hammer CLI. You must use the Hammer CLI to upload source RPMs.

Procedure

  1. In the Foreman web UI, click Content > Products.

  2. Click the name of the product.

  3. In the Repositories tab, click the name of the RPM repository.

  4. Under Upload Package, click Browse…​ and select the RPM you want to upload.

  5. Click Upload.

To view all RPMs in this repository, click the number next to Packages under Content Counts.

CLI procedure

  • Enter the following command to upload an RPM:

    # hammer repository upload-content \
--id Repository_ID \
--path /path/to/example-package.rpm

  • Enter the following command to upload a source RPM:

    # hammer repository upload-content \
--content-type srpm \
--id Repository_ID \
--path /path/to/example-package.src.rpm

    When the upload is complete, you can view information about a source RPM by using the commands hammer srpm list and hammer srpm info --id srpm_ID.

5.16. Configuring SELinux to Permit Content Synchronization on Custom Ports

SELinux permits access of Foreman for content synchronization only on specific ports. By default, connecting to web servers running on the following ports is permitted: 80, 81, 443, 488, 8008, 8009, 8443, and 9000.

Procedure

  1. On Foreman, to verify the ports that are permitted by SELinux for content synchronization, enter a command as follows:

    # semanage port -l | grep ^http_port_t
http_port_t     tcp      80, 81, 443, 488, 8008, 8009, 8443, 9000

  2. To configure SELinux to permit a port for content synchronization, for example 10011, enter a command as follows:

    # semanage port -a -t http_port_t -p tcp 10011

5.17. Recovering a Corrupted Repository

In case of repository corruption, you can recover it by using an advanced synchronization, which has three options:

Optimized Sync

Synchronizes the repository bypassing RPMs that have no detected differences from the upstream RPMs.

Complete Sync

Synchronizes all RPMs regardless of detected changes. Use this option if specific RPMs could not be downloaded to the local repository even though they exist in the upstream repository.

Verify Content Checksum

Synchronizes all RPMs and then verifies the checksum of all RPMs locally. If the checksum of an RPM differs from the upstream, it re-downloads the RPM. This option is relevant only for yum repositories. Use this option if you have one of the following errors:

  • Specific RPMs cause a 404 error while synchronizing with yum.

  • Package does not match intended download error, which means that specific RPMs are corrupted.

Procedure

  1. In the Foreman web UI, navigate to Content > Products.

  2. Select the product containing the corrupted repository.

  3. Select the name of a repository you want to synchronize.

  4. To perform optimized sync or complete sync, select Advanced Sync from the Select Action menu.

  5. Select the required option and click Sync.

  6. Optional: To verify the checksum, click Verify Content Checksum from the Select Action menu.

CLI procedure

  1. Obtain a list of repository IDs:

    # hammer repository list \
--organization "My_Organization"

  2. Synchronize a corrupted repository using the necessary option:

    • For the optimized synchronization:

      # hammer repository synchronize \
--id My_ID

    • For the complete synchronization:

      # hammer repository synchronize \
--id My_ID \
--skip-metadata-check true

    • For the validate content synchronization:

      # hammer repository synchronize \
--id My_ID \
--validate-contents true

5.18. Adding an HTTP Proxy

Use this procedure to add HTTP proxies to Foreman. You can then specify which HTTP proxy to use for Products, repositories, and supported compute resources.

Prerequisites

Your HTTP proxy must allow access to the following hosts:

Host name Port Protocol

subscription.rhsm.redhat.com

443

HTTPS

cdn.redhat.com

443

HTTPS

*.akamaiedge.net

443

HTTPS

If Foreman server uses a proxy to communicate with subscription.rhsm.redhat.com and cdn.redhat.com then the proxy must not perform SSL inspection on these communications.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Infrastructure > HTTP Proxies and select New HTTP Proxy.

  2. In the Name field, enter a name for the HTTP proxy.

  3. In the URL field, enter the URL for the HTTP proxy, including the port number.

  4. If your HTTP proxy requires authentication, enter a Username and Password.

  5. Optional: In the Test URL field, enter the HTTP proxy URL, then click Test Connection to ensure that you can connect to the HTTP proxy from Foreman.

  6. Click the Locations tab and add a location.

  7. Click the Organization tab and add an organization.

  8. Click Submit.

CLI procedure

  • On Foreman server, enter the following command to add an HTTP proxy:

    # hammer http-proxy create --name proxy-name \
--url proxy-URL:port-number

    If your HTTP proxy requires authentication, add the --username name and --password password options.

For further information, see the Knowledgebase article How to access Red Hat Subscription Manager (RHSM) through a firewall or proxy on the Red Hat Customer Portal.

5.19. Changing the HTTP Proxy Policy for a Product

For granular control over network traffic, you can set an HTTP proxy policy for each Product. A Product’s HTTP proxy policy applies to all repositories in the Product, unless you set a different policy for individual repositories.

To set an HTTP proxy policy for individual repositories, see Changing the HTTP Proxy Policy for a Repository.

Procedure

  1. In the Foreman web UI, navigate to Content > Products and select the checkbox next to each of the Products that you want to change.

  2. From the Select Action list, select Manage HTTP Proxy.

  3. Select an HTTP Proxy Policy from the list:

    • Global Default: Use the global default proxy setting.

    • No HTTP Proxy: Do not use an HTTP proxy, even if a global default proxy is configured.

    • Use specific HTTP Proxy: Select an HTTP Proxy from the list. You must add HTTP proxies to Foreman before you can select a proxy from this list. For more information, see Adding an HTTP Proxy.

  4. Click Update.

5.20. Changing the HTTP Proxy Policy for a Repository

For granular control over network traffic, you can set an HTTP proxy policy for each repository. To use the CLI instead of the Foreman web UI, see the CLI procedure.

To set the same HTTP proxy policy for all repositories in a Product, see Changing the HTTP Proxy Policy for a Product.

Procedure

  1. In the Foreman web UI, navigate to Content > Products and click the name of the Product that contains the repository.

  2. In the Repositories tab, click the name of the repository.

  3. Locate the HTTP Proxy field and click the edit icon.

  4. Select an HTTP Proxy Policy from the list:

    • Global Default: Use the global default proxy setting.

    • No HTTP Proxy: Do not use an HTTP proxy, even if a global default proxy is configured.

    • Use specific HTTP Proxy: Select an HTTP Proxy from the list. You must add HTTP proxies to Foreman before you can select a proxy from this list. For more information, see Adding an HTTP Proxy.

  5. Click Save.

CLI procedure

  • On Foreman server, enter the following command, specifying the HTTP proxy policy you want to use:

    # hammer repository update --id repository-ID \
--http-proxy-policy policy

    Specify one of the following options for --http-proxy-policy:

    • none: Do not use an HTTP proxy, even if a global default proxy is configured.

    • global_default_http_proxy: Use the global default proxy setting.

    • use_selected_http_proxy: Specify an HTTP proxy using either --http-proxy proxy-name or --http-proxy-id proxy-ID. To add a new HTTP proxy to Foreman, see Adding an HTTP Proxy.

5.21. Creating a Sync Plan

A sync plan checks and updates the content at a scheduled date and time. In Foreman, you can create a sync plan and assign products to the plan.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Sync Plans and click New Sync Plan.

  2. In the Name field, enter a name for the plan.

  3. Optional: In the Description field, enter a description of the plan.

  4. From the Interval list, select the interval at which you want the plan to run.

  5. From the Start Date and Start Time lists, select when to start running the synchronization plan.

  6. Click Save.

CLI procedure

  1. To create the synchronization plan, enter the following command:

    # hammer sync-plan create \
--name "Red Hat Products 2" \
--description "Example Plan for Red Hat Products" \
--interval daily \
--sync-date "2016-02-01 01:00:00" \
--enabled true \
--organization "My_Organization"

  2. View the available sync plans for an organization to verify that the sync plan has been created:

    # hammer sync-plan list --organization "Default Organization"

5.22. Assigning a Sync Plan to a Product

A sync plan checks and updates the content at a scheduled date and time. In Foreman, you can assign a sync plan to products to update content regularly.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Products.

  2. Select a product.

  3. On the Details tab, select a Sync Plan from the drop down menu.

CLI procedure

  1. Assign a sync plan to a product:

    # hammer product set-sync-plan \
--name "Product_Name" \
--sync-plan "Sync_Plan_Name" \
--organization "My_Organization"

5.23. Assigning a Sync Plan to Multiple Products

Use this procedure to assign a sync plan to the products in an organization that have been synchronized at least once and contain at least one repository.

Procedure

  1. Run the following Bash script:

    ORG="Your_Organization"
SYNC_PLAN="daily_sync_at_3_a.m"

hammer sync-plan create --name $SYNC_PLAN --interval daily --sync-date "2023-04-5 03:00:00" --enabled true --organization $ORG
for i in $(hammer --no-headers --csv --csv-separator="|" product list --organization $ORG --per-page 999 | grep -vi not_synced | awk -F'|' '$5 != "0" { print $1}')
do
  hammer product set-sync-plan --sync-plan $SYNC_PLAN --organization $ORG --id $i
done

  2. After executing the script, view the products assigned to the sync plan:

    # hammer product list --organization $ORG --sync-plan $SYNC_PLAN

5.24. Limiting Synchronization Concurrency

By default, each Repository Synchronization job can fetch up to ten files at a time. This can be adjusted on a per repository basis.

Increasing the limit may improve performance, but can cause the upstream server to be overloaded or start rejecting requests. If you are seeing Repository syncs fail due to the upstream servers rejecting requests, you may want to try lowering the limit.

CLI procedure
# hammer repository update \
--download-concurrency 5 \
--id Repository_ID \
--organization "My_Organization"

5.25. Importing a GPG Key

When clients are consuming signed content, ensure that the clients are configured to validate the installation of packages with the appropriate GPG Key. This helps to ensure that only packages from authorized sources can be installed.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

Prerequisites

Ensure that you have a copy of the GPG key used to sign the RPM content that you want to use and manage in Foreman. Most RPM distribution providers provide their GPG Key on their website. You can also extract this manually from an RPM:

  1. Download a copy of the version specific repository package to your client system:

    $ wget http://www.example.com/9.5/example-9.5-2.noarch.rpm

  2. Extract the RPM file without installing it:

    $ rpm2cpio example-9.5-2.noarch.rpm | cpio -idmv

The GPG key is located relative to the extraction at etc/pki/rpm-gpg/RPM-GPG-KEY-EXAMPLE-95.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Credentials and in the upper-right of the window, click Create Content Credential.

  2. Enter the name of your repository and select GPG Key from the Type list.

  3. Either paste the GPG key into the Content Credential Contents field, or click Browse and select the GPG key file that you want to import.

    If your repository contains content signed by multiple GPG keys, you must enter all required GPG keys in the Content Credential Contents field with new lines between each key, for example:

    -----BEGIN PGP PUBLIC KEY BLOCK-----

mQINBFy/HE4BEADttv2TCPzVrre+aJ9f5QsR6oWZMm7N5Lwxjm5x5zA9BLiPPGFN
4aTUR/g+K1S0aqCU+ZS3Rnxb+6fnBxD+COH9kMqXHi3M5UNzbp5WhCdUpISXjjpU
XIFFWBPuBfyr/FKRknFH15P+9kLZLxCpVZZLsweLWCuw+JKCMmnA
=F6VG
-----END PGP PUBLIC KEY BLOCK-----

-----BEGIN PGP PUBLIC KEY BLOCK-----

mQINBFw467UBEACmREzDeK/kuScCmfJfHJa0Wgh/2fbJLLt3KSvsgDhORIptf+PP
OTFDlKuLkJx99ZYG5xMnBG47C7ByoMec1j94YeXczuBbynOyyPlvduma/zf8oB9e
Wl5GnzcLGAnUSRamfqGUWcyMMinHHIKIc1X1P4I=
=WPpI
-----END PGP PUBLIC KEY BLOCK-----

  4. Click Save.

CLI procedure

  1. Copy the GPG key to your Foreman server:

    $ scp ~/etc/pki/rpm-gpg/RPM-GPG-KEY-EXAMPLE-95 root@foreman.example.com:~/.

  2. Upload the GPG key to Foreman:

    # hammer content-credentials create \
--content-type gpg_key \
--name "My_GPG_Key" \
--organization "My_Organization" \
--path ~/RPM-GPG-KEY-EXAMPLE-95

5.26. Restricting Custom Repositories to RHEL 9 in Foreman

Procedure

  1. In the Foreman web UI, navigate to Content > Products.

  2. Select the product that contains the repository sets that you want to restrict.

  3. In the Repositories tab, click the repository that you want to restrict.

  4. From the Restrict to OS list, select the operating system to include Red Hat Enterprise Linux operating systems for their corresponding Red Hat Enterprise Linux repositories.

  5. Click Save to submit your change.

6. Managing Application Life Cycles

This chapter outlines the application life cycle in Foreman and how to create and remove application life cycles for Foreman and Smart Proxy.

6.1. Introduction to Application Life Cycle

The application life cycle is a concept central to Foreman’s content management functions. The application life cycle defines how a particular system and its software look at a particular stage. For example, an application life cycle might be simple; you might only have a development stage and production stage. In this case the application life cycle might look like this:

  • Development

  • Production

However, a more complex application life cycle might have further stages, such as a phase for testing or a beta release. This adds extra stages to the application life cycle:

  • Development

  • Testing

  • Beta Release

  • Production

Foreman provides methods to customize each application life cycle stage so that it suits your specifications.

Each stage in the application life cycle is called an environment in Foreman. Each environment uses a specific collection of content. Foreman defines these content collections as a Content View. Each Content View acts as a filter where you can define what repositories, and packages to include in a particular environment. This provides a method for you to define specific sets of content to designate to each environment.

For example, an email server might only require a simple application life cycle where you have a production-level server for real-world use and a test server for trying out the latest mail server packages. When the test server passes the initial phase, you can set the production-level server to use the new packages.

Another example is a development life cycle for a software product. To develop a new piece of software in a development environment, test it in a quality assurance environment, pre-release as a beta, then release the software as a production-level application.

The Foreman Application Life Cycle
Figure 1. The Foreman Application Life Cycle

6.2. Promoting Content across the Application Life Cycle

In the application life cycle chain, when content moves from one environment to the next, this is called promotion.

Example Content Promotion Across Foreman Life Cycle Environments

Each environment contains a set of systems registered to Foreman. These systems only have access to repositories relevant to their environment. When you promote packages from one environment to the next, the target environment’s repositories receive new package versions. As a result, each system in the target environment can update to the new package versions.

This example uses a .rpm package, but you can promote any type of content across the application life cycle.

Development Testing Production

example_software-1.1-0.noarch.rpm

example_software-1.0-0.noarch.rpm

example_software-1.0-0.noarch.rpm

After completing development on the patch, you promote the package to the Testing environment so the Quality Engineering team can review the patch. The application life cycle then contains the following package versions in each environment:

Development Testing Production

example_software-1.1-0.noarch.rpm

example_software-1.1-0.noarch.rpm

example_software-1.0-0.noarch.rpm

While the Quality Engineering team reviews the patch, the Development team starts work on example_software 2.0. This results in the following application life cycle:

Development Testing Production

exampleware-2.0-0.noarch.rpm

exampleware-1.1-0.noarch.rpm

exampleware-1.0-0.noarch.rpm

The Quality Engineering team completes their review of the patch. Now example_software 1.1 is ready to release. You promote 1.1 to the Production environment:

Development Testing Production

example_software-2.0-0.noarch.rpm

example_software-1.1-0.noarch.rpm

example_software-1.1-0.noarch.rpm

The Development team completes their work on example_software 2.0 and promotes it to the Testing environment:

Development Testing Production

example_software-2.0-0.noarch.rpm

example_software-2.0-0.noarch.rpm

example_software-1.1-0.noarch.rpm

Finally, the Quality Engineering team reviews the package. After a successful review, promote the package to the Production environment:

Development Testing Production

exampleware-2.0-0.noarch.rpm

exampleware-2.0-0.noarch.rpm

exampleware-2.0-0.noarch.rpm

For more information, see Promoting a Content View.

6.3. Creating a Life Cycle Environment Path

To create an application life cycle for developing and releasing software, use the Library environment as the initial environment to create environment paths. Then optionally add additional environments to the environment paths.

Procedure

  1. In the Foreman web UI, navigate to Content > Lifecycle Environments.

  2. Click New Environment Path to start a new application life cycle.

  3. In the Name field, enter a name for your environment.

  4. In the Description field, enter a description for your environment.

  5. Click Save.

  6. Optional: To add an environment to the environment path, click Add New Environment, complete the Name and Description fields, and select the prior environment from the Prior Environment list.

CLI procedure

  1. To create an environment path, enter the hammer lifecycle-environment create command and specify the Library environment with the --prior option:

    # hammer lifecycle-environment create \
--name "Environment Path Name" \
--description "Environment Path Description" \
--prior "Library" \
--organization "My_Organization"

  2. Optional: To add an environment to the environment path, enter the hammer lifecycle-environment create command and specify the parent environment with the --prior option:

    # hammer lifecycle-environment create \
--name "Environment Name" \
--description "Environment Description" \
--prior "Prior Environment Name" \
--organization "My_Organization"

  3. To view the chain of the life cycle environment, enter the following command:

    # hammer lifecycle-environment paths --organization "My_Organization"

6.4. Removing Life Cycle Environments from Foreman server

Use this procedure to remove a life cycle environment.

Procedure

  1. In the Foreman web UI, navigate to Content > Life Cycle Environments.

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

  3. Click Remove to remove the environment.

CLI procedure

  1. List the life cycle environments for your organization and note the name of the life cycle environment you want to remove:

    # hammer lifecycle-environment list \
--organization "My_Organization"

  2. Use the hammer lifecycle-environment delete command to remove an environment:

    # hammer lifecycle-environment delete \
--name "My_Environment" \
--organization "My_Organization"

6.5. Removing Life Cycle Environments from Smart Proxy server

When life cycle environments are no longer relevant to the host system or environments are added incorrectly to Smart Proxy server, you can remove the life cycle environments from Smart Proxy server.

You can use both the Foreman web UI and the Hammer CLI to remove life cycle environments from Smart Proxy.

Procedure

  1. In the Foreman web UI, navigate to Infrastructure > Smart Proxies, and select the Smart Proxy that you want to remove a life cycle from.

  2. Click Edit and click the Life Cycle Environments tab.

  3. From the right menu, select the life cycle environments that you want to remove from Smart Proxy, and then click Submit.

  4. To synchronize Smart Proxy’s content, click the Overview tab, and then click Synchronize.

  5. Select either Optimized Sync or Complete Sync.

CLI procedure

  1. Select Smart Proxy server that you want from the list and take note of its id:

    # hammer capsule list

  2. To verify Smart Proxy server’s details, enter the following command:

    # hammer capsule info \
--id Smart Proxy_ID

  3. Verify the list of life cycle environments currently attached to Smart Proxy server and take note of the Environment ID:

    # hammer capsule content lifecycle-environments \
--id Smart Proxy_ID

  4. Remove the life cycle environment from Smart Proxy server:

    # hammer capsule content remove-lifecycle-environment \
--id Smart Proxy_ID
--lifecycle-environment-id Lifecycle_Environment_ID

    Repeat this step for every life cycle environment that you want to remove from Smart Proxy server.

  5. Synchronize the content from Foreman server’s environment to Smart Proxy server:

    # hammer capsule content synchronize \
--id Smart Proxy_ID

6.6. Adding Life Cycle Environments to Smart Proxy servers

If your Smart Proxy server has the content functionality enabled, you must add an environment so that Smart Proxy can synchronize content from Foreman server and provide content to host systems.

Do not assign the Library lifecycle environment to your Smart Proxy server because it triggers an automated Smart Proxy sync every time the CDN updates a repository. This might consume multiple system resources on Smart Proxies, network bandwidth between Foreman and Smart Proxies, and available disk space on Smart Proxies.

You can use Hammer CLI on Foreman server or the Foreman web UI.

Procedure

  1. In the Foreman web UI, navigate to Infrastructure > Smart Proxies, and select the Smart Proxy that you want to add a life cycle to.

  2. Click Edit and click the Life Cycle Environments tab.

  3. From the left menu, select the life cycle environments that you want to add to Smart Proxy and click Submit.

  4. To synchronize the content on the Smart Proxy, click the Overview tab and click Synchronize.

  5. Select either Optimized Sync or Complete Sync.

    For definitions of each synchronization type, see Recovering a Repository.

CLI procedure

  1. To display a list of all Smart Proxy servers, on Foreman server, enter the following command:

    # hammer capsule list

    Note the Smart Proxy ID of the Smart Proxy that you want to add a life cycle to.

  2. Using the ID, verify the details of your Smart Proxy:

    # hammer capsule info --id capsule_id

  3. To view the life cycle environments available for your Smart Proxy server, enter the following command and note the ID and the organization name:

    # hammer capsule content available-lifecycle-environments --id capsule_id

  4. Add the life cycle environment to your Smart Proxy server:

    # hammer capsule content add-lifecycle-environment \
--id capsule_id --organization "My_Organization" \
--lifecycle-environment-id lifecycle-environment_id

    Repeat for each life cycle environment you want to add to Smart Proxy server.

  5. Synchronize the content from Foreman to Smart Proxy.

    • To synchronize all content from your Foreman server environment to Smart Proxy server, enter the following command:

      # hammer capsule content synchronize --id capsule_id

    • To synchronize a specific life cycle environment from your Foreman server to Smart Proxy server, enter the following command:

      # hammer capsule content synchronize --id external_capsule_id \
--lifecycle-environment-id lifecycle-environment_id

7. Managing Content Views

Foreman uses Content Views to allow your hosts access to a deliberately curated subset of content. To do this, you must define which repositories to use and then apply certain filters to the content. These filters include package filters, package group filters, errata filters, module stream filters, and container image tag filters. You can use Content Views to define which software versions a particular environment uses. For example, a Production environment might use a Content View containing older package versions, while a Development environment might use a Content View containing newer package versions.

Alternatively, a Default Organization View is an application-controlled Content View for all content that is synchronized to Foreman. This type is useful if you want to register a host to Foreman and access content using a subscription, without manipulating content views and lifecycle environments.

Each Content View creates a set of repositories across each environment, which Foreman server stores and manages. When you promote a Content View from one environment to the next environment in the application life cycle, the respective repository on Foreman server updates and publishes the packages.

Development Testing Production

Content View Version and Contents

Version 2 – example_software-1.1-0.noarch.rpm

Version 1 – example_software-1.0-0.noarch.rpm

Version 1 – example_software-1.0-0.noarch.rpm

The repositories for Testing and Production contain the example_software-1.0-0.noarch.rpm package. If you promote Version 2 of the Content View from Development to Testing, the repository for Testing regenerates and then contains the example_software-1.1-0.noarch.rpm package:

Development Testing Production

Content View Version and Contents

Version 2 – example_software-1.1-0.noarch.rpm

Version 2 – example_software-1.1-0.noarch.rpm

Version 1 – example_software-1.0-0.noarch.rpm

This ensures systems are designated to a specific environment but receive updates when that environment uses a new version of the Content View.

The general workflow for creating Content Views for filtering and creating snapshots is as follows:

  1. Create a Content View.

  2. Add one or more repositories that you want to the Content View.

  3. Optional: Create one or more filters to refine the content of the Content View. For more information, see Content Filter Examples.

  4. Optional: Resolve any package dependencies for a Content View. For more information, see Resolving Package Dependencies.

  5. Publish the Content View.

  6. Optional: Promote the Content View to another environment. For more information, see Promoting a Content View.

  7. Attach the content host to the Content View.

If a repository is not associated with the Content View, the file /etc/yum.repos.d/redhat.repo remains empty and systems registered to it cannot receive updates.

Hosts can only be associated with a single Content View. To associate a host with multiple Content Views, create a composite Content View. For more information, see Creating a Composite Content View.

7.1. Creating a Content View

Use this procedure to create a simple Content View. To use the CLI instead of the Foreman web UI, see the CLI procedure.

Prerequisites

While you can stipulate whether you want to resolve any package dependencies on a Content View by Content View basis, you might want to change the default Foreman settings to enable or disable package resolution for all Content Views. For more information, see Resolving Package Dependencies.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views and click Create content view.

  2. In the Name field, enter a name for the view. Foreman automatically completes the Label field from the name you enter.

  3. In the Description field, enter a description of the view.

  4. In the Type field, select a Content view or a Composite content view.

  5. Optional: If you want to solve dependencies automatically every time you publish this Content View, select the Solve dependencies check box. Dependency solving slows the publishing time and might ignore any Content View filters you use. This can also cause errors when resolving dependencies for errata.

  6. Optional: If you want to designate this Content View for importing from an upstream server, select the Import only check box. Import-only content views cannot be published directly.

  7. Click Create content view.

Content View Steps

  1. Click Create content view to create the Content View.

  2. In the Repositories tab, select the repository from the Type list that you want to add to your Content View, select the checkbox next to the available repositories you want to add, then click Add repositories.

  3. Click Publish new version and in the Description field, enter information about the version to log changes.

  4. Optional: You can enable a promotion path by clicking Promote to Select a lifecycle environment from the available promotion paths to promote new version.

  5. Click Next.

  6. On the Review page, you can review the environments you are trying to publish.

  7. Click Finish.

    Note
    		 Remove and Delete are similar but the Delete option deletes an entire Content View and the versions associated with that lifecycle environment. The Remove option allows you to choose which version you want removed from the lifecycle environment.

You can view the Content View in the Content Views window. To view more information about the Content View, click the Content View name. To register a host to your Content View, see Registering Hosts in Managing Hosts.

CLI procedure

  1. Obtain a list of repository IDs:

    # hammer repository list --organization "My_Organization"

  2. Create the Content View and add repositories:

    # hammer content-view create \
--description "My_Content_View" \
--name "My_Content_View" \
--organization "My_Organization" \
--repository-ids 1,2

    For the --repository-ids option, you can find the IDs in the output of the hammer repository list command.

  3. Publish the view:

    # hammer content-view publish \
--description "My_Content_View" \
--name "My_Content_View" \
--organization "My_Organization"

  4. Optional: To add a repository to an existing Content View, enter the following command:

    # hammer content-view add-repository \
--name "My_Content_View" \
--organization "My_Organization" \
--repository-id repository_ID

Foreman server creates the new version of the view and publishes it to the Library environment.

7.2. Viewing Module Streams

In Foreman, you can view the module streams of the repositories in your Content Views.

Procedure

  1. In the Foreman web UI, navigate to a published version of a Content View > Module Streams to view the module streams that are available for the Content Types.

  2. Use the Search field to search for specific modules.

  3. To view the information about the module, click the module and its corresponding tabs to include Details, Repositories, Profiles, and Artifacts.

7.3. Promoting a Content View

Use this procedure to promote Content Views across different lifecycle environments. To use the CLI instead of the Foreman web UI, see the CLI procedure.

Permission Requirements for Content View Promotion

Non-administrator users require two permissions to promote a Content View to an environment:

  1. promote_or_remove_content_views

  2. promote_or_remove_content_views_to_environment.

The promote_or_remove_content_views permission restricts which Content Views a user can promote.

The promote_or_remove_content_views_to_environment permission restricts the environments to which a user can promote Content Views.

With these permissions you can assign users permissions to promote certain Content Views to certain environments, but not to other environments. For example, you can limit a user so that they are permitted to promote to test environments, but not to production environments.

You must assign both permissions to a user to allow them to promote Content Views.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views and select the Content View that you want to promote.

  2. Select the version that you want to promote, click the vertical ellipsis icon, and click Promote.

  3. Select the environment where you want to promote the Content View and click Promote.

Now the repository for the Content View appears in all environments.

CLI procedure

  • Promote the Content View using the hammer content-view version promote each time:

    # hammer content-view version promote \
--content-view "Database" \
--version 1 \
--to-lifecycle-environment "Development" \
--organization "My_Organization"
# hammer content-view version promote \
--content-view "Database" \
--version 1 \
--to-lifecycle-environment "Testing" \
--organization "My_Organization"
# hammer content-view version promote \
--content-view "Database" \
--version 1 \
--to-lifecycle-environment "Production" \
--organization "My_Organization"

    Now the database content is available in all environments.

To register a host to your Content View, see Registering Hosts in the Managing Hosts guide.

7.4. Promoting a Content View Across All Life Cycle Environments within an Organization

Use this procedure to promote Content Views across all lifecycle environments within an organization.

Procedure

  1. To promote a selected Content View version from Library across all life cycle environments within an organization, run the following Bash script:

    ORG="My_Organization"
CVV_ID=3

for i in $(hammer --no-headers --csv lifecycle-environment list --organization $ORG | awk -F, {'print $1'} | sort -n)
do
   hammer content-view version promote --organization $ORG --to-lifecycle-environment-id $i --id $CVV_ID
done

  2. Display information about your Content View version to verify that it is promoted to the required lifecycle environments:

    # hammer content-view version info --id 3

7.5. Composite Content Views Overview

A Composite Content View combines the content from several Content Views. For example, you might have separate Content Views to manage an operating system and an application individually. You can use a Composite Content View to merge the contents of both Content Views into a new repository. The repositories for the original Content Views still exist but a new repository also exists for the combined content.

If you want to develop an application that supports different database servers. The example_application appears as:

example_software

Application

Database

Operating System

Example of four separate Content Views:

  • Red Hat Enterprise Linux (Operating System)

  • PostgreSQL (Database)

  • MariaDB (Database)

  • example_software (Application)

From the previous Content Views, you can create two Composite Content Views.

Example Composite Content View for a PostgreSQL database:

Composite Content View 1 – example_software on PostgreSQL

example_software (Application)

PostgreSQL (Database)

Red Hat Enterprise Linux (Operating System)

Example Composite Content View for a MariaDB:

Composite Content View 2 – example_software on MariaDB

example_software (Application)

MariaDB (Database)

Red Hat Enterprise Linux (Operating System)

Each Content View is then managed and published separately. When you create a version of the application, you publish a new version of the Composite Content Views. You can also select the Auto Publish option when creating a Composite Content View, and then the Composite Content View is automatically republished when a Content View it includes is republished.

Repository restrictions

Docker repositories cannot be included more than once in a Composite Content View. For example, if you attempt to include two Content Views using the same docker repository in a Composite Content View, Foreman server reports an error.

7.6. Creating a Composite Content View

Use this procedure to create a composite Content View. To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views and click Create content view.

  2. In the Create content view window, enter a name for the view in the Name field. Foreman automatically completes the Label field from the name you enter.

  3. Optional: In the Description field, enter a description of the view.

  4. On the Type tab, select Composite content view.

  5. Optional: If you want to automatically publish a new version of the Composite Content View when a Content View is republished, select the Auto publish checkbox.

  6. Click Create content view.

  7. On the Content views tab, select the Content Views that you want to add to the Composite Content View, and then click Add content views.

  8. In the Add content views window, select the version of each Content View.

  9. Optional: If you want to automatically update the Content View to the latest version, select the Always update to latest version checkbox.

  10. Click Add, then click Publish new version.

  11. Optional: In the Description field, enter a description of the Content View.

  12. In the Publish window, set the Promote switch, then select the lifecycle environment.

  13. Click Next, then click Finish.

CLI procedure

  1. Before you create the Composite Content Views, list the version IDs for your existing Content Views:

    # hammer content-view version list \
--organization "My_Organization"

  2. Create a new Composite Content View. When the --auto-publish option is set to yes, the Composite Content View is automatically republished when a Content View it includes is republished:

    # hammer content-view create \
--composite \
--auto-publish yes \
--name "Example_Composite_Content_View" \
--description "Example Composite Content View" \
--organization "My_Organization"

  3. Add a Content View to the Composite Content View. You can identify Content View, Content View version, and Organization in the commands by either their ID or their name. To add multiple Content Views to the Composite Content View, repeat this step for every Content View you want to include.

    • If you have the Always update to latest version option enabled for the Content View:

      # hammer content-view component add \
--component-content-view-id Content_View_ID \
--composite-content-view "Example_Composite_Content_View" \
--latest \
--organization "My_Organization"

    • If you have the Always update to latest version option disabled for the Content View:

      # hammer content-view component add \
--component-content-view-id Content_View_ID \
--composite-content-view "Example_Composite_Content_View" \
--component-content-view-version-id Content_View_Version_ID \
--organization "My_Organization"

  4. Publish the Composite Content View:

    # hammer content-view publish \
--name "Example_Composite_Content_View" \
--description "Initial version of Composite Content View" \
--organization "My_Organization"

  5. Promote the Composite Content View across all environments:

    # hammer content-view version promote \
--content-view "Example_Composite_Content_View" \
--version 1 \
--to-lifecycle-environment "Development" \
--organization "My_Organization"
# hammer content-view version promote \
--content-view "Example_Composite_Content_View" \
--version 1 \
--to-lifecycle-environment "Testing" \
--organization "My_Organization"
# hammer content-view version promote \
--content-view "Example_Composite_Content_View" \
--version 1 \
--to-lifecycle-environment "Production" \
--organization "My_Organization"

7.7. Content Filter Overview

Content Views also use filters to include or restrict certain RPM and DEB content. Without these filters, a Content View includes everything from the selected repositories.

There are two types of content filters:

Table 1. Filter Types
Filter Type Description

Include

You start with no content, then select which content to add from the selected repositories. Use this filter to combine multiple content items.

Exclude

You start with all content from selected repositories, then select which content to remove. Use this filter when you want to use most of a particular content repository but exclude certain packages, such as blacklisted packages. The filter uses all content in the repository except for the content you select.
Include and Exclude Filter Combinations

If using a combination of Include and Exclude filters, publishing a Content View triggers the include filters first, then the exclude filters. In this situation, select which content to include, then which content to exclude from the inclusive subset.

Content Types

There are also five types of content to filter:

Table 2. Content Types
Content Type Description

RPM

Filter packages based on their name and version number. The RPM option filters non-modular RPM packages and errata.

Package Group

Filter packages based on package groups. The list of package groups is based on the repositories added to the Content View.

Erratum (by ID)

Select which specific errata to add to the filter. The list of Errata is based on the repositories added to the Content View.

Erratum (by Date and Type)

Select a issued or updated date range and errata type (Bugfix, Enhancement, or Security) to add to the filter.

Module Streams

Select whether to include or exclude specific module streams. The Module Streams option filters modular RPMs and errata, but does not filter non-modular content that is associated with the selected module stream.

Container Image Tag

Select whether to include or exclude specific container image tags.

7.8. Resolving Package Dependencies

Foreman can add dependencies of packages in a Content View to the dependent repository when publishing the Content View. To configure this, you can enable dependency solving.

For example, dependency solving is useful when you incrementally add a single package to a Content View version. You might need to enable dependency solving to install that package.

However, dependency solving is unnecessary in most situations. For example:

  • When incrementally adding a security errata to a Content View, dependency solving can cause significant delays to Content View publication without major benefits.

  • Packages from a newer erratum might have dependencies that are incompatible with packages from an older Content View version. Incrementally adding the erratum using dependency solving might include unwanted packages. As an alternative, consider updating the Content View.

Note

Dependency solving only considers packages within the repositories of the Content View. It does not consider packages installed on clients.

For more information, see Limitations to Repository Dependency Resolution in Managing Content.

Dependency solving can lead to the following problems:

Significant delay in Content View publication

Foreman examines every repository in a Content View for dependencies. Therefore, publish time increases with more repositories.

To mitigate this problem, use multiple Content Views with fewer repositories and combine them into composite Content Views.

Ignored Content View filters on dependent packages

Foreman prioritizes resolving package dependencies over the rules in your filter.

For example, if you create a filter for security purposes but enable dependency solving, Foreman can add packages that you might consider insecure.

To mitigate this problem, carefully test filtering rules to determine the required dependencies. If dependency solving includes unwanted packages, manually identify the core basic dependencies that the extra packages and errata need.

7.9. Enabling Dependency Solving for a Content View

Use this procedure to enable dependency solving for a Content View.

Prerequisite
Procedure

  1. In the Foreman web UI, navigate to Content > Content Views.

  2. From the list of content views, select the required Content View.

  3. On the Details tab, toggle Solve dependencies.

7.10. Content Filter Examples

Use any of the following examples with the procedure that follows to build custom content filters.

Note
 Filters can significantly increase the time to publish a Content View. For example, if a Content View publish task completes in a few minutes without filters, it can take 30 minutes after adding an exclude or include errata filter.
Example 1

Create a repository with the base Red Hat Enterprise Linux packages. This filter requires a Red Hat Enterprise Linux repository added to the Content View.

Filter:

  • Inclusion Type: Include

  • Content Type: Package Group

  • Filter: Select only the Base package group

Example 2

Create a repository that excludes all errata, except for security updates, after a certain date. This is useful if you want to perform system updates on a regular basis with the exception of critical security updates, which must be applied immediately. This filter requires a Red Hat Enterprise Linux repository added to the Content View.

Filter:

  • Inclusion Type: Exclude

  • Content Type: Erratum (by Date and Type)

  • Filter: Select only the Bugfix and Enhancement errata types, and clear the Security errata type. Set the Date Type to Updated On. Set the Start Date to the date you want to restrict errata. Leave the End Date blank to ensure any new non-security errata is filtered.

Example 3

A combination of Example 1 and Example 2 where you only require the operating system packages and want to exclude recent bug fix and enhancement errata. This requires two filters attached to the same Content View. The Content View processes the Include filter first, then the Exclude filter.

Filter 1:

  • Inclusion Type: Include

  • Content Type: Package Group

  • Filter: Select only the Base package group

Filter 2:

  • Inclusion Type: Exclude

  • Content Type: Erratum (by Date and Type)

  • Filter: Select only the Bugfix and Enhancement errata types, and clear the Security errata type. Set the Date Type to Updated On. Set the Start Date to the date you want to restrict errata. Leave the End Date blank to ensure any new non-security errata is filtered.

Example 4

Filter a specific module stream in a Content View.

Filter 1:

  • Inclusion Type: Include

  • Content Type: Module Stream

  • Filter: Select only the specific module stream that you want for the Content View, for example ant, and click Add Module Stream.

Filter 2:

  • Inclusion Type: Exclude

  • Content Type: Package

  • Filter: Add a rule to filter any non-modular packages that you want to exclude from the Content View. If you do not filter the packages, the Content View filter includes all non-modular packages associated with the module stream ant. Add a rule to exclude all * packages, or specify the package names that you want to exclude.

For another example of how content filters work, see the following article: "How do content filters work in Satellite 6".

7.11. Creating a Content Filter for Yum Content

You can filter Content Views containing Yum content to include or exclude specific packages, package groups, errata, or module streams. Filters are based on a combination of the name, version, and architecture.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

For examples of how to build a filter, see Content Filter Examples.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views and select a Content View.

  2. On the Filters tab, click Create filter.

  3. Enter a name.

  4. From the Content type list, select a content type.

  5. From the Inclusion Type list, select either Include filter or Exclude filter.

  6. Optional: In the Description field, enter a description for the filter.

  7. Click Create filter to create your content filter.

  8. Depending on what you enter for Content Type, add rules to create the filter that you want.

  9. Select if you want the filter to Apply to subset of repositories or Apply to all repositories.

  10. Click Publish New Version to publish the filtered repository.

  11. Optional: In the Description field, enter a description of the changes.

  12. Click Create filter to publish a new version of the Content View.

    You can promote this Content View across all environments.

CLI procedure

  1. Add a filter to the Content View. Use the --inclusion false option to set the filter to an Exclude filter:

    # hammer content-view filter create \
--name "Errata Filter" \
--type erratum --content-view "Example_Content_View" \
--description "My latest filter" \
--inclusion false \
--organization "My_Organization"

  2. Add a rule to the filter:

    # hammer content-view filter rule create \
--content-view "Example_Content_View" \
--content-view-filter "Errata Filter" \
--start-date "YYYY-MM-DD" \
--types enhancement,bugfix \
--date-type updated \
--organization "My_Organization"

  3. Publish the Content View:

    # hammer content-view publish \
--name "Example_Content_View" \
--description "Adding errata filter" \
--organization "My_Organization"

  4. Promote the view across all environments:

    # hammer content-view version promote \
--content-view "Example_Content_View" \
--version 1 \
--to-lifecycle-environment "Development" \
--organization "My_Organization"
# hammer content-view version promote \
--content-view "Example_Content_View" \
--version 1 \
--to-lifecycle-environment "Testing" \
--organization "My_Organization"
# hammer content-view version promote \
--content-view "Example_Content_View" \
--version 1 \
--to-lifecycle-environment "Production" \
--organization "My_Organization"

7.12. Creating a Content Filter for APT Content

You can filter Content Views containing deb content to include or exclude specific packages or package groups. Filters are based on a combination of the name and the architecture.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

For examples of how to build a filter, see Content Filter Examples.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views and select a Content View.

  2. On the Filters tab, click Create filter.

  3. Enter a name.

  4. From the Content type list, select a content type.

  5. From the Inclusion Type list, select either Include filter or Exclude filter.

  6. Optional: In the Description field, enter a description for the filter.

  7. Click Create filter to create your content filter.

  8. Depending on what you enter for Content Type, add rules to create the filter that you want.

  9. Select if you want the filter to Apply to subset of repositories or Apply to all repositories.

  10. Click Publish New Version to publish the filtered repository.

  11. Optional: In the Description field, enter a description of the changes.

  12. Click Save to publish a new version of the Content View.

    You can promote this Content View across all environments.

CLI procedure

  1. Add a filter to the Content View. Use the --inclusion false option to set the filter to an Exclude filter:

    # hammer content-view filter create \
--content-view "Example_Content_View" \
--description "My_Content_View_Filter_Description" \
--inclusion false \
--name "Errata Filter" \
--organization "My_Organization" \
--type erratum

  2. Add a rule to the filter:

    # hammer content-view filter rule create \
--content-view "My_Content_View" \
--content-view-filter "My_Errata_Filter" \
--date-type updated \
--organization "My_Organization" \
--start-date "YYYY-MM-DD" \
--types enhancement,bugfix

  3. Publish the Content View:

    # hammer content-view publish \
--description "Adding errata filter" \
--name "My_Content_View" \
--organization "My_Organization"

  4. Promote the view across all environments:

    # hammer content-view version promote \
--content-view "Example_Content_View" \
--organization "My_Organization" \
--to-lifecycle-environment "Development" \
--version 1
# hammer content-view version promote \
--content-view "Example_Content_View" \
--organization "My_Organization" \
--to-lifecycle-environment "Testing" \
--version 1
# hammer content-view version promote \
--content-view "Example_Content_View" \
--organization "My_Organization" \
--to-lifecycle-environment "Production" \
--version 1

7.13. Deleting A Content View Version

Use this procedure to delete a Content View version.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views.

  2. Select the Content View.

  3. On the Versions tab, select the version you want to delete and click on the vertical ellipsis on the right side of the version line.

  4. Click Delete to open the deletion wizard that shows any affected environments.

  5. Optional: If there are any affected environments, reassign any hosts or activation keys before deletion.

  6. Click Next and review the details of the action.

  7. Click Delete.

8. Synchronizing Content Between Foreman Servers

In a Foreman setup with multiple Foreman servers, you can use Inter-Server Synchronization (ISS) to synchronize content from one upstream server to one or more downstream servers.

There are two possible ISS configurations of Foreman, depending on how you deployed your infrastructure:

ISS Network Sync

If your upstream server can communicate with the downstream server over a network, you can synchronize content over HTTPS.

Configure your Foreman to synchronize content over a network. For more information, see Configuring Foreman Server to Synchronize Content over a Network.

ISS Export Sync

If your upstream and downstream servers are air-gapped, you can synchronize content using export and import.

Configure your Foreman to synchronize content using export and import. For more information, see Configuring Foreman Server to Synchronize Content Using Exports.

Additional Resources

8.1. How to Synchronize Content Using Export and Import

There are multiple approaches for synchronizing content using the export and import workflow:

  • You employ the upstream Foreman server as a content store, which means that you sync the whole Library rather than Content View versions. This approach offers the simplest export/import workflow. In such case, you can manage the versions downstream. For more information, see Using an Upstream Foreman server as a Content Store.

  • You use the upstream Foreman server to sync Content View versions. This approach offers more control over what content is synced between Foreman servers. For more information, see Using an Upstream Foreman server to Sync Content View Versions.

  • You sync a single repository. This can be useful if you use the Content-View syncing approach, but you want to sync an additional repository without adding it to an existing Content View. For more information, see Synchronizing a Single Repository.

8.1.1. Using an Upstream Foreman server as a Content Store

In this scenario, you use the upstream Foreman server as a content store for updates rather than to manage content. You use the downstream Foreman server to manage content for all infrastructure behind the isolated network. You export the Library content from the upstream Foreman server and import it into the downstream Foreman server.

On the upstream Foreman server

  1. Ensure that repositories are using the Immediate download policy in one of the following ways:

    1. For existing repositories using On Demand, change their download policy on the repository details page to Immediate.

    2. For new repositories, ensure that the Default Red Hat Repository download policy setting is set to Immediate before enabling Red Hat repositories, and that the Default download policy is set to Immediate for custom repositories.

    For more information, see Download Policies Overview.

  2. Enable the content that you want to synchronize. For more information, see Enabling Red Hat Repositories.

    If you want to sync custom content, first create a custom Product and synchronize Product repositories.

  3. Synchronize the enabled content:

    1. On the first export, perform a complete Library export so that all the synchronized content is exported. This generates content archives that you can later import into one or more downstream Foreman servers. For more information on performing a complete Library export, see Exporting the Library Environment.

    2. Export all future updates on the upstream Foreman server incrementally. This generates leaner content archives that contain only a recent set of updates. For example, if you enable and synchronize a new repository, the next exported content archive contains content only from the newly enabled repository. For more information on performing an incremental Library export, see Exporting the Library Environment Incrementally.

On the downstream Foreman server

  1. Bring the content exported from the upstream Foreman server over to the hard disk.

  2. Place it inside a directory under /var/lib/pulp/imports.

  3. Import the content to an organization using the procedure outlined in Importing into the Library Environment.

    You can then manage content using Content Views or Lifecycle Environments as you require.

8.1.2. Using an Upstream Foreman server to Sync Content View Versions

In this scenario, you use the upstream Foreman server not only as a content store, but also to synchronize content for all infrastructure behind the isolated network. You curate updates coming from the CDN into Content Views and Lifecycle Environments. Once you promote content to a designated Lifecycle Environment, you can export the content from the upstream Foreman server and import it into the downstream Foreman server.

On the upstream Foreman server

  1. Ensure that repositories are using the Immediate download policy in one of the following ways:

    1. For existing repositories using On Demand, change their download policy on the repository details page to Immediate.

    2. For new repositories, ensure that the Default Red Hat Repository download policy setting is set to Immediate before enabling Red Hat repositories, and that the Default download policy is set to Immediate for custom repositories.

    For more information, see Download Policies Overview.

  2. Enable the content that you want to synchronize. For more information, see Enabling Red Hat Repositories.

    If you want to sync custom content, first create a custom Product and synchronize Product repositories.

  3. Synchronize the enabled content:

    1. For the first export, perform a complete Version export on the Content View Version that you want to export. For more information see, Exporting a Content View Version. This generates content archives that you can import into one or more downstream Foreman servers.

    2. Export all future updates in the connected Foreman servers incrementally. This generates leaner content archives that contain changes only from the recent set of updates. For example, if your Content View has a new repository, this exported content archive contains only the latest changes. For more information, see Exporting a Content View Version Incrementally.

    3. When you have new content, republish the Content Views that include this content before exporting the increment. For more information, see Managing Content Views. This creates a new Content View Version with the appropriate content to export.

On the downstream Foreman server

  1. Bring the content exported from the upstream Foreman server over to the hard disk.

  2. Place it inside a directory under /var/lib/pulp/imports.

  3. Import the content to the organization that you want. For more information, see Importing a Content View Version. This will create a Content View Version from the exported content archives and then import content appropriately.

8.1.3. Synchronizing a Single Repository

In this scenario, you export and import a single repository.

On the upstream Foreman server

  1. Ensure that the repository is using the Immediate download policy in one of the following ways:

    1. For existing repositories using On Demand, change their download policy on the repository details page to Immediate.

    2. For new repositories, ensure that the Default Red Hat Repository download policy setting is set to Immediate before enabling Red Hat repositories, and that the Default download policy is set to Immediate for custom repositories.

    For more information, see Download Policies Overview.

  2. Enable the content that you want to synchronize. For more information, see Enabling Red Hat Repositories.

    If you want to sync custom content, first create a custom Product and synchronize Product repositories.

  3. Synchronize the enabled content:

    1. On the first export, perform a complete repository export so that all the synchronized content is exported. This generates content archives that you can later import into one or more downstream Foreman servers. For more information on performing a complete repository export, see Exporting a Repository.

    2. Export all future updates on the upstream Foreman server incrementally. This generates leaner content archives that contain only a recent set of updates. For more information on performing an incremental repository export, see Exporting a Repository Incrementally.

On the downstream Foreman server

  1. Bring the content exported from the upstream Foreman server over to the hard disk.

  2. Place it inside a directory under /var/lib/pulp/imports.

  3. Import the content to an organization. See Importing a Repository.

    You can then manage content using Content Views or Lifecycle Environments as you require.

8.2. Synchronizing a Custom Repository

When using Inter-Server Synchronization Network Sync, Red Hat repositories are configured automatically, but custom repositories are not. Use this procedure to synchronize content from a custom repository on a connected Foreman server to a disconnected Foreman server through Inter-Server Synchronization (ISS) Network Sync.

Follow the procedure for the connected Foreman server before completing the procedure for the disconnected Foreman server.

Connected Foreman server

  1. In the Foreman web UI, navigate to Content > Products.

  2. Click on the custom product.

  3. Click on the custom repository.

  4. Copy the Published At: URL.

  5. Continue with the procedure on disconnected Foreman server.

Disconnected Foreman server

  1. Download the katello-server-ca.crt file from the connected Foreman server:

    # curl http://foreman.example.com/pub/katello-server-ca.crt

  2. Create an SSL Content Credential with the contents of katello-server-ca.crt. For more information on creating an SSL Content Credential, see Importing SSL Certificates.

  3. In the Foreman web UI, navigate to Content > Products.

  4. Create your custom product with the following:

    • Upstream URL: Paste the link that you copied earlier.

    • SSL CA Cert: Select the SSL certificate that was transferred from your connected Foreman server.

    For more information on creating a custom product, see Creating a Product.

After completing these steps, the custom repository is properly configured on the disconnected Foreman server.

8.3. Exporting the Library Environment

You can export contents of all Yum repositories in the Library environment of an organization to an archive file from Foreman server and use this archive file to create the same repositories in another Foreman server or in another Foreman server organization. The exported archive file contains the following data:

  • A JSON file containing Content View version metadata

  • An archive file containing all the repositories from the Library environment of the organization.

Foreman server exports only RPM and kickstart files included in a Content View version. Foreman does not export the following content:

  • Docker content

Prerequisites

To export the contents of the Library lifecycle environment of the organization, ensure that Foreman server where you want to export meets the following conditions:

  • Ensure that the export directory has free storage space to accommodate the export.

  • Ensure that the /var/lib/pulp/exports directory has free storage space equivalent to the size of the repositories being exported for temporary files created during the export process.

  • Ensure that you set download policy to Immediate for all repositories within the Library lifecycle environment you export. For more information, see Download Policies Overview.

  • Ensure that you synchronize Products that you export to the required date.

Export the Library Content of an Organization

  1. Use the organization name or ID to export.

    # hammer content-export complete library --organization="My_Organization"

  2. Verify that the archive containing the exported version of a Content View is located in the export directory:

    # ls -lh /var/lib/pulp/exports/My_Organization/Export-Library/1.0/2021-03-02T03-35-24-00-00
total 68M
-rw-r--r--. 1 pulp pulp 68M Mar  2 03:35 export-1e25417c-6d09-49d4-b9a5-23df4db3d52a-20210302_0335.tar.gz
-rw-r--r--. 1 pulp pulp 333 Mar  2 03:35 export-1e25417c-6d09-49d4-b9a5-23df4db3d52a-20210302_0335-toc.json
-rw-r--r--. 1 pulp pulp 443 Mar  2 03:35 metadata.json

    You need all three files, the tar.gz, the toc.json, and the metadata.json file to be able to import.

  3. A new Content View Export-Library is created in the organization. This Content View contains all the repositories belonging to this organization. A new version of this Content View is published and exported automatically.

Export with chunking

In many cases the exported archive content may be several gigabytes in size. If you want to split it into smaller sizes or chunks. You can use the --chunk-size-gb flag directly in the export command to handle this. In the following example, you can see how to specify --chunk-size-gb=2 to split the archives in 2 GB chunks.

# hammer content-export complete library \
--chunk-size-gb=2 \
--organization="My_Organization"

Generated /var/lib/pulp/exports/My_Organization/Export-Library/2.0/2021-03-02T04-01-25-00-00/metadata.json

# ls -lh /var/lib/pulp/exports/My_Organization/Export-Library/2.0/2021-03-02T04-01-25-00-00/

8.4. Exporting the Library Environment Incrementally

Exporting Library content can be a very expensive operation in terms of system resources. Organizations that have multiple Red Hat Enterprise Linux trees can occupy several gigabytes of space on Foreman server.

In such cases, you can use Incremental Export to export only pieces of content that changed since the previous export. Incremental exports typically result in smaller archive files than the full exports.

The example below shows incremental export of all repositories in the organization’s Library.

Procedure

  1. Create an incremental export:

    # hammer content-export incremental library --organization="My_Organization"

Generated /var/lib/pulp/exports/My_Organization/Export-Library/3.0/2021-03-02T04-22-14-00-00/metadata.json

  2. Optional: View the exported data:

    # ls -lh /var/lib/pulp/exports/My_Organization/Export-Library/3.0/2021-03-02T04-22-14-00-00/
total 172K
-rw-r--r--. 1 pulp pulp 161K Mar  2 04:22 export-436882d8-de5a-48e9-a30a-17169318f908-20210302_0422.tar.gz
-rw-r--r--. 1 pulp pulp  333 Mar  2 04:22 export-436882d8-de5a-48e9-a30a-17169318f908-20210302_0422-toc.json
-rw-r--r--. 1 pulp pulp  492 Mar  2 04:22 metadata.json

8.5. Exporting a Content View Version

You can export a version of a Content View to an archive file from Foreman server and use this archive file to create the same Content View version on another Foreman server or on another Foreman server organization. Foreman exports composite Content Views as normal Content Views. The composite nature is not retained. On importing the exported archive, a regular Content View is created or updated on your downstream Foreman server. The exported archive file contains the following data:

  • A JSON file containing Content View version metadata

  • An archive file containing all the repositories included into the Content View version

Foreman server exports only RPM and kickstart files added to a version of a Content View. Foreman does not export the following content:

  • Docker content

  • Content View definitions and metadata, such as package filters.

Prerequisites

To export a Content View, ensure that Foreman server where you want to export meets the following conditions:

  • Ensure that the export directory has free storage space to accommodate the export.

  • Ensure that the /var/lib/pulp/exports directory has free storage space equivalent to the size of the repositories being exported for temporary files created during the export process.

  • Ensure that you set download policy to Immediate for all repositories within the Content View you export. For more information, see Download Policies Overview.

  • Ensure that you synchronize Products that you export to the required date.

  • Ensure that the user exporting the content has the Content Exporter role.

To Export a Content View Version

  1. List versions of the Content View that are available for export:

    # hammer content-view version list \
--content-view="My_Content_View" \
--organization="My_Organization"

---|----------|---------|-------------|-----------------------
ID | NAME     | VERSION | DESCRIPTION | LIFECYCLE ENVIRONMENTS
---|----------|---------|-------------|-----------------------
5  | view 3.0 | 3.0     |             | Library
4  | view 2.0 | 2.0     |             |
3  | view 1.0 | 1.0     |             |
---|----------|---------|-------------|----------------------
Export a Content View version

  1. Get the version number of desired version. The following example targets version 1.0 for export.

    # hammer content-export complete version \
--content-view="Content_View_Name" \
--version=1.0 \
--organization="My_Organization"

  2. Verify that the archive containing the exported version of a Content View is located in the export directory:

    # ls -lh /var/lib/pulp/exports/My_Organization/Content_View_Name/1.0/2021-02-25T18-59-26-00-00/

You require all three files, for example, the tar.gz archive file, the toc.json and metadata.json to import the content successfully.

Export with chunking

In many cases, the exported archive content can be several gigabytes in size. You might want to split it smaller sizes or chunks. You can use the --chunk-size-gb option with in the hammer content-export command to handle this. The following example uses the --chunk-size-gb=2 to split the archives into 2 GB chunks.

# hammer content-export complete version \
--chunk-size-gb=2 \
--content-view="Content_View_Name" \
--organization="My_Organization" \
--version=1.0
# ls -lh /var/lib/pulp/exports/My_Organization/view/1.0/2021-02-25T21-15-22-00-00/

8.6. Exporting a Content View Version Incrementally

Exporting complete versions can be a very expensive operation in terms of system resources. Content View versions that have multiple Red Hat Enterprise Linux trees can occupy several gigabytes of space on Foreman server.

In such cases, you can use Incremental Export to export only pieces of content that changed since the previous export. Incremental exports typically result in smaller archive files than the full exports.

The example below targets the version 2.0 for export, because the version 1.0 was exported previously.

Procedure

  1. Create an incremental export:

    # hammer content-export incremental version \
--content-view="Content_View_Name" \
--organization="My_Organization" \
--version=2.0

  2. Optional: View the exported Content View:

    # ls -lh /var/lib/pulp/exports/My_Organization/view/2.0/2021-02-25T21-45-34-00-00/

8.7. Exporting a Repository

You can export the content of a repository in the Library environment of an organization from Foreman server. You can use this archive file to create the same repository in another Foreman server or in another Foreman server organization.

You can export the following content from Foreman server:

  • RPM repositories

  • Kickstart repositories

  • Ansible repositories

  • file repositories

You cannot export Docker content nor DEB repositories from Foreman server.

The export contains the following data:

  • Two JSON files containing repository metadata.

  • One or more archive files containing the contents of the repository from the Library environment of the organization.

You need all the files, tar.gz, toc.json and metadata.json, to be able to import.

Prerequisites

To export the contents of a repository, ensure that Foreman server from which you want to export, meets the following conditions:

  • Ensure that the export directory has enough free storage space to accommodate the export.

  • Ensure that the /var/lib/pulp/exports directory has enough free storage space equivalent to the size of the repositories being exported for temporary files created during the export process.

  • Ensure that you set download policy to Immediate for the repository within the Library lifecycle environment you export. For more information, see Download Policies Overview.

  • Ensure that you synchronize Products that you export to the required date.

Export a Repository

  1. Use the repository name or ID to export.

    # hammer content-export complete repository \
 --organization="My_Organization" \
 --product="My_Product" \
 --name="My_Repository"

  2. Optional: Verify that the exported archive is located in the export directory:

    # ls -lh /var/lib/pulp/exports/My_Organization/Export-My_Repository/1.0/2021-03-02T03-35-24-00-00
total 68M
-rw-r--r--. 1 pulp pulp 68M Mar  2 03:35 export-1e25417c-6d09-49d4-b9a5-23df4db3d52a-20210302_0335.tar.gz
-rw-r--r--. 1 pulp pulp 333 Mar  2 03:35 export-1e25417c-6d09-49d4-b9a5-23df4db3d52a-20210302_0335-toc.json
-rw-r--r--. 1 root root 443 Mar  2 03:35 metadata.json
Export a Repository with Chunking

In many cases the exported content archive may be several gigabytes in size. If you want to split it into chunks of smaller size, you can use the --chunk-size-gb argument in the export command and limit the size by an integer value in gigabytes.

  1. Export content into archive chunks of a limited size, such as 2 GB:

    # hammer content-export complete repository \
--chunk-size-gb=2 \
--organization="My_Organization" \
--product="My_Product" \
--name="My_Repository"

Generated /var/lib/pulp/exports/My_Organization/Export-My_Repository/1.0/2021-03-02T03-35-24-00-00/metadata.json

  2. Optional: View the exported data:

    # ls -lh /var/lib/pulp/exports/My_Organization/Export-My_Repository/1.0/2021-03-02T03-35-24-00-00/

8.8. Exporting a Repository Incrementally

Exporting a repository can be a very expensive operation in terms of system resources. A typical Red Hat Enterprise Linux tree may occupy several gigabytes of space on Foreman server.

In such cases, you can use Incremental Export to export only pieces of content that changed since the previous export. Incremental exports typically result in smaller archive files than the full exports.

The example below shows incremental export of a repository in the Library lifecycle environment.

Procedure

  1. Create an incremental export:

    # hammer content-export incremental repository \
 --organization="My_Organization" \
 --product="My_Product" \
 --name="My_Repository"

Generated /var/lib/pulp/exports/My_Organization/Export-My_Repository/3.0/2021-03-02T03-35-24-00-00/metadata.json

  2. Optional: View the exported data:

    # ls -lh /var/lib/pulp/exports/My_Organization/Export-My_Repository/3.0/2021-03-02T03-35-24-00-00/
total 172K
-rw-r--r--. 1 pulp pulp  20M Mar  2 04:22 export-436882d8-de5a-48e9-a30a-17169318f908-20210302_0422.tar.gz
-rw-r--r--. 1 pulp pulp  333 Mar  2 04:22 export-436882d8-de5a-48e9-a30a-17169318f908-20210302_0422-toc.json
-rw-r--r--. 1 root root  492 Mar  2 04:22 metadata.json

8.9. Keeping Track of Your Exports

Foreman keeps records of all exports. Each time you export content on the upstream Foreman server, the export is recorded and maintained for future querying. You can use the records to organize and manage your exports, which is useful especially when exporting incrementally.

When exporting content from the upstream Foreman server for several downstream Foreman servers, you can also keep track of content exported for specific servers. This helps you track which content was exported and to where.

Use the --destination-server argument during export to indicate the target server. This option is available for all content-export operations.

Tracking Destinations of Library Exports

  • Specify the destination server when exporting the Library:

    # hammer content-export complete library \
--destination-server=My_Downstream_Server_1 \
--organization="My_Organization" \
--version=1.0
Tracking Destinations of Content View Exports

  • Specify the destination server when exporting a Content View version:

    # hammer content-export complete version \
--content-view="Content_View_Name" \
--destination-server=My_Downstream_Server_1 \
--organization="My_Organization" \
--version=1.0
Querying Export Records

  • List content exports using the following command:

    # hammer content-export list --organization="My_Organization"

8.10. Importing into the Library Environment

You can import exported Library content into the Library lifecycle environment of an organization on another Foreman server. For more information about exporting contents from the Library environment, see Exporting the Library Environment.

Prerequisites

  • The exported files must be in a directory under /var/lib/pulp/imports.

  • If there are any Red Hat repositories in the exported content, the importing organization’s manifest must contain subscriptions for the products contained within the export.

  • The user importing the content must have the Content Importer Role.

Procedure

  1. Copy the exported files to a subdirectory of /var/lib/pulp/imports on Foreman server where you want to import.

  2. Set the ownership of the import directory and its contents to pulp:pulp.

    # chown -R pulp:pulp /var/lib/pulp/imports/2021-03-02T03-35-24-00-00
# ls -lh /var/lib/pulp/imports/2021-03-02T03-35-24-00-00
total 68M
-rw-r--r--. 1 pulp pulp 68M Mar  2 04:29 export-1e25417c-6d09-49d4-b9a5-23df4db3d52a-20210302_0335.tar.gz
-rw-r--r--. 1 pulp pulp 333 Mar  2 04:29 export-1e25417c-6d09-49d4-b9a5-23df4db3d52a-20210302_0335-toc.json
-rw-r--r--. 1 pulp pulp 443 Mar  2 04:29 metadata.json

  3. Identify the Organization that you wish to import into.

  4. To import the Library content to Foreman server, enter the following command:

    # hammer content-import library \
--organization="My_Organization" \
--path=/var/lib/pulp/imports/2021-03-02T03-35-24-00-00

    Note you must enter the full path /var/lib/pulp/imports/My_Exported_Library_Dir. Relative paths do not work.

  5. To verify that you imported the Library content, check the contents of the Product and Repositories. A new Content View called Import-Library is created in the target organization. This Content View is used to facilitate the Library content import.

    By default, this Content View is not shown in the Foreman web UI. Import-Library is not meant to be assigned directly to hosts. Instead, assign your hosts to Default Organization View or another Content View as you would normally.

8.11. Importing a Content View Version

You can import an exported Content View version to create a version with the same content in an organization on another Foreman server. For more information about exporting a Content View version, see Exporting a Content View Version.

When you import a Content View version, it has the same major and minor version numbers and contains the same repositories with the same packages and errata. Custom Repositories, Products and Content Views are automatically created if they do not exist in the importing organization.

Prerequisites

  • The exported files must be in a directory under /var/lib/pulp/imports.

  • If there are any Red Hat repositories in the exported content, the importing organization’s manifest must contain subscriptions for the products contained within the export.

  • The user importing the Content View version must have the Content Importer Role.

Procedure

  1. Copy the exported files to a subdirectory of /var/lib/pulp/imports on Foreman server where you want to import.

  2. Set the ownership of the import directory and its contents to pulp:pulp.

    # chown -R pulp:pulp /var/lib/pulp/imports/2021-02-25T21-15-22-00-00/

  3. Verify that the ownership is set correctly:

    # ls -lh /var/lib/pulp/imports/2021-02-25T21-15-22-00-00/

  4. To import the Content View version to Foreman server, enter the following command:

    # hammer content-import version \
--organization-id=My_Organization_ID \
--path=/var/lib/pulp/imports/2021-02-25T21-15-22-00-00/

    Note that you must enter the full path /var/lib/pulp/imports/My_Exported_Version_Dir. Relative paths do not work.

  5. To verify that you imported the Content View version successfully, list Content View versions for your organization:

    # hammer content-view version list \
--organization-id=My_Organization_ID

8.12. Importing a Repository

You can import an exported repository into an organization on another Foreman server. For more information about exporting content of a repository, see Exporting a Repository.

Prerequisites

  • The export files must be in a directory under /var/lib/pulp/imports.

  • If the export contains any Red Hat repositories, the manifest of the importing organization must contain subscriptions for the products contained within the export.

  • The user importing the content must have the Content Importer Role.

Procedure

  1. Copy the exported files to a subdirectory of /var/lib/pulp/imports on Foreman server where you want to import.

  2. Set the ownership of the import directory and its contents to pulp:pulp.

    # chown -R pulp:pulp /var/lib/pulp/imports/2021-03-02T03-35-24-00-00
# ls -lh /var/lib/pulp/imports/2021-03-02T03-35-24-00-00
total 68M
-rw-r--r--. 1 pulp pulp 68M Mar  2 04:29 export-1e25417c-6d09-49d4-b9a5-23df4db3d52a-20210302_0335.tar.gz
-rw-r--r--. 1 pulp pulp 333 Mar  2 04:29 export-1e25417c-6d09-49d4-b9a5-23df4db3d52a-20210302_0335-toc.json
-rw-r--r--. 1 pulp pulp 443 Mar  2 04:29 metadata.json

  3. Identify the Organization that you wish to import into.

  4. To import the Library content to Foreman server, enter the following command:

    # hammer content-import repository \
--organization="My_Organization" \
--path=/var/lib/pulp/imports/2021-03-02T03-35-24-00-00

    Note that you must enter the full path /var/lib/pulp/imports/My_Exported_Repo_Dir. Relative paths do not work.

  5. To verify that you imported the repository, check the contents of the Product and Repository.

8.13. Exporting and Importing Content using Hammer CLI Cheat Sheet

Table 3. Export
Intent Command

Fully export an Organization’s Library

hammer content-export complete library --organization="My_Organization"

Incrementally export an Organization’s Library (assuming you have exported something previously)

hammer content-export incremental library --organization="My_Organization"

Fully export a Content View version

hammer content-export complete version --content-view="My_Content_View" --version=1.0 --organization="My_Organization"

Export a Content View version promoted to the Dev Environment

hammer content-export complete version --content-view="My_Content_View" --organization="My_Organization" --lifecycle-environment="Dev"

Export a Content View in smaller chunks (2-GB slabs)

hammer content-export complete version --content-view="My_Content_View" --version=1.0 --organization="My_Organization" --chunk-size-gb=2

Incrementally export a Content View version (assuming you have exported something previously)

hammer content-export incremental version --content-view="My_Content_View" --version=2.0 --organization="My_Organization"

Fully export a Repository

hammer content-export complete repository --product="My_Product" --name="My_Repository" --organization="My_Organization"

Incrementally export a Repository (assuming you have exported something previously)

hammer content-export incremental repository --product="My_Product" --name="My_Repository" --organization="My_Organization"

List exports

hammer content-export list --content-view="My_Content_View" --organization="My_Organization"
Table 4. Import
Intent Command

Import into an Organization’s Library

hammer content-import library --organization="My_Organization" --path="/var/lib/pulp/imports/My_Exported_Library_Dir"

Import to a Content View version

hammer content-import version --organization="My_Organization" --path="/var/lib/pulp/imports/My_Exported_Version_Dir"

Import a Repository

hammer content-import repository --organization="My_Organization" --path="/var/lib/pulp/imports/My_Exported_Repo_Dir"

9. Managing Activation Keys

Activation keys provide a method to automate system registration and subscription attachment. You can create multiple keys and associate them with different environments and Content Views. For example, you might create a basic activation key with a subscription for Red Hat Enterprise Linux workstations and associate it with Content Views from a particular environment.

You can use activation keys during content host registration to improve the speed, simplicity and consistency of the process. Note that activation keys are used only when hosts are registered. If changes are made to an activation key, it is applicable only to hosts that are registered with the amended activation key in the future. The changes are not made to existing hosts.

Activation keys can define the following properties for content hosts:

  • Associated subscriptions and subscription attachment behavior

  • Available products and repositories

  • A life cycle environment and a Content View

  • Host collection membership

  • System purpose

Content View Conflicts between Host Creation and Registration

When you provision a host, Foreman uses provisioning templates and other content from the Content View that you set in the host group or host settings. When the host is registered, the Content View from the activation key overwrites the original Content View from the host group or host settings. Then Foreman uses the Content View from the activation key for every future task, for example, rebuilding a host.

When you rebuild a host, ensure that you set the Content View that you want to use in the activation key and not in the host group or host settings.

Using the Same Activation Key with Multiple Content Hosts

You can apply the same activation key to multiple content hosts if it contains enough subscriptions. However, activation keys set only the initial configuration for a content host. When the content host is registered to an organization, the organization’s content can be attached to the content host manually.

Using Multiple Activation Keys with a Content Host

A content host can be associated with multiple activation keys that are combined to define the host settings. In case of conflicting settings, the last specified activation key takes precedence. You can specify the order of precedence by setting a host group parameter as follows:

$ hammer hostgroup set-parameter \
--hostgroup "My_Host_Group" \
--name "My_Activation_Key" \
--value "name_of_first_key", "name_of_second_key", ...

9.1. Creating an Activation Key

You can use activation keys to define a specific set of subscriptions to attach to hosts during registration. The subscriptions that you add to an activation key must be available within the associated Content View.

Subscription Manager attaches subscriptions differently depending on the following factors:

  • Are there any subscriptions associated with the activation key?

  • Is the auto-attach option enabled?

  • For Red Hat Enterprise Linux 8 hosts: Is there system purpose set on the activation key?

Note that Foreman automatically attaches subscriptions only for the products installed on a host. For subscriptions that do not list products installed on Red Hat Enterprise Linux by default, such as the Extended Update Support (EUS) subscription, use an activation key specifying the required subscriptions and with the auto-attach disabled.

Based on the previous factors, there are three possible scenarios for subscribing with activation keys:

  1. Activation key that attaches subscriptions automatically.

    With no subscriptions specified and auto-attach enabled, hosts using the activation key search for the best fitting subscription from the ones provided by the Content View associated with the activation key. This is similar to entering the subscription-manager --auto-attach command. For Red Hat Enterprise Linux 8 hosts, you can configure the activation key to set system purpose on hosts during registration to enhance the automatic subscriptions attachment.

  2. Activation key providing a custom set of subscription for auto-attach.

    If there are subscriptions specified and auto-attach is enabled, hosts using the activation key select the best fitting subscription from the list specified in the activation key. Setting system purpose on the activation key does not affect this scenario.

  3. Activation key with the exact set of subscriptions.

    If there are subscriptions specified and auto-attach is disabled, hosts using the activation key are associated with all subscriptions specified in the activation key. Setting system purpose on the activation key does not affect this scenario.

Products

If a product, typically containing content not provided by Red Hat, is assigned to an activation key, this product is always enabled for the registered content host regardless of the auto-attach setting.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Activation keys and click Create Activation Key.

  2. In the Name field, enter the name of the activation key.

  3. If you want to set a limit, clear the Unlimited hosts checkbox, and in the Limit field, enter the maximum number of systems you can register with the activation key. If you want unlimited hosts to register with the activation key, ensure the Unlimited Hosts checkbox is selected.

  4. Optional: In the Description field, enter a description for the activation key.

  5. From the Environment list, select the environment to use.

  6. From the Content View list, select a Content View to use. If you intend to use the deprecated Katello Agent instead of Remote Execution, the Content View must contain the https://yum.theforeman.org/client/3.1/ repository because it contains the katello-agent package.

  7. If Simple Content Access (SCA) is enabled:

    1. In the Repository Sets tab, ensure only your named repository is enabled.

  8. If SCA is not enabled:

    1. Click the Subscriptions tab, then click the Add submenu.

    2. Click the checkbox under the subscription you created before.

    3. Click Add Selected.

  9. Click Save.

  10. Optional: For Red Hat Enterprise Linux 8 hosts, in the System Purpose section, you can configure the activation key with system purpose to set on hosts during registration to enhance subscriptions auto attachment.

CLI procedure

  1. Create the activation key:

    # hammer activation-key create \
--name "My_Activation_Key" \
--unlimited-hosts \
--description "Example Stack in the Development Environment" \
--lifecycle-environment "Development" \
--content-view "Stack" \
--organization "My_Organization"

  2. Optional: For Red Hat Enterprise Linux 8 hosts, enter the following command to configure the activation key with system purpose to set on hosts during registration to enhance subscriptions auto attachment.

    # hammer activation-key update \
--organization "My_Organization" \
--name "My_Activation_Key" \
--service-level "Standard" \
--purpose-usage "Development/Test" \
--purpose-role "Red Hat Enterprise Linux Server" \
--purpose-addons "addons"

  3. Obtain a list of your subscription IDs:

    # hammer subscription list --organization "My_Organization"

  4. Attach the Red Hat Enterprise Linux subscription UUID to the activation key:

    # hammer activation-key add-subscription \
--name "My_Activation_Key" \
--subscription-id My_Subscription_ID \
--organization "My_Organization"

  5. List the product content associated with the activation key:

    1. If Simple Content Access (SCA) is enabled:

      # hammer activation-key product-content \
--content-access-mode-all true \
--name "My_Activation_Key" \
--organization "My_Organization"

    2. If SCA is not enabled:

      # hammer activation-key product-content \
--name "My_Activation_Key" \
--organization "My_Organization"

  6. Override the default auto-enable status for the https://yum.theforeman.org/client/3.1/ repository. The default status is set to disabled. To enable, enter the following command:

    # hammer activation-key content-override \
--name "My_Activation_Key" \
--content-label https://yum.theforeman.org/client/3.1/el7/x86_64/foreman-client-release.rpm \
--value 1 \
--organization "My_Organization"

9.2. Updating Subscriptions Associated with an Activation Key

Use this procedure to change the subscriptions associated with an activation key. To use the CLI instead of the Foreman web UI, see the CLI procedure.

Note that changes to an activation key apply only to machines provisioned after the change. To update subscriptions on existing content hosts, see Updating Red Hat Subscriptions on Multiple Hosts.

Procedure

  1. In the Foreman web UI, navigate to Content > Activation keys and click the name of the activation key.

  2. Click the Subscriptions tab.

  3. To remove subscriptions, select List/Remove, and then select the checkboxes to the left of the subscriptions to be removed and then click Remove Selected.

  4. To add subscriptions, select Add, and then select the checkboxes to the left of the subscriptions to be added and then click Add Selected.

  5. Click the Repository Sets tab and review the repositories' status settings.

  6. To enable or disable a repository, select the checkbox for a repository and then change the status using the Select Action list.

  7. Click the Details tab, select a Content View for this activation key, and then click Save.

CLI procedure

  1. List the subscriptions that the activation key currently contains:

    # hammer activation-key subscriptions \
--name My_Activation_Key \
--organization "My_Organization"

  2. Remove the required subscription from the activation key:

    # hammer activation-key remove-subscription \
--name "My_Activation_Key" \
--subscription-id ff808181533518d50152354246e901aa \
--organization "My_Organization"

    For the --subscription-id option, you can use either the UUID or the ID of the subscription.

  3. Attach new subscription to the activation key:

    # hammer activation-key add-subscription \
--name "My_Activation_Key" \
--subscription-id ff808181533518d50152354246e901aa \
--organization "My_Organization"

    For the --subscription-id option, you can use either the UUID or the ID of the subscription.

  4. List the product content associated with the activation key:

    # hammer activation-key product-content \
--name "My_Activation_Key" \
--organization "My_Organization"

  5. Override the default auto-enable status for the required repository:

    # hammer activation-key content-override \
--name "My_Activation_Key" \
--content-label content_label \
--value 1 \
--organization "My_Organization"

    For the --value option, enter 1 for enable, 0 for disable.

9.3. Using Activation Keys for Host Registration

You can use activation keys to complete the following tasks:

  • Registering new hosts during provisioning through Foreman. The kickstart provisioning templates in Foreman contain commands to register the host using an activation key that is defined when creating a host.

  • Registering existing Red Hat Enterprise Linux hosts. Configure Subscription Manager to use Foreman server for registration and specify the activation key when running the subscription-manager register command.

You can register hosts with Foreman using the host registration feature, the Foreman API, or Hammer CLI.

Procedure

  1. In the Foreman web UI, navigate to Hosts > Register Host.

  2. Click Generate to create the registration command.

  3. Click on the files icon to copy the command to your clipboard.

  4. Log in to the host you want register and run the previously generated command.

  5. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

CLI procedure

  1. Generate the host registration command using the Hammer CLI:

    # hammer host-registration generate-command \
--activation-keys "My_Activation_Key"

    If your hosts do not trust the SSL certificate of Foreman server, you can disable SSL validation by adding the --insecure flag to the registration command.

    # hammer host-registration generate-command \
--activation-keys "My_Activation_Key" \
--insecure true

  2. Log in to the host you want register and run the previously generated command.

  3. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

API procedure

  1. Generate the host registration command using the Foreman API:

    # curl -X POST https://foreman.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"] }}'

    If your hosts do not trust the SSL certificate of Foreman server, you can disable SSL validation by adding the --insecure flag to the registration command.

    # curl -X POST https://foreman.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"], "insecure": true }}'

    Use an activation key to simplify specifying the environments. For more information, see Managing Activation Keys in the Content Management guide.

    To enter a password as command line argument, use username:password syntax. Keep in mind this can save the password in the shell history.

    For more information about registration see Registering a Host to Foreman in Managing Hosts.

  2. Log in to the host you want register and run the previously generated command.

  3. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

Multiple Activation Keys

You can use multiple activation keys when registering a content host. You can then create activation keys for specific subscription sets and combine them according to content host requirements. For example, the following command registers a content host to your organization with both VDC and OpenShift subscriptions:

# subscription-manager register --org="My_Organization" \
--activationkey="ak-VDC,ak-OpenShift"
Settings Conflicts

If there are conflicting settings in activation keys, the rightmost key takes precedence.

  • Settings that conflict: Service Level, Release Version, Environment, Content View, and Product Content.

  • Settings that do not conflict and the host gets the union of them: Subscriptions and Host Collections.

  • Settings that influence the behavior of the key itself and not the host configuration: Content Host Limit and Auto-Attach.

9.4. Enabling Auto-Attach

When auto-attach is enabled on an activation key and there are subscriptions associated with the key, the subscription management service selects and attaches the best-matched associated subscriptions based on a set of criteria like currently installed products, architecture, and preferences like service level.

You can enable auto-attach and have no subscriptions associated with the key. This type of key is commonly used to register virtual machines when you do not want the virtual machine to consume a physical subscription, but to inherit a host-based subscription from the hypervisor.

Auto-attach is enabled by default. Disable the option if you want to force attach all subscriptions associated with the activation key.

Procedure

  1. In the Foreman web UI, navigate to Content > Activation Keys.

  2. Click the activation key name that you want to edit.

  3. Click the Subscriptions tab.

  4. Click the edit icon next to Auto-Attach.

  5. Select or clear the checkbox to enable or disable auto-attach.

  6. Click Save.

CLI procedure

  • Enter the following command to enable auto-attach on the activation key:

    # hammer activation-key update --name "My_Activation_Key" \
--organization "My_Organization" --auto-attach true

9.5. Setting the Service Level

You can configure an activation key to define a default service level for the new host created with the activation key. Setting a default service level selects only the matching subscriptions to be attached to the host. For example, if the default service level on an activation key is set to Premium, only subscriptions with premium service levels are attached to the host upon registration.

Procedure

  1. In the Foreman web UI, navigate to Content > Activation Keys.

  2. Click the activation key name you want to edit.

  3. Click the edit icon next to Service Level.

  4. Select the required service level from the list. The list only contains service levels available to the activation key.

  5. Click Save.

CLI procedure

  • Enter the following command to set a default service level to Premium on the activation key:

    # hammer activation-key update --name "My_Activation_Key" \
--organization "My_Organization" --service-level premium

10. Managing SUSE Content

You can use the SCC Manager plug-in to comfortably manage content from SUSE using your Foreman.

10.1. Preparing SUSE Installation Media

Extract the SUSE installation medium on your Foreman server to perform offline installations. This example prepares the installation medium for SUSE Linux Enterprise Server 15 SP3.

Procedure

  1. Download the SLES 15 SP3 installation medium from suse.com/download/sles.

  2. Download the signature and checksum from suse.com.

  3. Transfer the .iso image, the signature, and the checksum from your local machine to Foreman server using scp:

    # scp SLE-15-SP3-Full-x86_64-GM-Media1.iso root@foreman.example.com:/tmp/
# scp SLE-15-SP3-Full-x86_64-GM-Media1.iso.sha256 root@foreman.example.com:/tmp/
# scp sles_15_sp3.signature root@foreman.example.com:/tmp/

  4. On your Foreman server, verify the integrity and authenticity of the .iso image using GPG public keys:

    # cd /tmp
# gpg --verify sles_15_sp3.signature SLE-15-SP3-Full-x86_64-GM-Media1.iso.sha256
# echo '2a6259fc849fef6ce6701b8505f64f89de0d2882857def1c9e4379d26e74fa56 SLE-15-SP3-Full-x86_64-GM-Media1.iso' | sha256sum --check

  5. Mount the .iso image:

    # mount SLE-15-SP3-Full-x86_64-GM-Media1.iso /mnt

  6. Copy the content of the mounted installation medium to the pub directory:

    # mkdir -p /var/www/html/pub/installation_media/sles/15sp3
# cp -a /mnt/* /var/www/html/pub/installation_media/sles/15sp3/

  7. Unmount and delete the .iso image:

    # cd
# umount /mnt
# rm -f /tmp/SLE-15-SP3-Full-x86_64-GM-Media1.iso
# rm -f /tmp/SLE-15-SP3-Full-x86_64-GM-Media1.iso.sha256
# rm -f /tmp/sles_15_sp3.signature

Use the path to the local installation media files when creating an installation medium, for example http://foreman.example.com/pub/installation_media/sles/15sp3/.

10.2. Creating a SUSE Operating System

Create an installation media and operating system entry for SLES 15 SP3.

Prerequisite

  • An extracted .iso image on Foreman or an HTTP server that can be reached during the host provisioning process.

Procedure

  1. In the Foreman web UI, navigate to Hosts > Installation Media and click Create Medium.

  2. Set a Name for the installation medium for SLES 15 SP3. Add local to the name because the path of the extracted .iso image points to your Foreman.

  3. Set the Path of the extracted .iso image. The content of /var/www/html/pub/ is publicly available on http://foreman.example.com/pub/. If you extract the .iso image to /var/www/html/pub/installation_media/sles/15sp3/, the path is http://foreman.example.com/pub/installation_media/sles/15sp3/.

  4. Set the Operating System Family to SUSE for all SLES systems.

  5. Set a location and organization context for the installation media.

  6. On the Parameters tab, add the sle-module-basesystem-url parameter, select the string type, and enter the value http://foreman.example.com/pub/installation_media/sles/15sp3/. Note that the value depends on the path of the extracted .iso image.

    (SLES 12 only) Add the parameter additional_media, select the string type, and enter the value "".

  7. Click Submit to save the installation media entry for SLES 15 SP3.

  8. In the Foreman web UI, navigate to Hosts > Operating Systems and click Create Operating System.

  9. Set the Name of the operating system. Choose a name as reported by Ansible, Puppet, or Salt as fact.

  10. Set the Major Version of SLES, for example 15.

  11. Set the Minor Version of SLES, for example 3 for SLES 15 SP3.

  12. Optional: Add an arbitrary Description.

  13. Set the Family to SUSE for all SLES systems.

  14. Set the Root Password Hash to SHA256 for SLES 15 SP3.

  15. Assign the Architectures to SLES 15 SP3.

  16. Click Submit to save the operating system entry.

  17. In the Foreman web UI, navigate to Hosts > Partition Tables and click Create Partition Table. The partition tables are stored in the /usr/share/foreman/app/views/unattended/partition_tables_templates/ directory on your Foreman server.

    For more information, see Partition Tables in the Provisioning guide.

  18. In the Foreman web UI, navigate to Hosts > Provisioning Templates and click Create Template. The provisioning templates are stored in the /usr/share/foreman/app/views/unattended/provisioning_templates/ directory on your Foreman server.

    For more information, see Provisioning Templates in the Provisioning guide.

  19. In the Foreman web UI, navigate to Hosts > Operating Systems.

  20. Select the previously created operating system.

  21. On the Partition Table tab, select the previously created partition table.

  22. On the Templates tab, select the previously created provisioning template.

  23. Click Submit to save the operating system entry.

10.3. Installing the SCC Manager Plug-in

Perform the following steps to install the SCC Manager plug-in on your Foreman.

Procedure

  1. Connect to your Foreman server using SSH:

    # ssh root@foreman.example.com

  2. Install the SCC Manager plug-in on your Foreman:

    # yum install -y tfm-rubygem-foreman_scc_manager
Note
 For Enterprise Linux 8, remove tfm- from the prefix of packages.

  1. Run database migrations on your Foreman:

    # foreman-rake db:migrate
# foreman-rake db:seed

  2. Restart Foreman services:

    # foreman-maintain service restart

Continue with adding your SCC account to Foreman.

10.4. Adding an SCC Account to Foreman

Prerequisite
Procedure

  1. In the Foreman web UI, navigate to Content > Content Credentials and click Create Content Credential.

    Add the GPG public key for SLES 15 SP3 from suse.com.

  2. In the Foreman web UI, navigate to Content > SUSE Subscriptions.

  3. Click Add SCC Account.

  4. Enter your account name and password.

  5. Optional: Set a Sync interval to periodically update the SCC authentication tokens. Note that this does not refer to synchronizing content to Foreman.

  6. Assign a GPG key for SUSE products to the SCC products. zypper automatically verifies the signatures of each software package to ensure their authenticity.

    Note

    You can also set the GPG public key for SUSE repositories at a later stage. However, changing it does not affect already synchronized products. If you already have synchronized products in Foreman, navigate to Content > Products and replace the GPG key in each respective product.

  7. Click Test connection to verify your account information. Note that you have to re-enter your password if you have already saved your SCC account to Foreman.

  8. Click Submit to save your SCC account to Foreman.

  9. In the Foreman web UI, navigate to Content > SUSE Subscriptions, select your SCC account, and click Sync to fetch a list of products associated to your SCC account.

Continue with importing products from your SCC account.

10.5. Switching SCC Accounts

You can switch your SCC account by changing the SCC credentials saved on Foreman.

Warning

The SCC Manager plug-in does not support multiple SCC accounts.

If you want to switch your SCC account and retain the synchronized content, do not immediately delete your old SCC account, even if it is expired. If you delete your old SCC account, you cannot reuse existing repositories, products, Content Views, and composite Content Views.
Procedure

  1. In the Foreman web UI, navigate to Content > SUSE Subscriptions.

  2. Select your SCC account.

  3. Enter a new Login and Password.

  4. Click Submit to change your SCC account.

Your new SCC account reuses existing products and repositories from SUSE. Content that is no longer available for your new SCC account cannot be synchronized anymore.

10.6. Importing SUSE Products

Prerequisites
Procedure

  1. In the Foreman web UI, navigate to Content > SUSE Subscriptions.

  2. Click Select products on your previously synchronized SCC account.

  3. Select all SUSE products you want to synchronize to Foreman. This guide assumes you have access to and select the SUSE Linux Enterprise Server 15 SP3 x86_64 product.

  4. Click Submit to create the selected SUSE products in Foreman.

Continue with synchronizing SUSE products.

10.7. Synchronizing SUSE Content

You can use Foreman to synchronize SUSE content to deploy, attach, and serve content to managed hosts.

Procedure

  1. In the Foreman web UI, navigate to Content > Products.

  2. Select the SUSE Linux Enterprise Server 15 SP3 x86_64 product and click Sync Now to synchronize the SUSE repositories for SLES 15 SP3 to Foreman.

  3. In the Foreman web UI, navigate to Content > Content Views.

  4. Create a Content View called SLES 15 SP3 comprising the SLES repositories created in the SLES 15 SP3 product and a Content View called SLES 15 SP3 Foreman client comprising the Foreman client repository created in the SLES 15 SP3 Foreman client product.

    For more information, see creating a Content View.

  5. Publish a new version of both Content Views.

    For more information, see promoting a Content View.

  6. In the Foreman web UI, navigate to Content > Content Views.

  7. Click Create Content View to create a Composite Content View called Composite SLES 15 SP3 comprising the previously published SLES 15 SP3 Content View, the SLES 15 SP3 Foreman client Content View, and optionally further Content Views of your choice, for example a Content View containing Puppet. For more information, see creating a Composite Content View.

  8. Publish a new version and promote this version to the Life Cycle Environment of your choice.

  9. In the Foreman web UI, navigate to Content > Activation Keys.

  10. Click Create Activation Key to create an Activation Key called sles-15-sp3.

    For more information, see creating an Activation Key.

  11. On the Details tab, select a Life Cycle Environment and Composite Content View.

  12. On the Subscriptions tab, select the necessary subscriptions, for example SLES 15 SP3, SLES 15 SP3 Foreman client, and Puppet.

You can now create a Host Group and assign the previously created Activation Key to it to deploy hosts running SLES 15 SP3 more comfortably.

11. Managing Errata

Red Hat Enterprise Linux users receive errata for each release of official Red Hat RPMs. SUSE Linux Enterprise Server users receive errata for each release of official SUSE RPMs. There are three types of advisories (in order of importance):

Security Advisory

Describes fixed security issues found in the package. The security impact of the issue can be Low, Moderate, Important, or Critical.

Bug Fix Advisory

Describes bug fixes for the package.

Product Enhancement Advisory

Describes enhancements and new features added to the package.

For Red Hat Enterprise Linux, Foreman imports errata information when synchronizing repositories with Red Hat’s Content Delivery Network (CDN). For SUSE Linux Enterprise Server, Foreman imports errata information when synchronizing repositories with SUSE Customer Center. For Alma Linux and Rocky Linux, Foreman imports errata information when synchronizing repositories with upstream repositories. Foreman also provides tools to inspect and filter errata, allowing for precise update management. This way, you can select relevant updates and propagate them through Content Views to selected content hosts.

Errata are labeled according to the most important advisory type they contain. Therefore, errata labeled as Product Enhancement Advisory can contain only enhancement updates, while Bug Fix Advisory errata can contain both bug fixes and enhancements, and Security Advisory can contain all three types.

In Foreman, there are two keywords that describe an erratum’s relationship to the available content hosts:

Applicable

An erratum that applies to one or more content hosts, which means it updates packages present on the content host. Although these errata apply to content hosts, until their state changes to Installable, the errata are not ready to be installed. Installable errata are automatically applicable.

Installable

An erratum that applies to one or more content hosts and is available to install on the content host. Installable errata are available to a content host from life cycle environment and the associated Content View, but are not yet installed.

This chapter shows how to manage errata and apply them to either a single host or multiple hosts.

11.1. Inspecting Available Errata

The following procedure describes how to view and filter the available errata and how to display metadata of the selected advisory. To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Errata to view the list of available errata.

  2. Use the filtering tools at the top of the page to limit the number of displayed errata:

    • Select the repository to be inspected from the list. All Repositories is selected by default.

    • The Applicable checkbox is selected by default to view only applicable errata in the selected repository. Select the Installable checkbox to view only errata marked as installable.

    • To search the table of errata, type the query in the Search field in the form of:

      parameter operator value

      See Parameters Available for Errata Search for the list of parameters available for search. Find the list of applicable operators in Supported Operators for Granular Search in Administering Foreman. Automatic suggestion works as you type. You can also combine queries with the use of and and or operators. For example, to display only security advisories related to the kernel package, type:

      type = security and package_name = kernel

      Press Enter to start the search.

  3. Click the Errata ID of the erratum you want to inspect:

    • The Details tab contains the description of the updated package as well as documentation of important fixes and enhancements provided by the update.

    • On the Content Hosts tab, you can apply the erratum to selected content hosts as described in Applying Errata to Multiple Hosts.

    • The Repositories tab lists repositories that already contain the erratum. You can filter repositories by the environment and Content View, and search for them by the repository name.

You can also use the new Host page to view to inspect available errata and select errata to install.

  1. In the Foreman web UI, navigate to Hosts > All Hosts and select the host you require.

  2. If there are errata associated with the host, an Installable Errata card on the new Host page displays an interactive pie chart showing a breakdown of the security advisories, bugfixes, and enhancements.

  3. On the new Host page, select the Content tab.

  4. On the Content page select the Errata tab.

  5. The page displays installable errata for the chosen host.

  6. Click the checkbox for any errata you wish to install.

  7. Using the vertical ellipsis icon next to the errata you want to add to the host, select Apply via Katello agent if you have no connectivity to the target host using SSH.

  8. Select Apply via Remote Execution to use Remote Execution, or Apply via customized remote execution if you want to customize the remote execution.

  9. Click Submit.

CLI procedure

  • To view errata that are available for all organizations, enter the following command:

    # hammer erratum list

  • To view details of a specific erratum, enter the following command:

    # hammer erratum info --id erratum_ID

  • You can search errata by entering the query with the --search option. For example, to view applicable errata for the selected product that contains the specified bugs ordered so that the security errata are displayed on top, enter the following command:

    # hammer erratum list \
--product-id 7 \
--search "bug = 1213000 or bug = 1207972" \
--errata-restrict-applicable 1 \
--order "type desc"

11.2. Parameters Available for Errata Search

Parameter Description Example

bug

Search by the Bugzilla number.

bug = 1172165

cve

Search by the CVE number.

cve = CVE-2015-0235

id

Search by the errata ID. The auto-suggest system displays a list of available IDs as you type.

id = RHBA-2014:2004

issued

Search by the issue date. You can specify the exact date, like "Feb16,2015", or use keywords, for example "Yesterday", or "1 hour ago". The time range can be specified with the use of the "<" and ">" operators.

issued < "Jan 12,2015"

package

Search by the full package build name. The auto-suggest system displays a list of available packages as you type.

package = glib2-2.22.5-6.el6.i686

package_name

Search by the package name. The auto-suggest system displays a list of available packages as you type.

package_name = glib2

severity

Search by the severity of the issue fixed by the security update. Specify Critical, Important, or Moderate.

severity = Critical

title

Search by the advisory title.

title ~ openssl

type

Search by the advisory type. Specify security, bugfix, or enhancement.

type = bugfix

updated

Search by the date of the last update. You can use the same formats as with the issued parameter.

updated = "6 days ago"

11.3. Applying Installable Errata

Use the following procedure to view a list of installable errata and select errata to install.

Procedure

  1. In the Foreman web UI, navigate to Hosts > All Hosts and select the host you require.

  2. If there are errata associated with the host, they are displayed in an Installable Errata card on the new Host page.

  3. On the Content tab, Errata displays installable errata for the chosen host.

  4. Click the checkbox for any errata you wish to install.

  5. Using the vertical ellipsis icon next to the errata you want to add to the host, select Apply via Remote Execution to use Remote Execution. Select Apply via customized remote execution if you want to customize the remote execution, or select Apply via Katello agent if you have no connectivity to the target host using SSH.

  6. Click Submit.

11.4. Subscribing to Errata Notifications

You can configure email notifications for Foreman users. Users receive a summary of applicable and installable errata, notifications on Content View promotion or after synchronizing a repository. For more information, see Configuring Email Notifications in the Administering Foreman guide.

11.5. Limitations to Repository Dependency Resolution

With Foreman, using incremental updates to your Content Views solves some repository dependency problems. However, dependency resolution at a repository level still remains problematic on occasion.

When a repository update becomes available with a new dependency, Foreman retrieves the newest version of the package to solve the dependency, even if there are older versions available in the existing repository package. This can create further dependency resolution problems when installing packages.

Example scenario

A repository on your client has the package example_repository-1.0 with the dependency example_repository-libs-1.0. The repository also has another package example_tools-1.0.

A security erratum becomes available with the package example_tools-1.1. The example_tools-1.1 package requires the example_repository-libs-1.1 package as a dependency.

After an incremental Content View update, the example_tools-1.1, example_tools-1.0, and example_repository-libs-1.1 are now in the repository. The repository also has the packages example_repository-1.0 and example_repository-libs-1.0. Note that the incremental update to the Content View did not add the package example_repository-1.1. Because you can install all these packages using yum, no potential problem is detected. However, when the client installs the example_tools-1.1 package, a dependency resolution problem occurs because both example_repository-libs-1.0 and example_repository-libs-1.1 cannot be installed.

There is currently no workaround for this problem. The larger the time frame, and major Y releases between the base set of RPMs and the errata being applied, the higher the chance of a problem with dependency resolution.

11.6. Creating a Content View Filter for Errata

You can use content filters to limit errata. Such filters include:

  • ID – Select specific erratum to allow into your resulting repositories.

  • Date Range – Define a date range and include a set of errata released during that date range.

  • Type – Select the type of errata to include such as bug fixes, enhancements, and security updates.

Create a content filter to exclude errata after a certain date. This ensures your production systems in the application life cycle are kept up to date to a certain point. Then you can modify the filter’s start date to introduce new errata into your testing environment to test the compatibility of new packages into your application life cycle.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

Prerequisites

  • A Content View with the repositories that contain required errata is created. For more information, see Creating a Content View.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views and select a Content View that you want to use for applying errata.

  2. Select Yum Content > Filters and click New Filter.

  3. In the Name field, enter Errata Filter.

  4. From the Content Type list, select Erratum – Date and Type.

  5. From the Inclusion Type list, select Exclude.

  6. In the Description field, enter Exclude errata items from YYYY-MM-DD.

  7. Click Save.

  8. For Errata Type, select the checkboxes of errata types you want to exclude. For example, select the Enhancement and Bugfix checkboxes and clear the Security checkbox to exclude enhancement and bugfix errata after certain date, but include all the security errata.

  9. For Date Type, select one of two checkboxes:

    • Issued On for the issued date of the erratum.

    • Updated On for the date of the erratum’s last update.

  10. Select the Start Date to exclude all errata on or after the selected date.

  11. Leave the End Date field blank.

  12. Click Save.

  13. Click Publish New Version to publish the resulting repository.

  14. Enter Adding errata filter in the Description field.

  15. Click Save.

    When the Content View completes publication, notice the Content column reports a reduced number of packages and errata from the initial repository. This means the filter successfully excluded the all non-security errata from the last year.

  16. Click the Versions tab.

  17. Click Promote to the right of the published version.

  18. Select the environments you want to promote the Content View version to.

  19. In the Description field, enter the description for promoting.

  20. Click Promote Version to promote this Content View version across the required environments.

CLI procedure

  1. Create a filter for the errata:

    # hammer content-view filter create --name "Filter Name" \
--description "Exclude errata items from the YYYY-MM-DD" \
--content-view "CV Name" --organization "Default Organization" \
--type "erratum"

  2. Create a filter rule to exclude all errata on or after the Start Date that you want to set:

    # hammer content-view filter rule create --start-date "YYYY-MM-DD" \
--content-view "CV Name" --content-view-filter="Filter Name" \
--organization "Default Organization" --types=security,enhancement,bugfix

  3. Publish the Content View:

    # hammer content-view publish --name "CV Name" \
--organization "Default Organization"

  4. Promote the Content View to the lifecycle environment so that the included errata are available to that lifecycle environment:

    # hammer content-view version promote \
--content-view "CV Name" \
--organization "Default Organization" \
--to-lifecycle-environment "Lifecycle Environment Name"

11.7. Adding Errata to an Incremental Content View

If errata are available but not installable, you can create an incremental Content View version to add the errata to your content hosts. For example, if the Content View is version 1.0, it becomes Content View version 1.1, and when you publish, it becomes Content View version 2.0.

Important
 If your Content View version is old, you might encounter incompatibilities when incrementally adding enhancement errata. This is because enhancements are typically designed for the most current software in a repository.

To use the CLI instead of the Foreman web UI, see CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Errata.

  2. From the Errata list, click the name of the errata that you want to apply.

  3. Select the content hosts that you want to apply the errata to, and click Apply to Hosts. This creates the incremental update to the Content View.

  4. If you want to apply the errata to the content host, select the Apply Errata to Content Hosts immediately after publishing checkbox.

  5. Click Confirm to apply the errata.

CLI procedure

  1. List the errata and its corresponding IDs:

    # hammer erratum list

  2. List the different content-view versions and the corresponding IDs:

    # hammer content-view version list

  3. Apply a single erratum to content-view version. You can add more IDs in a comma-separated list.

    # hammer content-view version incremental-update \
--content-view-version-id 319 --errata-ids 34068b

11.8. Applying Errata to a Host

Use these procedures to review and apply errata to a host.

Prerequisites

  • Register the host to an environment and Content View on Foreman server. For more information, see Registering Hosts in the Managing Hosts guide.

  • Configure the host for remote execution. For more information about running remote execution jobs, see Configuring and Setting Up Remote Jobs in the Managing Hosts guide.

Note

If the host is already configured to receive content updates with the deprecated Katello Agent, migrate to remote execution instead. For more information, see Migrating Hosts From Katello Agent to Remote Execution in Managing Hosts.

The procedure to apply an erratum to a managed host depends on its operating system.

11.8.1. Applying Errata to a Host running CentOS 7

Use these procedures to review and apply errata to a host running CentOS 7.

Procedure

  1. In the Foreman web UI, navigate to Hosts > Content Hosts and select the host you want to apply errata to.

  2. Navigate to the Errata tab to see the list of errata.

  3. Select the errata to apply and click Apply Selected. In the confirmation window, click Apply.

  4. After the task to update all packages associated with the selected errata completes, click the Details tab to view the updated packages.

CLI procedure

  1. List all errata for the host:

    # hammer host errata list \
--host client.example.com

  2. Apply the most recent erratum to the host. Identify the erratum to apply using the erratum ID:

    # hammer job-invocation create \
--feature katello_errata_install \
--inputs errata=ERRATUM_ID1,ERRATUM_ID2 \
--search-query "name = client.example.com"

11.8.2. Applying Errata to a Host running Debian or Ubuntu

Use these procedures to review and apply errata to a host running Debian or Ubuntu.

Procedure

  1. In the Foreman web UI, navigate to Hosts > Content Hosts and select the host you want to apply errata to.

  2. Navigate to the Errata tab to see the list of errata.

  3. Select the errata to apply and click Apply Selected. In the confirmation window, click Apply.

  4. After the task to update all packages associated with the selected errata completes, click the Details tab to view the updated packages.

CLI procedure

  1. List all errata for the host:

    # hammer host errata list \
--host client.example.com

  2. Apply the most recent erratum to the host. Identify the erratum to apply using the erratum ID.

    Using Remote Execution

    # hammer job-invocation create \
--feature katello_errata_install \
--inputs errata=ERRATUM_ID1,ERRATUM_ID2 \
--search-query "name = client.example.com"

11.8.3. Applying Errata to a Host running Red Hat Enterprise Linux 7

Use these procedures to review and apply errata to a host running Red Hat Enterprise Linux 7.

Procedure

  1. In the Foreman web UI, navigate to Hosts > Content Hosts and select the host you want to apply errata to.

  2. Navigate to the Errata tab to see the list of errata.

  3. Select the errata to apply and click Apply Selected. In the confirmation window, click Apply.

  4. After the task to update all packages associated with the selected errata completes, click the Details tab to view the updated packages.

CLI procedure

  1. List all errata for the host:

    # hammer host errata list \
--host client.example.com

  2. Apply the most recent erratum to the host. Identify the erratum to apply using the erratum ID.

    Using Remote Execution

    # hammer job-invocation create \
--feature katello_errata_install \
--inputs errata=ERRATUM_ID1,ERRATUM_ID2 \
--search-query "name = client.example.com"

    Using Katello Agent (deprecated)

    # hammer host errata apply --host "client.example.com" \
--errata-ids ERRATUM_ID1,ERRATUM_ID2...

11.8.4. Applying Errata to a Host running Red Hat Enterprise Linux 8

Use this procedure to review and apply errata to a host running Red Hat Enterprise Linux 8.

CLI procedure

  1. On Foreman, list all errata for the host:

    # hammer host errata list \
--host client.example.com

  2. Find the module stream an erratum belongs to:

    # hammer erratum info --id ERRATUM_ID

  3. On the host, update the module stream:

    # yum update Module_Stream_Name

11.8.5. Applying Errata to a Host Running SLES 15

Use this procedure to review and apply errata to a host running SUSE Linux Enterprise Server 15.

Procedure

  1. In the Foreman web UI, navigate to Hosts > Content Hosts and select the host you want to apply errata to.

  2. Navigate to the Errata tab to view the list of errata.

  3. Select the errata to apply and click Apply Selected. In the confirmation window, click Apply.

  4. After the task to update all packages associated with the selected errata completes, click the Details tab to view the updated packages.

CLI procedure

  1. List all errata for the host:

    # hammer host errata list \
--host client.example.com

  2. Apply the most recent erratum to the host. Identify the erratum to apply using the erratum ID:

    # hammer job-invocation create \
--feature katello_errata_install \
--inputs errata=ERRATUM_ID1,ERRATUM_ID2 \
--search-query "name = client.example.com"

11.9. Applying Errata to Multiple Hosts

Use these procedures to review and apply errata to multiple RHEL 7 hosts.

Prerequisites

  • Synchronize Foreman repositories with the latest errata available from Red Hat. For more information, see Synchronizing Repositories.

  • Register the hosts to an environment and Content View on Foreman server. For more information, see Registering Hosts in the Managing Hosts guide.

  • Configure the host for remote execution. For more information about running remote execution jobs, see Configuring and Setting Up Remote Jobs in the Managing Hosts guide.

Note

If the host is already configured to receive content updates with the deprecated Katello Agent, migrate to remote execution instead. For more information, see Migrating Hosts From Katello Agent to Remote Execution in Managing Hosts.
Procedure

  1. In the Foreman web UI, navigate to Content > Errata.

  2. Click the name of an erratum you want to apply.

  3. Click to Content Hosts tab.

  4. Select the hosts you want to apply errata to and click Apply to Hosts.

  5. Click Confirm.

CLI procedure

  1. List all installable errata:

    # hammer erratum list \
--errata-restrict-installable true \
--organization "Default Organization"

  2. Apply one of the errata to multiple hosts:

    Using Remote Execution

    # hammer job-invocation create \
--feature katello_errata_install \
--inputs errata=ERRATUM_ID \
--search-query "applicable_errata = ERRATUM_ID"

    Using Katello Agent (deprecated)

    Identify the erratum you want to use and list the hosts that this erratum is applicable to:

    # hammer host list \
--search "applicable_errata = ERRATUM_ID" \
--organization "Default Organization"

    The following Bash script applies an erratum to each host for which this erratum is available:

    for HOST in hammer --csv --csv-separator "|" host list --search "applicable_errata = ERRATUM_ID" --organization "Default Organization" | tail -n+2 | awk -F "|" '{ print $2 }' ;
do
  echo "== Applying to $HOST ==" ; hammer host errata apply --host $HOST --errata-ids ERRATUM_ID1,ERRATUM_ID2 ;
done

    This command identifies all hosts with erratum_IDs as an applicable erratum and then applies the erratum to each host.

  3. To see if an erratum is applied successfully, find the corresponding task in the output of the following command:

    # hammer task list

  4. View the state of a selected task:

    # hammer task progress --id task_ID

11.10. Applying Errata to a Host Collection

Using Remote Execution
# hammer job-invocation create \
--feature katello_errata_install \
--inputs errata=ERRATUM_ID1,ERRATUM_ID2,... \
--search-query "host_collection = HOST_COLLECTION_NAME"
Using Katello Agent (deprecated)
# hammer host-collection erratum install \
--errata "erratum_ID1,erratum_ID2,..." \
--name "host_collection_name"\
--organization "My_Organization"

12. Managing OSTree Content

You can use OSTree to manage bootable, immutable, versioned file system trees.

OSTree makes it easy to install and update Linux-based operating systems on hosts and to switch between versions of operating systems on hosts. If a host update fails, you can easily revert the operating system on the host to the previous working version.

You can create an OSTree image using an image builder and expose it in an OSTree repository on an HTTP server. Then you can use your Foreman to synchronize and manage OSTree branches from the exposed OSTree repository.

Prerequisites

  • OSTree content is supported only when running Foreman on Enterprise Linux 8.

  • In Foreman server, OSTree management tools are not enabled by default. To enable OSTree, enter the following command:

    # foreman-installer --foreman-proxy-content-enable-ostree=true

  • If you want to use Hammer CLI, you must enable the hammer-cli-katello plugin on Foreman server.

12.1. Importing OSTree Content

You can import and synchronize OSTree content from custom online sources over HTTPS.

Prerequisite

  • A published HTTP location, known as an upstream URL, for the OSTree to import.

Procedure

  1. In the Foreman web UI, navigate to Content > Products and click Create Product.

  2. In the Name field, enter a name for your OSTree content. This automatically populates the Label field.

  3. Optional: From the GPG Key list, select the GPG key for the product.

  4. Optional: From the SSL CA Cert list, select the SSL CA certificate for the product.

  5. Optional: From the SSL Client Cert list, select the SSL client certificate for the product.

  6. Optional: From the SSL Client Key list, select the SSL client key for the product.

  7. Optional: From the Sync Plan list, select an existing sync plan or click Create Sync Plan and create a sync plan for your product requirements.

  8. Optional: In the Description field, enter a description of the product.

  9. Click Save.

  10. When the product creation completes, click New Repository.

  11. In the Name field, enter a name for the repository. This automatically populates the Label field.

  12. From the Type list, select ostree.

  13. In the Upstream URL field, enter the URL of the external repository to use as a source. For example http://www.example.com/rpm-ostree/.

  14. Optional: Select the Verify SSL checkbox if you want to verify that the upstream repository’s SSL certificates are signed by a trusted CA.

  15. In the Upstream Username field, enter the user name for the upstream repository if required for authentication. Clear this field if the repository does not require authentication.

  16. In the Upstream Password field, enter the corresponding password for the upstream repository.

  17. In the Upstream Authentication Token field, enter the corresponding token for the upstream repository.

  18. From the Mirroring Policy menu, select one of the following policies to mirror OSTree content for this repository:

    • Additive – new content available during sync will be added to the repository, and no content will be removed.

    • Mirror Content Only – any new content available during sync will be added to the repository and any content removed from the upstream repository will be removed from the local repository.

  19. Optional: In the HTTP Proxy Policy field, select an HTTP proxy.

  20. Optional: Disable the Unprotected checkbox to require a subscription entitlement certificate for accessing the published repository.

  21. Optional: In the SSL CA Cert field, select the SSL CA Certificate for the repository.

  22. Optional: In the SSL Client cert field, select the SSL Client Certificate for the repository.

  23. Optional: In the SSL Client Key field, select the SSL Client Key for the repository.

  24. Click Save.

  25. When the repository creation completes, select the new repository and click Sync Now to start the synchronization process.

  26. To view the synchronization status, navigate to Content > Sync Status and expand the entry that you want to view.

CLI Procedure

  1. Create a product for your OSTree content:

    # hammer product create \
--name "OSTree" \
--sync-plan "Example_Plan" \
--description "OSTree Content" \
--organization "My_Organization"

  2. Create the repository for the OSTree:

    # hammer repository create \
--name "OSTree" \
--content-type "ostree" \
--url "http://www.example.com/rpm-ostree/" \
--product "OSTree Content" \
--organization "My_Organization"

  3. Synchronize the repository:

    # hammer repository synchronize \
--name "OSTree" \
--product "OSTree Content" \
--organization "My_Organization"

12.2. Uploading OSTree Content with Hammer CLI

In deployments in which the Foreman server does not have internet access, you can upload OSTree image archives using Hammer CLI.

You can create images using the Image Builder or OSBuild tool.

You can also create an OSTree image archive by downloading a repository from an upstream URL, such as:

# wget --no-parent -r https://repos.example.com/ostree/repo_name/
# tar --exclude="index.html" -cvf "example_archive_repo.tar" -C repos.example.com/ostree "repo_name"
Prerequisite

  • You have an OSTree image archive ready and present on your file system.

Procedure

  1. Connect to your Foreman server using SSH.

  2. Upload your OSTree archive with the hammer command:

    # hammer repository upload-content --id repository_id \
--content-type ostree_ref \
--path /path/to/image/file.tar \
--ostree-repository-name example_repo_name

    The value of --ostree-repository-name must match the name of the OSTree repository in the archive.

Additional resources

12.3. Managing OSTree Content with Content Views

Use Content Views to manage OSTree branches across the application life cycle. This process uses the same publication and promotion method as RPMs or Puppet modules.

Prerequisite

  • You have created a Product and added an OSTree repository to it.

Procedure

  1. In the Foreman web UI, navigate to Content > Content Views and click Create content view.

  2. In the Name field, enter a plain text name for the view. This automatically populates the Label field.

  3. In the Description field, enter a description of the OSTree Content View.

  4. If you want to use a Composite Content View, select the Composite View checkbox.

  5. Optional: If you want to solve dependencies automatically every time you publish this Content View, select the Solve Dependencies checkbox. Dependency solving slows the publishing time and might ignore any Content View filters you use.

  6. Optional: If this Content View is for importing from an upstream server only, select the Import only checkbox. You cannot publish import-only Content Views directly.

  7. Click Save to complete.

  8. Navigate to the Repositories tab.

  9. Select the OSTree repository that you want to use. Click Add Repository to add the OSTree content from this repository to the Content View.

  10. Click Publish new version.

  11. Optional: In the Description field, enter a description for the version.

  12. Optional: Enable the Promote switch to promote this Content View across environments in the application life cycle.

  13. Click Next.

  14. Review details and click Finish.

CLI Procedure

  1. Obtain a list of repository IDs:

    # hammer repository list --organization "My_Organization"

  2. Create the Content View and add the repository:

    # hammer content-view create \
--name "OSTree" \
--description "Example Content View for the OSTree" \
--repository-ids 5 \
--organization "My_Organization"

  3. Publish the Content View:

    # hammer content-view publish \
--name "OSTree" \
--description "Example Content View for the OSTree" \
--organization "My_Organization"

13. Managing Container Images

With Foreman, you can import container images from various sources and distribute them to external containers using Content Views.

For information about containers, see Getting Started with Containers in Red Hat Enterprise Linux Atomic Host 7.

13.1. Importing Container Images

You can import container image repositories from Red Hat Registry or from other image registries.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure with repository discovery

  1. In the Foreman web UI, navigate to Content > Products and click Repo Discovery.

  2. From the Repository Type list, select Container Images.

  3. In the Registry to Discover field, enter the URL of the registry to import images from.

  4. In the Registry Username field, enter the name that corresponds with your user name for the container image registry.

  5. In the Registry Password field, enter the password that corresponds with the user name that you enter.

  6. In the Registry Search Parameter field, enter any search criteria that you want to use to filter your search, and then click Discover.

  7. Optional: To further refine the Discovered Repository list, in the Filter field, enter any additional search criteria that you want to use.

  8. From the Discovered Repository list, select any repositories that you want to import, and then click Create Selected.

  9. Optional: To change the download policy for this container repository to on demand, see Changing the Download Policy for a Repository.

  10. Optional: If you want to create a product, from the Product list, select New Product.

  11. In the Name field, enter a product name.

  12. Optional: In the Repository Name and Repository Label columns, you can edit the repository names and labels.

  13. Click Run Repository Creation.

  14. When repository creation is complete, you can click each new repository to view more information.

  15. Optional: To filter the content you import to a repository, click a repository, and then navigate to Limit Sync Tags. Click to edit, and add any tags that you want to limit the content that synchronizes to Foreman.

  16. In the Foreman web UI, navigate to Content > Products and select the name of your product.

  17. Select the new repositories and then click Sync Now to start the synchronization process.

Procedure with creating a repository manually

  1. In the Foreman web UI, navigate to Content > Products. Click the name of the required product.

  2. Click New repository.

  3. From the Type list, select docker. Enter the details for the repository, and click Save.

  4. Select the new repository, and click Sync Now.

Next steps

  • To view the progress of the synchronization, navigate to Content > Sync Status and expand the repository tree.

  • When the synchronization completes, you can click Container Image Manifests to list the available manifests. From the list, you can also remove any manifests that you do not require.

CLI procedure

  1. Create the custom Red Hat Container Catalog product:

    # hammer product create \
--description "Red Hat Container Catalog content" \
--name "Red Hat Container Catalog" \
--organization "My_Organization" \
--sync-plan "My_Sync_Plan"

  2. Create the repository for the container images:

    # hammer repository create \
--name "RHEL7" \
--content-type "docker" \
--url "http://registry.access.redhat.com/" \
--docker-upstream-name "rhel7" \
--product "Red Hat Container Catalog" \
--organization "My_Organization"

  3. Synchronize the repository:

    # hammer repository synchronize \
--name "RHEL7" \
--product "Red Hat Container Catalog" \
--organization "My_Organization"
Additional resources

  • For more information about creating a product and repository manually, see Importing Content.

13.2. Managing Container Name Patterns

When you use Foreman to create and manage your containers, as the container moves through Content View versions and different stages of the Foreman lifecycle environment, the container name changes at each stage. For example, if you synchronize a container image with the name ssh from an upstream repository, when you add it to a Foreman product and organization and then publish as part of a Content View, the container image can have the following name: my_organization_production-custom_spin-my_product-custom_ssh. This can create problems when you want to pull a container image because container registries can contain only one instance of a container name. To avoid problems with Foreman naming conventions, you can set a registry name pattern to override the default name to ensure that your container name is clear for future use.

Limitations

If you use a registry name pattern to manage container naming conventions, because registry naming patterns must generate globally unique names, you might experience naming conflict problems. For example:

  • If you set the repository.docker_upstream_name registry name pattern, you cannot publish or promote Content Views with container content with identical repository names to the Production lifecycle.

  • If you set the lifecycle_environment.name registry name pattern, this can prevent the creation of a second container repository with the identical name.

You must proceed with caution when defining registry naming patterns for your containers.

Procedure

To manage container naming with a registry name pattern, complete the following steps:

  1. In the Foreman web UI, navigate to Content > Lifecycle Environments, and either create a lifecycle environment or select a lifecycle environment to edit.

  2. In the Container Image Registry area, click the edit icon to the right of Registry Name Pattern area.

  3. Use the list of variables and examples to determine which registry name pattern you require.

  4. In the Registry Name Pattern field, enter the registry name pattern that you want to use. For example, to use the repository.docker_upstream_name:

    <%= repository.docker_upstream_name %>

  5. Click Save.

13.3. Managing Container Registry Authentication

You can manage the authentication settings for accessing containers images from Foreman. By default, users must authenticate to access containers images in Foreman.

You can specify whether you want users to authenticate to access container images in Foreman in a lifecycle environment. For example, you might want to permit users to access container images from the Production lifecycle without any authentication requirement and restrict access the Development and QA environments to authenticated users.

Procedure

  1. In the Foreman web UI, navigate to Content > Lifecycle Environments.

  2. Select the lifecycle environment that you want to manage authentication for.

  3. To permit unauthenticated access to the containers in this lifecycle environment, select the Unauthenticated Pull checkbox. To restrict unauthenticated access, clear the Unauthenticated Pull checkbox.

  4. Click Save.

13.4. Configuring Podman and Docker to trust the Certificate Authority

Podman uses two paths to locate the CA file, namely, /etc/containers/certs.d/ and /etc/docker/certs.d/.

Copy the root CA file to one of these locations, with the exact path determined by the server hostname, and naming the file ca.crt

In the following examples, replace hostname.example.com with foreman-server.example.com or smart-proxy-server.example.com, depending on your use case.

  • You might first need to create the relevant location using:

    # mkdir -p /etc/containers/certs.d/hostname.example.com

    or

    # mkdir -p /etc/docker/certs.d/hostname.example.com

  • For podman, use:

    # cp rootCA.pem /etc/containers/certs.d/hostname.example.com/ca.crt

  • Alternatively, if you are using Docker, copy the root CA file to the equivalent Docker directory:

    # cp rootCA.pem /etc/docker/certs.d/hostname.example.com/ca.crt

You no longer need to use the --tls-verify=false option when logging in to the registry:

$ podman login hostname.example.com

Username: admin
Password:
Login Succeeded!

13.5. Using Container Registries

Podman and Docker can be used to fetch content from container registries.

Container Registries on Smart Proxies

On Smart Proxies with content, the Container Gateway Smart Proxy plugin acts as the container registry. It caches authentication information from Katello and proxies incoming requests to Pulp. The Container Gateway is available by default on Smart Proxies with content.

Procedure

Logging in to the container registry:

# podman login foreman.example.com

Listing container images:

# podman search foreman.example.com/

Pulling container images:

# podman pull foreman.example.com/my-image:<optional_tag>

14. Managing ISO Images

You can use Foreman to store ISO images, either from Red Hat’s Content Delivery Network or other sources. You can also upload other files, such as virtual machine images, and publish them in repositories.

14.1. Importing ISO Images from Red Hat

The Red Hat Content Delivery Network provides ISO images for certain products. The procedure for importing this content is similar to the procedure for enabling repositories for RPM content.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Red Hat Repositories.

  2. In the Search field, enter an image name, for example, Red Hat Enterprise Linux 7 Server (ISOs).

  3. In the Available Repositories window, expand Red Hat Enterprise Linux 7 Server (ISOs).

  4. For the x86_64 7.2 entry, click the Enable icon to enable the repositories for the image.

  5. In the Foreman web UI, navigate to Content > Products and click Red Hat Enterprise Linux Server.

  6. Click the Repositories tab of the Red Hat Enterprise Linux Server window, and click Red Hat Enterprise Linux 7 Server ISOs x86_64 7.2.

  7. In the upper right of the Red Hat Enterprise Linux 7 Server ISOs x86_64 7.2 window, click Select Action and select Sync Now.

To view the Synchronization Status

  • In the Foreman web UI, navigate to Content > Sync Status and expand Red Hat Enterprise Linux Server.

CLI procedure

  1. Locate the Red Hat Enterprise Linux Server product for file repositories:

    # hammer repository-set list \
--product "Red Hat Enterprise Linux Server" \
--organization "My_Organization" | grep "file"

  2. Enable the file repository for Red Hat Enterprise Linux 7.2 Server ISO:

    # hammer repository-set enable \
--product "Red Hat Enterprise Linux Server" \
--name "Red Hat Enterprise Linux 7 Server (ISOs)" \
--releasever 7.2 \
--basearch x86_64 \
--organization "My_Organization"

  3. Locate the repository in the product:

    # hammer repository list \
--product "Red Hat Enterprise Linux Server" \
--organization "My_Organization"

  4. Synchronize the repository in the product:

    # hammer repository synchronize \
--name "Red Hat Enterprise Linux 7 Server ISOs x86_64 7.2" \
--product "Red Hat Enterprise Linux Server" \
--organization "My_Organization"

14.2. Importing Individual ISO Images and Files

Use this procedure to manually import ISO content and other files to Foreman server. To import files, you can complete the following steps in the Foreman web UI or using the Hammer CLI. However, if the size of the file that you want to upload is larger than 15 MB, you must use the Hammer CLI to upload it to a repository.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Products, and in the Products window, click Create Product.

  2. In the Name field, enter a name to identify the product. This name populates the Label field.

  3. Optional: In the GPG Key field, enter a GPG Key for the product.

  4. Optional: From the Sync Plan list, select a synchronization plan for the product.

  5. Optional: In the Description field, enter a description of the product.

  6. Click Save.

  7. In the Products window, click the new product and then click Create Repository.

  8. In the Name field, enter a name for the repository. This automatically populates the Label field.

  9. From the Type list, select file.

  10. In the Upstream URL field, enter the URL of the registry to use as a source. Add a corresponding user name and password in the Upstream Username and Upstream Password fields.

  11. Click Save.

  12. Select the new repository.

  13. Navigate to Upload File and click Browse.

  14. Select the .iso file and click Upload.

CLI procedure

  1. Create the product:

    # hammer product create \
--name "My_ISOs" \
--sync-plan "Example Plan" \
--description "My_Product" \
--organization "My_Organization"

  2. Create the repository:

    # hammer repository create \
--name "My_ISOs" \
--content-type "file" \
--product "My_Product" \
--organization "My_Organization"

  3. Upload the ISO file to the repository:

    # hammer repository upload-content \
--path ~/bootdisk.iso \
--id repo_ID \
--organization "My_Organization"

15. Managing File Type Content

In Foreman, you might require methods of managing and distributing SSH keys and source code files or larger files such as virtual machine images and ISO files. To achieve this, products in Foreman include repositories for file types. This provides a generic method to incorporate arbitrary files in a product.

You can upload files to the repository and synchronize files from an upstream Foreman server. When you add files to a file type repository, you can use the normal Foreman management functions such as adding a specific version to a Content View to provide version control and making the repository of files available on various Smart Proxy servers. Clients must download the files over HTTP or HTTPS using curl -O.

You can create a file type repository in Foreman server only in a product, but there is flexibility in how you create the file type repository. You can create an independent file type repository in a directory on the system where Foreman is installed, or on a remote HTTP server, and then synchronize the contents of that directory into Foreman. This method is useful when you have multiple files to add to a Foreman repository.

15.1. Creating a File Type Repository

The procedure for creating a file type repository is the same as the procedure for creating any content, except that when you create the repository, you select the file type. You must create a product and then add a repository.

To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

  1. In the Foreman web UI, navigate to Content > Products.

  2. Select a product that you want to create a repository for.

  3. On the Repositories tab, click New Repository.

  4. In the Name field, enter a name for the repository. Foreman automatically completes the Label field based on the name.

  5. Optional: In the Description field, enter a description for the repository.

  6. From the Type list, select file as type of repository.

  7. Optional: In the Upstream URL field, enter the URL of the upstream repository to use as a source.

  8. Select the Verify SSL checkbox if you want to verify that the upstream repository’s SSL certificates are signed by a trusted CA.

  9. Optional: In the Upstream Username field, enter the user name for the upstream repository if required for authentication. Clear this field if the repository does not require authentication.

  10. Optional: In the Upstream Password field, enter the corresponding password for the upstream repository. Clear this field if the repository does not require authentication.

  11. Optional: In the Upstream Authentication Token field, provide the token of the upstream repository user for authentication. Leave this field empty if the repository does not require authentication.

  12. From the Mirroring Policy list, select the type of content synchronization Foreman server performs. For more information, see Mirroring Policies Overview.

  13. Optional: In the HTTP Proxy Policy field, select or deselect using a HTTP proxy. By default, it uses the Global Default HTTP proxy.

  14. Optional: You can clear the Unprotected checkbox to require a subscription entitlement certificate for accessing this repository. By default, the repository is published through HTTP.

  15. Optional: In the SSL CA Cert field, select the SSL CA Certificate for the repository.

  16. Optional: In the SSL Client Cert field, select the SSL Client Certificate for the repository.

  17. Optional: In the SSL Client Key field, select the SSL Client Key for the repository.

  18. Click Save to create the repository.

CLI procedure

  1. Create a product:

    # hammer product create \
--description "My_Files" \
--name "My_File_Product" \
--organization "My_Organization" \
--sync-plan "My_Sync_Plan"
    Table 5. Optional Parameters for the hammer product create Command
    Option Description

    --gpg-key-id gpg_key_id

    GPG key numeric identifier

    --sync-plan sync_plan_name

    Sync plan name to search by

    --sync-plan-id sync_plan_id

    Sync plan numeric identifier

  2. Create a file type repository:

    # hammer repository create \
--content-type "file" \
--name "My_Files" \
--organization "My_Organization" \
--product "My_File_Product"
    Table 6. Optional Parameters for the hammer repository create Command
    Option Description

    --checksum-type sha_version

    Repository checksum, currently 'sha1' & 'sha256' are supported

    --download-policy policy_name

    Download policy for yum repos (either 'immediate' or 'on_demand').

    --gpg-key gpg_key_name

    Key name to search by

    --gpg-key-id gpg_key_id

    GPG key numeric identifier

    --mirror-on-sync boolean

    Must this repo be mirrored from the source, and stale RPMs removed, when synced? Set to true or false, yes or no, 1 or 0.

    --publish-via-http boolean

    Must this also be published using HTTP? Set to true or false, yes or no, 1 or 0.

    --upstream-username repository_username

    Upstream repository user, if required for authentication

    --upstream-password repository_password

    Password for the upstream repository user

    --url source_repo_url

    URL of the Source repository

    --verify-ssl-on-sync boolean

    Must Katello verify that the upstream URL’s SSL certificates are signed by a trusted CA? Set to true or false, yes or no, 1 or 0.

15.2. Creating a File Type Repository in a Local Directory

You can create a file type repository, from a directory of files, on the base system where Foreman is installed using the pulp-manifest command. You can then synchronize the files into Foreman server. When you add files to a file type repository, you can work with the files as with any other repository.

Use this procedure to configure a repository in a directory on the base system where Foreman is installed. To create a file type repository in a directory on a remote server, see Creating a Remote File Type Repository.

Procedure

To create a file type repository in a local directory, complete the following procedure:

  1. Install the Pulp Manifest package:

    # yum install python38-pulp_manifest

  2. Create a directory that you want to use as the file type repository in the HTTP server’s public folder, for example, /var/lib/pulp/sync_imports/new_repo

    # mkdir /var/lib/pulp/sync_imports/new_repo

  3. Add files to the directory or create a test file:

    # touch my_file_repo/test.txt

  4. Enter the Pulp Manifest command to create the manifest:

    # pulp-manifest my_file_repo

  5. Verify the manifest was created:

    # ls my_file_repo
PULP_MANIFEST test.txt

  6. Configure additional import paths to sync a file repository that exists on the Foreman. For example, if a file repository is at /path/to/myrepo, enter:

    # foreman-installer --foreman-proxy-content-pulpcore-additional-import-paths /path/to/myrepo
Importing Files from a File Type Repository

To import files from a file type repository in a local directory, complete the following procedure:

  1. Ensure a product exists in Foreman server.

  2. In the Foreman web UI, navigate to Content > Products.

  3. Select the name of a product.

  4. Click the Repositories tab and select New Repository.

  5. In the Name field, enter a name for the repository. Foreman automatically completes this field based on what you enter for Name.

  6. From the Type list, select the content type of the repository.

  7. In the Upstream URL field, enter the local directory with the repository to use as the source, in the form file:///my_file_repo.

  8. Select the Verify SSL checkbox to check the SSL certificate for the repository or clear the Verify SSL checkbox.

  9. Optional: In the Upstream Username field, enter the upstream user name that you require.

  10. Optional: In the Upstream Password field, enter the corresponding password for your upstream user name.

  11. Optional: In the Upstream Authentication Token field, provide the token of the upstream repository user for authentication. Leave this field empty if the repository does not require authentication.

  12. From the Mirroring Policy list, select the type of content synchronization Foreman server performs. For more information, see Mirroring Policies Overview.

  13. Optional: In the HTTP Proxy Policy field, select the desired HTTP proxy. The default value is Global Default.

  14. Optional: You can clear the Unprotected checkbox to require a subscription entitlement certificate for accessing this repository. By default, the repository is published through HTTP.

  15. Optional: In the GPG Key field, select the GPG key for the repository.

  16. Optional: In the SSL CA Cert field, select the SSL CA Certificate for the repository.

  17. Optional: In the SSL Client cert field, select the SSL Client Certificate for the repository.

  18. Optional: In the SSL Client Key field, select the SSL Client Key for the repository.

  19. Select Save to save this repository entry.

Updating a File Type Repository

To update the file type repository, complete the following steps:

  1. In the Foreman web UI, navigate to Content > Products.

  2. Select the name of a product.

  3. Select the name of the repository you want to update.

  4. From the Select Action menu, select Sync Now.

  5. Visit the URL where the repository is published to see the files.

15.3. Creating a Remote File Type Repository

You can create a file type repository from a directory of files that is external to Foreman server using the pulp-manifest command. You can then synchronize the files into Foreman server over HTTP or HTTPS. When you add files to a file type repository, you can work with the files as with any other repository.

Use this procedure to configure a repository in a directory on a remote server. To create a file type repository in a directory on the base system where Foreman server is installed, see Creating a File Type Repository in a Local Directory.

Prerequisites

Before you create a remote file type repository, ensure the following conditions exist:

  • You have a Red Hat Enterprise Linux 7 server registered to your Foreman or the Red Hat CDN.

  • You have installed an HTTP server. For more information about configuring a web server, see The Apache HTTP Server in the Red Hat Enterprise Linux 7 System Administrator’s Guide.

Procedure

To create a file type repository in a remote directory, complete the following procedure:

  1. Install the Pulp Manifest package:

    • For Enterprise Linux 8:

      # yum install python38-pulp_manifest

    • For Enterprise Linux 7:

      # yum install tfm-pulpcore-python3-pulp_manifest

  2. Create a directory that you want to use as the file type repository in the HTTP server’s public folder:

    # mkdir /var/www/html/pub/my_file_repo

  3. Add files to the directory or create a test file:

    # touch /var/www/html/pub/my_file_repo/test.txt

  4. Enter the Pulp Manifest command to create the manifest:

    # pulp-manifest /var/www/html/pub/my_file_repo

  5. Verify the manifest was created:

    # ls /var/www/html/pub/my_file_repo
PULP_MANIFEST test.txt
Importing Files from a Remote a File Type Repository

To import files from a remote file type repository, complete the following procedure:

  1. Ensure a product exists in Foreman server, or create a product. For more information see Creating a File Type Repository

  2. In the Foreman web UI, navigate to Content > Products.

  3. Select the name of a product.

  4. Click the Repositories tab and select New Repository.

  5. In the Name field, enter a name for the repository. Foreman automatically completes this field based on what you enter for Name.

  6. From the Type list, select file.

  7. In the Upstream URL field, enter the URL of the upstream repository to use as a source.

  8. Select the Verify SSL checkbox if you want to verify that the upstream repository’s SSL certificates are signed by a trusted CA.

  9. Optional: In the Upstream Username field, enter the user name for the upstream repository if required for authentication. Clear this field if the repository does not require authentication.

  10. Optional: In the Upstream Password field, enter the corresponding password for the upstream repository. Clear this field if the repository does not require authentication.

  11. Optional: In the Upstream Authentication Token field, provide the token of the upstream repository user for authentication. Leave this field empty if the repository does not require authentication.

  12. From the Mirroring Policy list, select the type of content synchronization Foreman server performs. For more information, see Mirroring Policies Overview.

  13. Optional: In the HTTP Proxy Policy field, select the desired HTTP proxy. The default value is Global Default.

  14. Optional: You can clear the Unprotected checkbox to require a subscription entitlement certificate for accessing this repository. By default, the repository is published through HTTP.

  15. Optional: In the GPG Key field, select the GPG key for the repository.

  16. Optional: In the SSL CA Cert field, select the SSL CA Certificate for the repository.

  17. Optional: In the SSL Client cert field, select the SSL Client Certificate for the repository.

  18. Optional: In the SSL Client Key field, select the SSL Client Key for the repository.

  19. Click Save.

  20. To update the file type repository, navigate to Content > Products. Select the name of a product that contains the repository that you want to update.

  21. In the product’s window, select the name of the repository you want to update.

  22. From the Select Action menu, select Sync Now.

Visit the URL where the repository is published to view the files.

15.4. Uploading Files To a File Type Repository

Use this procedure to upload files to a file type repository.

Procedure

  1. In the Foreman web UI, navigate to Content > Products.

  2. Select a product by name.

  3. Select a file type repository by name.

  4. Click Browse to search and select the file you want to upload.

  5. Click Upload to upload the selected file to Foreman server.

  6. Visit the URL where the repository is published to see the file.

CLI procedure
# hammer repository upload-content \
--id repo_ID \
--organization "My_Organization" \
--path example_file

The --path option can indicate a file, a directory of files, or a glob expression of files. Globs must be escaped by single or double quotes.

15.5. Downloading Files to a Host From a File Type Repository

You can download files to a client over HTTPS using curl -O, and optionally over HTTP if the Unprotected option for repositories is selected.

Prerequisites
Procedure

  1. In the Foreman web UI, navigate to Content > Products.

  2. Select a product by name.

  3. Select a file type repository by name.

  4. Ensure to select the Unprotected checkbox to access the repository published through HTTP.

  5. Copy the URL where the repository is published.

CLI procedure

  1. List the file type repositories.

    # hammer repository list --content-type file
---|------------|-------------------|--------------|----
ID | NAME       | PRODUCT           | CONTENT TYPE | URL
---|------------|-------------------|--------------|----
7  | My_Files   | My_File_Product   | file         |
---|------------|-------------------|--------------|----

  2. Display the repository information.

    # hammer repository info \
--name "My_Files" \
--organization-id My_Organization_ID \
--product "My_File_Product"

    If Unprotected is enabled, the output is similar to this:

    Publish Via HTTP:   yes
Published At:       https://foreman.example.com/pulp/content/My_Organization_Label/Library/custom/My_File_Product_Label/My_Files_Label/

    If Unprotected is not enabled, the output is similar to this:

    Publish Via HTTP:   no
Published At:       https://foreman.example.com/pulp/content/My_Organization_Label/Library/custom/My_File_Product_Label/My_Files_Label/

  3. On the client, enter a command in the appropriate format for HTTP or HTTPS:

    For HTTP:

    # curl -O http://foreman.example.com/pulp/content/My_Organization_Label/Library/custom/My_File_Product_Label/My_Files_Label/my_file

    For HTTPS:

    # curl -O --cert ./_My-Organization-key-cert.pem_ --cacert katello-server-ca.crt https://foreman.example.com/pulp/content/My_Organization_Label/Library/custom/My_File_Product_Label/My_Files_Label/my_file

Appendix A: Using an NFS Share for Content Storage

Your environment requires adequate hard disk space to fulfill content storage. In some situations, it is useful to use an NFS share to store this content. This appendix shows how to mount the NFS share on your Foreman server’s content management component.

Important
 Use high-bandwidth, low-latency storage for the /var/lib/pulp file system. Foreman has many I/O-intensive operations; therefore, high-latency, low-bandwidth storage might have issues with performance degradation.
Procedure

  1. Create the NFS share. This example uses a share at nfs.example.com:/Foreman/pulp. Ensure this share provides the appropriate permissions to Foreman server and its apache user.

  2. Stop Foreman services on your Foreman server:

    # foreman-maintain service stop

  3. Ensure Foreman server has the nfs-utils package installed:

    # yum install nfs-utils

  4. You need to copy the existing contents of /var/lib/pulp to the NFS share. First, mount the NFS share to a temporary location:

    # mkdir /mnt/temp
# mount -o rw nfs.example.com:/Foreman/pulp /mnt/temp

    Copy the existing contents of /var/lib/pulp to the temporary location:

    # cp -r /var/lib/pulp/* /mnt/temp/.

  5. Set the permissions for all files on the share to use the pulp user.

  6. Unmount the temporary storage location:

    # umount /mnt/temp

  7. Remove the existing contents of /var/lib/pulp:

    # rm -rf /var/lib/pulp/*

  8. Edit the /etc/fstab file and add the following line:

    nfs.example.com:/Foreman/pulp    /var/lib/pulp   nfs    rw,hard,intr,context="system_u:object_r:pulpcore_var_lib_t:s0"

    This makes the mount persistent across system reboots. Ensure to include the SELinux context.

  9. Enable the mount:

    # mount -a

  10. Confirm the NFS share mounts to var/lib/pulp:

    # df
Filesystem                         1K-blocks     Used Available Use% Mounted on
...
nfs.example.com:/Foreman/pulp 309506048 58632800 235128224  20% /var/lib/pulp
...

    Also confirm that the existing content exists at the mount on var/lib/pulp:

    # ls /var/lib/pulp

  11. Start Foreman services on your Foreman server:

    # foreman-maintain service start

Foreman server now uses the NFS share to store content. Run a content synchronization to ensure the NFS share works as expected. For more information, see Synchronizing Repositories.

Appendix B: Configuring Inter-Server Synchronization (ISS) in Foreman

B.1. How to Configure Inter-Server Synchronization

Foreman uses Inter-Server Synchronization (ISS) to synchronize content between two Foreman servers including those that are air-gapped.

You can use ISS in cases such as:

  • If you want to copy some but not all content from your Foreman server to other Foreman servers. For example, you have Content Views that your IT department consumes from Foreman server, and you want to copy content from those Content Views to other Foreman servers.

  • If you want to copy all Library content from your Foreman server to other Foreman servers. For example, you have Products and repositories that your IT department consumes from Foreman server in the Library, and you want to copy all Products and repositories in that organization to other Foreman servers.

Note

You cannot use ISS to synchronize content from Foreman server to Smart Proxy server. Smart Proxy server supports synchronization natively. For more information, see Smart Proxy server Overview in Planning for Foreman.

There are different ways of using ISS. The way you can use depends on your multi-server setup that can fall to one of the following scenarios.

B.1.1. ISS Network Sync in a Disconnected Scenario

In a disconnected scenario, there is the following setup:

  • The upstream Foreman server is connected to the Internet. This server consumes content from the Red Hat Content Delivery Network (CDN) or custom sources.

  • The downstream Foreman server is completely isolated from all external networks.

  • The downstream Foreman server can communicate with a connected upstream Foreman server over an internal network.

The Foreman ISS Disconnected Scenario
Figure 2. The Foreman ISS Disconnected Scenario

You can configure your downstream Foreman server to synchronize content from the upstream Foreman server over the network. See Configuring Foreman Server to Synchronize Content over a Network.

B.1.2. ISS Export Sync in an Air-Gapped Scenario

In an air-gapped scenario, there is the following setup:

  • The upstream Foreman server is connected to the Internet. This server consumes content from the Red Hat CDN or custom sources.

  • The downstream Foreman server is completely isolated from all external networks.

  • The downstream Foreman server does not have a network connection to a connected upstream Foreman server.

The Foreman ISS Air-Gapped Scenario
Figure 3. The Foreman ISS Air-Gapped Scenario

The only way for an air-gapped downstream Foreman server to receive content updates is by exporting payload from the upstream Foreman server, bringing it physically to the downstream Foreman server, and importing the payload. For more information, see Synchronizing Content Between Foreman servers in the Content Management Guide.

Configure your downstream Foreman server to synchronize content using exports. See Configuring Foreman Server to Synchronize Content Using Exports.

B.2. Configuring Foreman Server to Synchronize Content Using Exports

If you deployed your downstream Foreman server as air-gapped, configure your Foreman server as such to avoid attempts to consume content from a network.

Procedure

  1. In the Foreman web UI, navigate to Content > Subscriptions.

  2. Click the Manage Manifest button.

  3. Switch to the CDN Configuration tab.

  4. Select the Export Sync tab.

  5. Click Update.

CLI Procedure

  1. Log in to your Foreman server using SSH.

  2. Set CDN configuration to sync using exports:

    # hammer organization configure-cdn --name="My_Organization" --type=export_sync

B.3. Configuring Foreman Server to Synchronize Content over a Network

Configure a downstream Foreman server to synchronize repositories from a connected upstream Foreman server over HTTPS.

Prerequisites

  • A network connection exists between the upstream Foreman server and the downstream Foreman server.

  • You imported the subscription manifest on both the upstream and downstream Foreman server.

  • On the upstream Foreman server, you enabled the required repositories for the organization.

  • The upstream user is an admin or has the following permissions:

    • view_organizations

    • view_products

    • edit_organizations (to download the CA certificate)

    • view_lifecycle_environments

    • view_content_views

  • On the downstream Foreman server, you have imported the SSL certificate of the upstream Foreman server using the contents of http://upstream-foreman.example.com/pub/katello-server-ca.crt. For more information, see Importing SSL Certificates in the Content Management Guide.

  • The downstream user is an admin or has the permissions to create product repositories and organizations.

Procedure

  1. Navigate to Content > Subscriptions.

  2. Click the Manage Manifest button.

  3. Navigate to the CDN Configuration tab.

  4. Select the Network Sync tab.

  5. In the URL field, enter the address of the upstream Foreman server.

  6. In the Username, enter your username for upstream login.

  7. In the Password, enter your password or personal access token for upstream login.

  8. In the Organization label field, enter the label of the upstream organization.

  9. Optional: In the Lifecycle Environment Label field, enter the label of the upstream lifecycle environment. Default is Library.

  10. Optional: In the Content view label field, enter the label of the upstream Content View. Default is Default_Organization_View.

  11. From the SSL CA Content Credential menu, select a CA certificate used by the upstream Foreman server.

  12. Click Update.

  13. In the Foreman web UI, navigate to Content > Products.

  14. Click Sync Now to synchronize the repositories.

    You can also create a synchronization plan to ensure updates on a regular basis. For more information, see Creating a Synchronization Plan in the Content Management Guide.

CLI Procedure

  1. Connect to your downstream Foreman server using SSH.

  2. View information about the upstream CA certificate:

    # hammer content-credential show \
--name="My_Upstream_CA_Cert" \
--organization="My_Downstream_Organization"

    Note the ID of the CA certificate for the next step.

  3. Set CDN configuration to an upstream Foreman server:

    # hammer organization configure-cdn --name="My_Downstream_Organization" \
--type=network_sync \
--url https://upstream-foreman.example.com \
--username upstream_username --password upstream_password \
--ssl-ca-credential-id "My_Upstream_CA_Cert_ID" \
--upstream-organization-label="_My_Upstream_Organization" \
[--upstream-lifecycle-environment-label="My_Lifecycle_Environment"] \
[--upstream-content-view-label="My_Content_View"]

    The default lifecycle environment label is Library. The default Content View label is Default_Organization_View.