Red Hat Training

A Red Hat training course is available for Red Hat Satellite

12.2. Configuring and Running Remote Commands

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

12.2.1. Setting up Job Templates

Satellite provides a number of default job templates that you can use for executing jobs, find them under Hosts → Job templates. If you find a template fitting your needs amongst the default templates, proceed to Section 12.2.2, “Executing Jobs”.
You can also use default templates as a basis for developing your own. Default job templates are locked for editing, therefore you have to first clone the template to be able to modify it.

Procedure 12.1. To Create a Job Template:

  1. Navigate to Hosts → Job templates.
  2. Click New Job Template. As an alternative, you can modify an existing template – in the Actions column, select Clone from the drop-down menu.
  3. Configure the job template:
    1. On the Template tab, enter a unique name for your job template. Select Default to make the template available for all organizations and locations. You can insert the template manually using Template editor or upload it from a text file by clicking Browse. Templates use Embedded Ruby (ERB) template syntax, see Section 12.2.4, “Creating Advanced Templates” for more information. An advanced template is required, for example, for executing jobs that perform power actions; see Example 12.4, “Including Power Actions in Templates” for information on how to include the Power Action - SSH Default template in a custom template.
    2. On the Job tab, you can define the job category (define your own or select from the default categories listed in Table 12.1, “Default Job Template Categories”) as well as the effective user; these settings can be configured also when invoking the job (see Procedure 12.2, “To Execute a Remote Job:”). You can also define input parameters for template commands. These parameters are then requested when executing the job.
    3. Remaining tabs enable setting the template type, organizations and locations as well as viewing the template history.
  4. Click Submit. When the page refreshes, your new template should appear in the list of job templates.

Important

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.

Table 12.1. 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 Satellite web UI (for example bulk actions UI for content hosts), but can be used separately to perform operations such as errata installation.

Example 12.1. Creating a restorecon Template

This example shows how to create a template called Run Command - restorecon that will restore the default SELinux context for all files in the selected directory on target hosts.
  1. Navigate to Hosts → Job templates. Click New Job Template.
  2. Insert 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 will be replaced by a user-defined directory during job invocation.
  3. On the Job tab, perform the following actions:
    1. Set Job category to Commands.
    2. Click Add Input to allow job customization. Insert directory to the Name field. The input name must match the value specified in the Template editor.
    3. Click Required so that the command cannot be executed without the user specified parameter.
    4. Select User input from the Input type drop-down list. Also provide a Description to be shown during job invocation, for example Target directory for restorecon.
  4. Click Submit.
See Example 12.2, “Executing a restorecon Template on Multiple Hosts” for information on how to execute a job based on this template.

12.2.2. Executing Jobs

This section shows how to run a job based on a job template against one or more hosts.

Procedure 12.2. To Execute a Remote Job:

  1. Navigate to Hosts → All hosts and select the target hosts for your job. You can use the search field to narrow down the host list.
  2. From the Select Action menu at the upper right of the screen select Run Job. This will take you to the Job invocation page. Alternatively, if you target just one host, click its name and click Run Job on the host information page. Note that you can invoke jobs also from the Job Templates page by using the Run button.
  3. On the Job invocation page, define the main job settings:
    1. Select the Job category and the Job template you want to use. These settings are required.
    2. Optionally, select a stored search string in the Bookmark list to specify the target hosts.
    3. Optionally, further limit the targeted hosts by inserting 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 will list the targeted hosts.
    4. The remaining settings depend on the selected job template. See Procedure 12.1, “To Create a Job Template:” for information on adding custom parameters to a template.
  4. Clicking Display advanced fields will show advanced setting for the job. 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 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.
    • Time span 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.
    Concurrency level and Time span settings enable you to tailor job execution to fit your infrastructure hardware and needs.
  5. If you want to execute 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. For more information about cron, see Automating System Tasks section of the Red Hat Enterprise Linux 7 System Administrator's Guide.
  6. Click Submit. This displays the Job Overview page, and when the job completes, also displays the status of the job.

Example 12.2. Executing a restorecon Template on Multiple Hosts

This example shows how to execute a job based on the template created in Example 12.1, “Creating a restorecon Template” on multiple hosts. The job will restore the SELinux context in all files under the /home/ directory.
  1. Navigate to Hosts → All hosts and select target hosts. Select Run Job from the Select Action drop-down 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.

12.2.3. Monitoring Jobs

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

Procedure 12.3. To Monitor a Job:

  1. Navigate to the Job page. 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.

12.2.4. Creating Advanced Templates

When creating a job template, you can import an existing template in the Template editor field – this is referred to as rendering. 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 httpd service on Red Hat Enterprise Linux systems: 
<%= render_template 'Package Action - SSH Default', :action => 'install', :package => 'httpd' %>
<%= render_template 'Service Action - SSH Default', :action => 'start', :service_name => 'httpd' %>
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 drop-down list. You can import all parameters or specify a comma separated list.

Example 12.3. Rendering a restorecon Template

This example shows how to create a template derived from the Run command - restorecon template created in Example 12.1, “Creating a 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 Section 12.2.1, “Setting up Job Templates”, and specify the following string in the Template editor screen: 
<%= render_template("Run Command - restorecon", :directory => "/home") %>

Example 12.4. 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 Satellite 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 Section 12.2.1, “Setting up Job Templates”, and specify the following string in the Template editor screen: 
<%= render_template("Power Action - SSH Default", :action => "restart") %>