1. Synchronizing content to Foreman

Synchronize added repositories to download content into Foreman, then keep it current with ad hoc runs or recurring sync plans. Configure network access and HTTP proxies for restricted environments, and use advanced synchronization to troubleshoot issues.

1.1. Configuring network for content synchronization

Content synchronization requires outbound access to upstream URLs. Adjust SELinux, HTTP proxies, and per-product or per-repository HTTP proxy policies if your environment restricts or inspects that traffic.

1.1.1. Configuring SELinux to permit content synchronization on custom ports

Add a TCP port to the SELinux http_port_t type when upstream content servers use a port that Foreman cannot reach by default for synchronization.

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 server, verify the ports that are permitted by SELinux for content synchronization:

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

  2. Configure SELinux to permit a custom port for content synchronization, for example 10011:

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

1.1.2. Adding an HTTP proxy by using Foreman web UI

You can 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

  • If Foreman server uses an HTTP proxy to communicate with subscription.rhsm.redhat.com and cdn.redhat.com, then your HTTP proxy must not perform SSL inspection on these communications.

Procedure

  1. In the Foreman web UI, navigate to Infrastructure > HTTP Proxies.

  2. Select New HTTP Proxy.

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

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

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

  6. In the Cacert field, enter the SSL CA certificate if your HTTP proxy requires authentication.

  7. Optional: In the Test URL field, enter a URL, then click Test Connection to ensure that Foreman server can connect to the URL through your HTTP proxy.

  8. Optional: Select the Default content HTTP proxy option to set your HTTP proxy as default to synchronize content.

  9. Click the Locations tab and add a location.

  10. Click the Organization tab and add an organization.

  11. Click Submit.

Additional resources

1.1.3. Adding an HTTP proxy by using Hammer CLI

You can 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

  • If Foreman server uses an HTTP proxy to communicate with subscription.rhsm.redhat.com and cdn.redhat.com, then your HTTP proxy must not perform SSL inspection on these communications.

Procedure

  • Add your HTTP proxy to Foreman:

    $ hammer http-proxy create \
--name My_HTTP_Proxy \
--url http-proxy.example.com:8080

    Optional: To set the HTTP proxy as default for content synchronization, add the --content-default-http-proxy true option.

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

Additional resources

1.1.4. Changing the HTTP proxy policy for a product

For granular control over network traffic, you can set an HTTP proxy policy for each product. An HTTP proxy policy of a product 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 by using Foreman web UI.

Procedure

  1. In the Foreman web UI, navigate to Content > Products and select 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 by using Foreman web UI.

  4. Click Update.

1.1.5. Changing the HTTP proxy policy for a repository by using Foreman web UI

You can set an HTTP proxy policy to synchronize repositories to Foreman server. Use an HTTP proxy for repository synchronization if your network restricts access to the internet.

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 HTTP proxy setting.

    • No HTTP Proxy: Do not use an HTTP proxy, even if a global default HTTP 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.

  5. Click Save.

Additional resources

1.1.6. Changing the HTTP proxy policy for a repository by using Hammer CLI

You can set an HTTP proxy policy to synchronize repositories to Foreman server. Use an HTTP proxy for repository synchronization if your network restricts access to the internet.

Procedure

  • Specify the HTTP proxy policy you want to use:

    $ hammer repository update \
--http-proxy-policy My_HTTP_Proxy_Policy \
--id My_Repository_ID

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

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

    • global_default_http_proxy: Use the global default HTTP proxy setting.

    • use_selected_http_proxy: Specify an HTTP proxy using either --http-proxy My_HTTP_Proxy_Name or --http-proxy-id My_HTTP_Proxy_ID.

Additional resources

1.2. Synchronizing repositories ad hoc

You must synchronize repositories to download content into Foreman. Use ad hoc synchronization for the initial download or whenever you need to update repositories manually.

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:

Table 1. Estimated duration for first-time synchronization
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

Schedule product synchronization by creating a sync plan to ensure updates on a regular basis.

Additional resources

1.2.1. Synchronizing repositories by using Foreman web UI

Run an ad hoc synchronization for selected repositories to download the latest upstream content into Foreman.

Procedure

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

  2. Select the product that contains the repositories that you want to synchronize.

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

Verification

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

  2. Expand the corresponding product or repository tree.

  3. Verify that the synchronization is complete.

1.2.2. Synchronizing repositories by using Hammer CLI

Run an ad hoc synchronization for a product or individual repository to download the latest upstream content into Foreman.

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"

1.2.3. Synchronizing all repositories in an organization

Run an asynchronous Hammer CLI script to synchronize every repository in an organization when you need to refresh all content at once.

Procedure

  1. Log in to your Foreman server using SSH.

  2. Run the following Bash script:

    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

1.3. Scheduling product synchronization

Sync plans run repository synchronization on a schedule. Assign a sync plan to one or more products so updates are fetched automatically.

1.3.1. Best practices for sync plans

Apply sync plan scheduling and automation patterns that keep content current without overloading Foreman during large synchronizations.

  • Add sync plans to products and regularly synchronize content to keep the load on Foreman low during synchronization. Synchronize content rather more often than less often. For example, setup a sync plan to synchronize content every day rather than only once a month.

  • Automate the creation and update of sync plans by using a Hammer script or an Ansible Playbook.

  • Distribute synchronization tasks over several hours to reduce the task load by creating multiple sync plans with the Custom Cron option.

Example 1. Custom Cron expressions
Cron expression Explanation

0 22 * * 1-5

every day at 22:00 from Monday to Friday

30 3 * * 6,0

at 03:30 every Saturday and Sunday

30 2 8-14 * *

at 02:30 every day between the 8th and the 14th days of the month

1.3.2. Creating a sync plan by using Foreman web UI

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.

Procedure

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

  2. Click New Sync Plan.

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

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

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

  6. From the Start Date and Start Time lists, select when to start running the sync plan.

  7. Click Save.

1.3.3. Creating a sync plan by using Hammer CLI

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.

Procedure

  • Create a sync plan:

    $ hammer sync-plan create \
--description "My_Description" \
--enabled true \
--interval daily \
--name "My_Products" \
--organization "My_Organization" \
--sync-date "2023-01-01 01:00:00"
Verification

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

    $ hammer sync-plan list --organization "My_Organization"

1.3.4. Assigning a sync plan to a product by using Foreman web UI

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.

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.

1.3.5. Assigning a sync plan to a product by using Hammer CLI

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.

Procedure

  • Assign a sync plan to a product:

    $ hammer product set-sync-plan \
--name "My_Product_Name" \
--organization "My_Organization" \
--sync-plan "My_Sync_Plan_Name"

1.3.6. Assigning a sync plan to multiple products

Assign one sync plan to every product in an organization that has been synchronized at least once and has repositories by using a Hammer script.

Procedure

  1. Run the following Bash script:

    ORG="My_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

1.4. Refreshing content counts on Smart Proxy

Refresh content counts on your Smart Proxy that mirrors content so you can verify which content views and repositories are available to hosts.

Procedure

  1. In the Foreman web UI, navigate to Infrastructure > Smart Proxies, and select the Smart Proxy where you want to see the synchronized content.

  2. Select the Overview tab.

  3. Under Content Sync, toggle the Synchronize button to do an Optimized Sync or a Complete Sync to synchronize the Smart Proxy which refreshes the content counts.

  4. Select the Content tab.

  5. Choose an Environment to view content views available to those Smart Proxies by clicking >.

  6. Expand the content view by clicking > to view repositories available to the content view and the specific version for the environment.

  7. View the number of content counts under Packages specific to yum repositories.

  8. View the number of errata, package groups, files, container tags, container manifests, and Ansible collections under Additional content.

  9. Click the options icon in the column to the right next to the environment and click Refresh counts to refresh the content counts synchronized on the Smart Proxy under Packages.

1.5. Advanced synchronization options

Use advanced synchronization when standard synchronization leaves packages missing or corrupted on Foreman server.

Advanced synchronization has the following options:

Optimized Sync

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

Complete Sync

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

Verify Content Checksum

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

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

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

Additional resources

2. Managing alternate content sources

You can accelerate content synchronization for your Foreman server and Smart Proxy servers by creating alternate content sources. Use an alternate content source on your local filesystem or nearby network to download content faster while still receiving metadata from the upstream source.

An alternate content source (ACS) defines an alternate path to download content during synchronization. The content itself is downloaded from the ACS, while the metadata is downloaded from the Foreman server or the upstream URL, depending on the configuration. You can use ACS to accelerate synchronization if the content is located on the local filesystem or on a nearby network. You can set up ACS for Foreman server and Smart Proxy servers.

You must refresh the alternate content source after creation or after making any changes. A weekly cron job refreshes all alternate content sources. You can also refresh the alternate content sources manually by using the Foreman web UI or Hammer CLI. Alternate content sources associated with your Foreman server, or Smart Proxy servers attached to multiple organizations, affect all organizations.

There are the following types of alternate content sources:

Custom

Custom alternate content sources download the content from any upstream repository on the network or filesystem.

Simplified

Simplified alternate content sources copy the upstream repository information from your Foreman server for the selected products. Simplified alternate content sources are ideal for situations where the connection from your Smart Proxy server to the upstream repository is faster than to your Foreman server.

RHUI

RHUI alternate content sources download content from a Red Hat Update Infrastructure (RHUI) server. Foreman web UI provides examples to help you find the network paths and to import authentication credentials.

2.1. Creating a custom alternate content source by using Foreman web UI

You can create a custom alternate content source (ACS) to accelerate content synchronization by downloading from your local network or filesystem instead of remote upstream servers.

Prerequisites

  • If the repository requires SSL authentication, the SSL certificate and key must be imported into Foreman.

  • You have the base URL and subpaths of your alternate content source. For example, if your base URL is https://server.example.com and your subpaths are enterprise-linux-9/ and enterprise-linux-8/, then Foreman will search https://server.example.com/enterprise-linux-9/ and https://server.example.com/enterprise-linux-8/.

Procedure

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

  2. Click Add source.

  3. Set the Source type to Custom.

  4. Select the Content type from the drop-down list.

  5. In the Name field, enter a name for your custom ACS.

  6. Optional: In the Description field, provide a description for the ACS.

  7. Select Smart Proxies to which you want to synchronize content from your alternate content source.

  8. If you require synchronizing content through the HTTP proxy of your Smart Proxies, select Use HTTP proxies.

  9. In the Base URL field, enter the base URL of the alternate content source.

  10. In the Subpaths field, provide a comma-separated list of subpaths.

  11. If your alternate content source requires authentication, select the Manual authentication or Content credentials.

  12. If SSL verification is required, enable Verify SSL and select the SSL CA certificate.

  13. Click Add.

  14. Navigate to Content > Alternate Content Sources.

  15. Open the options menu next to the newly created alternate content source and click Refresh.

Verification

  1. In the Foreman web UI, navigate to Monitor > Foreman Tasks > Tasks.

  2. Search for Refresh Alternate Content Source.

  3. Verify that the task finished successfully.

2.2. Creating a custom alternate content source by using Hammer CLI

You can create a custom alternate content source (ACS) to accelerate content synchronization by downloading from your local network or filesystem instead of remote upstream servers.

Prerequisites

  • If the repository requires SSL authentication, the SSL certificate and key must be imported into Foreman.

  • You have the base URL and subpaths of your alternate content source. For example, if your base URL is https://server.example.com and your subpaths are enterprise-linux-9/ and enterprise-linux-8/, then Foreman will search https://server.example.com/enterprise-linux-9/ and https://server.example.com/enterprise-linux-8/.

Procedure

  1. Create a custom alternate content source:

    $ hammer alternate-content-source create \
--alternate-content-source-type custom \
--base-url "https://local-repo.example.com:port" \
--name "My_ACS_Name" \
--smart-proxy-ids My_Smart_Proxy_ID_1,My_Smart_Proxy_ID_2 \
--subpaths "My_Subpath_1/,_My_Subpath_2/," \
--verify-ssl _true

  2. Refresh your alternate content source:

    $ hammer alternate-content-source refresh --name "My_ACS_Name"
Verification

  • Verify that the task ran successfully:

    $ hammer task list --search "Refresh Alternate Content Source"

2.3. Creating a simplified alternate content source by using Foreman web UI

You can create a simplified alternate content source (ACS) when your Smart Proxy servers have faster connections to the upstream repository than to your Foreman server. This accelerates synchronization by downloading content directly from the upstream source.

Prerequisites

  • You have created the products that will use the alternate content source.

Procedure

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

  2. Click Add source.

  3. Set the Source type to Simplified.

  4. Select the Content type from the drop-down list.

  5. In the Name field, enter a name for your simplified ACS.

  6. Optional: In the Description field, provide a description for the ACS.

  7. Select Smart Proxies to which you want to synchronize content from your alternate content source.

  8. If you require synchronizing content through the HTTP proxy of your Smart Proxies, select Use HTTP proxies.

  9. Select the products that should use the alternate content source.

  10. Click Add.

  11. Navigate to Content > Alternate Content Sources.

  12. Open the options menu next to the newly created alternate content source and click Refresh.

Verification

  1. In the Foreman web UI, navigate to Monitor > Foreman Tasks > Tasks.

  2. Search for Refresh Alternate Content Source.

  3. Verify that the task finished successfully.

2.4. Creating a simplified alternate content source by using Hammer CLI

You can create a simplified alternate content source (ACS) when your Smart Proxy servers have faster connections to the upstream repository than to your Foreman server. This accelerates synchronization by downloading content directly from the upstream source.

Prerequisites

  • You have created the products that will use the alternate content source.

Procedure

  1. Create a simplified alternate content source:

    $ hammer alternate-content-source create \
--alternate-content-source-type simplified \
--content-type yum \
--name "My_ACS_Name" \
--product-ids My_Product_ID_1,My_Product_ID_2 \
--smart-proxy-ids My_Smart_Proxy_ID_1,My_Smart_Proxy_ID_2

    Use --content-type file if you want to create a simplified ACS for a product with file-type repositories.

  2. Refresh your alternate content source:

    $ hammer alternate-content-source refresh --name "My_ACS_Name"
Verification

  • Verify that the task ran successfully:

    $ hammer task list --search "Refresh Alternate Content Source"

2.5. Synchronizing Smart Proxy directly from Red Hat CDN by using Foreman web UI

You can configure your Smart Proxy servers to sync Red Hat content directly from the Red Hat CDN to reduce load on your Foreman server and accelerate content synchronization.

Prerequisites

  • The required Red Hat repositories are enabled in Foreman.

Procedure

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

  2. Click Add source.

  3. Set the Source type as Simplified.

  4. Set the Content type to Yum.

  5. In the Name field, enter a name for the alternate content source.

  6. Optional: In the Description field, provide a description for the alternate content source.

  7. Select Smart Proxies that you want to sync directly from Red Hat CDN.

  8. If you require synchronizing content through the HTTP proxy of your Smart Proxies, select Use HTTP proxies.

  9. Select the Red Hat products that should be synced to the Smart Proxy from Red Hat CDN.

  10. Review details and click Add.

  11. Navigate to Content > Alternate Content Sources, click the options icon next to the newly created alternate content source, and select Refresh.

2.6. Creating an RHUI alternate content source by using Foreman web UI

You can create an RHUI alternate content source (ACS) to synchronize content from your Red Hat Update Infrastructure (RHUI) server. Leverage your existing RHUI investment and accelerate content synchronization.

Foreman searches content paths that combine a base URL with subpaths. For example, if your base URL is https://server.example.com and your subpaths are rhel10/ and rhel9/, then Foreman searches https://server.example.com/rhel10/ and https://server.example.com/rhel9/.

Prerequisites
Procedure

  1. On your RHUA server, display details for the required repositories:

    # rhui-manager repo info --repo_id My_Repo_ID

    Record the relative paths from the command output to use as subpaths.

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

  3. Click Add source.

  4. Set the Source type to RHUI.

  5. Generate RHUI certificates using the command provided in the Foreman web UI. Ensure that you pass the repo labels of the desired repositories.

  6. In the Name field, enter a name for your RHUI ACS.

  7. Optional: In the Description field, provide a description for the ACS.

  8. Select Smart Proxies to which you want to synchronize content from your alternate content source.

  9. If you require synchronizing content through the HTTP proxy of your Smart Proxies, select Use HTTP proxies.

  10. In the Base URL field, enter the base URL of the Red Hat Update Infrastructure CDS node.

  11. In the Subpaths field, provide a comma-separated list of subpaths.

  12. If your alternate content source requires authentication, provide the SSL client certificate and SSL client key.

  13. If SSL verification is required, enable Verify SSL and select the SSL CA certificate.

  14. Click Add.

  15. Navigate to Content > Alternate Content Sources.

  16. Open the options menu next to the newly created alternate content source and click Refresh.

2.7. Creating an RHUI alternate content source by using Hammer CLI

You can create an RHUI alternate content source (ACS) to synchronize content from your Red Hat Update Infrastructure (RHUI) server. Leverage your existing RHUI investment and accelerate content synchronization.

Foreman searches content paths that combine a base URL with subpaths. For example, if your base URL is https://server.example.com and your subpaths are rhel10/ and rhel9/, then Foreman searches https://server.example.com/rhel10/ and https://server.example.com/rhel9/.

Prerequisites
Procedure

  1. On your RHUA server, display details for the required repositories:

    # rhui-manager repo info --repo_id My_Repo_ID

    Record the relative paths from the command output to use as subpaths.

  2. Create a RHUI alternate content source:

    $ hammer alternate-content-source create \
--alternate-content-source-type rhui \
--base-url "https://rhui-cds-node.example.com/pulp/content" \
--name "My_ACS_Name" \
--smart-proxy-ids My_Smart_Proxy_ID_1,My_Smart_Proxy_ID_2 \
--ssl-client-cert-id My_SSL_Client_Certificate_ID \
--ssl-client-key-id My_SSL_Client_Key_ID \
--subpaths path/to/repo/1/,path/to/repo/2/ \
--verify-ssl true

  3. Refresh the alternate content source:

    $ hammer alternate-content-source refresh --name "My_ACS_Name"
Verification

  • Verify that the task ran successfully:

    $ hammer task list --search "Refresh Alternate Content Source"

2.8. Permissions required to manage alternate content sources

User accounts must have a role that grants the following permissions to view and manage alternate content sources in Foreman.

Permissions to view ACS

  • view_content_credentials

  • view_organizations

  • view_products

  • view_smart_proxies

Permissions to manage ACS

  • create_alternate_content_sources

  • destroy_alternate_content_sources

  • edit_alternate_content_sources

  • view_alternate_content_sources

3. Optimizing content synchronization and storage

Use download and mirroring policies, sync concurrency limits, and package retention to balance local storage, bandwidth, and upstream alignment on Foreman server and Smart Proxy servers. Configure defaults for new repositories or adjust individual repositories as needed.

3.1. Download policies overview

Download policies control when Foreman stores Deb, Yum, and container image content during synchronization versus fetching it on request from Smart Proxies or hosts.

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 lifecycle 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.

Streamed

Streamed download policy for Smart Proxies permits Smart Proxies to avoid caching any content. When content is requested from the Smart Proxy, it functions as a proxy and requests the content directly from the Foreman.

You can configure the global default download policies in Content settings.

3.2. Updating the default download policy by using Foreman web UI

Set the default download policy so new repositories inherit immediate or on-demand behavior without updating existing repositories.

Depending on whether it is a Red Hat, SUSE, or repository, Foreman uses separate settings. Changing the default value does not change the setting in existing repositories, but only the default setting for new repositories.

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.

3.3. Updating the default download policy by using Hammer CLI

Set the default download policy so new repositories inherit immediate or on-demand behavior without updating existing repositories.

Depending on whether it is a Red Hat, SUSE, or repository, Foreman uses separate settings. Changing the default value does not change the setting in existing repositories, but only the default setting for new repositories.

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

3.4. Updating the download policy for a repository by using Foreman web UI

Change the download policy for an existing repository when you need immediate full downloads or on-demand storage.

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.

3.5. Updating the download policy for a repository by using Hammer CLI

Update the download policy for a specific repository when you need immediate full downloads or on-demand lazy synchronization for that repository.

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"

3.6. Mirroring policies overview

Mirroring policies control whether synchronized repositories add only new content, mirror repodata, or fully mirror upstream changes including deletions. Use them to match upstream behavior and storage needs for each 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.

Warning

Avoid republishing metadata for repositories with Complete Mirror mirroring policy. This also applies to content views containing repositories with the Complete Mirror mirroring policy.

3.7. Updating the default mirroring policy by using Foreman web UI

Set default mirroring policies for new repositories so they inherit additive, content-only, or complete mirroring without affecting existing repositories.

Depending on whether it is a Yum or non-Yum repository, Foreman uses separate settings. Only Yum repositories support the mirror_complete mirroring policy. Red Hat repositories use the mirror_complete policy by default and are not affected by these settings. Changing the default value does not change existing mirroring policy settings per repository. For more information on mirroring policies, see Mirroring policies overview.

Procedure

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

  2. Click the Content tab.

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

    • To change the default mirroring policy for a Yum repository, change the value of the Default custom yum repository mirroring policy setting.

    • To change the default mirroring policy for a non-Yum repository, change the value of the Default custom non-yum repository mirroring policy setting.

3.8. Updating the default mirroring policy by using Hammer CLI

Set default mirroring policies for new repositories so they inherit additive, content-only, or complete mirroring without affecting existing repositories.

Depending on whether it is a Yum or non-Yum repository, Foreman uses separate settings. Only Yum repositories support the mirror_complete mirroring policy. Red Hat repositories use the mirror_complete policy by default and are not affected by these settings. Changing the default value does not change existing mirroring policy settings per repository. For more information on mirroring policies, see Mirroring policies overview.

Procedure

  • Change the default mirroring policy for a Yum repository to additive, mirror_content_only, or mirror_complete:

    $ hammer settings set \
--name default_yum_mirroring_policy \
--value mirror_complete

  • Change the default mirroring policy for a non-Yum repository to additive or mirror_content_only:

    $ hammer settings set \
--name default_non_yum_mirroring_policy \
--value additive

3.9. Updating the mirroring policy for a repository by using Foreman web UI

Update the mirroring policy for an existing repository to control whether synchronization adds content only, mirrors repodata, or removes content deleted upstream.

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.

3.10. Updating the mirroring policy for a repository by using Hammer CLI

Update the mirroring policy for a specific repository to control whether synchronization adds content only, mirrors repodata, or removes content deleted upstream.

Procedure

  1. List the repositories for an organization:

    $ hammer repository list \
--organization-label My_Organization_Label

  2. Change the mirroring policy for a repository to additive, mirror_complete, or mirror_content_only:

    $ hammer repository update \
--id My_Repository_ID \
--mirroring-policy mirror_complete

3.11. Limiting synchronization concurrency

Adjust per-repository download concurrency when sync jobs fail because upstream servers reject parallel requests, or raise the limit cautiously to improve sync performance.

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.

Procedure

  • Define a value for synchronization concurrency:

    $ hammer repository update \
--download-concurrency 5 \
--id Repository_ID \
--organization "My_Organization"

3.12. Limiting growth of synchronized content by using Foreman web UI

Limit how many package versions Foreman keeps in the Library by setting an additive mirroring policy and a retain count, reducing disk growth from repeated synchronizations.

Procedure

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

  2. Select your product.

  3. On the Repository tab, select your repository.

  4. Set the Mirroring Policy to Additive.

  5. Define the number of retained package versions:

    • Set Retain package versions to 1 to only keep the latest synchronized package version on Foreman.

    • Set Retain package versions to 2 or higher to keep multiple package versions on Foreman.

Additional resources

3.13. Limiting growth of synchronized content by using Hammer CLI

Limit how many package versions Foreman keeps in the Library by setting an additive mirroring policy and a retain count, reducing disk growth from repeated synchronizations.

Procedure

  • Configure your repository to retain a limited number of package versions in Foreman:

    $ hammer repository update \
--id My_Repository_ID \
--mirroring-policy additive \
--retain-package-versions-count My_Package_Versions_Count

    • Set My_Package_Versions_Count to 1 to only keep the latest synchronized package version on Foreman.

    • Set My_Package_Versions_Count to 2 or higher to keep multiple package versions on Foreman.

Additional resources

4. Recovering corrupted content

Resynchronize corrupted repositories on Foreman server, verify checksums on Smart Proxy servers, and republish repository or content view metadata when the repository metadata no longer matches stored content.

Additional resources

4.1. Recovering a corrupted repository by using Foreman web UI

Recover a corrupted repository with optimized or complete advanced sync, and optionally verify content checksums to confirm packages match upstream sources.

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 for a Yum repository, click Verify Content Checksum from the Select Action menu.

Additional resources

4.2. Recovering a corrupted repository by using Hammer CLI

Recover a corrupted repository by using optimized sync, complete sync, or validate-content synchronization when packages or metadata no longer match expected content.

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 validating content of a Yum repository:

      $ hammer repository synchronize \
--id My_ID \
--validate-contents true
Additional resources

4.3. Recovering corrupted content on a Smart Proxy server by using Foreman web UI

Verify checksums for a lifecycle environment or content view on your Smart Proxy server when hosts cannot consume content and you need to repair corrupted files on the Smart Proxy server.

Procedure

  1. In the Foreman web UI, navigate to Infrastructure > Smart Proxies.

  2. Select your Smart Proxy server.

  3. Recover corrupted content on your Smart Proxy server.

    • To repair content in a lifecycle environment, click the options menu icon next to your lifecycle environment and select Verify Content Checksum.

    • To repair content in a content view, click the options menu icon next to your content view and select Verify Content Checksum.

Verification

  1. In the Foreman web UI, navigate to Monitor > Foreman Tasks > Tasks.

  2. Search for Verify checksum for content.

  3. Verify that the task completed successfully.

4.4. Recovering corrupted content on a Smart Proxy server by using CLI

Verify checksums on your Smart Proxy server for a repository, content view, lifecycle environment, or all Smart Proxy server content when hosts cannot consume synchronized packages.

Prerequisites

  • The lifecycle environment, content view, or repository that you want to repair is available on the Smart Proxy server.

Procedure

  1. Display a list of all Smart Proxies:

    $ hammer proxy list

    Note the ID of your Smart Proxy server.

  2. Recover corrupted content on your Smart Proxy server:

    • Repair content in a content view:

      $ hammer proxy content verify-checksum \
--content-view-id My_Content_View_ID \
--id My_Smart_Proxy_Server_ID \
--organization-id My_Organization_ID

    • Repair content in a lifecycle environment:

      $ hammer proxy content verify-checksum \
--id My_Smart_Proxy_Server_ID \
--lifecycle-environment-id My_Lifecycle_Environment_ID \
--organization-id My_Organization_ID

    • Repair content in a repository:

      $ hammer proxy content verify-checksum \
--id My_Smart_Proxy_Server_ID \
--organization-id My_Organization_ID \
--repository-id My_Repository_ID

    • Repair all content on your Smart Proxy server:

      $ hammer proxy content verify-checksum \
--id My_Smart_Proxy_Server_ID
Verification

  • Verify that the task completed successfully:

    $ hammer task list --search "Verify checksum for content"

4.5. Republishing repository metadata by using Foreman web UI

Republish repository metadata when published metadata does not match repository contents.

Warning

Foreman community recommends a complete repository sync or publishing a new content view version to repair broken metadata instead.
Prerequisites

  • The mirroring policy of the repository is not set to Complete Mirroring.

    This action is not available for repositories that use the Complete Mirroring policy because the metadata is copied verbatim from the upstream source of the repository.

Procedure

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

  2. Select the product that includes the repository for which you want to republish metadata.

  3. On the Repositories tab, select a repository.

  4. To republish metadata for the repository, click Republish Repository Metadata from the Select Action menu.

4.6. Republishing repository metadata by using CLI

Republish repository metadata when published metadata does not match repository contents.

Warning

Foreman community recommends a complete repository sync or publishing a new content view version to repair broken metadata in favor of republishing repository metadata.
Prerequisites

  • The mirroring policy of the repository is not set to Complete Mirroring.

    This action is not available for repositories that use the Complete Mirroring policy because the metadata is copied verbatim from the upstream source of the repository.

Procedure

  • Republish metadata for your repository:

    $ hammer repository verify-checksum \
--name "My_Repository_Name" \
--organization-id My_Organization_ID \
--product "My_Product_Name"
Verification

  • Verify that the task completed successfully:

    $ hammer task list --search "Metadata generate repository"

4.7. Republishing content view metadata by using Foreman web UI

Republish content view version metadata when hosts report checksum mismatches. Foreman can regenerate metadata for repositories that do not use complete mirroring.

Republishing regenerates metadata for all repositories in the content view version that do not adhere to the Complete Mirroring policy.

Prerequisites

  • The content view version includes repositories that do not use the Complete Mirroring policy.

Procedure

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

  2. Select a content view.

  3. On the Versions tab, select a content view version.

  4. To republish metadata for the content view version, click Republish repository metadata from the options icon.

4.8. Republishing content view metadata by using CLI

Republish content view version metadata when hosts report checksum mismatches. Foreman can regenerate metadata for repositories that do not use complete mirroring.

Republishing regenerates metadata for all repositories in the content view version that do not adhere to the Complete Mirroring policy.

Prerequisites

  • The content view version includes repositories that do not use the Complete Mirroring policy.

Procedure

  • Republish metadata for your content view version:

    $ hammer content-view version verify-checksum --id My_Content_View_Version_ID
Verification

  • Verify that the task completed successfully:

    $ hammer task list --search "Verify checksum of repositories in"

5. Synchronizing content between Foreman servers

In multi-server Foreman deployments, use Inter-Server Synchronization to deliver content from upstream to downstream Foreman servers over a network or through export and import, including the Library environment, content view versions, and individual repositories.

5.1. Inter-Server Synchronization configurations

Depending on network connectivity between upstream and downstream Foreman servers, you can synchronize content over HTTPS with network sync or by exporting and importing content when servers are air gapped.

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.

ISS Export Sync

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

Configure your Foreman to synchronize content by using export and import.

Additional resources

5.1.1. Configuring Foreman server to synchronize content over a network by using Foreman web UI

To synchronize content over a network, configure your downstream Foreman server to pull repositories from a connected upstream Foreman server.

Prerequisites

  • A network connection exists between the upstream Foreman server and the downstream Foreman server.

  • You imported the same 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

    • export_content

    • 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.

  • The downstream user is an admin or has the permissions to create product repositories and organizations.

Procedure

  1. Navigate to Content > Subscriptions.

  2. Click Manage Manifest.

  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. Select the product that contains the repositories that you want to synchronize.

  15. From the Select Action menu, select Sync Now to synchronize all repositories within the product.

    You can also create a synchronization plan to ensure updates on a regular basis.

Additional resources

5.1.2. Configuring Foreman server to synchronize content over a network by using Hammer CLI

To synchronize content over a network, configure your downstream Foreman server to pull repositories from a connected upstream Foreman server.

Prerequisites

  • A network connection exists between the upstream Foreman server and the downstream Foreman server.

  • You imported the same 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

    • export_content

    • 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.

  • The downstream user is an admin or has the permissions to create product repositories and organizations.

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.

Additional resources

5.1.3. Configuring Foreman server to synchronize content through exports by using Foreman web UI

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 Manage Manifest.

  3. Switch to the CDN Configuration tab.

  4. Select the Export Sync tab.

  5. Click Update.

5.1.4. Configuring Foreman server to synchronize content through exports by using Hammer CLI

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. Log in to your Foreman server by using SSH.

  2. Set CDN configuration to sync by using exports:

    $ hammer organization configure-cdn \
--name="My_Organization" \
--type=export_sync

5.2. Synchronizing a repository

To synchronize repositories over a network, configure the repositories on the downstream Foreman server to synchronize from published URLs on the upstream server. Red Hat repositories do not require this configuration.

Procedure

  1. On the connected Foreman server, perform the following steps:

    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.

  2. On the disconnected Foreman server, perform the following steps:

    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.

    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.

5.3. Content synchronization by using export and import

Export content from an upstream Foreman server and import it into a downstream server when network connectivity is limited or air gapped. Choose an approach based on what content you need to synchronize.

Note

Synchronizing content by using export and import requires the same major version of Foreman on both the downstream and upstream Foreman servers.

When you are unable to match upstream and downstream Foreman versions, you can use:

  • Syncable exports and imports.

  • Inter-Server Synchronization (ISS) with your upstream Foreman connected to the internet and your downstream Foreman connected to the upstream Foreman.

5.3.1. Using an upstream Foreman server as a content store

Export Library content from an upstream Foreman server that serves as a content store and import it on the downstream server that manages content for isolated infrastructure.

Procedure

  1. On the upstream Foreman server, perform the following steps:

    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.

    2. Enable the content that you want to synchronize.

      If you want to sync custom content, first create a product and then synchronize 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.

      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.

  2. On the downstream Foreman server, perform the following steps:

    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.

      You can then manage content using content views or lifecycle environments as you require.

Additional resources

5.3.2. Using an upstream Foreman server to synchronize content view versions

Curate updates on the upstream Foreman server into content views and lifecycle environments, then export promoted content and import it on the downstream server that manages isolated infrastructure.

Procedure

  1. On the upstream Foreman server, perform the following steps:

    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.

      3. Ensure that the Default download policy is set to Immediate for custom repositories.

    2. Enable the content that you want to synchronize.

      If you want to sync custom content, first create a product and then synchronize 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. 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.

      3. When you have new content, republish the content views that include this content before exporting the increment. This creates a new content view version with the appropriate content to export.

  2. On the downstream Foreman server, perform the following steps:

    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. This will create a content view version from the exported content archives and then import content appropriately.

Additional resources

5.3.3. Synchronizing a single repository

Export a single repository from the upstream Foreman server and import it on the downstream server when you need to synchronize only specific content between air-gapped servers.

Procedure

  1. On the upstream Foreman server, perform the following steps:

    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.

    2. Enable the content that you want to synchronize.

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

    3. Synchronize the enabled content:

    4. 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.

    5. Export all future updates on the upstream Foreman server incrementally. This generates leaner content archives that contain only a recent set of updates.

  2. On the downstream Foreman server, perform the following steps:

    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.

      You can then manage content using content views or lifecycle environments as you require.

Additional resources

5.4. Exporting content from Foreman server

When synchronizing content by using export and import, export the Library environment, content view versions, or individual repositories from the upstream Foreman server.

5.4.1. Exporting the Library environment

You can export all Library content for an organization to an archive file and recreate the same repositories on another Foreman server or 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.

You can export the following content from Foreman server:

  • Ansible collections

  • Deb content

  • Docker content

  • Custom file type content

  • Kickstart repositories

  • Yum content

Prerequisites

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

  • 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.

  • Download policy is set to Immediate for all repositories within the Library lifecycle environment you export. For more information, see Download policies overview.

  • Products that you export are synchronized to the required date.

  • The user exporting the content has the Content Exporter role.

Procedure

  1. Export the Library environment for your organization:

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

    In many cases the exported archive might be several gigabytes in size. You might want to split it into chunks of a smaller size. You can use the --chunk-size-gb option to split the export into smaller chunks, for example --chunk-size-gb=2 to split the archive into 2 GB chunks.

  2. 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.

Verification

  • 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/

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

5.4.2. Exporting the Library environment in the syncable format

You can export content in the Library environment of an organization to a syncable format that you can use to create your custom CDN and synchronize the content from the custom CDN over HTTP/HTTPS.

You can use the generated content to create the same repository in another Foreman server or in another Foreman server organization by using content import. On import of the exported archive, a regular content view is created or updated on your importing Foreman server. For more information, see Importing a content view version.

You can export the following content types in the syncable format from Foreman server:

  • Custom file type content

  • Kickstart repositories

  • Yum content

You cannot export Ansible collections, Deb content, or Docker content in the syncable format.

The export contains directories with the packages, listing files, and metadata of the repository in Yum format that can be used to synchronize in the importing Foreman server.

Prerequisites

  • Exports are written to one of your allowed export paths. The default export path is /var/lib/pulp/exports/. To configure additional paths, run foremanctl deploy with one or more --content-export-path options.

  • Download policy is set to Immediate for all repositories within the Library lifecycle environment you export. For more information, see Download policies overview.

  • Products that you export are synchronized to the required date.

  • The user exporting the content has the Content Exporter role.

Procedure

  1. Use the organization name or ID to export:

    $ hammer content-export complete library \
--organization="My_Organization" \
--format=syncable

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

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

5.4.3. Exporting the Library environment incrementally

You can export only Library content that changed since the last export to reduce archive size and system resource usage when full Library exports are too large.

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

In such cases, you can create an incremental export which contains only pieces of content that have changed since the last export. Incremental exports typically result in smaller archive files than the full exports.

You can export the following content from Foreman server:

  • Ansible collections

  • Deb content

  • Docker content

  • Custom file type content

  • Kickstart repositories

  • Yum content

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"

    If you want to create a syncable export, add --format=syncable. By default, Foreman creates an importable export.

Next steps

  • Optional: View the exported data:

    # find /var/lib/pulp/exports/My_Organization/Export-Library/

5.4.4. Exporting a content view version

You can export a content view version to an archive file and recreate the same version on another Foreman server. Foreman exports composite content views as regular 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

You can export the following content from Foreman server:

  • Ansible collections

  • Deb content

  • Docker content

  • Custom file type content

  • Kickstart repositories

  • Yum content

Foreman does not export content view definitions and metadata such as package filters.

Prerequisites

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

  • 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.

  • Download policy is set to Immediate for all repositories within the content view version you export. For more information, see Download policies overview.

  • Products that you export are synchronized to the required date.

  • The user exporting the content has the Content Exporter role.

Procedure

  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"

    Note the version number that you want to export. In the following example, the version number is 1.0.

  2. Export the content view version:

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

    In many cases, the exported archive might be several gigabytes in size. You might want to split it into smaller chunks of a smaller size. You can use the --chunk-size-gb option to export the content view version into smaller chunks, for example --chunk-size-gb=2 to split the archives into 2 GB chunks.

Verification

  1. 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, the tar.gz archive file, the toc.json file, and the metadata.json file, to import the content successfully.

5.4.5. Exporting a content view version in the syncable format

You can export a content view version in syncable format to serve from a custom CDN over HTTP/HTTPS or import on a matching Foreman version.

After you have exported the content view, you can do either of the following:

  • Synchronize the content from your custom CDN over HTTP/HTTPS.

  • Import the content using hammer content-import. Note that this requires both the Export and Import servers to run Foreman nightly.

You can use the generated content to create the same repository in another Foreman server or in another Foreman server organization using content import. On importing the exported archive, a regular content view is created or updated on your downstream Foreman server. For more information, see Importing a content view version.

The export contains directories with the packages, listing files, and metadata of the repository in Yum format that can be used to synchronize in the importing Foreman server.

You can export the following content types in the syncable format from Foreman server:

  • Custom file type content

  • Kickstart repositories

  • Yum content

You cannot export Ansible collections, Deb content, or Docker content in the syncable format.

Prerequisites

  • Exports are written to one of your allowed export paths. The default export path is /var/lib/pulp/exports/. To configure additional paths, run foremanctl deploy with one or more --content-export-path options.

  • Download policy is set to Immediate for all repositories within the content view you export. For more information, see Download policies overview.

  • Products that you export are synchronized to the required date.

  • The user exporting the content has the Content Exporter role.

Procedure

  1. List versions of the content view that are available for export:

    $ hammer content-view version list \
--content-view="My_Content_View_Name" \
--organization="My_Organization"

    Note the version number that you want to export. In the following example, the version number is 1.0.

  2. Export the content view version in a syncable format:

    $ hammer content-export complete version \
--content-view="My_Content_View_Name" \
--version=1.0 \
--organization="My_Organization" \
--format=syncable
Verification

  • Verify that the exported content is located in the export directory:

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

5.4.6. Exporting a content view version incrementally

You can export only the content that changed in a content view version since the last export to reduce archive size when full exports are too resource-intensive.

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

In such cases, you can create an incremental export which contains only pieces of content that have changed since the last export. Incremental exports typically result in smaller archive files than the full exports.

You can export the following content from Foreman server:

  • Ansible collections

  • Deb content

  • Docker content

  • Custom file type content

  • Kickstart repositories

  • Yum content

Procedure

  1. Create an incremental export:

    $ hammer content-export incremental version \
--content-view="My_Content_View" \
--organization="My_Organization" \
--version="My_Content_View_Version"

    If you want to create a syncable export, add --format=syncable. By default, Foreman creates an importable export.

Next steps

  • Optional: View the exported content view:

    # find /var/lib/pulp/exports/My_Organization/My_Exported_Content_View/My_Content_View_Version/

  • You can import your exported content view version into Foreman server. For more information, see Importing a content view version.

5.4.7. Exporting a repository

You can export a repository from the Library environment to an archive file and recreate the same repository on another Foreman server or organization.

You can export the following content from Foreman server:

  • Ansible collections

  • Deb content

  • Docker content

  • Custom file type content

  • Kickstart repositories

  • Yum content

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

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

  • The /var/lib/pulp/exports/ directory has enough free storage space equivalent to the size of the repository that you export.

  • Download policy is set to Immediate for the repository you export. For more information, see Download policies overview.

  • Products that you export are synchronized to the required date.

  • The user exporting the content has the Content Exporter role.

Procedure

  1. Export a repository:

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

    The size of the exported archive depends on the number and size of the packages within the repository. If you want to split the exported archive into chunks, export your repository using the --chunk-size-gb argument to limit the size by an integer value in gigabytes, for example --chunk-size-gb=2.

  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/2022-09-02T03-35-24-00-00/

5.4.8. Exporting a repository in the syncable format

You can export the content of a repository in the Library environment of an organization to a syncable format that you can use to create your custom CDN and synchronize the content from the custom CDN over HTTP/HTTPS.

You can use the generated content to create the same repository in another Foreman server or in another Foreman server organization using content import. On importing the exported archive, a regular content view is created or updated on your downstream Foreman server. For more information, see Importing a content view version.

The export contains directories with the packages, listing files, and metadata of the repository in Yum format that can be used to synchronize in the importing Foreman server.

You can export the following content types in the syncable format from Foreman server:

  • Custom file type content

  • Kickstart repositories

  • Yum content

You cannot export Ansible collections, Deb content, or Docker content in the syncable format.

Prerequisites

  • Exports are written to one of your allowed export paths. The default export path is /var/lib/pulp/exports/. To configure additional paths, run foremanctl deploy with one or more --content-export-path options.

  • Download policy is set to Immediate for the repository you export. For more information, see Download policies overview.

  • The user exporting the content has the Content Exporter role.

Procedure

  1. Export a repository using the repository name or ID:

    $ hammer content-export complete repository \
--organization="My_Organization" \
--product="My_Product" \
--name="My_Repository" \
--format=syncable

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

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

5.4.9. Exporting a repository incrementally

You can export only repository content that changed since the previous export to reduce archive size when full repository exports are too large.

Exporting a repository can be a very expensive operation in terms of system resources. A typical 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.

You can export the following content from Foreman server:

  • Ansible collections

  • Deb content

  • Docker content

  • Custom file type content

  • Kickstart repositories

  • Yum content

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 \
--name="My_Repository" \
--organization="My_Organization" \
--product="My_Product"

  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

5.4.10. Exporting a repository incrementally in the syncable format

You can export only changed repository content in the syncable format to reduce transfer size when serving content from a custom CDN over HTTP/HTTPS.

Exporting a repository can be a very expensive operation in terms of system resources. A typical 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 full exports.

You can export the following content types in the syncable format from Foreman server:

  • Custom file type content

  • Kickstart repositories

  • Yum content

You cannot export Ansible collections, Deb content, or Docker content in the syncable format.

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

Prerequisites

  • Exports are written to one of your allowed export paths. The default export path is /var/lib/pulp/exports/. To configure additional paths, run foremanctl deploy with one or more --content-export-path options.

Procedure

  1. Create an incremental export:

    $ hammer content-export incremental repository \
--format=syncable \
--name="My_Repository" \
--organization="My_Organization" \
--product="My_Product"

  2. Optional: View the exported data:

    # find /var/lib/pulp/exports/Default_Organization/My_Product/2.0/2023-03-09T10-55-48-05-00/ -name "*.rpm"

5.4.11. Keeping track of your exports

Query and manage export records on the upstream Foreman server to organize incremental exports and track which content was exported to specific downstream servers.

Procedure

  1. Optional: Track the destinations of content exports. Use the --destination-server argument during export to indicate the target server. This option is available for all content-export operations.

    For example, specify the destination server when exporting a content view version:

    $ hammer content-export complete version \
--content-view="My_Content_View_Name" \
--destination-server=My_Downstream_Server_1 \
--organization="My_Organization" \
--version=1.0

  2. Query export records by listing the exports:

    $ hammer content-export list \
--organization="My_Organization"

5.5. Importing exported content

When synchronizing content by using export and import, import exported content into the downstream Foreman server Library environment, content view versions, or individual repositories.

5.5.1. Importing exports in the syncable format

Import syncable exports from an allowed import path on your downstream Foreman server into the Library environment.

Prerequisites

  • The syncable exports must be located in one of your allowed import paths. The default import paths are /var/lib/pulp/imports/ and /var/lib/pulp/sync_imports/. To configure additional paths, run foremanctl deploy with one or more --content-import-path options.

  • The importing organization must be configured to synchronize content through exports. For more information, see Configuring Foreman server to synchronize content through exports by using Foreman web UI.

Procedure

  • Import the syncable exports into the Library environment of your organization:

    $ hammer content-import library \
--organization="My_Organization" \
--path="My_Path_To_Syncable_Export"

5.5.2. Importing into the Library environment

You can import exported Library content into the Library environment of an organization on a downstream Foreman server.

Prerequisites

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

  • The importing organization must be configured to synchronize content through exports. For more information, see Configuring Foreman server to synchronize content through exports by using Foreman web UI.

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

  • The user importing the content has 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/

  3. Verify that the ownership is set correctly:

    # 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

  4. Identify the Organization that you want to import into.

  5. Import the Library content to Foreman server:

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

    You must specify the absolute path as in the example: /var/lib/pulp/imports/2021-03-02T03-35-24-00-00/. Relative paths do not work.

  6. Verify that you imported the Library content by checking 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.

    The importing Foreman server extracts the /var/lib/pulp/imports directory to /var/lib/pulp/.

  7. Delete the import files after a successful import:

    # rm -fr /var/lib/pulp/imports/2021-03-02T03-35-24-00-00/

5.5.3. Importing into the Library environment from a web server

You can import exported Library content directly from a web server into the Library environment on a downstream Foreman server when exports are in syncable format.

Prerequisites

  • The exported files must be in the syncable format.

  • The exported files must be accessible through HTTP/HTTPS.

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

  • The user importing the content has the Content Importer role.

Procedure

  1. Identify the Organization that you want to import into.

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

    $ hammer content-import library \
--organization="My_Organization" \
--path=http://server.example.com/pub/exports/2021-02-25T21-15-22-00-00/

    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.

5.5.4. Importing a content view version

You can import an exported content view version to recreate the same content in an organization on a downstream Foreman server.

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.

  • The importing organization must be configured to synchronize content through exports. For more information, see Configuring Foreman server to synchronize content through exports by using Foreman web UI.

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

  • The user importing the content view version has 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. Import the content view version to Foreman server:

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

    You must specify the absolute path as in the example: /var/lib/pulp/imports/2021-02-25T21-15-22-00-00/. Relative paths do not work.

  5. Verify that you imported the content view version successfully by listing the content view versions for your organization:

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

    The importing Foreman server extracts the /var/lib/pulp/imports directory to /var/lib/pulp/.

  6. Delete the import files after a successful import:

    # rm -fr /var/lib/pulp/imports/2021-02-25T21-15-22-00-00/

5.5.5. Importing a content view version from a web server

You can import an exported content view version directly from a web server when the export is in syncable format and accessible over HTTP/HTTPS.

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 syncable format.

  • The exported files must be accessible through HTTP/HTTPS.

  • 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

  • Import the content view version into Foreman server:

    $ hammer content-import version \
--organization=My_Organization \
--path=http://server.example.com/pub/exports/2021-02-25T21-15-22-00-00/

5.5.6. Importing a repository

You can import an exported repository into an organization on a downstream Foreman server to match content from the upstream server.

Prerequisites

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

  • The importing organization must be configured to synchronize content through exports. For more information, see Configuring Foreman server to synchronize content through exports by using Foreman web UI.

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

  • The user importing the content has 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/

  3. Verify that the ownership is set correctly:

    # 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

  4. Identify the Organization that you want to import into.

  5. Import the repository content into Foreman server:

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

    You must specify the absolute path as in the example: /var/lib/pulp/imports/2021-03-02T03-35-24-00-00. Relative paths do not work.

  6. Verify that you imported the repository by checking the contents of the product and repository. The importing Foreman server extracts the /var/lib/pulp/imports directory to /var/lib/pulp/.

  7. Delete the import files after a successful import:

    # rm -fr /var/lib/pulp/imports/2021-03-02T03-35-24-00-00/

5.5.7. Importing a repository from a web server

You can import an exported repository directly from a web server when the export is in syncable format and accessible over HTTP/HTTPS.

Prerequisites

  • The exported files must be in a syncable format.

  • The exported files must be accessible through HTTP/HTTPS.

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

  • The user importing the content has the Content Importer role.

Procedure

  1. Select the organization into which you want to import.

  2. Import the repository to Foreman server:

    $ hammer content-import repository \
--organization="My_Organization" \
--path=http://server.example.com/pub/exports/2021-02-25T21-15-22-00-00/

5.6. Hammer CLI cheat sheet for exporting and importing content

Use these Hammer CLI commands as a quick reference when exporting and importing content between Foreman servers.

Table 2. 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 3. 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"

6. Managing activation keys

Activation keys automate host configuration during registration to Foreman by assigning content view environments and enabling repositories. Create and configure your activation keys to scale consistent content access across many hosts.

You can use activation keys during 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 hosts:

  • Available products and repositories

  • Content view environments

  • 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 environments from the activation key overwrite the original content view from the host group or host settings. Then Foreman uses the content view environments 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 multiple activation keys with a host

    A 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", ...

6.1. Best practices for activation keys

Plan dedicated activation keys per use case, use descriptive names, and automate key management with Hammer or Ansible to keep host content modular and consistent.

  • Create an activation key for each use case. This structures, modularizes, and simplifies content management on hosts.

  • Use a naming convention for activation keys to indicate the content and lifecycle environment, for example, enterprise-linux-webserver.

  • Automate activation key management by using a Hammer script or an Ansible Playbook.

6.2. Creating an activation key by using Foreman web UI

Create an activation key and associate content view environments and repository overrides for host registration.

Procedure

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

  2. Click Create Activation Key.

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

  4. 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.

  5. Optional: In the Description field, enter a description for the activation key.

  6. On the Content view environments card, click Assign content view environments.

  7. Select a lifecycle environment.

  8. Select a content view.

  9. Optional: Click Assign another content view environment to assign additional content view environments to the activation key.

  10. Optional: Drag and drop the content view environments to change the order of the content view environments.

  11. Click Save to save the content view environments.

  12. Click Save to save the activation key.

  13. Optional: In the System Purpose section, you can configure the activation key to set system purpose attributes on hosts during registration. This helps determine which repositories are available on the host. It also helps with reporting in the Subscriptions service of the Red Hat Hybrid Cloud Console.

  14. On the Repository Sets tab, override repositories to Enabled or Disabled as desired. For more information, see Enabling and disabling repositories on activation key.

  15. Optional: On the Host Collections tab, click Add to view a list of available host collections. Select your host collection and click Add Selected. This ensures that hosts become part of your host collection during the host registration process.

6.3. Creating an activation key by using Hammer CLI

Create an activation key and associate content view environments and repository overrides for host registration.

Procedure

  1. Create the activation key:

    $ hammer activation-key create \
--name "My_Activation_Key" \
--unlimited-hosts \
--description "Example Stack in the Development Environment" \
--content-view-environments "Development/Stack" \
--organization "My_Organization"

  2. Optional: Configure the activation key with system purpose attributes to set on hosts during registration. This helps determine which repositories are available on the host. It also helps with reporting in the Subscriptions service of the Red Hat Hybrid Cloud Console.

    $ 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"

  3. List the product content associated with the activation key:

    $ hammer activation-key product-content \
--content-access-mode-all true \
--name "My_Activation_Key" \
--organization "My_Organization"

  4. Override the default auto-enable status for the Foreman Client repository:

    $ hammer activation-key content-override \
--name "My_Activation_Key" \
--content-label "My_Content_Label" \
--value 1 \
--organization "My_Organization"

    For a repository, the content label consists of your organization label, product label, and repository label split by underscores. For example, Example_Foreman_Client_Enterprise_Linux_9. For content from Red Hat, the content label is taken from the Red Hat manifest. For example, rhel-10-for-x86_64-baseos-rpms.

    The default status is set to disabled.

  5. Optional: Assign a host collection to your activation key:

    $ hammer activation-key add-host-collection \
--host-collection-id My_Host_Collection_ID \
--id _My_Activation_Key_ID \
--organization-id _My_Organization_ID

    This ensures that hosts become part of your host collection during the host registration process.

6.4. Setting the service level by using Foreman web UI

Configure an activation key to set the default subscription service level that hosts inherit when they register with the activation key.

Note

You can only select a Premium service level if your Red Hat manifest contains premium support for any Red Hat products.
Procedure

  1. In the Foreman web UI, navigate to Content > Lifecycle > 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.

6.5. Setting the service level by using Hammer CLI

Configure an activation key to set the default subscription service level that hosts inherit when they register with the activation key.

Note

You can only select a Premium service level if your Red Hat manifest contains premium support for any Red Hat products.
Procedure

  • Set the service level to Premium on your activation key:

    $ hammer activation-key update \
--name "My_Activation_Key" \
--organization "My_Organization" \
--service-level premium

6.6. Enabling and disabling repositories on activation key

Override repository set status on an activation key to control which repositories are enabled when hosts register with the activation key.

Procedure

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

  2. Select an activation key.

  3. Select the Repository Sets tab.

  4. Optional: Clear the Limit to Environment checkbox to view repositories that are available in the lifecycle environment of the activation key.

  5. Optional: Use the Repository type dropdown menu to filter repositories by type.

  6. Optional: Use the Status dropdown menu to filter repositories by status.

  7. Select the desired repositories or click the Select All checkbox to select all repositories.

  8. From the Select Action list, select Override to Enabled, Override to Disabled, or Reset to Default.

6.7. Activation keys and host registration

Use activation keys during provisioning or when registering existing Enterprise Linux hosts to apply subscription and content settings automatically.

Note

The Agama, AutoYaST, Kickstart, Preseed, and Preseed Autoinstall provisioning templates in Foreman contain commands to register the host, using an activation key that is defined when creating a host.

You can use multiple activation keys when registering a host. For example, you can use one activation key to enable specific repositories and another to assign content view environments.

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: Host Collections.

  • Settings that influence the behavior of the key itself and not the host configuration: Content Host Limit.

Additional resources

6.8. Multiple activation keys and content view environments

When you register a host with multiple activation keys, Foreman merges their settings and resolves conflicts by key order and the Allow multiple content views setting.

When multiple activation keys assign the same attributes, Foreman decides how to resolve conflicts. In general, the host receives the union of non-conflicting settings and the setting from the last activation key for conflicting settings.

Conflicting settings, where the setting from the last activation key wins, include:

  • System purpose attributes

  • Release version

Non-conflicting settings, where the host receives the union of them, include:

  • Host collections

Activation key behavior regarding multiple content view environments depends on the Allow multiple content views setting. If you enable Allow multiple content views, content view environments are treated as non-conflicting. If you disable Allow multiple content views, content view environments are considered conflicting.

When you enable Allow multiple content views and register a host with multiple activation keys, the host receives all content view environments from each activation key, in the order they are passed.

Example 2. Example with Allow multiple content views enabled

Assuming that:

  • Activation key ak_multi assigns content view environments dev/cv2, dev/cv3.

  • Activation key ak4 assigns content view environments dev/cv4.

A host registered with activation keys ak_multi and ak4 receives content view environments dev/cv2, dev/cv3, and dev/cv4.

If the order is reversed, with ak4 followed by ak_multi, the host receives content view environments dev/cv4, dev/cv2, and dev/cv3.

When you disable Allow multiple content views and register a host with multiple activation keys, the host receives the content view environments from the last activation key with any content view environments. If any of the activation keys is a multi-environment activation key, registration fails with an error, regardless of the order.

Example 3. Example with Allow multiple content views disabled

Assuming that:

  • Activation key ak_multi assigns content view environments dev/cv2, dev/cv3.

  • Activation key ak4 assigns content view environment dev/cv4.

  • Activation key ak5 assigns content view environment dev/cv5.

  • Activation key ak_none assigns no content view environments.

If you attempt to register a host with activation keys ak_multi, ak4, registration fails because ak_multi is a multi-environment activation key.

If you register a host with activation keys ak4, ak5, the host receives dev/cv5, as ak5 is the last activation key with content view environments.

If you register a host with activation keys ak4, ak5, ak_none, the host receives dev/cv5 because ak5 is the last activation key with content view environments.

If you register a host with activation keys ak5, ak4, the host receives dev/cv4, as ak4 is the last activation key with content view environments.

6.9. Assigning content view environments to an activation key by using Foreman web UI

Assign content view environments to an activation key so registered hosts receive content from the content view environments you specify, in the order you define.

Prerequisites

  • If you want to assign multiple content view environments, the Allow multiple content views setting must be enabled.

  • You have created an activation key.

Procedure

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

  2. Click the name of the activation key to which you want to assign content view environments.

  3. On the the Content view environments card, click Assign content view environments.

  4. Select a lifecycle environment.

  5. Select a content view.

  6. Optional: Click Assign another content view environment to assign additional content view environments to the activation key.

  7. Optional: Drag and drop the content view environments to change the order of the content view environments.

  8. Click Save.

Verification

  • The Details tab of the activation key displays the assigned content view environments in order.

Additional resources

6.10. Assigning content view environments to an activation key by using Hammer CLI

Assign content view environments to an activation key so registered hosts receive content from the content view environments you specify, in the order you define.

Prerequisites

  • If you want to assign multiple content view environments, the Allow multiple content views setting must be enabled.

  • You have created an activation key.

Procedure

  1. Display the available content view environments to obtain their labels or IDs:

    $ hammer content-view-environment list

  2. Assign content view environments to an activation key:

    • By using their labels:

      $ hammer activation-key update \
--id My_Activation_Key_ID \
--organization-id My_Organization_ID \
--content-view-environments "My_env1/My_cv1,My_env2/My_cv2"

    • By using their IDs:

      $ hammer activation-key update \
--id My_Activation_Key_ID \
--organization-id My_Organization_ID \
--content-view-environment-ids [My_content_view_env_ID_1, My_content_view_env_ID_2]
Additional resources

6.11. Removing all content view environments from an activation key

Remove all content view environments from an activation key when you need to clear assignments before reconfiguring the activation key.

Procedure

  • Remove all content view environments from the activation key by passing an empty array:

    $ hammer activation-key update \
--content-view-environment-ids [] \
--name My_Activation_Key \
--organization-id My_Organization_ID

  • Remove all content view environments from an activation key by passing an empty string:

    $ hammer activation-key update \
--content-view-environments "" \
--name My_Activation_Key \
--organization-id My_Organization_ID

7. 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 by 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.

7.1. Enabling OSTree content

You can enable OSTree on your Foreman to synchronize and manage OSTree branches from the exposed OSTree repository.

Procedure

  • On your Foreman server, enable OSTree content:

    # foremanctl --add-feature content/ostree

7.2. Importing OSTree content by using Foreman web UI

You can import and synchronize OSTree content from custom online sources over HTTPS by using Foreman web UI.

Prerequisites

  • 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. Optional: In the Exclude Refs field, enter a list of OSTree head refs separated with commas to exclude from importing to Foreman. The excludes are evaluated after the includes.

  19. Optional: In the Include Refs field, enter a list of OSTree head refs separated with commas to include in importing to Foreman. For example fedora/x86_64/coreos/stable.

  20. Optional: In the Depth field, enter the number of commits to traverse.

  21. 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.

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

  23. Optional: Disable the Unprotected checkbox to require a subscription entitlement certificate for accessing the published repository.

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

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

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

  27. Click Save.

  28. When the repository creation completes, select the new repository and click Sync Now to start the synchronization process.

  29. To view the synchronization status, navigate to Content > Sync Status and expand the entry that you want to view.

7.3. Importing OSTree content by using Hammer CLI

You can import and synchronize OSTree content from custom online sources over HTTPS by using Hammer CLI.

Prerequisites

  • A published HTTP location, known as an upstream URL, for the OSTree to import.

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"

7.4. Uploading OSTree content by using 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"
Prerequisites

  • You have an OSTree image archive ready and present on your file system.

Procedure

  • On your Foreman server, upload your OSTree archive:

    $ hammer repository upload-content \
--content-type ostree_ref \
--id My_Repository_id \
--ostree-repository-name My_Repository_Name \
--path /path/to/image/file.tar

    The value of --ostree-repository-name must match the name of the OSTree repository in the archive.

Additional resources

7.5. Managing OSTree content with content views by using Foreman web UI

Use content views to manage OSTree branches across the application lifecycle by using Foreman web UI. This process uses the same publication and promotion method as RPMs or Puppet modules.

Prerequisites

  • You have created a product and added an OSTree repository to it.

Procedure

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

  2. Click Create content view.

  3. In the Name field, enter a plain text name for the view. This automatically populates the Label field.

  4. In the Description field, enter a description of the OSTree content view.

  5. If you want to use a composite content view, select the Composite View checkbox.

  6. 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.

  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 lifecycle.

  13. Click Next.

  14. Review details and click Finish.

7.6. Managing OSTree content with content views by using Hammer CLI

Use content views to manage OSTree branches across the application lifecycle by using Hammer CLI. This process uses the same publication and promotion method as RPMs or Puppet modules.

Prerequisites

  • You have created a product and added an OSTree repository to it.

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 My_Repository_IDs \
--organization "My_Organization"

  3. Publish the content view:

    $ hammer content-view publish \
--name "OSTree" \
--description "Example content view for the OSTree" \
--organization "My_Organization"

7.7. Installing OSTree content from Foreman server on hosts

OSTree content from Foreman on hosts is managed by Subscription Manager and can be accessed by using rpm-ostree.

Prerequisites
Procedure

  1. On your hosts, view the available heads:

    $ rpm-ostree remote list

  2. Rebase to a new remote from Foreman:

    $ rpm-ostree rebase --remote=My_Organization_OSTree_Content_OSTree

8. Managing file type content in Foreman

You can use file type repositories in products to store and distribute arbitrary files such as SSH keys, source code, or ISO images in Foreman.

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.

You can create a file type repository in Foreman server only in a product, but there is flexibility in how you create the repository source. You can create an independent repository source in a directory on Foreman server, 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.

You can also use file type repositories to provide local installation media for Debian and Ubuntu in disconnected environments.

Additional resources

8.1. Creating a local source for a file type repository

When you have multiple files to import, you can prepare a directory on Foreman server as a local Pulp source. Then, synchronize files from this directory into a file type repository.

Configure a directory on the base system where Foreman is installed as the repository source. To create a file type repository in a directory on a remote server, see Creating a remote source for a file type repository.

Procedure

  1. On your Foreman server, install the Pulp Manifest package:

    # dnf install pulp-manifest

  2. Create a directory that you want to use as the file type repository, such as:

    # mkdir -p /var/lib/pulp/local_repos/my_file_repo

  3. Add the parent folder to allowed import paths:

    # foremanctl deploy --content-import-path /var/lib/pulp/local_repos

    To add multiple import paths, use the --content-import-path option multiple times:

    # foremanctl deploy --content-import-path /var/lib/pulp/local_repo1 \
--content-import-path /var/lib/pulp/local_repo2

  4. Add files to the directory or create a test file:

    # touch /var/lib/pulp/local_repos/my_file_repo/test.txt

  5. Create the Pulp Manifest:

    # pulp-manifest /var/lib/pulp/local_repos/my_file_repo

  6. Verify the manifest was created:

    # ls /var/lib/pulp/local_repos/my_file_repo
PULP_MANIFEST test.txt
Next steps

  • You can import your local source as a file type repository. Use the file:// URL scheme and the name of the directory to specify an Upstream URL, such as file:///var/lib/pulp/local_repos/my_file_repo. For more information, see Creating a file type repository by using Foreman web UI.

8.2. Creating a remote source for a file type repository

You can prepare a directory on a remote HTTP server as a Pulp source and synchronize files into a file type repository on Foreman server.

Configure a directory on a remote server as the repository source. To create a file type repository in a directory on the base system where Foreman server is installed, see Creating a local source for a file type repository.

Prerequisites

  • You have a server running Enterprise Linux 9 registered to your Foreman.

  • You have installed an HTTP server. For more information about configuring a web server, see Setting up the Apache HTTP web server in Red Hat Enterprise Linux 9 Deploying web servers and reverse proxies.

Procedure

  1. On your HTTP server, enable the required repositories:

    # dnf config-manager --add-repo=https://yum.theforeman.org/pulpcore/3.105/el9/x86_64/
# echo "gpgkey=https://yum.theforeman.org/pulpcore/3.105/GPG-RPM-KEY-pulpcore" \
>> /etc/yum.repos.d/yum.theforeman.org_pulpcore_3.105_el9_x86_64_.repo

  2. Install the Pulp Manifest package:

    # dnf install pulp-manifest

  3. 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

  4. Add files to the directory or create a test file:

    # touch /var/www/html/pub/my_file_repo/test.txt

  5. Create the Pulp Manifest:

    # pulp-manifest /var/www/html/pub/my_file_repo

  6. Verify the manifest was created:

    # ls /var/www/html/pub/my_file_repo
PULP_MANIFEST test.txt
Next steps

8.3. Creating a file type repository by using Foreman web UI

You can add a file type repository to an existing product. Select the file repository type and follow the same workflow as when you add other content.

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. If you do not enter an upstream URL, you can manually upload packages.

  8. Select Verify SSL to verify that the SSL certificates of the repository 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 Download Policy list, select the type of synchronization Foreman server performs.

  13. From the Mirroring Policy list, select the type of content synchronization Foreman server performs.

  14. Optional: In the HTTP Proxy Policy field, select an HTTP proxy. By default, it uses the Global Default HTTP proxy.

  15. 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.

  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 to create the repository.

8.4. Creating a file type repository by using Hammer CLI

You can add a file type repository to an existing product. Select the file repository type and follow the same workflow as when you add other content.

Procedure

  1. Create a product:

    $ hammer product create \
--name "My_File_Product" \
--organization-id My_Organization_ID \
--sync-plan "My_Sync_Plan"
    Table 4. Optional parameters for the hammer product create command
    Option Description

    --gpg-key-id gpg_key_id

    GPG key numeric identifier

    --sync-plan-id sync_plan_id

    Sync plan numeric identifier

    --sync-plan sync_plan_name

    Sync plan name to search by

  2. Create a file type repository:

    $ hammer repository create \
--content-type file \
--name "My_Files" \
--organization-id My_Organization_ID \
--product "My_File_Product"
    Table 5. Optional parameters for the hammer repository create command
    Option Description

    --checksum-type sha_version

    Repository checksum (either sha256, sha384, or sha512)

    --download-policy policy_name

    Download policy for repositories (either immediate or on_demand)

    --gpg-key-id gpg_key_id

    GPG key numeric identifier

    --gpg-key gpg_key_name

    Key name to search by

    --mirror-on-sync boolean

    Must this repo be mirrored from the source, and stale packages 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-password repository_password

    Password for the upstream repository user

    --upstream-username repository_username

    Upstream repository user, if required for authentication

    --url My_Repository_URL

    URL of the remote repository

    --verify-ssl-on-sync boolean

    Verify that the upstream SSL certificates of the remote repository are signed by a trusted CA? Set to true or false, yes or no, 1 or 0.

8.5. Creating file type repositories for installation media for Debian 13

You can use file type repositories to provide local installation media for Debian. This allows you to provision hosts running Debian 13 in disconnected environments.

Procedure

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

  2. Click Create Product.

  3. Enter a Name for your product.

  4. Optional: Select a sync plan from the Sync Plan drop down menu.

  5. Click Save to create the product.

  6. On the Repositories tab of the previously created product, click New Repository.

  7. Enter a Name for the repository.

    If you use the file type repository as installation medium for offline installations, Foreman community recommends adding offline installation media to indicate the offline installation capability, for example, Debian 13 offline installation media.

  8. Select file as Type.

  9. In the Upstream URL field, enter the URL of the file type repository that contains your Debian 13 installation medium.

  10. Click Save to create the repository.

  11. On the Repositories tab, select your previously created repository and click Sync Now.

  12. After you have synchronized the repository, navigate to Content > Products.

  13. Select the previously created product.

  14. On the Repositories tab, select the previously created repository.

  15. Copy the Published At URL.

  16. Navigate to Hosts > Installation Media.

  17. Click Create Medium.

  18. Enter a Name for the installation media.

    Foreman community recommends adding local to indicate that the installation medium is stored on your Foreman locally. You can use this installation medium to provision hosts in disconnected environments.

  19. Enter the copied URL as Path.

  20. Select the Operating System Family.

  21. Click Submit to create the installation media.

8.6. Creating file type repositories for installation media for Ubuntu 26.04

You can use file type repositories to provide local installation media for Ubuntu. This allows you to provision hosts running Ubuntu 26.04 in disconnected environments.

To provision Ubuntu 26.04, you need to provide both the ISO image and the extracted ISO image on your Foreman server or the relevant Smart Proxy server. This example uses Foreman server.

Procedure

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

  2. Click Create Product.

  3. Enter a Name for your product.

  4. Optional: Select a sync plan from the Sync Plan drop down menu.

  5. Click Save to create the product.

  6. On the Repositories tab of the previously created product, click New Repository.

  7. Enter a Name for the repository.

    If you use the file type repository as installation medium for offline installations, Foreman community recommends adding offline installation media to indicate the offline installation capability, for example, Ubuntu 26.04 offline installation media.

  8. Select file as Type.

  9. In the Upstream URL field, enter the URL of the file type repository that contains your Ubuntu 26.04 installation medium.

  10. Click Save to create the repository.

  11. On the Repositories tab, select your previously created repository and click Sync Now.

  12. After you have synchronized the repository, navigate to Content > Products.

  13. Select the previously created product.

  14. On the Repositories tab, select the previously created repository.

  15. Copy the Published At URL.

  16. On your Foreman server, use the Published At URL from your synchronized file repository to download the ISO image:

    $ wget --directory-prefix /tmp/ https://foreman.example.com/pulp/content/My_Organization_Label/Library/custom/My_Product/My_Repository/ubuntu-26.04-latest.iso

  17. Mount the ISO image:

    # mount ubuntu-26.04-latest.iso /mnt

  18. Provide the ISO image and the extracted directory under foreman.example.com/pub:

    # mkdir --parents /var/www/html/pub/installation_media/ubuntu/26.04-x86_64/
# cp ubuntu-26.04-latest.iso /var/www/html/pub/installation_media/ubuntu/26.04-x86_64.iso
# cp --archive /mnt/* /var/www/html/pub/installation_media/ubuntu/26.04-x86_64/

    Ensure that the path in /pub/ matches the path in your Preseed default PXELinux Autoinstall template.

  19. Unmount and delete the ISO image:

    # umount /mnt/
# rm --force ubuntu-26.04-latest.iso
Next steps

  • Use http://foreman.example.com/pub/installation_media/ubuntu/26.04-x86_64/ to set up your installation media entry in Foreman.

Appendix A: Required Red Hat repositories

Enable the Red Hat repositories for your release and host architecture so Foreman can synchronize content from the Red Hat CDN to manage Red Hat Enterprise Linux hosts. Enable matching Kickstart repositories when you provision hosts with the Anaconda installer.

To register and manage hosts with Foreman, you need the following repositories:

For Red Hat Enterprise Linux 10 hosts

  • Red Hat Enterprise Linux 10 for x86_64 - BaseOS (RPMs)

  • Red Hat Enterprise Linux 10 for x86_64 - AppStream (RPMs)

For Red Hat Enterprise Linux 9 hosts

  • Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs)

  • Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs)

For Red Hat Enterprise Linux 8 hosts

  • Red Hat Enterprise Linux 8 for x86_64 - BaseOS (RPMs)

  • Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMs)

For Red Hat Enterprise Linux 7 hosts

  • Red Hat Enterprise Linux 7 Server (RPMs)

To provision hosts by using the Anaconda installer with Kickstart, you additionally need the following repositories:

For Red Hat Enterprise Linux 10 hosts

  • Red Hat Enterprise Linux 10 for x86_64 - BaseOS (Kickstart)

  • Red Hat Enterprise Linux 10 for x86_64 - AppStream (Kickstart)

For Red Hat Enterprise Linux 9 hosts

  • Red Hat Enterprise Linux 9 for x86_64 - BaseOS (Kickstart)

  • Red Hat Enterprise Linux 9 for x86_64 - AppStream (Kickstart)

For Red Hat Enterprise Linux 8 hosts

  • Red Hat Enterprise Linux 8 for x86_64 - BaseOS (Kickstart)

  • Red Hat Enterprise Linux 8 for x86_64 - AppStream (Kickstart)

For Red Hat Enterprise Linux 7 hosts

  • Red Hat Enterprise Linux 7 Server (Kickstart)

For other supported architectures, substitute your architecture for x86_64 in the repository names.

Appendix B: Troubleshooting synchronization errors

If you encounter the following errors during content synchronization, follow the steps to troubleshoot and resolve the problem.

"[Errno 1] Operation not permitted: …​" during repository syncing
# chown --recursive pulp:pulp /var/lib/pulp/media/
500 API error during syncing with "cryptography.fernet.InvalidToken" in /var/log/messages traceback

Run this command on your Foreman server and all Smart Proxy servers:

# sudo -u pulp PULP_SETTINGS='/etc/pulp/settings.py' pulpcore-manager datarepair-2327 --dry-run

If you see values greater than 0, repair the content:

# sudo -u pulp PULP_SETTINGS='/etc/pulp/settings.py' pulpcore-manager datarepair-2327

Appendix C: Storing content on an NFS share

When local disk space on your Foreman server is insufficient for content storage, you can mount an NFS share at /var/lib/pulp to store synchronized content remotely.

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.
Prerequisites

  • The NFS share exists and provides the appropriate permissions to Foreman server and its apache user. This example uses a share at nfs.example.com:/Foreman/pulp.

Procedure

  1. Stop Foreman services on your Foreman server:

    # systemctl stop foreman.target

  2. Install the nfs-utils package on your Foreman server:

    # dnf install nfs-utils

  3. Copy the existing contents of /var/lib/pulp to the NFS share.

    1. Mount the NFS share at a temporary location:

      # mkdir /mnt/temp
# mount -o rw nfs.example.com:/Foreman/pulp /mnt/temp

    2. Copy the existing contents of /var/lib/pulp to the temporary location:

      # cp -r /var/lib/pulp/* /mnt/temp/.

    3. Set the permissions for all files on the share to use the pulp user.

    4. Unmount the temporary storage location:

      # umount /mnt/temp

  4. Remove the existing contents of /var/lib/pulp:

    # rm -rf /var/lib/pulp/*

  5. 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.

  6. Enable the mount:

    # mount -a

  7. Verify the NFS share provides the content:

    1. 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
...

    2. Confirm the content exists at the mount on /var/lib/pulp:

      # ls /var/lib/pulp

  8. Start Foreman services on your Foreman server:

    # systemctl start foreman.target
Pre-release version Report issue