Administering orcharhino

This guide uses orcharhino specific terminology. If you are new to orcharhino or unsure about certain terms, have a look at our glossary.

Accessing orcharhino

After orcharhino has been installed and configured, use the orcharhino management UI interface to log in to orcharhino for further configuration.

Importing the Katello root CA certificate

The first time you log in to orcharhino, you might see a warning informing you that you are using the default self-signed certificate and you might not be able to connect this browser to orcharhino until the root CA certificate is imported in the browser. Use the following procedure to locate the root CA certificate on orcharhino and to import it into your browser.

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

Prerequisites

  • Your orcharhino is installed and configured.

Procedure

  1. Identify the fully qualified domain name of your orcharhino Server:

    # hostname -f

  2. Access the pub directory on your orcharhino Server using a web browser pointed to the fully qualified domain name:

    https://orcharhino.example.com/pub

  3. When you access orcharhino for the first time, an untrusted connection warning displays in your web browser. Accept the self-signed certificate and add the orcharhino URL as a security exception to override the settings. This procedure might differ depending on the browser being used. Ensure that the orcharhino URL is valid before you accept the security exception.

  4. Select katello-server-ca.crt.

  5. Import the certificate into your browser as a certificate authority and trust it to identify websites.

CLI procedure

  1. From the orcharhino CLI, copy the katello-server-ca.crt file to the machine you use to access the orcharhino management UI:

    # scp /var/www/html/pub/katello-server-ca.crt username@hostname:remotefile

  2. In the browser, import the katello-server-ca.crt certificate as a certificate authority and trust it to identify websites.

Logging in to orcharhino

Use the web user interface to log in to orcharhino for further configuration.

Prerequisites
Procedure

  1. Access orcharhino Server using a web browser pointed to the fully qualified domain name:

    https://orcharhino.example.com/

  2. Enter the user name and password created during the configuration process. If a user was not created during the configuration process, the default user name is admin. If you have problems logging in, you can reset the password. For more information, see Resetting the Administrative User Password.

Use the navigation tabs to browse the orcharhino management UI.

Navigation Tabs Description

Any Context

Clicking this tab changes the organization and location. If no organization or location is selected, the default organization is Any Organization and the default location is Any Location. Use this tab to change to different values.

Monitor

Provides summary dashboards and reports.

Content

Provides content management tools. This includes content views, Activation Keys, and lifecycle environments.

Hosts

Provides host inventory and provisioning configuration tools.

Configure

Provides general configuration tools and data including Host Groups and Puppet data.

Infrastructure

Provides tools on configuring how orcharhino interacts with the environment.

User Name

Provides user administration where users can edit their personal information.

notification bell

Provides event notifications to keep administrators informed of important environment changes.

Administer

Provides advanced configuration for settings such as Users and RBAC, as well as general settings.

Changing the password

These steps show how to change your password.

Procedure

  1. In the orcharhino management UI, click your user name at the top right corner.

  2. Select My Account from the menu.

  3. In the Current Password field, enter the current password.

  4. In the Password field, enter a new password.

  5. In the Verify field, enter the new password again.

  6. Click Submit to save your new password.

Resetting the administrative user password

Use the following procedures to reset the administrative password to randomly generated characters or to set a new administrative password.

To reset the administrative user password

  1. Log in to the base operating system where orcharhino Server is installed.

  2. Enter the following command to reset the password:

    # foreman-rake permissions:reset
Reset to user: admin, password: qwJxBptxb7Gfcjj5

  3. Use this password to reset the password in the orcharhino management UI.

  4. Edit the ~/.hammer/cli.modules.d/foreman.yml file on orcharhino Server to add the new password:

    # vi ~/.hammer/cli.modules.d/foreman.yml

Unless you update the ~/.hammer/cli.modules.d/foreman.yml file, you cannot use the new password with Hammer CLI.

To set a new administrative user password

  1. Log in to the base operating system where orcharhino Server is installed.

  2. To set the password, enter the following command:

    # foreman-rake permissions:reset password=new_password

  3. Edit the ~/.hammer/cli.modules.d/foreman.yml file on orcharhino Server to add the new password:

    # vi ~/.hammer/cli.modules.d/foreman.yml

Unless you update the ~/.hammer/cli.modules.d/foreman.yml file, you cannot use the new password with Hammer CLI.

Setting a custom message on the Login page

Procedure

  1. In the orcharhino management UI, navigate to Administer > Settings, and click the General tab.

  2. Click the edit button next to Login page footer text, and enter the desired text to be displayed on the login page. For example, this text may be a warning message required by your company.

  3. Click Save.

  4. Log out of the orcharhino management UI and verify that the custom text is now displayed on the login page below the orcharhino version number.

Starting and stopping orcharhino

orcharhino provides the orcharhino-maintain service command to manage orcharhino services from the command line. This is useful when creating a backup of orcharhino. For more information on creating backups, see Backing up orcharhino Server and orcharhino Proxy Server.

After installing orcharhino with the orcharhino-installer command, all orcharhino services are started and enabled automatically. View the list of these services by executing:

# orcharhino-maintain service list

To see the status of running services, execute:

# orcharhino-maintain service status

To stop orcharhino services, execute:

# orcharhino-maintain service stop

To start orcharhino services, execute:

# orcharhino-maintain service start

To restart orcharhino services, execute:

# orcharhino-maintain service restart

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.

To confirm whether your orcharhino Server has internal or external databases, you can query the status of your databases:

For PostgreSQL, enter the following command:

# orcharhino-maintain service status --only postgresql

To migrate from the default internal databases to external databases, you must complete the following procedures:

  1. preparing a host for external databases. Prepare a Enterprise Linux 8 server to host the external databases.

  2. installing postgresql. Prepare PostgreSQL with databases for orcharhino, Pulp and Candlepin with dedicated users owning them.

  3. migrating to external databases. Edit the parameters of orcharhino-installer to point to the new databases, and run orcharhino-installer.

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

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

Preparing a host for external databases

Install a freshly provisioned system with the latest Enterprise Linux 9 or Enterprise Linux 8 to host the external databases.

Prerequisites
Procedure

Ensure the prepared host has the same content available as your orcharhino Server.

Installing PostgreSQL

You can install only the same version of PostgreSQL that is installed with the orcharhino-installer tool during an internal database installation. orcharhino supports PostgreSQL version 12.

Procedure

  1. To install PostgreSQL, enter the following command:

    # dnf install postgresql-server postgresql-evr postgresql-contrib

  2. To initialize PostgreSQL, enter the following command:

    # 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. Edit the /var/lib/pgsql/data/pg_hba.conf file:

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

  6. Add the following line to the file:

      host  all   all   orcharhino_ip/32   scram-sha-256

  7. To start, and enable PostgreSQL service, enter the following commands:

    # systemctl enable --now postgresql

  8. Open the postgresql port on the external PostgreSQL server:

    # firewall-cmd --add-service=postgresql

  9. 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 orcharhino, one for Candlepin, and one for Pulp:

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

  12. Connect to the Pulp database:

    postgres=# \c pulpcore
You are now connected to database "pulpcore" as user "postgres".

  13. Create the hstore extension:

    pulpcore=# CREATE EXTENSION IF NOT EXISTS "hstore";
CREATE EXTENSION

  14. Exit the postgres user:

    # \q

  15. From orcharhino Server, test that you can access the database. If the connection succeeds, the commands return 1.

    # PGPASSWORD='Foreman_Password' psql -h postgres.example.com  -p 5432 -U foreman -d foreman -c "SELECT 1 as ping"
# PGPASSWORD='Candlepin_Password' psql -h postgres.example.com -p 5432 -U candlepin -d candlepin -c "SELECT 1 as ping"
# PGPASSWORD='Pulpcore_Password' psql -h postgres.example.com -p 5432 -U pulp -d pulpcore -c "SELECT 1 as ping"

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 a Enterprise Linux server.

Procedure

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

    # orcharhino-maintain service stop --exclude postgresql

  2. Back up the internal databases:

    # orcharhino-maintain backup online \
--preserve-directory \
--skip-pulp-content \
/var/migration_backup

  3. Transfer the data to the new external databases:

    PGPASSWORD='Foreman_Password' pg_restore -h postgres.example.com -U foreman -d foreman < /var/migration_backup/foreman.dump
PGPASSWORD='Candlepin_Password' pg_restore -h postgres.example.com -U candlepin -d candlepin < /var/migration_backup/candlepin.dump
PGPASSWORD='Pulpcore_Password' pg_restore -h postgres.example.com -U pulp -d pulpcore < /var/migration_backup/pulpcore.dump

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

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

Managing orcharhino with Ansible collections

orcharhino Ansible Collections is a set of Ansible modules that interact with the orcharhino API. You can manage and automate many aspects of orcharhino with orcharhino Ansible collections.

Installing the orcharhino Ansible modules

Use this procedure to install the orcharhino Ansible modules.

Procedure

  • Install the package using the following command:

    # dnf install ansible-collection-theforeman-foreman

Viewing the orcharhino Ansible modules

You can view the installed orcharhino Ansible modules by running:

# ansible-doc -l "`theforeman.foreman`"

Managing users and roles

A User defines a set of details for individuals using the system. Users can be associated with organizations and environments, so that when they create new entities, the default settings are automatically used. Users can also have one or more roles attached, which grants them rights to view and manage organizations and environments. See Managing Users for more information on working with users.

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. For more information on creating user groups, see Creating and Managing User Groups.

Roles define a set of permissions and access levels. Each role contains one on more permission filters that specify the actions allowed for the role. Actions are grouped according to the Resource type. Once a role has been created, users and user groups can be associated with that role. This way, you can assign the same set of permissions to large groups of users. orcharhino provides a set of predefined roles and also enables creating custom roles and permission filters as described in Creating and Managing Roles.

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

Creating a user

Use this procedure to create a user. To use the CLI instead of the orcharhino management UI, see the CLI procedure.

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:

    • INTERNAL: to manage the user inside orcharhino Server.

    • EXTERNAL: to manage the user with external authentication. For more information, see Configuring External Authentication in Installing orcharhino Server.

  • On the Organizations tab, select an organization for the user. Specify the default organization orcharhino selects for the user after login from the Default on login list.

    If a user is not assigned to an organization, their access is limited.
CLI 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 \
--password My_User_Password

    The --auth-source-id 1 setting means that the user is authenticated internally, you can specify an external authentication source as an alternative. Add the --admin option to grant administrator privileges to the user. Specifying organization IDs is not required.

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

Additional resources

  • For more information about creating user accounts by using Hammer, enter hammer user create --help.

Creating Personal Access Tokens via Hammer CLI

  1. ssh into your orcharhino server.

  2. Get a list of existing users: hammer user list.

  3. Create an API personal access token: hammer user access-token create --name my_PAT --location-id 1 --organization-id 2 --expires-at 2021-04-01 --user-id 3.

    Adjust the location, organization, and user ID accordingly. This will return the PAT as follows:

    Personal access token [my_PAT] created:
7UqkVjcN6VyTdbmhYiDNmw

  4. View existing API access tokens: hammer user access-token list --user-id 3

    ---|--------|--------|--------------------
ID | NAME | ACTIVE | EXPIRES AT
---|--------|--------|--------------------
1 | my_PAT | yes | 2021/04/01 00:00:00
---|--------|--------|--------------------

    Adjust the user ID accordingly. Run hammer user access-token create --help for more information.

Refer to the API endpoint on your orcharhino for more information: https://orcharhino.example.com/apidoc/v2/personal_access_tokens.html.

If you set a random passphrase for a new user and adjust its user roles accordingly, you can create a PAT for this user and use it as an "API only" user.

Assigning roles to a user

Use this procedure to assign roles to a user. To use the CLI instead of the orcharhino management UI, see the CLI procedure.

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.

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

CLI procedure

  • To assign roles to a user, enter the following command:

    # hammer user add-role --id user_id --role role_name

Impersonating a different user account

Administrators can impersonate other authenticated users for testing and troubleshooting purposes by temporarily logging on to the orcharhino management UI as a different user. When impersonating another user, the administrator has permissions to 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

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

Creating an API-only user

You can create users that can interact only with the orcharhino API.

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

Managing SSH keys

Adding SSH keys to a user allows deployment of SSH keys during provisioning. For information on deploying SSH keys during provisioning, see Deploying SSH Keys during Provisioning in Provisioning Hosts.

Managing SSH keys for a user

Use this procedure to add or remove SSH keys for a user. To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Prerequisites

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

CLI procedure

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

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

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

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

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

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

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.

Creating a Personal Access Token

Use this procedure to create a Personal Access Token.

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.

    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 https://orcharhino.example.com/api/status --user My_Username:My_Personal_Access_Token

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

    {"orcharhino_version":"6.11.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.

Revoking a Personal Access Token

Use this procedure to revoke a Personal Access Token before its expiration date.

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 https://orcharhino.example.com/api/status --user My_Username:My_Personal_Access_Token

  2. You receive the following error message:

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

Creating and managing user groups

User groups

With orcharhino, you can assign permissions to groups of users. You can also create user groups as collections of other user groups. If using an external authentication source, you can map orcharhino user groups to external user groups as described in Configuring External User Groups in Installing orcharhino Server.

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

Creating a user group

Use this procedure to create a user group.

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.

CLI procedure

  • To create a user group, enter the following command:

    # 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

Removing a user group

Use the following procedure to remove a user group from orcharhino.

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.

Creating and managing roles

orcharhino provides a set of predefined roles with permissions sufficient for standard tasks, as listed in Predefined roles available in orcharhino. It is also possible to configure custom roles, and assign one or more permission filters to them. Permission filters define the actions allowed for a certain resource type. Certain orcharhino plugins create roles automatically.

Creating a role

Use this procedure to create a role.

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.

CLI procedure

  • To create a role, enter the following command:

    # hammer role create --name My_Role_Name

To serve its purpose, a role must contain permissions. After creating a role, proceed to Adding Permissions to a Role.

Cloning a role

Use the orcharhino management UI to clone a role.

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.

Adding permissions to a role

Use this procedure to add permissions to a role. To use the CLI instead of the orcharhino management UI, see the CLI procedure.

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. Depending on the Resource type selected, you can select or deselect the Unlimited and Override checkbox. The Unlimited checkbox is selected by default, which means that the permission is applied on all resources of the selected type. When you disable the Unlimited checkbox, the Search field activates. In this field you can specify further filtering with use of the orcharhino search syntax. For more information, see Granular Permission Filtering. When you enable the Override checkbox, you can add additional locations and organizations to allow the role to access the resource type in the additional locations and organizations; you can also remove an already associated location and organization from the resource type to restrict access.

  6. Click Next.

  7. Click Submit to save changes.

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

Viewing permissions of a role

Use the orcharhino management UI to view the permissions of a role.

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.

Creating a complete permission table

Use the orcharhino CLI to create a permission table.

Procedure

  1. Ensure that the required packages are installed. Execute the following command on orcharhino Server:

    # dnf install foreman-console

  2. Start the orcharhino console with the following command:

    # foreman-rake console

    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(result)

    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. Insert the following text at the first line of /tmp/table.html:

    <table border="1"><tr><td>Permission name</td><td>Actions</td><td>Resource type</td></tr>

    Append the following text at the end of /tmp/table.html:

    </table>

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

Removing a role

Use the following procedure to remove a role from orcharhino.

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.

Predefined roles available in orcharhino

The following table provides an overview of permissions that predefined roles in orcharhino grant to a user.

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.

Granular permission filtering

As mentioned in Adding Permissions to a Role, orcharhino provides the ability to limit the configured user permissions to selected instances of a resource type. These granular filters are queries to the orcharhino database and are supported by the majority of resource types.

Creating a granular permission filter

Use this procedure to create a granular filter. To use the CLI instead of the orcharhino management UI, see the CLI procedure.

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

Specify a query in the Search field on the Edit Filter page. Deselect the Unlimited checkbox for the field to be active. 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.

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.

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

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. The following filter allows you to work with content while it is in the development stage of the application lifecycle, but the content becomes inaccessible once is pushed to production.

Applying permissions for the host resource type

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

You can limit user permissions to a certain organization or location with the use of the granular permission filter in the Search field. However, some resource types provide a GUI alternative, an Override checkbox that provides the Locations and Organizations tabs. On these tabs, you can select from the list of available organizations and locations. For more information, see Creating an Organization Specific Manager Role.

Creating an organization-specific manager role

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

Procedure

  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. For some filters, you can enable the Override option if you want the role to be able to access resources in additional locations and organizations. For example, by selecting the Domain resource type, the Override option, and then additional locations and organizations using the Locations and Organizations tabs, you allow this role to access domains in the additional locations and organizations that is not associated with this role. You can also click New filter to associate new filters with this role.

Supported operators for granular search

Table 1. Logical operators

Operator

Description

and

Combines search criteria.

not

Negates an expression.

has

Object must have a specified property.
Table 2. 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.

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.

For an overview of available notification types, see Email Notification Types.

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.

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

Email notification types

orcharhino can create the following email notifications:

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.

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.

Configure email notifications for a user from the orcharhino management UI.

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

    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.

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.

If the email is delivered, the verification is complete. Otherwise, you must 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.

Testing email notifications

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

Procedure

  • To trigger the notifications, execute the following command:

    # foreman-rake reports:_My_Frequency_

    Replace My_Frequency with one of the following:

  • daily

  • weekly

  • monthly

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

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

Changing email notification settings for a host

orcharhino can send event notifications for a host to the host’s registered owner. 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.

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

Backing up orcharhino Server and orcharhino Proxy Server

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

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

To create a backup of your orcharhino Server or orcharhino Proxy Server and all associated data, use the orcharhino-maintain backup command. Backing up to a separate storage device on a separate system is highly recommended.

orcharhino services are unavailable during the backup. Therefore, you must ensure that no other tasks are scheduled by other administrators. You can schedule a backup using cron. For more information, see the Example of a Weekly Full Backup Followed by Daily Incremental Backups.

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

A backup contains sensitive information from the /root/ssl-build directory. For example, it can contain hostnames, ssh keys, request files and SSL certificates. You must encrypt or move the backup to a secure location to minimize the risk of damage or unauthorized access to the hosts.

Conventional backup methods

You can also use conventional backup methods.

If you plan to use the orcharhino-maintain backup command to create a backup, do not stop orcharhino services.

  • When creating a snapshot or conventional backup, you must stop all services as follows:

    # orcharhino-maintain service stop

  • Start the services after creating a snapshot or conventional backup:

    # orcharhino-maintain service start

Estimating the size of a backup

The full backup creates uncompressed archives of PostgreSQL and Pulp database files, and orcharhino configuration files. Compression occurs after the archives are created to decrease the time when orcharhino services are unavailable.

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

Procedure

  1. Enter the du command to 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 3. 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.

Performing a full backup of orcharhino Server or orcharhino Proxy Server

orcharhino uses the orcharhino-maintain backup command to make backups.

There are two main methods of backing up orcharhino Server:

  • Offline backup

  • Online backup

    For more information about each of these methods, you can view the usage statements for each backup method.

Offline backups
# orcharhino-maintain backup offline --help
Online backups
# orcharhino-maintain backup online --help
Directory creation

The orcharhino-maintain backup command creates a time-stamped subdirectory in the backup directory that you specify. The orcharhino-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 orcharhino-maintain backup command stops and restarts services as required.

When you run the orcharhino-maintain backup offline command, the following default backup directories are created:

  • orcharhino-backup on orcharhino

  • foreman-proxy-backup on orcharhino Proxy

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.

Note that if you use a local PostgreSQL database, the postgres user requires write access to the backup directory.

Remote databases

You can use the orcharhino-maintain backup command to back up remote databases.

You can use both online and offline methods to back up remote databases, but if you use offline method, the orcharhino-maintain backup command performs a database dump.

Backing up to a remote NFS share

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

Prerequisites

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

  • On orcharhino Server, enter the following command:

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

  • On orcharhino Proxy Server, enter the following command:

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

Performing a backup without Pulp content

You can perform an offline backup that excludes the contents of the Pulp directory. The 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. For production usecases, do not restore from a directory that does not contain Pulp content.

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

  • To perform an offline backup without Pulp content, enter the following command:

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

Performing an incremental backup

Use this procedure to perform an offline backup of any changes since a previous 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.

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

  1. To perform a full offline backup, enter the following command:

    # orcharhino-maintain backup offline /var/backup_directory

  2. To create a directory within your backup directory to store the first incremental back up, enter the orcharhino-maintain backup command with the --incremental option:

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

  3. To create the second incremental backup, enter the orcharhino-maintain backup command with the --incremental option and include 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:

    # orcharhino-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:

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

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
  orcharhino-maintain backup offline --assumeyes $DESTINATION
else
  LAST=$(ls -td -- $DESTINATION/*/ | head -n 1)
  orcharhino-maintain backup offline --assumeyes --incremental "$LAST" $DESTINATION
fi
exit 0

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

Performing an online backup

Perform an online backup only for debugging purposes.

Risks associated with online backups

When performing an online backup, if there are procedures affecting the Pulp database, the Pulp part of the backup procedure repeats until it is no longer being altered. Because the backup of the Pulp database is the most time consuming part of backing up orcharhino, if you make a change that alters the Pulp database during this time, the backup procedure keeps restarting.

For production environments, use the offline method. For more information, see Performing a Full Backup. If you want to use the online backup method in production, proceed with caution and ensure that no modifications occur during the backup.

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

  • To perform an online backup, enter the following command:

    # orcharhino-maintain backup online /var/backup_directory

Skipping steps when performing backups

A backup using the orcharhino-maintain backup command proceeds in a sequence of steps. To skip part of the backup, add the --whitelist option to the command and the step label that you want to omit.

Procedure

  • To display a list of available step labels, enter the following command:

    # orcharhino-maintain advanced procedure run -h

  • To skip a step of the backup, enter the orcharhino-maintain backup command with the --whitelist option. For example:

    # orcharhino-maintain backup online \
--whitelist backup-metadata \
/var/backup_directory

Restoring orcharhino Server or orcharhino Proxy Server from a backup

You can restore orcharhino Server or orcharhino Proxy Server from the backup data that you create as part of Backing up orcharhino Server and orcharhino Proxy Server. 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.

Restoring from a full backup

Use this procedure to restore orcharhino or orcharhino Proxy Server from a full 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

  • Ensure that you are restoring to the correct instance. The orcharhino instance must have the same host name, configuration, and be the same minor version (X.Y) as the original system.

  • Ensure that you have an existing target directory. The target directory is read from the configuration files contained within the archive.

  • Ensure that you have enough space to store this 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, enter the following command:

    # du -sh /var/backup_directory

    To check for free space, enter the following command:

    # df -h /var/backup_directory

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

  • Ensure that all SELinux contexts are correct. Enter the following command to restore the correct SELinux contexts:

    # restorecon -Rv /
Procedure

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

  2. Ensure that all orcharhino Server or orcharhino Proxy Server services are running:

    # orcharhino-maintain health check

  3. Copy the backup data to orcharhino Server’s local file system. Use /var/ or /var/tmp/.

  4. Run the restoration script.

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

Additional resources

  • For troubleshooting, you can check /var/log/foreman/production.log and /var/log/messages.

Restoring from incremental backups

Use this procedure to restore orcharhino or orcharhino Proxy Server from incremental backups. 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.

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.

Procedure

  1. Ensure that all orcharhino Server or orcharhino Proxy Server services are running:

    # orcharhino-maintain health check

  2. Restore the last full backup using the instructions in Restoring from a Full Backup.

  3. Remove the full backup data from orcharhino Server’s local file system, for example, /var/ or /var/tmp/.

  4. Copy the incremental backup data to orcharhino Server’s local file system, for example, /var/ or /var/tmp/.

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

    # orcharhino-maintain restore /var/backup_directory/FIRST_INCREMENTAL
# orcharhino-maintain restore /var/backup_directory/SECOND_INCREMENTAL
Additional resources

  • For troubleshooting, you can check /var/log/foreman/production.log and /var/log/messages.

Backup and restore orcharhino Proxy Server using a virtual machine snapshot

If your orcharhino Proxy Server is a virtual machine, you can restore it from a snapshot. Creating weekly snapshots to restore from is recommended. In the event of failure, you can install, or configure a new orcharhino Proxy Server, and then synchronize the database content from orcharhino Server.

If required, deploy a new orcharhino Proxy Server, ensuring 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. 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. Then use the procedure Synchronizing content from orcharhino Server to orcharhino Proxy Servers to synchronize from orcharhino.

Synchronizing content from orcharhino Server to orcharhino Proxy Servers

Use this procedure to synchronize content from your orcharhino Server to your orcharhino Proxy Server.

Prerequisites

  • Ensure that you either select the relevant organization and location context of your orcharhino Proxy Server or choose Any Organization and Any Location.

Procedure

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

  2. Select your orcharhino Proxy Server.

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

Renaming orcharhino Server or orcharhino Proxy Server

To rename orcharhino Server or orcharhino Proxy Server, use the katello-change-hostname script.

When changing the domain name of your orcharhino Server or orcharhino Proxy Server, update the hostname using katello-change-hostname to avoid networking issues.

Renaming orcharhino Server

The host name of orcharhino Server is used by orcharhino Server components, all orcharhino Proxy Servers, and hosts registered to it for communication. This procedure ensures that in addition to renaming orcharhino Server, you also update all references to point to the new host name.

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

  • Back up 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 Server and orcharhino Proxy Server.

  • Run the hostname and hostname -f commands on 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, obtain 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 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.

Renaming orcharhino Proxy Server

The host name of orcharhino Proxy Server is referenced by orcharhino Server components and all hosts registered to it. This procedure ensures that in addition to renaming orcharhino Proxy Server, you also update all references to the new host name.

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

  • Back up 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 Server and orcharhino Proxy Server.

  • Run the hostname and hostname -f commands on 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.network2.example.com-certs.tar \
--foreman-proxy-fqdn new-orcharhino-proxy.network2.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.network2.example.com-certs.tar root@orcharhino-proxy.network2.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.network2.example.com \
--certs-tar /root/new-orcharhino-proxy.network2.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. On all hosts registered to your orcharhino Proxy Server, enter the following commands to reinstall the bootstrap RPM, reregister clients, and refresh their subscriptions.

    You can use the remote execution feature to perform this step. For more information, see Configuring and Setting up Remote Jobs 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.

Maintaining orcharhino Server

This chapter provides information on how to maintain a orcharhino Server, including information on how to work with audit records, how to clean unused tasks, and how to recover Pulp from a full disk.

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.

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.

Anonymizing audit records

You can 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, if you want to anonymize audit records that are older than seven days, enter the following command:

# foreman-rake audits:anonymize days=7

Deleting report records

Report records are created automatically in orcharhino. You can 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, if you want to delete report records that are older than seven days, enter the following command:

# foreman-rake reports:expire days=7

Configuring the cleaning unused tasks feature

orcharhino performs regular cleaning to reduce disc space in the database and limit the rate of disk growth. As a result, orcharhino backup completes faster and overall performance is higher.

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

Deleting task records

Task records are created automatically in orcharhino. You can 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, if you want to delete task records from successful repository synchronizations, enter the following command:

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

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.

Recovering from a full disk

The following procedure describes how to resolve the situation when a logical volume (LV) with the Pulp database on it has no free space.

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.

      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:

        # orcharhino-maintain service stop

      2. Grow the file system on the LV.

      3. Start orcharhino services:

        # orcharhino-maintain service start

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

Reclaiming PostgreSQL space

The PostgreSQL database can use a large amount of disk space especially in heavily loaded deployments. Use this procedure to reclaim some of this disk space on orcharhino.

Procedure

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

    # orcharhino-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:

    # orcharhino-maintain service start

Logging and reporting problems

The following sections describe the most commonly used log files and debugging tools available in orcharhino.

Increasing logging levels to help with debugging

You can increase the logging level of orcharhino components to troubleshoot orcharhino. Increasing the logging level to debug provides the most detailed information. The default logging level is info.

Increasing the logging level for the Foreman application

To increase logging for the Foreman application:

  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

For more information about orcharhino logging settings, use orcharhino-installer with the --full-help option:

# orcharhino-installer --full-help | grep logging

Increasing the logging level for Hammer

You can find the log in ~/.hammer/log/hammer.log.

To increase logging for Hammer:

  • In /etc/hammer/cli_config.yml, set the :log_level: option to debug:

:log_level: 'debug'

Increasing the logging level for orcharhino Proxy

You can find the log in /var/log/foreman-proxy/proxy.log.

To increase logging for orcharhino Proxy:

  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

Running orcharhino-installer will revert the setting back to default.

Increasing the logging level for Candlepin

You can find the logs in /var/log/candlepin/candlepin.log and /var/log/candlepin/error.log.

To increase logging for Candlepin:

  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

  1. After you complete debugging, reset the logging level to the default value:

    # orcharhino-installer --reset-katello-candlepin-loggers

Increasing the logging level for Redis

You can find the log for Redis in /var/log/redis/redis.log.

To increase logging for Redis:

  1. In /etc/redis.conf, set the logging level to debug:

    loglevel debug

  2. Restart the Redis service:

    # systemctl restart redis

Running orcharhino-installer will revert the setting to default.

Increasing the logging level for orcharhino installer

You can find the log files in /var/log/foreman-installer/.

To increase the logging level of the orcharhino installer, add the --verbose-log-level debug option during the installation:

# orcharhino-installer --verbose-log-level debug

Increasing the logging level for Pulp

By default, Pulp logs to syslog. You can view the log in /var/log/messages or with journalctl.

To increase logging for Pulp:

  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@1 \
pulpcore-worker@2 \
redis

Increasing the logging level for Puppet agent

You can find the logs in /var/log/puppetlabs/puppet/.

To increase logging for Puppet agent:

  1. Set the logging level to debug:

    # orcharhino-installer --puppet-agent-additional-settings log_level:debug

Increasing the logging level for Puppet server

You can find the logs in /var/log/puppetlabs/puppetserver/.

To increase logging for Puppet server:

  1. Set the logging level to debug:

    # orcharhino-installer --puppet-server-additional-settings log_level:debug

  2. Restart the Puppet server:

    # orcharhino-maintain service restart --only puppetserver

Increasing the logging level for Salt

Salt Master logs to /var/log/salt/master. Salt Minions log to /var/log/salt/minion.

To increase the logging level for Salt Master or Salt Minion:

  • In /etc/salt/master or /etc/salt/minion, set the logging level to debug:

log_level: debug

Configuring logging levels with Hammer CLI

You can use Hammer to log debugging information for various orcharhino components. The default logging level is INFO.

  • To list the components whose logging level you can change by using hammer:

    # hammer admin logging --list

  • To set DEBUG level logging for all components:

    # hammer admin logging --all --level-debug
# orcharhino-maintain service restart

  • To set PRODUCTION level logging for all components:

    # hammer admin logging --all --level-production
# orcharhino-maintain service restart

  • To set DEBUG level logging for a specific component:

    # hammer admin logging --components My_Component --level-debug
# orcharhino-maintain service restart

  • To list all available logging options:

    # hammer admin logging --help

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 for configuring logging with journal

  1. Enter the following orcharhino-installer command to configure logging to the journald service:

    # orcharhino-installer \
--foreman-logging-type journald \
--foreman-proxy-log JOURNAL

  2. Optional: To inspect the log messages, use 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

Procedure for configuring file-based logging

  1. Enter the following orcharhino-installer command to configure file-based logging:

    # orcharhino-installer \
--reset-foreman-logging-type \
--reset-foreman-proxy-log

  2. Optional: To inspect the log messages, view these files:

    • /var/log/foreman/production.log

    • /var/log/foreman-proxy.log

Procedure for configuring logging to JSON output

  1. On your orcharhino Server, enable logging to JSON output for orcharhino-installer:

    # orcharhino-installer \
--foreman-logging-layout json \
--foreman-logging-type file

  2. Optional: Inspect the log messages using jq:

    # cat /var/log/foreman/production.log | jq

Selective debugging with individual loggers

You can enable individual loggers for selective debugging.

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

Overview of individual loggers

The following list provides an overview of selected loggers. 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.

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.

Retrieving the status of services

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

Procedure

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

    • On the Smart Proxies tab, view the status of all orcharhino Proxies.

    • On the Compute Resources tab, view the status of attached compute resource providers.

    • In the Backend System Status table, view the status of all back-end services.

CLI procedure

  • Get information from the database and orcharhino services:

    # hammer ping

  • Check the status of the services running in systemd:

    # orcharhino-maintain service status

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

  • Perform a health check:

    $ orcharhino-maintain health check

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

Restarting services

orcharhino uses a set of back-end services. When troubleshooting, you can restart the services if needed.

Procedure

  • Restart orcharhino services:

    # orcharhino-maintain service restart

Utilities for processing log information

You can collect information from log files to troubleshoot orcharhino.

orcharhino-debug

The orcharhino-debug command collects configuration and log file data for orcharhino, its back-end services, and system information. This output is stored in a tar file. By default, the tar file is located at /tmp/orcharhino-debug-xxx.tar.xz.

Additionally, the orcharhino-debug command exports tasks run during the last 60 days. By default, the output tar file is located at /tmp/task-export-xxx.tar.xz. If the file is missing, see the file /tmp/task-export.log to learn why task export was unsuccessful. There is no timeout when running this command.

For more information, run orcharhino-debug -h.

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

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

System journal metadata

The following table lists metadata that the journald service uses in orcharhino. You can use this metadata to filter your queries.

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

Configuring external authentication

By using external authentication you can derive user and user group permissions from user group membership in an external identity provider. When you use external authentication, you do not have to create these users and maintain their group membership manually on orcharhino Server. In case the external source does not provide email, it will be requested during the first login through orcharhino management UI.

Important user and group account information

All user and group accounts must be local accounts. This is to ensure that there are no authentication conflicts between local accounts on your orcharhino Server and accounts in your Active Directory domain.

Your system is not affected by this conflict if your user and group accounts exist in both /etc/passwd and /etc/group files. For example, to check if entries for puppet, apache, foreman and foreman-proxy groups exist in both /etc/passwd and /etc/group files, enter the following commands:

# grep 'puppet\|apache\|foreman\|foreman-proxy' /etc/passwd /etc/group

You can set up multi-factor (MFA) or two-factor authentication (2FA) in orcharhino by using an Identity Management system (IdM) as external authentication source which enables multi-factor authentication. For more information, see Configuring External Authentication in Administering orcharhino.

Configuring an LDAP server as an external identity provider for orcharhino

Lightweight Directory Access Protocol (LDAP) is a set of open protocols used to access centrally stored information over a network. With orcharhino, you can use one or multiple LDAP directories for external authentication.

Users cannot use both FreeIPA and LDAP as an authentication method. After a user authenticates by using one of these methods, they cannot use the other method.

To change the authentication method for a user, remove the automatically created user from orcharhino.

For more information on using FreeIPA as an authentication method, see Using FreeIPA.

Configuring TLS for secure LDAP

If orcharhino uses TLS to establish a secure LDAP connection (LDAPS), you must obtain the CA certificates of your LDAP server and add them to the trusted CA list on the base operating system of your orcharhino Server.

If your LDAP server uses a certificate chain with intermediate certificate authorities, you must obtain all root and intermediate certificates and add them to the trusted CA list.

Procedure

  1. Obtain the CA certificate from the LDAP Server:

    1. If you use Active Directory Certificate Services, export the Enterprise PKI CA Certificate using the Base64 encoded X.509 format.

    2. Download the LDAP server certificate to a temporary location on the orcharhino Server, such as /tmp/example.crt. You will remove the certificate when finished.

      The filename extensions .cer and .crt are only conventions and can refer to DER binary or PEM ASCII format certificates.

  2. Add the LDAP certificate to your CA trust list:

    1. Install the LDAP certificate in the /etc/pki/tls/certs/ directory with the correct permissions:

      # install /tmp/example.crt /etc/pki/tls/certs/

      LDAP certificates must be individual files.

    2. Create a symbolic link to the LDAP certificate:

      # ln -s example.crt /etc/pki/tls/certs/$(openssl \
x509 -noout -hash -in \
/etc/pki/tls/certs/example.crt).0

    3. Restart the httpd service:

      # systemctl restart httpd

  3. Delete the downloaded LDAP certificate from the temporary location on your orcharhino Server.

Configuring orcharhino to use LDAP

Configure an LDAP authentication source to enable users to log in to orcharhino with their existing LDAP credentials.

Prerequisites

  • Your user account has the following permissions:

    • view_authenticators, create_authenticators, edit_authenticators

    • view_locations, assign_locations

    • view_organizations, assign_organizations

Procedure

  1. On your orcharhino Server, enable the Network Information System (NIS) service so that SELinux does not block outgoing LDAP connections:

    # setsebool -P nis_enabled on

  2. In the orcharhino management UI, navigate to Administer > Authentication Sources.

  3. From the LDAP menu, select Create.

  4. On the LDAP server tab, enter the details of your LDAP server.

    For TLS encrypted connections, select LDAPS to enable encryption.

  5. On the Account tab, enter the account information and domain name details.

    See Example Settings for LDAP Connections and Example LDAP Filters.

  6. On the Attribute mappings tab, map LDAP attributes to orcharhino attributes.

  7. On the Locations tab, select the locations you want orcharhino to assign to users created from the LDAP authentication source. These locations are available to users after they log in for the first time.

  8. On the Organizations tab, select the organizations you want orcharhino to assign to users created from the LDAP authentication source. These locations are available to users after they log in for the first time.

  9. Click Submit.

Next steps

  • If you did not select Automatically Create Accounts In orcharhino on the Account tab, create user accounts manually. For more information, see Creating a User in Administering orcharhino.

  • If you selected Automatically Create Accounts In orcharhino, LDAP users can now log in to orcharhino using their LDAP accounts and passwords.

  • After users log in for the first time, the orcharhino administrator must assign roles to them manually. For more information about assigning appropriate roles to user accounts, see Assigning Roles to a User in Administering orcharhino.

Example settings for LDAP connections

Example 1. Example settings for Active Directory LDAP connections

This example uses a dedicated service account called redhat that has bind, read, and search permissions on the user and group entries.

  • Account Username: DOMAIN\redhat

  • Account password: P@ssword

  • Base DN: DC=example,DC=COM

  • Login name attribute: userPrincipalName

  • First name attribute: givenName

  • Last name attribute: sn

  • Email address attribute: mail

  • Photo attribute: thumbnailPhoto

The userPrincipalName attribute allows the use of whitespace in usernames. The sAMAccountName attribute, which provides backwards compatibility with legacy Microsoft systems, does not allow the use of whitespace in usernames.

Example 2. Example settings for FreeIPA LDAP connections

This example uses a dedicated service account called redhat that has bind, read, and search permissions on the user and group entries.

  • Account Username: uid=redhat,cn=users,cn=accounts,dc=example,dc=com

  • Base DN: dc=example,dc=com

  • Groups Base DN: cn=groups,cn=accounts,dc=example,dc=com

  • Login name attribute: uid

  • First name attribute: givenName

  • Last name attribute: sn

  • Email address attribute: mail

Example 3. Example settings for POSIX LDAP connections

This example uses a dedicated service account called redhat that has bind, read, and search permissions on the user and group entries.

  • Account Username: uid=redhat,ou=users,dc=example,dc=com

  • Base DN: dc=example,dc=com

  • Groups Base DN: cn=employee,ou=userclass,dc=example,dc=com

  • Login name attribute: uid

  • First name attribute: givenName

  • Last name attribute: sn

  • Email address attribute: mail

Example LDAP filters

Example 4. Example LDAP filters for allowing specific users to login

You are using the following LDAP directory structure:

DC=Domain,DC=Example
   |
   |----- CN=Users
         |
         |----- CN=Group1
         |----- CN=Group2
         |----- CN=User1
         |----- CN=User2
         |----- CN=User3

Group membership is defined as follows:

  • Group1 includes users User1 and User3

  • Group2 includes users User2 and User3

For example, you can define the following search filters:

Search result (users) Filter

User1

(distinguishedName=cn=User1,cn=Users,dc=domain,dc=example)

User1, User3

(memberOf=cn=Group1,cn=Users,dc=domain,dc=example)

User2, User3

(memberOf=cn=Group2,cn=Users,dc=domain,dc=example)

User1, User2, User3

(|(memberOf=cn=Group1,cn=Users,dc=domain,dc=example)(memberOf=cn=Group2,cn=Users,dc=domain,dc=example))

User1, User2, User3

(memberOf:1.2.840.113556.1.4.1941:=cn=Users,dc=domain,dc=example)

Because group Users is a nested group that contains groups Group1 and Group2, the filter must include memberOf:1.2.840.113556.1.4.1941:= before the nested group name. This enables you to filter all users from the nested group.

Configuring a FreeIPA server as an external identity provider for orcharhino

FreeIPA deals with the management of individual identities, their credentials, and privileges used in a networking environment.

Using FreeIPA

This section shows how to integrate orcharhino Server with a FreeIPA server and how to enable host-based access control.

You can attach FreeIPA as an external authentication source with no single sign-on support. For more information, see configuring an ldap server as an external identity provider for project.

Users cannot use both FreeIPA and LDAP as an authentication method. After a user authenticates by using one of these methods, they cannot use the other method.

To change the authentication method for a user, remove the automatically created user from orcharhino.
Prerequisites

  • The base operating system of orcharhino Server must be enrolled in the FreeIPA domain by the FreeIPA administrator of your organization.

The examples in this chapter assume separation between FreeIPA and orcharhino configuration.

Configuring FreeIPA authentication on orcharhino Server

In the orcharhino CLI, configure FreeIPA authentication by first creating a host entry on the FreeIPA server.

Procedure

  1. On the FreeIPA server, to authenticate, enter the following command and enter your password when prompted:

    # kinit admin

  2. To verify that you have authenticated, enter the following command:

    # klist

  3. On the FreeIPA server, create a host entry for orcharhino Server and generate a one-time password, for example:

    # ipa host-add --random hostname

    The generated one-time password must be used on the client to complete FreeIPA-enrollment.

  4. Create an HTTP service for orcharhino Server, for example:

    # ipa service-add HTTP/hostname

  5. On orcharhino Server, install the IPA client:

    # dnf install ipa-client

  6. On orcharhino Server, enter the following command as root to configure FreeIPA-enrollment:

    # ipa-client-install --password OTP

    Replace OTP with the one-time password provided by the FreeIPA administrator.

  7. Set FreeIPA as the authentication provider, using one of the following commands:

    • If you only want to enable access to the orcharhino management UI but not the orcharhino API, enter:

      # orcharhino-installer \
--foreman-ipa-authentication=true

    • If you want to enable access both to the orcharhino management UI and the orcharhino API, enter:

      # orcharhino-installer \
--foreman-ipa-authentication-api=true \
--foreman-ipa-authentication=true

      Enabling access to both the orcharhino API and the orcharhino management UI can lead to security problems. After an IdM user receives a Kerberos ticket-granting ticket (TGT) by entering kinit user_name, an attacker can obtain an API session. The attack is possible even if the user did not previously enter the orcharhino login credentials anywhere, for example in the browser.

  8. Restart orcharhino services:

    # orcharhino-maintain service restart

External users can now log in to orcharhino using their FreeIPA credentials. They can now choose to either log in to orcharhino Server directly using their username and password or take advantage of the configured Kerberos single sign-on and obtain a ticket on their client machine and be logged in automatically. The two-factor authentication with one-time password (2FA OTP) is also supported.

Configuring host-based authentication control

HBAC rules define which machine within the domain a FreeIPA user is allowed to access. You can configure HBAC on the FreeIPA server to prevent selected users from accessing orcharhino Server. With this approach, you can prevent orcharhino from creating database entries for users that are not allowed to log in.

On the FreeIPA server, configure Host-Based Authentication Control (HBAC).

Procedure

  1. On the FreeIPA server, to authenticate, enter the following command and enter your password when prompted:

    # kinit admin

  2. To verify that you have authenticated, enter the following command:

    # klist

  3. Create HBAC service and rule on the FreeIPA server and link them together. The following examples use the PAM service name orcharhino-prod. Execute the following commands on the FreeIPA server:

    # ipa hbacsvc-add orcharhino-prod
# ipa hbacrule-add allow_orcharhino_prod
# ipa hbacrule-add-service allow_orcharhino_prod --hbacsvcs=orcharhino-prod

  4. Add the user who is to have access to the service orcharhino-prod, and the hostname of orcharhino Server:

    # ipa hbacrule-add-user allow_orcharhino_prod --user=username
# ipa hbacrule-add-host allow_orcharhino_prod --hosts=orcharhino.example.com

    Alternatively, host groups and user groups can be added to the alloworcharhino_prod_ rule.

  5. To check the status of the rule, execute:

    # ipa hbacrule-find orcharhino-prod
# ipa hbactest --user=username --host=orcharhino.example.com --service=orcharhino-prod

  6. Ensure the allow_all rule is disabled on the FreeIPA server.

  7. Configure the FreeIPA integration with orcharhino Server as described in Configuring FreeIPA Authentication on Server. On orcharhino Server, define the PAM service as root:

    # orcharhino-installer --foreman-pam-service=orcharhino-prod

Configuring Active Directory integrated with FreeIPA through cross-forest Kerberos trust as an external identity provider for orcharhino

Kerberos can create cross-forest trust that defines a relationship between two otherwise separate domain forests. A domain forest is a hierarchical structure of domains; both AD and FreeIPA constitute a forest. With a trust relationship enabled between AD and FreeIPA, AD users can access Linux hosts and services using a single set of credentials.

Active Directory with cross-forest trust

Kerberos can create cross-forest trust that defines a relationship between two otherwise separate domain forests. A domain forest is a hierarchical structure of domains; both AD and FreeIPA constitute a forest. With a trust relationship enabled between AD and FreeIPA, users of AD can access Linux hosts and services using a single set of credentials.

From the orcharhino point of view, the configuration process is the same as integration with FreeIPA server without cross-forest trust configured. orcharhino Server has to be enrolled in the IdM domain and integrated as described in Using FreeIPA.

Configuring Wildfly-based Keycloak authentication for orcharhino

Use this section to configure orcharhino to use Wildfly-based Keycloak as an OpenID provider for external authentication.

Prerequisites for configuring orcharhino with Wildfly-based Keycloak authentication

Before configuring orcharhino with Wildfly-based Keycloak external authentication, ensure that you meet the following requirements:

  • A working installation of Wildfly-based Keycloak server that uses HTTPS instead of HTTP.

  • A Wildfly-based Keycloak account with admin privileges.

  • A realm for orcharhino user accounts created in Wildfly-based Keycloak.

  • If the certificates or the CA are self-signed, ensure that they are added to the end-user certificate trust store.

  • Users imported or added to Wildfly-based Keycloak.

    If you have an existing user database configured such as LDAP or Kerberos, you can import users from it by configuring user federation.

    If you do not have an existing user database configured, you can manually create users in Wildfly-based Keycloak.

Registering orcharhino as a client of Keycloak

Use this procedure to register orcharhino to Keycloak as a client and configure orcharhino to use Keycloak as an authentication source.

You can configure orcharhino and Keycloak with two different authentication methods:

  1. Users authenticate to orcharhino using the orcharhino management UI.

  2. Users authenticate to orcharhino using the orcharhino CLI.

You must decide on how you want your users to authenticate in advance because both methods require different orcharhino clients to be registered to Keycloak and configured. The steps to register and configure orcharhino client in Keycloak are distinguished within the procedure.

You can also register two different orcharhino clients to Keycloak if you want to use both authentication methods and configure both clients accordingly.

Procedure

  1. On orcharhino Server, install the following packages:

    # dnf install mod_auth_openidc keycloak-httpd-client-install python3-lxml

  2. Register orcharhino to Keycloak as a client. Note that you the registration process for logging in using the web UI and the CLI are different. You can register two clients orcharhino clients to Keycloak to be able to log in to orcharhino from the web UI and the CLI.

    • If you want you users to authenticate to orcharhino using the web UI, create a client as follows:

      # keycloak-httpd-client-install --app-name foreman-openidc \
--keycloak-server-url "https://keycloak.example.com" \
--keycloak-admin-username "admin" \
--keycloak-realm "orcharhino_Realm" \
--keycloak-admin-realm master \
--keycloak-auth-role root-admin \
-t openidc -l /users/extlogin --force

      Enter the password for the administer account when prompted. This command creates a client for orcharhino in Keycloak.

      Then, configure orcharhino to use Keycloak as an authentication source:

      # orcharhino-installer --foreman-keycloak true \
--foreman-keycloak-app-name "foreman-openidc" \
--foreman-keycloak-realm "orcharhino_Realm"

    • If you want your users to authenticate to orcharhino using the CLI, create a client as follows:

      # keycloak-httpd-client-install --app-name hammer-openidc \
--keycloak-server-url "https://keycloak.example.com" \
--keycloak-admin-username "admin" \
--keycloak-realm "orcharhino_Realm" \
--keycloak-admin-realm master \
--keycloak-auth-role root-admin \
-t openidc -l /users/extlogin --force

      Enter the password for the administer account when prompted. This command creates a client for orcharhino in Keycloak.

  3. Restart the httpd service:

    # systemctl restart httpd

Configuring the orcharhino client in Wildfly-based Keycloak

Use this procedure to configure the orcharhino client in the Wildfly-based Keycloak web UI and create group and audience mappers for the orcharhino client.

Procedure

  1. In the Wildfly-based Keycloak web UI, navigate to the created orcharhino realm, then Clients and click the orcharhino client.

  2. Configure access type:

    • If you want your users to authenticate to orcharhino using the orcharhino management UI, from the Access Type list, select confidential.

    • If you want your users to authenticate to orcharhino using the CLI, from the Access Type list, select public.

  3. In the Valid redirect URI fields, add a valid redirect URI.

    • If you want your users to authenticate to orcharhino using the orcharhino management UI, in the blank field below the existing URI, enter a URI in the form https://orcharhino.example.com/users/extlogin. Note that you must add the string /users/extlogin after the orcharhino FQDN.

      After completing this step, the orcharhino client for logging in using the orcharhino management UI must have the following Valid Redirect URIs:

      https://orcharhino.example.com/users/extlogin/redirect_uri
https://orcharhino.example.com/users/extlogin

    • If you want your users to authenticate to orcharhino using the CLI, in the blank field below the existing URI, enter urn:ietf:wg:oauth:2.0:oob.

      After completing this step, the orcharhino client for logging in using the CLI must have the following Valid Redirect URIs:

      https://orcharhino.example.com/users/extlogin/redirect_uri
urn:ietf:wg:oauth:2.0:oob

  4. Click Save.

  5. Click the Mappers tab and click Create to add an audience mapper.

  6. In the Name field, enter a name for the audience mapper.

  7. From the Mapper Type list, select Audience.

  8. From the Included Client Audience list, select the orcharhino client.

  9. Click Save.

  10. Click Create to add a group mapper so that you can specify authorization in orcharhino based on group membership.

  11. In the Name field, enter a name for the group mapper.

  12. From the Mapper Type list, select Group Membership.

  13. In the Token Claim Name field, enter groups.

  14. Set the Full group path setting to OFF.

  15. Click Save.

Configuring orcharhino settings for Wildfly-based Keycloak authentication using the web UI

Use this procedure to configure orcharhino settings for Wildfly-based Keycloak authentication using the orcharhino management UI.

Note that you can navigate to the following URL within your realm to obtain values to configure orcharhino settings: https://keycloak.example.com/auth/realms/orcharhino_Realm/.well-known/openid-configuration

Prerequisites

  • Ensure that the Access Type setting in the orcharhino client in the Wildfly-based Keycloak web UI is set to confidential.

Procedure

  1. In the orcharhino management UI, navigate to Administer > Settings, and click the Authentication tab.

  2. Locate the Authorize login delegation row, and in the Value column, set the value to Yes.

  3. Locate the Authorize login delegation auth source user autocreate row, and in the Value column, set the value to External.

  4. Locate the Login delegation logout URL row, and in the Value column, set the value to https://orcharhino.example.com/users/extlogout.

  5. Locate the OIDC Algorithm row, and in the Value column, set the algorithm for encoding on Wildfly-based Keycloak to RS256.

  6. Locate the OIDC Audience row, and in the Value column, set the value to the client ID for Wildfly-based Keycloak.

  7. Locate the OIDC Issuer row, and in the Value column, set the value to https://keycloak.example.com/auth/realms/orcharhino_Realm.

  8. Locate the OIDC JWKs URL row, and in the Value column, set the value to https://keycloak.example.com/auth/realms/orcharhino_Realm/protocol/openid-connect/certs.

  9. In the orcharhino management UI, navigate to Administer > Authentication Sources, click the vertical ellipsis on the External card, and select Edit.

  10. Click the Locations tab and add locations that can use the Wildfly-based Keycloak authentication source.

  11. Click the Organizations tab and add organizations that can use the Wildfly-based Keycloak authentication source.

  12. Click Submit.

Configuring orcharhino settings for Wildfly-based Keycloak authentication using the CLI

Use this procedure to configure orcharhino settings for Wildfly-based Keycloak authentication using the orcharhino CLI.

Note that you can navigate to the following URL within your realm to obtain values to configure orcharhino settings: https://keycloak.example.com/auth/realms/orcharhino_Realm/.well-known/openid-configuration

Prerequisites

  • Ensure that the Access Type setting in the orcharhino client in the Wildfly-based Keycloak web UI is set to public.

Procedure

  1. On orcharhino, set the login delegation to true so that users can authenticate using the Open IDC protocol:

    # hammer settings set --name authorize_login_delegation --value true

  2. Set the login delegation logout URL:

    # hammer settings set --name login_delegation_logout_url \
--value https://orcharhino.example.com/users/extlogout

  3. Set the algorithm for encoding on Wildfly-based Keycloak, for example, RS256:

    # hammer settings set --name oidc_algorithm --value 'RS256'

  4. Open the keycloak.example.com/auth/realms/KEYCLOAK_REALM/.well-known/openid-configuration URL and note the values to populate the options in the following steps.

  5. Add the value for the Hammer client in the Open IDC audience:

    # hammer settings set --name oidc_audience \
--value "['orcharhino.example.com-hammer-openidc']"

    If you register several Wildfly-based Keycloak clients to orcharhino, ensure that you append all audiences in the array. For example:

    # hammer settings set --name oidc_audience \
--value "['orcharhino.example.com-foreman-openidc', 'orcharhino.example.com-hammer-openidc']"

  6. Set the value for the Open IDC issuer:

    # hammer settings set --name oidc_issuer \
--value "keycloak.example.com/auth/realms/KEYCLOAK_REALM"

  7. Set the value for Open IDC Java Web Token (JWT):

    # hammer settings set --name oidc_jwks_url \
--value "{keycloak-example.com}/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs"

  8. Retrieve the ID of the Wildfly-based Keycloak authentication source:

    # hammer auth-source external list

  9. Set the location and organization:

    # hammer auth-source external update --id Authentication Source ID \
--location-ids Location ID --organization-ids Organization ID

Logging in to the orcharhino management UI using Keycloak

Use this procedure to log in to the orcharhino management UI using Keycloak.

Procedure

  • In your browser, log in to orcharhino and enter your credentials.

Logging in to the orcharhino CLI using Keycloak

Use this procedure to authenticate to the orcharhino CLI using the code grant type.

Procedure

  1. To authenticate to the orcharhino CLI using the code grant type, enter the following command:

    # hammer auth login oauth \
--two-factor \
--oidc-token-endpoint 'https://keycloak.example.com/auth/realms/ssl-realm/protocol/openid-connect/token' \
--oidc-authorization-endpoint 'https://keycloak.example.com/auth' \
--oidc-client-id 'orcharhino.example.com-foreman-openidc' \
--oidc-redirect-uri urn:ietf:wg:oauth:2.0:oob

    The command prompts you to enter a success code.

  2. To retrieve the success code, navigate to the URL that the command returns and provide the required information.

  3. Copy the success code that the web UI returns.

  4. In the command prompt of hammer auth login oauth, enter the success code to authenticate to the orcharhino CLI.

Configuring group mapping for Keycloak authentication

Optionally, to implement the Role Based Access Control (RBAC), create a group in orcharhino, assign a role to this group, and then map an Active Directory group to the orcharhino group. As a result, anyone in the given group in Keycloak are logged in under the corresponding orcharhino group. This example configures users of the orcharhino-admin user group in the Active Directory to authenticate as users with administrator privileges on orcharhino.

Procedure

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

  2. Click Create User Group.

  3. In the Name field, enter a name for the user group. The name should not be the same as in the Active Directory.

  4. Do not add users and user groups to the right-hand columns. Click the Roles tab.

  5. Select the Administer checkbox.

  6. Click the External Groups tab.

  7. Click Add external user group.

  8. In the Name field, enter the name of the Active Directory group.

  9. From the list, select EXTERNAL.

Configuring Wildfly-based Keycloak authentication with TOTP cards for orcharhino

Use this section to configure orcharhino to use Wildfly-based Keycloak as an OpenID provider for external authentication with TOTP cards.

Prerequisites for configuring orcharhino with Wildfly-based Keycloak authentication

Before configuring orcharhino with Wildfly-based Keycloak external authentication, ensure that you meet the following requirements:

  • A working installation of Wildfly-based Keycloak server that uses HTTPS instead of HTTP.

  • A Wildfly-based Keycloak account with admin privileges.

  • A realm for orcharhino user accounts created in Wildfly-based Keycloak.

  • If the certificates or the CA are self-signed, ensure that they are added to the end-user certificate trust store.

  • Users imported or added to Wildfly-based Keycloak.

    If you have an existing user database configured such as LDAP or Kerberos, you can import users from it by configuring user federation.

    If you do not have an existing user database configured, you can manually create users in Wildfly-based Keycloak.

Registering orcharhino as a client of Keycloak

Use this procedure to register orcharhino to Keycloak as a client and configure orcharhino to use Keycloak as an authentication source.

You can configure orcharhino and Keycloak with two different authentication methods:

  1. Users authenticate to orcharhino using the orcharhino management UI.

  2. Users authenticate to orcharhino using the orcharhino CLI.

You must decide on how you want your users to authenticate in advance because both methods require different orcharhino clients to be registered to Keycloak and configured. The steps to register and configure orcharhino client in Keycloak are distinguished within the procedure.

You can also register two different orcharhino clients to Keycloak if you want to use both authentication methods and configure both clients accordingly.

Procedure

  1. On orcharhino Server, install the following packages:

    # dnf install mod_auth_openidc keycloak-httpd-client-install python3-lxml

  2. Register orcharhino to Keycloak as a client. Note that you the registration process for logging in using the web UI and the CLI are different. You can register two clients orcharhino clients to Keycloak to be able to log in to orcharhino from the web UI and the CLI.

    • If you want you users to authenticate to orcharhino using the web UI, create a client as follows:

      # keycloak-httpd-client-install --app-name foreman-openidc \
--keycloak-server-url "https://keycloak.example.com" \
--keycloak-admin-username "admin" \
--keycloak-realm "orcharhino_Realm" \
--keycloak-admin-realm master \
--keycloak-auth-role root-admin \
-t openidc -l /users/extlogin --force

      Enter the password for the administer account when prompted. This command creates a client for orcharhino in Keycloak.

      Then, configure orcharhino to use Keycloak as an authentication source:

      # orcharhino-installer --foreman-keycloak true \
--foreman-keycloak-app-name "foreman-openidc" \
--foreman-keycloak-realm "orcharhino_Realm"

    • If you want your users to authenticate to orcharhino using the CLI, create a client as follows:

      # keycloak-httpd-client-install --app-name hammer-openidc \
--keycloak-server-url "https://keycloak.example.com" \
--keycloak-admin-username "admin" \
--keycloak-realm "orcharhino_Realm" \
--keycloak-admin-realm master \
--keycloak-auth-role root-admin \
-t openidc -l /users/extlogin --force

      Enter the password for the administer account when prompted. This command creates a client for orcharhino in Keycloak.

  3. Restart the httpd service:

    # systemctl restart httpd

Configuring the orcharhino client in Wildfly-based Keycloak

Use this procedure to configure the orcharhino client in the Wildfly-based Keycloak web UI and create group and audience mappers for the orcharhino client.

Procedure

  1. In the Wildfly-based Keycloak web UI, navigate to the created orcharhino realm, then Clients and click the orcharhino client.

  2. Configure access type:

    • If you want your users to authenticate to orcharhino using the orcharhino management UI, from the Access Type list, select confidential.

    • If you want your users to authenticate to orcharhino using the CLI, from the Access Type list, select public.

  3. In the Valid redirect URI fields, add a valid redirect URI.

    • If you want your users to authenticate to orcharhino using the orcharhino management UI, in the blank field below the existing URI, enter a URI in the form https://orcharhino.example.com/users/extlogin. Note that you must add the string /users/extlogin after the orcharhino FQDN.

      After completing this step, the orcharhino client for logging in using the orcharhino management UI must have the following Valid Redirect URIs:

      https://orcharhino.example.com/users/extlogin/redirect_uri
https://orcharhino.example.com/users/extlogin

    • If you want your users to authenticate to orcharhino using the CLI, in the blank field below the existing URI, enter urn:ietf:wg:oauth:2.0:oob.

      After completing this step, the orcharhino client for logging in using the CLI must have the following Valid Redirect URIs:

      https://orcharhino.example.com/users/extlogin/redirect_uri
urn:ietf:wg:oauth:2.0:oob

  4. Click Save.

  5. Click the Mappers tab and click Create to add an audience mapper.

  6. In the Name field, enter a name for the audience mapper.

  7. From the Mapper Type list, select Audience.

  8. From the Included Client Audience list, select the orcharhino client.

  9. Click Save.

  10. Click Create to add a group mapper so that you can specify authorization in orcharhino based on group membership.

  11. In the Name field, enter a name for the group mapper.

  12. From the Mapper Type list, select Group Membership.

  13. In the Token Claim Name field, enter groups.

  14. Set the Full group path setting to OFF.

  15. Click Save.

Configuring orcharhino settings for Wildfly-based Keycloak authentication using the web UI

Use this procedure to configure orcharhino settings for Wildfly-based Keycloak authentication using the orcharhino management UI.

Note that you can navigate to the following URL within your realm to obtain values to configure orcharhino settings: https://keycloak.example.com/auth/realms/orcharhino_Realm/.well-known/openid-configuration

Prerequisites

  • Ensure that the Access Type setting in the orcharhino client in the Wildfly-based Keycloak web UI is set to confidential.

Procedure

  1. In the orcharhino management UI, navigate to Administer > Settings, and click the Authentication tab.

  2. Locate the Authorize login delegation row, and in the Value column, set the value to Yes.

  3. Locate the Authorize login delegation auth source user autocreate row, and in the Value column, set the value to External.

  4. Locate the Login delegation logout URL row, and in the Value column, set the value to https://orcharhino.example.com/users/extlogout.

  5. Locate the OIDC Algorithm row, and in the Value column, set the algorithm for encoding on Wildfly-based Keycloak to RS256.

  6. Locate the OIDC Audience row, and in the Value column, set the value to the client ID for Wildfly-based Keycloak.

  7. Locate the OIDC Issuer row, and in the Value column, set the value to https://keycloak.example.com/auth/realms/orcharhino_Realm.

  8. Locate the OIDC JWKs URL row, and in the Value column, set the value to https://keycloak.example.com/auth/realms/orcharhino_Realm/protocol/openid-connect/certs.

  9. In the orcharhino management UI, navigate to Administer > Authentication Sources, click the vertical ellipsis on the External card, and select Edit.

  10. Click the Locations tab and add locations that can use the Wildfly-based Keycloak authentication source.

  11. Click the Organizations tab and add organizations that can use the Wildfly-based Keycloak authentication source.

  12. Click Submit.

Configuring orcharhino settings for Wildfly-based Keycloak authentication using the CLI

Use this procedure to configure orcharhino settings for Wildfly-based Keycloak authentication using the orcharhino CLI.

Note that you can navigate to the following URL within your realm to obtain values to configure orcharhino settings: https://keycloak.example.com/auth/realms/orcharhino_Realm/.well-known/openid-configuration

Prerequisites

  • Ensure that the Access Type setting in the orcharhino client in the Wildfly-based Keycloak web UI is set to public.

Procedure

  1. On orcharhino, set the login delegation to true so that users can authenticate using the Open IDC protocol:

    # hammer settings set --name authorize_login_delegation --value true

  2. Set the login delegation logout URL:

    # hammer settings set --name login_delegation_logout_url \
--value https://orcharhino.example.com/users/extlogout

  3. Set the algorithm for encoding on Wildfly-based Keycloak, for example, RS256:

    # hammer settings set --name oidc_algorithm --value 'RS256'

  4. Open the keycloak.example.com/auth/realms/KEYCLOAK_REALM/.well-known/openid-configuration URL and note the values to populate the options in the following steps.

  5. Add the value for the Hammer client in the Open IDC audience:

    # hammer settings set --name oidc_audience \
--value "['orcharhino.example.com-hammer-openidc']"

    If you register several Wildfly-based Keycloak clients to orcharhino, ensure that you append all audiences in the array. For example:

    # hammer settings set --name oidc_audience \
--value "['orcharhino.example.com-foreman-openidc', 'orcharhino.example.com-hammer-openidc']"

  6. Set the value for the Open IDC issuer:

    # hammer settings set --name oidc_issuer \
--value "keycloak.example.com/auth/realms/KEYCLOAK_REALM"

  7. Set the value for Open IDC Java Web Token (JWT):

    # hammer settings set --name oidc_jwks_url \
--value "{keycloak-example.com}/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs"

  8. Retrieve the ID of the Wildfly-based Keycloak authentication source:

    # hammer auth-source external list

  9. Set the location and organization:

    # hammer auth-source external update --id Authentication Source ID \
--location-ids Location ID --organization-ids Organization ID

Configuring orcharhino with Keycloak for TOTP authentication

Use this procedure to configure orcharhino to use Keycloak as an OpenID provider for external authentication with Time-based One-time Password (TOTP).

Procedure

  1. In the Keycloak web UI, navigate to the orcharhino realm.

  2. Navigate to Authentication, and click the OTP Policy tab.

  3. Ensure that the Supported Applications field includes FreeOTP or Google Authenticator.

  4. Configure the OTP settings to suit your requirements.

  5. Optional: If you want to use TOTP authentication as a default authentication method for all users, click the Flows tab, and to the right of the OTP Form setting, select REQUIRED.

  6. Click the Required Actions tab.

  7. To the right of the Configure OTP row, select the Default Action checkbox.

Logging in to the orcharhino management UI using Keycloak TOTP authentication

Use this procedure to log in to the orcharhino management UI using Keycloak TOTP authentication.

Procedure

  1. Log in to orcharhino, orcharhino redirects you to the Keycloak login screen.

  2. Enter your username and password, and click Log In.

  3. The first attempt to log in, Keycloak requests you to configure your client by scanning the barcode and entering the pin displayed.

  4. After you configure your client and enter a valid PIN, Keycloak redirects you to orcharhino and logs you in.

Logging in to the orcharhino CLI using Keycloak

Use this procedure to authenticate to the orcharhino CLI using the code grant type.

Procedure

  1. To authenticate to the orcharhino CLI using the code grant type, enter the following command:

    # hammer auth login oauth \
--two-factor \
--oidc-token-endpoint 'https://keycloak.example.com/auth/realms/ssl-realm/protocol/openid-connect/token' \
--oidc-authorization-endpoint 'https://keycloak.example.com/auth' \
--oidc-client-id 'orcharhino.example.com-foreman-openidc' \
--oidc-redirect-uri urn:ietf:wg:oauth:2.0:oob

    The command prompts you to enter a success code.

  2. To retrieve the success code, navigate to the URL that the command returns and provide the required information.

  3. Copy the success code that the web UI returns.

  4. In the command prompt of hammer auth login oauth, enter the success code to authenticate to the orcharhino CLI.

Configuring group mapping for Keycloak authentication

Optionally, to implement the Role Based Access Control (RBAC), create a group in orcharhino, assign a role to this group, and then map an Active Directory group to the orcharhino group. As a result, anyone in the given group in Keycloak are logged in under the corresponding orcharhino group. This example configures users of the orcharhino-admin user group in the Active Directory to authenticate as users with administrator privileges on orcharhino.

Procedure

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

  2. Click Create User Group.

  3. In the Name field, enter a name for the user group. The name should not be the same as in the Active Directory.

  4. Do not add users and user groups to the right-hand columns. Click the Roles tab.

  5. Select the Administer checkbox.

  6. Click the External Groups tab.

  7. Click Add external user group.

  8. In the Name field, enter the name of the Active Directory group.

  9. From the list, select EXTERNAL.

Configuring Quarkus-based Keycloak authentication for orcharhino

Use this section to configure orcharhino to use Quarkus-based Keycloak as an OpenID provider for external authentication.

Prerequisites for configuring orcharhino with Quarkus-based Keycloak authentication

Before configuring orcharhino with Quarkus-based Keycloak external authentication, ensure that you meet the following requirements:

  • A working installation of Quarkus-based Keycloak server that uses HTTPS instead of HTTP.

  • Configuring Quarkus-based Quarkus-based Keycloak authentication requires the --http-relative-path=/auth context path to be configured in your Quarkus-based Keycloak system setup. If you want to use a different context path, make manual adjustments after the initialisation with /auth or fully set up the foreman-openidc_oidc_keycloak_Foreman_Realm.conf file of the httpd service manually.

    For more information, see Different context-path on reverse proxy in the Quarkus-based Keycloak Administration Guide.

  • A Quarkus-based Keycloak account with admin privileges.

  • A realm for orcharhino user accounts created in Quarkus-based Keycloak.

  • If the certificates or the CA are self-signed, ensure that they are added to the end-user certificate trust store.

  • Users imported or added to Quarkus-based Keycloak.

    If you have an existing user database configured such as LDAP or Kerberos, you can import users from it by configuring user federation.

    If you do not have an existing user database configured, you can manually create users in Quarkus-based Keycloak.

Registering orcharhino as a client of Keycloak

Use this procedure to register orcharhino to Keycloak as a client and configure orcharhino to use Keycloak as an authentication source.

You can configure orcharhino and Keycloak with two different authentication methods:

  1. Users authenticate to orcharhino using the orcharhino management UI.

  2. Users authenticate to orcharhino using the orcharhino CLI.

You must decide on how you want your users to authenticate in advance because both methods require different orcharhino clients to be registered to Keycloak and configured. The steps to register and configure orcharhino client in Keycloak are distinguished within the procedure.

You can also register two different orcharhino clients to Keycloak if you want to use both authentication methods and configure both clients accordingly.

Procedure

  1. On orcharhino Server, install the following packages:

    # dnf install mod_auth_openidc keycloak-httpd-client-install python3-lxml

  2. Register orcharhino to Keycloak as a client. Note that you the registration process for logging in using the web UI and the CLI are different. You can register two clients orcharhino clients to Keycloak to be able to log in to orcharhino from the web UI and the CLI.

    • If you want you users to authenticate to orcharhino using the web UI, create a client as follows:

      # keycloak-httpd-client-install --app-name foreman-openidc \
--keycloak-server-url "https://keycloak.example.com" \
--keycloak-admin-username "admin" \
--keycloak-realm "orcharhino_Realm" \
--keycloak-admin-realm master \
--keycloak-auth-role root-admin \
-t openidc -l /users/extlogin --force

      Enter the password for the administer account when prompted. This command creates a client for orcharhino in Keycloak.

      Then, configure orcharhino to use Keycloak as an authentication source:

      # orcharhino-installer --foreman-keycloak true \
--foreman-keycloak-app-name "foreman-openidc" \
--foreman-keycloak-realm "orcharhino_Realm"

    • If you want your users to authenticate to orcharhino using the CLI, create a client as follows:

      # keycloak-httpd-client-install --app-name hammer-openidc \
--keycloak-server-url "https://keycloak.example.com" \
--keycloak-admin-username "admin" \
--keycloak-realm "orcharhino_Realm" \
--keycloak-admin-realm master \
--keycloak-auth-role root-admin \
-t openidc -l /users/extlogin --force

      Enter the password for the administer account when prompted. This command creates a client for orcharhino in Keycloak.

  3. Restart the httpd service:

    # systemctl restart httpd

Configuring the orcharhino client in Quarkus-based Keycloak

Use this procedure to configure the orcharhino client in the Quarkus-based Keycloak web UI and create group and audience mappers for the orcharhino client.

Procedure

  1. In the Quarkus-based Keycloak web UI, navigate to the created orcharhino realm, then Clients and click the orcharhino client.

  2. Configure access type:

    • If you want your users to authenticate to orcharhino using the orcharhino management UI, set the Client authentication setting to ON.

    • If you want your users to authenticate to orcharhino using the CLI, set the Client authentication setting to OFF.

  3. In the Valid redirect URI fields, add a valid redirect URI.

    • If you want your users to authenticate to orcharhino using the orcharhino management UI, in the blank field below the existing URI, enter a URI in the form https://orcharhino.example.com/users/extlogin. Note that you must add the string /users/extlogin after the orcharhino FQDN.

      After completing this step, the orcharhino client for logging in using the orcharhino management UI must have the following Valid Redirect URIs:

      https://orcharhino.example.com/users/extlogin/redirect_uri
https://orcharhino.example.com/users/extlogin

    • If you want your users to authenticate to orcharhino using the CLI, in the blank field below the existing URI, enter urn:ietf:wg:oauth:2.0:oob.

      After completing this step, the orcharhino client for logging in using the CLI must have the following Valid Redirect URIs:

      https://orcharhino.example.com/users/extlogin/redirect_uri
urn:ietf:wg:oauth:2.0:oob

  4. Click Save.

  5. Click the Client Scopes tab and enter the scope called like the client ending with -dedicated.

  6. Click Add mapper, followed by By configuration (or if no mappers are configured Configure a new mapper) and select the Audience mapper.

  7. In the Name field, enter a name for the audience mapper.

  8. From the Included Client Audience list, select the orcharhino client.

  9. Set the Add to ID token setting to ON.

  10. Click Save.

  11. Click Add mapper, followed by By configuration and select the Group Membership mapper to add a group mapper so that you can specify authorization in orcharhino based on group membership.

  12. In the Name field, enter a name for the group mapper.

  13. In the Token Claim Name field, enter groups.

  14. Set the Full group path setting to OFF.

  15. Click Save.

Configuring orcharhino settings for Quarkus-based Keycloak authentication using the web UI

Use this procedure to configure orcharhino settings for Quarkus-based Keycloak authentication using the orcharhino management UI.

Note that you can navigate to the following URL within your realm to obtain values to configure orcharhino settings: https://keycloak.example.com/auth/realms/orcharhino_Realm/.well-known/openid-configuration

Prerequisites

  • Ensure that the Client authentication setting in the orcharhino client in the Quarkus-based Keycloak web UI is set to ON.

Procedure

  1. In the orcharhino management UI, navigate to Administer > Settings, and click the Authentication tab.

  2. Locate the Authorize login delegation row, and in the Value column, set the value to Yes.

  3. Locate the Authorize login delegation auth source user autocreate row, and in the Value column, set the value to External.

  4. Locate the Login delegation logout URL row, and in the Value column, set the value to https://orcharhino.example.com/users/extlogout.

  5. Locate the OIDC Algorithm row, and in the Value column, set the algorithm for encoding on Quarkus-based Keycloak to RS256.

  6. Locate the OIDC Audience row, and in the Value column, set the value to the client ID for Quarkus-based Keycloak.

  7. Locate the OIDC Issuer row, and in the Value column, set the value to https://keycloak.example.com/auth/realms/orcharhino_Realm.

  8. Locate the OIDC JWKs URL row, and in the Value column, set the value to https://keycloak.example.com/auth/realms/orcharhino_Realm/protocol/openid-connect/certs.

  9. In the orcharhino management UI, navigate to Administer > Authentication Sources, click the vertical ellipsis on the External card, and select Edit.

  10. Click the Locations tab and add locations that can use the Quarkus-based Keycloak authentication source.

  11. Click the Organizations tab and add organizations that can use the Quarkus-based Keycloak authentication source.

  12. Click Submit.

Configuring orcharhino settings for Quarkus-based Keycloak authentication using the CLI

Use this procedure to configure orcharhino settings for Quarkus-based Keycloak authentication using the orcharhino CLI.

Note that you can navigate to the following URL within your realm to obtain values to configure orcharhino settings: https://keycloak.example.com/auth/realms/orcharhino_Realm/.well-known/openid-configuration

Prerequisites

  • Ensure that the Client authentication setting in the orcharhino client in the Quarkus-based Keycloak web UI is set to OFF.

Procedure

  1. On orcharhino, set the login delegation to true so that users can authenticate using the Open IDC protocol:

    # hammer settings set --name authorize_login_delegation --value true

  2. Set the login delegation logout URL:

    # hammer settings set --name login_delegation_logout_url \
--value https://orcharhino.example.com/users/extlogout

  3. Set the algorithm for encoding on Quarkus-based Keycloak, for example, RS256:

    # hammer settings set --name oidc_algorithm --value 'RS256'

  4. Open the keycloak.example.com/auth/realms/KEYCLOAK_REALM/.well-known/openid-configuration URL and note the values to populate the options in the following steps.

  5. Add the value for the Hammer client in the Open IDC audience:

    # hammer settings set --name oidc_audience \
--value "['orcharhino.example.com-hammer-openidc']"

    If you register several Quarkus-based Keycloak clients to orcharhino, ensure that you append all audiences in the array. For example:

    # hammer settings set --name oidc_audience \
--value "['orcharhino.example.com-foreman-openidc', 'orcharhino.example.com-hammer-openidc']"

  6. Set the value for the Open IDC issuer:

    # hammer settings set --name oidc_issuer \
--value "keycloak.example.com/auth/realms/KEYCLOAK_REALM"

  7. Set the value for Open IDC Java Web Token (JWT):

    # hammer settings set --name oidc_jwks_url \
--value "keycloak.example.com/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs"

  8. Retrieve the ID of the Quarkus-based Keycloak authentication source:

    # hammer auth-source external list

  9. Set the location and organization:

    # hammer auth-source external update --id Authentication Source ID \
--location-ids Location ID --organization-ids Organization ID

Logging in to the orcharhino management UI using Keycloak

Use this procedure to log in to the orcharhino management UI using Keycloak.

Procedure

  • In your browser, log in to orcharhino and enter your credentials.

Logging in to the orcharhino CLI using Keycloak

Use this procedure to authenticate to the orcharhino CLI using the code grant type.

Procedure

  1. To authenticate to the orcharhino CLI using the code grant type, enter the following command:

    # hammer auth login oauth \
--two-factor \
--oidc-token-endpoint 'https://keycloak.example.com/auth/realms/ssl-realm/protocol/openid-connect/token' \
--oidc-authorization-endpoint 'https://keycloak.example.com/auth' \
--oidc-client-id 'orcharhino.example.com-foreman-openidc' \
--oidc-redirect-uri urn:ietf:wg:oauth:2.0:oob

    The command prompts you to enter a success code.

  2. To retrieve the success code, navigate to the URL that the command returns and provide the required information.

  3. Copy the success code that the web UI returns.

  4. In the command prompt of hammer auth login oauth, enter the success code to authenticate to the orcharhino CLI.

Configuring group mapping for Keycloak authentication

Optionally, to implement the Role Based Access Control (RBAC), create a group in orcharhino, assign a role to this group, and then map an Active Directory group to the orcharhino group. As a result, anyone in the given group in Keycloak are logged in under the corresponding orcharhino group. This example configures users of the orcharhino-admin user group in the Active Directory to authenticate as users with administrator privileges on orcharhino.

Procedure

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

  2. Click Create User Group.

  3. In the Name field, enter a name for the user group. The name should not be the same as in the Active Directory.

  4. Do not add users and user groups to the right-hand columns. Click the Roles tab.

  5. Select the Administer checkbox.

  6. Click the External Groups tab.

  7. Click Add external user group.

  8. In the Name field, enter the name of the Active Directory group.

  9. From the list, select EXTERNAL.

Configuring Quarkus-based Keycloak authentication with TOTP cards for orcharhino

Use this section to configure orcharhino to use Quarkus-based Keycloak as an OpenID provider for external authentication with TOTP cards.

Prerequisites for configuring orcharhino with Quarkus-based Keycloak authentication

Before configuring orcharhino with Quarkus-based Keycloak external authentication, ensure that you meet the following requirements:

  • A working installation of Quarkus-based Keycloak server that uses HTTPS instead of HTTP.

  • Configuring Quarkus-based Quarkus-based Keycloak authentication requires the --http-relative-path=/auth context path to be configured in your Quarkus-based Keycloak system setup. If you want to use a different context path, make manual adjustments after the initialisation with /auth or fully set up the foreman-openidc_oidc_keycloak_Foreman_Realm.conf file of the httpd service manually.

    For more information, see Different context-path on reverse proxy in the Quarkus-based Keycloak Administration Guide.

  • A Quarkus-based Keycloak account with admin privileges.

  • A realm for orcharhino user accounts created in Quarkus-based Keycloak.

  • If the certificates or the CA are self-signed, ensure that they are added to the end-user certificate trust store.

  • Users imported or added to Quarkus-based Keycloak.

    If you have an existing user database configured such as LDAP or Kerberos, you can import users from it by configuring user federation.

    If you do not have an existing user database configured, you can manually create users in Quarkus-based Keycloak.

Registering orcharhino as a client of Keycloak

Use this procedure to register orcharhino to Keycloak as a client and configure orcharhino to use Keycloak as an authentication source.

You can configure orcharhino and Keycloak with two different authentication methods:

  1. Users authenticate to orcharhino using the orcharhino management UI.

  2. Users authenticate to orcharhino using the orcharhino CLI.

You must decide on how you want your users to authenticate in advance because both methods require different orcharhino clients to be registered to Keycloak and configured. The steps to register and configure orcharhino client in Keycloak are distinguished within the procedure.

You can also register two different orcharhino clients to Keycloak if you want to use both authentication methods and configure both clients accordingly.

Procedure

  1. On orcharhino Server, install the following packages:

    # dnf install mod_auth_openidc keycloak-httpd-client-install python3-lxml

  2. Register orcharhino to Keycloak as a client. Note that you the registration process for logging in using the web UI and the CLI are different. You can register two clients orcharhino clients to Keycloak to be able to log in to orcharhino from the web UI and the CLI.

    • If you want you users to authenticate to orcharhino using the web UI, create a client as follows:

      # keycloak-httpd-client-install --app-name foreman-openidc \
--keycloak-server-url "https://keycloak.example.com" \
--keycloak-admin-username "admin" \
--keycloak-realm "orcharhino_Realm" \
--keycloak-admin-realm master \
--keycloak-auth-role root-admin \
-t openidc -l /users/extlogin --force

      Enter the password for the administer account when prompted. This command creates a client for orcharhino in Keycloak.

      Then, configure orcharhino to use Keycloak as an authentication source:

      # orcharhino-installer --foreman-keycloak true \
--foreman-keycloak-app-name "foreman-openidc" \
--foreman-keycloak-realm "orcharhino_Realm"

    • If you want your users to authenticate to orcharhino using the CLI, create a client as follows:

      # keycloak-httpd-client-install --app-name hammer-openidc \
--keycloak-server-url "https://keycloak.example.com" \
--keycloak-admin-username "admin" \
--keycloak-realm "orcharhino_Realm" \
--keycloak-admin-realm master \
--keycloak-auth-role root-admin \
-t openidc -l /users/extlogin --force

      Enter the password for the administer account when prompted. This command creates a client for orcharhino in Keycloak.

  3. Restart the httpd service:

    # systemctl restart httpd

Configuring the orcharhino client in Quarkus-based Keycloak

Use this procedure to configure the orcharhino client in the Quarkus-based Keycloak web UI and create group and audience mappers for the orcharhino client.

Procedure

  1. In the Quarkus-based Keycloak web UI, navigate to the created orcharhino realm, then Clients and click the orcharhino client.

  2. Configure access type:

    • If you want your users to authenticate to orcharhino using the orcharhino management UI, set the Client authentication setting to ON.

    • If you want your users to authenticate to orcharhino using the CLI, set the Client authentication setting to OFF.

  3. In the Valid redirect URI fields, add a valid redirect URI.

    • If you want your users to authenticate to orcharhino using the orcharhino management UI, in the blank field below the existing URI, enter a URI in the form https://orcharhino.example.com/users/extlogin. Note that you must add the string /users/extlogin after the orcharhino FQDN.

      After completing this step, the orcharhino client for logging in using the orcharhino management UI must have the following Valid Redirect URIs:

      https://orcharhino.example.com/users/extlogin/redirect_uri
https://orcharhino.example.com/users/extlogin

    • If you want your users to authenticate to orcharhino using the CLI, in the blank field below the existing URI, enter urn:ietf:wg:oauth:2.0:oob.

      After completing this step, the orcharhino client for logging in using the CLI must have the following Valid Redirect URIs:

      https://orcharhino.example.com/users/extlogin/redirect_uri
urn:ietf:wg:oauth:2.0:oob

  4. Click Save.

  5. Click the Client Scopes tab and enter the scope called like the client ending with -dedicated.

  6. Click Add mapper, followed by By configuration (or if no mappers are configured Configure a new mapper) and select the Audience mapper.

  7. In the Name field, enter a name for the audience mapper.

  8. From the Included Client Audience list, select the orcharhino client.

  9. Set the Add to ID token setting to ON.

  10. Click Save.

  11. Click Add mapper, followed by By configuration and select the Group Membership mapper to add a group mapper so that you can specify authorization in orcharhino based on group membership.

  12. In the Name field, enter a name for the group mapper.

  13. In the Token Claim Name field, enter groups.

  14. Set the Full group path setting to OFF.

  15. Click Save.

Configuring orcharhino settings for Quarkus-based Keycloak authentication using the web UI

Use this procedure to configure orcharhino settings for Quarkus-based Keycloak authentication using the orcharhino management UI.

Note that you can navigate to the following URL within your realm to obtain values to configure orcharhino settings: https://keycloak.example.com/auth/realms/orcharhino_Realm/.well-known/openid-configuration

Prerequisites

  • Ensure that the Client authentication setting in the orcharhino client in the Quarkus-based Keycloak web UI is set to ON.

Procedure

  1. In the orcharhino management UI, navigate to Administer > Settings, and click the Authentication tab.

  2. Locate the Authorize login delegation row, and in the Value column, set the value to Yes.

  3. Locate the Authorize login delegation auth source user autocreate row, and in the Value column, set the value to External.

  4. Locate the Login delegation logout URL row, and in the Value column, set the value to https://orcharhino.example.com/users/extlogout.

  5. Locate the OIDC Algorithm row, and in the Value column, set the algorithm for encoding on Quarkus-based Keycloak to RS256.

  6. Locate the OIDC Audience row, and in the Value column, set the value to the client ID for Quarkus-based Keycloak.

  7. Locate the OIDC Issuer row, and in the Value column, set the value to https://keycloak.example.com/auth/realms/orcharhino_Realm.

  8. Locate the OIDC JWKs URL row, and in the Value column, set the value to https://keycloak.example.com/auth/realms/orcharhino_Realm/protocol/openid-connect/certs.

  9. In the orcharhino management UI, navigate to Administer > Authentication Sources, click the vertical ellipsis on the External card, and select Edit.

  10. Click the Locations tab and add locations that can use the Quarkus-based Keycloak authentication source.

  11. Click the Organizations tab and add organizations that can use the Quarkus-based Keycloak authentication source.

  12. Click Submit.

Configuring orcharhino settings for Quarkus-based Keycloak authentication using the CLI

Use this procedure to configure orcharhino settings for Quarkus-based Keycloak authentication using the orcharhino CLI.

Note that you can navigate to the following URL within your realm to obtain values to configure orcharhino settings: https://keycloak.example.com/auth/realms/orcharhino_Realm/.well-known/openid-configuration

Prerequisites

  • Ensure that the Client authentication setting in the orcharhino client in the Quarkus-based Keycloak web UI is set to OFF.

Procedure

  1. On orcharhino, set the login delegation to true so that users can authenticate using the Open IDC protocol:

    # hammer settings set --name authorize_login_delegation --value true

  2. Set the login delegation logout URL:

    # hammer settings set --name login_delegation_logout_url \
--value https://orcharhino.example.com/users/extlogout

  3. Set the algorithm for encoding on Quarkus-based Keycloak, for example, RS256:

    # hammer settings set --name oidc_algorithm --value 'RS256'

  4. Open the keycloak.example.com/auth/realms/KEYCLOAK_REALM/.well-known/openid-configuration URL and note the values to populate the options in the following steps.

  5. Add the value for the Hammer client in the Open IDC audience:

    # hammer settings set --name oidc_audience \
--value "['orcharhino.example.com-hammer-openidc']"

    If you register several Quarkus-based Keycloak clients to orcharhino, ensure that you append all audiences in the array. For example:

    # hammer settings set --name oidc_audience \
--value "['orcharhino.example.com-foreman-openidc', 'orcharhino.example.com-hammer-openidc']"

  6. Set the value for the Open IDC issuer:

    # hammer settings set --name oidc_issuer \
--value "keycloak.example.com/auth/realms/KEYCLOAK_REALM"

  7. Set the value for Open IDC Java Web Token (JWT):

    # hammer settings set --name oidc_jwks_url \
--value "keycloak.example.com/auth/realms/KEYCLOAK_REALM/protocol/openid-connect/certs"

  8. Retrieve the ID of the Quarkus-based Keycloak authentication source:

    # hammer auth-source external list

  9. Set the location and organization:

    # hammer auth-source external update --id Authentication Source ID \
--location-ids Location ID --organization-ids Organization ID

Configuring orcharhino with Keycloak for TOTP authentication

Use this procedure to configure orcharhino to use Keycloak as an OpenID provider for external authentication with Time-based One-time Password (TOTP).

Procedure

  1. In the Keycloak web UI, navigate to the orcharhino realm.

  2. Navigate to Authentication, and click the OTP Policy tab.

  3. Ensure that the Supported Applications field includes FreeOTP or Google Authenticator.

  4. Configure the OTP settings to suit your requirements.

  5. Optional: If you want to use TOTP authentication as a default authentication method for all users, click the Flows tab, and to the right of the OTP Form setting, select REQUIRED.

  6. Click the Required Actions tab.

  7. To the right of the Configure OTP row, select the Default Action checkbox.

Logging in to the orcharhino management UI using Keycloak TOTP authentication

Use this procedure to log in to the orcharhino management UI using Keycloak TOTP authentication.

Procedure

  1. Log in to orcharhino, orcharhino redirects you to the Keycloak login screen.

  2. Enter your username and password, and click Log In.

  3. The first attempt to log in, Keycloak requests you to configure your client by scanning the barcode and entering the pin displayed.

  4. After you configure your client and enter a valid PIN, Keycloak redirects you to orcharhino and logs you in.

Logging in to the orcharhino CLI using Keycloak

Use this procedure to authenticate to the orcharhino CLI using the code grant type.

Procedure

  1. To authenticate to the orcharhino CLI using the code grant type, enter the following command:

    # hammer auth login oauth \
--two-factor \
--oidc-token-endpoint 'https://keycloak.example.com/auth/realms/ssl-realm/protocol/openid-connect/token' \
--oidc-authorization-endpoint 'https://keycloak.example.com/auth' \
--oidc-client-id 'orcharhino.example.com-foreman-openidc' \
--oidc-redirect-uri urn:ietf:wg:oauth:2.0:oob

    The command prompts you to enter a success code.

  2. To retrieve the success code, navigate to the URL that the command returns and provide the required information.

  3. Copy the success code that the web UI returns.

  4. In the command prompt of hammer auth login oauth, enter the success code to authenticate to the orcharhino CLI.

Configuring group mapping for Keycloak authentication

Optionally, to implement the Role Based Access Control (RBAC), create a group in orcharhino, assign a role to this group, and then map an Active Directory group to the orcharhino group. As a result, anyone in the given group in Keycloak are logged in under the corresponding orcharhino group. This example configures users of the orcharhino-admin user group in the Active Directory to authenticate as users with administrator privileges on orcharhino.

Procedure

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

  2. Click Create User Group.

  3. In the Name field, enter a name for the user group. The name should not be the same as in the Active Directory.

  4. Do not add users and user groups to the right-hand columns. Click the Roles tab.

  5. Select the Administer checkbox.

  6. Click the External Groups tab.

  7. Click Add external user group.

  8. In the Name field, enter the name of the Active Directory group.

  9. From the list, select EXTERNAL.

Configuring Active Directory as an external identity provider for orcharhino

This section shows how to use direct Active Directory (AD) as an external authentication source for orcharhino Server.

You can attach Active Directory as an external authentication source with no single sign-on support. For more information, see configuring an ldap server as an external identity provider for project.

Direct AD integration means that orcharhino Server is joined directly to the AD domain where the identity is stored. The recommended setup consists of two steps:

GSS-Proxy

The traditional process of Kerberos authentication in Apache requires the Apache process to have read access to the keytab file. GSS-Proxy allows you to implement stricter privilege separation for the Apache server by removing access to the keytab file while preserving Kerberos authentication functionality. When using AD as an external authentication source for orcharhino, it is recommended to implement GSS-proxy, because the keys in the keytab file are the same as the host keys.

Enrolling orcharhino Server with the AD server

In the orcharhino CLI, enroll orcharhino Server with the Active Directory server.

Prerequisites

  • GSS-proxy and nfs-utils are installed.

    Installing GSS-proxy and nfs-utils:

    # dnf install gssproxy nfs-utils
Procedure

  1. Install the required packages:

    # dnf install sssd adcli realmd ipa-python-compat krb5-workstation samba-common-tools

  2. Enroll orcharhino Server with the AD server. You may need to have administrator permissions to perform the following command:

    # realm join -v EXAMPLE.ORG --membership-software=samba -U Administrator

    You must use the Samba client software to enroll with the AD server to create the HTTP keytab in Configuring Direct AD Integration with GSS Proxy.

Configuring direct AD integration with GSS-proxy

In the orcharhino CLI, configure the direct Active Directory integration with GSS-proxy.

Prerequisites
Procedure

  1. Create the /etc/ipa/ directory and the default.conf file:

    # mkdir /etc/ipa
# touch /etc/ipa/default.conf

  2. To the default.conf file, add the following content:

    [global]
server = unused
realm = EXAMPLE.ORG

  3. Create the /etc/net-keytab.conf file with the following content:

    [global]
workgroup = EXAMPLE
realm = EXAMPLE.ORG
kerberos method = system keytab
security = ads

  4. Determine the effective user ID of the Apache user:

    # id apache

    Apache user must not have access to the keytab file.

  5. Create the /etc/gssproxy/00-http.conf file with the following content:

    [service/HTTP]
mechs = krb5
cred_store = keytab:/etc/httpd/conf/http.keytab
cred_store = ccache:/var/lib/gssproxy/clients/krb5cc_%U
euid = ID_of_Apache_User

  6. Create a keytab entry:

    # KRB5_KTNAME=FILE:/etc/httpd/conf/http.keytab net ads keytab add HTTP -U administrator -d3 -s /etc/net-keytab.conf
# chown root.apache /etc/httpd/conf/http.keytab
# chmod 640 /etc/httpd/conf/http.keytab

  7. Enable IPA authentication in orcharhino:

    # orcharhino-installer --foreman-ipa-authentication=true

  8. Start and enable the gssproxy service:

    # systemctl restart gssproxy
# systemctl enable --now gssproxy

  9. To configure the Apache server to use the gssproxy service, create a systemd drop-in file and add the following content to it:

    # mkdir -p /etc/systemd/system/httpd.service.d/
# vi /etc/systemd/system/httpd.service.d/gssproxy.conf
[Service]
Environment=GSS_USE_PROXY=1

  10. Apply changes to the service:

    # systemctl daemon-reload

  11. Start and enable the httpd service:

    # systemctl restart httpd

With direct AD integration, HBAC through FreeIPA is not available. As an alternative, you can use Group Policy Objects (GPO) that enable administrators to centrally manage policies in AD environments. To ensure correct GPO to PAM service mapping, add the following SSSD configuration to /etc/sssd/sssd.conf:

access_provider = ad
ad_gpo_access_control = enforcing
ad_gpo_map_service = +foreman

Here, foreman is the PAM service name.
Verification

Verify that SSO is working as expected.

With a running Apache server, users making HTTP requests against the server are authenticated if the client has a valid Kerberos ticket.

  1. Retrieve the Kerberos ticket of the LDAP user, using the following command:

    # kinit ldapuser

  2. View the Kerberos ticket, using the following command:

    # klist

  3. View output from successful SSO-based authentication, using the following command:

    # curl -k -u : --negotiate https://orcharhino.example.com/users/extlogin

    This returns the following response:

    <html><body>You are being <a href="https://orcharhino.example.com/users/4-ldapuserexample-com/edit">redirected</a>.</body></html>

Kerberos configuration in web browsers

If you use the Internet Explorer browser, add orcharhino Server to the list of Local Intranet or Trusted sites, and turn on the Enable Integrated Windows Authentication setting. See the Internet Explorer documentation for details.

Configuring the FreeIPA server to use cross-forest trust

On the FreeIPA server, configure the server to use cross-forest trust.

Procedure

  1. Enable HBAC:

    1. Create an external group and add the AD group to it.

    2. Add the new external group to a POSIX group.

    3. Use the POSIX group in a HBAC rule.

  2. Configure sssd to transfer additional attributes of AD users.

    • Add the AD user attributes to the nss and domain sections in /etc/sssd/sssd.conf. For example:

      [nss]
user_attributes=+mail, +sn, +givenname
[domain/EXAMPLE.com]
...
krb5_store_password_if_offline = True
ldap_user_extra_attrs=email:mail, lastname:sn, firstname:givenname

[ifp]
allowed_uids = ipaapi, root
user_attributes=+email, +firstname, +lastname

    • Verify the AD attributes value.

      # dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserAttr string:ad-user@ad-domain array:string:email,firstname,lastname

Configuring orcharhino to manage the lifecycle of a host registered to a FreeIPA realm

As well as providing access to orcharhino Server, hosts provisioned with orcharhino can also be integrated with FreeIPA realms. orcharhino has a realm feature that automatically manages the lifecycle of any system registered to a realm or domain provider.

Use this section to configure orcharhino Server or orcharhino Proxy Server for FreeIPA realm support, then add hosts to the FreeIPA realm group.

Prerequisites

  • orcharhino Server that is registered to the Content Delivery Network or an external orcharhino Proxy Server that is registered to orcharhino Server.

  • A deployed realm or domain provider such as FreeIPA.

To install and configure FreeIPA packages on orcharhino Server or orcharhino Proxy Server:

To use FreeIPA for provisioned hosts, complete the following steps to install and configure FreeIPA packages on orcharhino Server or orcharhino Proxy Server:

  1. Install the ipa-client package on orcharhino Server or orcharhino Proxy Server:

    # dnf install ipa-client

  2. Configure the server as a FreeIPA client:

    # ipa-client-install

  3. Create a realm proxy user, realm-orcharhino-proxy, and the relevant roles in FreeIPA:

    # foreman-prepare-realm admin realm-orcharhino-proxy

    Note the principal name that returns and your FreeIPA server configuration details because you require them for the following procedure.

To configure orcharhino Server or orcharhino Proxy Server for FreeIPA realm support:

Complete the following procedure on orcharhino and every orcharhino Proxy that you want to use:

  1. Copy the /root/freeipa.keytab file to any orcharhino Proxy Server that you want to include in the same principal and realm:

    # scp /root/freeipa.keytab root@orcharhino-proxy.network2.example.com:/etc/foreman-proxy/freeipa.keytab

  2. Move the /root/freeipa.keytab file to the /etc/foreman-proxy directory and set the ownership settings to the foreman-proxy user:

    # mv /root/freeipa.keytab /etc/foreman-proxy
# chown foreman-proxy:foreman-proxy /etc/foreman-proxy/freeipa.keytab

  3. Enter the following command on all orcharhino Proxies that you want to include in the realm. If you use the integrated orcharhino Proxy on orcharhino, enter this command on orcharhino Server:

    # orcharhino-installer --foreman-proxy-realm true \
--foreman-proxy-realm-keytab /etc/foreman-proxy/freeipa.keytab \
--foreman-proxy-realm-principal realm-orcharhino-proxy@EXAMPLE.COM \
--foreman-proxy-realm-provider freeipa

    You can also use these options when you first configure the orcharhino Server.

  4. Ensure that the most updated versions of the ca-certificates package is installed and trust the FreeIPA Certificate Authority:

    # cp /etc/ipa/ca.crt /etc/pki/ca-trust/source/anchors/ipa.crt
# update-ca-trust enable
# update-ca-trust

  5. Optional: If you configure FreeIPA on an existing orcharhino Server or orcharhino Proxy Server, complete the following steps to ensure that the configuration changes take effect:

    1. Restart the foreman-proxy service:

      # systemctl restart foreman-proxy

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

    3. Locate the orcharhino Proxy you have configured for FreeIPA and from the list in the Actions column, select Refresh.

To create a realm for the FreeIPA-enabled orcharhino Proxy

After you configure your integrated or external orcharhino Proxy with FreeIPA, you must create a realm and add the FreeIPA-configured orcharhino Proxy to the realm.

Procedure

  1. In the orcharhino management UI, navigate to Infrastructure > Realms and click Create Realm.

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

  3. From the Realm Type list, select the type of realm.

  4. From the Realm orcharhino Proxy list, select orcharhino Proxy Server where you have configured FreeIPA.

  5. Click the Locations tab and from the Locations list, select the location where you want to add the new realm.

  6. Click the Organizations tab and from the Organizations list, select the organization where you want to add the new realm.

  7. Click Submit.

Updating host groups with realm information

You must update any host groups that you want to use with the new realm information.

  1. In the orcharhino management UI, navigate to Configure > Host Groups, select the host group that you want to update, and click the Network tab.

  2. From the Realm list, select the realm you create as part of this procedure, and then click Submit.

Adding hosts to a FreeIPA host group

FreeIPA supports the ability to set up automatic membership rules based on a system’s attributes. orcharhino’s realm feature provides administrators with the ability to map the orcharhino host groups to the FreeIPA parameter userclass which allow administrators to configure automembership.

When nested host groups are used, they are sent to the FreeIPA server as they are displayed in the orcharhino User Interface. For example, "Parent/Child/Child".

orcharhino Server or orcharhino Proxy Server sends updates to the FreeIPA server, however automembership rules are only applied at initial registration.

To add hosts to a FreeIPA host group:

  1. On the FreeIPA server, create a host group:

    # ipa hostgroup-add hostgroup_name --desc=hostgroup_description

  2. Create an automembership rule:

    # ipa automember-add --type=hostgroup hostgroup_name automember_rule

    Where you can use the following options:

    • automember-add flags the group as an automember group.

    • --type=hostgroup identifies that the target group is a host group, not a user group.

    • automember_rule adds the name you want to identify the automember rule by.

  3. Define an automembership condition based on the userclass attribute:

    # ipa automember-add-condition --key=userclass --type=hostgroup --inclusive-regex=^webserver hostgroup_name
----------------------------------
Added condition(s) to "hostgroup_name"
----------------------------------
Automember Rule: automember_rule
Inclusive Regex: userclass=^webserver
----------------------------
Number of conditions added 1
----------------------------

    Where you can use the following options:

    • automember-add-condition adds regular expression conditions to identify group members.

    • --key=userclass specifies the key attribute as userclass.

    • --type=hostgroup identifies that the target group is a host group, not a user group.

    • --inclusive-regex= ^webserver identifies matching values with a regular expression pattern.

    • hostgroup_name – identifies the target host group’s name.

When a system is added to orcharhino Server’s hostgroup_name host group, it is added automatically to the FreeIPA server’s "hostgroup_name" host group. FreeIPA host groups allow for Host-Based Access Controls (HBAC), sudo policies and other FreeIPA functions.

Configuring external user groups

orcharhino does not associate external users with their user group automatically. You must create a user group with the same name as in the external source on orcharhino. Members of the external user group then automatically become members of the orcharhino user group and receive the associated permissions.

The configuration of external user groups depends on the type of external authentication.

To assign additional permissions to an external user, add this user to an internal user group that has no external mapping specified. Then assign the required roles to this group.

Prerequisites

  • If you use an LDAP server, configure orcharhino to use LDAP authentication. For more information, see configuring an ldap server as an external identity provider for project.

    When using external user groups from an LDAP source, you cannot use the $login variable as a substitute for the account user name. You must use either an anonymous or dedicated service user.

  • If you use a FreeIPA or AD server, configure orcharhino to use FreeIPA or AD authentication. For more information, see Configuring External Authentication in Installing orcharhino Server.

  • Ensure that at least one external user authenticates for the first time.

  • Retain a copy of the external group names you want to use. To find the group membership of external users, enter the following command:

    # id username
Procedure

  1. In the orcharhino management UI, navigate to Administer > User Groups, and click Create User Group.

  2. Specify the name of the new user group. Do not select any users to avoid adding users automatically when you refresh the external user group.

  3. Click the Roles tab and select the roles you want to assign to the user group. Alternatively, select the Administrator checkbox to assign all available permissions.

  4. Click the External groups tab, then click Add external user group, and select an authentication source from the Auth source drop-down menu.

    Specify the exact name of the external group in the Name field.

  5. Click Submit.

Refreshing external user groups for LDAP

To set the LDAP source to synchronize user group membership automatically on user login, in the Auth Source page, select the Usergroup Sync option. If this option is not selected, LDAP user groups are refreshed automatically through a scheduled cron job synchronizing the LDAP Authentication source every 30 minutes by default.

If the user groups in the LDAP Authentication source change in the lapse of time between scheduled tasks, the user can be assigned to incorrect external user groups. This is corrected automatically when the scheduled task runs.

Use this procedure to refresh the LDAP source manually.

Procedure

  1. In the orcharhino management UI, navigate to Administer > Usergroups and select a user group.

  2. On the External Groups tab, click Refresh to the right of the required user group.

CLI procedure

  • Enter the following command:

    # foreman-rake ldap:refresh_usergroups

Refreshing external user groups for FreeIPA or AD

External user groups based on FreeIPA or AD are refreshed only when a group member logs in to orcharhino. It is not possible to alter user membership of external user groups in the orcharhino management UI, such changes are overwritten on the next group refresh.

Configuring the Hammer CLI to use FreeIPA user authentication

This section describes how to configure the orcharhino Hammer command-line interface (CLI) tool to use FreeIPA (IdM) to authenticate users.

Prerequisites

  • You are logged in to the host from which you want to access orcharhino by using Hammer.

Procedure

  1. Enable sessions in the ~/.hammer/cli.modules.d/foreman.yml Hammer configuration file by adding the :use_sessions: true line to the foreman parameters:

    :foreman:
  :use_sessions: true

    Adding the line enforces session usage in Hammer. This means that Hammer performs the authentication request only once instead of with each hammer command.

  2. Optional: Enable negotiate authentication in the ~/.hammer/cli.modules.d/foreman.yml Hammer configuration file by adding the :default_auth_type: 'Negotiate_Auth' line to the foreman parameters:

    :foreman:
  :default_auth_type: 'Negotiate_Auth'
  :use_sessions: true

    Adding this line means that your authentication is negotiated when you enter the first hammer command. If this entry is present, Hammer tries to communicate with orcharhino Server using the negotiation protocol.

Disabling Keycloak authentication

If you want to disable Keycloak authentication in orcharhino, complete this procedure.

Procedure

  • Reset Keycloak support to the default value:

    # orcharhino-installer --reset-foreman-keycloak

Using webhooks

A webhook is a way for a web page or web application to provide other applications with information in real time. 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. Webhooks enable you to define a call to an external API based on orcharhino internal event using a fire-and-forget message exchange pattern. The application sending the request does not wait for the response, or ignores it.

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.

Because webhooks use HTTP, no new infrastructure needs be added to existing web services.

The typical use case for webhooks in orcharhino is making a call to a monitoring system when a host is created or deleted.

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.

For a list of available events, see Available webhook events.

Migrating to webhooks

The legacy foreman_hooks plugin provided full access to model objects that the webhooks plugin does not intentionally provide.

The scope of what is available is limited by the safemode and all objects and macros are both subject to an API stability promise and are fully documented.

The number of events triggered by webhooks is substantially fewer than with foreman_hooks.

Webhooks are processed asynchronously so there is minimal risk of tampering with internals of the system. It is not possible to migrate from foreman_hooks without creating payloads for each individual webhook script. However, the webhooks plugin comes with several example payload templates. You can also use the example payloads with shellhooks to simplify migration.

Both script and payload templates must be customized to achieve similar results.

The foreman_hooks plugin will be removed in an upcoming version of orcharhino.

You can use orcharhino webhooks plugin instead.

Installing the webhooks plugin

Use the following procedure to install the webhooks plugin. Then, you can configure orcharhino Server to send webhook requests.

Procedure

  • Install the webhooks plugin by running the following command:

    # orcharhino-installer --enable-foreman-plugin-webhooks

  • Optional: Install the webhooks CLI plugin:

    # orcharhino-installer --enable-foreman-cli-webhooks

Creating a webhook template

Webhook templates are used to generate the body of HTTP request to a configured target when a webhook is triggered. Use the following procedure to 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.

Examples

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

Creating a webhook

You can customize events, payloads, HTTP authentication, content type, and headers through the orcharhino management UI.

Use the following procedure to create a webhook in the orcharhino management UI.

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.

Available webhook events

The following table contains a list of 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).

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

Shellhooks

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 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 as long as 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 using HTTP headers in format X-Shellhook-Arg-1 to X-Shellhook-Arg-99. For more information on passing arguments to shellhook script, see:

The HTTP method must be POST. An example URL would be: https://orcharhino-proxy.network2.example.com:9090/shellhook/My_Script.

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.

For an example on creating a shellhook script, see creating a shellhook to print arguments.

Installing the shellhooks plugin

Optionally, you can install and enable the shellhooks plugin on each orcharhino Proxy used for shellhooks.

Procedure

  • Run the following command:

    # orcharhino-installer --enable-foreman-proxy-plugin-shellhooks

Passing arguments to shellhook script using webhooks

Use this procedure to pass arguments to a shellhook script using webhooks.

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
{
  "X-Shellhook-Arg-1": "<%= @object.content_view_version_id %>",
  "X-Shellhook-Arg-2": "<%= @object.content_view_name %>"
}

Passing arguments to shellhook script using curl

Use this procedure to pass arguments to a shellhook script using curl.

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
# curl -sX POST -H 'Content-Type: text/plain' \
-H "X-Shellhook-Arg-1: Version 1.0" \
-H "X-Shellhook-Arg-2: My content view" \
--data "" https://orcharhino-proxy.network2.example.com:9090/shellhook/My_Script

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.network2.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 Executing a Remote Job 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!

Searching and bookmarking

orcharhino features powerful search functionality on most pages of the orcharhino management UI. It enables you to search all kinds of resources that orcharhino manages. Searches accept both free text and syntax-based queries, which can be built using extensive input prediction. Search queries can be saved as bookmarks for future reuse.

Building search queries

As you start typing a search query, a list of valid options to complete the current part of the query appears. You can either select an option from the list and keep building the query using the prediction, or continue typing. To learn how free text is interpreted by the search engine, see Using Free Text Search.

Query syntax

parameter operator value

Available fields, resources to search, and the way the query is interpreted all depend on context, that is, the page where you perform the search. For example, the field "hostgroup" on the Hosts page is equivalent to the field "name" on the Host Groups page. The field type also determines available operators and accepted values.

For a list of all operators, see Operators. For descriptions of value formats, see Values.

Query operators

All operators that can be used between parameter and value are listed in the following table. Other symbols and special characters that might appear in a prediction-built query, such as colons, do not have special meaning and are treated as free text.

Table 4. Comparison operators accepted by search
Operator Short Name Description Example

=

EQUALS

Accepts numerical, temporal, or text values. For text, exact case sensitive matches are returned.

hostgroup = RHEL7

!=

NOT EQUALS

~

LIKE

Accepts text or temporal values. Returns case insensitive matches. 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%

hostgroup ~ rhel%

!~

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: >= <=

registered_at > 10-January-2017
The search will return hosts that have been registered after the given date, that is, between 10th January 2017 and now.

registered_at <= Yesterday
The search will return hosts that have been registered yesterday or earlier.

<

LESS THAN

^

IN

Compares an expression against a list of values, as in SQL. Returns matches that contain or not contain the values, respectively.

release_version !^ 7

!^

NOT IN

HAS or set?

 

Returns values that are present or not present, respectively.

has hostgroup or set? hostgroup
On the Puppet Classes page, the search will return classes that are assigned to at least one host group.

not has hostgroup or null? hostgroup
On the Dashboard with an overview of hosts, the search will return all hosts that have no assigned host group.

NOT HAS or null?

 

Simple queries that follow the described syntax can be combined into more complex ones using logical operators AND, OR, and NOT. Alternative notations of the operators are also accepted:

Table 5. Logical operators accepted by search
Operator Alternative Notations Example

and

&

&&

<whitespace>

class = motd AND environment ~ production

or

|

||

 

errata_status = errata_needed || errata_status = security_needed

not

–

!

 

hostgroup ~ rhel7 not status.failed

Query values

Text Values

Text containing whitespaces must be enclosed in quotes. A whitespace is otherwise interpreted as the AND operator.

Examples:

hostgroup = "Web servers"

The search will return hosts with assigned host group named "Web servers".

hostgroup = Web servers

The search will return hosts in the host group Web with any field matching %servers%.

Temporal Values

Many date and time formats are accepted, including the following:

  • "10 January 2017"

  • "10 Jan 2017"

  • 10-January-2017

  • 10/January/2017

  • "January 10, 2017"

  • Today, Yesterday, and the like.

Avoid ambiguous date formats, such as 02/10/2017 or 10-02-2017.
Search examples

  • Search for all hosts within a certain domain: name ~ "*.network.example.com"

  • Search for all hosts not within a certain domain: name !~ "*.network.example.com"

  • Search for all hosts running on a specific compute resource: compute_resource == "My Compute Resource"

  • Search for all hosts not running on Proxmox: model !~ "Proxmox"

  • If you want to exclude certain hosts, use model !~ "My_Model*" instead of model != "My_Model*". Note that searching for the model column returns data for both the hardware model and compute resource name.

  • If you want to search for any snippets, use snippet to filter for templates of type snippet.

  • If you want to search for any template with snippet in its name, use name ~ snippet.

Using free text search

When you enter free text, it will be searched for across multiple fields. For example, if you type "64", the search will return all hosts that have that number in their name, IP address, MAC address, and architecture.

Multi-word queries must be enclosed in quotes, otherwise the whitespace is interpreted as the AND operator.

Because of searching across all fields, free text search results are not very accurate and searching can be slow, especially on a large number of hosts. For this reason, we recommend that you avoid free text and use more specific, syntax-based queries whenever possible.

Managing bookmarks

You can save search queries as bookmarks for reuse. You can also delete or modify a bookmark.

Bookmarks appear only on the page on which they were created. On some pages, there are default bookmarks available for the common searches, for example, all active or disabled hosts.

Creating bookmarks

This section details how to save a search query as a bookmark. You must save the search query on the relevant page to create a bookmark for that page, for example, saving a host related search query on the Hosts page.

Procedure

  1. In the orcharhino management UI, navigate to the page where you want to create a bookmark.

  2. In the Search field, enter the search query you want to save.

  3. Select the arrow to the right of the Search button and then select Bookmark this search.

  4. In the Name field, enter a name for the new bookmark.

  5. In the Search query field, ensure your search query is correct.

  6. Ensure the Public checkbox is set correctly:

    • Select the Public checkbox to set the bookmark as public and visible to all users.

    • Clear the Public checkbox to set the bookmark as private and only visible to the user who created it.

  7. Click Submit.

To confirm the creation, either select the arrow to the right of the Search button to display the list of bookmarks, or navigate to Administer > Bookmarks and then check the Bookmarks list for the name of the bookmark.

Deleting bookmarks

You can delete bookmarks on the Bookmarks page.

Procedure

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

  2. On the Bookmarks page, click Delete for the Bookmark you want to delete.

  3. When the confirmation window opens, click OK to confirm the deletion.

To confirm the deletion, check the Bookmarks list for the name of the bookmark.

Using keyboard shortcuts

You can use keyboard shortcuts to quickly focus search bars.

  • To focus the vertical navigation search bar, press Ctrl + Shift + F.

  • To focus the page search bar, press /.

Administration settings

This section contains information about settings that you can edit in the orcharhino management UI by navigating to Administer > Settings.

General settings

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

Task settings

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.

Template sync settings

Setting Default Value Description

Associate

New

Associate templates with OS, 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.

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.

Discovered settings

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 PXEGrub template name

pxegrub_discovery

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

Boot disk settings

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.

Red Hat Cloud settings

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.

Content settings

Setting Default Value Description

Default HTTP Proxy

Default HTTP Proxy for syncing content.

CDN SSL version

SSL version used to communicate with the CDN.

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 PXEGrub template

Kickstart default PXEGrub

Default PXEGrub 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 export destination filepath

/var/lib/pulp/katello-export

On-disk location for exported repositories.

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.

Authentication settings

Setting Default Value Description

OAuth active

Yes

orcharhino will use OAuth for API authorization.

OAuth consumer key

*****

OAuth consumer key.

OAuth consumer secret

*****

OAuth consumer secret.

OAuth map users

No

orcharhino maps users by username in the request-header. If this is disabled, OAuth requests have administrator rights.

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.

Email settings

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.

Notifications settings

Setting Default Value Description

RSS enable

Yes

Pull RSS notifications.

RSS URL

https://orcharhino.com/feed/

URL from which to fetch RSS notifications.

Provisioning settings

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 PXEGrub template

PXEGrub global default

Global default PXEGrub 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 PXEGrub template

PXEGrub default local boot

Template that is selected as PXEGrub 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.

Facts settings

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.

Configuration management settings

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.

Remote execution settings

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 - SSH 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 cancelled. Applies only to pull-mqtt based jobs. Defaults to one day.

Ansible settings

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.

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