Configuring Hosts Using Ansible

Ansible is an automation engine and configuration management tool. It works without client and daemon and solely relies on Python and SSH. Ansible consists of a control node, for example a notebook, a workstation, or a server and managed nodes, that is the hosts in its inventory. You can use Ansible to configure hosts similar to Puppet and Salt.

ATIX offers Ansible trainings for beginners and advanced users on how to use Ansible as a configuration management tool. This helps you manage your infrastructure more efficiently using Ansible roles. It communicates how to create, use, and maintain Ansible roles, inventories, and playbooks based on best practices. Refer to the Ansible trainings website for more information or contact us.

Webinar on YouTube "orcharhino Ansible Integration vs AWX/Tower"

Getting Started with Ansible in orcharhino

Use this guide to configure orcharhino to use Ansible for remote execution.

Supported Ansible Versions

orcharhino uses Ansible as provided by the base operating system of orcharhino Server or any orcharhino Proxies for remote execution. Therefore, the supported version of Ansible depends on your base OS configuration.

Configuring Your orcharhino to Run Ansible Roles

In orcharhino, you can import Ansible roles to help with automation of routine tasks. To enable Ansible on orcharhino Server, see Enabling Ansible Integration with orcharhino.

Ansible paths

orcharhino imports Ansible roles and variables from paths based on configuration in /etc/ansible/ansible.cfg. orcharhino then runs imported roles from paths based on configuration in /etc/foreman-proxy/ansible.cfg. In both cases, orcharhino reads the paths from roles_path and collections_paths directives. Keep these two cfg files in sync, otherwise you might import roles that cannot be run or you will not see roles you can run.

If none of the paths are specified in the configuration files, the following default paths are used:

  • /etc/ansible/roles

  • /usr/share/ansible/roles

  • /etc/ansible/collections

  • /usr/share/ansible/collections

Procedure

  1. Configure your Ansible paths on the orcharhino Server and all orcharhino Proxies where you want to use the roles.

  2. Add the roles to a directory in an Ansible path on the orcharhino Server and all orcharhino Proxies from where you want to use the roles. If you want to use custom or third party Ansible roles, ensure to configure an external version control system to synchronize roles between orcharhino Server and orcharhino Proxies.

  3. On all orcharhino Proxies that you want to use to run Ansible roles on hosts, enable the Ansible plug-in:

    $ orcharhino-installer --no-enable-foreman \
--enable-foreman-proxy-plugin-ansible

  4. Distribute SSH keys to enable orcharhino Proxies to connect to hosts using SSH. For more information, see Distributing SSH Keys for Remote Execution in Managing Hosts. orcharhino runs Ansible roles the same way it runs remote execution jobs.

  5. Import the Ansible roles into orcharhino.

  6. Proceed to Using Ansible Roles to Automate Repetitive Tasks on Clients.

Enabling Ansible Integration with orcharhino

Perform the following procedure to enable the Ansible plug-in on your orcharhino Server.

Procedure

  • Enable the Ansible plug-in on your orcharhino Server:

    $ orcharhino-installer \
--enable-foreman-plugin-ansible \
--enable-foreman-proxy-plugin-ansible

Importing Ansible Roles and Variables

You can import Ansible roles and variables from the Ansible paths on orcharhino Server or orcharhino Proxy that has Ansible enabled.

Note that some roles take longer to import than others.

Prerequisite

  • Ensure that the roles and variables that you import are located in the Ansible paths on all orcharhino Proxies from where you want to use the roles.

Procedure

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

  2. Click Import to select the orcharhino Proxy from which you want to import.

  3. Select the roles that you want to import.

  4. Click Submit.

Overriding Ansible Variables in orcharhino

If you run Ansible roles in orcharhino, you can use orcharhino to override Ansible variables for those roles.

The following procedure refers to hosts and host groups. For more information, see Managing Hosts.

Precedence in Overriding Variables

If you use an Ansible role to run a task as a user that is not the Effective User, there is a strict order of precedence for overriding Ansible variables. To ensure the variable that you override follows the correct order of precedence, see Variable precedence: Where should I put a variable?

Prerequisite
Procedure

  1. In the orcharhino management UI, navigate to Configure > Variables.

  2. Select the Ansible variable that you want to override and manage with orcharhino.

  3. In the Default Behavior area, select the Override checkbox.

  4. In the Parameter Type field, select the value type for validation such as string or boolean. The types array and hash have further options for handling upon a variable match. For more information, see the Prioritize Attribute Order area below.

  5. In the Default Value field, enter the default value that you want to use if there is no match for the variable.

  6. Optional: If you do not want to display the value of the variable as plain text in the orcharhino management UI, select the Hidden Value checkbox to display the content of the variable as asterisks. This is useful for sensitive values such as passwords or secret tokens.

  7. Optional: Expand the Optional Input Validator area and specify conditions that will be used to validate concrete values of the variable:

    • Select Required if you want to enforce users to fill in this variable.

    • In the Validator Type field, select how the value will be validated:

      • list – The value will be validated against an enumeration of allowed values.

      • regex – The value will be validated against a regular expression pattern.

  8. Optional: In the Prioritize Attribute Order area, specify the order of priority to match an override with a host by host attributes. Order at the top takes higher precedence. The first match wins.

    You can combine multiple attributes into a single matcher key using a comma as the AND operation. For example, the matcher key of hostgroup, environment would expect matchers such as hostgroup = "web servers" AND environment = production.

    If you use the parameter type array or hash, you can further set:

    • Merge Overrides – Merges members of the arrays/hashes instead of replacing the whole array or hash. If the hashes contain the same key, the value is overwritten by the value of the host.

    • Merge Default – Adds the default value to the array or hash.

    • Avoid Duplicates – Ensures that the values in the array or hash are unique.

  9. Optional: Expand the Specify Matchers area and specify criteria for selecting hosts on which the variable overrides.

  10. To save the override settings, click Submit.

To use the Ansible variable, add the variable as a parameter to your host or host group, or add the variable as a global parameter.

Adding the Variable to a Host

  1. In the orcharhino management UI, navigate to Hosts > All Hosts and select the host that you want to use.

  2. Click the Ansible tab, and in the Variables area, click the pencil icon to edit the value of the variable.

  3. Click the tick icon to accept the value of the changed variable or the cross icon to cancel the change.

Adding the Variable to a Host Group

  1. In the orcharhino management UI, navigate to Configure > Host Groups, and select the host group that you want to use.

  2. Click the Parameters tab, and in the Host Group Parameters area, click Add Parameter.

  3. In the Name field, add the Ansible variable name.

  4. From the Type list, select the type of the variable for validation.

  5. In the Value field, enter the value for the variable.

Adding the Variable as a Global Parameter

  1. In the orcharhino management UI, navigate to Configure > Global Parameters, and click Create Parameter.

  2. In the Name field, add the Ansible variable name.

  3. From the Type list, select the type of the variable for validation.

  4. In the Value field, enter the value for the variable.

  5. Optional: If you do not want to display the Ansible variable in plain text, select the Hidden Values checkbox to display the content of the variable as asterisks in the orcharhino management UI.

Adding Ubuntu System Roles

Ubuntu System Roles is a configuration interface to remotely manage Ubuntu servers. You can use Ubuntu System Roles to add Ansible roles in orcharhino. Using Ansible Roles in orcharhino can make configuration faster and easier.

Support levels for some of the Ubuntu System Roles might be in Technology Preview. For up-to-date information about support levels and general information about Ubuntu System Roles, see Ubuntu System Roles.

Before subscribing to the Extras channels, see the Ubuntu Extras Product Life Cycle article.

Procedure

  1. Ensure that the following repository is enabled:

    • On Ubuntu 8, ensure that the Appstream repository is enabled:

      $ subscription-manager repos --enable=EL8AppStream

      You must enable an Appstream repository that is designated for your architecture.

    • On Ubuntu 7, ensure that the Extras repository is enabled:

      $ subscription-manager repos --enable=rhel-7-server-extras-rpms

  2. Install the rhel-system-roles package:

    $ dnf install rhel-system-roles

    The rhel-system-roles package downloads to /usr/share/ansible/roles/. You can view and make any modifications that you want to the files before you import.

  3. In the orcharhino management UI, navigate to Configure > Roles and click the orcharhino Proxy that contains the roles that you want to import.

  4. From the list of Ansible roles, select the checkbox of the roles you want to import, and then click Update.

You can now assign Ansible roles to hosts or host groups. For more information, see Assigning Ansible Roles to an Existing Host.

You can also add the modules contained in these roles to your Ansible playbooks by adding them to Ansible Job Templates. You must include the hosts:all line in the job template.

Synchronizing Ansible Collections

On orcharhino, you can synchronize your Ansible Collections from any Ansible Galaxy and other orcharhino instances. Ansible Collections will appear on orcharhino as a new repository type in the orcharhino management UI menu under Content after the sync.

Procedure

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

  2. Select the required product name.

  3. In the Products window, select the name of a product that you want to create a repository for.

  4. Click the Repositories tab, and then click New Repository.

  5. In the Name field, enter a name for the repository.

    The Label field is populated automatically based on the name.

  6. From the Type list, select ansible collection.

  7. In the Upstream URL field, enter the URL for the upstream collections repository.

    The URL can be any Ansible Galaxy endpoint. For example, https://galaxy.ansible.com.

  8. Optional: In the Requirements.yml field, you can specify the list of collections you want to sync from the endpoint, as well as their versions.

    If you do not specify the list of collections, everything from the endpoint will be synced.

    ---
collections:
- name: my_namespace.my_collection
  version: 1.2.3

    For more information, see Install multiple collections with a requirements file in Galaxy User Guide.

  9. Authenticate.

    1. To sync orcharhino from Private Automation Hub, enter your token in the Auth Token field.

    2. To sync orcharhino from console.redhat.com, enter your token in the Auth Token field and enter your SSO URL in the the Auth URL field.

    3. To sync orcharhino from orcharhino, leave both authentication fields blank.

  10. Click Save.

  11. Navigate to the Ansible Collections repository.

  12. From the Select Action menu, select Sync Now.

Using Ansible Vault with orcharhino

You can encrypt sensitive Ansible data files using the Ansible Vault tool and configure Ansible to access the encrypted files using a password stored in a file.

Procedure

  1. If you customized /etc/ansible/ansible.cfg, copy your configuration from /etc/ansible/ansible.cfg to /usr/share/foreman-proxy/.ansible.cfg.

  2. Encrypt the sensitive file using the ansible-vault command:

    $ ansible-vault encrypt /etc/ansible/roles/Role_Name/vars/main.yml

    Note that ansible-vault changes the file permissions to 600.

  3. Change the group and permissions of the encrypted file to ensure that the foreman-proxy user can read it:

    $ chgrp foreman-proxy /etc/ansible/roles/Role_Name/vars/main.yml
$ chmod 0640 /etc/ansible/roles/Role_Name/vars/main.yml

  4. Create the /usr/share/foreman-proxy/.ansible_vault_password file and enter the Vault password into it.

  5. Change the user and permissions of the .ansible_vault_password file to ensure that only the foreman-proxy user can read it:

    $ chown foreman-proxy:foreman-proxy /usr/share/foreman-proxy/.ansible_vault_password
$ chmod 0400 /usr/share/foreman-proxy/.ansible_vault_password

  6. Add the path of the Vault password file to the [defaults] section in /usr/share/foreman-proxy/.ansible.cfg:

    [defaults]
vault_password_file = /usr/share/foreman-proxy/.ansible_vault_password

    The path to the Vault password file must be absolute.

Using Ansible Roles to Automate Repetitive Tasks on Clients

Assigning Ansible Roles to an Existing Host

You can use Ansible roles for remote management of orcharhino clients.

Prerequisites

  • Ensure that you have configured and imported Ansible roles.

Procedure

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

  2. Select the host and click Edit.

  3. On the Ansible Roles tab, select the role that you want to add from the Available Ansible Roles list.

  4. Click the + icon to add the role to the host. You can add more than one role.

  5. Click Submit.

After you assign Ansible roles to hosts, you can use Ansible for remote execution. For more information, see Distributing SSH Keys for Remote Execution.

Overriding Parameter Variables

On the Parameters tab, click Add Parameter to add any parameter variables that you want to pass to job templates at run time. This includes all Ansible playbook parameters and host parameters that you want to associate with the host. To use a parameter variable with an Ansible job template, you must add a Host Parameter.

Removing Ansible Roles from a Host

Use the following procedure to remove Ansible roles from a host.

Procedure

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

  2. Select the host and click Edit.

  3. Select the Ansible Roles tab.

  4. In the Assigned Ansible Roles area, click the - icon to remove the role from the host. Repeat to remove more roles.

  5. Click Submit.

Changing the Order of Ansible Roles

Use the following procedure to change the order of Ansible roles applied to a host.

Procedure

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

  2. Select a host.

  3. Select the Ansible Roles tab.

  4. In the Assigned Ansible Roles area, you can change the order of the roles by dragging and dropping the roles into the preferred position.

  5. Click Submit to save the order of the Ansible roles.

Running Ansible Roles on a Host

You can run Ansible roles on a host through the orcharhino management UI.

Prerequisites
Procedure

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

  2. Select the checkbox of the host that contains the Ansible role you want to run.

  3. From the Select Action list, select Run all Ansible roles.

You can view the status of your Ansible job on the Run Ansible roles page. To rerun a job, click the Rerun button.

Assigning Ansible Roles to a Host Group

You can use Ansible roles for remote management of orcharhino clients.

Prerequisite
Procedure

  1. In the orcharhino management UI, navigate to Configure > Host Groups.

  2. Click the host group name to which you want to assign an Ansible role.

  3. On the Ansible Roles tab, select the role that you want to add from the Available Ansible Roles list.

  4. Click the + icon to add the role to the host group. You can add more than one role.

  5. Click Submit.

Running Ansible Roles on a Host Group

You can run Ansible roles on a host group through the orcharhino management UI.

Prerequisites

  • You must configure your deployment to run Ansible roles. For more information, see Configuring Your orcharhino to Run Ansible Roles.

  • You must have assigned the Ansible roles to the host group.

  • You must have at least one host in your host group.

Procedure

  1. In the orcharhino management UI, navigate to Configure > Host Groups.

  2. From the list in the Actions column for the host group, select Run all Ansible roles.

You can view the status of your Ansible job on the Run Ansible roles page. To rerun a job, click the Rerun button.

Running Ansible Roles in Check Mode

You can run Ansible roles in check mode through the orcharhino management UI.

Prerequisites

  • You must configure your deployment to run Ansible roles. For more information, see Configuring Your orcharhino to Run Ansible Roles.

  • You must have assigned the Ansible roles to the host group.

  • You must have at least one host in your host group.

Procedure

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

  2. Click Edit for the host you want to enable check mode for.

  3. In the Parameters tab, ensure that the host has a parameter named ansible_roles_check_mode with type boolean set to true.

  4. Click Submit.

Configuring and Setting Up Remote Jobs

Use this section as a guide to configuring orcharhino to execute jobs on remote hosts.

Any command that you want to apply to a remote host must be defined as a job template. After you have defined a job template you can execute it multiple times.

About Running Jobs on Hosts

You can run jobs on hosts remotely from orcharhino Proxies using shell scripts or Ansible tasks and playbooks. This is referred to as remote execution.

For custom Ansible roles that you create, or roles that you download, you must install the package containing the roles on the orcharhino Proxy base operating system. Before you can use Ansible roles, you must import the roles into orcharhino from the orcharhino Proxy where they are installed.

Communication occurs through orcharhino Proxy, which means that orcharhino Server does not require direct access to the target host, and can scale to manage many hosts. For more information, see transport modes for remote execution.

orcharhino uses ERB syntax job templates. For more information, see Template Writing Reference in Managing Hosts.

Several job templates for shell scripts and Ansible are included by default. For more information, see Setting up Job Templates in Managing Hosts.

Any orcharhino Proxy base operating system is a client of orcharhino Server’s internal orcharhino Proxy, and therefore this section applies to any type of host connected to orcharhino Server, including orcharhino Proxies.

You can run jobs on multiple hosts at once, and you can use variables in your commands for more granular control over the jobs you run. You can use host facts and parameters to populate the variable values.

In addition, you can specify custom values for templates when you run the command.

For more information, see Executing a Remote Job in Managing Hosts.

Remote Execution Workflow

When you run a remote job on hosts, for every host, orcharhino performs the following actions to find a remote execution orcharhino Proxy to use.

orcharhino searches only for orcharhino Proxies that have the remote execution feature enabled.

  1. orcharhino finds the host’s interfaces that have the Remote execution checkbox selected.

  2. orcharhino finds the subnets of these interfaces.

  3. orcharhino finds remote execution orcharhino Proxies assigned to these subnets.

  4. From this set of orcharhino Proxies, orcharhino selects the orcharhino Proxy that has the least number of running jobs. By doing this, orcharhino ensures that the jobs load is balanced between remote execution orcharhino Proxies.

If you have enabled Prefer registered through orcharhino Proxy for remote execution, orcharhino runs the REX job using the orcharhino Proxy the host is registered to.

By default, Prefer registered through orcharhino Proxy for remote execution is set to No. To enable it, in the orcharhino management UI, navigate to Administer > Settings, and on the Content tab, set Prefer registered through orcharhino Proxy for remote execution to Yes. This ensures that orcharhino performs REX jobs on hosts by the orcharhino Proxy to which they are registered to.

If orcharhino does not find a remote execution orcharhino Proxy at this stage, and if the Fallback to Any orcharhino Proxy setting is enabled, orcharhino adds another set of orcharhino Proxies to select the remote execution orcharhino Proxy from. orcharhino selects the most lightly loaded orcharhino Proxy from the following types of orcharhino Proxies that are assigned to the host:

  • DHCP, DNS and TFTP orcharhino Proxies assigned to the host’s subnets

  • DNS orcharhino Proxy assigned to the host’s domain

  • Realm orcharhino Proxy assigned to the host’s realm

  • Puppet server orcharhino Proxy

  • Puppet CA orcharhino Proxy

  • OpenSCAP orcharhino Proxy

If orcharhino does not find a remote execution orcharhino Proxy at this stage, and if the Enable Global orcharhino Proxy setting is enabled, orcharhino selects the most lightly loaded remote execution orcharhino Proxy from the set of all orcharhino Proxies in the host’s organization and location to execute a remote job.

Permissions for Remote Execution

You can control which roles can run which jobs within your infrastructure, including which hosts they can target. The remote execution feature provides two built-in roles:

  • Remote Execution Manager: Can access all remote execution features and functionality.

  • Remote Execution User: Can only run jobs.

You can clone the Remote Execution User role and customize its filter for increased granularity. If you adjust the filter with the view_job_templates permission on a customized role, you can only see and trigger jobs based on matching job templates. You can use the view_hosts and view_smart_proxies permissions to limit which hosts or orcharhino Proxies are visible to the role.

The execute_template_invocation permission is a special permission that is checked immediately before execution of a job begins. This permission defines which job template you can run on a particular host. This allows for even more granularity when specifying permissions.

You can run remote execution jobs against orcharhino and orcharhino Proxy registered as hosts to orcharhino with the execute_jobs_on_infrastructure_hosts permission. Standard Manager and Site Manager roles have this permission by default. If you use either the Manager or Site Manager role, or if you use a custom role with the execute_jobs_on_infrastructure_hosts permission, you can execute remote jobs against registered orcharhino and orcharhino Proxy hosts.

For more information on working with roles and permissions, see Creating and Managing Roles in Administering orcharhino.

The following example shows filters for the execute_template_invocation permission:

name = Reboot and host.name = staging.example.com
name = Reboot and host.name ~ *.staging.example.com
name = "Restart service" and host_group.name = webservers

Use the first line in this example to apply the Reboot template to one selected host. Use the second line to define a pool of hosts with names ending with .staging.example.com. Use the third line to bind the template with a host group.

Permissions assigned to users with these roles can change over time. If you have already scheduled some jobs to run in the future, and the permissions change, this can result in execution failure because permissions are checked immediately before job execution.

Transport Modes for Remote Execution

You can configure your orcharhino to use two different modes of transport for remote job execution.

On orcharhino Proxies in ssh mode, remote execution uses the SSH service to transport job details. This is the default transport mode. The SSH service must be enabled and active on the target hosts. The remote execution orcharhino Proxy must have access to the SSH port on the target hosts. Unless you have a different setting, the standard SSH port is 22.

On orcharhino Proxies in pull-mqtt mode, remote execution uses Message Queueing Telemetry Transport (MQTT) to publish jobs it receives from orcharhino Server. The host subscribes to the MQTT broker on orcharhino Proxy for job notifications using the yggdrasil pull client. After the host receives a notification, it pulls job details from orcharhino Proxy over HTTPS, runs the job, and reports results back to orcharhino Proxy.

To use the pull-mqtt mode, you must enable it on orcharhino Proxy and configure the pull client on the target hosts.

Additional resources

Configuring a Host to Use the Pull Client

For orcharhino Proxies configured to use pull-mqtt mode, hosts can subscribe to remote jobs using the remote execution pull client. Managed hosts do not require an SSH connection to their orcharhino Proxy.

Prerequisites

  • You have registered the host to orcharhino.

  • The host’s orcharhino Proxy is configured to use pull-mqtt mode. For more information, see Configuring Remote Execution for Pull Client in Installing orcharhino Proxy.

  • The ATIX AG orcharhino Client for Ubuntu repository is enabled and synchronized on orcharhino Server, and enabled on the host.

  • The host is able to communicate with its orcharhino Proxy over MQTT using port 1883.

  • The host is able to communicate with its orcharhino Proxy over HTTPS.

The katello-pull-transport-migrate package was created to help users migrate from Katello Agent to remote execution with the pull client. However, having Katello Agent installed on the host is not a requirement. You can use katello-pull-transport-migrate regardless of whether Katello Agent is installed.
Procedure

  1. Install the katello-pull-transport-migrate package on your host:

    The package installs foreman_ygg_worker and yggdrasil as dependencies and enables the pull mode on the host. The host’s subscription-manager configuration and consumer certificates are used to configure the yggdrasil client on the host, and the pull mode client worker is started.

  2. Optional: To verify that the pull client is running and configured properly, check the status of the yggdrasild service:

    $ systemctl status yggdrasild

  3. Optional: After the package is installed, you can remove katello-agent from the host.

    If your host is installed on oVirt version 4.4 or lower, do not remove the katello-agent package because the removed dependencies corrupt the host.

Creating a Job Template

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

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Job templates.

  2. Click New Job Template.

  3. Click the Template tab, and in the Name field, enter a unique name for your job template.

  4. Select Default to make the template available for all organizations and locations.

  5. Create the template directly in the template editor or upload it from a text file by clicking Import.

  6. Optional: In the Audit Comment field, add information about the change.

  7. Click the Job tab, and in the Job category field, enter your own category or select from the default categories listed in Default Job Template Categories in Managing Hosts.

  8. Optional: In the Description Format field, enter a description template. For example, Install package %{package_name}. You can also use %{template_name} and %{job_category} in your template.

  9. From the Provider Type list, select SSH for shell scripts and Ansible for Ansible tasks or playbooks.

  10. Optional: In the Timeout to kill field, enter a timeout value to terminate the job if it does not complete.

  11. Optional: Click Add Input to define an input parameter. Parameters are requested when executing the job and do not have to be defined in the template. For examples, see the Help tab.

  12. Optional: Click Foreign input set to include other templates in this job.

  13. Optional: In the Effective user area, configure a user if the command cannot use the default remote_execution_effective_user setting.

  14. Optional: If this template is a snippet to be included in other templates, click the Type tab and select Snippet.

  15. Click the Location tab and add the locations where you want to use the template.

  16. Click the Organizations tab and add the organizations where you want to use the template.

  17. Click Submit to save your changes.

You can extend and customize job templates by including other templates in the template syntax. For more information, see Template Writing Reference and Job Template Examples and Extensions in Managing Hosts.

CLI procedure

  • To create a job template using a template-definition file, enter the following command:

    # hammer job-template create \
--file "Path_to_My_Template_File" \
--job-category "My_Category_Name" \
--name "My_Template_Name" \
--provider-type SSH

Importing an Ansible Playbook by Name

You can import Ansible playbooks by name to orcharhino from collections installed on orcharhino Proxy.

Prerequisite

  • Ansible plug-in in orcharhino is enabled

Procedure

  1. Fetch the available Ansible playbooks using the following API request:

    $ curl -X GET 'Content-Type: application/json' https://orcharhino.example.com/ansible/api/v2/ansible_playbooks/fetch?proxy_id=Myorcharhino-proxy_ID_

  2. Select the Ansible playbook you want to import and note its name.

  3. Import the Ansible playbook using its name:

    $ curl -X PUT 'Content-Type: application/json' -d '{ "playbook_names": ["My_Playbook_Name"] }' https://orcharhino.example.com/ansible/api/v2/ansible_playbooks/sync?proxy_id=Myorcharhino-proxy_ID_

    You get a notification in the orcharhino management UI after the import completes.

Importing All Available Ansible Playbooks

You can import all the available Ansible playbooks to orcharhino from collections installed on orcharhino Proxy.

Prerequisite

  • Ansible plug-in in orcharhino is enabled

Procedure

  • Import the Ansible playbooks using the following API request:

    $ curl -X PUT 'Content-Type: application/json' https://orcharhino.example.com/ansible/api/v2/ansible_playbooks/sync?proxy_id=My-orcharhino-proxy-ID

    You get a notification in the orcharhino management UI after the import completes.

Configuring the Fallback to Any orcharhino Proxy Remote Execution Setting in orcharhino

You can enable the Fallback to Any orcharhino Proxy setting to configure orcharhino to search for remote execution orcharhino Proxies from the list of orcharhino Proxies that are assigned to hosts. This can be useful if you need to run remote jobs on hosts that have no subnets configured or if the hosts' subnets are assigned to orcharhino Proxies that do not have the remote execution feature enabled.

If the Fallback to Any orcharhino Proxy setting is enabled, orcharhino adds another set of orcharhino Proxies to select the remote execution orcharhino Proxy from. orcharhino also selects the most lightly loaded orcharhino Proxy from the set of all orcharhino Proxies assigned to the host, such as the following:

  • DHCP, DNS and TFTP orcharhino Proxies assigned to the host’s subnets

  • DNS orcharhino Proxy assigned to the host’s domain

  • Realm orcharhino Proxy assigned to the host’s realm

  • Puppet server orcharhino Proxy

  • Puppet CA orcharhino Proxy

  • OpenSCAP orcharhino Proxy

Procedure

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

  2. Click Remote Execution.

  3. Configure the Fallback to Any orcharhino Proxy setting.

CLI procedure

  • Enter the hammer settings set command on orcharhino to configure the Fallback to Any orcharhino Proxy setting. To set the value to true, enter the following command:

    $ hammer settings set \
--name=remote_execution_fallback_proxy \
--value=true

Configuring the Global orcharhino Proxy Remote Execution Setting in orcharhino

By default, orcharhino searches for remote execution orcharhino Proxies in hosts' organizations and locations regardless of whether orcharhino Proxies are assigned to hosts' subnets or not. You can disable the Enable Global orcharhino Proxy setting if you want to limit the search to the orcharhino Proxies that are assigned to hosts' subnets.

If the Enable Global orcharhino Proxy setting is enabled, orcharhino adds another set of orcharhino Proxies to select the remote execution orcharhino Proxy from. orcharhino also selects the most lightly loaded remote execution orcharhino Proxy from the set of all orcharhino Proxies in the host’s organization and location to execute a remote job.

Procedure

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

  2. Click Remote Execution.

  3. Configure the Enable Global orcharhino Proxy setting.

CLI procedure

  • Enter the hammer settings set command on orcharhino to configure the Enable Global orcharhino Proxy setting. To set the value to true, enter the following command:

    $ hammer settings set \
--name=remote_execution_global_proxy \
--value=true

Configuring orcharhino to Use an Alternative Directory to Execute Remote Jobs on Hosts

By default, orcharhino uses the /var/tmp directory on the client system to execute the remote execution jobs. If the client system has noexec set for the /var/ volume or file system, you must configure orcharhino to use an alternative directory because otherwise the remote execution job fails since the script cannot be run.

Procedure

  1. Create a new directory:

    $ mkdir /My_Remote_Working_Directory

  2. Copy the SELinux context from the default var directory:

    $ chcon --reference=/var /My_Remote_Working_Directory

  3. Configure the system:

    $ orcharhino-installer \
--foreman-proxy-plugin-remote-execution-script-remote-working-dir /My_Remote_Working_Directory

Distributing SSH Keys for Remote Execution

For orcharhino Proxies in ssh mode, remote execution connections are authenticated using SSH. The public SSH key from orcharhino Proxy must be distributed to its attached hosts that you want to manage.

Ensure that the SSH service is enabled and running on the hosts. Configure any network or host-based firewalls to enable access to port 22.

Use one of the following methods to distribute the public SSH key from orcharhino Proxy to target hosts:

  1. distributing ssh keys for remote execution manually.

  2. Using the orcharhino API to Obtain SSH Keys for Remote Execution.

  3. Configuring a Preseed Template to Distribute SSH Keys During Provisioning.

  4. For new orcharhino hosts, you can deploy SSH keys to orcharhino hosts during registration using the global registration template. For more information, see Registering a Host to orcharhino Using the Global Registration Template in Managing Hosts.

orcharhino distributes SSH keys for the remote execution feature to the hosts provisioned from orcharhino by default.

If the hosts are running on Amazon Web Services, enable password authentication. For more information, see New User Accounts.

Distributing SSH Keys for Remote Execution Manually

To distribute SSH keys manually, complete the following steps:

Procedure

  • Copy the SSH pub key from your orcharhino Proxy to your target host:

    $ ssh-copy-id -i ~foreman-proxy/.ssh/id_rsa_foreman_proxy.pub root@client.example.com

    Repeat this step for each target host you want to manage.

Verification

  • To confirm that the key was successfully copied to the target host, enter the following command on orcharhino Proxy:

    $ ssh -i ~foreman-proxy/.ssh/id_rsa_foreman_proxy root@client.example.com

Using the orcharhino API to Obtain SSH Keys for Remote Execution

To use the orcharhino API to download the public key from orcharhino Proxy, complete this procedure on each target host.

Procedure

  1. On the target host, create the ~/.ssh directory to store the SSH key:

    $ mkdir ~/.ssh

  2. Download the SSH key from orcharhino Proxy:

    $ curl https://orcharhino-proxy.network2.example.com:443/ssh/pubkey >> ~/.ssh/authorized_keys

  3. Configure permissions for the ~/.ssh directory:

    $ chmod 700 ~/.ssh

  4. Configure permissions for the authorized_keys file:

    $ chmod 600 ~/.ssh/authorized_keys

Configuring a AutoYaST Template to Distribute SSH Keys During Provisioning

You can add a remote_execution_ssh_keys snippet to your custom AutoYaST template to deploy SSH Keys to hosts during provisioning. AutoYaST templates that orcharhino ships include this snippet by default. orcharhino copies the SSH key for remote execution to the systems during provisioning.

Procedure

  • To include the public key in newly-provisioned hosts, add the following snippet to the AutoYaST template that you use:

    <%= snippet 'remote_execution_ssh_keys' %>

Configuring a Kickstart Template to Distribute SSH Keys During Provisioning

You can add a remote_execution_ssh_keys snippet to your custom Kickstart template to deploy SSH Keys to hosts during provisioning. Kickstart templates that orcharhino ships include this snippet by default. orcharhino copies the SSH key for remote execution to the systems during provisioning.

Procedure

  • To include the public key in newly-provisioned hosts, add the following snippet to the Kickstart template that you use:

    <%= snippet 'remote_execution_ssh_keys' %>

Configuring a Preseed Template to Distribute SSH Keys During Provisioning

You can add a remote_execution_ssh_keys snippet to your custom Preseed template to deploy SSH Keys to hosts during provisioning. Preseed templates that orcharhino ships include this snippet by default. orcharhino copies the SSH key for remote execution to the systems during provisioning.

Procedure

  • To include the public key in newly-provisioned hosts, add the following snippet to the Preseed template that you use:

    <%= snippet 'remote_execution_ssh_keys' %>

Configuring a keytab for Kerberos Ticket Granting Tickets

Use this procedure to configure orcharhino to use a keytab to obtain Kerberos ticket granting tickets. If you do not set up a keytab, you must manually retrieve tickets.

Procedure

  1. Find the ID of the foreman-proxy user:

    $ id -u foreman-proxy

  2. Modify the umask value so that new files have the permissions 600:

    $ umask 077

  3. Create the directory for the keytab:

    $ mkdir -p "/var/kerberos/krb5/user/My_User_ID"

  4. Create a keytab or copy an existing keytab to the directory:

    $ cp My_Client.keytab /var/kerberos/krb5/user/My_User_ID/client.keytab

  5. Change the directory owner to the foreman-proxy user:

    $ chown -R foreman-proxy:foreman-proxy "/var/kerberos/krb5/user/My_User_ID"

  6. Ensure that the keytab file is read-only:

    $ chmod -wx "/var/kerberos/krb5/user/My_User_ID/client.keytab"

  7. Restore the SELinux context:

    $ restorecon -RvF /var/kerberos/krb5

Configuring Kerberos Authentication for Remote Execution

You can use Kerberos authentication to establish an SSH connection for remote execution on orcharhino hosts.

Prerequisites

  • Enroll orcharhino Server on the Kerberos server

  • Enroll the orcharhino target host on the Kerberos server

  • Configure and initialize a Kerberos user account for remote execution

  • Ensure that the foreman-proxy user on orcharhino has a valid Kerberos ticket granting ticket

Procedure

  1. To install and enable Kerberos authentication for remote execution, enter the following command:

    $ orcharhino-installer --scenario katello \
--foreman-proxy-plugin-remote-execution-script-ssh-kerberos-auth true

  2. To edit the default user for remote execution, in the orcharhino management UI, navigate to Administer > Settings and click the Remote Execution tab. In the SSH User row, edit the second column and add the user name for the Kerberos account.

  3. Navigate to remote_execution_effective_user and edit the second column to add the user name for the Kerberos account.

Verification

  • To confirm that Kerberos authentication is ready to use, run a remote job on the host. For more information, see Executing a Remote Job in Managing Hosts.

Setting up Job Templates

orcharhino provides default job templates that you can use for executing jobs. To view the list of job templates, navigate to Hosts > Job templates. If you want to use a template without making changes, proceed to Executing a Remote Job in Managing Hosts.

You can use default templates as a base for developing your own. Default job templates are locked for editing. Clone the template and edit the clone.

Procedure

  1. To clone a template, in the Actions column, select Clone.

  2. Enter a unique name for the clone and click Submit to save the changes.

Job templates use the Embedded Ruby (ERB) syntax. For more information about writing templates, see the Template Writing Reference in Managing Hosts.

Ansible Considerations

To create an Ansible job template, use the following procedure and instead of ERB syntax, use YAML syntax. Begin the template with ---. You can embed an Ansible playbook YAML file into the job template body. You can also add ERB syntax to customize your YAML Ansible template. You can also import Ansible playbooks in orcharhino. For more information, see Synchronizing Repository Templates in Managing Hosts.

Parameter Variables

At run time, job templates can accept parameter variables that you define for a host. Note that only the parameters visible on the Parameters tab at the host’s edit page can be used as input parameters for job templates. If you do not want your Ansible job template to accept parameter variables at run time, in the orcharhino management UI, navigate to Administer > Settings and click the Ansible tab. In the Top level Ansible variables row, change the Value parameter to No.

Executing a Remote Job

You can execute a job that is based on a job template against one or more hosts.

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

Procedure

  1. In the orcharhino management UI, navigate to Hosts > All Hosts and select the target hosts on which you want to execute a remote job. You can use the search field to filter the host list.

  2. From the Select Action list, select Schedule a Job.

  3. On the Job invocation page, define the main job settings:

  4. Select the Job category and the Job template you want to use.

  5. Optional: Select a stored search string in the Bookmark list to specify the target hosts.

  6. Optional: Further limit the targeted hosts by entering a Search query. The Resolves to line displays the number of hosts affected by your query. Use the refresh button to recalculate the number after changing the query. The preview icon lists the targeted hosts.

  7. The remaining settings depend on the selected job template. See Creating a Job Template for information on adding custom parameters to a template.

  8. Optional: To configure advanced settings for the job, click Display advanced fields. Some of the advanced settings depend on the job template, the following settings are general:

    • Effective user defines the user for executing the job, by default it is the SSH user.

    • Concurrency level defines the maximum number of jobs executed at once, which can prevent overload of systems' resources in a case of executing the job on a large number of hosts.

    • Timeout to kill defines time interval in seconds after which the job should be killed, if it is not finished already. A task which could not be started during the defined interval, for example, if the previous task took too long to finish, is canceled.

    • Type of query defines when the search query is evaluated. This helps to keep the query up to date for scheduled tasks.

    • Execution ordering determines the order in which the job is executed on hosts: alphabetical or randomized.

      Concurrency level and Timeout to kill settings enable you to tailor job execution to fit your infrastructure hardware and needs.

  9. To run the job immediately, ensure that Schedule is set to Execute now. You can also define a one-time future job, or set up a recurring job. For recurring tasks, you can define start and end dates, number and frequency of runs. You can also use cron syntax to define repetition.

  10. Click Submit. You can view status of the jobs in the Recent Jobs section on the same page.

CLI procedure

  1. Enter the following command on orcharhino:

    $ hammer settings set \
--name=remote_execution_global_proxy \
--value=false

  2. Find the ID of the job template you want to use:

    $ hammer job-template list

  3. Show the template details to see parameters required by your template:

    $ hammer job-template info --id My_Template_ID

  4. Execute a remote job with custom parameters:

    # hammer job-invocation create \
--inputs My_Key_1="My_Value_1",My_Key_2="My_Value_2",... \
--job-template "My_Template_Name" \
--search-query "My_Search_Query"

    Replace My_Search_Query with the filter expression that defines hosts, for example "name ~ My_Pattern". For more information about executing remote commands with hammer, enter hammer job-template --help and hammer job-invocation --help.

Scheduling a Recurring Ansible Job for a Host

You can schedule a recurring job to run Ansible roles on hosts.

Prerequisite

  • Ensure you have the view_foreman_tasks, view_job_invocations, and view_recurring_logics permissions.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > All Hosts and select the target host on which you want to execute a remote job.

  2. On the Ansible tab, select Jobs.

  3. Click Schedule recurring job.

  4. Define the repetition frequency, start time, and date of the first run in the Create New Recurring Ansible Run window.

  5. Click Submit.

  6. Optional: View the scheduled Ansible job in host overview or by navigating to Ansible > Jobs.

Scheduling a Recurring Ansible Job for a Host Group

You can schedule a recurring job to run Ansible roles on host groups.

Procedure

  1. In the orcharhino management UI, navigate to Configure > Host groups.

  2. In the Actions column, select Configure Ansible Job for the host group you want to schedule an Ansible roles run for.

  3. Click Schedule recurring job.

  4. Define the repetition frequency, start time, and date of the first run in the Create New Recurring Ansible Run window.

  5. Click Submit.

Monitoring Jobs

You can monitor the progress of a job while it is running. This can help in any troubleshooting that may be required.

Ansible jobs run on batches of 100 hosts, so you cannot cancel a job running on a specific host. A job completes only after the Ansible playbook runs on all hosts in the batch.

Procedure

  1. In the orcharhino management UI, navigate to Monitor > Jobs. This page is automatically displayed if you triggered the job with the Execute now setting. To monitor scheduled jobs, navigate to Monitor > Jobs and select the job run you wish to inspect.

  2. On the Job page, click the Hosts tab. This displays the list of hosts on which the job is running.

  3. In the Host column, click the name of the host that you want to inspect. This displays the Detail of Commands page where you can monitor the job execution in real time.

  4. Click Back to Job at any time to return to the Job Details page.

CLI procedure

  1. Find the ID of a job:

    # hammer job-invocation list

  2. Monitor the job output:

    # hammer job-invocation output \
--host "My_Host_Name" \
--id My_Job_ID

  3. Optional: To cancel a job, enter the following command:

    # hammer job-invocation cancel \
--id My_Job_ID

Job Template Examples and Extensions

Use this section as a reference to help modify, customize, and extend your job templates to suit your requirements.

Customizing Job Templates

When creating a job template, you can include an existing template in the template editor field. This way you can combine templates, or create more specific templates from the general ones.

The following template combines default templates to install and start the nginx service on clients:

<%= render_template 'Package Action - SSH Default', :action => 'install', :package => 'nginx' %>
<%= render_template 'Service Action - SSH Default', :action => 'start', :service_name => 'nginx' %>

The above template specifies parameter values for the rendered template directly. It is also possible to use the input() method to allow users to define input for the rendered template on job execution. For example, you can use the following syntax:

<%= render_template 'Package Action - SSH Default', :action => 'install', :package => input("package") %>

With the above template, you have to import the parameter definition from the rendered template. To do so, navigate to the Jobs tab, click Add Foreign Input Set, and select the rendered template from the Target template list. You can import all parameters or specify a comma separated list.

Default Job Template Categories

Job template category Description

Packages

Templates for performing package related actions. Install, update, and remove actions are included by default.

Puppet

Templates for executing Puppet runs on target hosts.

Power

Templates for performing power related actions. Restart and shutdown actions are included by default.

Commands

Templates for executing custom commands on remote hosts.

Services

Templates for performing service related actions. Start, stop, restart, and status actions are included by default.

Katello

Templates for performing content related actions. These templates are used mainly from different parts of the orcharhino management UI (for example bulk actions UI for content hosts), but can be used separately to perform operations such as errata installation.

Example restorecon Template

This example shows how to create a template called Run Command - restorecon that restores the default SELinux context for all files in the selected directory on target hosts.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Job templates. Click New Job Template.

  2. Enter Run Command - restorecon in the Name field. Select Default to make the template available to all organizations. Add the following text to the template editor:

    restorecon -RvF <%= input("directory") %>

    The <%= input("directory") %> string is replaced by a user-defined directory during job invocation.

  3. On the Job tab, set Job category to Commands.

  4. Click Add Input to allow job customization. Enter directory to the Name field. The input name must match the value specified in the template editor.

  5. Click Required so that the command cannot be executed without the user specified parameter.

  6. Select User input from the Input type list. Enter a description to be shown during job invocation, for example Target directory for restorecon.

  7. Click Submit. For more information, see Executing a restorecon Template on Multiple Hosts in Managing Hosts.

Rendering a restorecon Template

This example shows how to create a template derived from the Run command - restorecon template created in Example restorecon Template. This template does not require user input on job execution, it will restore the SELinux context in all files under the /home/ directory on target hosts.

Create a new template as described in Setting up Job Templates, and specify the following string in the template editor:

<%= render_template("Run Command - restorecon", :directory => "/home") %>

Executing a restorecon Template on Multiple Hosts

This example shows how to run a job based on the template created in Example restorecon Template on multiple hosts. The job restores the SELinux context in all files under the /home/ directory.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > All hosts and select target hosts. Select Schedule Remote Job from the Select Action list.

  2. In the Job invocation page, select the Commands job category and the Run Command - restorecon job template.

  3. Type /home in the directory field.

  4. Set Schedule to Execute now.

  5. Click Submit. You are taken to the Job invocation page where you can monitor the status of job execution.

Including Power Actions in Templates

This example shows how to set up a job template for performing power actions, such as reboot. This procedure prevents orcharhino from interpreting the disconnect exception upon reboot as an error, and consequently, remote execution of the job works correctly.

Create a new template as described in Setting up Job Templates, and specify the following string in the template editor:

<%= render_template("Power Action - SSH Default", :action => "restart") %>

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