Bookmark this page

Chapter 7. Run Remote Execution

Abstract

Goal	Run ad hoc and scheduled tasks on managed hosts with various configuration management tools.
Objectives	Prepare for remote execution by establishing a secure connection to hosts and creating job templates, and then run remote jobs and view job results. Configure and enable remote execution and install additional Ansible Roles on a Satellite Capsule Server. Create a content view that supports Puppet configuration and create an activation key that enables Puppet configuration.
Sections	Run Remote Jobs on Managed Hosts (and Guided Exercise) Configure Ansible Remote Execution (and Guided Exercise) Run Remote Puppet Jobs on Managed Hosts (and Guided Exercise)
Lab	Run Remote Execution

Run Remote Jobs on Managed Hosts

Objectives

Prepare for remote execution by establishing a secure connection to hosts and creating job templates, and then run remote jobs and view job results.

Run Remote Jobs on Hosts

You can use Satellite to run remote jobs on managed hosts. The jobs to run on managed hosts can be shell commands and scripts, Ansible ad hoc commands, playbooks, or roles. This feature is called remote execution.

The remote execution feature is enabled by default on Satellite Server. On Capsule Server, you must specifically enable this feature. This feature uses SSH to run the jobs in the managed hosts. When enabled, Capsule Servers handle remote execution for their managed hosts. Satellite Server can then scale and control many hosts without requiring direct access to all target hosts.

You can run jobs on multiple hosts at the same time, and use command variables to simplify multiple target scripts.

Enable Remote Execution

By default, on Capsule Servers the remote execution feature is disabled. To enable remote execution on your Capsule, use the following command:

[root@capsule ~]# satellite-installer --scenario capsule \
--enable-foreman-proxy-plugin-remote-execution-ssh

To verify whether remote execution is enabled on Capsule, in the Satellite web UI, navigate to Infrastructure → Capsules. Then, click the Capsule name and view the Active features section for the Capsule. If SSH is listed, then remote execution is enabled.

Figure 7.1: Remote execution is enabled

By default, Satellite uses remote execution to run the remote job. You can instead change this behavior to use the Katello agent if required. However, the Katello agent is deprecated and will be removed in a future Satellite version. To use the Katello agent, first create a custom job template. Then, navigate to Administer → Remote Execution Features and change the job template for every action to change.

Distribute SSH Keys for Remote Execution

During Capsule installation, Satellite automatically creates the SSH keys for remote execution, but does not automatically distribute these keys to managed hosts. You must manually distribute the Capsule's public keys to each host that will use remote execution.

The remote execution settings for SSH are stored in the /etc/foreman-proxy/settings.d/remote_execution_ssh.yml file.

On the remote execution target hosts, ensure that the SSH service is active and that the firewall allows access to port 22.

You can distribute the public key from your Capsule to the target hosts by using one of the following methods:

Distribute the SSH keys manually by using the ssh-copy-id command. Repeat for each target host to manage.
```
[root@capsule ~]# ssh-copy-id -i ~foreman-proxy/.ssh/id_rsa_foreman_proxy.pub \
root@host.example.com
```

Important

Starting with RHEL 9, the OpenSSH server prevents password-based authentication for the root user account by default, but allows private key-based authentication for root. For this reason, to manually distribute the SSH keys by using the ssh-copy-id command, you must first set the PermitRootLogin parameter to yes in the /etc/ssh/sshd_config file to allow password-based authentication for the root user. Then, you must reload the sshd service to apply the changes.

It is a good practice to prohibit password-based authentication to the root user account from remote systems. Red Hat recommends changing the PermitRootLogin parameter to the default value (without-password) after you successfully distribute the SSH keys.

Use the Satellite API to download the public key from the Capsule. On each target host, use the following command:
```
[root@host ~]# curl https://capsule.example.com:9090/ssh/pubkey >> \
~/.ssh/authorized_keys
```
Distribute the public key when you provision a new system by using Kickstart. To include the public key in the Kickstart configuration, modify the Kickstart default finish template to include the following line:
```
<%= snippet 'remote_execution_ssh_keys' %>
```

Note

You can use Kerberos authentication to establish an SSH connection for remote execution. For more information about how to configure your environment by using Kerberos, see the Setting up Kerberos Authentication for Remote Execution section in the Managing Hosts guide at https://access.redhat.com/documentation/en-us/red_hat_satellite/6.11/html-single/managing_hosts/index#configuring-kerberos-authentication-for-remote-execution_managing-hosts

Use Job Templates to Define Remote Jobs

The commands to run on a remote host should exist on Satellite as a job template. Satellite includes various job templates to simplify administrative tasks, such as package installation, power-related activities, and service management. You can also create custom job templates.

Invoke a Job Template

With the SSH keys distributed on the target hosts, you can run jobs based on existing job templates against one or more of the hosts.

The following procedure shows how to execute a remote job based on an existing template:

Log in to the Satellite web UI as a user with the appropriate access level.
Ensure that the correct organization context and location are set. To access the full list of hosts, set the organization to Any Organization and the location to Any Location.
Navigate to Hosts → All hosts and select the target hosts for the job.
Click Select Action and choose Schedule Remote Job.
Figure 7.2: Remote job scheduling
On the Job invocation page, define the job settings:
- Select the Job category and the Job template to use.
- Enter a search query to limit the list of targeted hosts (optional).
- The remaining settings depend on the job template that you select. Choose a Run Command template to run a Linux command or script.
To execute the job as a user other than the SSH user, click Display advanced fields. Advanced settings depend on the job template type. In this example, Effective user defines the user for executing the job.
Specify when to run this job:
- Execute now executes the job on submission.
- Schedule future execution specifies a future date and time to execute the job.
- Set up recurring execution creates a recurring job where you can specify the start and end dates, number, and frequency of runs.
Click Submit to display the Job Overview page, to show the status of the job.
Figure 7.3: Job invocation page

Monitor Jobs

You can monitor the progress of a running job in the Job Overview page. On the Job Overview page, click the name of the target host to view the output of a running job. This action opens a new page with the output of your job.

To monitor scheduled jobs, navigate to Monitor → Jobs and select the job to inspect. On the Job Overview page, click the job to inspect its output.

Figure 7.4: Job details page

On the Overview tab, scroll down and click the host to inspect. This action displays a new page where you can monitor the job execution results.

Figure 7.5: Monitoring a remote job

Execute and Monitor Jobs with CLI

Use the Hammer CLI to execute and monitor remote jobs. You can create shell scripts to interact with Satellite and automate your administrative tasks.

To execute a remote job from the CLI, first list the available templates.

[root@satellite ~]# hammer job-template list
----|-----------------------------------|------------------|----------|-----------
ID  | NAME                              | JOB CATEGORY     | PROVIDER | TYPE
----|-----------------------------------|------------------|----------|-----------
178 | Ansible Collection - Install f... | Ansible Galaxy   | Ansible  | job_tem...
179 | Ansible Roles - Ansible Defaul... | Ansible Playbook | Ansible  | job_tem...
180 | Ansible Roles - Install from G... | Ansible Galaxy   | Ansible  | job_tem...
...output omitted...
158 | Run Command - SSH Default         | Commands         | SSH      | job_tem...
...output omitted...
174 | Update Package - Katello SSH D... | Katello          | SSH      | job_tem...
----|-----------------------------------|------------------|----------|-----------

Then, to access the template details and parameters, use the job template's ID or name.

[root@satellite ~]# hammer job-template info --id 158
ID:            158
Name:          Run Command - SSH Default
Job Category:  Commands
Provider:      SSH
Type:          job_template
Description:

Inputs:
  - command

Locations:
    Boston
    Default Location
Organizations:
    Default Organization
    Operations

To execute a remote job with custom parameters, provide the specified inputs in the job template details, and create a filter that specifies the target hosts, for example "name=server1.example.com".

[root@satellite ~]# hammer job-invocation create \
--job-template-id 158 --inputs command="date" \
--search-query "name=server1.example.com"
Job invocation 1 created
[......................................................................] [100%]

You can list the running or finished remote jobs with the following command:

[root@satellite ~]# hammer job-invocation list
---|-------------|-----------|---------|--------|---------|-------|--------------
ID | DESCRIPTION | STATUS    | SUCCESS | FAILED | PENDING | TOTAL | START
---|-------------|-----------|---------|--------|---------|-------|--------------
1  | Run date    | succeeded | 1       | 0      | 0       | 1     | 2022-06-29...
---|-------------|-----------|---------|--------|---------|-------|--------------

Use the remote job ID to monitor a running job or inspect the output of a finished remote job. Replace the host option with the hostname that the job was executed on.

[root@satellite ~]# hammer job-invocation output --id 1 \
--host server1.lab.example.com
Wed Jun 29 10:55:08 EDT 2022
Exit status: 0

To cancel a running or scheduled job, use the following hammer command:

[root@satellite ~]# hammer job-invocation cancel --id job_ID

Satellite Remote Execution Global Settings

Satellite provides global settings to customize remote execution on the Administer → Settings page in the Remote Execution tab.

The following table explains some important global settings:

Parameter name	Description
Default SSH key passphrase	Specifies the default passphrase to use for SSH.
Default SSH password	Specifies the default password to use for SSH.
Effective User Method	Specifies the method to set the effective user on the target hosts.
Effective User	Specifies the effective user for any job. You can override this setting for each job template and job invocation.
SSH User	Specifies the default user that the Capsule uses to connect to the target host. This user can be different from the effective user.

Important

Change these settings only by using the Satellite web UI, because every time you run the satellite-installer command, any manual change to the /etc/foreman/settings.yml file is overwritten. Alternatively, use the foreman-rake config command from a console.

Create a Job Template

A job template is a powerful tool to run remote commands easily and consistently. A job template can specify additional logic for handling more complex scenarios such as different operating system versions. Satellite ships with various job templates, for example to run simple remote commands, use Puppet for configuration changes, or use Ansible ad hoc commands, playbooks, or roles. Depending on your environment configuration, you might need to create a job template. You can also modify or combine existing job templates or create job templates for your needs.

To create a job template in the Satellite web UI, navigate to Hosts → Job templates and click New Job Template. In the Template tab, enter a unique name in the Name field. Then, select the appropriate organizations and locations to access your template, or use Default to provide it to all your organizations. Use the template editor to create the template, or upload it from a file by using the Import File button.

After you complete the Template tab information, go to the Job tab and select a category from the Job category field. Alternatively, create your own category. Select the required provider type from the list: use SSH for shell scripts, and Ansible for Ansible-related tasks or Playbooks.

Optionally, go to the Inputs tab and click Add Input to define an input parameter. Although Satellite requests these parameters when executing the job, you do not have to define them in the template.

Finally, go to the Location and Organizations tabs and choose the locations and organization where this template is available. Click Submit to create the job template.

Use ERB in Job Templates

Red Hat Satellite uses ERB (Embedded Ruby) syntax among others in job templates. The default templates in Satellite provide a good source for the ERB syntax.

When the remote job is running, Satellite executes the code in the ERB syntax, and replaces the variables with specific values. This process is called rendering. Satellite uses a safe-mode rendering mechanism, which prevents execution of any harmful code by using the templates.

The following examples summarize the ERB syntax:

<% %>

Encloses Ruby code within the ERB template. Satellite renders the code when it renders the template. The template can contain Ruby structure as well as Satellite-specific functions and variables. The following example shows how to restart a service depending on the operating system in use:

<% if @host.operatingsystem.family == "Redhat" && @host.operatingsystem.major.to_i > 6 %>
systemctl <%= input("action") %> <%= input("service") %>
<% else %>
service <%= input("service") %> <%= input("action") %>
<% end -%>

If the host is running a later RHEL version than 6, then it runs the systemctl command followed by the action and service. The action and name are provided through variables. For all other hosts, the example template runs the service command followed by the service and action.

<%= %>

Inserts the code output into the template. For example, for variable substitution, use the following code:

echo <%= @host.name %>

<%# %>

Indicates a comment. Satellite ignores the comment when rendering the template.

<%# This line is a comment %>

Note

For more information about how to write a job template, see the Template Writing Reference section in the Managing Hosts guide at https://access.redhat.com/documentation/en-us/red_hat_satellite/6.11/html-single/managing_hosts/index#Template_Writing_Reference_managing-hosts

References

For more information, see the Configuring and Setting Up Remote Jobs section in the Managing Hosts guide at https://access.redhat.com/documentation/en-us/red_hat_satellite/6.11/html-single/managing_hosts/index#Configuring_and_Setting_Up_Remote_Jobs_managing-hosts

Discuss Red Hat Satellite 6 Administration

Go to community

Welcome to the Red Hat Satellite 6 Administration (RH403) group in the Red Hat Learning Community!

Syed

26 wrz 2023

We are excited to launch a space dedicated to the Red Hat Training course Red Hat Satellite 6 Administration! To gain the most value from this group - click the "Join Group" button in the upper right hand corner of the group home page.We encourage group members to collaborate in this group to discuss topics, ask questions, share best practices and tips, provide course feedback, and share their accomplishments as it relates to RH403.Read more about Red Hat Satellite 6 Administration here.

Revision: rh403-6.11-3ad886e