job-v20 - The 'job' XML file declares job entries for Rundeck.
This is a demonstration document using all possible elements in the current Rundeck "jobs" XML.
This file can be batch loaded via rd-jobs load command:
rd-jobs load --file /path/to/jobs.xmlRundeck job definitions can be dumped and saved to a file via rd-jobs list command:
rd-jobs list --file /tmp/jobs.xmlThe root (aka "top-level") element of the jobs XML file.
Nested elements
Example
<joblist>
<job>
...
</job>
<job>
...
</job>
</joblist>The job element is a sub-element of joblist and defines a job executable in Rundeck.
The following elements are used to describe the job. Only one of each element is allowed.
Nested elements
unique UUID to identify the job
the job name
the job description
group name
If the job can be executed multiple times simultaneously
command context
dispatch options
workflow sequence
notifications of execution success/failure, via email or webhook
node filtering expressions
the logging level
Job command modes
Jobs execute a sequence of commands. Commands come in several styles:
Examples
Execute the Unix 'who' command
<joblist>
<job>
<name>who's logged in?</name>
<description>Runs the unix who command</description>
<group>sysadm/users</group>
<context>
<project>default</project>
</context>
<sequence>
<command>
<!-- the Unix 'who' command -->
<exec>who</exec>
</command>
</sequence>
<nodefilters excludeprecedence="true">
<include>
<os-family>unix</os-family>
</include>
</nodefilters>
<dispatch>
<threadcount>1</threadcount>
<keepgoing>true</keepgoing>
</dispatch>
</job>
</joblist>Execute a Bash script
<joblist>
<job>
<name>a simple script</name>
<description>Runs a trivial bash script</description>
<group>sysadm/users</group>
<context>
<project>default</project>
</context>
<sequence>
<command>
<script><![CDATA[#!/bin/bash
echo this is an example job running on $(hostname)
echo whatever
exit 0 ]]></script>
</command>
</sequence>
<dispatch>
<threadcount>1</threadcount>
<keepgoing>true</keepgoing>
</dispatch>
</job>
</joblist>Execute a sequence of other commands, scripts and jobs:
<joblist>
<job>
<name>test coreutils</name>
<description/>
<context>
<project>default</project>
</context>
<sequence>
<!-- the Unix 'who' command -->
<command>
<exec>who</exec>
</command>
<!-- a Job named test/other tests -->
<command>
<jobref group="test" name="other tests"/>
</command>
</sequence>
<dispatch>
<threadcount>1</threadcount>
<keepgoing>false</keepgoing>
</dispatch>
</job>
</joblist>The UUID is a sub-element of job. This string can be set manually (if you are writing the job definition from scratch), or will be assigned at job creation time by the Rundeck server using a random UUID. This string should be as unique as possible if you set it manually.
This identifier is used to uniquely identify jobs when ported between Rundeck instances.
The job name is a sub-element of job. The combination of 'name' and group and project must be unique if the uuid identifier is not included.
The job description is a sub-element of job and allows a short description of the job.
The group is a sub-element of job and defines the job's group identifier. This is a "/" (slash) separated string that mimics a directory structure.
Example
<job>
<name>who</name>
<description>who is logged in?</description>
<group>/sysadm/users</group>
</job>Boolean value: 'true/false'. If 'true', then the job can be run multiple times at once. Otherwise, the Job can only have a single execution at a time.
<job>
<name>who</name>
<description>who is logged in?</description>
<group>/sysadm/users</group>
<multipleExecutions>true</multipleExecutions>
</job>schedule is a sub-element of job and specifies periodic job execution using the stated schedule. The schedule can be specified using embedded elements as shown below, or using a single crontab attribute to set a full crontab expression.
Nested elements
Attributes
Example
Run the job every morning at 6AM, 7AM and 8AM.
<schedule>
<time hour="06,07,08" minute="00"/>
<weekday day="*"/>
<month month="*"/>
</schedule>Run the job every morning at 6:00:02AM, 7:00:02AM and 8:00:02AM only in the year 2010:
<schedule>
<time hour="06,07,08" minute="00" seconds="02"/>
<weekday day="*"/>
<month month="*"/>
<year year="2010"/>
</schedule>Run the job every morning at 6:00:02AM, 7:00:02AM and 8:00:02AM only in the year 2010, using a single crontab attribute to express it:
<schedule crontab="02 00 06,07,08 ? * * 2010"/>For more information, see http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html or http://www.stonebranch.com
Attribute of the schedule, sets the schedule with a full crontab string. For more information, see http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html.
If specified, then the embedded schedule elements are not used.
The schedule time to run the job
Attributes
values: 00-23
values: 00-59
The schedule weekday to run the job
Attributes
* - all ; 1-5 days "sun-sat" ; 1,2,3-5 - days "sun,mon,tue-thu", etc
The schedule month to run the job
Attributes
values: * - all 1-10 - month jan-oct 1,2,3-5 - months jan,feb,mar-may, etc.
day of the month: * - all; 1-31 specific days
The job context.
Nested elements
The context project name.
The context options that correspond to the called command.
Nested elements
Example
<options>
<option name="detail" value="true"/>
</options>Defines one option within the options.
Attributes
the option name
the default value
comma separated list of values
URL to a list of JSON values
Boolean specifying that must pick from one of values
Regex pattern of acceptable value
Description of the option
Boolean specifying that the option is required
"true/false" - whether the option supports multiple input values
A string used to conjoin multiple input values. (Required if multivalued is "true")
"true/false" - whether the option is a secure input option. Not compatible with "multivalued"
Example
Define defaults for the "port" option, requiring regex match.
<option name="port" value="80" values="80,8080,8888" regex="\d+"/>Define defaults for the "port" option, enforcing the values list.
<option name="port" value="80" values="80,8080,8888" enforcedvalues="true" />Define defaults for the "ports" option, allowing multiple values separated by ",".
<option name="port" value="80" values="80,8080,8888" enforcedvalues="true" multivalued="true" delimiter="," />The data returned from the valuesUrl can be formatted as a list of values:
["x value","y value"]or as Name-value list:
[
{name:"X Label", value:"x value"},
{name:"Y Label", value:"y value"},
{name:"A Label", value:"a value"}
] The job dispatch options. See the [Dispatcher options] for general information.
Nested elements
dispatch up to threadcount
keep going flag
Name of the Node attribute to use for ordering the sequence of nodes (default is "nodename")
Order direction for node ranking. Either "ascending" or "descending" (default "ascending")
Example
<dispatch>
<threadcount>1</threadcount>
<keepgoing>false</keepgoing>
<rankAttribute>nodename</rankAttribute>
<rankOrder>descending</rankOrder>
</dispatch>Defines the number of threads to execute within dispatch. Must be a positive integer.
Boolean describing if the dispatch should continue of an error occurs (true/false). If true, continue if an error occurs.
This is the name of a Node attribute that determines the order in which the Nodes are traversed. The default value of "nodename" will rank the nodes based on their names.
This can be any attribute of a Node, even attributes that do not exist on some nodes. For example you can set it to "rank", then any Nodes with a "rank" attribute will be ordered before any other nodes, and they will be used in the order of the rank attribute value.
The values in the rank attribute are compared first numerically if they are valid integers, but otherwise they are compared alphanumerically. Nodes which do not have the specified rank attribute will be ordered by node name and treated as if they come after all nodes which do have the rank attribute (if in ascending order).
This determines whether the rank attribute should be used to order the nodes in ascending or descending order.
Possible values: "ascending", or "descending". The default if not specified is "ascending".
The job logging level. The lower the more profuse the messages.
The job nodefilters options. See Include/exclude patterns for a general description.
Attributes
Nested elements
Example
<nodefilters excludeprecedence="true">
<include>
<hostname/>
<type/>
<tags>tomcats</tags>
<os-name/>
<os-family/>
<os-arch/>
<os-version/>
<name/>
</include>
</nodefilters>The nodefilters include and exclude patterns.
Nested elements
node hostname
node resource name
node type
node tags. comma separated
operating system name (eg, Linux, Mac OS X)
operating system family (eg, unix, windows)
operating system architecture (eg i386,sparc)
operating system version
The job workflow sequence.
Attributes
true/false. (default false). If true, the workflow sequence will continue even if there is a failure
node-first/step-first. (default "node-first"). The strategy to use for executing the workflow across nodes.
The strategy attribute determines the way that the workflow is executed. "node-first" means execute the full workflow on each node prior to the next. "step-first" means execute each step across all nodes prior to the next step.
Nested elements
Defines a step for a workflow sequence.
The different types of sequence steps are defined in different ways.
See:
Script steps can be defined in three ways within a command element:
exec element.script element.scriptfile and scriptargs elements.Example exec step:
<command>
<exec>echo this is a shell command</exec>
</command>Inline script. Note that using CDATA section will preserve linebreaks in the script. Simply put the script within a script element:
<command>
<script><![CDATA[#!/bin/bash
echo this is a test
echo whatever
exit 2 ]></script>
</command>Script File:
<command >
<scriptfile>/path/to/a/script</scriptfile>
<scriptargs>-whatever something</scriptargs>
</command> Script URL:
<command >
<scripturl>http://example.com/path/to/a/script</scripturl>
<scriptargs>-whatever something</scriptargs>
</command> Define a jobref element within the command element
Attributes
the job name
the group name
Nested elements
Optional "arg" element can be embedded:
Example passing arguments to the job:
<command >
<jobref group="My group" name="My Job">
<arg line="-option value -option2 value2"/>
</jobref>
</command> Defines email and webhook notifications for Job success and failure, with in a job definition.
Nested elements
define notifications for success result
define notifications for failure/kill result
Example
<notification>
<onfailure>
<email recipients="test@example.com,foo@example.com" />
</onfailure>
<onsuccess>
<email recipients="test@example.com" />
<webhook urls="http://example.com?id=${execution.id}" />
</onsuccess>
</notification> Embed an email element to send email on success, within notification.
Embed an webhook element to perform a HTTP POST to some URLs, within notification.
Embed an email element to send email on failure or kill, within notification.
Embed an webhook element to perform a HTTP POST to some URLs, within notification.
Define email recipients for Job execution result, within onsuccess or onfailure.
Attributes
Example
<email recipients="test@example.com,dev@example.com" />Define URLs to submit a HTTP POST to containing the job execution result, within onsuccess or onfailure.
Attributes
Example
<webhook urls="http://server/callback?id=${execution.id}&status=${execution.status}&trigger=${notification.trigger}"/>rd-jobs (1).
The Rundeck source code and all documentation may be downloaded from https://github.com/dtolabs/rundeck/.