1. Tuning orcharhino Server performance with predefined profiles

If your orcharhino deployment includes a large number of hosts, you can use predefined tuning profiles to configure your orcharhino Server to use the optimal amount of CPU cores and memory. This can help improve orcharhino performance.

1.1. How predefined tuning profiles apply

When you run the orcharhino-installer command with the --tuning option, deployment configuration settings from multiple sources are applied to orcharhino in a specific order. This order defines the priority of these settings.

orcharhino loads tuning configuration settings from the following sources:

Custom Hiera settings

If you use custom Hiera settings on your orcharhino Server, you can find them in the /etc/foreman-installer/custom-hiera.yaml file.

Predefined tuning profile

This is the profile that you select when running the orcharhino-installer command with the --tuning option. The settings for these profiles are defined in the /usr/share/foreman-installer/config/foreman.hiera/tuning/sizes/ directory.

Base tuning profile

The settings for this profile are defined in the /usr/share/foreman-installer/config/foreman.hiera/tuning/common.yaml file.

When merging these settings, orcharhino applies them in the following order:

  • Custom settings in the /etc/foreman-installer/custom-hiera.yaml file override the settings in any predefined profile and the base profile.

  • Predefined profile settings override the settings in the base profile.

1.2. Predefined tuning profiles

The following predefined tuning profiles are available in orcharhino to right-size your orcharhino Server based on the number of hosts your orcharhino manages and available hardware resources.

The predefined tuning profiles are available in the /usr/share/foreman-installer/config/foreman.hiera/tuning/sizes directory. Each profile targets a managed-host range and minimum RAM and CPU cores.

Table 1. Predefined tuning profiles
Tuning profile Number of hosts RAM Number of CPU cores

default

0 – 5000

20G

4

medium

5001 – 10000

32G

8

large

10001 – 20000

64G

16

extra-large

20001 – 60000

128G

32

extra-extra-large

60000+

256G

48+

1.3. Applying a predefined tuning profile

Run orcharhino-installer with the --tuning option to apply a profile. Choosing the right tuning profile helps your orcharhino Server use its CPU cores and memory better.

Note

You cannot use predefined tuning profiles on orcharhino Proxy Servers.
Procedure

  1. If you use a custom-hiera.yaml file on your orcharhino Server, perform the following steps:

    1. Optional: Back up your custom-hiera.yaml file:

      # cp /etc/foreman-installer/custom-hiera.yaml \
/etc/foreman-installer/custom-hiera.original.yaml

      This ensures you can restore the custom-hiera.yaml file to its original state if it becomes corrupted.

    2. Review the definitions of the base tuning profile in /usr/share/foreman-installer/config/foreman.hiera/tuning/common.yaml and the tuning profile that you want to apply in /usr/share/foreman-installer/config/foreman.hiera/tuning/sizes/.

    3. Compare the configuration entries against the entries in your /etc/foreman-installer/custom-hiera.yaml file.

    4. Remove any duplicated configuration settings that you find in custom-hiera.yaml. This ensures the settings in custom-hiera.yaml do not override the settings in the base tuning profile and your chosen predefined tuning profile.

  2. Apply the tuning profile:

    # orcharhino-installer --tuning medium

2. Migrating from internal orcharhino databases to external databases

When you install orcharhino, the orcharhino-installer command installs PostgreSQL databases on the same server as orcharhino. If you are using the default internal databases but want to start using external databases to help with the server load, you can migrate your internal databases to external databases.

2.1. Determining whether your orcharhino Server uses internal or external databases

You can confirm whether your orcharhino Server uses internal or external databases by checking the status of the PostgreSQL database service.

Procedure

  • On orcharhino Server, query the status of your databases:

    # foreman-maintain service status --only postgresql

2.2. PostgreSQL as an external database considerations

Foreman, Katello, and Candlepin use the PostgreSQL database. If you want to use PostgreSQL as an external database, the following information can help you decide if this option is right for your orcharhino configuration. orcharhino supports PostgreSQL version 13.

Advantages of external PostgreSQL

  • Increase in free memory and free CPU on orcharhino

  • Flexibility to set shared_buffers on the PostgreSQL database to a high number without the risk of interfering with other services on orcharhino

  • Flexibility to tune the PostgreSQL server’s system without adversely affecting orcharhino operations

Disadvantages of external PostgreSQL

  • Increase in deployment complexity that can make troubleshooting more difficult

  • The external PostgreSQL server is an additional system to patch and maintain

  • If either orcharhino or the PostgreSQL database server suffers a hardware or storage failure, orcharhino is not operational

  • If there is latency between the orcharhino server and database server, performance can suffer

2.3. Installing PostgreSQL as an external database

Install and configure PostgreSQL on a dedicated host if you want to use an external database with your orcharhino Server.

orcharhino supports PostgreSQL version 13.

Prerequisites

  • The prepared host has base operating system repositories enabled.

  • The prepared host has sufficient disk space available for the /var/lib/pgsql directory. The expected installation size is 100 MB and the expected runtime size is 20 GB.

Procedure

  1. On your new database server, install PostgreSQL:

    # dnf install postgresql-server postgresql-contrib

  2. Initialize the PostgreSQL database:

    # postgresql-setup --initdb

  3. Edit the /var/lib/pgsql/data/postgresql.conf file:

    # vi /var/lib/pgsql/data/postgresql.conf

    Note that the default configuration of external PostgreSQL needs to be adjusted to work with orcharhino. The base recommended external database configuration adjustments are as follows:

    • checkpoint_completion_target: 0.9

    • max_connections: 500

    • shared_buffers: 512MB

    • work_mem: 4MB

  4. Remove the # and edit to listen to inbound connections:

    listen_addresses = '*'

  5. Add the following line to the end of the file to use SCRAM for authentication:

    password_encryption=scram-sha-256

  6. Edit the /var/lib/pgsql/data/pg_hba.conf file:

    # vi /var/lib/pgsql/data/pg_hba.conf

  7. Add the following line to the file:

      host  all   all   orcharhino_ip/32   scram-sha-256

  8. Start and enable the PostgreSQL service:

    # systemctl enable --now postgresql

  9. Update the firewall configuration. For example, using the firewall-cmd command:

    1. Open the postgresql port:

      # firewall-cmd --add-service=postgresql

    2. Make the changes persistent:

      # firewall-cmd --runtime-to-permanent

  10. Switch to the postgres user and start the PostgreSQL client:

    $ su - postgres -c psql

  11. Create three databases and dedicated roles: one for Foreman, one for Candlepin, and one for Pulp:

    CREATE USER "foreman" WITH PASSWORD 'Foreman_Password';
CREATE DATABASE foreman OWNER foreman;
CREATE USER "candlepin" WITH PASSWORD 'Candlepin_Password';
CREATE DATABASE candlepin OWNER candlepin;
CREATE USER "pulp" WITH PASSWORD 'Pulpcore_Password';
CREATE DATABASE pulpcore OWNER pulp;

  12. Exit the postgres user:

    # \q
Verification

  • From orcharhino Server, test that you can access the database:

    # PGPASSWORD='Foreman_Password' pg_isready --host=postgres.example.com --port=5432 --username=foreman --dbname=foreman
# PGPASSWORD='Candlepin_Password' pg_isready --host=postgres.example.com --port=5432 --username=candlepin --dbname=candlepin
# PGPASSWORD='Pulpcore_Password' pg_isready --host=postgres.example.com --port=5432 --username=pulp --dbname=pulpcore

    If the connection succeeded, this displays an accepting connections message.

2.4. Migrating to external databases

Back up and transfer existing data, then use the orcharhino-installer command to configure orcharhino to connect to an external PostgreSQL database server.

Prerequisites

  • You have installed and configured a PostgreSQL server on an external server.

Procedure

  1. On orcharhino Server, stop all orcharhino services except for PostgreSQL:

    # foreman-maintain service stop --exclude postgresql

  2. Create your target directory for the orcharhino backup:

    # mkdir /var/My_Migration_Backup_Directory

  3. Back up the internal databases:

    # foreman-maintain backup online \
--preserve-directory \
--skip-pulp-content \
/var/My_Migration_Backup_Directory

  4. Transfer the data to the new external databases:

    PGPASSWORD='Foreman_Password' pg_restore --host=postgres.example.com --username=foreman --dbname=foreman < /var/My_Migration_Backup_Directory/foreman.dump
PGPASSWORD='Candlepin_Password' pg_restore --host=postgres.example.com --username=candlepin --dbname=candlepin < /var/My_Migration_Backup_Directory/candlepin.dump
PGPASSWORD='Pulpcore_Password' pg_restore --host=postgres.example.com --username=pulp --dbname=pulpcore < /var/My_Migration_Backup_Directory/pulpcore.dump

  5. Use the orcharhino-installer command to update orcharhino to point to the new databases:

    # orcharhino-installer \
--katello-candlepin-manage-db false \
--katello-candlepin-db-host postgres.example.com \
--katello-candlepin-db-name candlepin \
--katello-candlepin-db-user candlepin \
--katello-candlepin-db-password Candlepin_Password \
--foreman-proxy-content-pulpcore-manage-postgresql false \
--foreman-proxy-content-pulpcore-postgresql-host postgres.example.com \
--foreman-proxy-content-pulpcore-postgresql-db-name pulpcore \
--foreman-proxy-content-pulpcore-postgresql-user pulp \
--foreman-proxy-content-pulpcore-postgresql-password Pulpcore_Password \
--foreman-db-manage false \
--foreman-db-host postgres.example.com \
--foreman-db-database foreman \
--foreman-db-username foreman \
--foreman-db-password Foreman_Password

  6. Remove the PostgreSQL package on orcharhino Server:

    # dnf remove postgresql-server

  7. Remove the PostgreSQL data directory:

    # rm -fr /var/lib/pgsql/data

3. Preparing for disaster recovery and recovering from data loss

ATIX AG recommends preparing a disaster recovery plan to ensure the continuity of orcharhino services in case of a disruptive event. These guidelines help ensure that you will be able to restore your orcharhino deployment to an operational state after an incident.

Choose a disaster recovery plan that best helps ensure the continuity of orcharhino services in your deployment.

Snapshots of virtualized orcharhino Server
How do I back up?

Virtualize your orcharhino Server and use the hypervisor tools to take virtual machine snapshots of the server. This method is suitable if you can run orcharhino in a virtual machine.

How will I recover in case of a disruptive event?

To recover orcharhino services, restore a virtual machine snapshot.

Disadvantages and expected impact

Expect some amount of data inconsistency after recovery, based on how old your last snapshot is. You will lose data changes that have occurred since the snapshot you are using to recover was taken.

Active and passive orcharhino Server, with external storage
How do I back up?

Store the following critical data on network attached storage: content in /var/lib/pulp and database in /var/lib/pgsql. Replicate this storage into a different data center. Attach the storage to a orcharhino Server that is a clone of the primary orcharhino Server but runs passively.

How will I recover in case of a disruptive event?

To recover orcharhino services, switch DNS records of the active orcharhino Server with the passive orcharhino Server. This ensures that the passive server becomes the active server. All hosts remain connected without configuration updates.

Disadvantages and expected impact

If the network attached storage is replicated to another location, expect some amount of data inconsistency after recovery based on the synchronization interval.

Active and passive orcharhino Server, with backup and restore
How do I back up?

Ensure periodic backups of your orcharhino Server. Copy this backup to a passive orcharhino Server and restore it on the passive server.

How will I recover in case of a disruptive event?

To recover orcharhino services, switch DNS records of the active orcharhino Server with the passive orcharhino Server. This ensures that the passive server becomes the active server. All hosts remain connected without configuration updates.

Disadvantages and expected impact

Expect some amount of data inconsistency after recovery, based on how often you took and restored backups and on how long it takes to complete the restore process.

Dual active orcharhino Server
How do I back up?

Operate an active, independent orcharhino Server per data center. Hosts from each data center are registered to the orcharhino Server in that data center. Then configure automation to ensure recovery in case of a disruptive event. For example, you can periodically run a health check and if the health check discovers that the current orcharhino Server a host is registered to does not resolve, the host is re-registered to the other orcharhino Server.

To minimize downtime, you can automate the recovery in various ways. For example, you can use the orcharhino Ansible collection. For more information, see Using the orcharhino Ansible Collection.

How will I recover in case of a disruptive event?

To recover orcharhino services, re-register all hosts to the orcharhino Server in the other data center.

Disadvantages and expected impact

You must ensure that content synchronization and content view creation are synchronized to create the same content view in each orcharhino and prevent content drift. Content drift occurs when available content deviates from the intended state defined by a content view. If you fail to prevent content drift, expect inconsistency in the content that is available to hosts.

3.2. Disaster recovery by virtualizing your orcharhino Server

If you virtualize your orcharhino Server and ensure that you take regular snapshots of the virtual machine (VM), you can respond to various disaster scenarios by restoring your orcharhino deployment from one of your snapshots.

Note

The details for how to implement this scenario depend on your choice of a virtualization platform. Due to the variety of different hypervisors and their capabilities, ATIX AG does not provide detailed instructions for any specific virtualization platform.

3.2.1. Preparing for disaster recovery by virtualizing your orcharhino Server

Implement a reliable process for regularly taking VM snapshots of your virtualized orcharhino Server and for backing up your snapshots for long-term storage.

Prerequisites
Procedure

  1. Define a schedule for taking periodic snapshots of your virtualized orcharhino Server. Consider your tolerance for potential data loss: Taking snapshots frequently will result in smaller amounts of data loss in case of a disaster. However, creating a snapshot takes time, and the snapshots also require storage space.

  2. Define your snapshot retention policy. Consider how many snapshots you want to store: Regularly removing outdated snapshots helps optimize storage usage.

  3. Using your hypervisor, schedule periodic snapshots of your orcharhino Server.

  4. Schedule periodic backups of the snapshots to prevent data loss in case of hypervisor failure.

    Note

    While snapshots provide quick recovery points, backing up your snapshots gives you the ability for long-term storage and provides extra safety in case of a disaster on the side of your hypervisor.

  5. If you are using an external database that runs on a different machine than your orcharhino Server, create snapshots and backups on the same schedule as your orcharhino Server.

Verification

  1. Verify that your hypervisor takes the snapshots according to the schedule that you defined.

  2. Use the latest snapshot of your orcharhino Server and restore it in an isolated environment.

  3. To verify that you will be able to restore orcharhino services in case of a disaster, assess the functionality of the test orcharhino Server. For more information, see Retrieving the status of services by using Hammer CLI.

  4. Perform these verification checks regularly.

3.2.2. Recovering from disaster by restoring a VM snapshot of orcharhino Server

In case of a disaster, use a virtual machine (VM) snapshot of your orcharhino Server to restore orcharhino services.

Important

Ensure that the hostname of your orcharhino Server does not change during recovery. The IP address can change.
Procedure

  1. Identify the snapshot from which you want to recover.

  2. Use hypervisor tools to restore from the selected snapshot.

  3. If you are using an external database that runs on a different machine than your orcharhino Server, ensure that you restore the database from a snapshot taken at the same time as or before the orcharhino Server snapshot.

  4. Update DNS records so that the orcharhino Server hostname resolves to the new IP address. This redirects traffic from the old server to the new server and you will not need to re-register your hosts.

Verification

3.2.3. Retrieving the status of services by using Hammer CLI

orcharhino uses a set of back-end services. When troubleshooting, you can check the status of orcharhino services by using Hammer CLI.

Procedure

  • Get information from the database and orcharhino services:

    $ hammer ping

  • Check the status of the services running in systemd:

    # foreman-maintain service status

    Run foreman-maintain service --help for more information.

  • Perform a health check:

    $ foreman-maintain health check

    Run foreman-maintain health --help for more information.

3.3. Disaster recovery for active and passive orcharhino Server with external storage

To prepare for disaster recovery, you can configure two orcharhino Servers and store critical data externally on shared storage. The primary server is active while the secondary server remains passive. If the primary server fails, the shared storage is attached to your secondary server, which turns the secondary server into your new primary server.

3.3.1. Preparing for disaster recovery with active and passive orcharhino Server with external storage

Create your passive orcharhino Server as a backup of your active orcharhino Server. Ensure that the /var/lib/pulp and /var/lib/pgsql directories on your shared storage are available to both servers.

Prerequisites
Procedure

  1. Replicate the /var/lib/pulp and /var/lib/pgsql directories from the active orcharhino Server to your shared storage.

  2. Back up your active orcharhino Server and restore it on a system that will serve as your passive orcharhino Server. For more information, see Backing up orcharhino and Restoring orcharhino Server or orcharhino Proxy Server from a backup.

  3. Keep the source server powered on. Power off the new server.

    The source server remains your active primary server, while the new server becomes the passive secondary server.

  4. Determine how you want to attach the database content on the shared storage to your passive server:

    • If you mount the storage directly on both your active and passive server, the servers will always see the same, up-to-date content.

    • If you mount the storage only on your active server, the passive server will access the data only if it takes over as the active server.

Verification

Perform this test in an isolated staging environment:

  1. Mimic a full outage on the active server. To make sure the active server is inaccessible, you can turn the machine off, halt the virtual machine (VM) if your server runs on a VM, or isolate the machine by using a firewall.

  2. Switch DNS records of the active server with the DNS records of the passive server.

  3. Verify that your passive server can access the data stored on your shared storage.

  4. Assess the functionality of the test orcharhino Server. For more information, see Retrieving the status of services by using Hammer CLI.

  5. Perform these verification checks regularly.

3.3.2. Recovering from disaster with active and passive server with external storage

If your active orcharhino Server fails, detach it from the shared storage and make sure your passive server can access the data stored on the shared storage. This turns the passive server into your new active server.

Procedure

  1. Verify that the failed active server is powered off or fully detached from the shared storage. This ensures that the failed server cannot keep writing to the shared storage.

  2. Switch DNS records of the active server with the DNS records of the passive server. This ensures that hosts remain connected and you do not need to re-register them.

  3. If your shared storage was mounted on both your active and passive servers, your passive server can already access the data.

  4. If your shared storage was mounted only on your active server, re-mount it on your passive server.

  5. Assess the functionality of your new active orcharhino Server. For more information, see Retrieving the status of services by using Hammer CLI.

3.3.3. Retrieving the status of services by using Hammer CLI

orcharhino uses a set of back-end services. When troubleshooting, you can check the status of orcharhino services by using Hammer CLI.

Procedure

  • Get information from the database and orcharhino services:

    $ hammer ping

  • Check the status of the services running in systemd:

    # foreman-maintain service status

    Run foreman-maintain service --help for more information.

  • Perform a health check:

    $ foreman-maintain health check

    Run foreman-maintain health --help for more information.

3.4. Disaster recovery for active and passive orcharhino Server with backup and restore

To prepare for disaster recovery, you can configure two orcharhino Servers: an active primary server and a passive secondary server. You configure periodic backups of the primary server. If the primary server fails, you can restore a backup on the secondary server to turn it into your new primary server.

3.4.1. Preparing for disaster recovery with active and passive orcharhino Server and backup and restore

Create your passive orcharhino Server by restoring a backup of your active orcharhino Server. Configure periodic backups of the active server.

Prerequisites
Procedure

  1. Define a schedule for periodic offline backups of your active orcharhino Server. Consider your tolerance for potential data loss and your storage options: Taking backups frequently will result in smaller amounts of data loss in case of a disaster, but backups require a significant amount of storage space.

    You can combine full backups with incremental backups. For an example of a cron job that ensures regular backups, see Example of a weekly full backup followed by daily incremental backups.

  2. Schedule periodic offline backups of your active orcharhino Server to be taken according to the schedule you defined. For information about performing backups, see Backing up orcharhino.

  3. Ensure that the backup directories are encrypted and regularly synchronized to a secure location. By default, orcharhino stores the backups in the /var/orcharhino-backup directory.

    Important

    orcharhino Server backups contain sensitive information from the /root/ssl-build directory. For example, they can contain hostnames, ssh keys, request files, and SSL certificates. Encrypting or moving the backups to a secure location helps minimize the risk of damage or unauthorized access to the hosts.

  4. Restore the most recent backup on a system that will serve as your passive orcharhino Server. For information about restoring backups, see Restoring orcharhino Server or orcharhino Proxy Server from a backup.

  5. Optional: Automate backup restoration to keep the passive server periodically updated with the latest backup. A regularly restored passive server helps reduce switchover time if the active server fails.

    Consider how often you want the backups to be restored: More frequent updates reduce potential data loss but increase infrastructure and automation costs.

  6. Power off the passive server. Keep the active server powered on.

  7. Define your backup retention policy. Consider how many backups you want to store: Regularly removing outdated backups helps optimize storage usage.

Verification

  1. Verify that orcharhino takes backups according to the schedule you defined.

  2. Perform further testing steps in an isolated staging environment:

    1. Mimic a full outage on the active server. To make sure the active server is inaccessible, you can turn the machine off, halt the virtual machine (VM) if your server runs on a VM, or isolate the machine by using a firewall.

    2. Switch DNS records of the active server with the DNS records of the passive server.

    3. Assess the functionality of the test orcharhino Server. For more information, see Retrieving the status of services by using Hammer CLI.

    4. Perform these verification checks regularly.

3.4.2. Recovering from disaster with active and passive server and backup and restore

If your active orcharhino Server fails, activate your passive secondary server.

Procedure

  1. Verify that the failed active server is powered off and that backups are no longer being synchronized to your passive server.

  2. Switch DNS records of the active server with the DNS records of the passive server. This ensures that hosts remain connected and you do not need to re-register them.

  3. Assess the functionality of your new active orcharhino Server. For more information, see Retrieving the status of services by using Hammer CLI.

3.4.3. Retrieving the status of services by using Hammer CLI

orcharhino uses a set of back-end services. When troubleshooting, you can check the status of orcharhino services by using Hammer CLI.

Procedure

  • Get information from the database and orcharhino services:

    $ hammer ping

  • Check the status of the services running in systemd:

    # foreman-maintain service status

    Run foreman-maintain service --help for more information.

  • Perform a health check:

    $ foreman-maintain health check

    Run foreman-maintain health --help for more information.

3.4.4. Example of a weekly full backup followed by daily incremental backups

The following script performs a full backup on a Sunday followed by incremental backups for each of the following days. A new subdirectory is created for each day that an incremental backup is performed. The script requires a daily cron job.

#!/bin/bash -e
PATH=/sbin:/bin:/usr/sbin:/usr/bin
DESTINATION=/var/backup_directory
if [[ $(date +%w) == 0 ]]; then
  foreman-maintain backup offline --assumeyes $DESTINATION
else
  LAST=$(ls -td -- $DESTINATION/*/ | head -n 1)
  foreman-maintain backup offline --assumeyes --incremental "$LAST" $DESTINATION
fi
exit 0

Note that the {foreman-maintain backup} command requires /sbin and /usr/sbin directories to be in PATH and the --assumeyes option is used to skip the confirmation prompt.

3.5. Disaster recovery with two active orcharhino Servers

To prepare for disaster recovery, you can configure two orcharhino Servers and operate each server in a different data center. If one of the servers fails, you can re-register all hosts from the failed server to the other server.

3.5.1. Preparing for disaster recovery with two active orcharhino Servers

Create a second orcharhino Server by restoring a backup of your first orcharhino Server. Configure both servers to operate independently in their respective data centers, but ensure that their content does not drift apart over time.

Note

Ansible playbooks can help you automate failover, re-registration, and synchronization. For more information, see Using the orcharhino Ansible Collection.
Prerequisites
Procedure

  1. Back up your orcharhino Server. For more information, see Backing up orcharhino.

  2. Restore the backup on a system that will serve as your other orcharhino Server. For more information, see Restoring orcharhino Server or orcharhino Proxy Server from a backup.

    Note

    Each server must have a distinct hostname and IP address. This enables you to re-register hosts if one of the servers fails.

  3. Ensure that content on your servers remains consistent:

    • If you want both servers to manage content synchronization and content view creation, follow these guidelines to prevent content drift:

      • Regularly synchronize repositories on both servers. You can use the following Ansible modules to automate repository synchronization: theforeman.foreman.repository_sync and theforeman.foreman.sync_plan.

      • Ensure that content views on both servers match.

    • If you want one server to manage content synchronization and content view creation, use one of these features to prevent content drift:

      • If your disaster recovery site has network access to your primary site, use Inter-Server Synchronization (ISS) to ensure your disaster recovery server synchronizes its content from the primary server.

      • If your disaster recovery site does not have network access to your primary site, synchronize content by using export and import.

    • If you want one server to manage only content view creation but not content synchronization, you can configure the other server or multiple other servers to import content views from the first server but synchronize content from repositories.

  4. Register hosts to your servers so that each server manages hosts in its respective data center. For example, register all hosts in My_Data_Center_1 to one orcharhino Server and all hosts in My_Data_Center_2 to the other orcharhino Server.

  5. Automate running the foreman-maintain health check command on both servers. The health check verifies whether the servers remain fully operational.

Verification

Perform this test in an isolated staging environment:

  1. Mimic a full outage on one of your servers. To verify that the server is inaccessible, you can turn the machine off, halt the virtual machine (VM) if your server runs on a VM, or isolate the machine by using a firewall.

  2. Verify that your foreman-maintain health check automation reported an error.

  3. Re-register all hosts from the inaccessible server to the accessible server.

  4. Verify that hosts have been properly re-registered to the accessible server.

  5. Perform these verification checks regularly.

Additional resources

3.5.2. Recovering from disaster with two active orcharhino Servers

If the health checks implemented in Preparing for disaster recovery with two active orcharhino Servers report an issue on one of your orcharhino Servers, it might mean that the server has failed. If the server is down, you must re-register hosts to the other server.

Note

Ansible playbooks can help you automate failover, re-registration, and synchronization. For more information, see Using the orcharhino Ansible Collection.
Procedure

  1. Verify the status of the server:

    $ foreman-maintain health check

  2. If foreman-maintain health check reported a problem, ensure that the server is powered off.

  3. Re-register all hosts from the data center managed by the failed server to the other, functional server.

Verification

  • Verify that hosts have been properly re-registered.

4. Managing users and roles

orcharhino users represent individuals who access your orcharhino and are scoped to organizations and locations. You assign roles to users to control which actions they can perform in your environment.

4.1. Managing orcharhino users

As an administrator, you can create, modify and remove orcharhino users. You can also configure access permissions for a user or a group of users by assigning them different roles.

4.1.1. Creating a user by using orcharhino management UI

Create user accounts from the orcharhino management UI to grant individuals access to your orcharhino environment.

Users are strictly confined to their assigned organizations and locations. Users can only access and assign resources within the organizations and locations they belong to.

Procedure

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

  2. Click Create User.

  3. Enter the account details for the new user.

  4. Click Submit to create the user.

    The user account details that you can specify include the following:

    • On the User tab, select an authentication source from the Authorized by list:

    • On the Organizations tab, select organizations for the user. Select the default organization from the Default on login list. orcharhino uses this organization for the user after login.

    • On the Locations tab, select locations for the user. Select the default location from the Default on login list. orcharhino uses this location for the user after login.

4.1.2. Creating a user by using Hammer CLI

Create user accounts by using Hammer CLI to grant individuals access to your orcharhino environment.

Users are strictly confined to their assigned organizations and locations. Users can only access and assign resources within the organizations and locations they belong to.

Procedure

  • Create a user:

    $ hammer user create \
--auth-source-id My_Authentication_Source \
--login My_User_Name \
--mail My_User_Mail \
--organization-ids My_Organization_ID_1,My_Organization_ID_2 \
--location-ids My_Location_ID_1,My_Location_ID_2 \
--password My_User_Password

    Append --auth-source-id 1 so that the user is authenticated internally. Run hammer auth-source list to get a list of authentication sources. Add the --admin option to grant administrator privileges to the user.

    You can modify the user details later by using the hammer user update command.

4.1.3. Assigning roles to a user by using orcharhino management UI

Assign roles to a user in the orcharhino management UI to control which permissions and resources they can access in your environment.

Procedure

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

  2. Click the username of the user to be assigned one or more roles.

    Note

    If a user account is not listed, check that you are currently viewing the correct organization. To list all the users in orcharhino, click Default Organization and then Any Organization.

  3. Click the Locations tab, and select a location if none is assigned.

  4. Click the Organizations tab, and check that an organization is assigned.

  5. Click the Roles tab to display the list of available roles.

  6. Select the roles to assign from the Roles list.

    To grant all the available permissions, select the Administrator checkbox.

  7. Click Submit.

    To view the roles assigned to a user, click the Roles tab; the assigned roles are listed under Selected items. To remove an assigned role, click the role name in Selected items.

4.1.4. Assigning roles to a user by using Hammer CLI

Assign roles to a user with Hammer CLI to grant the permissions they need to perform tasks in orcharhino.

Procedure

  • Assign roles to a user:

    $ hammer user add-role \
--id My_User_ID \
--role My_Role_Name

4.1.5. Impersonating a different user account

As an administrator, you can impersonate another user by logging on to the orcharhino management UI as that user. Impersonating another user is useful for testing and troubleshooting purposes because you can access exactly what the impersonated user can access in the system, including the same menus.

Audits are created to record the actions that the administrator performs while impersonating another user. However, all actions that an administrator performs while impersonating another user are recorded as having been performed by the impersonated user.

Prerequisites

  • You are logged on to the orcharhino management UI as a user with administrator privileges for orcharhino.

Procedure

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

  2. To the right of the user that you want to impersonate, from the list in the Actions column, select Impersonate.

    When you want to stop the impersonation session, in the upper right of the main menu, click the impersonation icon.

4.1.6. Creating an API-only user

You can create a user account that can interact only with the orcharhino API. This is useful for service accounts or integrations that must not use the orcharhino management UI.

Prerequisites

  • You have created a user and assigned roles to them. Note that this user must be authorized internally. For more information, see Managing users and roles.

Procedure

  1. Log in to your orcharhino as admin.

  2. Navigate to Administer > Users and select a user.

  3. On the User tab, set a password. Do not save or communicate this password with others. You can create pseudo-random strings on your console:

    # openssl rand -hex 32

  4. Create a Personal Access Token for the user. For more information, see Creating a Personal Access Token.

4.2. Managing SSH keys

Add SSH keys to user accounts so orcharhino can deploy those keys during host provisioning.

For information on deploying SSH keys during provisioning, see Deploying SSH keys during provisioning in Provisioning hosts.

4.2.1. Managing SSH keys for a user by using orcharhino management UI

Add or remove SSH keys for a user in the orcharhino management UI to control which keys orcharhino deploys during provisioning.

Prerequisites

  • You are logged in to the orcharhino management UI as an Admin user of orcharhino or a user with the create_ssh_key permission enabled for adding SSH key and destroy_ssh_key permission for removing a key.

Procedure

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

  2. From the Username column, click on the username of the required user.

  3. Click on the SSH Keys tab.

    • To Add SSH key

      1. Prepare the content of the public SSH key in a clipboard.

      2. Click Add SSH Key.

      3. In the Key field, paste the public SSH key content from the clipboard.

      4. In the Name field, enter a name for the SSH key.

      5. Click Submit.

    • To Remove SSH key

      1. Click Delete on the row of the SSH key to be deleted.

      2. Click OK in the confirmation prompt.

4.2.2. Managing SSH keys for a user by using Hammer CLI

Add or remove SSH keys for a user with Hammer CLI to manage which keys orcharhino deploys during provisioning.

Prerequisites

  • You are logged in to the orcharhino management UI as an Admin user of orcharhino or a user with the create_ssh_key permission enabled for adding SSH key and destroy_ssh_key permission for removing a key.

Procedure

  1. To add an SSH key to a user, you must specify either the path to the public SSH key file, or the content of the public SSH key copied to the clipboard:

    • If you have the public SSH key file, enter the following command:

      $ hammer user ssh-keys add \
--user-id user_id \
--name key_name \
--key-file ~/.ssh/id_rsa.pub

    • If you have the content of the public SSH key, enter the following command:

      $ hammer user ssh-keys add \
--user-id user_id \
--name key_name \
--key ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNtYAAABBBHHS2KmNyIYa27Qaa7EHp+2l99ucGStx4P77e03ZvE3yVRJEFikpoP3MJtYYfIe8k 1/46MTIZo9CPTX4CYUHeN8= host@user

  2. To delete an SSH key from a user, enter the following command:

    $ hammer user ssh-keys delete --id key_id --user-id user_id

  3. To view an SSH key attached to a user, enter the following command:

    $ hammer user ssh-keys info --id key_id --user-id user_id

  4. To list SSH keys attached to a user, enter the following command:

    $ hammer user ssh-keys list --user-id user_id

4.3. Managing Personal Access Tokens

Personal Access Tokens allow you to authenticate API requests without using your password. You can set an expiration date for your Personal Access Token and you can revoke it if you decide it should expire before the expiration date.

4.3.1. Creating a Personal Access Token

Create a Personal Access Token to authenticate API requests without sharing your password.

Prerequisites

  • Your user account has a role that grants the create_personal_access_tokens permission.

Procedure

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

  2. Select a user for which you want to create a Personal Access Token.

  3. On the Personal Access Tokens tab, click Add Personal Access Token.

  4. Enter a Name for you Personal Access Token.

  5. Optional: Select the Expires date to set an expiration date. If you do not set an expiration date, your Personal Access Token will never expire unless revoked.

  6. Click Submit. You now have the Personal Access Token available to you on the Personal Access Tokens tab.

    Important

    Ensure to store your Personal Access Token as you will not be able to access it again after you leave the page or create a new Personal Access Token. You can click Copy to clipboard to copy your Personal Access Token.
Verification

  1. Make an API request to your orcharhino Server and authenticate with your Personal Access Token:

    $ curl \
--user My_Username:My_Personal_Access_Token \
https://orcharhino.example.com/api/status

  2. You should receive a response with status 200, for example:

    {"orcharhino_version":"7.10.0","result":"ok","status":200,"version":"3.5.1.10","api_version":2}

    If you go back to Personal Access Tokens tab, you can see the updated Last Used time next to your Personal Access Token.

4.3.2. Revoking a Personal Access Token

Revoke a Personal Access Token before its expiration date when a token is compromised or no longer needed for API access.

Procedure

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

  2. Select a user for which you want to revoke the Personal Access Token.

  3. On the Personal Access Tokens tab, locate the Personal Access Token you want to revoke.

  4. Click Revoke in the Actions column next to the Personal Access Token you want to revoke.

Verification

  1. Make an API request to your orcharhino Server and try to authenticate with the revoked Personal Access Token:

    $ curl \
--user My_Username:My_Personal_Access_Token \
https://orcharhino.example.com/api/status

  2. You receive the following error message:

    {
  "error": {"message":"Unable to authenticate user My_Username"}
}

4.4. Creating and managing user groups

You can manage permissions of several users at once by organizing them into user groups. User groups themselves can be further grouped to create a hierarchy of permissions.

With orcharhino, you can assign permissions to groups of users. You can also create user groups as collections of other user groups. If you use an external authentication source, you can map orcharhino user groups to external user groups as described in Managing external user groups in Configuring authentication for orcharhino users.

User groups are defined in an organizational context, meaning that you must select an organization before you can access user groups.

4.4.1. Creating a user group by using orcharhino management UI

Create a user group in the orcharhino management UI and define which roles the group will have.

Procedure

  1. In the orcharhino management UI, navigate to Administer > User Groups.

  2. Click Create User group.

  3. On the User Group tab, specify the name of the new user group and select group members:

    • Select the previously created user groups from the User Groups list.

    • Select users from the Users list.

  4. On the Roles tab, select the roles you want to assign to the user group. Alternatively, select the Admin checkbox to assign all available permissions.

  5. Click Submit.

4.4.2. Creating a user group by using Hammer CLI

Create a user group by using Hammer CLI and define which roles the group will have.

Procedure

  • Create a user group:

    $ hammer user-group create \
--name My_User_Group_Name \
--role-ids My_Role_ID_1,My_Role_ID_2 \
--user-ids My_User_ID_1,My_User_ID_2

4.4.3. Removing a user group

Remove a user group from orcharhino when you no longer need it or when you want to reorganize how permissions are assigned.

Procedure

  1. In the orcharhino management UI, navigate to Administer > User Groups.

  2. Click Delete to the right of the user group you want to delete.

  3. Click Confirm to delete the user group.

5. Creating and managing roles

Roles define a set of permissions and access levels through permission filters. Assign roles to users and user groups to control which actions they can perform in your environment.

5.1. Creating a role by using orcharhino management UI

Create a role by using the orcharhino management UI. You can add permissions to the role to control which actions users can perform.

Procedure

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

  2. Click Create Role.

  3. Provide a Name for the role.

  4. Click Submit to save your new role.

Next steps

  • Add permissions to the role. To serve its purpose, a role must contain permissions.

5.2. Creating a role by using Hammer CLI

Create a role by using Hammer CLI. You can add permissions to the role to control which actions users can perform.

Procedure

  • Create a role:

    $ hammer role create --name My_Role_Name
Next steps

  • Add permissions to the role. To serve its purpose, a role must contain permissions.

5.3. Cloning a role

Clone an existing role in the orcharhino management UI to quickly create a new role with similar permissions. You can edit the cloned role to customize permissions for your environment.

Procedure

  1. In the orcharhino management UI, navigate to Administer > Roles and select Clone from the drop-down menu to the right of the required role.

  2. Provide a Name for the role.

  3. Click Submit to clone the role.

  4. Click the name of the cloned role and navigate to Filters.

  5. Edit the permissions as required.

  6. Click Submit to save your new role.

Example 1. Creating an organization-specific manager role

Use the orcharhino management UI to create an administrative role restricted to a single organization named org-1.

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

  2. Clone the existing Organization admin role. Select Clone from the drop-down list next to the Filters button. You are then prompted to insert a name for the cloned role, for example org-1 admin.

  3. Click the desired locations and organizations to associate them with the role.

  4. Click Submit to create the role.

  5. Click org-1 admin, and click Filters to view all associated filters. The default filters work for most use cases. However, you can optionally click Edit to change the properties for each filter. You can also click New filter to associate new filters with this role.

5.4. Adding permissions to a role by using orcharhino management UI

Add permissions to a role in the orcharhino management UI to define which actions users with that role can perform.

Procedure

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

  2. Select Add Filter from the drop-down list to the right of the required role.

  3. Select the Resource type from the drop-down list. The (Miscellaneous) group gathers permissions that are not associated with any resource group.

  4. Click the permissions you want to select from the Permission list.

  5. Click Next.

  6. Click Submit to save changes.

5.5. Adding permissions to a role by using Hammer CLI

Add permissions to a role by using Hammer CLI to define which actions users with that role can perform.

Procedure

  1. List all available permissions:

    $ hammer filter available-permissions

  2. Add permissions to a role:

    $ hammer filter create \
--permission-ids My_Permission_ID_1,My_Permission_ID_2 \
--role My_Role_Name

    For more information about roles and permissions parameters, enter the hammer role --help and hammer filter --help commands.

5.6. Viewing permissions of a role

View the permissions assigned to a role in the orcharhino management UI to verify which actions users with that role can perform.

Procedure

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

  2. Click Filters to the right of the required role to get to the Filters page.

    The Filters page contains a table of permissions assigned to a role grouped by the resource type. It is also possible to generate a complete table of permissions and actions that you can use on your orcharhino system. For more information, see Creating a complete permission table.

5.7. Creating a complete permission table

Generate a complete permission table from the orcharhino console to review all available permissions and actions on your orcharhino.

Prerequisites

  • The foreman-console package is installed on orcharhino Server.

Procedure

  1. Start the orcharhino console:

    # foreman-rake console

  2. Insert the following code into the console:

    f = File.open('/tmp/table.html', 'w')

result = Foreman::AccessControl.permissions {|a,b| a.security_block <=> b.security_block}.collect do |p|
      actions = p.actions.collect { |a| "<li>#{a}</li>" }
      "<tr><td>#{p.name}</td><td><ul>#{actions.join('')}</ul></td><td>#{p.resource_type}</td></tr>"
end.join("\n")

f.write("<table border=\"1\"><tr><td>Permission name</td><td>Actions</td><td>Resource type</td></tr>\n")
f.write(result)
f.write("</table>\n")

    The above syntax creates a table of permissions and saves it to the /tmp/table.html file.

  3. Press Ctrl + D to exit the orcharhino console.

  4. Open /tmp/table.html in a web browser to view the table.

5.8. Removing a role

You can remove a role from the orcharhino management UI if you no longer need it to grant permissions to users.

Procedure

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

  2. Select Delete from the drop-down list to the right of the role to be deleted.

  3. Click Confirm to delete the role.

5.9. Predefined roles available in orcharhino

Review predefined roles in orcharhino to understand which permissions each role grants before assigning roles to users.

For a complete set of predefined roles and the permissions they grant, log in to orcharhino management UI as the privileged user and navigate to Administer > Roles. For more information, see Viewing permissions of a role.

Predefined role Permissions the role provides Additional information

Auditor

View the Audit log.

Default role

View tasks and jobs invocations.

orcharhino automatically assigns this role to every user in the system.

Manager

View and edit global settings.

Organization admin

All permissions except permissions for managing organizations.

An administrator role defined per organization. The role has no visibility into resources in other organizations.

By cloning this role and assigning an organization, you can delegate administration of that organization to a user.

Site manager

View permissions for various items.

Permissions to manage hosts in the infrastructure.

A restrained version of the Manager role.

System admin

Edit global settings in Administer > Settings.

View, create, edit, and destroy users, user groups, and roles.

View, create, edit, destroy, and assign organizations and locations but not view resources within them.

Users with this role can create users and assign all roles to them. Give this role only to trusted users.

Viewer

View the configuration of every element of the orcharhino structure, logs, reports, and statistics.

5.10. Granular permission filtering

With granular permission filters, you can limit permissions of a user to selected instances of a resource type.

5.10.1. Creating a granular permission filter by using orcharhino management UI

Create a granular permission filter in the orcharhino management UI to limit role permissions to specific resource instances.

orcharhino does not apply search conditions to create actions. For example, limiting the create_locations action with name = "Default Location" expression in the search field does not prevent the user from assigning a custom name to the newly created location.

Procedure

  1. Specify a query in the Search field on the Edit Filter page. Queries have the following form:

    field_name operator value

    • field_name marks the field to be queried. The range of available field names depends on the resource type. For example, the Partition Table resource type offers family, layout, and name as query parameters.

    • operator specifies the type of comparison between field_name and value. See Supported operators for granular search for an overview of applicable operators.

    • value is the value used for filtering. This can be for example a name of an organization. Two types of wildcard characters are supported: underscore (_) provides single character replacement, while percent sign (%) replaces zero or more characters.

      Note

      For most resource types, the Search field provides a drop-down list suggesting the available parameters. This list appears after placing the cursor in the search field. For many resource types, you can combine queries using logical operators such as and, not and has operators.

5.10.2. Creating a granular permission filter by using Hammer CLI

Create a granular permission filter by using Hammer CLI to limit role permissions to specific resource instances.

orcharhino does not apply search conditions to create actions. For example, limiting the create_locations action with name = "Default Location" expression in the search field does not prevent the user from assigning a custom name to the newly created location.

Procedure

  • To create a granular filter, enter the hammer filter create command with the --search option to limit permission filters, for example:

    $ hammer filter create \
--permission-ids 91 \
--search "name ~ ccv*" \
--role qa-user

    This command adds to the qa-user role a permission to view, create, edit, and destroy content views that only applies to content views with name starting with ccv.

5.10.3. Examples of using granular permission filters

As an administrator, you can allow selected users to make changes in a certain part of the environment path. For example, you can allow users to work with content while it is in the development stage of the application lifecycle, but not once the content is pushed to production.

The following query applies any permissions specified for the Host resource type only to hosts in the group named host-editors:

hostgroup = host-editors

The following query returns records where the name matches XXXX, Yyyy, or zzzz example strings:

name ^ (XXXX, Yyyy, zzzz)

You can also limit permissions to a selected environment. To do so, specify the environment name in the Search field, for example:

Dev

5.10.4. Supported operators for granular search

You can use logical and symbolic operators to build precise search queries when limiting user permissions.

Table 2. Logical operators

Operator

Description

and

Combines search criteria.

not

Negates an expression.

has

Object must have a specified property.
Table 3. Symbolic operators

Operator

Description

=

Is equal to. An equality comparison that is case-sensitive for text fields.

!=

Is not equal to. An inversion of the = operator.

~

Like. A case-insensitive occurrence search for text fields.

!~

Not like. An inversion of the ~ operator.

^

In. An equality comparison that is case-sensitive search for text fields. This generates a different SQL query to the Is equal to comparison, and is more efficient for multiple value comparison.

!^

Not in. An inversion of the ^ operator.

>, >=

Greater than, greater than or equal to. Supported for numerical fields only.

<, ⇐

Less than, less than or equal to. Supported for numerical fields only.

6. Configuring email notifications

Email notifications are created by orcharhino Server periodically or after completion of certain events. The periodic notifications can be sent daily, weekly or monthly.

Users do not receive any email notifications by default. An administrator can configure users to receive notifications based on criteria such as the type of notification, and frequency.

Important

orcharhino Server does not enable outgoing emails by default, therefore you must review your email configuration.

6.1. Email notification types

You can configure orcharhino to send email notifications for system events such as host builds, errata updates, content synchronization failures, and audit summaries to stay informed about important activities in your environment.

Audit summary

A summary of all activity audited by orcharhino Server.

Compliance policy summary

A summary of OpenSCAP policy reports and their results.

Content view promote failure

A notification sent after content view promotion fails.

Content view publish failure

A notification sent after content view publication fails.

Host built

A notification sent after a host is built.

Host errata advisory

A summary of applicable and installable errata for hosts managed by the user.

orcharhino Proxy sync failure

A notification sent after orcharhino Proxy synchronization fails.

Promote errata

A notification sent only after a content view promotion. It contains a summary of errata applicable and installable to hosts registered to the promoted content view. This allows a user to monitor what updates have been applied to which hosts.

Repository sync failure

A notification sent after repository synchronization fails.

Sync errata

A notification sent only after synchronizing a repository. It contains a summary of new errata introduced by the synchronization.

For a complete list of email notification types, navigate to Administer > Users in the orcharhino management UI, click the Username of the required user, and select the Email Preferences tab.

6.2. Configuring email notification preferences

You can configure orcharhino to send email messages to individual users registered to orcharhino. orcharhino sends the email to the email address that has been added to the account, if present.

Users can edit the email address by clicking on their name in the top right of the orcharhino management UI and selecting My account.

Note

If you want to send email notifications to a group email address instead of an individual email address, create a user account with the group email address and minimal orcharhino permissions, then subscribe the user account to the desired notification types.
Prerequisites

  • The user you are configuring to receive email notifications has a role with this permission: view_mail_notifications.

Procedure

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

  2. Click the Username of the user you want to edit.

  3. On the User tab, verify the value of the Mail field. Email notifications will be sent to the address in this field.

  4. On the Email Preferences tab, select Mail Enabled.

  5. Select the notifications you want the user to receive using the drop-down menus next to the notification types.

    Note

    The Audit Summary notification can be filtered by entering the required query in the Mail Query text box.

  6. Click Submit.

    The user will start receiving the notification emails.

6.3. Testing email delivery

To verify the delivery of emails, send a test email to a user. If the email gets delivered, the settings are correct.

Procedure

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

  2. Click on the username.

  3. On the Email Preferences tab, click Test email.

    A test email message is sent immediately to the user’s email address.

Verification

  • If the email is delivered, the verification is complete.

Troubleshooting

  • If the email is not delivered, perform the following diagnostic steps:

    1. Verify the user’s email address.

    2. Verify orcharhino Server’s email configuration.

    3. Examine firewall and mail server logs.

    4. If your orcharhino Server uses the Postfix service for email delivery, the test email might be held in the queue. To verify, enter the mailq command to list the current mail queue. If the test email is held in the queue, mailq displays the following message:

      postqueue: warning: Mail system is down -- accessing queue directly
-Queue ID-  --Size-- ----Arrival Time---- -Sender/Recipient-------
BE68482A783    1922 Thu Oct  3 05:13:36  orcharhino-noreply@example.com

      To fix the problem, start the Postfix service on your orcharhino Server:

      # systemctl start postfix

6.4. Testing email notifications

To verify that users are correctly subscribed to notifications, trigger the notifications manually.

This triggers all notifications scheduled for the specified frequency for all subscribed users. If every subscribed user receives the notifications, the verification succeeds.

Note

Sending manually triggered notifications to individual users is currently not supported.
Procedure

  • Trigger email notifications:

    # foreman-rake reports:_My_Frequency_

    Replace My_Frequency with one of the following:

  • daily

  • weekly

  • monthly

6.5. Changing email notification settings for a host

You can enable or disable email notifications for a host to control whether its events trigger alerts. orcharhino sends these notifications to the registered owner of the host.

You can configure orcharhino to send email notifications either to an individual user or a user group. When set to a user group, all group members who are subscribed to the email type receive a message.

Receiving email notifications for a host can be useful, but also overwhelming if you are expecting to receive frequent errors, for example, because of a known issue or error you are working around.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > All Hosts, locate the host that you want to view, and click Edit in the Actions column.

  2. Go to the Additional Information tab. If the checkbox Include this host within orcharhino reporting is checked, then the email notifications are enabled on that host.

  3. Optional: Toggle the checkbox to enable or disable the email notifications.

    Note

    If you want to receive email notifications, ensure that you have an email address set in your user settings.

7. Backing up orcharhino

You can back up your orcharhino deployment to ensure the continuity of your orcharhino deployment and associated data in case a disaster occurs. If your deployment uses custom configurations, you must consider how to handle these custom configurations when you plan your backup and disaster recovery policy.

7.1. Planning orcharhino backup

Backing up your orcharhino Server and orcharhino Proxy Server requires you to plan scheduling, storage, and security so you avoid disruption and protect sensitive data.

7.1.1. Available backup methods

Choose an offline backup method based on how long you can keep orcharhino services unavailable and how much time you can allocate for the backup.

Offline backup

All orcharhino services are stopped during an offline backup to ensure data consistency.

For more details, read help information for the offline backup:

# foreman-maintain backup offline --help
Online backup

Only orcharhino services that affect the consistency of the backup, including all background workers, are shut down while the backup process is running. Online backups check for consistency and require more time than offline backups.

For more details, read help information for the online backup:

# foreman-maintain backup online --help

7.1.2. Best practices for backing up orcharhino

Apply these recommendations when scheduling and storing backups so you protect sensitive data and avoid conflicts with other administrators.

  • ATIX AG recommends backing up orcharhino to a separate storage device on a separate system. The foreman-maintain backup command creates a backup of your orcharhino Server or orcharhino Proxy Server and all associated data.

  • orcharhino services are unavailable during the backup. Coordinate with other administrators to ensure no conflicting tasks run during the backup window.

    Warning

    Request other users of orcharhino Server or orcharhino Proxy Server to save any changes and warn them that orcharhino services are unavailable for the duration of the backup. Ensure no other tasks are scheduled for the same time as the backup.

    You can schedule a backup by using cron.

    Note

    During offline backups, the services are inactive and orcharhino is in a maintenance mode. A firewall rejects traffic from outside on port 443 to ensure there are no modifications triggered.

  • Encrypt or move the backup to a secure location to minimize the risk of damage or unauthorized access to the hosts. A backup has sensitive information from the /root/ssl-build directory. For example, it can have hostnames, SSH keys, request files and SSL certificates.

7.1.3. Directories created during backups

orcharhino organizes backups in time-stamped subdirectories, which helps you identify and select the correct backup when restoring your system.

The foreman-maintain backup command creates a time-stamped subdirectory in the backup directory that you specify. The foreman-maintain backup command does not overwrite backups, therefore you must select the correct directory or subdirectory when restoring from a backup or an incremental backup. The foreman-maintain backup command stops and restarts services as required.

orcharhino creates the following default backup directories:

  • orcharhino-backup on orcharhino Server

  • foreman-proxy-backup on orcharhino Proxy Server

If you want to set a custom directory name, add the --preserve-directory option and add a directory name. The backup is then stored in the directory you provide in the command line. If you use the --preserve-directory option, no data is removed if the backup fails.

7.1.4. Estimating the size of a backup

Estimate how much disk space a orcharhino backup requires so you can ensure enough storage is available and avoid backup failures.

A full backup requires space to store the following data:

  • Uncompressed orcharhino database and configuration files

  • Compressed orcharhino database and configuration files

  • An extra 20% of the total estimated space to ensure a reliable backup

Compression occurs after the archives are created to decrease the time when orcharhino services are unavailable.

Procedure

  1. Estimate the size of uncompressed directories containing orcharhino database and configuration files:

    # du -sh /var/lib/pgsql/data /var/lib/pulp
100G    /var/lib/pgsql/data
100G	/var/lib/pulp

# du -csh /var/lib/tftpboot /etc /root/ssl-build \
/var/www/html/pub /opt/puppetlabs
16M   /var/lib/tftpboot
37M   /etc
900K  /root/ssl-build
100K  /var/www/html/pub
2M    /opt/puppetlabs
942M  total

  2. Calculate how much space is required to store the compressed data.

    The following table describes the compression ratio of all data items included in the backup:

    Table 4. Backup data compression ratio
    Data type Directory Ratio Example results

    PostgreSQL database files

    /var/lib/pgsql/data

    80 – 85%

    100 GB → 20 GB

    Pulp RPM files

    /var/lib/pulp

    (not compressed)

    100 GB

    Configuration files

    /var/lib/tftpboot

    /etc

    /root/ssl-build

    /var/www/html/pub

    /opt/puppetlabs

    85%

    942 MB → 141 MB

    In this example, the compressed backup data occupies 120 GB in total.

  3. To calculate the amount of available space you require to store a backup, calculate the sum of the estimated values of compressed and uncompressed backup data, and add an extra 20% to ensure a reliable backup.

    This example requires 201 GB plus 120 GB for the uncompressed and compressed backup data, 321 GB in total. With 64 GB of extra space, 385 GB must be allocated for the backup location.

7.2. Performing a full backup

Run a full offline backup on orcharhino Server and orcharhino Proxy Server to capture all orcharhino content and configuration. A full backup is useful when you want to prepare for a future restore from scratch.

Prerequisites

  • Your backup location must have sufficient available disk space to store the backup. For more information, see Estimating the size of a backup.

  • To enable orcharhino to save the backup to an NFS share, the root user of your orcharhino Server or orcharhino Proxy Server must be able to write to the NFS share. NFS export options such as root_squash and all_squash are known to prevent this.

Warning

Request other users of orcharhino Server or orcharhino Proxy Server to save any changes and warn them that orcharhino services are unavailable for the duration of the backup. Ensure no other tasks are scheduled for the same time as the backup.
Procedure

  1. Back up your orcharhino Server:

    # foreman-maintain backup offline /var/orcharhino-backup

  2. Back up your orcharhino Proxy Server:

    # foreman-maintain backup offline /var/foreman-proxy-backup

7.3. Performing a backup without Pulp content

Run an offline backup that excludes the contents of the Pulp directory. A backup without Pulp content is useful for debugging purposes and is only intended to provide access to configuration files without backing up the Pulp database.

Warning

Do not use a backup without Pulp content to restore your orcharhino Server or orcharhino Proxy Server for production use cases.
Prerequisites
Procedure

  • Back up your orcharhino Server without Pulp content:

    # foreman-maintain backup offline --skip-pulp-content /var/backup_directory

7.4. Performing an incremental backup

Run an incremental backup to perform an offline backup that captures any changes since a previous full backup. Incremental backups use less time and storage than a full offline backup.

To perform incremental backups, you must perform a full backup as a reference to create the first incremental backup of a sequence. Keep the most recent full backup and a complete sequence of incremental backups to restore from.

Prerequisites
Procedure

  1. Perform a full offline backup. For more information, see Performing a full backup.

  2. Create a directory within your backup directory to store the first incremental backup:

    # foreman-maintain backup offline --incremental /var/backup_directory/full_backup /var/backup_directory

  3. Create the second incremental backup by including the path to the first incremental backup to indicate the starting point for the next increment. This creates a directory for the second incremental backup in your backup directory:

    # foreman-maintain backup offline --incremental /var/backup_directory/first_incremental_backup /var/backup_directory

  4. Optional: If you want to point to a different version of the backup, and make a series of increments with that version of the backup as the starting point, you can do this at any time. For example, if you want to make a new incremental backup from the full backup rather than the first or second incremental backup, point to the full backup directory:

    # foreman-maintain backup offline --incremental /var/backup_directory/full_backup /var/backup_directory

7.5. Example of a weekly full backup followed by daily incremental backups

The following script performs a full backup on a Sunday followed by incremental backups for each of the following days. A new subdirectory is created for each day that an incremental backup is performed. The script requires a daily cron job.

#!/bin/bash -e
PATH=/sbin:/bin:/usr/sbin:/usr/bin
DESTINATION=/var/backup_directory
if [[ $(date +%w) == 0 ]]; then
  foreman-maintain backup offline --assumeyes $DESTINATION
else
  LAST=$(ls -td -- $DESTINATION/*/ | head -n 1)
  foreman-maintain backup offline --assumeyes --incremental "$LAST" $DESTINATION
fi
exit 0

Note that the {foreman-maintain backup} command requires /sbin and /usr/sbin directories to be in PATH and the --assumeyes option is used to skip the confirmation prompt.

7.6. Performing an online backup

Run an online backup to create a orcharhino backup while keeping most services running. This is useful when you need to maintain system availability during backup operations.

When you perform an online backup, most orcharhino services remain running and usable. Background workers are shut down to ensure consistent backups. Operations that require background workers remain in pending state. The backup process ensures that the Pulp data (/var/lib/pulp) is not altered during the backup. Any changes to the Pulp data during the backup will result in restart of the backup process, taking additional time.

Prerequisites
Procedure

  • Perform an online backup on your orcharhino Server:

    # foreman-maintain backup online /var/backup_directory

7.7. Creating a conventional backup

You can use conventional backup methods to back up your orcharhino Server or orcharhino Proxy Server. Unlike orcharhino backup methods, conventional backup methods require you to stop orcharhino services.

Procedure

  1. When creating a snapshot or conventional backup, stop all orcharhino services:

    # foreman-maintain service stop

  2. Create the snapshot or conventional backup.

  3. Start orcharhino services after creating a snapshot or conventional backup:

    # foreman-maintain service start

8. Restoring orcharhino Server or orcharhino Proxy Server from a backup

You can restore orcharhino Server or orcharhino Proxy Server from a backup to recover after failure or data loss. This process outlines how to restore the backup on the same server that generated the backup, and all data covered by the backup is deleted on the target system. If the original system is unavailable, provision a system with the same configuration settings and host name.

8.1. Restoring from a full backup

Restore orcharhino Server or orcharhino Proxy Server from a full backup return the system to the state at the time of the backup. When the restore process completes, all processes are online, and all databases and system configuration revert to the state at the time of the backup.

Prerequisites

  • Your orcharhino Server must have the same host name, configuration, and be the same minor version (X.Y) as the original system.

  • The target directory must exist and be writable. The target directory is read from the configuration files contained within the backup archive.

  • If the backed up system had FIPS enabled, the system on which you are restoring must also have FIPS enabled.

Procedure

  1. Ensure that you have enough space to store the backup data on the base system of orcharhino Server or orcharhino Proxy Server as well as enough space after the restoration to contain all the data in the /etc/ and /var/ directories contained within the backup.

    To check the space used by a directory:

    # du -sh /var/backup_directory

    To check for free space:

    # df -h /var/backup_directory

    Add the --total option to get a total of the results from more than one directory.

  2. Restore the correct SELinux contexts:

    # restorecon -Rv /

  3. Choose the appropriate method to install orcharhino or orcharhino Proxy:

  4. Copy the backup data to the local file system on orcharhino Server. Use /var/ or /var/tmp/.

  5. Run the restoration script.

    # foreman-maintain restore /var/backup_directory

    Where backup_directory is the time-stamped directory or subdirectory containing the backed-up data.

    The restore process can take a long time to complete, because of the amount of data to copy.

Next steps

  • If you create a new instance of orcharhino Server or orcharhino Proxy Server, decommission the old instance after restoring the backup. Cloned instances are not supposed to run in parallel in a production environment.

Troubleshooting

  • Review the /var/log/foreman/production.log and /var/log/messages log files.

8.2. Restoring from incremental backups

Restore orcharhino Server or orcharhino Proxy Server from an incremental backup to return the system to the state at the time of the backup. When the restore process completes, all processes are online, and all databases and system configuration revert to the state at the time of the backup.

If you have multiple branches of incremental backups, select your full backup and each incremental backup for the branch you want to restore, in chronological order.

Prerequisites

  • If the backed up system had FIPS enabled, the system on which you are restoring must also have FIPS enabled.

Procedure

  1. Restore the last full backup using the instructions in Restoring from a full backup.

  2. Remove the full backup data from the local file system on orcharhino Server, for example, /var/ or /var/tmp/.

  3. Copy the incremental backup data to the local file system on orcharhino Server, for example, /var/ or /var/tmp/.

  4. Restore the incremental backups in the same sequence that they are made:

    # foreman-maintain restore /var/backup_directory/FIRST_INCREMENTAL
# foreman-maintain restore /var/backup_directory/SECOND_INCREMENTAL
Next steps

  • If you create a new instance of orcharhino Server or orcharhino Proxy Server, decommission the old instance after restoring the backup. Cloned instances are not supposed to run in parallel in a production environment.

Troubleshooting

  • Review the /var/log/foreman/production.log and /var/log/messages log files.

8.3. Restoring orcharhino Proxy Server by using a virtual machine snapshot

Restore orcharhino Proxy Server from a virtual machine snapshot to return the system to the state at the time of the snapshot. You can use virtual machine snapshots to back up and restore your orcharhino Proxy Server for quick recovery after server failure or configuration issues.

Prerequisites

  • If the backed up system had FIPS enabled, the system on which you are restoring must also have FIPS enabled.

  • You have selected the relevant organization and location context of your orcharhino Proxy Server, or chosen Any Organization and Any Location.

Procedure

  1. If your orcharhino Proxy Server is a virtual machine, include it in your backup strategy by using VM snapshots. Creating weekly snapshots that you can restore from is recommended.

  2. After a failure, either restore your orcharhino Proxy Server from a snapshot by using your hypervisor tools, or deploy a new orcharhino Proxy Server and ensure that the host name is the same as before, and then install the orcharhino Proxy certificates. You may still have them on orcharhino Server, the package name ends in -certs.tar, alternately create new ones.

  3. Follow the procedures in Installing orcharhino Proxy Server until you can confirm, in the orcharhino management UI, that orcharhino Proxy Server is connected to orcharhino Server.

  4. In the orcharhino management UI, navigate to Infrastructure > orcharhino Proxies.

  5. Select your orcharhino Proxy Server.

  6. On the Overview tab, click Synchronize.

    • Select Optimized Sync to synchronize content from your orcharhino Server to your orcharhino Proxy Server that bypasses unnecessary steps to speed up performance.

    • Select Complete Sync to perform a complete sync from your orcharhino Server to your orcharhino Proxy Server that synchronizes content even if the metadata has not changed.

9. Renaming orcharhino Server or orcharhino Proxy Server

You can rename orcharhino Server or orcharhino Proxy Server when its hostname or domain changes. After renaming, it is important to update all references to avoid communication and certificate errors.

9.1. Renaming orcharhino Server

Rename orcharhino Server when its hostname or domain changes so that components, orcharhino Proxy Servers, and registered hosts continue to communicate correctly. Use the katello-change-hostname script and update all references to the new hostname.

Warning

Renaming your orcharhino Server host shuts down all orcharhino services on that host. The services restart after the renaming is complete.
Prerequisites

  • You have a backup of your orcharhino Server before changing its host name. If you fail to successfully rename it, restore it from the backup. For more information, see Backing up orcharhino.

  • The hostname and hostname -f commands on orcharhino Server both return the FQDN of orcharhino Server. If both commands do not return the FQDN of orcharhino Server, the katello-change-hostname script will fail to complete.

    If the hostname command returns the shortname of orcharhino Server instead of the FQDN, use hostnamectl set-hostname My_Old_FQDN to set the old FQDN correctly before using the katello-change-hostname script.

  • If orcharhino Server has a custom SSL certificate installed, you have a new certificate for the new FQDN of the host.

Procedure

  1. On orcharhino Server, run the katello-change-hostname script, and provide the new host name. Choose one of the following methods:

    • If your orcharhino Server is installed with the default self-signed SSL certificates:

      # katello-change-hostname new-orcharhino \
--username My_Username \
--password 'My_Password'

    • If your orcharhino Server is installed with custom SSL certificates:

      # katello-change-hostname new-orcharhino \
--username My_Username \
--password 'My_Password' \
--custom-cert "/root/ownca/test.com/test.com.crt" \
--custom-key "/root/ownca/test.com/test.com.key"

  2. If you have created a custom SSL certificate for the new orcharhino Server host name, run the orcharhino installation script to install the certificate.

  3. Reregister all hosts and orcharhino Proxy Servers that are registered to orcharhino Server. For more information, see Registering hosts by using global registration in Managing hosts.

  4. On all orcharhino Proxy Servers, run the orcharhino installation script to update references to the new host name:

    # orcharhino-installer \
--foreman-proxy-foreman-base-url https://new-orcharhino.example.com \
--foreman-proxy-trusted-hosts new-orcharhino.example.com

  5. On orcharhino Server, list all orcharhino Proxy Servers:

    # hammer proxy list

  6. On orcharhino Server, synchronize content for each orcharhino Proxy Server:

    # hammer proxy content synchronize \
--id My_orcharhino_Proxy_ID

  7. If you use the virt-who agent, update the virt-who configuration files with the new host name.

  8. If you use external authentication, reconfigure orcharhino Server for external authentication after you run the katello-change-hostname script. For more information, see Configuring authentication for orcharhino users.

9.2. Renaming orcharhino Proxy Server

Rename orcharhino Proxy Server when its hostname or domain changes so that orcharhino components and registered hosts continue to communicate correctly. Use the katello-change-hostname script and update certificates and references to the new hostname.

Warning

Renaming your orcharhino Proxy Server host shuts down all orcharhino services on that host. The services restart after the renaming is complete.
Prerequisites

  • You have a backup of your orcharhino Proxy Server before renaming. If you fail to successfully rename it, restore it from the backup. For more information, see Backing up orcharhino.

  • The hostname and hostname -f commands on orcharhino Proxy Server both return the FQDN of orcharhino Proxy Server. If both commands do not return the FQDN of orcharhino Proxy Server, the katello-change-hostname script will fail to complete.

    If the hostname command returns the shortname of orcharhino Proxy Server instead of the FQDN, use hostnamectl set-hostname My_Old_FQDN to set the old FQDN correctly before attempting to use the katello-change-hostname script.

Procedure

  1. On your orcharhino Server, generate a new certificates archive file for your orcharhino Proxy Server.

    • If you are using the default SSL certificate, regenerate the default SSL certificates:

      # foreman-proxy-certs-generate \
--certs-tar /root/new-orcharhino-proxy.example.com-certs.tar \
--foreman-proxy-fqdn new-orcharhino-proxy.example.com

      Ensure that you enter the full path to the .tar file.

    • If you are using a custom SSL certificate, create a new SSL certificate for your orcharhino Proxy Server.

  2. On your orcharhino Server, copy the certificates archive file to your orcharhino Proxy Server. For example, to copy the archive file to the root user’s home directory:

    # scp /root/new-orcharhino-proxy.example.com-certs.tar root@orcharhino-proxy.example.com:

  3. On your orcharhino Proxy Server, run the katello-change-hostname script and provide the host’s new name, orcharhino credentials, and certificates archive file name.

    # katello-change-hostname new-orcharhino-proxy.example.com \
--certs-tar /root/new-orcharhino-proxy.example.com-certs.tar \
--password 'My_Password' \
--username My_Username

    Ensure that you enter the full path to the .tar file.

  4. If you have created a custom certificate for your orcharhino Proxy Server, deploy the certificate to your orcharhino Proxy Server by entering the orcharhino-installer command that the foreman-proxy-certs-generate command returned in a previous step.

  5. Reregister all hosts that are registered to your orcharhino Proxy Server. For more information, see Registering hosts to orcharhino in Managing hosts.

  6. Update the orcharhino Proxy host name in the orcharhino management UI.

    1. In the orcharhino management UI, navigate to Infrastructure > orcharhino Proxies.

    2. Locate orcharhino Proxy Server in the list, and click Edit.

    3. Edit the Name and URL fields to match orcharhino Proxy Server’s new host name, then click Submit.

    4. On your DNS server, add a record for the new hostname of your orcharhino Proxy Server, and delete the record of the previous host name.

10. Configuring orcharhino for Insights analytics

You can configure orcharhino to connect to Insights hosted in the Red Hat Hybrid Cloud Console so your Red Hat Enterprise Linux hosts receive suggestions for improvement.

10.1. Insights overview

Insights is a set of analytical services by Red Hat for hosts running Red Hat Enterprise Linux. Insights services analyze host data and provide suggestions for host improvements.

Insights services

Insights services include:

  • Advisor, which provides recommendations for host improvements.

  • Vulnerability, which provides reports on vulnerabilities found on your hosts.

  • Compliance, which provides reports on compliance with regulatory requirements.

Insights services hosted in the Red Hat Hybrid Cloud Console are not limited to the listed services.

Hosted Insights

When you use Insights hosted in the Red Hat Hybrid Cloud Console, the Insights client on your hosts collects data and orcharhino forwards it to the hosted Insights services for analysis.

If you use Insights in the Red Hat Hybrid Cloud Console:

  • You can use Insights services online in the Red Hat Hybrid Cloud Console.

  • The Insights client collects data of your hosts and orcharhino forwards the data to the Red Hat Hybrid Cloud Console to calculate recommendations.

  • You can view and remediate those recommendations both in the orcharhino management UI and in the Red Hat Hybrid Cloud Console.

  • orcharhino uploads host inventory reports to the Red Hat Hybrid Cloud Console.

  • You have control over how much information is included in those reports.

Additional resources

10.2. Enabling hosted Insights

Enable the integration between orcharhino and hosted Insights in the Red Hat Hybrid Cloud Console to upload host inventory and receive cloud-based recommendations for your hosts.

10.2.1. Installing Red Hat Cloud plugin

Install the Red Hat Cloud plugin on your orcharhino Server to upload inventory reports to the Red Hat Hybrid Cloud Console. This step is required before you configure the cloud connector.

Procedure

  • Install the Red Hat Cloud plugin on your orcharhino Server:

    # orcharhino-installer --enable-foreman-plugin-rh-cloud
Verification

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

  2. On the Plugins tab, verify that it lists the foreman_rh_cloud plugin.

10.2.2. Adding orcharhino Server SSH key to authorized keys

To run remote execution jobs on orcharhino Server itself, add the orcharhino Server SSH key to authorized keys on your orcharhino Server.

Prerequisites

  • You can access your orcharhino Server by using SSH as root.

Procedure

  1. If the ~root/.ssh/authorized_keys file does not exist, create it with restrictive ownership and permissions:

    1. If the ~root/.ssh directory does not exist, create it:

      # mkdir ~root/.ssh

    2. Ensure that the directory is owned by the root user:

      # chown root:root ~root/.ssh

    3. Ensure that the directory is accessible only to the root user:

      # chmod 700 ~root/.ssh

    4. Create the authorized_keys file:

      # touch ~root/.ssh/authorized_keys

    5. Ensure that the authorized_keys file is owned by the root user:

      # chown root:root ~root/.ssh/authorized_keys

    6. Ensure that the authorized_keys file is accessible only to the root user:

      # chmod 600 ~root/.ssh/authorized_keys

  2. Add the SSH key of the foreman-proxy user to the authorized_keys file:

    # cat ~foreman-proxy/.ssh/id_rsa_foreman_proxy.pub >>~root/.ssh/authorized_keys

10.2.3. Configuring orcharhino Server for cloud connection

You can configure orcharhino Server to connect to the Red Hat Hybrid Cloud Console by using remote execution. This enables inventory upload and cloud-based features such as Insights for your hosts.

Prerequisites

  • You have installed the Red Hat Cloud plugin on your orcharhino Server. For more information, see Installing Red Hat Cloud plugin.

  • Your environment is configured for remote execution. For more information, see Configuring and setting up remote jobs in Managing hosts.

  • orcharhino Server must be registered with Red Hat Subscription Management. You can verify the status by running subscription-manager status.

  • You have added the SSH key to authorized keys on your orcharhino Server. For more information, see Adding orcharhino Server SSH key to authorized keys.

  • Your orcharhino account has a role that grants the execute_jobs_on_infrastructure_hosts permission.

    Note that this permission is not included in the default Remote Execution User role.

Procedure

  1. In the orcharhino management UI, navigate to Insights > Inventory Upload.

  2. Click Configure cloud connector.

  3. Click Confirm.

Verification

  1. In the orcharhino management UI, navigate to Monitor > orcharhino Tasks > Tasks.

  2. Find the job with the name Remote action: Configure cloud connector.

  3. Verify that the job completed successfully.

Next steps

10.3. Data control settings for hosted Insights

You can configure how orcharhino handles the data collected from hosts before uploading it to the Red Hat Hybrid Cloud Console and how orcharhino handles hosts in the Red Hat Hybrid Cloud Console that are no longer managed by orcharhino.

10.3.1. Minimizing collected data

Use minimal data collection to limit host data sent to Red Hat while keeping the Subscriptions service active. Other Insights services are disabled because they require installed package data.

You can use minimal reporting to limit the amount of system data sent to the Subscriptions service, which remains active. Other Insights services are disabled because they require installed package data, which minimal reports do not include. Reports are still processed daily during the midnight synchronization cycle.

Minimal reports also exclude hostnames, IP addresses, and installed packages. Therefore, obfuscation and exclusion settings do not apply.

If you switch to Analytics data collection, orcharhino enables the following settings by default:

  • Obfuscate host names

  • Obfuscate host ipv4 addresses

  • Exclude installed packages

Review and adjust these settings to control what data orcharhino shares.

Example 2. Example of data collected in a minimal report
{
  "report_slice_id": "de92044d-9d77-4895-83c4-a476f5020519",
  "hosts": [
    {
      "account": "123456789",
      "subscription_manager_id": "9fc621b9-08c3-4085-a749-bfed38c3052e",
      "insights_id": "9fc621b9-08c3-4085-a749-bfed38c3052e",
      "bios_uuid": "203F234F-58C7-4237-8DDF-A17A2838A66C",
      "bios_vendor": "SeaBIOS",
      "bios_version": "1.16.1-1.el9",
      "arch": "x86_64",
      "infrastructure_type": "virtual",
      "system_profile": {
        "installed_products": [
          {
            "name": "Red Hat Enterprise Linux for x86_64",
            "id": "479"
          }
        ],
        "cores_per_socket": 1,
        "system_memory_bytes": 3836579840,
        "number_of_cpus": 1,
        "number_of_sockets": 1
      },
      "cpu_socket(s)": "1"
    }
  ]
}
Prerequisites

  • Your user account has a role that grants the edit_settings permission.

  • Existing data in Insights Inventory has been deleted before switching to minimal reporting. To remove existing data of a system, navigate to Inventory > Systems in the Red Hat Hybrid Cloud Console, select the system, and click Delete.

  • You have selected an organization and location.

Procedure

  1. In the orcharhino management UI, navigate to Insights > Inventory Upload.

  2. Select the Minimal data collection setting from the dropdown menu under Settings.

  3. When you select this option, orcharhino also updates the corresponding setting on the Insights tab under Administer > Settings.

  4. Click the Generate and upload report button to create a new inventory report and send it to the Red Hat Hybrid Cloud Console.

10.3.2. Obfuscating hostnames and IP addresses

You can configure orcharhino to obfuscate hostnames and IP addresses when uploading host data to Insights. Obfuscation ensures that sensitive identifying information is not exposed.

When obfuscation settings are enabled, orcharhino obfuscates hostnames and IP addresses. If obfuscation settings are enabled and the host has its own insights-client obfuscation settings, orcharhino honors the host settings. If obfuscation settings are disabled, orcharhino does not obfuscate hostnames or IP addresses unless the client has obfuscation enabled in insights-client.

By default, orcharhino applies global obfuscation settings unless an insights-client on the host overrides the settings with its own configuration.

Note

Obfuscation only works when Minimal data collection is disabled. If Minimal data collection is enabled, hostnames and IP addresses are not included in reports, making obfuscation unnecessary and inactive.
Prerequisites

  • Your hosts have insights-client installed and configured.

Procedure

  1. In the orcharhino management UI, navigate to Insights > Inventory Upload.

  2. Enable the Obfuscate host names setting to obfuscate host names sent to the Red Hat Hybrid Cloud Console.

  3. Enable the Obfuscate host ipv4 addresses setting to obfuscate IPv4 addresses sent to the Red Hat Hybrid Cloud Console.

Verification

  1. In the orcharhino management UI, navigate to Insights > Inventory Upload.

  2. In the Organization dropdown menu, select the organization that uploaded the host data.

  3. Click Generate report to create a fresh report with obfuscated data.

  4. Click Download report to download the host inventory report.

  5. Verify that the hostname is randomhostname.example.com and the IP address is obfuscated.

Next steps

  • Click Generate and upload report to create and upload a new report with obfuscated data to the Red Hat Hybrid Cloud Console.

10.3.3. Removing hosts from the Insights Inventory

When hosts are removed from orcharhino, they can also be removed from the inventory of Insights, either automatically or manually. You can configure automatic removal of hosts from the Insights Inventory during Red Hat Hybrid Cloud Console synchronization with orcharhino that occurs daily by default.

If you leave the setting disabled, you can still remove the bulk of hosts from the Inventory manually.

If Automatic mismatch deletion is enabled, orcharhino removes any hosts from the Red Hat Hybrid Cloud Console that are not registered in orcharhino. Enable this setting only when all hosts are registered through orcharhino. If any hosts are registered through other orcharhino instances or directly to the Red Hat Hybrid Cloud Console, orcharhino deletes them.

Note

Automatic mismatch deletion runs once a day as a scheduled task. After removing hosts from orcharhino, hosts are deleted from the Red Hat Hybrid Cloud Console inventory during the next scheduled sync. Clicking Sync all inventory status updates the status of hosts but does not trigger immediate deletion.
Prerequisites

  • Your orcharhino account has a role that grants the view_foreman_rh_cloud and edit_settings permissions.

Procedure

  1. In the orcharhino management UI, navigate to Insights > Inventory Upload.

  2. Enable the Automatic mismatch deletion setting.

10.4. Disabling hosted Insights

If you do not want to use the hosted Insights services in the Red Hat Hybrid Cloud Console, you can disable the integration between orcharhino and the Red Hat Hybrid Cloud Console.

Prerequisites

  • The Red Hat Cloud plugin is installed on orcharhino Server.

Procedure

  1. Uninstall the Red Hat Cloud plugin on orcharhino Server:

    # orcharhino-installer --no-enable-foreman-plugin-rh-cloud

  2. Remove the Red Hat Cloud package and its dependencies from orcharhino Server:

    # dnf remove rubygem-foreman_rh_cloud

  3. Restart the orcharhino services:

    # foreman-maintain service restart
Verification

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

  2. On the Plugins tab, verify that it does not list the foreman_rh_cloud plugin.

11. Reducing storage use on orcharhino Server

orcharhino Server can accumulate a large amount of data over time, which can use a significant amount of disk space. You can clean up database records or reclaim disk space to reduce storage use.

11.1. Cleaning audit records

Audit records log changes that users make to orcharhino resources, such as creating hosts or editing settings. You can clean up outdated audit records by deleting them.

11.1.1. Deleting audit records manually

You can use the foreman-rake audits:expire command to remove audit records at any time.

Procedure

  • Delete the audit records using the foreman-rake audits:expire command:

    # foreman-rake audits:expire days=Number_Of_Days

    This command deletes all audit records older than Number_Of_Days.

11.1.2. Deleting audit records automatically

You can automatically delete audit records using the Saved audits interval setting. This setting is empty by default, meaning orcharhino does not automatically delete the audit records.

Procedure

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

  2. On the General tab, find the Saved audits interval setting.

  3. Set the value of the setting to the number of days after which you want orcharhino to delete the audit records.

11.2. Cleaning report records

Report records are configuration reports that hosts send to orcharhino after Puppet, Ansible, or Salt runs. Clean up outdated reports to reduce database growth and storage use.

11.2.1. Deleting report records

orcharhino creates report records automatically. To remove old and unnecessary report records, you can delete them. This is useful for maintaining a clean and organized report history.

Procedure

  • Use the foreman-rake reports:expire command to remove reports at any time. You can also use a cron job to schedule report record deletions at the set interval that you want.

    By default, using the foreman-rake reports:expire command removes report records that are older than 90 days. You can specify the number of days to keep the report records by adding the days option and add the number of days.

    For example, you can delete report records that are older than seven days:

    # foreman-rake reports:expire days=7

11.3. Cleaning task records

Task records track background jobs that orcharhino executes, such as synchronizing repositories. Configure automatic cleanup or manually clean up outdated tasks to save database space.

11.3.1. Configuring the cleaning unused tasks feature

orcharhino automatically cleans up old tasks. You can configure the automatic cleaning process according to your needs.

By default, orcharhino executes a cron job that cleans tasks every day at 19:45. orcharhino removes the following tasks during the cleaning:

  • Tasks that have run successfully and are older than thirty days

  • All tasks that are older than a year

You can configure the cleaning unused tasks feature using these options:

  • To configure the time at which orcharhino runs the cron job, set the --foreman-plugin-tasks-cron-line parameter to the time you want in cron format. For example, to schedule the cron job to run every day at 15:00, enter the following command:

    # orcharhino-installer --foreman-plugin-tasks-cron-line "00 15 * * *"

  • To configure the period after which orcharhino deletes the tasks, edit the :rules: section in the /etc/foreman/plugins/foreman-tasks.yaml file.

  • To disable regular task cleanup on orcharhino, enter the following command:

    # orcharhino-installer --foreman-plugin-tasks-automatic-cleanup false

  • To reenable regular task cleanup on orcharhino, enter the following command:

    # orcharhino-installer --foreman-plugin-tasks-automatic-cleanup true

11.3.2. Deleting task records

orcharhino creates task records automatically. To remove old and unnecessary task records, you can delete them. This helps maintain system performance and keeps your task history organized.

Procedure

  • Use the foreman-rake foreman_tasks:cleanup command to remove tasks at any time. You can also use a cron job to schedule Task record deletions at the set interval that you want.

    For example, you can delete task records from successful repository synchronizations:

    # foreman-rake foreman_tasks:cleanup TASK_SEARCH='label = Actions::Katello::Repository::Sync' STATES='stopped'

11.3.3. Deleting a task by ID

You can delete tasks by ID, for example if you have submitted confidential data by mistake.

Procedure

  1. Connect to your orcharhino Server using SSH:

    # ssh root@orcharhino.example.com

  2. Optional: View the task:

    $ hammer task info --id My_Task_ID

  3. Delete the task:

    # foreman-rake foreman_tasks:cleanup TASK_SEARCH="id=My_Task_ID"

  4. Optional: Ensure the task has been removed from orcharhino Server:

    $ hammer task info --id My_Task_ID

    Note that because the task is deleted, this command returns a non-zero exit code.

11.4. Reclaiming disk space

orcharhino can consume a significant amount of disk space, especially in large deployments. By reclaiming disk space, you can reduce the amount of disk space used by orcharhino.

11.4.1. Recovering from a full disk

If a logical volume (LV) with the Pulp database on it is full, Pulp tasks can fail due to insufficient space. You can recover from the situation by increasing the amount of free space available on the LV.

Procedure

  1. Let running Pulp tasks finish but do not trigger any new ones as they can fail due to the full disk.

  2. Ensure that the LV with the /var/lib/pulp directory on it has sufficient free space. Here are some ways to achieve that:

    1. Remove orphaned content:

      # foreman-rake katello:delete_orphaned_content RAILS_ENV=production

      This is run weekly so it will not free much space.

    2. Change the download policy from Immediate to On Demand for as many repositories as possible and remove already downloaded packages.

    3. Grow the file system on the LV with the /var/lib/pulp directory on it.

      Note

      If you use an untypical file system (other than for example ext3, ext4, or xfs), you might need to unmount the file system so that it is not in use. In that case, complete the following steps:

      1. Stop orcharhino services:

        # foreman-maintain service stop

      2. Grow the file system on the LV.

      3. Start orcharhino services:

        # foreman-maintain service start

  3. If some Pulp tasks failed due to the full disk, run them again.

11.4.2. Reclaiming PostgreSQL space

If the PostgreSQL database is using a large amount of disk space, you can reclaim space by vacuuming the database. By reclaiming PostgreSQL space, you can reduce the amount of disk space used by orcharhino.

Procedure

  1. Stop all services, except for the postgresql service:

    # foreman-maintain service stop --exclude postgresql

  2. Switch to the postgres user and reclaim space on the database:

    # su - postgres -c 'vacuumdb --full --all'

  3. Start the other services when the vacuum completes:

    # foreman-maintain service start

11.4.3. Reclaiming space from on-demand repositories

If you set the download policy to on demand, orcharhino downloads packages only when the clients request them. You can clean up these packages to reclaim space.

Note

Space reclamation requires an existing repository. For deleted repositories, wait for the next scheduled orphan cleanup or remove orphaned content manually:

# foreman-rake katello:delete_orphaned_content
Procedure

  1. If you want to reclaim space for a single repository:

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

    2. Select a product.

    3. On the Repositories tab, click the repository name.

    4. From the Select Actions list, select Reclaim Space.

  2. If you want to reclaim space for multiple repositories:

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

    2. Select the product name.

    3. On the Repositories tab, select the checkbox of the repositories.

    4. Click Reclaim Space at the top right corner.

  3. If you want to reclaim space for orcharhino Proxies:

    1. In the orcharhino management UI, navigate to Infrastructure > orcharhino Proxies.

    2. Select the orcharhino Proxy Server.

    3. Click Reclaim space.

12. Renewing certificates

You can renew the CA certificate on orcharhino Server or the custom SSL certificate on orcharhino Server as well as on orcharhino Proxy Server.

12.1. Planning for self-signed CA certificate renewal

If you need to update the Certification Authority (CA) certificate on your orcharhino Server, add the new CA certificate and use a temporary dual CA certificate file to retain the HTTPS connections to your orcharhino Server during the renewal.

Procedure

  1. Add the new SSL certificate to the CA certificate file on orcharhino Server and keep the old SSL certificate.

  2. Renew the certificates on orcharhino Server and any orcharhino Proxy Servers.

  3. Deploy the dual CA certificate on hosts.

  4. Remove the old certificate from the CA certificates file on orcharhino Server, so the CA certificate file contains only the new SSL certificate.

  5. Renew the certificates on orcharhino Server and any orcharhino Proxy Servers.

  6. Deploy the new CA certificate on hosts.

Additional resources

12.2. Renewing a custom SSL certificate on orcharhino Server

You can deploy a renewed custom SSL certificate on orcharhino Server to replace an expiring certificate and maintain trusted access to the orcharhino management UI and API.

Prerequisites

  • You have created a new Certificate Signing Request (CSR) and sent it to the Certificate Authority to sign the certificate. Refer to the Configuring orcharhino Server with a custom SSL certificate guide before creating a new CSR because the Server certificate must have X.509 v3 Key Usage and Extended Key Usage extensions with required values. In return, you will receive the orcharhino Server certificate and CA bundle.

Procedure

  • Deploy the renewed CA certificates to orcharhino Server:

    # orcharhino-installer --scenario katello \
--certs-server-cert "/root/orcharhino_cert/orcharhino_cert.pem" \
--certs-server-key "/root/orcharhino_cert/orcharhino_cert_key.pem" \
--certs-server-ca-cert "/root/orcharhino_cert/ca_cert_bundle.pem" \
--certs-update-server \
--certs-update-server-ca
    Important

    Do not delete the certificate files after you deploy the certificate. They are required when upgrading orcharhino Server.
Verification

  1. Access the orcharhino management UI from your local machine. For example, https://orcharhino.example.com.

  2. In your browser, view the certificate details to verify the deployed certificate.

Next steps

12.3. Renewing a custom SSL certificate on orcharhino Proxy Server

You can deploy a renewed custom SSL certificate on each orcharhino Proxy Server before it expires to maintain secure communication with orcharhino Server. Run a unique orcharhino-installer command on each server because the output of foreman-proxy-certs-generate cannot be reused.

Prerequisites

  • You have created a new Certificate Signing Request and sent it to the Certificate Authority to sign the certificate. Refer to the Configuring orcharhino Server with a custom SSL certificate guide before creating a new CSR because the orcharhino Server certificate must have X.509 v3 Key Usage and Extended Key Usage extensions with required values. In return, you will receive the orcharhino Proxy Server certificate and CA bundle.

Procedure

  1. On your orcharhino Server, generate the certificate archive file for your orcharhino Proxy Server:

    # foreman-proxy-certs-generate \
--certs-tar "/root/My_Certificates/orcharhino-proxy.example.com-certs.tar" \
--certs-update-server \
--foreman-proxy-fqdn "orcharhino-proxy.example.com" \
--server-ca-cert "/root/My_Certificates/ca_cert_bundle.pem" \
--server-cert "/root/My_Certificates/orcharhino-proxy_cert.pem" \
--server-key "/root/My_Certificates/orcharhino-proxy_cert_key.pem"

  2. On your orcharhino Server, copy the certificate archive file to your orcharhino Proxy Server:

    # scp /root/My_Certificates/orcharhino-proxy.example.com-certs.tar user@orcharhino-proxy.example.com:

    You can move the copied file to the applicable path if required.

  3. Retain a copy of the orcharhino-installer command that the foreman-proxy-certs-generate command returns for deploying the certificate to your orcharhino Proxy Server.

  4. Deploy the certificate on your orcharhino Proxy Server using the orcharhino-installer command returned by the foreman-proxy-certs-generate command:

    # orcharhino-installer --scenario foreman-proxy-content \
--certs-tar-file "/root/My_Certificates/orcharhino-proxy.example.com-certs.tar" \
--certs-update-server \
--foreman-proxy-foreman-base-url "https://orcharhino.example.com"
    Important

    Do not delete the certificate archive file on the orcharhino Proxy Server after you deploy the certificate. They are required when upgrading orcharhino Proxy Server.
Next steps

13. Synchronizing template repositories

You can synchronize repositories of job templates, provisioning templates, report templates, and partition table templates between orcharhino Server and a version control system or local directory. You can use the Template Sync plugin to export and import templates.

13.1. Enabling the Template Sync plugin

You can enable the Template Sync plugin to synchronize provisioning templates, report templates, and other templates between your orcharhino Server and a version control system or local directory. This is useful when you want to manage templates in Git repositories or keep templates synchronized across multiple orcharhino instances.

Procedure

  1. Enable the plugin on your orcharhino Server:

    # orcharhino-installer --enable-foreman-plugin-templates

  2. Optional: Enable the Hammer CLI plugin on your orcharhino Server:

    # orcharhino-installer --enable-foreman-cli-templates
Verification

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

  2. On the Plugins tab, ensure that the page includes the Template Sync plugin.

Next steps

  1. In the orcharhino management UI, navigate to Administer > Settings > Template Sync to configure the plugin. For more information, see Template sync settings.

13.2. Synchronizing templates with an existing repository

If you store templates in a repository under a version control system, you can synchronize the templates between your orcharhino Server and the repository.

In this procedure, a Git repository is used for demonstration purposes.

Procedure

  1. If you want to use HTTPS to connect to the repository and you use a self-signed certificate authority (CA) on your Git server:

    1. Create a new directory under the /usr/share/foreman/ directory to store the Git configuration for the certificate:

      # mkdir --parents /usr/share/foreman/.config/git

    2. Create a file named config in the new directory:

      # touch /usr/share/foreman/.config/git/config

    3. Allow the foreman user access to the .config directory:

      # chown --recursive foreman /usr/share/foreman/.config

    4. Update the Git global configuration for the foreman user with the path to your self-signed CA certificate:

      # sudo --user foreman git config --global http.sslCAPath Path_To_CA_Certificate

  2. If you want to use SSH to connect to the repository:

    1. Create an SSH key pair if you do not already have it. Do not specify a passphrase.

      # sudo --user foreman ssh-keygen

    2. Configure your version control server with the public key from your orcharhino, which resides in /usr/share/foreman/.ssh/id_rsa.pub.

    3. Accept the Git SSH host key as the foreman user:

      # sudo --user foreman ssh git.example.com

  3. In the orcharhino management UI, provide details for your Git repository:

    1. Navigate to Administer > Settings.

    2. Click the Template Sync tab.

    3. Change the Branch setting to define the target branch of the repository.

    4. Change the Repo setting to define the repository URL.

    5. If you want to use an HTTP proxy to connect to the repository, change the HTTP proxy policy setting to Global default HTTP proxy or Custom HTTP proxy.

Next steps

  • Import templates from your repository or export templates to your repository.

13.3. Synchronizing templates with a local directory

If you store templates in a local directory that is tracked under a version control system, you can synchronize the templates between your orcharhino Server and the local directory.

Prerequisites

  • Each template must contain the location and organization that the template belongs to. This applies to all template types. Before you import a template, ensure that you add the following section to the template:

    <%#
kind: provision
name: My_Provisioning_Template
oses:
- My_first_Operating_System
- My_second_Operating_System
locations:
- My_first_Location
- My_second_Location
organizations:
- My_first_Organization
- My_second_Organization
%>
Procedure

  1. On your orcharhino Server, in /var/lib/foreman, create a directory for storing templates:

    # mkdir /var/lib/foreman/My_Templates_Dir
    Note

    You can place your templates to a custom directory outside /var/lib/foreman, but you have to ensure that the Foreman service can read its contents. The directory must have the correct file permissions and the foreman_lib_t SELinux label.

  2. Change the owner of the new templates directory to the foreman user:

    # chown foreman /var/lib/foreman/My_Templates_Dir

  3. Change the Repo setting on the Template Sync tab to match the /var/lib/foreman/My_Templates_Dir/ directory.

13.4. Importing templates by using orcharhino management UI

You can import templates from a repository of your choice from the orcharhino management UI. You can use different protocols to point to your repository, for example /tmp/dir, git://example.com, https://example.com, and ssh://example.com.

Note

The templates provided by orcharhino are locked and you cannot import them by default. To overwrite this behavior, change the Force import setting in the Template Sync menu to yes or add the force parameter -d '{ "force": "true" }' to the import command.
Prerequisites

  • Each template must contain the location and organization that the template belongs to. This applies to all template types.

  • Before you import a template, ensure that you add the following section to the template:

    <%#
kind: provision
name: My_Provisioning_Template
oses:
- My_first_Operating_System
- My_second_Operating_System
locations:
- My_first_Location
- My_second_Location
organizations:
- My_first_Organization
- My_second_Organization
%>
Procedure

  1. In the orcharhino management UI, navigate to Hosts > Templates > Sync Templates.

  2. Click Import.

  3. Each field is populated with values configured in Administer > Settings > Template Sync. Change the values as required for the templates you want to import. For more information about each field, see Template sync settings.

  4. Click Submit.

    The orcharhino management UI displays the status of the import. The status is not persistent; if you leave the status page, you cannot return to it.

13.5. Importing templates by using Hammer CLI

You can import templates from a repository of your choice by using Hammer CLI. You can use different protocols to point to your repository, for example /tmp/dir, git://example.com, https://example.com, and ssh://example.com.

Note

The templates provided by orcharhino are locked and you cannot import them by default. To overwrite this behavior, change the Force import setting in the Template Sync menu to yes or add the force parameter -d '{ "force": "true" }' to the import command.
Prerequisites

  • Each template must contain the location and organization that the template belongs to. This applies to all template types.

  • Before you import a template, ensure that you add the following section to the template:

    <%#
kind: provision
name: My_Provisioning_Template
oses:
- My_first_Operating_System
- My_second_Operating_System
locations:
- My_first_Location
- My_second_Location
organizations:
- My_first_Organization
- My_second_Organization
%>
Procedure

  • Import a template from a repository:

    $ hammer import-templates \
--branch "My_Branch" \
--filter '.*Template Name$' \
--organization "My_Organization" \
--prefix "[Custom Index] " \
--repo "https://git.example.com/path/to/repository"

    For better indexing and management of your templates, use --prefix to set a category for your templates. To select certain templates from a large repository, use --filter to define the title of the templates that you want to import. For example --filter '.*Ansible Default$' imports various Ansible Default templates.

13.6. Importing templates by using orcharhino API

You can import templates from a repository of your choice by using orcharhino API. You can use different protocols to point to your repository, for example /tmp/dir, git://example.com, https://example.com, and ssh://example.com.

Note

The templates provided by orcharhino are locked and you cannot import them by default. To overwrite this behavior, change the Force import setting in the Template Sync menu to yes or add the force parameter -d '{ "force": "true" }' to the import command.
Prerequisites

  • Each template must contain the location and organization that the template belongs to. This applies to all template types.

  • Before you import a template, ensure that you add the following section to the template:

    <%#
kind: provision
name: My_Provisioning_Template
oses:
- My_first_Operating_System
- My_second_Operating_System
locations:
- My_first_Location
- My_second_Location
organizations:
- My_first_Organization
- My_second_Organization
%>
Procedure

  • Send a POST request to api/v2/templates/import:

    $ curl \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--request POST \
--user "My_User_Name:My_Password" \
https://orcharhino.example.com/api/v2/templates/import

    If the import is successful, you receive {"message":"Success"}.

13.7. Importing templates using Ansible

You can import templates from a repository of your choice. You can use different protocols to point to your repository, for example /tmp/dir, git://example.com, https://example.com, and ssh://example.com.

Procedure

  • Use the theforeman.foreman.templates_import module.

Additional resources

13.8. Exporting templates by using orcharhino management UI

You can export templates to an existing repository from the orcharhino management UI. This is useful for backing up customized templates and keeping them synchronized with your version control system.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Templates > Sync Templates.

  2. Click Export.

  3. Each field is populated with values configured in Administer > Settings > Template Sync. Change the values as required for the templates you want to export. For more information about each field, see Template sync settings.

  4. Click Submit.

    The orcharhino management UI displays the status of the export. The status is not persistent; if you leave the status page, you cannot return to it.

13.9. Exporting templates by using Hammer CLI

You can export templates to an existing repository by using Hammer CLI. This is useful for backing up customized templates and keeping them synchronized with your version control system.

Procedure

  • Export all templates to a repository:

    $ hammer export-templates \
--organization "My_Organization" \
--repo "https://git.example.com/path/to/repository"
    Note

    This command clones the repository, makes changes in a commit, and pushes back to the repository. You can use the --branch "My_Branch" option to export the templates to a specific branch.

13.10. Exporting templates by using orcharhino API

You can export templates to an existing repository by using orcharhino API. This is useful for backing up customized templates and keeping them synchronized with your version control system.

Procedure

  1. Send a POST request to api/v2/templates/export:

    $ curl \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--request POST \
--user "My_User_Name:My_Password" \
https://orcharhino.example.com/api/v2/templates/export

    If the export is successful, you receive {"message":"Success"}.

    Note

    You can override default API settings by specifying them in the request with the -d parameter. The following example exports templates to the git.example.com/templates repository:

    $ curl \
--data "{\"repo\":\"git.example.com/templates\"}" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--request POST \
--user "My_User_Name:My_Password" \
https://orcharhino.example.com/api/v2/templates/export

13.11. Uninstalling the Foreman templates plugin

Use the following procedure to avoid errors after removing the Templates plugin.

Procedure

  1. Disable the plugin using the orcharhino installer:

    # orcharhino-installer --no-enable-foreman-plugin-templates

  2. Clean custom data of the plugin. The command does not affect any templates that you created.

    # foreman-rake templates:cleanup

  3. Uninstall the plugin:

    # dnf remove foreman-plugin-templates

14. Monitoring orcharhino resources

You can use orcharhino management UI to monitor your orcharhino environment and hosts. This includes details of hosts, such as configuration or compliance, and information about content and orcharhino Proxies.

14.1. Using the orcharhino content dashboard

The orcharhino content dashboard contains various widgets. Use the dashboard to get a quick overview of the resources currently in use in orcharhino.

In the orcharhino management UI, navigate to Monitor > Dashboard to access the content dashboard. The dashboard can be rearranged by clicking on a widget and dragging it to a different position. The following widgets are available:

Host Configuration Status

An overview of the configuration states and the number of hosts associated with it during the last reporting interval. The following table shows the descriptions of the possible configuration states.

Table 5. Host configuration states
Icon State Description

host state config okay

Hosts that had performed modifications without error

Host that successfully performed modifications during the last reporting interval.

host state config error

Hosts in error state

Hosts on which an error was detected during the last reporting interval.

host state config report

Good host reports in the last 35 minutes

Hosts without error that did not perform any modifications in the last 35 minutes.

host state config pending

Hosts that had pending changes

Hosts on which some resources would be applied but Puppet was configured to run in the noop mode.

host state config outofsync

Out of sync hosts

Hosts that were not synchronized and the report was not received during the last reporting interval.

host state config noreport

Hosts with no reports

Hosts for which no reports were collected during the last reporting interval.

host state config noalert

Hosts with alerts disabled

Hosts which are not being monitored.

Click the particular configuration status to view hosts associated with it.

Host Configuration Chart

A pie chart shows the proportion of the configuration status and the percentage of all hosts associated with it.

Latest Events

A list of messages produced by hosts including administration information, product changes, and any errors.

Monitor this section for global notifications sent to all users and to detect any unusual activity or errors.

Run Distribution (last 30 minutes)

A graph shows the distribution of the running OpenVox agents during the last puppet interval which is 30 minutes by default. In this case, each column represents several reports received from clients during 3 minutes.

New Hosts

A list of the recently created hosts. Click the host for more details.

Task Status

A summary of all current tasks, grouped by their state and result. Click the number to see the list of corresponding tasks.

Latest Warning/Error Tasks

A list of the latest tasks that have been stopped due to a warning or error. Click a task to see more details.

Discovered Hosts

A list of all bare-metal hosts detected on the provisioning network by the Discovery plugin.

Latest Errata

A list of all errata available for hosts registered to orcharhino.

Content Views

A list of all content views in orcharhino and their publish status.

Sync Overview

An overview of all products or repositories enabled in orcharhino and their synchronization status. All products that are in the queue for synchronization, are unsynchronized or have been previously synchronized are listed in this section.

Host Collections

A list of all host collections in orcharhino and their status, including the number of hosts in each host collection.

Virt-who Configuration Status

An overview of the status of reports received from the virt-who daemon running on hosts in the environment. The following table shows the possible states.

Table 6. virt-who configuration states
State Description

No Reports

No report has been received because either an error occurred during the virt-who configuration deployment, or the configuration has not been deployed yet, or virt-who cannot connect to orcharhino during the scheduled interval.

No Change

No report has been received because hypervisor did not detect any changes on the virtual machines, or virt-who failed to upload the reports during the scheduled interval. If you added a virtual machine but the configuration is in the No Change state, check that virt-who is running.

OK

The report has been received without any errors during the scheduled interval.

Total Configurations

A total number of virt-who configurations.

Click the configuration status to see all configurations in this state.

The widget also lists the three latest configurations in the No Change state under Latest Configurations Without Change.

Latest Compliance Reports

A list of the latest compliance reports. Each compliance report shows several rules passed (P), failed (F), or othered (O). Click the host for the detailed compliance report. Click the policy for more details on that policy.

Compliance Reports Breakdown

A pie chart shows the distribution of compliance reports according to their status.

Insights Actions

Insights is a tool embedded in orcharhino that checks the environment and suggests actions you can take. The actions are divided into 4 categories: Availability, Stability, Performance, and Security.

Insights Risk Summary

A table shows the distribution of the actions according to the risk levels. Risk level represents how critical the action is and how likely it is to cause an actual issue. The possible risk levels are: Low, Medium, High, and Critical.

14.2. orcharhino task management

You can monitor and manage all planned or performed tasks, such as repositories synchronized, errata applied, and content views published. This is useful to track progress, troubleshoot issues, or adjust timeout settings for low bandwidth or high latency environments.

Reviewing the log

To review the log, in the orcharhino management UI, navigate to Monitor > orcharhino Tasks > Tasks.

In the Task window, you can search for specific tasks, view their status, details, and elapsed time since they started. You can also cancel and resume one or more tasks.

The tasks are managed using the Dynflow engine. Remote tasks have a timeout which can be adjusted as needed.

Adjusting timeout settings

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

  2. Enter %_timeout in the search box and click Search. The search should return four settings, including a description.

  3. In the Value column, click the icon next to a number to edit it.

  4. Enter the desired value in seconds, and click Save.

    Note

    Adjusting the %_finish_timeout values might help in case of low bandwidth. Adjusting the %_accept_timeout values might help in case of high latency.

When a task is initialized, any back-end service that will be used in the task, such as Candlepin or Pulp, will be checked for correct functioning. If the check fails, you will receive an error similar to the following one:

There was an issue with the backend service candlepin: Connection refused – connect(2).

If the back-end service checking feature turns out to be causing any trouble, it can be disabled as follows.

Disabling checking for services

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

  2. Enter check_services_before_actions in the search box and click Search.

  3. In the Value column, click the icon to edit the value.

  4. From the drop-down menu, select false.

  5. Click Save.

14.3. Configuring RSS notifications

You can configure custom RSS feed notifications to receive event alerts from your preferred sources, such as project blogs or internal news feeds, instead of the default notification sources.

To view orcharhino event notification alerts, click the Notifications icon in the upper right of the screen.

By default, the Notifications area displays RSS feed events published in the orcharhino news.

The feed is refreshed every 12 hours and the Notifications area is updated whenever new events become available.

You can configure the RSS feed notifications by changing the URL feed. The supported feed format is RSS 2.0 and Atom.

Procedure

  1. In the orcharhino management UI, navigate to Administer > Settings and select the Notifications tab.

  2. In the RSS URL row, click the edit icon in the Value column and type the required URL.

  3. In the RSS enable row, click the edit icon in the Value column to enable or disable this feature.

14.4. Monitoring orcharhino Server

Audit records list the changes made by all users on orcharhino. You can use this information for maintenance and troubleshooting.

Procedure

  1. In the orcharhino management UI, navigate to Monitor > Audits to view the audit records.

  2. Obtain a list of all audit attributes:

    # foreman-rake audits:list_attributes

14.5. Monitoring orcharhino Proxy Server

In the orcharhino management UI, you can find various information about orcharhino Proxy Server and its services. This information is useful to maintain orcharhino Proxy Server and troubleshoot any issues.

14.5.1. Viewing general orcharhino Proxy information

You can view general information about your orcharhino Proxies in the orcharhino management UI, such as their status, enabled features, and managed hosts, to verify configuration or troubleshoot connectivity issues.

In the orcharhino management UI, navigate to Infrastructure > orcharhino Proxies to view a table of orcharhino Proxy Servers registered to orcharhino Server. The information contained in the table answers the following questions:

Is orcharhino Proxy Server running?

This is indicated by a green icon in the Status column. A red icon indicates an inactive orcharhino Proxy, use the service foreman-proxy restart command on orcharhino Proxy Server to activate it.

What services are enabled on orcharhino Proxy Server?

In the Features column, you can verify if, for example, your orcharhino Proxy provides a DHCP service or acts as a Pulp mirror. orcharhino Proxy features can be enabled during installation or configured in addition. For more information, see Installing orcharhino Proxy Server.

What organizations and locations is orcharhino Proxy Server assigned to?

A orcharhino Proxy Server can be assigned to multiple organizations and locations, but only orcharhino Proxies belonging to the currently selected organization are displayed. To list all orcharhino Proxies, select Any Organization from the context menu in the top left corner.

After changing the orcharhino Proxy configuration, select Refresh from the drop-down menu in the Actions column to ensure the orcharhino Proxy table is up to date.

Click the orcharhino Proxy name to view further details. At the Overview tab, you can find the same information as in the orcharhino Proxy table. In addition, you can answer to the following questions:

Which hosts are managed by orcharhino Proxy Server?

The number of associated hosts is displayed next to the Hosts managed label. Click the number to view the details of associated hosts.

How much storage space is available on orcharhino Proxy Server?

The amount of storage space occupied by the Pulp content in /var/lib/pulp is displayed. Also the remaining storage space available on the orcharhino Proxy can be ascertained.

14.5.2. Monitoring orcharhino Proxy services

You can view the status and configuration details of orcharhino Proxy services in orcharhino management UI. This helps you verify that your orcharhino Proxy services are running correctly and troubleshoot any issues.

Procedure

  • In the orcharhino management UI, navigate to Infrastructure > orcharhino Proxies and click the name of the selected orcharhino Proxy.

    • At the Services tab, you can find basic information on orcharhino Proxy services, such as the list of DNS domains, or the number of Pulp workers.

      The appearance of the page depends on what services are enabled on orcharhino Proxy Server. Services providing more detailed status information can have dedicated tabs at the orcharhino Proxy page. For more information, see Monitoring Puppet on orcharhino Proxy.

14.5.3. Monitoring Puppet on orcharhino Proxy

You can monitor Puppet activity and certificate management for each orcharhino Proxy.

Note

The Puppet and Puppet CA tabs are available only if you have Puppet enabled in your orcharhino.
Procedure

  1. In the orcharhino management UI, navigate to Infrastructure > orcharhino Proxies.

  2. Click the name of your orcharhino Proxy.

    • At the Puppet tab you can find the following:

      • A summary of Puppet events, an overview of latest Puppet runs, and the synchronization status of associated hosts at the General sub-tab.

      • A list of Puppet environments at the Environments sub-tab.

    • At the Puppet CA tab you can find the following:

      • A certificate status overview and the number of autosign entries at the General sub-tab.

      • A table of CA certificates associated with the orcharhino Proxy at the Certificates sub-tab. Here you can inspect the certificate expiry data, or cancel the certificate by clicking Revoke.

      • A list of autosign entries at the Autosign entries sub-tab. Here you can create an entry by clicking New or delete one by clicking Delete.

Additional resources

15. Limiting host resources

You can use the Resource Quota plugin to limit users' access to host resources during host provisioning. Each host is assigned to exactly one resource quota. By default, orcharhino assigns the Unassigned resource quota to hosts during global registration. This means that the host is not assigned to a specific pool of resources.

In a typical usage scenario, orcharhino manages multiple compute resources for multiple departments. To share managed resources in a fair and predictable way, administrators can assign resource quotas to users and user groups.

Supported resource types

  • CPU cores

  • Memory

  • Disk space

Supported compute resources

  • VMware

  • libvirt

Additional resources

15.1. Installing the Resource Quota plugin

To limit host resources for your orcharhino users, install the Resource Quota plugin.

Procedure

  1. Install the plugin on your orcharhino Server:

    # orcharhino-installer --enable-foreman-plugin-resource-quota

  2. Optional: Install the Hammer CLI plugin on your orcharhino Server:

    # orcharhino-installer --enable-foreman-cli-resource-quota

15.2. Managing resource quotas

You can create, edit, and delete resource quotas in orcharhino management UI. All resource quotas are listed on Configure > Resource Quotas.

15.2.1. Creating a resource quota by using orcharhino management UI

Create a resource quota to limit the resource consumption of orcharhino users by using the orcharhino management UI.

Procedure

  1. In the orcharhino management UI, navigate to Configure > Resource Quotas.

  2. Click Create resource quota.

  3. Specify the name, CPU cores, memory, and disk space.

  4. Click Create resource quota to submit the resource quota to orcharhino.

15.2.2. Creating a resource quota by using Hammer CLI

Create a resource quota to limit the resource consumption of orcharhino users by using Hammer CLI.

Procedure

  • Create a resource quota:

    $ hammer resource-quota create \
--cpu-cores My_CPU_Cores \
--description My_Resource_Quota_Description \
--disk-space My_Disk_Space_in_GiB \
--memory My_Memory_in_MiB \
--name "My_Resource_Quota_Name"

    For all options, see hammer resource-quota create --help.

15.2.3. Editing a resource quota by using orcharhino management UI

You can edit a resource quota to adjust available resources to orcharhino users by using orcharhino management UI.

Procedure

  1. In the orcharhino management UI, navigate to Configure > Resource Quotas.

  2. Select your resource quota.

  3. Adjust the CPU cores, Memory, or Disk space and click Apply to submit your changes to orcharhino.

  4. Click Create resource quota to submit the resource quota to orcharhino.

15.2.4. Editing a resource quota by using Hammer CLI

You can edit a resource quota to adjust available resources to orcharhino users by using Hammer CLI.

Procedure

  1. Optional: List all resource quotas:

    $ hammer resource-quota list --fields id,name

  2. Edit a resource quota:

    $ hammer resource-quota update \
--cpu-cores My_CPU_Cores \
--description My_Resource_Quota_Description \
--disk-space My_Disk_Space_in_GiB \
--id My_Resource_Quota_ID \
--memory My_Memory_in_MiB \
--name "My_Resource_Quota_Name"

    If you set the value to 0, users cannot consume any resource at all. To reset resource quotas, you can use --remove-cpu-cores-limit, --remove-disk-space-limit, and --remove-memory-limit.

    For all options, see hammer resource-quota update --help.

15.2.5. Deleting a resource quota by using orcharhino management UI

You can delete a resource quota from orcharhino by using orcharhino management UI.

Procedure

  1. In the orcharhino management UI, navigate to Configure > Resource Quotas.

  2. In the Actions column, click Delete for your resource quota.

15.2.6. Deleting a resource quota by using Hammer CLI

You can delete a resource quota from orcharhino by using Hammer CLI.

Procedure

  1. Optional: List all resource quotas:

    $ hammer resource-quota list --fields id,name

  2. Delete a resource quota:

    $ hammer resource-quota delete --id My_Resource_Quota_ID

    For all options, see hammer resource-quota delete --help.

15.3. Assigning resource quotas to users

You can assign resource quotas to users or user groups. A user can select one of their assigned resource quotas during host provisioning. If Resource Quota optional assignment is set to No, a user does not have to assign a resource quota. You can use the resource_quota filter in the orcharhino management UI to view users or user groups with assigned resource quotas.

If you want to introduce resource quotas to your organization, set Global Resource Quota no action to Yes to allow users to provision hosts even if they exceed their resource quotas.

15.3.1. Assigning resource quotas to a user by using orcharhino management UI

You can assign resource quotas to a user to limit the resource consumption of that orcharhino user by using orcharhino management UI.

Procedure

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

  2. Select a user.

  3. On the Resource Quota tab, assign resource quotas to the user.

  4. If you want to make the usage of resource quotas optional, select the Optional Assignment checkbox.

    This means that orcharhino will not prevent users from consuming more resources than their assigned quota.

  5. Click Submit to assign resource quotas to a user.

15.3.2. Assigning resource quotas to a user by using Hammer CLI

You can assign resource quotas to a user to limit the resource consumption of that orcharhino user by using Hammer CLI

Procedure

  1. Optional: List all orcharhino users:

    $ hammer user list --fields id,login

  2. Optional: List all resource quotas:

    $ hammer resource-quota list --fields id,name

  3. Assign resource quotas to a user:

    $ hammer user update \
--id My_User_ID \
--resource-quota-ids My_Resource_Quota_IDs

    If you want to make resource quota optional, add the --resource-quota-is-optional true option.

    For all options, see hammer user update --help.

15.3.3. Assigning resource quotas to a user group by using orcharhino management UI

You can assign resource quotas to a user group to limit the resource consumption of that orcharhino user group. All users of the user group share the pool of resources.

Procedure

  1. In the orcharhino management UI, navigate to Administer > User Groups.

  2. On the Resource Quota tab, assign resource quotas to the user group.

  3. Click Submit to assign resource quotas to a user group.

15.3.4. Assigning resource quotas to a user group by using Hammer CLI

You can assign resource quotas to a user group to limit the resource consumption of that orcharhino user group by using Hammer CLI. All users of the user group share the pool of resources.

Procedure

  1. Optional: List all orcharhino user groups:

    $ hammer user-group list --fields id,name

  2. Optional: List all resource quotas:

    $ hammer resource-quota list --fields id,name

  3. Assign resource quotas to a user group:

    $ hammer user-group update \
--id My_User_Group_ID \
--resource-quota-ids My_Resource_Quota_IDs

    For all options, see hammer user-group update --help.

15.4. Viewing resource quotas by using orcharhino management UI

You can use orcharhino management UI to view the resource quota of hosts.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > All Hosts.

  2. In the search bar, filter your hosts. For example, resource_quota = Unassigned.

    For more information, see Working efficiently with orcharhino management UI.

15.5. Viewing resource quotas by using Hammer CLI

You can use Hammer CLI to view the resource quota of hosts.

Procedure

  1. Optional: Retrieve the ID of your host:

    $ hammer host list

  2. Display the resource quota assigned to your host:

    $ hammer host info \
--fields "Id,Name,Resource quota id" \
--id My_Host_ID

15.6. Resource Quota settings

You can configure the following global orcharhino settings for the Resource Quota plugin:

Global Resource Quota no action

orcharhino will not limit the resource consumption if a resource quota is exceeded.

Resource Quota optional assignment

orcharhino will not enforce selecting a resource quota during host provisioning. The global setting overwrites user-specific and user group-specific configuration options.

You can find the Resource Quota settings by navigating to Administer > Settings > Provisioning.

16. Using webhooks in orcharhino

A webhook is a way for a web page or web application to provide other applications with information in real time. You can use webhooks to define a call to an external API based on orcharhino internal event by using a fire-and-forget message exchange pattern.

16.1. Webhook behavior and integration

You can use webhooks as a way to integrate orcharhino with external systems. For example, webhooks can integrate with monitoring systems to send alerts when a host is created or deleted.

Webhooks are only triggered after an event occurs. The request usually contains details of the event. An event triggers callbacks, such as sending an e-mail confirming a host has been provisioned. The application sending the request does not wait for the response, or ignores it.

Because webhooks use HTTP, no new infrastructure needs be added to existing web services. Webhooks are useful where the action you want to perform in the external system can be achieved through its API.

Where it is necessary to run additional commands or edit files, the shellhooks plugin for orcharhino Proxies is available. The shellhooks plugin enables you to define a shell script on the orcharhino Proxy that can be executed through the API.

You can use webhooks successfully without installing the shellhooks plugin.

Payload of a webhook is created from webhook templates. Webhook templates use the same ERB syntax as Provisioning templates. Available variables:

  • @event_name: Name of an event.

  • @webhook_id: Unique event ID.

  • @payload: Payload data, different for each event type. To access individual fields, use @payload[:key_name] Ruby hash syntax.

  • @payload[:object]: Database object for events triggered by database actions (create, update, delete). Not available for custom events.

  • @payload[:context]: Additional information as hash like request and session UUID, remote IP address, user, organization and location.

Additional resources

16.2. Installing the webhooks plugin

Use the following procedure to install the webhooks plugin. Then, you can configure orcharhino Server to send webhook requests.

Procedure

  1. On your orcharhino Server, install the webhooks plugin:

    # orcharhino-installer --enable-foreman-plugin-webhooks

  2. Optional: Install the webhooks CLI plugin:

    # orcharhino-installer --enable-foreman-cli-webhooks

16.3. Creating a webhook template

Webhook templates are used to generate the body of HTTP request to a configured target when a webhook is triggered. You can create a webhook template in the orcharhino management UI.

Procedure

  1. In the orcharhino management UI, navigate to Administer > Webhook > Webhook Templates.

  2. Click Clone an existing template or Create Template.

  3. Enter a name for the template.

  4. Use the editor to make changes to the template payload.

    A webhook HTTP payload must be created using orcharhino template syntax. The webhook template can use a special variable called @object that can represent the main object of the event. @object can be missing in case of certain events. You can determine what data are actually available with the @payload variable.

    For more information, see Template Writing Reference in Managing hosts and for available template macros and methods, visit /templates_doc on orcharhino Server.

  5. Optional: Enter the description and audit comment.

  6. Assign organizations and locations.

  7. Click Submit.

Example 3. Creating a webhook template

When creating a webhook template, you must follow the format of the target application for which the template is intended. For example, an application can expect a "text" field with the webhook message. Refer to the documentation of your target application to find more about how your webhook template format should look like.

Running remote execution jobs

This webhook template defines a message with the ID and result of a remote execution job. The webhook which uses this template can be subscribed to events such as Actions Remote Execution Run Host Job Succeeded or Actions Remote Execution Run Host Job Failed.

{
    "text": "job invocation <%= @object.job_invocation_id %> finished with result <%= @object.task.result %>"
}
Creating users

This webhook template defines a message with the login and email of a created user. The webhook which uses this template should be subscribed to the User Created event.

{
    "text": "user with login <%= @object.login %> and email <%= @object.mail %> created"
}

16.4. Creating a webhook

When creating a webhook in the orcharhino management UI, you can customize events, payloads, HTTP authentication, content type, and headers.

Procedure

  1. In the orcharhino management UI, navigate to Administer > Webhook > Webhooks.

  2. Click Create new.

  3. From the Subscribe to list, select an event.

  4. Enter a Name for your webhook.

  5. Enter a Target URL. Webhooks make HTTP requests to pre-configured URLs. The target URL can be a dynamic URL.

  6. Click Template to select a template. Webhook templates are used to generate the body of the HTTP request to orcharhino Server when a webhook is triggered.

  7. Enter an HTTP method.

  8. Optional: If you do not want activate the webhook when you create it, uncheck the Enabled flag.

  9. Click the Credentials tab.

  10. Optional: If HTTP authentication is required, enter User and Password.

  11. Optional: Uncheck Verify SSL if you do not want to verify the server certificate against the system certificate store or orcharhino CA.

  12. On the Additional tab, enter the HTTP Content Type. For example, application/json, application/xml or text/plain on the payload you define. The application does not attempt to convert the content to match the specified content type.

  13. Optional: Provide HTTP headers as JSON. ERB is also allowed.

16.5. Available webhook events

Review the webhook events that are available from the orcharhino management UI.

Action events trigger webhooks only on success, so if an action fails, a webhook is not triggered.

For more information about payload, go to Administer > About > Support > Templates DSL. A list of available types is provided in the following table. Some events are marked as custom, in that case, the payload is an object object but a Ruby hash (key-value data structure) so syntax is different.

Event name Description Payload

Actions Katello Content View Promote Succeeded

A content view was successfully promoted.

Actions::Katello::ContentView::Promote

Actions Katello Content View Publish Succeeded

A repository was successfully synchronized.

Actions::Katello::ContentView::Publish

Actions Remote Execution Run Host Job Succeeded

A generic remote execution job succeeded for a host. This event is emitted for all Remote Execution jobs, when complete.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Katello Errata Install Succeeded

Install errata using the Katello interface.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Katello Group Install Succeeded

Install package group using the Katello interface.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Katello Package Install Succeeded

Install package using the Katello interface.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Katello Group Remove

Remove package group using the Katello interface.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Katello Package Remove Succeeded

Remove package using the Katello interface.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Katello Service Restart Succeeded

Restart Services using the Katello interface.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Katello Group Update Succeeded

Update package group using the Katello interface.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Katello Package Update Succeeded

Update package using the Katello interface.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Foreman OpenSCAP Run Scans Succeeded

Run OpenSCAP scan.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Ansible Run Host Succeeded

Runs an Ansible Playbook containing all the roles defined for a host.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Ansible Run orcharhino Proxy Upgrade Succeeded

Upgrade orcharhino Proxies on given orcharhino Proxy Servers.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Ansible Configure Cloud Connector Succeeded

Configure Cloud Connector on given hosts.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Ansible Run Playbook Succeeded

Run an Ansible Playbook against given hosts.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Ansible Enable Web Console Succeeded

Run an Ansible Playbook to enable the web console on given hosts.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Puppet Run Host Succeeded

Perform a single Puppet run.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Katello Module Stream Action Succeeded

Perform a module stream action using the Katello interface.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Leapp Pre-upgrade Succeeded

Upgradeability check for RHEL 7 host.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Leapp Remediation Plan Succeeded

Run Remediation plan with Leapp.

Actions::RemoteExecution::RunHostJob

Actions Remote Execution Run Host Job Leapp Upgrade Succeeded

Run Leapp upgrade job for RHEL 7 host.

Actions::RemoteExecution::RunHostJob

Build Entered

A host entered the build mode.

Custom event: @payload[:id] (host id), @payload[:hostname] (host name).

Build Exited

A host build mode was canceled, either it was successfully provisioned or the user canceled the build manually.

Custom event: @payload[:id] (host id), @payload[:hostname] (host name).

Config Report Created/Updated/Destroyed

Common database operations on a configuration report.

ConfigReport

Content View Created/Updated/Destroyed

Common database operations on a content view.

Katello::ContentView

Domain Created/Updated/Destroyed

Common database operations on a domain.

Domain

Host Created/Updated/Destroyed

Common database operations on a host.

Host

Hostgroup Created/Updated/Destroyed

Common database operations on a hostgroup.

Hostgroup

Model Created/Updated/Destroyed

Common database operations on a model.

Model

Status Changed

Global host status of a host changed.

Custom event: @payload[:id] (host id), @payload[:hostname], @payload[:global_status] (hash)

Subnet Created/Updated/Destroyed

Common database operations on a subnet.

Subnet

Template Render Performed

A report template was rendered.

Template

User Created/Updated/Destroyed

Common database operations on a user.

User

16.6. Shellhooks plugin for orcharhino Proxy

With webhooks, you can only map one orcharhino event to one API call. For advanced integrations, where a single shell script can contain multiple commands, you can install a orcharhino Proxy shellhooks plugin that exposes executables by using a REST HTTP API.

You can then configure a webhook to reach out to a orcharhino Proxy API to run a predefined shellhook. A shellhook is an executable script that can be written in any language provided that it can be executed. The shellhook can for example contain commands or edit files.

You must place your executable scripts in /var/lib/foreman-proxy/shellhooks with only alphanumeric characters and underscores in their name.

You can pass input to shellhook script through the webhook payload. This input is redirected to standard input of the shellhook script. You can pass arguments to shellhook script by using HTTP headers in format X-Shellhook-Arg-1 to X-Shellhook-Arg-99.

The HTTP method must be POST. An example URL would be: https://orcharhino-proxy.example.com:9090/shellhook/My_Script.

Note

Unlike the shellhooks directory, the URL must contain /shellhook/ in singular to be valid.

You must enable orcharhino Proxy Authorization for each webhook connected to a shellhook to enable it to authorize a call.

Standard output and standard error output are redirected to the orcharhino Proxy logs as messages with debug or warning levels respectively.

The shellhook HTTPS calls do not return a value.

Additional resources

16.7. Installing the shellhooks plugin

Optionally, you can install and enable the shellhooks plugin on each orcharhino Proxy used for shellhooks.

Procedure

  • Install the shellhooks plugin on your orcharhino Proxy:

    # orcharhino-installer --enable-foreman-proxy-plugin-shellhooks

16.8. Passing arguments to shellhook script using webhooks

You can pass dynamic values from a webhook event to a shellhook script by configuring HTTP headers when you create the webhook. This enables your script to use event-specific data such as object IDs or names without parsing the webhook payload.

Procedure

  • When creating a webhook, on the Additional tab, create HTTP headers in the following format:

    {
  "X-Shellhook-Arg-1": "VALUE",
  "X-Shellhook-Arg-2": "VALUE"
}

    Ensure that the headers have a valid JSON or ERB format. Only pass safe fields like database ID, name, or labels that do not include new lines or quote characters.

    For more information, see Creating a webhook.

Example 4. Passing arguments to shellhook script using webhooks
{
  "X-Shellhook-Arg-1": "<%= @object.content_view_version_id %>",
  "X-Shellhook-Arg-2": "<%= @object.content_view_name %>"
}

16.9. Passing arguments to shellhook script using curl

You can pass custom values to a shellhook script by using a curl request. Use this when you need to test a script manually or call it directly, rather than through webhook automation.

Procedure

  • When executing a shellhook script using curl, create HTTP headers in the following format:

    "X-Shellhook-Arg-1: VALUE"
"X-Shellhook-Arg-2: VALUE"
Example 5. Passing arguments to shellhook script using curl
$ curl \
--data "" \
--header "Content-Type: text/plain" \
--header "X-Shellhook-Arg-1: Version 1.0" \
--header "X-Shellhook-Arg-2: My content view" \
--request POST \
--show-error \
--silent \
https://orcharhino-proxy.example.com:9090/shellhook/My_Script

16.10. Creating a shellhook to print arguments

Create a simple shellhook script that prints Hello World! when you run a remote execution job.

Prerequisites
Procedure

  1. Modify the /var/lib/foreman-proxy/shellhooks/print_args script to print arguments to standard error output so you can see them in the orcharhino Proxy logs:

    #!/bin/sh
#
# Prints all arguments to stderr
#
echo "$@" >&2

  2. In the orcharhino management UI, navigate to Administer > Webhook > Webhooks.

  3. Click Create new.

  4. From the Subscribe to list, select Actions Remote Execution Run Host Job Succeeded.

  5. Enter a Name for your webhook.

  6. In the Target URL field, enter the URL of your orcharhino Proxy Server followed by :9090/shellhook/print_args:

    https://orcharhino-proxy.example.com:9090/shellhook/print_args

    Note that shellhook in the URL is singular, unlike the shellhooks directory.

  7. From the Template list, select Empty Payload.

  8. On the Credentials tab, check orcharhino Proxy Authorization.

  9. On the Additional tab, enter the following text in the Optional HTTP headers field:

    {
    "X-Shellhook-Arg-1": "Hello",
    "X-Shellhook-Arg-2": "World!"
}

  10. Click Submit. You now have successfully created a shellhook that prints "Hello World!" to orcharhino Proxy logs every time you a remote execution job succeeds.

Verification

  1. Run a remote execution job on any host. You can use time as a command. For more information, see Configuring and setting up remote jobs in Managing hosts.

  2. Verify that the shellhook script was triggered and printed "Hello World!" to orcharhino Proxy Server logs:

    # tail /var/log/foreman-proxy/proxy.log

    You should find the following lines at the end of the log:

    [I] Started POST /shellhook/print_args
[I] Finished POST /shellhook/print_args with 200 (0.33 ms)
[I] [3520] Started task /var/lib/foreman-proxy/shellhooks/print_args\ Hello\ World\!
[W] [3520] Hello World!

17. Working efficiently with orcharhino management UI

The orcharhino management UI includes search, bookmarking, keyboard shortcuts, and various settings to help you work more efficiently.

17.1. Efficiency tips for orcharhino management UI

Use these keyboard shortcuts and techniques to navigate and search more efficiently in the orcharhino management UI.

Ctrl + Shift + F focuses the vertical navigation search bar

After pressing this shortcut, you can start typing in the vertical navigation search bar.

/ focuses the page search bar

After pressing this shortcut, you can start typing in the page search bar.

Saving searches as bookmarks

You can save a search you frequently use as a bookmark. After entering your search query in the search field, click the arrow next to the Search button and select Bookmark this search. You can then give the bookmark a name and choose whether to make it public or private.

To manage all bookmarks, navigate to Administer > Bookmarks.

Compact table mode

Navigate to the user menu in the top bar and select My account. Under the UI Preferences tab, you can enable compact table mode. With compact table mode enabled, orcharhino management UI displays table rows with less space between items.

Instance title setting

If you have multiple orcharhino instances, you can configure orcharhino management UI to always show a banner with the instance title in the top bar to help you identify which instance you are currently using. To set an instance title, navigate to Administer > Settings, and edit the Instance title setting on the General tab. To set a color for the instance title banner, edit the Instance color setting.

17.2. orcharhino management UI search query reference

Use search query syntax and operators in the orcharhino management UI to filter lists of resources on orcharhino management UI pages. Parameter-based queries help you find the resources you need faster and more precisely than free-text search in large inventories.

Search queries in the page search bar follow the pattern:

parameter operator value

To search text with whitespaces, enclose it in quotes:

hostgroup = "Web Servers"

Typing without specifying a parameter searches across multiple fields simultaneously, also known as free-text search. For example, typing 64 in the search bar on the hosts page displays all hosts that have 64 in their name, IP address, MAC address, and architecture.

Note

Free text search is slower and less accurate than parameter-based queries. Use specific parameters whenever possible for better performance and precision.

The search bar supports multiple date and time formats, including the following:

  • "10 January 2017"

  • "10 Jan 2017"

  • 10-January-2017

  • 10/January/2017

  • "January 10, 2017"

  • Today, yesterday, and similar keywords

Table 7. Comparison operators accepted by search
Operator Short Name Description

=

EQUALS

Accepts numerical, temporal, or text values. For text, exact case sensitive matches are returned.

!=

NOT EQUALS

~

LIKE

Accepts text or temporal values. The search is not case-sensitive. Accepts the following wildcards: _ for a single character, % or * for any number of characters including zero. If no wildcard is specified, the string is treated as if surrounded by wildcards: %rhel7%

!~

NOT LIKE

>

GREATER THAN

Accepts numerical or temporal values. For temporal values, the operator > is interpreted as "later than", and < as "earlier than". Both operators can be combined with EQUALS: >= <=

<

LESS THAN

^

IN

Compares an expression against a list of values, as in SQL. Returns matches that contain or not contain the values, respectively.

!^

NOT IN

HAS or set?

 

Returns values that are present or not present, respectively.

NOT HAS or null?

 
Table 8. Logical operators accepted by search
Operator Alternative Notations

and

&

&&

<whitespace>

or

|

||

 

not

–

!

 

17.3. Useful search examples

The following examples demonstrate useful ways to filter and find resources in orcharhino management UI. Use them as starting points to build your own searches that match your specific needs.

These search examples show how to filter hosts and are based on host attribute search parameters. You can use them on orcharhino management UI pages that list hosts, such as Hosts > All Hosts. You can apply the same syntax to filter other resources on other orcharhino management UI pages.

Find hosts by host global status and sub-status

Hosts that have an OK global status:

global_status = ok

Hosts that have an Error or Warning global status:

global_status = error or global_status = warning

Hosts that have at least one pending resource:

status.pending > 0

Hosts that restarted some service during last run:

status.restarted > 0

Hosts that have an interesting last run that might indicate something has happened:

status.interesting = true
Find hosts that need attention

Hosts with security updates available:

errata_status = security_needed

Hosts that have email notifications for configuration errors enabled and are in a failed state:

status.enabled = true AND status.failed = true

Hosts that have not generated a report recently:

last_report < "7 days ago"
Find hosts by configuration, environment, or registration date

Hosts in production that belong to a host group whose name includes a variation of the word "webservers":

environment = production AND hostgroup ~ webservers

Hosts registered in the last month:

registered_at > "30 days ago"

Hosts registered between specific dates:

registered_at > 1-January-2026 AND registered_at < 31-January-2026
Exclude specific results

All hosts except hosts in a host group named "exceptions":

NOT hostgroup = exceptions

Hosts that are not compliant with policies:

compliance_status != compliant

This search query requires the OpenSCAP plugin.

Use wildcards for flexible matching

Hosts with names that include the strings "web" and "prod":

name ~ web*prod*

Host groups starting with a specific prefix:

hostgroup ~ rhel%

Appendix A: Starting and stopping orcharhino services

orcharhino provides the foreman-maintain service command to manage orcharhino services from the command line.

After installing orcharhino with the orcharhino-installer command, all orcharhino services are started and enabled automatically. View the list of these services by executing:

# foreman-maintain service list

To see the status of running services, execute:

# foreman-maintain service status

To stop orcharhino services, execute:

# foreman-maintain service stop

To start orcharhino services, execute:

# foreman-maintain service start

To restart orcharhino services, execute:

# foreman-maintain service restart

Appendix B: Logging and reporting problems

Review the most commonly used log files and debugging tools available in orcharhino.

B.1. Configuring logging type and layout

By default, orcharhino uses file-based logging. You can use orcharhino-installer to change the logging type and logging layout.

Procedure

  1. To use the journald service for logging:

    1. Change the logging type to journald:

      # orcharhino-installer \
--foreman-logging-type journald \
--foreman-proxy-log JOURNAL

    2. Inspect the log messages by using the journalctl utility. For example:

      • journalctl --unit foreman and journalctl --unit foreman-proxy show messages for the foreman and foreman-proxy units

      • journalctl REQUEST=request_ID shows messages for a specified request

  2. To use file-based logging:

    1. Change the logging type to file-based:

      # orcharhino-installer \
--reset-foreman-logging-type \
--reset-foreman-proxy-log

    2. Inspect the log messages by viewing these files:

      • /var/log/foreman/production.log

      • /var/log/foreman-proxy.log

  3. To use JSON output:

    1. Change the logging layout to JSON:

      # orcharhino-installer \
--foreman-logging-layout json \
--foreman-logging-type file

    2. Inspect the log messages by using jq:

      # cat /var/log/foreman/production.log | jq

B.2. Enabling individual loggers for selective debugging

You can enable individual loggers to collect detailed diagnostics for specific orcharhino components when you troubleshoot integration or performance issues, without increasing the global logging level.

Procedure

  1. Enable the required individual loggers. For example, to enable sql and ldap loggers, enter the following command:

    # orcharhino-installer \
--foreman-loggers ldap:true \
--foreman-loggers sql:true

  2. Optional: Reset all loggers to their default values:

    # orcharhino-installer --reset-foreman-loggers

B.3. Overview of individual loggers

Review selected loggers and their default values. You can find the complete list of loggers with their default values in /usr/share/foreman/config/application.rb under Foreman::Logging.add_loggers.

app

Logs web requests and all general application messages.

Default value: true.

audit

Logs additional fact statistics, numbers of added, updated, and removed facts.

Default value: true.

background

Logs information from the background processing component.

blob

Logs contents of rendered templates for auditing purposes.

Important

The blob logger might contain sensitive data.
dynflow

Logs information from the Dynflow process.

ldap

Logs high level LDAP queries and LDAP operations.

Default value: false.

notifications

Logs information from the notifications component.

permissions

Logs queries to user roles, filters, and permissions when loading pages.

Default value: false.

sql

Logs SQL queries made through Rails ActiveRecord.

Default value: false.

telemetry

Logs debugging information from telemetry.

templates

Logs information from the template renderer component.

B.4. Retrieving the status of services by using Hammer CLI

orcharhino uses a set of back-end services. When troubleshooting, you can check the status of orcharhino services by using Hammer CLI.

Procedure

  • Get information from the database and orcharhino services:

    $ hammer ping

  • Check the status of the services running in systemd:

    # foreman-maintain service status

    Run foreman-maintain service --help for more information.

  • Perform a health check:

    $ foreman-maintain health check

    Run foreman-maintain health --help for more information.

B.5. Restarting orcharhino services

orcharhino uses a set of back-end services. When troubleshooting, you can restart the services if needed.

Procedure

  • Restart orcharhino services:

    # foreman-maintain service restart

B.6. Utilities for processing log information

You can collect information from log files to troubleshoot orcharhino.

sosreport

The sos report command collects configuration and diagnostic information from a Linux system, such as the running kernel version, loaded modules, running services, and system and service configuration files. Additionally, it collects information about orcharhino, such as its back-end services and tasks. This output is stored in a tar file located at /var/tmp/sosreport-XXX-20171002230919.tar.xz.

For more information, run sos report --help or see SOS user documentation.

Important

The sos report command removes security information such as passwords, tokens, and keys while collecting information. However, the tar files can still contain sensitive information about the orcharhino Server. Send the tar files directly to the intended recipient and not to a public target.
foreman-tail

The foreman-tail command displays orcharhino logs in real time.

For more information, see the foreman-tail(8) man page.

B.7. Log file directories

The following table provides an overview of selected log directories on orcharhino Server.

Log file directory Description of log file content

/var/log/candlepin/

Subscription management

/var/log/foreman-installer/

Installer

/var/log/foreman-maintain/

Foreman maintain

/var/log/foreman-proxy/

Foreman proxy

/var/log/foreman/

Foreman

/var/log/httpd/

Apache HTTP server

/var/log/messages/

Various other log messages

/var/log/puppetlabs/puppet/

Puppet

/var/log/tomcat/

Candlepin web service logs

B.8. System journal metadata

The journald service uses metadata fields to filter logs. You can use these fields to filter logs when troubleshooting.

AUDIT_ACTION

Audit action performed

Example: Create, update, or delete

AUDIT_TYPE

Audit resource type

Example: Host, Subnet, or ContentView

AUDIT_ID

Audit resource database ID as a number

AUDIT_ATTRIBUTE

Audit resource field or an updated database column

AUDIT_FIELD_OLD

Old audit value of an update action

AUDIT_FIELD_NEW

New audit value of an update action

AUDIT_ID

Record database ID of the audit subject

AUDIT_ATTRIBUTE

Attribute name or column on which an action was performed

Example: Name or description

EXCEPTION_MESSAGE

Exception message when error is logged

EXCEPTION_CLASS

Exception Ruby class when error is logged

EXCEPTION_BACKTRACE

Exception backtrace as a multiline string when error is logged

LOC_ID

Location database ID

LOC_NAME

Location name

LOC_LABEL

Location label

LOGGER

Logger name

To see the current list of loggers enabled by default, enter this command:

# awk '/add_loggers/,/^$/' /usr/share/foreman/config/application.rb
ORG_ID

Organization database ID

ORG_NAME

Organization name

ORG_LABEL

Organization label

REMOTE_IP

Remote IP address of a client

REQUEST

Request ID generated by the Action Dispatch module

SESSION

Random ID generated per session or a request for a sessionless request

TEMPLATE_NAME

Template name

TEMPLATE_DIGEST

Digest (SHA256) of rendered template contents

TEMPLATE_HOST_NAME

Host name for a rendered template if present

TEMPLATE_HOST_ID

Host database ID for a rendered template if present

USER_LOGIN

User login name

Appendix C: Increasing logging levels of orcharhino components

orcharhino components use configurable logging levels to record operational events. Increase the level to debug when you need detailed output to troubleshoot a specific service.

C.1. Increasing the logging level for Foreman

Increase Foreman logging to debug to capture detailed orcharhino activity when diagnosing application or API issues. Reset the level when debugging is complete to avoid excessive log volume.

By default, Foreman writes logs to /var/log/foreman/production.log. For more information, see Configuring logging type and layout.

Note

For more information about orcharhino logging settings, use orcharhino-installer with the --full-help option:

# orcharhino-installer --full-help | grep logging
Procedure

  1. Set the logging level to debug:

    # orcharhino-installer --foreman-logging-level debug

  2. After you complete debugging, reset the logging level to the default value:

    # orcharhino-installer --reset-foreman-logging-level

C.2. Increasing the logging level for Hammer

Increase Hammer logging to debug to capture detailed CLI activity when troubleshooting command-line errors or API responses.

Hammer writes logs to ~/.hammer/log/hammer.log.

Procedure

  • In /etc/hammer/cli_config.yml, set the :log_level: option to debug:

    :log_level: 'debug'

C.3. Increasing the logging level for orcharhino Proxy

Increase orcharhino Proxy logging to debug to capture detailed orcharhino Proxy activity when troubleshooting communication between orcharhino and hosts. Reset the level when debugging is complete to avoid excessive log volume.

By default, orcharhino Proxy writes logs to /var/log/foreman-proxy/proxy.log. For more information, see Configuring logging type and layout.

Procedure

  1. Set the logging level to debug:

    # orcharhino-installer --foreman-proxy-log-level DEBUG

  2. After you complete debugging, reset the logging level to the default value:

    # orcharhino-installer --reset-foreman-proxy-log-level

C.4. Increasing the logging level for Candlepin

Increase Candlepin logging to DEBUG when you need detailed subscription and content management diagnostics on your orcharhino.

Candlepin writes logs to /var/log/candlepin/candlepin.log and /var/log/candlepin/error.log.

Procedure

  1. Set the logging level to DEBUG:

    # orcharhino-installer --katello-candlepin-loggers log4j.logger.org.candlepin:DEBUG

    If the candlepin log files are too verbose, you can decrease the default debug level:

    # orcharhino-installer \
--katello-candlepin-loggers log4j.logger.org.candlepin:DEBUG \
--katello-candlepin-loggers log4j.logger.org.candlepin.resource.ConsumerResource:WARN \
--katello-candlepin-loggers log4j.logger.org.candlepin.resource.HypervisorResource:WARN

  2. After you complete debugging, reset the logging level to the default value:

    # orcharhino-installer --reset-katello-candlepin-loggers

C.5. Increasing the logging level for Redis

Increase Redis logging to debug to capture detailed cache activity when troubleshooting performance or connectivity issues.

Redis writes logs to /var/log/redis/redis.log.

Procedure

  1. In /etc/redis/redis.conf, set the logging level to debug:

    loglevel debug

  2. Restart the Redis service:

    # systemctl restart redis
    Note

    Running orcharhino-installer will revert the setting to default.

C.6. Increasing the logging level for orcharhino-installer

Increase orcharhino-installer verbose output to debug when you need detailed installation and configuration diagnostics during setup or upgrades.

Procedure

  • Increase the logging level of the orcharhino-installer utility:

    # orcharhino-installer --verbose-log-level debug

    Note that this only affects standard output but not any log files written to disk.

C.7. Increasing the logging level for Pulp

Increase Pulp logging to DEBUG when you need detailed content repository diagnostics.

Pulp writes logs to the systemd journal. You can view them with journalctl --unit 'pulpcore*'.

Procedure

  1. In /etc/pulp/settings.py, set the logging level to DEBUG:

    LOGGING = {"dynaconf_merge": True, "loggers": {'': {'handlers': ['console'], 'level': 'DEBUG'}}}

  2. Restart the Pulp services:

    # systemctl restart \
pulpcore-api \
pulpcore-content \
pulpcore-resource-manager \
pulpcore-worker@\*
    Note

    Running orcharhino-installer will revert the setting to default.

C.8. Increasing the logging level for OpenVox agent

Increase OpenVox agent logging to debug when you need detailed configuration application diagnostics on hosts.

OpenVox agent writes logs to /var/log/puppetlabs/puppet/.

Prerequisites
Procedure

  • Set the logging level to debug:

    # orcharhino-installer --puppet-agent-additional-settings log_level:debug

C.9. Increasing the logging level for OpenVox server

Increase OpenVox server logging to debug when you need detailed catalog compilation and agent communication diagnostics.

OpenVox server writes logs to /var/log/puppetlabs/puppetserver/.

Prerequisites
Procedure

  • Set the logging level to debug:

    # orcharhino-installer --puppet-server-additional-settings log_level:debug

C.10. Increasing the logging level for Salt

Increase Salt Master or Minion logging to debug when you need detailed remote execution or state application diagnostics.

Salt Master writes logs to /var/log/salt/master and Salt Minions write logs to /var/log/salt/minion.

Procedure

  • In /etc/salt/master or /etc/salt/minion, set the logging level to debug:

    log_level: debug

Appendix D: Anonymizing audit records

You can anonymize audit records to remove user account and IP information while preserving the audit trail. This is useful for maintaining compliance with privacy regulations or internal security policies.

Procedure

  • Use the foreman-rake audits:anonymize command to remove any user account or IP information while maintaining the audit records in the database. You can also use a cron job to schedule anonymizing the audit records at the set interval that you want.

    By default, using the foreman-rake audits:anonymize command anonymizes audit records that are older than 90 days. You can specify the number of days to keep the audit records by adding the days option and add the number of days.

    For example, you can anonymize audit records that are older than seven days:

    # foreman-rake audits:anonymize days=7

Appendix E: Administration settings information

In the orcharhino management UI, you can edit various settings to configure orcharhino. You can find these settings by navigating to Administer > Settings.

E.1. General settings information

The general settings define system-wide configuration options for orcharhino, including administrator email, instance URL, user interface preferences, HTTP proxy settings, and default language and time zone.

Setting Default Value Description

Administrator email address

The default administrator email address

orcharhino URL

URL where your orcharhino instance is reachable. See also Provisioning > Unattended URL.

Entries per page

20

Number of records shown per page in orcharhino

Fix DB cache

No

orcharhino maintains a cache of permissions and roles. When set to Yes, orcharhino recreates this cache on the next restart.

DB pending seed

No

Should the foreman-rake db:seed be executed on the next run of the installer modules?

orcharhino Proxy request timeout

60

Open and read timeout for HTTP requests from orcharhino to orcharhino Proxy (in seconds).

Login page footer text

Text to be shown in the login-page footer.

HTTP(S) proxy

Set a proxy for outgoing HTTP(S) connections from the orcharhino product. System-wide proxies must be configured at the operating system level.

HTTP(S) proxy except hosts

[]

Set hostnames to which requests are not to be proxied. Requests to the local host are excluded by default.

Show Experimental Labs

No

Whether or not to show a menu to access experimental lab features (requires reload of page).

Display FQDN for hosts

Yes

If set to Yes, orcharhino displays names of hosts as fully qualified domain names (FQDNs).

Out of sync interval

30

Hosts report periodically, and if the time between reports exceeds this duration in minutes, hosts are considered out of sync. You can override this on your hosts by adding the outofsync_interval parameter, per host, at Hosts > All Hosts > $host > Edit > Parameters > Add Parameter.

orcharhino UUID

orcharhino instance ID. Uniquely identifies a orcharhino instance.

Default language

The UI for new users uses this language.

Default timezone

The time zone to use for new users.

Instance title

The instance title is shown on the top navigation bar (requires a page reload).

Saved audits interval

Duration in days to preserve audit data. Leave empty to disable the audits cleanup.

New host details UI

Yes

orcharhino loads the new UI for host details.

E.2. Background tasks settings

The tasks settings define how orcharhino manages background tasks, including timeouts, retry behavior, batch processing, and debugging options for the Dynflow console.

Setting Default Value Description

Sync task timeout

120

Number of seconds to wait for a synchronous task to finish before an exception is raised.

Enable dynflow console

Yes

Enable the Dynflow console (/foreman_tasks/dynflow) for debugging.

Require auth for dynflow console

Yes

The user must be authenticated as having administrative rights before accessing the Dynflow console.

Proxy action retry count

4

Number of attempts permitted to start a task on the orcharhino Proxy before failing.

Proxy action retry interval

15

Time in seconds between retries.

Allow proxy batch tasks

Yes

Allow triggering tasks on the orcharhino Proxy in batches.

Proxy tasks batch size

100

Number of tasks included in one request to the orcharhino Proxy if foreman_tasks_proxy_batch_trigger is enabled.

Tasks troubleshooting URL

URL pointing to the task troubleshooting documentation. It should contain a %{label} placeholder that is replaced with a normalized task label (restricted to only alphanumeric characters)). A %{version} placeholder is also available.

Polling intervals multiplier

1

Polling multiplier used to multiply the default polling intervals. You can use this to prevent polling too frequently for long running tasks.

E.3. Template sync settings

The template sync settings define how orcharhino synchronizes templates with Git repositories, including import and export behavior, filtering, locking, and metadata handling.

Setting Default Value Description

Associate

New

Associate templates with operating system, organization, and location.

Branch

Default branch in Git repo.

Commit message

Templates export made by a orcharhino user

Custom commit message for exported templates.

Dirname

/

The directory within the Git repo containing the templates.

Filter

Import or export of names matching this regex. Case-insensitive. Snippets are not filtered.

Force import

No

If set to Yes, locked templates are overwritten during an import.

HTTP proxy policy

Global default HTTP proxy

Whether to use an HTTP proxy to synchronize templates.

The Custom HTTP proxy value is available only if an HTTP proxy is configured under the selected organization and location and if your account has the view_http_proxies permission assigned.

Lock templates

Keep, do not lock new

How to handle lock for imported templates.

Metadata export mode

Refresh

Default metadata export mode.

Possible options:

refresh re-renders metadata.

keep keeps existing metadata.

remove exports the template without metadata.

Negate

No

Negate the filter for import or export.

Prefix

A string added as a prefix to imported templates.

Repo

Target path from where to import or export templates. Different protocols can be used, for example:

/tmp/dir

git://example.com

https://example.com

ssh://example.com

When exporting to /tmp, note that production deployments may be configured to use private tmp.

Verbosity

No

Choose verbosity for Rake task importing templates.

E.4. Host Discovery settings

The Discovery settings define how orcharhino handles discovered hosts, including default organization and location assignment, hostname generation, auto-provisioning behavior, and fact organization.

Setting Default Value Description

Discovery location

Indicates the default location to place discovered hosts in.

Discovery organization

Indicates the default organization to which discovered hosts are added.

Interface fact

discovery_bootif

Fact name to use for primary interface detection.

Create bond interfaces

No

Automatically create a bond interface if another interface is detected on the same VLAN using LLDP.

Clean all facts

No

Clean all reported facts (except discovery facts) during provisioning.

Hostname facts

discovery_bootif

List of facts to use for the hostname (comma separated, first wins).

Auto provisioning

No

Use the provisioning rules to automatically provision newly discovered hosts.

Reboot

Yes

Automatically reboot or kexec discovered hosts during provisioning.

Hostname prefix

mac

The default prefix to use for the hostname. Must start with a letter.

Fact columns

Extra facter columns to show in host lists (comma separated).

Highlighted facts

Regex to organize facts for highlights section – e.g. ^(abc|cde)$.

Storage facts

Regex to organize facts for the storage section.

Software facts

Regex to organize facts for the software section.

Hardware facts

Regex to organize facts for the hardware section.

Network facts

Regex to organize facts for the network section.

IPMI facts

Regex to organize facts for the Intelligent Platform Management Interface (IPMI) section.

Lock PXE

No

Automatically generate a Preboot Execution Environment (PXE) configuration to pin a newly discovered host to discovery.

Locked PXELinux template name

pxelinux_discovery

PXELinux template to be used when pinning a host to discovery.

Locked PXEGrub2 template name

pxegrub2_discovery

PXEGrub2 template to be used when pinning a host to discovery.

Force DNS

Yes

Force the creation of DNS entries when provisioning a discovered host.

Error on existing NIC

No

Do not permit to discover an existing host matching the MAC of a provisioning Network Interface Card (NIC) (errors out early).

Type of name generator

Fact + prefix

Discovery hostname naming pattern.

Prefer IPv6

No

Prefer IPv6 to IPv4 when calling discovered nodes.

E.5. Boot disk settings

The boot disk settings define paths to boot loader images and templates used for generating bootable disk images, including iPXE, ISOLINUX, SYSLINUX, and Grub2 configurations.

Setting Default Value Description

iPXE directory

/usr/share/ipxe

Path to directory containing iPXE images.

ISOLINUX directory

/usr/share/syslinux

Path to directory containing ISOLINUX images.

SYSLINUX directory

/usr/share/syslinux

Path to directory containing SYSLINUX images.

Grub2 directory

/var/lib/tftpboot/grub2

Path to directory containing grubx64.efi and shimx64.efi.

Host image template

Boot disk iPXE - host

iPXE template to use for host-specific boot disks.

Generic image template

Boot disk iPXE - generic host

iPXE template to use for generic host boot disks.

Generic Grub2 EFI image template

Boot disk Grub2 EFI - generic host

Grub2 template to use for generic Extensible Firmware Interface (EFI) host boot disks.

ISO generation command

genisoimage

Command to generate ISO image, use genisoimage or mkisofs.

Installation media caching

Yes

Installation media files are cached for full host images.

Allowed bootdisk types

[generic, host, full_host, subnet]

List of permitted bootdisk types. Leave blank to disable it.

E.6. Red Hat Cloud settings

The Red Hat Cloud settings define how orcharhino integrates with Red Hat cloud services, including automatic inventory upload, Insights recommendations synchronization, and hostname and IP address obfuscation.

Setting Default Value Description

Automatic inventory upload

Yes

Enable automatic upload of your host inventory to the Red Hat cloud.

Synchronize recommendations Automatically

No

Enable automatic synchronization of Insights recommendations from the Red Hat cloud.

Obfuscate host names

No

Obfuscate hostnames sent to the Red Hat cloud.

Obfuscate host ipv4 addresses

No

Obfuscate IPv4 addresses sent to the Red Hat cloud.

ID of the RHC daemon

*****

RHC daemon id.

E.7. Content management settings

The content settings define how orcharhino manages content repositories, subscriptions, content views, and host registration, including default templates, download policies, and synchronization behavior.

Setting Default Value Description

Default HTTP Proxy

Default HTTP Proxy for syncing content.

Default synced OS provisioning template

Kickstart default

Default provisioning template for operating systems created from synced content.

Default synced OS finish template

Kickstart default finish

Default finish template for new operating systems created from synced content.

Default synced OS user-data

Kickstart default user data

Default user data for new operating systems created from synced content.

Default synced OS PXELinux template

Kickstart default PXELinux

Default PXELinux template for new operating systems created from synced content.

Default synced OS PXEGrub2 template

Kickstart default PXEGrub2

Default PXEGrub2 template for new operating systems created from synced content.

Default synced OS iPXE template

Kickstart default iPXE

Default iPXE template for new operating systems created from synced content.

Default synced OS partition table

Kickstart default

Default partitioning table for new operating systems created from synced content.

Default synced OS kexec template

Discovery ATIX AG kexec

Default kexec template for new operating systems created from synced content.

Default synced OS Atomic template

Atomic Kickstart default

Default provisioning template for new atomic operating systems created from synced content.

Manifest refresh timeout

1200

Timeout when refreshing a manifest (in seconds).

Subscription connection enabled

Yes

Can communicate with the ATIX AG Portal for subscriptions.

Installable errata from Content View

No

Calculate errata host status based only on errata in a host’s content view and lifecycle environment.

Restrict Composite Content View promotion

No

If this is enabled, a composite content view cannot be published or promoted, unless the content view versions that it includes exist in the target environment.

Check services before actions

Yes

Check the status of backend services such as pulp and candlepin before performing actions?

Batch size to sync repositories in

100

How many repositories should be synced concurrently on a orcharhino Proxy. A smaller number may lead to longer sync times. A larger number will increase dynflow load.

Sync orcharhino Proxies after Content View promotion

Yes

Whether or not to auto sync orcharhino Proxies after a content view promotion.

Default Custom Repository download policy

immediate

Default download policy for custom repositories. Either immediate or on_demand.

Default ATIX AG Repository download policy

on_demand

Default download policy for enabled ATIX AG repositories. Either immediate or on_demand.

Default orcharhino Proxy download policy

on_demand

Default download policy for orcharhino Proxy syncs. Either inherit, immediate, or on_demand.

Pulp 3 export destination filepath

/var/lib/pulp/exports

On-disk location for Pulp 3 exported repositories.

Pulp client key

/etc/pki/katello/private/pulp-client.key

Path for SSL key used for Pulp server authentication.

Pulp client cert

/etc/pki/katello/certs/pulp-client.crt

Path for SSL certificate used for Pulp server authentication.

Sync Connection Timeout

300

Total timeout in seconds for connections when syncing.

Delete Host upon unregister

No

When unregistering a host using subscription-manager, also delete the host record. Managed resources linked to the host such as virtual machines and DNS records might also be deleted.

Subscription manager name registration fact

When registering a host using subscription-manager, force use the specified fact for the host name (in the form of fact.fact).

Subscription manager name registration fact strict matching

No

If this is enabled, and register_hostname_fact is set and provided, registration looks for a new host by name only using that fact, and skips all hostname matching.

Default Location subscribed hosts

Default Location

Default location where new subscribed hosts are stored after registration.

Expire soon days

120

The number of days remaining in a subscription before you are reminded about renewing it.

Content View Dependency Solving Default

No

The default dependency solving value for new content views.

Host Duplicate DMI UUIDs

[]

If hosts fail to register because of duplicate Desktop Management Interface (DMI) UUIDs, add their comma-separated values here. Subsequent registrations generate a unique DMI UUID for the affected hosts.

Host Profile Assume

Yes

Enable new host registrations to assume registered profiles with matching hostname if the registering DMI UUID is not used by another host.

Host Profile Can Change In Build

No

Enable host registrations to bypass Host Profile Assume if the host is in build mode.

Host Can Re-Register Only In Build

No

Enable hosts to re-register only when they are in build mode.

Host Tasks Workers Pool Size

5

Number of workers in the pool to handle the execution of host-related tasks. When set to 0, the default queue is used. Restart of the dynflowd/foreman-tasks service is required.

Applicability Batch Size

50

Number of host applicability calculations to process per task.

Autosearch

Yes

For pages that support it, automatically perform the search while typing in search input.

Autosearch delay

500

If Autosearch is enabled, delay in milliseconds before executing searches while typing.

Pulp bulk load size

2000

The number of items fetched from a single paged Pulp API call.

Upload profiles without Dynflow

Yes

Enable Katello to update host installed packages, enabled repositories, and module inventory directly instead of wrapped in Dynflow tasks (try turning off if Puma processes are using too much memory).

Orphaned Content Protection Time

1440

Time in minutes to consider orphan content as orphaned.

Prefer registered through proxy for remote execution

No

Prefer using a proxy to which a host is registered when using remote execution.

Allow deleting repositories in published content views

Yes

Enable removal of repositories that the user has previously published in one or more content view versions.

E.8. User authentication settings

The authentication settings define how orcharhino handles user authentication and authorization, including OAuth configuration, SSL certificates, login delegation, idle timeouts, and OpenID Connect integration.

Setting Default Value Description

OAuth active

Yes

orcharhino will use OAuth for API authorization.

This setting is for internal orcharhino use only. ATIX AG does not support using it to configure OAuth authentication for API calls.

OAuth consumer key

*****

OAuth consumer key.

This setting is for internal orcharhino use only. ATIX AG does not support using it to configure OAuth authentication for API calls.

OAuth consumer secret

*****

OAuth consumer secret.

This setting is for internal orcharhino use only. ATIX AG does not support using it to configure OAuth authentication for API calls.

OAuth map users

No

orcharhino maps users by username in the request-header. If this is disabled, OAuth requests have administrator rights.

This setting is for internal orcharhino use only. ATIX AG does not support using it to configure OAuth authentication for API calls.

Failed login attempts limit

30

orcharhino blocks user logins from an incoming IP address for 5 minutes after the specified number of failed login attempts. Set to 0 to disable brute force protection.

Restrict registered orcharhino Proxies

Yes

Only known orcharhino Proxies can access features that use orcharhino Proxy authentication.

Trusted hosts

[]

List of hostnames, IPv4, IPv6 addresses or subnets to be trusted in addition to orcharhino Proxies for access to fact/report importers and ENC output.

SSL certificate

/etc/foreman/client_cert.pem

SSL Certificate path that orcharhino uses to communicate with its proxies.

SSL CA file

/etc/foreman/proxy_ca.pem

SSL CA file path that orcharhino uses to communicate with its proxies.

SSL private key

/etc/foreman/client_key.pem

SSL Private Key path that orcharhino uses to communicate with its proxies.

SSL client DN env

HTTP_SSL_CLIENT_S_DN

Environment variable containing the subject DN from a client SSL certificate.

SSL client verify env

HTTP_SSL_CLIENT_VERIFY

Environment variable containing the verification status of a client SSL certificate.

SSL client cert env

HTTP_SSL_CLIENT_CERT

Environment variable containing a client’s SSL certificate.

Server CA file

SSL CA file path used in templates to verify the connection to orcharhino.

Websockets SSL key

etc/pki/katello/private/katello-apache.key

Private key file path that orcharhino uses to encrypt websockets.

Websockets SSL certificate

/etc/pki/katello/certs/katello-apache.crt

Certificate path that orcharhino uses to encrypt websockets.

Websockets encryption

Yes

VNC/SPICE websocket proxy console access encryption (websockets_ssl_key/cert setting required).

Login delegation logout URL

Redirect your users to this URL on logout. Enable Authorize login delegation also.

Authorize login delegation auth source user autocreate

External

Name of the external authentication source where unknown externally authenticated users (see Authorize login delegation) are created. Empty means no autocreation.

Authorize login delegation

No

Authorize login delegation with REMOTE_USER HTTP header.

Authorize login delegation API

No

Authorize login delegation with REMOTE_USER HTTP header for API calls too.

Idle timeout

60

Log out idle users after the specified number of minutes.

BCrypt password cost

9

Cost value of bcrypt password hash function for internal auth-sources (4 – 30). A higher value is safer but verification is slower, particularly for stateless API calls and UI logins. A password change is needed to affect existing passwords.

BMC credentials access

Yes

Permits access to BMC interface passwords through ENC YAML output and in templates.

OIDC JWKs URL

OpenID Connect JSON Web Key Set (JWKS) URL. Typically https://keycloak.example.com/auth/realms/<realm name>/protocol/openid-connect/certs when using Keycloak as an OpenID provider.

OIDC Audience

[]

Name of the OpenID Connect Audience that is being used for authentication. In the case of Keycloak this is the Client ID.

OIDC Issuer

The issuer claim identifies the principal that issued the JSON Web tokens (JWT), which exists at a /.well-known/openid-configuration in case of most of the OpenID providers.

OIDC Algorithm

The algorithm used to encode the JWT in the OpenID provider.

E.9. Email notification settings

The email settings define how orcharhino sends email notifications, including delivery method, SMTP configuration, reply addresses, and welcome email options.

Important

The sendmail command is a deprecated feature. Deprecated functionality is still included in orcharhino and continues to be supported. However, it will be removed in a future release of this product and is not recommended for new deployments.

Use an SMTP service instead.

For the most recent list of major functionality that has been deprecated or removed within orcharhino, refer to the Deprecated features section of the orcharhino release notes.
Setting Default Value Description

Email reply address

Email reply address for emails that orcharhino is sending.

Email subject prefix

Prefix to add to all outgoing email.

Send welcome email

No

Send a welcome email including username and URL to new users.

Delivery method

Sendmail

Method used to deliver email.

SMTP enable StartTLS auto

Yes

SMTP automatically enables StartTLS.

SMTP OpenSSL verify mode

Default verification mode

When using TLS, you can set how OpenSSL checks the certificate.

SMTP address

SMTP address to connect to.

SMTP port

25

SMTP port to connect to.

SMTP HELO/EHLO domain

HELO/EHLO domain.

SMTP username

Username to use to authenticate, if required.

SMTP password

*****

Password to use to authenticate, if required.

SMTP authentication

none

Specify authentication type, if required.

Sendmail arguments

-i

Specify additional options to sendmail. Only used when the delivery method is set to sendmail.

Sendmail location

/usr/sbin/sendmail

The location of the sendmail executable. Only used when the delivery method is set to sendmail.

E.10. RSS notifications settings

The notifications settings define how orcharhino retrieves and displays RSS notifications from external feeds.

Setting Default Value Description

RSS enable

Yes

Pull RSS notifications.

RSS URL

https://orcharhino.com/feed/

URL from which to fetch RSS notifications.

E.11. Host provisioning settings

The provisioning settings define how orcharhino provisions hosts, including default passwords, template rendering, PXE boot configuration, hostname generation, and virtual machine management.

Setting Default Value Description

Host owner

Default owner on provisioned hosts, if empty orcharhino uses the current user.

Root password

*****

Default encrypted root password on provisioned hosts.

Unattended URL

URL that hosts retrieve templates from during the build. When it starts with https, unattended, or userdata, controllers cannot be accessed using HTTP.

Safemode rendering

Yes

Enables safe mode rendering of provisioning templates. The default and recommended option Yes denies access to variables and any object that is not listed in orcharhino.

When set to No, any object may be accessed by a user with permission to use templating features, either by editing templates, parameters or smart variables. This permits users full remote code execution on orcharhino Server, effectively disabling all authorization. This is not a safe option, especially in larger companies.

Access unattended without build

No

Enable access to unattended URLs without build mode being used.

Query local nameservers

No

orcharhino queries the locally configured resolver instead of the SOA/NS authorities.

Installation token lifetime

360

Time in minutes that installation tokens should be valid for. Set to 0 to disable the token.

SSH timeout

120

Time in seconds before SSH provisioning times out.

Libvirt default console address

0.0.0.0

The IP address that should be used for the console listen address when provisioning new virtual machines using libvirt.

Update IP from built request

No

orcharhino updates the host IP with the IP that made the build request.

Use short name for VMs

No

orcharhino uses the short hostname instead of the FQDN for creating new virtual machines.

DNS timeout

[5, 10, 15, 20]

List of timeouts (in seconds) for DNS lookup attempts such as the dns_lookup macro and DNS record conflict validation.

Clean up failed deployment

Yes

orcharhino deletes the virtual machine if the provisioning script ends with a non-zero exit code.

Type of name generator

Random-based

Specifies the method used to generate a hostname when creating a new host.

The default Random-based option generates a unique random hostname which you can but do not have to use. This is useful for users who create many hosts and do not know how to name them.

The MAC-based option is for bare-metal hosts only. If you delete a host and create it later on, it receives the same hostname based on the MAC address. This can be useful for users who recycle servers and want them to always get the same hostname.

The Off option disables the name generator function and leaves the hostname field blank.

Default PXE global template entry

Default PXE menu item in a global template – local, discovery or custom, use blank for template default.

Default PXE local template entry

Default PXE menu item in local template – local, local_chain_hd0, or custom, use blank for template default.

iPXE intermediate script

iPXE intermediate script

Intermediate iPXE script for unattended installations.

Destroy associated VM on host delete

No

Destroy associated VM on host delete. When enabled, VMs linked to hosts are deleted on Compute Resource. When disabled, VMs are unlinked when the host is deleted, meaning they remain on Compute Resource and can be re-associated or imported back to orcharhino again. This does not automatically power off the VM

Maximum structured facts

100

Maximum number of keys in structured subtree, statistics stored in orcharhino::dropped_subtree_facts.

Default Global registration template

Global Registration

Global Registration template.

Default 'Host initial configuration' template

Linux host_init_config default

Default 'Host initial configuration' template, automatically assigned when a new operating system is created.

CoreOS Transpiler Command

[false, --pretty, --files-dir, /usr/share/foreman/config/ct]

Full path to CoreOS transpiler (ct) with arguments as an comma-separated array

Fedora CoreOS Transpiler Command

[false, --pretty, --files-dir, /usr/share/foreman/config/ct]

Full path to Fedora CoreOS transpiler (fcct) with arguments as an comma-separated array

Global default PXEGrub2 template

PXEGrub2 global default

Global default PXEGrub2 template. This template is deployed to all configured TFTP servers. It is not affected by upgrades.

Global default PXELinux template

PXELinux global default

Global default PXELinux template. This template is deployed to all configured TFTP servers. It is not affected by upgrades.

Global default iPXE template

iPXE global default

Global default iPXE template. This template is deployed to all configured TFTP servers. It is not affected by upgrades.

Local boot PXEGrub2 template

PXEGrub2 default local boot

Template that is selected as PXEGrub2 default for local boot.

Local boot PXELinux template

PXELinux default local boot

Template that is selected as PXELinux default for local boot.

Local boot iPXE template

iPXE default local boot

Template that is selected as iPXE default for local boot.

Manage PuppetCA

Yes

orcharhino automates certificate signing upon provision of a new host.

Use UUID for certificates

No

orcharhino uses random UUIDs for certificate signing instead of hostnames.

E.12. Host facts settings

The facts settings define how orcharhino processes and uses facts reported by hosts, including automatic host creation, location and organization assignment, interface updates, and fact filtering.

Setting Default Value Description

Create new host when facts are uploaded

Yes

orcharhino creates the host when new facts are received.

Location fact

orcharhino_location

Hosts created after a Puppet run are placed in the location specified by this fact.

Organization fact

orcharhino_organization

Hosts created after a Puppet run are placed in the organization specified by this fact. The content of this fact should be the full label of the organization.

Default location

Default Location

Hosts created after a Puppet run that did not send a location fact are placed in this location.

Default organization

Default Organization

Hosts created after a Puppet run that did not send an organization fact are placed in this organization.

Update hostgroup from facts

Yes

orcharhino updates a host’s hostgroup from its facts.

Ignore facts for operating system

No

Stop updating operating system from facts.

Ignore facts for domain

No

Stop updating domain values from facts.

Update subnets from facts

None

orcharhino updates a host’s subnet from its facts.

Ignore interfaces facts for provisioning

No

Stop updating IP and MAC address values from facts (affects all interfaces).

Ignore interfaces with matching identifier

[lo, en*v*, usb*, vnet*, macvtap*, ;vdsmdummy;, veth*, tap*, qbr*, qvb*, qvo*, qr-*, qg-*, vlinuxbr*, vovsbr*, br-int]

Skip creating or updating host network interfaces objects with identifiers matching these values from incoming facts. You can use a * wildcard to match identifiers with indexes, e.g. macvtap*. The ignored interface raw facts are still stored in the database, see the Exclude pattern setting for more details.

Exclude pattern for facts stored in orcharhino

[lo, en*v*, usb*, vnet*, macvtap*, ;vdsmdummy;, veth*, tap*, qbr*, qvb*, qvo*, qr-*, qg-*, vlinuxbr*, vovsbr*, br-int, load_averages::*, memory::swap::available*, memory::swap::capacity, memory::swap::used*, memory::system::available*, memory::system::capacity, memory::system::used*, memoryfree, memoryfree_mb, swapfree, swapfree_mb, uptime_hours, uptime_days]

Exclude pattern for all types of imported facts (Puppet, Ansible, rhsm). Those facts are not stored in the orcharhino database. You can use a * wildcard to match names with indexes, e.g. ignore* filters out ignore, ignore123 as well as a::ignore or even a::ignore123::b.

Default Puppet environment

production

orcharhino defaults to this puppet environment if it cannot auto detect one.

ENC environment

Yes

orcharhino explicitly sets the puppet environment in the ENC yaml output. This avoids conflicts between the environment in puppet.conf and the environment set in orcharhino.

Update environment from facts

No

orcharhino updates a host’s environment from its facts.

E.13. Configuration management settings

The configuration management settings define how orcharhino integrates with configuration management tools, including automatic host creation from reports, smart class parameter evaluation, and configuration status tracking.

Setting Default Value Description

Create new host when report is uploaded

Yes

orcharhino creates the host when a report is received.

Matchers inheritance

Yes

orcharhino matchers are inherited by children when evaluating smart class parameters for hostgroups, organizations, and locations.

Default parameters lookup path

[fqdn, hostgroup, os, domain]

orcharhino evaluates host smart class parameters in this order by default.

Interpolate ERB in parameters

Yes

orcharhino parses ERB in parameters value in the ENC output.

Always show configuration status

No

All hosts show a configuration status even when a Puppet orcharhino Proxy is not assigned.

Puppet interval

35

Duration in minutes after servers reporting using Puppet are classed as out of sync.

Puppet out of sync disabled

No

Disable host configuration status turning to out of sync for Puppet after report does not arrive within configured interval.

E.14. Remote execution settings

The remote execution settings define how orcharhino executes commands and scripts on remote hosts, including SSH configuration, user management, orcharhino Proxy selection, and job template synchronization.

Setting Default Value Description

Fallback to Any Proxy

No

Search the host for any proxy with Remote Execution. This is useful when the host has no subnet or the subnet does not have an execution proxy.

Enable Global Proxy

Yes

Search for Remote Execution proxy outside of the proxies assigned to the host. The search is limited to the host’s organization and location.

SSH User

root

Default user to use for SSH. You can override per host by setting the remote_execution_ssh_user parameter.

Effective User

root

Default user to use for executing the script. If the user differs from the SSH user, su or sudo is used to switch the user.

Effective User Method

sudo

The command used to switch to the effective user. One of [sudo, dzdo, su]

Effective user password

*****

Effective user password. See Effective User.

Sync Job Templates

Yes

Whether to sync templates from disk when running db:seed.

SSH Port

22

Port to use for SSH communication. Default port 22. You can override per host by setting the remote_execution_ssh_port parameter.

Connect by IP

No

Whether the IP addresses on host interfaces are preferred over the FQDN. It is useful when the DNS is not resolving the FQDNs properly. You can override this per host by setting the remote_execution_connect_by_ip parameter. For dual-stacked hosts, consider the remote_execution_connect_by_ip_prefer_ipv6 setting.

Prefer IPv6 over IPv4

No

When connecting using an IP address, are IPv6 addresses preferred? If no IPv6 address is set, it falls back to IPv4 automatically. You can override this per host by setting the remote_execution_connect_by_ip_prefer_ipv6 parameter. By default and for compatibility, IPv4 is preferred over IPv6.

Default SSH password

*****

Default password to use for SSH. You can override per host by setting the remote_execution_ssh_password parameter.

Default SSH key passphrase

*****

Default key passphrase to use for SSH. You can override per host by setting the remote_execution_ssh_key_passphrase parameter.

Workers pool size

5

Number of workers in the pool to handle the execution of the remote execution jobs. Restart of the dynflowd/orcharhino-tasks service is required.

Cleanup working directories

Yes

Whether working directories are removed after task completion. You can override this per host by setting the remote_execution_cleanup_working_dirs parameter.

Cockpit URL

Where to find the Cockpit instance for the Web Console button. By default, no button is shown.

Form Job Template

Run Command - Script Default

Choose a job template that is pre-selected in job invocation form.

Job Invocation Report Template

Jobs - Invocation report template

Select a report template used for generating a report for a particular remote execution job.

Time to pickup

86400

Time in seconds within which the host has to pick up a job. If the job is not picked up within this limit, the job will be canceled. Applies only to pull-mqtt based jobs. Defaults to one day.

E.15. Ansible integration settings

The Ansible settings define how orcharhino integrates with Ansible for configuration management, including connection types, verbosity levels, timeout values, and role import behavior.

Setting Default Value Description

Private Key Path

Use this to supply a path to an SSH Private Key that Ansible uses instead of a password. Override with the ansible_ssh_private_key_file host parameter.

Connection type

ssh

Use this connection type by default when running Ansible Playbooks. You can override this on hosts by adding the ansible_connection parameter.

WinRM cert Validation

validate

Enable or disable WinRM server certificate validation when running Ansible Playbooks. You can override this on hosts by adding the ansible_winrm_server_cert_validation parameter.

Default verbosity level

Disabled

orcharhino adds this level of verbosity for additional debugging output when running Ansible Playbooks.

Post-provision timeout

360

Timeout (in seconds) to set when orcharhino triggers an Ansible roles task playbook after a host is fully provisioned. Set this to the maximum time you expect a host to take until it is ready after a reboot.

Ansible report timeout

30

Timeout (in minutes) when hosts should have reported.

Ansible out of sync disabled

No

Disable host configuration status turning to out of sync for Ansible after a report does not arrive within the configured interval.

Default Ansible inventory report template

Ansible - Ansible Inventory

orcharhino uses this template to schedule the report with Ansible inventory.

Ansible roles to ignore

[]

The roles to exclude when importing roles from orcharhino Proxy. The expected input is comma separated values and you can use * wildcard metacharacters. For example: foo*, *b*, *bar.

Proxy tasks batch size for Ansible

Number of tasks which should be sent to the orcharhino Proxy in one request if orcharhino_tasks_proxy_batch_trigger is enabled. If set, it overrides the orcharhino_tasks_proxy_batch_size setting for Ansible jobs.