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
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:
- Navigate to
. - Click . As an alternative, you can modify an existing template – in the Actions column, select Clone from the drop-down menu.
- Configure the job template:
- 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 . 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.
- 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.
- Remaining tabs enable setting the template type, organizations and locations as well as viewing the template history.
- Click . 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.
|
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.
- Navigate to
. Click . - 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. - On the Job tab, perform the following actions:
- Set Job category to
Commands. - Click to allow job customization. Insert
directoryto the Name field. The input name must match the value specified in the Template editor. - Click Required so that the command cannot be executed without the user specified parameter.
- Select
User inputfrom the Input type drop-down list. Also provide a Description to be shown during job invocation, for example Target directory for restorecon.
- Click .
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:
- Navigate to
and select the target hosts for your job. You can use the search field to narrow down the host list. - 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 on the host information page. Note that you can invoke jobs also from the Job Templates page by using the button.
- On the Job invocation page, define the main job settings:
- Select the Job category and the Job template you want to use. These settings are required.
- Optionally, select a stored search string in the Bookmark list to specify the target hosts.
- 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.
- 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.
- 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. - 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. - Click . 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.
- Navigate to
and select target hosts. Select Run Job from the Select Action drop-down list. - In the Job invocation page, select the
Commandsjob category and theRun Command - restoreconjob template. - Type
/homein the directory field. - Set Schedule to
Execute now. - Click . 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:
- Navigate to the Job page. This page is automatically displayed if you triggered the job with the
Execute nowsetting. To monitor scheduled jobs, navigate toand select the job run you wish to inspect. - On the Job page, click the Hosts tab. This displays the list of hosts on which the job is running.
- 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.
- Click 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 , 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") %>