Products and Repositories

The products page can be accessed via the content menu:

Content > Products

The products page forms a part of orcharhino’s content management.

An orcharhino product is a named collection of one or more repositories. Products are closely associated with subscriptions.

A repository itself is a remote source for (software) content. To be usable, a software repository must be of a type supported by orcharhino. The most general repository type is a file repository, which may contain arbitrary content. Other repository types supported by orcharhino include deb, yum, Puppet, and Docker.

Note

There is a difference between a repository type and a content type. Some repository types may contain more than one type of content. For example, repositories of type yum may contain content of type errata as well as content of type RPM package.

In general repositories can only ever be added to orcharhino as part of some product. This serves to keep the orcharhino user interface tidy.

Once repositories have been added to a product in orcharhino, they need to be synchronized. Synchronization will copy the upstream content of all repositories contained within the product into orcharhino’s local database. Since the underlying (remote) repositories may be subject to change, it may be desirable to synchronize products periodically.

It is also possible to associate products with a GPG key or an SSL certificate to verify signed repositories. The GPG key is used to ensure the integrity of the packages in a repository. The SSL certificates are used to synchronize a third-party repository for which SSL-based authentication is required. In this case, you will probably need to provide an SSL CA certificate, an SSL client certificate, and an appropriate SSL client key. GPG keys and SSL certificates can be added on the content credentials page.

Note

The SSL certificates of a product are inherited to newly created repositories. Assigning or changing SSL certificates does not affect existing repositories. If you want to change SSL certificate, you must change the SSL certificate of the existing repository.


The products page includes a Create Product button, a Repo Discovery button, a Select Action menu and a list of products in orcharhino:

List available products and describe buttons on this view
  • The Create Product button (1) will take you to the create product page.

  • The Repo Discovery button (2) will take you to the repository discovery page.

  • The Select Action menu (3) is used to perform bulk actions on selected products.

  • The list of products (4) contains for each individual product the name, their optional description, information of recent sync results, the assigned sync plan and the number of contained repositories.

  • Clicking on the name of a product in the Name column (5) will take you to the product overview page.

Performing Bulk Actions

It is possible to perform actions on several products at once by selecting the desired products from the first column of the list of products and using the Select Action drop down menu to choose an action as follows:

Bulk actions on the products view
  • The checkbox in the top left corner (1) of the list of products can be used to select (or deselect) all products at once.

  • The Sync Selected action (2) will create a synchronization task for each selected product.

  • The Adcanced Sync action (3) will open the advanced sync window (see below).

  • The Manage Sync Plan action (4) will open the sync plan management window (see below).

  • The Remove action (5) will completely remove the selected products (including any repositories contained within them) from orcharhino. Note that products cannot be removed if any of their repositories are published as part of a content view.

The advanced sync window offers three different synchronization options:

Describe various advanced sync buttons
  • The three options (1), (2), (3) are documented directly within orcharhino.

  • Select the option you want and use the Sync button (4) to create the relevant tasks.

The sync plan management window allows you to add a preexisting sync plan to all selected products or to remove any associated sync plans from them:

Manage sync plans in which upstream content will be synchronized
  • Select the sync plan you want to add or remove from the selected products by clicking on it in the list (1). (The selected sync plan will be shaded in light blue).

  • The Update Sync Plan button (2) will add the selected sync plan to all selected products. You will be asked to confirm this action.

  • The Remove Sync Plan button (3) will remove whatever sync plan is currently associated with each selected product from them. You will be asked to confirm this action.

  • The Done button (4) will close the window (without performing any actions).

Creating a Product

The create products page can be accessed via the content menu:

Content > Products >> Create Product

The create products page includes several input fields and drop down menus:

Creating a product
  • The Name (1) and Label fields (2) are the only required fields. A product is just a named collection of repositories and we have yet to add any repositories. Any spaces in the name will be replaced with underscores for the label, which is used internally and cannot be changed once the product has been created.

  • Products can be associated with various GPG keys and SSL certificates which need to be added to orcharhino separately via the drop down menus provided (3, 4, 5, and 6).

  • Products can be associated with a sync plan via the drop down menu provided (7).

  • You may optionally add a Description (8).

  • The Save button (9) will create the new product and take you to its product overview page with the repositories tab selected. Here, you can use the New Repository button to start adding repositories to your new product.

Creating a Repository

The new repository page can be accessed via the relevant product overview page:

Content > Products >> list of products > Name column > name of a product > New Repository

To create a repository, you must already have created the product that the repository will be placed in.

Note

Using the type docker, file, and Puppet will present slightly less fields than yum and deb.

Using Type yum

The following fields appear when selecting yum as repository type:

Creating a yum repository part 1 Creating a yum repository part 2
  • Writing into the Name field (1) also writes to the Label field (2). Any spaces in the name will be replaced with underscores for the label, which is used internally and cannot be changed once the product has been created.

  • You may add an arbitrary Description (3).

  • Select type yum from the drop down menu (4).

  • The Restrict to Architecture drop down menu (5) allows you to only synchronize architecture specific packages.

  • The Upstream URL field (6) should contain the link to the yum repository.

  • You may choose to ignore different content types by selecting them in the Ignorable Content field (7).

    Note

    Select and deselect items by holding the control key.

  • The Verify SSL checkbox (8) allows you to verify the upstream SSL certificates.

  • The Upstream Username and Upstream Password fields (9 and 10) allow you to authenticate yourself against the repository.

  • The Download Policy drop down menu (11) lists options on how to download content to your orcharhino:

    • On demand indicates that packages are only synchronized when actually requested by hosts. Metadata is always synced automatically. This is not advised for content required to deploy hosts, as there would be various delays during the installation process for required software packages.

    • Background (deprecated) indicates that metadata is synchronized and packages are downloaded in the background. The download process is similar to immediate but rate limited.

    • Immediate indicates that content will be downloaded as soon as it’s available.

  • The Mirror on Sync checkbox (12) allows you to discard no longer provided content when synchronizing a repository.

  • The Http Proxy Policy drop down menu (13) allows you to select a proxy to use when synchronizing content.

  • The Checksum drop down menu (14) allows you to deviate from the default checksum algorithm which might be necessary for RHEL 5 and CentOS 5.

  • Select the Publish via HTTP checkbox (15) if you want your orcharhino repository to be reachable via HTTP. Note that this is a potential security risk.

  • The GPG Key drop down menu (16) allows you to use a GPG key to verify the authenticity of software packages. Refer to the content credentials page for more information.

  • The SSL CA Cert, SSL Client Cert, and SSL Client Key drop down menus (17, 18, and 19) allow you to select SSL certificates to authenticate yourself against the repository. Refer to the content credentials page for more information.

  • Click the Save button (20) to create your repository. Before you can use your new repository, it needs to be synchronized first.

Using Type deb

The following fields appear when selecting deb as repository type:

Creating a deb repository part 1 Creating a deb repository part 2
  • Writing into the Name field (1) also writes to the Label field (2). Any spaces in the name will be replaced with underscores for the label, which is used internally and cannot be changed once the product has been created.

  • You may add an arbitrary Description (3).

  • Select type deb from the drop down menu (4).

  • The Upstream URL field (5) should contain the link to the base of the Debian repository. (This is generally a Debian mirror as found in /etc/apt/sources.list on Debian systems).

  • We generally recommend setting the Releases field (6) explicitly using exactly one entry per orcharhino repository. This prevents you from synchronizing all upstream releases into a single repository, keeping things tidy and avoiding potential performance issues.

  • For official Debian repositories, we recommend setting a codename in the Releases field (6) e.g. stretch for Debian 9, buster for Debian 10, or bullseye for Debian 11. Avoid using stable or testing as they are merely references to a currently corresponding codename. This helps to avoid drastic changes once a new Debian version is released and the reference is changed.

  • For official Ubuntu repositories, the Ubuntu suite (e.g. focal or focal-updates) gives the correct values for the Releases field (6)

  • The Components field (7) 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 we generally recommend leaving this field blank to synchronize all available components. Note that some third party Debian repositories use the components in ways that may require setting an explicit selection.

    Note

    Releases and Components should be entered exactly as they would be in an /etc/apt/sources.list file.

  • The Architectures field (8) allows you to limit the synchronization of packages to a subset of the available architectures. Leave this field blank to synchronize all available architectures.

  • The Errata URL field (9) allows you to make use of the ATIX Debian and Ubuntu Errata Parser service. To do so, point the Errata URL at ATIX’s Debian and Ubuntu Errata Parser server (https://dep.atix.de/dep/api/v1/debian for Debian or https://dep.atix.de/dep/api/v1/ubuntu for Ubuntu).

    Important

    Debian and Ubuntu errata are derived from the Debian security announcements (DSA) and the Ubuntu security notices (USN) respectively. Debian and Ubuntu errata should only be added to Debian and Ubuntu repositories that contain the packages needed to apply the errata. For Debian, such repositories generally require <debian_release>/updates (e.g. buster/updates) as part of their Releases (6). The corresponding requirement for Ubuntu would be <ubuntu_release>-security (e.g. focal-security).

  • The Verify SSL checkbox (10) allows you to verify the upstream SSL certificates.

  • The Upstream Username and Upstream Password fields (11 and 12) allow you to authenticate yourself against the repository.

  • The Mirror on Sync checkbox (13) allows you to discard no longer provided content when synchronizing a repository.

  • The Http Proxy Policy drop down menu (14) allows you to select a proxy to use when synchronizing content.

  • Select the Publish via HTTP checkbox (15) if you want your orcharhino repository to be reachable via HTTP. Note that this is a potential security risk.

  • Add the relevant GPG Key (16) if you wish to verify the signatures of the Release files associated with the Debian repository. Refer to the content credentials page for more information.

  • The SSL CA Cert, SSL Client Cert, and SSL Client Key drop down menus (17, 18, and 19) allow you to select SSL certificates to authenticate yourself against the repository. Refer to the content credentials page for more information.

  • Click the Save button (20) to create your repository. Before you can use your new repository, it needs to be synchronized first.

Discovering Repositories

The repository discovery page can be accessed via the content menu:

Content > Products >> Repo Discovery

Note

Repository discovery currently works only for repositories of type yum. To create repositories of any other type, refer to the creating a repository subsection above.

Repository discovery offers an interactive way to create repositories (as well as products), that differs significantly to the process outlined above. We will use a step by step example to explain repository discovery.

  1. First, we navigate to the repository discovery page, which looks as follows:

    Discover yum repository available on a web URL
  2. Next, we enter the URL (2) of the repositories we wish to discover (https://dl.fedoraproject.org/pub/epel/7/ in our example), making sure we have selected the correct Repository Type (1) (yum repositories in our example), and press the Discover button (3). This will cause any repositories (of the type selected) found at the URL provided to appear as follows:

    Discovery repositories
  3. We can now select any repositories we want (x86_64 in our example) from the list of discovered repositories (1), and hit the Create Selected button (2). This will take us to the following page:

    Set some more options on the discovered repository view
    • In the Product Options area, you may choose existing product or new product from the Product drop down menu (1). (Additional fields will appear if new product is chosen). If existing product was chosen, you can select the product you want your new repository to be added to by using the Name drop down menu (2).

    • Select Serve via HTTP (3) if you want your new repository to be accessible via HTTP. This is a potential security risk, but precludes the need for SSL certificates.

    • Select Verify SSL (4) if you want the upstream repository source to be verified via SSL.

    • You can also adjust the Repository Name (5) and the Repository Label (6) before creating your new repositories. Note that labels cannot be changed after creation.

    • Once you have selected all options as desired, click the Run Repository Creation button (7). This will create any new products and repositories as chosen.

    • New repositories will have to be synchronized.

Viewing a Product

The product overview page can be accessed via the list of products:

Content > Products >> list of products > Name column > name of a product

The product overview page consists of three tabs and a Select Action drop down menu:

Show details of a orcharhino product
  • The Products link (1) will take you back to the products page

  • Selecting Sync Now (4) from the Select Action menu (3) will schedule all repositories associated with the product being viewed for synchronization.

  • Selecting New Sync Plan (5) from the Select Action menu (3) will open a create sync plan window.

  • Selecting Remove Product (6) from the Select Action menu (3) will completely delete the product being viewed. This action is only available if there are no published content view versions with content from this product.

  • The Details tab (7) shows various product properties, most of which can be edited using the edit icons provided. You can also add various content credentials (9) to the product here.

  • There are additional tabs (8) which are discussed further below.


The repositories tab exists to add, remove, or view repositories associated with the product being viewed:

List of repositories within a product
  • The New Repository button (2) will open the new repository page (within the repositories tab).

  • Existing repositories (in the product being viewed) can be synchronized by selecting the desired repositories via the checkboxes provided (1) and then using the Sync Now button (3).

  • Existing repositories (in the product being viewed) can be removed (from the product and by extension orcharhino) by selecting the desired repositories via the checkboxes provided (1) and then using the Remove Repositories button (4).

  • Selecting the name of a repository from the Name column (5) will take you to the repository overview page for that repository.


The tasks tab will list any tasks relating to the product being viewed:

List tasks which have relationship with a product

Viewing a Repository

The repository overview page can be accessed via the relevant product overview page:

Content > Products >> list of products > Name column > name of a product > name of a repository

Repository overview pages contain various information organized into several distinct areas:

Show details of a repository in a product
  • In the Basic Information area (1) you can change most settings of your repository via the edit icons provided.

  • Near the bottom of this area (2) you can edit the content credentials associated with your repository.

  • The Sync Status area (3) displays information on associated sync plans.

  • The link next to Packages (4) in the Content Counts area will take you to the packages subsection for the repository being viewed. (See the following screenshot for more information).

  • The link next to Errata (5) in the Content Counts area will take you to the errata page (filtered by the repository being viewed).

  • In the Upload Package area (6) you can manually upload additional packages to the repository being viewed.

    Note

    Depending on whether the mirror on sync setting is enabled for your repository, manually added packages may be removed with the next sync. Set mirror on sync to no in the basic information area if this is not desired.

  • Selecting Sync Now (8) from the Select Action drop down menu (7) will manually create a synchronization task for the repository being viewed.

  • Selecting Advanced Sync (9) from the Select Action drop down menu (7) will open a window with additional synchronization options.

  • Selecting Republish Repository Metadata (10) from the Select Action drop down menu (7) will recalculate all repository metadata from the actual content of the underlying database.

  • Selecting Remove Repository (11) from the Select Action drop down menu (7) will completely remove the repository being viewed from orcharhino. This action is only possible, if the repository is not currently published to any content views.

You can search the full list of packages contained in a repository on the packages subsection:

List of packages in a repository of a product
  • You can also select arbitrary packages via the checkboxes provided (1) and then remove them from the repository using the Remove Packages button (2).

    Note

    Packages that were manually removed may reappear with the next sync. If you do not want some package published to some content view version, remove it from the underlying repository, and publish the content view before the next sync.