NAME

job-v21 - The 'job' XML file declares job entries for Rundeck.

This is a demonstration document using all possible elements in the current Rundeck "jobs" XML.

Loading and unloading

This file can be batch loaded via rd jobs load command:

rd jobs load -p project --file /path/to/jobs.xml

Rundeck job definitions can be dumped and saved to a file via rd jobs list command:

rd jobs list -p project --file /tmp/jobs.xml

joblist

The root (aka "top-level") element of the jobs XML file.

Nested elements

job*
declares a single job

Example

<joblist>
  <job>
   ...
  </job>
  <job>
   ...
  </job>
</joblist>

job

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

uuid

unique UUID to identify the job

name

the job name

description

the job description

group

group name

multipleExecutions

If the job can be executed multiple times simultaneously

context

command context

dispatch

dispatch options

sequence

workflow sequence

notification

notifications of execution success/failure, via email or webhook

nodefilters

node filtering expressions

loglevel

the logging level

logging

limit on the amount of log output

Job command modes

Jobs execute a sequence of commands. Commands come in several styles:

  • System command
  • A script
  • A script file or URL
  • Another defined job

Examples

Execute the Unix 'who' command

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<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>

uuid

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.

name

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.

description

The job description is a sub-element of job and allows a short description of the job.

If the description contains more than one line of text, then the first line is used as the "short description" of the job, and rendered exactly as text. The remaining lines are the "extended description", rendered using Markdown format as HTML in the Rundeck GUI. Markdown can also embed HTML directly if you like. See Wikipedia - Markdown.

The HTML is sanitized to remove disallowed tags before rendering to the browser (such as <script>, etc.). You can disable all extended description HTML rendering via a configuration flag. See GUI Customization.

Note: To preserve formatting when defining the extended job description in XML, you should be sure to use a CDATA section. Wrap the contents in <![CDATA[ and ]]>.

Example Extended description

<job>
    <name>My Job</name>
    <description><![CDATA[Performs a service

This is <b>html</b>
<ul><li>bulleted list</li></ul>

<a href="/">Top</a>

1. this is a markdown numbered list
2. second item

[a link](http://example.com)

]]></description>
</job>

group

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>

multipleExecutions

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>

timeout

Timeout string indicating the maximum allowed runtime for a job. After this time expires, the job will be aborted.

The format is:

  • 123 a simple number, indicating seconds
  • [number][unit] where "number" is a valid decimal number, and "unit" is one of:
    • s - seconds
    • m - minutes
    • h - hours
    • d - days
  • Any sequence of [number][unit] pairs. The total time will be the added value of all the units. Any other text in the string is ignored, so the pairs can be separated by spaces or other descriptive text.

These are all valid values:

  • 1d 6h - 1 day and 6 hours
  • 120m - 120 minutes
  • ${option.timeout} reference to a job option value
<job>
    <name>who</name>
    <description>who is logged in?</description>
    <group>/sysadm/users</group>
    <timeout>1d 6h</timeout>
</job>

retry

Retry count indicating the maximum number of times to retry the job if it fails or times out.

Allowed values:

  • An integer number, indicating maximum number of retries
  • ${option.retry} reference to a job option value
<job>
    <name>iffy job</name>
    <description>Job which might need to be retried</description>
    <retry>${option.retry}</retry>
</job>

logging

An optional logging limit, and the action to perform if the limit is reached. (See Jobs - Log Limit).

<logging limit='1KB' limitAction='halt' status='aborted' />

If no limitAction is set, it will default to a value of halt and a status of failed.

The syntax for limit is:

  • ### If you specify a number, that is treated as the "Maximum total number of log lines"
  • ###/node If you specify a number followed by /node, the number is treated as the "Maximum number of log lines for a single node"
  • ###[GMK]B If you specify a number followed by a filesize suffix, that is treated as the "total log file size". The file size suffixes allowed are "GB" (gigabyte), "MB" (megabyte), "KB" (kilobyte) and "B" (byte).

The allowed values for limitAction are:

  • halt - halt the job with an optional status
  • truncate - do not halt the job, and truncate all further output

The allowed values for status are any status string:

  • failed - halt and fail the job
  • aborted - halt and abort the job
  • <anything> - a custom status string

schedule

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

time

the hour and minute and seconds

weekday

day(s) of week

month

month(s)

year

year

Attributes

crontab
a full crontab expression

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

crontab

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.

time

The schedule time to run the job

Attributes

hour

values: 00-23

minute

values: 00-59

weekday

The schedule weekday to run the job

Attributes

day
values: * - all ; 1-5 days "sun-sat" ; 1,2,3-5 - days "sun,mon,tue-thu", etc

month

The schedule month to run the job

Attributes

month

values: * - all 1-10 - month jan-oct 1,2,3-5 - months jan,feb,mar-may, etc.

day

day of the month: * - all; 1-31 specific days

year

The schedule year to run the job

Attributes

year
year: * - all; specific year

context

The job context.

Nested elements

options
job options. specifies one or more option elements

project

The context project name. Ignored. Project name must be specified at import time.

options

The context options for user input.

preserveOrder
If set to "true", then the order of the option elements will be preserved in the Rundeck GUI. Otherwise the options will be shown in alphabetical order.

Nested elements

option
an option element

Example

<options>
    <option name="detail" value="true"/>
</options>

option

Defines one option within the options.

Attributes

name

the option name

value

the default value

values

comma separated list of values

valuesUrl

URL to a list of JSON values

enforcedvalues

Boolean specifying that must pick from one of values

regex

Regex pattern of acceptable value

description

Description of the option, will be rendered as Markdown.

required

Boolean specifying that the option is required

multivalued

"true/false" - whether the option supports multiple input values

delimiter

A string used to conjoin multiple input values. (Required if multivalued is "true")

multivalueAllSelected

"true/false" - whether all values should be selected by default

secure

"true/false" - whether the option is a secure input option. Not compatible with "multivalued"

valueExposed

"true/false" - whether a secure input option value is exposed to scripts or not. false means the option will be used only as a Secure Remote Authentication option. default: false.

storagePath

for a secure option, a storage path to password value to use as default

isDate

"true/false" - the option should display as a date/time input field

dateFormat

The date/time format to use in the UI. Using the momentjs format.

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="," />

Use a multi-line description inside a CDATA section to preserve whitespace. Wrap the content in <![CDATA[ and ]]>:

<option name='example'>
  <description><![CDATA[example option description

* this content will be rendered
* as markdown]]></description>
</option>

valuesUrl JSON

The data returned from the valuesUrl can be formatted as a list of values:

["x value","y value"]

or as Name-value list:

1
2
3
4
5
[
  {name:"X Label", value:"x value"},
  {name:"Y Label", value:"y value"},
  {name:"A Label", value:"a value"}
] 

dispatch

The job dispatch options. See the [Dispatcher options] for general information.

Nested elements

threadcount

dispatch up to threadcount

keepgoing

keep going flag

rankAttribute

Name of the Node attribute to use for ordering the sequence of nodes (default is "nodename")

rankOrder

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>

threadcount

Defines the number of threads to execute within dispatch. Must be a positive integer.

keepgoing

Boolean describing if the dispatch should continue of an error occurs (true/false). If true, continue if an error occurs.

rankAttribute

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).

rankOrder

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".

loglevel

The job logging level. The lower the more profuse the messages.

  • DEBUG
  • VERBOSE
  • INFO
  • WARN
  • ERROR

nodefilters

The job nodefilters options.

Attributes

excludeprecedence
boolean value: true or false

Nested elements

filter

node filter string

include

include filter (deprecated)

exclude

exclude filter (deprecated)

Example

<nodefilters excludeprecedence="true">
  <filter>.*</filter>
</nodefilters>

filter

The filter string to select matching nodes.

The content of this element is the full node filter string. See User Guide - Node Filters.

include

See Include/exclude patterns

exclude

See Include/exclude patterns

Include/exclude patterns

The nodefilters include and exclude patterns.

Note: These elements are deprecated and will be removed in a later version of Rundeck. Use the filter string.

Nested elements

hostname

node hostname

name

node resource name

type

node type

tags

node tags. comma separated

os-name

operating system name (eg, Linux, Mac OS X)

os-family

operating system family (eg, unix, windows)

os-arch

operating system architecture (eg i386,sparc)

os-version

operating system version

sequence

The job workflow sequence.

Attributes

keepgoing

true/false. (default false). If true, the workflow sequence will continue even if there is a failure

strategy

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

command
a sequence step

command

Defines a step for a workflow sequence.

The different types of sequence steps are defined in different ways.

See:

A command can embed a errorhandler to define an action to run if the step fails.

A command can have a description element to set the step description.

errorhandler

Defines an action to handle an error in a command.

The contents of an <errorhandler> are exactly the same as for a command except it cannot contain any errorhandler itself.

The different types of errorhandler steps are defined in different ways.

Attributes

keepgoingOnSuccess
true/false. (default false). If true, and the error handler succeeds, the workflow sequence will continue even if the workflow keepgoing is false.

See:

Example:

<errorhandler>
   <exec>echo this is a shell command</exec>
</errorhandler>

Inline script. Note that using CDATA section will preserve linebreaks in the script. Simply put the script within a script element:

<errorhandler>
    <script><![CDATA[#!/bin/bash
echo this is a test
echo whatever
exit 2 ]></script>
</errorhandler>

Script File:

<errorhandler>
    <scriptfile>/path/to/a/script</scriptfile>
    <scriptargs>-whatever something</scriptargs>
</errorhandler>      

Example job reference:

<errorhandler >
    <jobref group="My group" name="My Job">
       <arg line="-option value -option2 value2"/>
    </jobref>
</errorhandler>      

description

Defines a description for a step.

Example:

<command>
   <exec>echo this is a shell command</exec>
   <description>Demonstrate echo command</description>
</command>

Script sequence step

Script steps can be defined in three ways within a command element:

  • Simple shell command using exec element.
  • Embedded script using script element.
  • Script file using 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>      

Script Interpreter

When using <script>, or <scriptfile>, you can declare an interpreter to use to execute the script and its args.

Add <scriptinterpreter> to the <command>:

<command >
    <scriptinterpreter>sudo -u usera</scriptinterpreter>
    <scripturl>http://example.com/path/to/a/script</scripturl>
    <scriptargs>-whatever something</scriptargs>
</command>

This will be executed effectively with this commandline:

sudo -u usera script.sh -whatever something

If the filename and arguments need to be quoted when passed to the interpreter, you can declare argsQuoted='true':

<command >
    <scriptinterpreter argsquoted='true'>sudo -u usera sh -c </scriptinterpreter>
    <scripturl>http://example.com/path/to/a/script</scripturl>
    <scriptargs>-whatever something</scriptargs>
</command>

This will execute as:

sudo -u usera sh -c 'script.sh -whatever something'

Job sequence step

Define a jobref element within the command element

jobref

Attributes

name

the job name

group

the group name

nodeStep

true/false whether the Job reference step should run for each node

Nested elements

Optional "arg" element can be embedded:

arg

: option arguments to the script or job

Example passing arguments to the job:

<command >
    <jobref group="My group" name="My Job">
       <arg line="-option value -option2 value2"/>
    </jobref>
</command>      

If nodeStep is set to "true", then the Job Reference step will operate as a Node Step instead of the default. As a Node Step it will execute once for each matched node in the containing Job workflow, and can use node attribute variable expansion in the arguments to the job reference.

nodefilters (jobref)

The node filters to override for the jobref.

Nested elements

filter
node filter string. See User Guide - Node Filters.

Example:

<jobref group="My group" name="My Job">
  <dispatch>
    <threadcount>1</threadcount>
    <keepgoing>false</keepgoing>
    <rankAttribute>nodename</rankAttribute>
    <rankOrder>descending</rankOrder>
  </dispatch>
  <nodefilters>
    <filter>tags: production+appserver</filter>
  </nodefilters>
</jobref>

dispatch (jobref)

The dispatch options to override for the jobref.

The content is the same as for the job dispatch section.

Plugin step

There are two types of plugin steps that can be defined: Node steps, and workflow steps.

Define either one within the command element:

Both have the following contents:

Attributes

type
The plugin provider type identifier

Nested elements

Optional 'configuration' can be embedded containing a list of 'entry' key/value pairs:

configuration

Defines plugin configuration entries

entry

Defines a key/value pair for the configuration.

Example node step plugin definition:

<command>
    <node-step-plugin type="my-node-step-plugin">
       <configuration>
        <entry key="someconfig" value="a value"/>
        <entry key="timout" value="2000"/>
       </configuration>
    </node-step-plugin>
</command> 

Example workflow step plugin definition:

<command>
    <step-plugin type="my-step-plugin">
       <configuration>
        <entry key="repeat" value="12"/>
        <entry key="debug" value="true"/>
       </configuration>
    </step-plugin>
</command>     

node-step-plugin

Defines a plugin step that executes for each node.

step-plugin

Defines a plugin step that executes once in a workflow.

configuration

Contains the key/value pair entries for plugin configuration, within a node-step-plugin or step-plugin.

entry

Defines a key/value pair within a configuration.

Attributes:

key

Key for the pair

value

Textual value

notification

Defines email, webhook or plugin notifications for Job success and failure, with in a job definition.

Nested elements

onsuccess

define notifications for success result

onfailure

define notifications for failure/kill result

onstart

define notifications for job start

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>
    <onstart>
        <plugin type="MyPlugin">
          <configuration>
            <entry key="customkey" value="customvalue"/>
          </configuration>
        </plugin>
   </onstart>
</notification>      

onsuccess

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 plugin element to perform a custom action, within notification.

onfailure

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.

Embed an plugin element to perform a custom action, within notification.

onstart

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.

Embed an plugin element to perform a custom action, within notification.

email

Define email recipients for Job execution result, within onsuccess, onfailure or onstart.

Attributes

recipients
comma-separated list of email addresses

Example

        <email recipients="test@example.com,dev@example.com" />

webhook

Define URLs to submit a HTTP POST to containing the job execution result, within onsuccess, onfailure or onstart.

Attributes

urls
comma-separated list of URLs

Example

<webhook urls="http://server/callback?id=${execution.id}&status=${execution.status}&trigger=${notification.trigger}"/>

plugin

Defines a configuration for a plugin to perform a Notification, within onsuccess, onfailure or onstart.

Attributes

type
The plugin provider type identifier

Nested elements

Optional 'configuration' can be embedded containing a list of 'entry' key/value pairs:

configuration

Defines plugin configuration entries

entry

Defines a key/value pair for the configuration.

Example notification plugin definition:

<onstart>
    <plugin type="my-notification-plugin">
       <configuration>
        <entry key="someconfig" value="a value"/>
        <entry key="timout" value="2000"/>
       </configuration>
    </plugin>
</onstart> 

configuration

Contains the key/value pair entries for plugin configuration, within a plugin notification definition.

entry

Defines a key/value pair within a configuration.

Attributes:

key

Key for the pair

value

Textual value

SEE ALSO

[rd-jobs](../man1/rd-jobs.html)

The Rundeck source code and all documentation may be downloaded from https://github.com/rundeck/rundeck/.