How to run a rundeck job using curl

Curl job run.md

Run a Job using Curl

This document describes how to use CURL to interact with the RunDeck server to invoke a Job to run.

The steps are as follows:

1. Authenticate to the RunDeck server and acquire a session cookie.

2. Submit run request for particular Job ID, sending session cookie.

3. Authenticate

---

The following script logs in with default admin username/pass to localhost:4440, and saves the cookies into "cookies" file. It fails if http request fails, or user unauthorized.

The request submits j_username and j_password params to the url $SERVERURL/j_security_check. The response should be a redirect (302) to the root path of the server. Otherwise the response will be a redirect to $SERVERURL/user/error.

#!/bin/bash

#usage: runjob.sh <server URL | - > <job ID>

errorMsg() {
   echo "$*" 1>&2
}

DIR=$(cd `dirname $0` && pwd)

# accept url argument on commandline, if '-' use default
url=$1
if [ "-" == "$url" ] ; then
    url='http://localhost:4440'
fi
loginurl="${url}/j_security_check"

# curl opts to use a cookie jar, and follow redirects, showing only errors
CURLOPTS=-s -S -L -c $DIR/cookies -b $DIR/cookies

#curl command to use with opts
CURL=curl $CURLOPTS

# submit login request
echo "Login..."
$CURL -d j_username=admin -d j_password=admin $loginurl > $DIR/curl.out 
if [ 0 != $? ] ; then
    errorMsg "failed login request to ${loginurl}"
    exit 2
fi

# make sure result doesn't contain the login form again, implying login failed
grep 'j_security_check' -q $DIR/curl.out 
if [ 0 == $? ] ; then
    errorMsg "login was not successful"
    exit 2
fi

echo "Login OK"

2. Submit run request for job

---

The request to run the job is submitted to $SERVERURL/scheduledExecution/runJobByName.xml. The responses for the run request are in XML, so a tool like xmlstarlet is useful.

The job to be run can be specified in two ways

1. Specify the Job ID, using an id parameter.
2. Specify the Job name, and optional group, using the jobName and groupPath parameters.

If the specified job name and group do not uniquely identify a job, then an error response will be returned.

The job can accept arguments specified with the extra.argString parameter.

Additionally, nodeset filters defined in the job can be overridden. To do so, include a parameter extra.doNodeDispatch=true. As well as filter parameters of the form: extra.node(Include|Exclude)[filter]=value. Where "filter" is one of "" (blank, indicating hostname), "name","tags","osFamily", etc.. As well, extra.nodeThreadcount and extra.nodeKeepgoing can be specified.

The XML response will either be a success response, or error response.

Error response:

<response error='true'>
    <error>
        <message>error message</message>
    </error>
</response>

A success response will include information about the successful execution request:

<response success='true'>
    <success>
        <message>success message</message>
    </success>
    <succeeded count="x">
        <execution>
            <id>..</id>
            <name>job name</name>
            <url>...</url>
        </execution>
    </succeeded>
</response>

The <id> element will contain the ID of the execution, and the <url> element will contain the URL (relative to the $SERVERURL) for viewing the output.

Here is the continuation of the previous shell script to submit the run request:

XMLSTARLET=xml

# now submit req
jobid=$3
params="id=${jobid}"
runurl="${url}/scheduledExecution/runJobByName.xml"
echo "Submit job..."
# get nodes page
$CURL ${runurl}?${params} > $DIR/curl.out
if [ 0 != $? ] ; then
    errorMsg "failed nodes request"
    exit 2
fi

#test curl.out for valid xml
$XMLSTARLET val -w $DIR/curl.out > /dev/null 2>&1
if [ 0 != $? ] ; then
    errorMsg "ERROR: Response was not valid xml"
    exit 2
fi

#test for expected /result element
$XMLSTARLET el $DIR/curl.out | grep -e '^result' -q
if [ 0 != $? ] ; then
    errorMsg "ERROR: Response did not contain expected result"
    exit 2
fi

#If <result error="true"> then an error occured.
waserror=$($XMLSTARLET sel -T -t -v "/result/@error" $DIR/curl.out)
if [ "true" == "$waserror" ] ; then
    errorMsg "Server reported an error: "
    $XMLSTARLET sel -T -t -v "/result/error/message" -n  $DIR/curl.out
    exit 2
fi

#If <response success='true'> then request succeeded.
wassuccess=$($XMLSTARLET sel -T -t -v "/result/@success" $DIR/curl.out)
if [ "true" == "$wassuccess" ] ; then
    echo "Job submitted successfully."
    $XMLSTARLET sel -T -t -v "/result/success/message" -n  $DIR/curl.out
    
    #echo execution id
    $XMLSTARLET sel -T -t -o "Execution ID: " -v "/result/succeeded/execution/id" -n $DIR/curl.out
    
    #echo job name
    $XMLSTARLET sel -T -t -o "Job name: " -v "/result/succeeded/execution/name" -n $DIR/curl.out
    
    #echo execution URL, which is relative to base server URL
    $XMLSTARLET sel -T -t  -o "Output url: $url" -v "/result/succeeded/execution/url" -n $DIR/curl.out
    
    #echo all on one line
    $XMLSTARLET sel -T -t -m "/result/succeeded/execution" -o "[" -v "id" -o "] " -v "name" -o ' &lt;' -v "url" -o '&gt;' -n $DIR/curl.out
fi

#rm $DIR/curl.out
rm $DIR/cookies