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

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

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

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

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

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

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

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

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

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

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

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

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

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

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