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.
This file can be batch loaded via [rd-jobs] load command:
rd-jobs load -p project --file /path/to/jobs.xmlRundeck job definitions can be dumped and saved to a file via rd-jobs list command:
rd-jobs list -p project --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
limit on the amount of log output
Job command modes
Jobs execute a sequence of commands. Commands come in several styles:
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 | |
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 | |
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 | |
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.
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><
]]></description>
</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>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 - secondsm - minutesh - hoursd - days[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 hours120m - 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 count indicating the maximum number of times to retry the job if it fails or times out.
Allowed values:
${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>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 statustruncate - do not halt the job, and truncate all further outputThe allowed values for status are any status string:
failed - halt and fail the jobaborted - halt and abort the job<anything> - a custom status stringschedule 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 schedule year to run the job
Attributes
The job context.
Nested elements
The context project name. Ignored. Project name must be specified at import time.
The context options for user input.
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, will be rendered as Markdown.
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"
"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.
for a secure option, a storage path to password value to use as default
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>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 | |
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.
Attributes
Nested elements
Example
<nodefilters excludeprecedence="true">
<filter>.*</filter>
</nodefilters>The filter string to select matching nodes.
The content of this element is the full node filter string. See User Guide - Node Filters.
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
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:
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.
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
keepgoingOnSuccesskeepgoing 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> Defines a description for a step.
Example:
<command>
<exec>echo this is a shell command</exec>
<description>Demonstrate echo command</description>
</command>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> 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 somethingIf 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'Define a jobref element within the command element
Attributes
the job name
the group name
true/false whether the Job reference step should run for each node
Nested elements
Optional "arg" element can be embedded:
: 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.
The node filters to override for the jobref.
Nested elements
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>The dispatch options to override for the jobref.
The content is the same as for the job dispatch section.
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
Nested elements
Optional 'configuration' can be embedded containing a list of 'entry' key/value pairs:
Defines plugin configuration entries
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> Defines a plugin step that executes for each node.
Defines a plugin step that executes once in a workflow.
Contains the key/value pair entries for plugin configuration, within a node-step-plugin or step-plugin.
Defines a key/value pair within a configuration.
Attributes:
Key for the pair
Textual value
Defines email, webhook or plugin notifications for Job success and failure, with in a job definition.
Nested elements
define notifications for success result
define notifications for failure/kill result
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> 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.
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.
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.
Define email recipients for Job execution result, within onsuccess, onfailure or onstart.
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, onfailure or onstart.
Attributes
Example
<webhook urls="http://server/callback?id=${execution.id}&status=${execution.status}&trigger=${notification.trigger}"/>Defines a configuration for a plugin to perform a Notification, within onsuccess, onfailure or onstart.
Attributes
Nested elements
Optional 'configuration' can be embedded containing a list of 'entry' key/value pairs:
Defines plugin configuration entries
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> Contains the key/value pair entries for plugin configuration, within a plugin notification definition.
Defines a key/value pair within a configuration.
Attributes:
Key for the pair
Textual value
[rd-jobs](../man1/rd-jobs.html)
The Rundeck source code and all documentation may be downloaded from https://github.com/rundeck/rundeck/.