Importing content

This chapter outlines how you can import different types of content to orcharhino. For example, you can use the following chapters for information on specific types of content but the underlying procedures are the same:

Products and repositories in orcharhino

You can organize content in Products. Products bundle an arbitrary number of repositories.

Products require a subscription for hosts to access. orcharhino creates a subscription for each product you create.

Importing custom SSL certificates

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

If you require SSL certificates and keys to download packages, you can add them to orcharhino.

To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Procedure
  1. In the orcharhino management UI, navigate to Content > Content Credentials. In the Content Credentials window, click Create Content Credential.

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

  3. From the Type list, select SSL Certificate.

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

  5. Click Save.

CLI procedure
  1. Copy the SSL certificate to your orcharhino Server:

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

    Or download the SSL certificate to your orcharhino Server from an online source:

    $ wget -P ~ http://upstream-orcharhino.example.com/pub/katello-server-ca.crt
  2. Upload the SSL Certificate to orcharhino:

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

Creating a product

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

Procedure
  1. In the orcharhino management UI, navigate to Content > Products, click Create Product.

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

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

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

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

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

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

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

  9. Click Save.

CLI procedure

To create the product, enter the following command:

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

Best practices for products and repositories

  • Use one content type per product and content view, for example, APT content only.

  • Use file repositories for installation media. File repositories require a PULP_MANIFEST file that you can create using pulp-manifest /path/to/files. Use local repositories with file:///path/to/files as Upstream URL in orcharhino, for example, for installation media. Alternatively, place the installation media file repositories on a web server that is accessible to the hosts during provisioning.

    ATIX AG provides file repositories for installation media to provision hosts in a disconnected environment using a local installation medium from orcharhino Server. For the upstream URLs, see ATIX Service Portal.

    ATIX AG provides the following installation media as file repositories:

    • Debian 12

    • Debian 11

    • Debian 10

    • Ubuntu 22.04

    • Ubuntu 20.04

    • Ubuntu 18.04

    For more information, see Managing Custom File Type Content.

  • Make file repositories available over HTTP. If you set Protected to true, you can only download content using a global debugging certificate.

  • Automate the creation of multiple products and repositories by using a Hammer script or an Ansible playbook.

  • Avoid uploading content to repositories with an Upstream URL. Instead, create a repository to synchronize content and upload content to without setting an Upstream URL.

    If you upload content to a repository that already synchronizes another repository, the content might be overwritten, depending on the mirroring policy and content type.

Extracting GPG public key fingerprints from Release files

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

Procedure
  1. Download the Release and Release.gpg files:

    $ wget https://deb.debian.org/debian/dists/bullseye/Release
    $ wget https://deb.debian.org/debian/dists/bullseye/Release.gpg
  2. Verify the signature:

    $ gpg --verify Release.gpg Release

    Note the GPG key fingerprint for any missing public GPG keys above the Can’t check signature: No public key message. These fingerprints will be used in the next step.

  3. If you cannot verify the signature, import the missing GPG public keys based on their fingerprint:

    $ gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys A7236886F3CCCAAD148A27F80E98404D386FA1D9
    $ gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 4CB50190207B4758A3F73A796ED0E7B82643E131
    $ gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys A4285295FC7B1A81600062A9605C66F00D6C9793
  4. Optional: Verify the signature again:

    $ gpg --verify Release.gpg Release
  5. Export the ASCII-armored GPG public keys to a file:

    $ gpg --armor --export A7236886F3CCCAAD148A27F80E98404D386FA1D9 4CB50190207B4758A3F73A796ED0E7B82643E131 A4285295FC7B1A81600062A9605C66F00D6C9793 > debian_11.txt

    Ensure that gpg returns a Good signature message for each signature.

    Upload the .txt file to orcharhino. For more information, see Importing a Custom GPG Key into orcharhino.

Adding Deb repositories

Use this procedure to add Deb repositories in orcharhino. To use the CLI instead of the orcharhino management UI, see the CLI procedure.

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

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

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

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

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

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

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

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

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

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

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

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

  9. Optional: In the Errata URL field, enter the URL of an errata service.

    The ATIX AG Debian and Ubuntu Errata service provides errata for Debian and Ubuntu. When creating a repository of type deb, point the Errata URL to ATIX AG Debian and Ubuntu Errata service. Use https://dep.atix.de/dep/api/v1/debian for Debian, https://dep.atix.de/dep/api/v1/ubuntu for Ubuntu, and https://dep.atix.de/dep/api/v1/ubuntu-esm for Ubuntu-ESM.

    An erratum contains the information which packages have to be updated to fix a security issue. Debian and Ubuntu errata are derived from the Debian security announcements (DSA) and the Ubuntu security notices (USN).

    You must add Debian and Ubuntu errata to the security repository. For Debian, you need the My_Debian_Release-security repository, for example, bookworm-security. For Ubuntu, you need the My_Ubuntu_Release-security repository, for example, noble-security.

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

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

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

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

  14. From the Download Policy list, select the type of synchronization orcharhino Server performs. For more information, see Download Policies Overview.

  15. From the Mirroring Policy list, select the type of content synchronization orcharhino Server performs. For more information, see Mirroring Policies Overview.

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

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

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

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

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

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

  22. Click Save to create the repository.

CLI procedure
  1. Enter the following command to create the repository:

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

Adding upstream repositories for Ubuntu 24.04

This example creates a product and repositories for Ubuntu 24.04.

Prerequisites
Procedure
  1. In the orcharhino management UI, navigate to Content > Products.

  2. Click Create Product to create a product named Ubuntu 24.04.

  3. On the Repositories tab, click New Repository to create three deb repositories with the following parameter values:

  4. Click Create Product to create a product named Ubuntu 24.04 client.

  5. On the Repositories tab, click New Repository to create a deb repository with the following parameter values:

    • Ubuntu 24.04 client

      • Upstream URL: see ATIX Service Portal

      • Releases/Distributions: stable

      • Component: main

      • Architecture: amd64

Additional resources

Adding upstream repositories for Ubuntu 22.04

This example creates a product and repositories for Ubuntu 22.04.

Prerequisites
Procedure
  1. In the orcharhino management UI, navigate to Content > Products.

  2. Click Create Product to create a product named Ubuntu 22.04.

  3. On the Repositories tab, click New Repository to create three deb repositories with the following parameter values:

  4. Click Create Product to create a product named Ubuntu 22.04 client.

  5. On the Repositories tab, click New Repository to create a deb repository with the following parameter values:

    • Ubuntu 22.04 client

      • Upstream URL: see ATIX Service Portal

      • Releases/Distributions: stable

      • Component: main

      • Architecture: amd64

Additional resources

The ATIX AG Debian and Ubuntu Errata service provides errata for Debian and Ubuntu. When creating a repository of type deb, point the Errata URL to ATIX AG Debian and Ubuntu Errata service. Use https://dep.atix.de/dep/api/v1/debian for Debian, https://dep.atix.de/dep/api/v1/ubuntu for Ubuntu, and https://dep.atix.de/dep/api/v1/ubuntu-esm for Ubuntu-ESM.

An erratum contains the information which packages have to be updated to fix a security issue. Debian and Ubuntu errata are derived from the Debian security announcements (DSA) and the Ubuntu security notices (USN).

You must add Debian and Ubuntu errata to the security repository. For Debian, you need the My_Debian_Release-security repository, for example, bookworm-security. For Ubuntu, you need the My_Ubuntu_Release-security repository, for example, noble-security.

Adding orcharhino Clients for Ubuntu

orcharhino Clients are required to register hosts to orcharhino. You can add them to your orcharhino during the installation process or afterwards. For more information, see Adding orcharhino Clients manually and Using orcharhino Clients gen2 in the ATIX Service Portal.

Procedure
  1. Create a product named orcharhino Clients for Ubuntu. For more information, see Creating a Custom Product.

  2. Create a repository for Ubuntu 24.04. You can find the upstream URL of all orcharhino Clients in the ATIX Service Portal. For more information, see Adding Custom deb Repositories.

  3. Synchronize the orcharhino Clients for Ubuntu to your orcharhino. For more information, see Synchronizing Repositories.

  4. Create a content view to make the .deb packages consumable by content hosts. For more information, see Creating an Activation Key.

  5. Create an activation key to register content hosts to orcharhino. For more information, see Creating an Activation Key.

  6. Optional: Create a host group to simplify the process of creating hosts. For more information, see Creating a Host Group.

Changing the repository sets status for a host in orcharhino

Repository sets show repositories available to each host. A host will be able to access content from a given repository if that repository is enabled.

Procedure
  1. In the orcharhino management UI, navigate to Hosts > All Hosts and select a host.

  2. Select the Content tab, then select the Repository sets subtab. On the tab, there is a set of repositories available to each host with a status of Enabled or Disabled.

  3. You can override the default status by using the action menus on each table row by changing the status to Override to disabled, Override to enabled, or Reset to default.

  4. You can also bulk select the checkboxes on each table row, and use the vertical ellipsis icon at the top.

    For hosts not in the default content view and lifecycle environment, the Repository sets tab shows a toggle group with two options, Limit to environment and Show all. The Limit to environment option shows only repositories that are relevant to the host. The Show all option shows all available repositories including those that may not be in the host’s content view and lifecycle environment. On the Overview tab, click Content view details to view the environment for the host.

Synchronizing repositories

You must synchronize repositories to download content into orcharhino. You can use this procedure for an initial synchronization of repositories or to synchronize repositories manually as you need.

You can also sync all repositories in an organization. For more information, see Synchronizing All Repositories in an Organization.

Create a sync plan to ensure updates on a regular basis. For more information, see Creating a Sync Plan.

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

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

256 Kbps

5 Mins 27 Secs

6 Hrs 49 Mins 36 Secs

2 Days 7 Hrs 55 Mins

512 Kbps

2 Mins 43.84 Secs

3 Hrs 24 Mins 48 Secs

1 Day 3 Hrs 57 Mins

T1 (1.5 Mbps)

54.33 Secs

1 Hr 7 Mins 54.78 Secs

9 Hrs 16 Mins 20.57 Secs

10 Mbps

8.39 Secs

10 Mins 29.15 Secs

1 Hr 25 Mins 53.96 Secs

100 Mbps

0.84 Secs

1 Min 2.91 Secs

8 Mins 35.4 Secs

1000 Mbps

0.08 Secs

6.29 Secs

51.54 Secs

Procedure
  1. In the orcharhino management UI, navigate to Content > Products and select the Product that contains the repositories that you want to synchronize.

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

  3. Optional: To view the progress of the synchronization in the orcharhino management UI, navigate to Content > Sync Status and expand the corresponding Product or repository tree.

CLI procedure
  • Synchronize an entire Product:

    # hammer product synchronize \
    --name "My_Product" \
    --organization "My_Organization"
  • Synchronize an individual repository:

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

Synchronizing all repositories in an organization

Use this procedure to synchronize all repositories within an organization.

Procedure
  1. Log in to your orcharhino 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

Download policies overview

orcharhino provides multiple download policies for synchronizing Deb and Yum content and container images. For example, you might want to download only the content metadata while deferring the actual content download for later.

orcharhino Server has the following policies:

Immediate

orcharhino Server downloads all metadata and packages during synchronization.

On Demand

orcharhino Server downloads only the metadata during synchronization. orcharhino Server only fetches and stores packages on the file system when orcharhino Proxies or directly connected clients request them. This setting has no effect if you set a corresponding repository on a orcharhino Proxy to Immediate because orcharhino 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.

orcharhino Proxy Server has the following policies:

Immediate

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

On Demand

orcharhino Proxy Server only downloads the metadata during synchronization. orcharhino 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 orcharhino Server if it is not available on orcharhino Proxy Server.

Inherit

orcharhino Proxy Server inherits the download policy for the repository from the corresponding repository on orcharhino Server.

Streamed Download Policy

Streamed Download Policy for orcharhino Proxies permits orcharhino Proxies to avoid caching any content. When content is requested from the orcharhino Proxy, it functions as a proxy and requests the content directly from the orcharhino.

Changing the default download policy

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

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

Procedure
  1. In the orcharhino management UI, navigate to Administer > Settings.

  2. Click the Content tab.

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

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

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

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

    # hammer settings set \
    --name default_redhat_download_policy \
    --value immediate
  • To change the default download policy for a repository to one of immediate or on_demand, enter the following command:

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

Changing the download policy for a repository

You can set the download policy for a repository.

Procedure
  1. In the orcharhino management UI, navigate to Content > Products.

  2. Select the required product name.

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

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

CLI procedure
  1. List the repositories for an organization:

    # hammer repository list \
    --organization-label My_Organization_Label
  2. Change the download policy for a repository to immediate or on_demand:

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

Mirroring policies overview

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

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

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

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

Changing the mirroring policy for a repository

You can set the mirroring policy for a repository.

To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Procedure
  1. In the orcharhino management 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.

CLI 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 1 \
    --mirroring-policy mirror_complete

Refreshing content counts on orcharhino Proxy

If your orcharhino Proxies have synchronized content enabled, you can refresh the number of content counts available to the environments associated with the orcharhino Proxy. This displays the content views inside those environments available to the orcharhino Proxy. You can then expand the content view to view the repositories associated with that content view version.

Procedure
  1. In the orcharhino management UI, navigate to Infrastructure > orcharhino Proxies, and select the orcharhino 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 orcharhino Proxy which refreshes the content counts.

  4. Select the Content tab.

  5. Choose an Environment to view content views available to those orcharhino 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 APT repositories.

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

  9. Click the vertical ellipsis in the column to the right next to the environment and click Refresh counts to refresh the content counts synchronized on the orcharhino Proxy under Packages.

Configuring SELinux to permit content synchronization on custom ports

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

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

    # semanage port -l | grep ^http_port_t
    http_port_t     tcp      80, 81, 443, 488, 8008, 8009, 8443, 9000
  2. To configure SELinux to permit a port for content synchronization, for example 10011, enter a command as follows:

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

Recovering a corrupted repository

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

Optimized Sync

Synchronizes the repository bypassing 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.

Procedure
  1. In the orcharhino management UI, navigate to Content > Products.

  2. Select the product containing the corrupted repository.

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

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

  5. Select the required option and click Sync.

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

CLI procedure
  1. Obtain a list of repository IDs:

    # hammer repository list \
    --organization "My_Organization"
  2. Synchronize a corrupted repository using the necessary option:

    • For the optimized synchronization:

      # hammer repository synchronize \
      --id My_ID
    • For the complete synchronization:

      # hammer repository synchronize \
      --id My_ID \
      --skip-metadata-check true
    • For the validate content synchronization:

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

Republishing repository metadata

You can republish repository metadata when a repository distribution does not have the content that should be distributed based on the contents of the repository.

Use this procedure with caution. ATIX AG recommends a complete repository sync or publishing a new content view version to repair broken metadata.

Procedure
  1. In the orcharhino management 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.

    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.

Republishing content view metadata

Use this procedure to republish content view metadata.

Procedure
  1. In the orcharhino management 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 vertical ellipsis icon.

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

Adding an HTTP proxy

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

To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Procedure
  1. In the orcharhino management UI, navigate to Infrastructure > HTTP Proxies and select New HTTP Proxy.

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

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

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

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

  6. Click the Locations tab and add a location.

  7. Click the Organization tab and add an organization.

  8. Click Submit.

CLI procedure
  • On orcharhino Server, enter the following command to add an HTTP proxy:

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

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

Changing the HTTP proxy policy for a product

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

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

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

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

  3. Select an HTTP Proxy Policy from the list:

    • Global Default: Use the global default proxy setting.

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

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

  4. Click Update.

Changing the HTTP proxy policy for a repository

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

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

Procedure
  1. In the orcharhino management UI, navigate to Content > Products and click the name of the Product that contains the repository.

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

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

  4. Select an HTTP Proxy Policy from the list:

    • Global Default: Use the global default proxy setting.

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

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

  5. Click Save.

CLI procedure
  • On orcharhino Server, enter the following command, specifying the HTTP proxy policy you want to use:

    # hammer repository update \
    --http-proxy-policy HTTP_Proxy_Policy \
    --id Repository_ID

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

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

    • global_default_http_proxy: Use the global default proxy setting.

    • use_selected_http_proxy: Specify an HTTP proxy using either --http-proxy My_HTTP_Proxy_Name or --http-proxy-id My_HTTP_Proxy_ID. To add a new HTTP proxy to orcharhino, see Adding an HTTP Proxy.

Creating a sync plan

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

To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Procedure
  1. In the orcharhino management UI, navigate to Content > Sync Plans and click New Sync Plan.

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

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

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

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

  6. Click Save.

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

    # hammer sync-plan create \
    --description "My_Description" \
    --enabled true \
    --interval daily \
    --name "My_Products" \
    --organization "My_Organization" \
    --sync-date "2023-01-01 01:00:00"
  2. View the available sync plans for an organization to verify that the sync plan has been created:

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

Assigning a sync plan to a product

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

To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Procedure
  1. In the orcharhino management UI, navigate to Content > Products.

  2. Select a product.

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

CLI procedure
  1. Assign a sync plan to a product:

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

Assigning a sync plan to multiple products

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

Procedure
  1. Run the following Bash script:

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

Best practices for sync plans

  • Add sync plans to products and regularly synchronize content to keep the load on orcharhino 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 tool.

Table 1. Cron expression examples
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

Limiting synchronization concurrency

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

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

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

Synchronizing Ubuntu Extended Life Support Content

Canonical provides Ubuntu Extended Security Maintenance (ESM) repositories for their paying customers. Use orcharhino to synchronize ESM repositories from Canonical to distribute content to your managed hosts running Ubuntu 14.04 and Ubuntu 16.04.

Extract the ESM repository information from an existing host running Ubuntu 14.04 or 16.04 once by hand to enable synchronization to orcharhino.

Providing Ubuntu ESM repositories to managed hosts running Ubuntu 14.04 or 16.04 requires a subscription from Canonical. Ensure to provide valid licenses for all used Canonical products. Using insufficient, invalid, or otherwise inadequate licenses might violate your terms with Canonical.

For more information on how to use Ubuntu ESM, see Synchronizing Ubuntu Extended Life Support Content.

One time procedure on an existing host
  1. Install ubuntu-advantage-tools on a host running Ubuntu 14.04 or 16.04:

    # apt-get install -y ubuntu-advantage-tools
  2. Register your host with Canonical:

    # ua attach ABCDEF0123456789

    Use the code from canonical.com.

  3. Extract the Upstream URL, Releases, Components, and Architectures from the ESM repository:

    # cat /etc/apt/sources.list.d/ubuntu-esm-infra.list
  4. Extract user name and password:

    # cat /etc/apt/auth.conf.d/90ubuntu-advantage
Procedure on orcharhino
  1. Add GPG public key to orcharhino:

    1. Navigate to Content > Content Credentials.

    2. Click Create Content Credential.

    3. Enter a name and the GPG public key for Ubuntu.

      Ensure to use ASCII-armored GPG keys. Convert the key if necessary:

      # gpg --import ubuntu-advantage-esm-infra-trusty.gpg
      # gpg --export --armor 4067E40313CB4B13
    4. Click Save to save your content credential to orcharhino.

  2. Create a product:

    1. Navigate to Content > Products.

    2. Click Create Product.

      1. Enter a Name, select the previously imported GPG public key, and optionally add a sync plan and description.

      2. Click Save to save the product to orcharhino.

    3. Navigate to Content > Products.

    4. Select the previously created product.

    5. Click New Repository.

      1. Enter a Name and select type deb.

      2. Enter the Upstream URL, Releases, Components, and Architectures as extracted from your host from /etc/apt/sources.list.d/ubuntu-esm-infra.list.

      3. Enter the Upstream Username and Upstream Password as extracted from your host from /etc/apt/auth.conf.d/90ubuntu-advantage.

      4. Enter Errata URL: https://dep.atix.de/dep/api/v1/ubuntu-esm.

      5. Click Save to save your repository to orcharhino.

  3. Synchronize your product.

    1. Navigate to Content > Products.

    2. Select the previously created product.

    3. Click Sync Now from the actions drop down menu.

  4. Distribute and manage your content as you manage other .deb content.

GPG Keys for Ubuntu

You can download the official GPG public keys from ubuntu.com:

  • Ubuntu 24.04 (Noble)

    You need the following ASCII-armored GPG keys which can be retrieved and exported with the following commands:

    $ gpg --keyserver keyserver.ubuntu.com --recv-key F6ECB3762474EDA9D21B7022871920D1991BC93C
    $ gpg --armor --export F6ECB3762474EDA9D21B7022871920D1991BC93C > ubuntu_2404_gpg_keys.txt
  • Ubuntu 22.04 (Jammy)

    You need the following ASCII-armored GPG keys which can be retrieved and exported with the following commands:

    $ gpg --keyserver keyserver.ubuntu.com --recv-key 871920D1991BC93C
    $ gpg --armor --export 871920D1991BC93C > ubuntu_2204_gpg_keys.txt
  • Ubuntu 20.04 (Focal)

    You need the following ASCII-armored GPG keys which can be retrieved and exported with the following commands:

    $ gpg --keyserver keyserver.ubuntu.com --recv-key 3B4FE6ACC0B21F32 D94AA3F0EFE21092 871920D1991BC93C
    $ gpg --armor --export 3B4FE6ACC0B21F32 D94AA3F0EFE21092 871920D1991BC93C > ubuntu_2004_gpg_keys.txt
  • Ubuntu 18.04 (Bionic)

    You need the following ASCII-armored GPG keys which can be retrieved and exported with the following commands:

    $ gpg --keyserver keyserver.ubuntu.com --recv-key 871920D1991BC93C 3B4FE6ACC0B21F32
    $ gpg --armor --export 871920D1991BC93C 3B4FE6ACC0B21F32 > ubuntu_1804_gpg_keys.txt
  • Ubuntu 16.04 (Xenial)

    You need the following ASCII-armored GPG keys which can be retrieved and exported with the following commands:

    $ gpg --keyserver keyserver.ubuntu.com --recv-key 0BFB847F3F272F5B 40976EAF437D05B5 46181433FBB75451 3B4FE6ACC0B21F32 D94AA3F0EFE21092
    $ gpg --armor --export 0BFB847F3F272F5B 40976EAF437D05B5 46181433FBB75451 3B4FE6ACC0B21F32 D94AA3F0EFE21092 > ubuntu_1604_gpg_keys.txt

You can upload the ubuntu_*_gpg_keys.txt files directly to orcharhino as shown above.

The text and illustrations on this page are licensed by ATIX AG under a Creative Commons Attribution Share Alike 4.0 International ("CC BY-SA 4.0") license. This page also contains text from the official Foreman documentation which uses the same license ("CC BY-SA 4.0").