1.2.1 Who makes the RunDeck software?

RunDeck is developed on GitHub as a project called dtolabs/rundeck. Many ideas for RunDeck come from DTO Solutions consultants working in the field, however all are welcome to join the project and contribute.

RunDeck is free software and is public under the Apache Software License.

1.4.1 RunDeck features

• distributed command execution via SSH
• multi-step workflows
• job definition and on demand or scheduled runs
• graphical console for command and job execution
• role-based access control policy with support for LDAP/ActiveDirectory
• history and auditing logs
• open integration to external host inventory tools
• command line interface

1.4.2 RunDeck in context

RunDeck is meant to compliment the tools you already use (including frameworks like Puppet, Chef, and Rightscale) and is geared towards helping you automate actions across them. If you currently manage your servers by running commands from the terminal or through scripts that SSH commands in a loop, RunDeck is a more user friendly alternative. Instead of managing node lists in a spreadsheet or wiki page and then having to transcribe the list to where you execute commands, RunDeck acts as a command and control portal that lets you execute commands using features like node filtering and parallel execution.

RunDeck also works well for managing virtual servers, be they from a cloud provider or from locally hosted virtualization software. The node abstraction enabled by the RunDeck command dispatcher helps you cope with managing dynamic environments.

Many automation tasks cross the boundaries of tool sets. For example, deploying software or maintaining an application often involves using tools up and down the management tool chain. RunDeck has a simple to use interface to create multi-step workflows that might call a package mangager, configuration mangement tool, system utilities, or your own scripts. RunDeck is really meant to help glue tools together and in return enable a push button interface you can hand off to others.

1.4.3 RunDeck architecture

RunDeck is a server application you host on a system you designate a central administrative control point. Internally, RunDeck stores job definitions and execution history in a relational database. Output from command and job executions is saved on disk.

RunDeck distributed command execution is performed using SSH. SSH connections are made using key-based authentication. RunDeck server configuration includes settings to define the outbound user allowed by the remote hosts. Remote machines are not required to make SSH connections back to the server.

RunDeck architecture

The RunDeck application itself is a Java-based webapp that runs in its own embedded servlet container. The application provides both graphical interface and network interfaces used by the RunDeck shell tools.

Access to the RunDeck application requires a login and password. The default RunDeck installation uses a flat file user directory containing a set of default logins. Logins are defined in terms of a username and password as well as one or more user groups. An alternative configuration to the flat file user directory, is LDAP (e.g., ActiveDirectory). Users must also be authorized to perform actions like command and job execution. This is controlled by an access control facility that reads policy files defined by the RunDeck administrator. Privilege is granted if a user's group membership meets the requirements of the policy.

Two installation methods are supported:

• RPM: The RPM is intended for managed installation and provides robust tools that integrate with your environment, man pages, shell tool set in your path, init.d startup and shutdown

• Launcher: The launcher is intended for quick setup, to get you running right away. Perfect for bootstrapping a project or trying a new feature.

2.1.1 Command dispatching

RunDeck supports a notion called command dispatching wherein a user specifies dispatch critera along with an action (called a command) and this specification is used to perform a distributed execution.

The command dispatcher is an internal mechanism that looks up node resources meeting specified filtering criteria and then performs the distributed command execution. The command executes in a data context that contains information about the Node resource. Besides node filtering, dispatcher options include parameters to control parallel execution, ordering and error handling.

The command dispatcher supports two methods of command execution:

• Ad-hoc commands: Execute any shell command or shell script across a set of hosts.
  
• Jobs: Encapsulate commands as a named Job and tie them together into multi-step workflows.

RunDeck provides both graphical and command line interfaces to interact with the command dispatcher.

2.1.2 Resource model

The command dispatcher works in conjunction with a resource model. A resource model is a representation of hosts deployed in your network. A Node is a resource that is either a physical or virtual instance of a network accessible host.

Nodes have a number of basic properties but these properties can be extended to include arbitrary named key value pairs.

You can configure RunDeck to retrieve and store resource model data from any source, so long as it meets the RunDeck resource model document requirement.

A resource model provider is an external service accesible via the HTTP GET method that returns data conforming to the RunDeck resource model document format resource-v10(5).

2.1.3 Authorization

RunDeck enforces an access control policy that grants certain privileges to groups of users. Every action executed through the RunDeck command dispatcher must meet the requirements of an access control policy definition.

Since RunDeck respects the policy definition, you can define role-based authorization to restrict some users to only a subset of actions. This enables a self-service type interface, where some users have access to only a limited set of executable actions.

2.1.4 Project

A project is a place to separate management activity. All RunDeck activities occur within the context of a project. Each project has its own resource model and Job store.

Multiple projects can be maintained on the same RunDeck server. Projects are independent from one another, so you can use them to organize unrelated systems within a single RunDeck installation. This can be useful for managing different infrastructures.

2.2.1 System Requirements

The following operating systems are known to support RunDeck:

• Linux: Most recent distributions are likely to work
• Windows: XP, Server and above
• Mac OS X 10.4 or later

Root (or Administrator on Windows) is not required or recommended. We recommend using a dedicated user account such as "rundeck".

If there is need for root access, please set up the RunDeck user to have access via sudo.

$ java -version
java version "1.6.0_22"
Java(TM) SE Runtime Environment (build 1.6.0_22-b04-307-10M3261)
Java HotSpot(TM) 64-Bit Server VM (build 17.1-b03-307, mixed mode)

netstat -an | egrep '4440|4435' 

tcp46      0      0  *.4440                 *.*                    LISTEN
tcp46      0      0  *.4435                 *.*                    LISTEN

2.2.2 Installing from Source

Checkout the sources from GitHub

Run the build script:

./build.sh

Build clean

./build.sh -clean

The build will generate a launcher jar. On Linux build servers, an RPM will also be generated.

2.2.3 Installing with RPM

If you want to install RunDeck on Linux via a binary installer, you can generally do so through the RPM tool that comes with your distribution.

# rpm -i rundeck-1.1.0.noarch.rpm

To install it using yum, first install the yum repo package and then run yum install:

# rpm -Uvh http://rundeck.org/latest.rpm
# yum install rundeck

2.2.4 Installing with Launcher

Use the launcher as an alternative to a system package:

1. Download the launcher jar file.

2. Define RDECK_BASE environment variable to the location of the install

   export RDECK_BASE=$HOME/rundeck; # or where you like it
   

3. Create the directory for the installation.

   mkdir -p $RDECK_BASE 
   

4. Copy the launcher jar to the installation directory.

   cp rundeck-launcher-1.1.0.jar $RDECK_BASE
   

5. Change directory and run the jar.

   cd $RDECK_BASE    
   java -jar rundeck-launcher-1.1.0.jar
   

6. Wait for the Started message.

   2010-11-19 13:35:51.127::INFO:  Started SocketConnector@0.0.0.0:4440
   

7. Update your shell environment

   PATH=$PATH:$RDECK_BASE/tools/bin
   MANPATH=$MANPATH:$RDECK_BASE/docs/man
   

If you get an error message that resembles the one below, you probably are using an unupported Java version.

Exception in thread "main" java.lang.UnsupportedClassVersionError: Bad version number in .class file

See the startup and shutdown section for instructions on using the rundeckd shell tool to manage the rundeck launcher process.

2.3.1 Logins

RunDeck supports a number of user directory configurations. By default, the installation uses a file based directory, but connectivity to LDAP is also available. See Managing logins in the Administration chapter.

The RunDeck installation process will have defined a set of temporary logins useful during the getting started phase.

• user: Has access to run commands and jobs but unable to modify job definitions. Password: "user"
• admin: Belongs to the "admin" group and is automatically granted the "admin" and "user" role privileges. Password: "admin"

2.3.2 Group membership

If you installed RunDeck using the RPM installation method, it will have created a unix group called "rundeck".

$ groups rundeck
rundeck : rundeck

It also made several log files writable to members of the "rundeck" group.

$ ls -l /var/log/rundeck/command.log
-rw-rw-r-- 1 rundeck rundeck 588 Dec  2 11:24 /var/log/rundeck/command.log

If you want to use the RunDeck shell tools, be sure to add that group to the necessary user accounts.

RunDeck shell tool users that do not belong to group, rundeck, will get error messages like so:

$ rd-jobs
log4j:ERROR setFile(null,true) call failed. java.io.FileNotFoundException: /var/log/rundeck/command.log (Permission denied)

Consult the usermod command to modify a user account.

3.1.1 Graphical Console

To get started, go to the URL for your RunDeck server. Login to the web app with the credentials defined by the RunDeck user directory configuration.

3.1.1.1 Navigation

The RunDeck page header contains global navigation control to move between tabbed pages: Run, Jobs and History. It also has links to logout, view your user profile and a link to this online help.

Top navigation bar

Run

The Run page is used to execute ad hoc commands. It displays filtered Node resources configured in your Project resource model. A filter control can be used to limit the listing to just the Node resources matching the filter criteria.

Jobs

From the Jobs page, one can list, create and run Jobs. A configurable filter allows a user to limit the Job listing to those Jobs matching the filtering criteria. These filter settings can be saved to a Users profile. Only authorized jobs will be visible.

History

From the History page, one can view currently executing commands in the "Now Running" area or browse execution history. The execution history can be filtered based on user selected parameters. Once the filter has been set, the matching history is displayed. The current filter settings also configure an RSS link, found in the top right of the page.

Project menu

The top navigation bar contains a menu to select the desired project. If only one project exists, the menu will automatically be defaulted.

Admin

If your login belongs to the "admin" group and therefore granted "admin" privileges, a wrench icon will be displayed next to your login name. This page allows the admin to view group memberships for all users, as well as, edit their profile data.

User profile

Shows a page showing group memberships.

Logout

Pressing this link ends the login session and will require a subsequent login.

Help

Opens a page to the online help system.

3.1.1.2 Now running

The "Now running" section appears at the top of the Run and Jobs pages and provides a view into the execution queue. Any currently executing ad hoc command or Job will be listed and include information like the name of the job, when it started, who ran it, and a link to the execution output.

Now running

Jobs that have been run before also have a progress bar approximating duration.

3.1.2 Shell Tools

RunDeck includes a number of shell tools to dispatch commands, load and run Job definitions and interact with the dispatcher queue. These command tools are an alternative to functions accessible in the graphical console.

dispatch

Execute ad hoc commands and scripts

rd-queue

Query the dispatcher for currently running Jobs and possibly kill them

rd-jobs

List defined jobs as well as load them from text file definitions

run

Invoke the execution of a stored Job

rd-project

Setup a new RunDeck project

rd-setup

(Re-)configure an instance of RunDeck

Consult the online manual pages for options and usage information.

3.2.1 Resource model

The initial resource model generated during project setup will contain information just about the RunDeck server host and is useful just for running local commands on the RunDeck server. You can browse the project resource model by going to the "Run" page.

In the shell, you can list the Node resources in a resource model using the shell tool, dispatch. Specify project name using the -p project option.

Here the dispatch command lists the registered server for the "examples" project after the project setup. The -v gives a verbose listing that includes more detail:

$ dispatch -p examples -v   
 strongbad:
    hostname: strongbad
    osArch: x86_64
    osFamily: unix
    osName: Mac OS X
    osVersion: 10.6.2
    tags: ''
   ---- Attributes ----

Node resources have standard properties, such as "hostname" but these can be extended via attributes. One of the more useful properties is the "tags" property. A tag is a text label that you give to the Node, perhaps denoting a classification, a role the node plays in the environment, or group membership. Multiple tags can be defined for a given node.

The output above shows the "strongbad" node currently has an empty tags property: tags: ''.

It is important to start thinking about node tagging for the nodes you manage because you will use them later when specifying filtering options to drive distributed command dispatch.

Each Project has a configuration file called project.properties, located at this path: $RDECK_BASE/projects/project/etc/project.properties.

This configuration file contains two important properties for accessing and storing resource model data:

• project.resources.file: File path to store resource model data (required).
• project.resources.url: URL to an external resource model provider (optional)

You can configure RunDeck to retrieve and store resource model data from any source, so long as it meets the RunDeck resource model document requirement. Set the project.resource.url to the resource model provider of your choice.

RunDeck reads the XML document retrieved from the ${project.resources.url} site and stores it in the path defined by ${project.resources.file}.

Here's the XML document stored for the "examples" project that corresponds to the output printed by the dispatch -v shown earlier:

<project>
    <node name="strongbad" type="Node" 
      description="the RunDeck server host" tags="" 
      hostname="strongbad" 
      osArch="x86_64" osFamily="unix" osName="Mac OS X" osVersion="10.6.2"
      username="alexh" 
      editUrl="" remoteUrl=""/>
</project>

You'll notice the root node is called project and there is a single node descriptor for "strongbad". The node tag has a number of required and optional attributes. Additional node descriptors can be added by defining new node elements inside the project tag.

The strongbad host does not have any tags defined for it. One or more tags can be defined. Use comma for the delimiter (e.g, tags="tag1,tag2").

Here's an example of a node called "homestar" with just the required attributes:

    <node name="homestar" type="Node" 
      hostname="192.168.1.02" 
      username="alexh" />

The hostname and username values are used for the SSH connection while the name and type are used to define Node identity in the resource model. It is possible to overload the hostname value to include port information (eg, hostname="somehost:2022"). This is useful if your run SSH on a different port.

Chances are you maintain information about your hosts within another tool, perhaps Chef, Puppet, Nagios, Amazon EC2, RightScale or even an in-house database. One of these tools might be considered the authority of knowledge about the nodes deployed in your network. Therefore, it is best to create an interface to the authorative tool and expose it as RunDeck resource model provider. This can be done as a simple CGI script that does a transformation from the tool's format to the one RunDeck understands.

Of course, a rudimentary alternative is to maintain this information as an XML document, storing it in a source repository that is periodically exported to Rundeck. This method could be practical if your host infrastructure infrequently changes.

The resource-v10(5) manual contains reference information about the RunDeck resources document content and structure.

Check the RunDeck web site for resource model providers. If you are interested in creating your own, see the Resource model provider section in the Integration with External Data Providers chapter.

3.3.1 Dispatcher options

Dispatcher execution can be controlled by various types of options.

Execution control

Command execution can be controlled in various ways. Concurrency is controlled through threadcount. Execution can continue if specified to keepgoing

Include and exclude patterns

Filtering options specify include and exclude patterns to determine which nodes from the project resource model to distribute commands.

Keywords

Keywords are used within they include and exclude patterns. The "tags" keywords additionally can use a boolean operator to combine logical ORs and ANDs.

Option combination

All keywords can be combined by specifying the include and exclude options multiple times on the command line.

One can experiment querying the resource model in the graphical console or with the dispatch tool.

3.3.1.1 Filtering nodes graphically

A project's Node resources are displayed in the Run page. Use the project menu in the navigation bar to change to the desired project. After choosing a project, the server node will be filtered by default.

Nodes can be filtered using include and exclude patterns by using the Filter form. The form can be opened by pressing the "Filter" button. Press the triangular disclosure icon to display the form.

Resource filter link

When the form opens, you will see it divided into an Include section where simple include expressions can be set, as well as, an "Extended Filters..." link where exclude expressions can be made.

Resource filter form

After filling out the filter form, press "Filter" to generate a new listing. Pressing "Clear" resets the form.

The Include and Exclude filters allow for filtering nodes based on the following keywords: Name, Tags, Hostname, OS Name, OS Family, OS Architecture, OS Version and Type.

Regular expressions can be used for any of the keywords. The .* pattern will match any text.

If more than 20 nodes match the filter, the UI will page the results.

dispatch -p examples -I os-name=Linux

dispatch -p examples -I os-name=Linux -X "web.*"

dispatch -p examples -I tags=web+prod

dispatch -p examples -I tags=web -K -C 10 -- sudo apachectl restart 

3.3.2 Ad-hoc commands

Typically, an ad-hoc command is a shell script or system executable that you run at an interactive terminal. Ad-hoc commands can be executed via the dispatch shell command or a graphical shell.

$ dispatch -I os-family=unix -- uptime
Succeeded queueing Workflow execution: Workflow:(threadcount:1){ [command( exec: uptime)] }
Queued job ID: 7 <http://strongbad:4440/execution/follow/7>

$ dispatch -I os-family=unix  --noqueue -- uptime
[ctier@centos54 dispatch][INFO]  10:34:54 up 46 min,  2 users,  load average: 0.00, 0.00, 0.00
[alexh@strongbad dispatch][INFO] 10:34  up 2 days, 18:51, 2 users, load averages: 0.55 0.80 0.75
[examples@ubuntu dispatch][INFO]  10:35:01 up 2 days, 18:40,  2 users,  load average: 0.00, 0.01, 0.00

$ dispatch -I os-family=unix --noqueue -- whoami
[ctier@centos54 dispatch][INFO] ctier
[alexh@strongbad dispatch][INFO] alexh
[examples@ubuntu dispatch][INFO] examples

#!/bin/sh
echo "info script"
echo uptime=`uptime`
echo whoami=`whoami`
echo uname=`uname -a`

$ dispatch -I os-family=unix -s info.sh

3.3.2.2 Graphical command shell execution

The RunDeck graphical console also provides the ability to execute ad-hoc commands to a set of filtered Node resources. The command prompt can accept any ad-hoc command string you might run via an SSH command or via the dispatch shell tool.

But before running any commands, you need to select the project containing the Nodes you wish to dispatch. Use the project menu to select the desired project name. After the project has been selected you will see a long horizontal textfield labeled "Command". This is the RunDeck ad hoc command prompt.

Ad hoc command prompt

To use the command prompt, type the desired ad-hoc command string into the textfield and press the "Run" button. The command will be dispatched to all the Node resources currently listed below the command prompt tool bar. The command prompt also becomes disabled until the execution completes. Output from the command execution will be shown below (see output).

Ad hoc execution output

You will also notice the ad hoc execution listed in the "Now running" part of the page, located above the command prompt. All running executions are listed there. Each running execution is listed, showing the start time, the user running it, and a link to follow execution output on a separate page.

Now running ad hoc command

At the bottom of the page, you will see a "History" section containing all executions in the selected project for the last 24 hours. After the execution completes, a new event will be added to the history. A yellow highlight indicates when the command leaves the Now running section and enters the history table.

Run history

History is organized in summary form using a table layout. The "Summary" column shows the command or script executed. The "Node Failure Count" contains the number of nodes where an error in execution occurred. If no errors occurred, "ok" will be displayed. The "User" and "Time" columns show the user that executed the command and when.

3.3.2.2.1 Following execution output

Ad hoc command execution output is displayed below the command prompt.

This page section provides several views to read the output using different formats.

Tail Output

Displays output messages from the command execution as if you were running the Unix tail -f command on the output log file. By default, only the last 20 lines of output is displayed but this can be expanded or reduced by pressing the "-" or "+" buttons. You can also type in an exact number into the textfield.

Annotated

The annotated mode displays the output messages in the order they are received but labels the each line with the Node from which the message originated. Through its additional controls each Node context can be expanded to show the output it produced, or completely collapsed to hide the textual detail.

Compact

Output messages are sorted into Node specific sections and are not interlaced. By default, the messages are collapsed but can be revealed by pressing the disclosure icon to the right.

3.3.2.2.1.1 Separate exeuction follow page

Sometimes it is useful to have a page where just the execution output is displayed separately. One purpose is to share a link to others interested in following the output messages. Click the "output >>" link in the "Now running" section to go to the execution follow page.

Also, notice the URL in the location bar of your browser. This URL can be shared to others interested in the progress of execution. The URL contains the execution ID (EID) and has a form like:

 http://rundeckserver/execution/follow/{EID}

After execution completes, the command will have a status:

• Successful: No errors occurred during execution of the command across the filtered Node set
• Failed: One or more errors occurred. A list of Nodes that incurred an error is displayed. The page will also contain a link "Retry Failed Nodes..." in case you would like to retry the command.

You can download the entire output as a text file from this page. Press the "Download" link to retrieve the file to your desk top.

3.3.3 Controlling command execution

Parallel execution is managed using thread count via "-C" option. The "-C" option specifies the number of execution threads. Here's an example that runs the uptime command across the Linux hosts with two threads:

dispatch -I os-name=Linux -C 2 -- uptime

The keepgoing and retry flags control when to exit incase an error occurs. Use "-K/-R" flags. Here's an example script that checks if the host has port 4440 in the listening state. If it does not, it will exit with code 1.

#!/bin/sh
netstat -an | grep 4440 | grep -q LISTEN
if [ "$?" != 0 ]; then
echo "not listening on 4440"
exit 1;
fi
echo  listening port=4440, host=`hostname`;

Commands or scripts that exit with a non-zero exit code will cause the dispatch to fail unless the keepgoing flag is set.

$ dispatch -I os-family=unix -s /tmp/listening.sh --noqueue
[alexh@strongbad dispatch][INFO] Connecting to centos54:22
[alexh@strongbad dispatch][INFO] done.
[ctier@centos54 dispatch][INFO] not listening on 4440
error: Remote command failed with exit status 1

The script failed on centos54 and caused dispatch to error out immediately.

Running the command again, but this time with the "-K" keepgoing flag will cause dispatch to continue and print on which nodes the script failed:

$ dispatch  --noqueue -K -I tags=web -s /tmp/listening.sh
[alexh@strongbad dispatch][INFO] Connecting to centos54:22
[alexh@strongbad dispatch][INFO] done.
[ctier@centos54 dispatch][INFO] not listening on 4440
[ctier@centos54 dispatch][ERROR] Failed execution for node: centos54: Remote command failed with exit status 1
[alexh@strongbad dispatch][INFO] listening port=4440, host=strongbad
[alexh@strongbad dispatch][INFO] Connecting to 172.16.167.211:22
[alexh@strongbad dispatch][INFO] done.
[examples@ubuntu dispatch][INFO] not listening on 4440
[examples@ubuntu dispatch][ERROR] Failed execution for node: ubuntu: Remote command failed with exit status 1
error: Execution failed on the following 2 nodes: [centos54, ubuntu]
error: Execute this command to retry on the failed nodes:
    dispatch -K -s /tmp/listening.sh -p examples -I
    name=centos54,ubuntu

3.3.4 Queuing commands to RunDeck

By default, commands or scripts executed on the command line by dispatch are queued as temporary jobs in RunDeck. The dispatch command is equivalent to a "Run and Forget" action in the graphical console.

The script below is a long running check that will conduct a check periodically waiting a set time between each pass. The script can be run with or without arguments as the parameters are defaulted inside the script:

$ cat ~/bin/checkagain.sh 
#!/bin/bash
iterations=$1 secs=$2 port=$3
echo "port ${port:=4440} will be checked ${iterations:=30} times waiting ${secs:=5}s between each iteration" 
i=0
while [ $i -lt ${iterations} ]; do
  echo "iteration: #${i}"
  netstat -an | grep $port | grep LISTEN && exit 0
  echo ----
  sleep ${secs}
  i=$(($i+1))
done
echo "Not listening on $port after $i checks" ; exit 1

Running dispatch causes the execution to queue in RunDeck and controlled as temporary Job. The -I centos54 limits execution to just the "centos54" node:

$ dispatch -I centos54 -s ~/bin/checkagain.sh 
Succeeded queueing workflow: Workflow:(threadcount:1){ [command( scriptfile: /Users/alexh/bin/checkagain.sh)] }
Queued job ID: 5 <http://strongbad:4440/execution/follow/4>

To pass arguments to the script pass them after the "--" (double dash):

$ iters=5 secs=60 port=4440
$ dispatch -I centos54 -s ~/bin/checkagain.sh -- $iters $secs $ports

3.3.5 Tracking execution

Queued ad-hoc command and temporary or saved Job executions can be tracked from the "Run" page in the "Now Running" area at the top of the page.

Execution can also be tracked using the rd-queue shell tool.

$ rd-queue
Queue: 1 items
[5] workflow: Workflow:(threadcount:1){[command( scriptfile: /Users/alexh/bin/checkagain.sh)]} <http://strongbad:4440/execution/follow/5>

Each job in the execution queue has an execution ID. The example above shows one item with the ID, 5.

Running jobs can also be killed via rd-queue kill. Specify execution ID using the "-e" option:

$ rd-queue kill -e 5
rd-queue kill: success. [5] Job status: killed

3.4.1 Filtering event history

By default, the History page will list history for the last day's executions. The page contains a filter control that can be used to expand or limit the executions.

The filter form contains a number of fields to limit search:

• Within: Time range. Choices include 1 day, 1 week, 1 month or other (given a start after/before to ended after/before).
• Name: Job title name.
• Project: Project name. This may be set if the project menu was used.
• User: User initiating action.
• Summary: Message text.
• Result: Success or failure status.

History filter form

After filling the form pressing the "Filter" button, the page will display events matching the search.

Filters can be saved to a menu that makes repeating searches more convenient. Click the "save this filter..." link to save the filter configuration.

3.4.2 Event view

History for each execution contains the command(s) executed, dispatcher options, success status and a link to a file containing all the output messages.

Event view

If any errors occurred, the "Node Failure Count" column will show the number of nodes in red text. A bar chart indicates the percent failed.

Event view

3.4.3 RSS link

An RSS icon provides a link to an RSS view of the events that match the current filtering critera.

RSS link

3.5.1 Saving filters

Each of the filter controls provides the means to save the current filter configuration. Press the "save this filter..." link to give it a name. Each saved filter is added to a menu you can access the next time you want that filter configuration.

3.5.2 Auto-Completion

If you use the Bash shell, RunDeck comes with a nice auto-completion script you can enable. Add this to your .bashrc file:

source $RDECK_BASE/etc/bash_completion.bash

Press the Tab key when you're writing a dispatch command, and it should return a set of suggestions for you to pick from:

$ dispatch <tab><tab>

4.2.1 Filtering Jobs

The Job page lets you search for Jobs using the Filter option.

Click the "Filter" link to show the filter options:

Job filter form

This will show the Filter fields. Enter a value in any of the filter fields:

• Job Name: the name of the job
• Group: the name of the job group
• Description: Job description text

You can type a substring or a regular expression in any of these fields.

After pressing the "Filter" button, the Job list will be filtered to include only the matching jobs.

Job filtered list

To refine the filter, click on the blue-outlined Filter description, and change the filter fields.

To reset the filter and go back to the full job page, click the "Clear" button in the Filter fields.

4.4.1 Choose execution options

Jobs can be defined to prompt the user for options. This page contains a form presenting any of these Job options.

Some options will have default values while others may present you with a menu of choices. Some options are optional while others are required. Lastly, their might be a pattern govering what values are acceptable.

If there are any such Job options, you can change them here before proceeding with the execution.

When you are ready, press "Run Job Now". The job will enter the execution queue and you can track its execution in the Now running section.

4.4.2 Following Running Jobs

Once you have started running a Job, you can follow the Job's output in the Execution Follow page.

On the Jobs page, look in the "Now running" section and click the "output >>" link in the row with the desired Job name.

If you pressed the "run" button from the Job's detail page, your browser will already have been directed to the Execution Follow page.

4.5.1 Temporary Jobs

A temporary job is a bit like an ad-hoc command except you get more control over how the commands will execute plus the execution can be better tracked within the RunDeck webapp.

To create a temporary job, begin by logging in to the RunDeck graphical console, and press the "Jobs" tab.

1. Locate the "New Job" button in the right hand corner and press it to display the "Create New Job" form.
2. A job is defined in terms of one or more workflow steps. In the Workflows area, click the "Add a step" link.
3. Workflow steps can be one of several types. Click the "Script" workflow step type.
4. A script type can be any script that can be executed on the target hosts. Type in the "info" shell script we executed earlier using dispatch.
5. At the bottom of the form, push the "Run and Forget" button to begin execution.
6. Execution output can be followed on the subsequent page.

Temporary job form

4.5.2 Saved Jobs

Running ad hoc commands and temporary jobs are a typical part of day to day administrative work. Occasionally, ad-hoc commands become routine procedures and if were reusable, would become more valuable. These jobs could be handed off to others in the team or invoked from within other Jobs. RunDeck provides an interface to declare and save jobs, both graphically or declared with an XML file.

4.5.3 Simple saved job

For the first saved Job example, create a Job that calls the info script.

1. Like in the earlier example, begin by pressing the "New Job" button.
2. Within the new job form:
   • Select "Yes" for the "Save this job?" prompt. Pressing Yes reveals a form to define a name, group and description for the job.
   • For "Job Name", enter "info" and for the "Group", enter "adm/resources".
   • Providing a description will be come helpful to other users to understand the intent and purpose for the Job.
   • Check the box for "Dispatch to Nodes"
   • Choose the "Node Exclude Filters" and enter the name of your RunDeck server. This will cause the job to run on just the remote Nodes (eg., centos54 and ubuntu).
   • Type in and info script
   • Save the Workflow step
   • Press the "Create" button at the bottom of the page.
3. After the the job is created, the browser is directed to the Jobs page. The folder structure reflecting the group naming will show one Job.
   • Navigate through the folders buttons to the new job
4. Notice the green arrow button.
   • Press the button to run the Job.
5. Press the "Run Job Now" button to begin execution.
   • The job will be queued and executed.
6. Look in the "Now running" section.
   • Press the "output >>" link to go to the execution follow page.

5.3.1 Command step

Use the command step to call system commands. This is the default type of workflow step when creating a Job. Enter any command string you would type at the terminal on the remote hosts.

Command step type

This is similar to calling the command with dispatch:

dispatch [filter-options] -- command

5.3.2 Script step

Execute the supplied shell script content. Optionally, can pass an argument to the script specified in the lower text field.

Script step type

This is similar to calling the command with dispatch:

dispatch [filter-options] --stdin -- args <<EOF 
script content here 
EOF

5.3.3 Script file step

Executes the script file local to the sever to the filtered Node set. Arguments can be passed to the script by specifying them in the lower text field.

Script file step type

This is similar to calling the script file with dispatch:

dispatch [filter-options] -s scriptfile -- args

5.3.4 Job reference step

To call another saved Job, create a Job Reference step. Enter the name of the Job and its group.

Job step type

The Job Reference form provides a Job browser to make it easier to select from the existing set of saved Jobs. Click the "Choose A Job..." link and navigate to the desired Job.

Finally, if the Job defines Options, you can specify them in the commandline arguments text field.

This is simililar to calling the other Job with run:

run [filter-options] -j group/jobname

7.4.1 Job structure

With an idea of the restart scripts in mind, the next step is to define a job to encapsulate the restart procedure. Though the overall goal is to provide a single restart procedure, for the sake of reusability, it might be preferred to break each step of the process into separate jobs.

Using this approach the adminstrator imagines the following jobs:

• start: call the start.sh script to start the web service
• stop: call the stop.sh script to stop the web service
• Restart: calls the jobs: stop, start

Since the restart procedure is the primary focus, it is capitalized for distinction.

The extra complexity from defining a job for every individual step can pay off later, if those steps can be recombined with future jobs to serve later management needs. How far a process is decomposed into individual jobs is a judgement balancing maintenance requirements and the desire for job reuse.

7.4.2 Job grouping

Though not a requirement, it is helpful to use job groups and have a convention for naming them. A good convention assists others with a navigation scheme that helps them remember and find the desired procedure.

The administrator chooses to create a top level group named "/anvils/web/" where the web restart related jobs will be organized.

anvils/
`-- web/
    |-- Restart
    |-- start
    `-- stop

After choosing the "anvils" project users will see this grouping of jobs.

Anvils job group

7.5.1 Allowed values

An option can be defined to only allow values from a specified list. This places safe guards on how a Job can be run by limiting choices to those the scripts can safely handle.

The administrator takes advantage of this by limiting the "method" option values to just "normal" or "kill" choices.

The screenshot below contains the Option edit form for the "method" option. The form includes elements to define description and default value, as well as, Allowed Values and Restrictions.

Option editor for method

Allowed values can be specified as a comma separated list as seen above but can also be requested from an external source using a "remote URL".

Option choices can be controlled using the "Enforced from values" restriction. When set "true", the RunDeck UI will only present a popup menu. If set "false", a text field will also be presented. Use the "Match Regular Expression" form to validate the input option.

Here's a screenshot of how RunDeck will display the menu choices:

Option menu for method

7.5.2 Script access to option data

Option values can be passed to scripts as an argument or referenced inside the script using a named token. For example, the value for the "method" option selection can be accessed in one of several ways:

Value referenced as an environment variable:

• Bash: $CT_OPTION_METHOD

Value passed in the argument vector to the executed script or command via the scriptargs tag:

• Commandline Arguments: ${option.method}

Value represented as a named token inside the script and replaced before execution:

• Script Content: @option.method@

8.1.1 RPM

The RPM installation includes the placement of the boot control script that will automatically start RunDeck when the system boots.

The script is located here: /etc/init.d/rundeckd

Startup

/etc/init.d/rundeckd start

Shutdown

/etc/initd./rundeckd stop

8.1.2 Launcher

The Launcher installation generates the script into the RDECK_BASE directory.

The script is located here: $RDECK_BASE/server/sbin/rundeckd.

Startup

$RDECK_BASE/server/sbin/rundeckd start

Shutdown

$RDECK_BASE/server/sbin/rundeckd stop

You may choose to incorporate this script into your server's operating system specific boot process.

8.2.1 Configuration layout

Configuration file layout differs between the RPM and Launcher installation methods. See RPM layout and Launcher layout for details.

/etc/rundeck
|-- admin.aclpolicy
|-- framework.properties
|-- log4j.properties
|-- profile
|-- project.properties
|-- jaas-loginmodule.conf
|-- log4j.properties
|-- realm.properties
|-- rundeck-config.properties
`-- ssl
    |-- ssl.properties
    |-- keystore (not packaged)
    `-- truststore (not packaged)

$RDECK_BASE/etc
|-- admin.aclpolicy
|-- framework.properties
|-- log4j.properties
|-- profile
`-- project.properties
$RDECK_BASE/server/config
|-- jaas-loginmodule.conf
|-- realm.properties
`-- rundeck-config.properties

8.2.2 Configuration files

Configuration is specified in a number of standard RunDeck configuration files generated during the installation process.

See the Configuration layout section for where these files reside for RPM and Launcher installations.

The purpose of each configuration file is described in its own section.

RDpropertyfilelogin {
  org.mortbay.jetty.plus.jaas.spi.PropertyFileLoginModule required
  debug="true"
  file="/etc/rundeck/realm.properties";
};

8.5.1 SSH configuration requirements

• The SSH configuration requires that the RunDeck server machine can ssh commands to the client machines.
• SSH is assumed to be installed and configured appropriately to allow this access.
  
• No passphrase should be set.
• SSH should not prompt for a password. There are many resources available on how to configure ssh to use public key authentication instead of passwords such as: Password-less logins with OpenSSH or How-To: Password-less SSH

8.5.2 SSH key generation

• The RunDeck installation can be configured to use RSA or DSA type keys.

Here's an example of SSH RSA key generation on a Linux system:

$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/demo/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/demo/.ssh/id_rsa.
Your public key has been saved in /home/demo/.ssh/id_rsa.pub.
The key fingerprint is:
a7:31:01:ca:f0:62:42:9d:ab:c8:b7:9c:d1:80:76:c6 demo@ubuntu
The key's randomart image is:
+--[ RSA 2048]----+
| .o . .          |
|.  * . .         |
|. = =   .        |
| = E     .       |
|+ + o   S .      |
|.o o .   =       |
|  o +   .        |
|   +             |
|                 |
+-----------------+

8.5.3 Configuring remote machine for SSH

To be able to directly ssh to remote machines, the SSH public key of the client should be shared to the remote machine.

Follow the steps given below to enable ssh to remote machines.

The ssh public key should be copied to the authorized_keys file of the remote machine. The public key will be available in ~/.ssh/id_rsa.pub file.

The authorized_keys file should be created in the .ssh directory of the remote machine.

The file permission of the authorized key should be read/write for the user and nothing for group and others. To do this check the permission and change it as shown below.

$ cd ~/.ssh
$ ls -la
-rw-r--r--   1 raj  staff     0 Nov 22 18:14 authorized_keys

$ chmod 600 authorized_keys 
$ ls -la
-rw-------   1 raj  staff     0 Nov 22 18:14 authorized_keys

The permission for the .ssh directory of the remote machine should be read/write/execute for the user and nothing for the group and others. To do this, check the permission and change it as shown below.

$ ls -la
drwxr-xr-x   2 raj  staff    68 Nov 22 18:19 .ssh
$ chmod 700 .ssh
$ ls -la
drwx------   2 raj  staff    68 Nov 22 18:19 .ssh

If you are running RunDeck on Windows, we heartily recommend using Cygwin on Windows as it includes SSH and a number of Unix-like tools that are useful when you work in a command line environment.

8.6.1 realm.properties

These instructions explain how to manage user credentials for RunDeck in the realm.properties file.

The default RunDeck webapp handles user authentication via its container, which in turn is configured to pull its user authentication from the $RDECK_BASE/server/config/realm.properties file. This file is created at the time that you install the server.

Assuming it wasn't modified, your realm.properties file will probably look something like this:

#
# This file defines users passwords and roles for a HashUserRealm
#
# The format is
#  <username>: <password>[,<rolename> ...]
#
# Passwords may be clear text, obfuscated or checksummed.  
#
# This sets the default user accounts for the RunDeck apps
#
admin:admin,user,admin
user:user,user

Adding additional users

You may wish to have additional users with various privileges rather than giving out role accounts to groups. You may also want to avoid having the passwords in plaintext within the configuration file.

To accomplish this, you'll need a properly hashed or encrypted password to use in the config. On the RunDeck server, move into the directory that contains your installation and pass the username and password to the Password utility. In this example, we'll setup a new user named "jsmith", with a password of "mypass":

$ cd $RDECK_BASE
$ java -cp server/lib/jetty-6.1.21.jar:server/lib/jetty-util-6.1.21.jar org.mortbay.jetty.security.Password jsmith mypass
OBF:1xfd1zt11uha1ugg1zsp1xfp
MD5:a029d0df84eb5549c641e04a9ef389e5
CRYPT:jsnDAc2Xk4W4o

Then add this to the realm.properties file with a line like so:

jsmith: MD5:a029d0df84eb5549c641e04a9ef389e5,user,admin

Then restart RunDeck to ensure it picks up the change and you're done.

8.6.2 LDAP and Active Directory

note Because the underlying security mechanism relies on JAAS, you are free to use what ever JAAS provider you feel is suitable for your environment.

1. Setup the LDAP login module configuration file

Create a jaas-activedirectory.conf file in the same directory as the jaas-loginmodule.conf file.

• RPM install: /etc/runduck/
• Launcher install: $RDECK_BASE/server/config

activedirectory {
    com.dtolabs.rundeck.jetty.jaas.JettyCachingLdapLoginModule required
    debug="true"
    contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
    providerUrl="ldap://localhost:389"
    bindDn="cn=Manager,dc=rundeck,dc=com"
    bindPassword="secret"
    authenticationMethod="simple"
    forceBindingLogin="true"
    userBaseDn="ou=users,dc=rundeck,dc=com"
    userRdnAttribute="cn"
    userIdAttribute="cn"
    userPasswordAttribute="unicodePwd"
    userObjectClass="user"
    roleBaseDn="ou=roles,dc=rundeck,dc=com"
    roleNameAttribute="cn"
    roleMemberAttribute="member"
    roleObjectClass="group";
    cacheDurationMillis="300000"
    reportStatistics="true";
    };

2. Update the profile

3. RPM: /etc/rundeck/profile

4. Launcher: $RDECK_BASE/etc/profile

Append the RDECK_JVM variable adding the java.security.auth.login.config and loginmodule.name properties to use the jaas-loginmodule.conf and activedirectory:

export RDECK_JVM="$RDECK_JVM -Djava.security.auth.login.config=/etc/rundeck/jaas-loginmodule.conf \
    -Dloginmodule.name=RDpropertyfilelogin \

to

export RDECK_JVM="-Djava.security.auth.login.config=/etc/rundeck/jaas-activedirectory.conf \
    -Dloginmodule.name=activedirectory \

3. Restart rundeckd

4. RPM install: sudo /etc/init.d/rundeckd restart

5. Launcher install: $RDECK_BASE/server/sbin/rundeckd restart

6. Attempt to login

If everything was configured correctly, you will be able to access RunDeck using your credentials. If something did not go smoothly, look at /var/log/rundeck/service.log for stack traces that may indicate what is wrong.

$ openssl s_client -showcerts -connect paypal.com:443
CONNECTED(00000003)
depth=1 C = US, O = "VeriSign, Inc.", OU = VeriSign Trust Network, OU = Terms of use at https://www.verisign.com/rpa (c)09, CN = VeriSign Class 3 Secure Server CA - G2
verify error:num=20:unable to get local issuer certificate
verify return:0
---
Certificate chain
 0 s:/C=US/ST=California/L=San Jose/O=PayPal, Inc./OU=Information Systems/CN=paypal.com
   i:/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=Terms of use at https://www.verisign.com/rpa (c)09/CN=VeriSign Class 3 Secure Server CA - G2
-----BEGIN CERTIFICATE-----
MIIFDjCCA/agAwIBAgIQL0NdM6l74HplIwrcygDcCTANBgkqhkiG9w0BAQUFADCB
tTELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL
ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2Ug
YXQgaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwOTEvMC0GA1UEAxMm
VmVyaVNpZ24gQ2xhc3MgMyBTZWN1cmUgU2VydmVyIENBIC0gRzIwHhcNMTAwNTAz
MDAwMDAwWhcNMTIwNjExMjM1OTU5WjB/MQswCQYDVQQGEwJVUzETMBEGA1UECBMK
Q2FsaWZvcm5pYTERMA8GA1UEBxQIU2FuIEpvc2UxFTATBgNVBAoUDFBheVBhbCwg
SW5jLjEcMBoGA1UECxQTSW5mb3JtYXRpb24gU3lzdGVtczETMBEGA1UEAxQKcGF5
cGFsLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEArlvu+86iVb4RXdX+
8MjmGynNSl+Hu2/ZJ7nU1sj5O2jASWwFH7PFUv10qlRtL+gi3Rjw+zFN958iUetz
ef4CxQYf52PA7Uj9YlFEzLz7f8UDotu4WNLM3QGbLrqS28pPb2qKyyOQDvwNpI1c
Jt4JDa0ofVnCdICZEnf+cJB121MCAwEAAaOCAdEwggHNMAkGA1UdEwQCMAAwCwYD
VR0PBAQDAgWgMEUGA1UdHwQ+MDwwOqA4oDaGNGh0dHA6Ly9TVlJTZWN1cmUtRzIt
Y3JsLnZlcmlzaWduLmNvbS9TVlJTZWN1cmVHMi5jcmwwRAYDVR0gBD0wOzA5Bgtg
hkgBhvhFAQcXAzAqMCgGCCsGAQUFBwIBFhxodHRwczovL3d3dy52ZXJpc2lnbi5j
b20vcnBhMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAfBgNVHSMEGDAW
gBSl7wsRzsBBA6NKZZBIshzgVy19RzB2BggrBgEFBQcBAQRqMGgwJAYIKwYBBQUH
MAGGGGh0dHA6Ly9vY3NwLnZlcmlzaWduLmNvbTBABggrBgEFBQcwAoY0aHR0cDov
L1NWUlNlY3VyZS1HMi1haWEudmVyaXNpZ24uY29tL1NWUlNlY3VyZUcyLmNlcjBu
BggrBgEFBQcBDARiMGChXqBcMFowWDBWFglpbWFnZS9naWYwITAfMAcGBSsOAwIa
BBRLa7kolgYMu9BSOJsprEsHiyEFGDAmFiRodHRwOi8vbG9nby52ZXJpc2lnbi5j
b20vdnNsb2dvMS5naWYwDQYJKoZIhvcNAQEFBQADggEBADbOGDkzZy22y+fW4OR7
wkx+1E3BxnRMZYx89OOykzTEUt2UV5DVuccUbqxTxg9/4pKMYJLywYn9UIOPHpwx
fbvMQNpdqV3JSuGMTwpROrMvC3bT13aCxxDnozeCjd/lH74m6G5ef2EUd3m5Y+iC
fMPo2NMrVyQYOCtpJurh9Tre1gQFHUYAXw8ty0YxfMoR/7FwYbd4spiZJwL2Mvfn
9gn24dWuKY7JaFutomwOM78rGzBDZZ/spEx9rcNa3OuVHcqBamnnXQZlZJilj4LE
buMBx8ti5Oqy4z1u1vzA8HalseiZerqFtBGOIakXdto8qLnwYEHQvVa/ih5iTsi3
Ja8=
-----END CERTIFICATE-----
 1 s:/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=Terms of use at https://www.verisign.com/rpa (c)09/CN=VeriSign Class 3 Secure Server CA - G2
   i:/C=US/O=VeriSign, Inc./OU=Class 3 Public Primary Certification Authority - G2/OU=(c) 1998 VeriSign, Inc. - For authorized use only/OU=VeriSign Trust Network
-----BEGIN CERTIFICATE-----
MIIGLDCCBZWgAwIBAgIQbk/6s8XmacTRZ8mSq+hYxDANBgkqhkiG9w0BAQUFADCB
wTELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMTwwOgYDVQQL
EzNDbGFzcyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0aG9yaXR5
IC0gRzIxOjA4BgNVBAsTMShjKSAxOTk4IFZlcmlTaWduLCBJbmMuIC0gRm9yIGF1
dGhvcml6ZWQgdXNlIG9ubHkxHzAdBgNVBAsTFlZlcmlTaWduIFRydXN0IE5ldHdv
cmswHhcNMDkwMzI1MDAwMDAwWhcNMTkwMzI0MjM1OTU5WjCBtTELMAkGA1UEBhMC
VVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQLExZWZXJpU2lnbiBU
cnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2UgYXQgaHR0cHM6Ly93
d3cudmVyaXNpZ24uY29tL3JwYSAoYykwOTEvMC0GA1UEAxMmVmVyaVNpZ24gQ2xh
c3MgMyBTZWN1cmUgU2VydmVyIENBIC0gRzIwggEiMA0GCSqGSIb3DQEBAQUAA4IB
DwAwggEKAoIBAQDUVo9XOzcopkBj0pXVBXTatRlqltZxVy/iwDSMoJWzjOE3JPMu
7UNFBY6J1/raSrX4Po1Ox/lJUEU3QJ90qqBRVWHxYISJpZ6AjS+wIapFgsTPtBR/
RxUgKIKwaBLArlwH1/ZZzMtiVlxNSf8miKtUUTovStoOmOKJcrn892g8xB85essX
gfMMrQ/cYWIbEAsEHikYcV5iy0PevjG6cQIZTiapUdqMZGkD3pz9ff17Ybz8hHyI
XLTDe+1fK0YS8f0AAZqLW+mjBS6PLlve8xt4+GaRCMBeztWwNsrUqHugffkwer/4
3RlRKyC6/qfPoU6wZ/WAqiuDLtKOVImOHikLAgMBAAGjggKpMIICpTA0BggrBgEF
BQcBAQQoMCYwJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3NwLnZlcmlzaWduLmNvbTAS
BgNVHRMBAf8ECDAGAQH/AgEAMHAGA1UdIARpMGcwZQYLYIZIAYb4RQEHFwMwVjAo
BggrBgEFBQcCARYcaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL2NwczAqBggrBgEF
BQcCAjAeGhxodHRwczovL3d3dy52ZXJpc2lnbi5jb20vcnBhMDQGA1UdHwQtMCsw
KaAnoCWGI2h0dHA6Ly9jcmwudmVyaXNpZ24uY29tL3BjYTMtZzIuY3JsMA4GA1Ud
DwEB/wQEAwIBBjBtBggrBgEFBQcBDARhMF+hXaBbMFkwVzBVFglpbWFnZS9naWYw
ITAfMAcGBSsOAwIaBBSP5dMahqyNjmvDz4Bq1EgYLHsZLjAlFiNodHRwOi8vbG9n
by52ZXJpc2lnbi5jb20vdnNsb2dvLmdpZjApBgNVHREEIjAgpB4wHDEaMBgGA1UE
AxMRQ2xhc3MzQ0EyMDQ4LTEtNTIwHQYDVR0OBBYEFKXvCxHOwEEDo0plkEiyHOBX
LX1HMIHnBgNVHSMEgd8wgdyhgcekgcQwgcExCzAJBgNVBAYTAlVTMRcwFQYDVQQK
Ew5WZXJpU2lnbiwgSW5jLjE8MDoGA1UECxMzQ2xhc3MgMyBQdWJsaWMgUHJpbWFy
eSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eSAtIEcyMTowOAYDVQQLEzEoYykgMTk5
OCBWZXJpU2lnbiwgSW5jLiAtIEZvciBhdXRob3JpemVkIHVzZSBvbmx5MR8wHQYD
VQQLExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrghB92f4Hz6getxB5Z/uniTTGMA0G
CSqGSIb3DQEBBQUAA4GBAGN0Lz1Tqi+X7CYRZhr+8d5BJxnSf9jBHPniOFY6H5Cu
OcUgdav4bC1nHynCIdcUiGNLsJsnY5H48KMBJLb7j+M9AgtvVP7UzNvWhb98lR5e
YhHB2QmcQrmy1KotmDojYMyimvFu6M+O0Ro8XhnF15s1sAIjJOUFuNWI4+D6ufRf
-----END CERTIFICATE-----
---
Server certificate
subject=/C=US/ST=California/L=San Jose/O=PayPal, Inc./OU=Information Systems/CN=paypal.com
issuer=/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=Terms of use at https://www.verisign.com/rpa (c)09/CN=VeriSign Class 3 Secure Server CA - G2
---
No client certificate CA names sent
---
SSL handshake has read 3039 bytes and written 401 bytes
---
New, TLSv1/SSLv3, Cipher is DES-CBC3-SHA
Server public key is 1024 bit
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
SSL-Session:
    Protocol  : TLSv1
    Cipher    : DES-CBC3-SHA
    Session-ID: A8AAA4F22E9A4B3F12F76303464643525178846D96CA0BC0B81F35368BF55B89
    Session-ID-ctx: 
    Master-Key: 9F767B91FC2450E291CBB21E3438CA9A73FE8D5B825AD98F821F5EB912C088DFB66FCBF2D53591E2D1ED77E9B6A22504
    Key-Arg   : None
    PSK identity: None
    PSK identity hint: None
    Start Time: 1295242116
    Timeout   : 300 (sec)
    Verify return code: 20 (unable to get local issuer certificate)
---
^C

keytool -import -alias CompanyAD -file AD.cert -keystore /etc/rundeck/ssl/truststore -storepass adminadmin 

keytool -import -alias CompanyAD -file AD.cert -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit 

keytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit

 providerUrl=ldaps://ad1 ldaps://ad2  

8.7.1 Access control policy

Access to running or modifying Jobs is managed in an access control policy defined using the aclpolicy XML document (aclpolicy-v10(5)). This file contains a number of policy elements that describe what user group is allowed to perform which actions.

Policies can be organized into more than one file to help organize access by group or pattern of use. The normal RunDeck install will have generated a policy for the "admin" group. Not all users will need to be given "admin" access level to control and modify all Jobs. More typically, a group of users will be given access to just a subset of Jobs.

File listing: admin.aclpolicy example

<policies>
  <policy description="Administrative group that has access to
execute all actions.">
    <context project="*">
      <command group="*" job="*" actions="*"/>
    </context>
    <by>
      <group name="admin"/>
    </by>
  </policy>
</policies>

The example policy document above demonstrates the access granted to the users in group "admin". The asterisks indicate a wild card for those attributes (eg, semantically it means "ALL").

8.7.2 Access control policy actions

The authorization defines a number of actions that can be referenced inside the access control policy document. Reading their names, one might see these actions as a granular set of roles.

admin

Enables the user or group "super user" access.

user_admin

Modify user profiles.

workflow_read

Read and view jobs.

workflow_create

Create new jobs.

workflow_update

Edit existing jo.bs

workflow_delete

Remove jobs.

workflow_kill

Kill running jobs.

workflow_run

Execute a job.

events_read

List and view history.

events_create

Create new events.

events_update

Modify history (unused).

events_delete

Delete events (unused).

resources_read

List and view resources.

resources_create

Create resources (unused).

resources_update

Modify resources (unused).

resources_delete

Delete resources (unused).

job_view_unauthorized

Special role for viewing jobs that the user is unauthorized to run.

<policies>
  <policy description="Limited user access for adm restart actions">
    <context project="*">
      <command group="adm" job="Restart" actions="workflow_run,workflow_read"/>
      <command group="adm" job="stop"  actions="workflow_run"/>
      <command group="adm" job="start" actions="workflow_run"/>
    </context>
    <by>
      <group name="restart_user"/>
    </by>
  </policy>
</policies>

8.7.3 Role mapping

Role mapping is a way of adapting the User Roles provided by your authentication system to the Application Roles used by the RunDeck web app. This lets you work with whatever authentication provider based roles you have. Role mappings are defined in the rundeck-config.properties configuration file.

Application Roles

Role names used by the RunDeck application for testing whether the user is allowed to perform certain actions

User Roles

Role names used by an authencation system

These properties provide a mapping of allowed Application Roles to a set of specified User Roles. The defaults shown here match the set of default User Roles installed in the file based login mechanism (ie, realm.properties when you install RunDeck.

If you use your own directory-based authentication (eg Active Directory) you may need to modify the roles you use, especially if you are unable to change the roles/groups that User profiles are assigned to in your directory.

These are the default Application Roles that the role mapping can override:

+-----------------------+-----------------------+ |Application Role |User Role | +-----------------------+-----------------------+ |admin |admin | +-----------------------+-----------------------+ |user_admin |admin | +-----------------------+-----------------------+ |workflow_read |user | +-----------------------+-----------------------+ |workflow_create |admin | +-----------------------+-----------------------+ |workflow_update |admin | +-----------------------+-----------------------+ |workflow_kill |user | +-----------------------+-----------------------+ |workflow_run |user | +-----------------------+-----------------------+ |events_read |user | +-----------------------+-----------------------+ |events_create |user | +-----------------------+-----------------------+ |events_update |admin | +-----------------------+-----------------------+ |events_delete |admin | +-----------------------+-----------------------+ |resources_read |user | +-----------------------+-----------------------+ |resources_create |admin | +-----------------------+-----------------------+ |resources_update |admin | +-----------------------+-----------------------+ |resources_delete |admin | +-----------------------+-----------------------+ |job_view_unauthorized|job_view_unauthorized| +-----------------------+-----------------------+

Note

Setting the mapping value to a comma-separated list of Role names grants that Application Role to a user in any of the mapped roles.

If no role mapping is defined for an Application Role, then the literal name of the Application Role will be tested as the role name. E.g. If "mappedRoles.admin" is not defined, then a role named "admin" will be used.

The listing below contains the role mappings that appear after a normal RunDeck installation you will find in rundeck-config.properties.

#
# Map rundeck actions to allowed roles
#       mappedRoles.X=A,B,C
# means allow X to users in role A, B or C
#
mappedRoles.admin=admin
mappedRoles.user_admin=admin
mappedRoles.workflow_read=user
mappedRoles.workflow_create=admin
mappedRoles.workflow_update=admin
mappedRoles.workflow_delete=admin
mappedRoles.workflow_kill=user
mappedRoles.workflow_run=user
mappedRoles.events_read=user
mappedRoles.events_create=user
mappedRoles.events_update=user
mappedRoles.events_delete=user
mappedRoles.resources_read=user
mappedRoles.resources_create=admin
mappedRoles.resources_update=admin
mappedRoles.resources_delete=admin
#special role for viewing jobs unauthorized to run
mappedRoles.job_view_unauthorized=job_view_unauthorized

You can replace all of the User Roles shown in this file with your own custom role names from your directory service.

8.7.4 Troubleshooting access control policy

After defining an aclpolicy file to grant access to a particular group of users, you may find them getting "unauthorized" messages or complaints that certain actions are not possible.

To diagnose this, begin by checking two bits:

1. The user's group membership. This can be done by going to the user's profile page in RunDeck. That page will list the groups the user is a member.
2. Read the messages inside the rundeck.audit.log log file. The authorization facility generates fairly low level messages describing how the policy is matched to the user context.

If you don't see any output in the audit log for a user's action and they are able to login, then make sure role mapping is set correctly.

Once the user role mappings are defined correctly ask the user to login again and attempt accessing their jobs. You should watch the stream of messages flowing through the audit log. For each entry, you'll see all decisions leading up to either a AUTHORIZED or a REJECTED message. It's not uncommon to see REJECTED messages followed by AUTHORIZED. The important thing is to look at the last decision made.

8.7.5 Authorization caveats

• aclpolicy is used to determine what UI widgets are displayed (e.g., run, edit, delete, etc). But Authorization for pages still depends on Roles. (i.e. the AuthorizationFilter code looks at role membership, not aclpolicy).
• role mapping changes require a server restart, while aclpolicy changes do not.
• new and deleted aclpolicy files are detected after restarts

8.8.1 Securing passwords

Passwords do not have to be stored in the ssl.config. If they are not set, then the server will prompt on the console for a user to enter the passwords.

If you want the server to start without prompting then you need to set the passwords in the config file.

The passwords stored in ssl.properties can be obfuscated so they are not in plaintext:

Run the jetty "Password" utility:

$ java -cp server/lib/jetty-6.1.21.jar:server/lib/jetty-util-6.1.21.jar org.mortbay.jetty.security.Password <password>

This will produce two lines, one starting with "OBF:"

Use the entire OBF: output as the password in the ssl.properties file, eg:

key.password=OBF:1lk2j1lkj321lj13lj

8.8.2 Troubleshooting keystore

Some common error messages and causes:

java.io.IOException: Keystore was tampered with, or password was incorrect

A password specified in the file was incorrect.

2010-12-02 10:07:29.958::WARN: failed SslSocketConnector@0.0.0.0:4443: java.io.FileNotFoundException: /Users/greg/rundeck/etc/keystore (No such file or directory)

The keystore/truststore file specified in ssl.properties doesn't exist

8.8.3 Optional PEM export

You can export the PEM formatted server certificate for use by HTTPS clients (web browsers or e.g. curl).

Export pem cacert for use by e.g. curl:

keytool -export -keystore etc/keystore -rfc -alias rundeck > rundeck.server.pem

8.10.1 File descriptors

The RunDeck server process opens a number of files during normal operation. These include system and java libraries, logs, and sockets. Your system restricts the number of open file handles per process but these limitations can be adjusted.

If your installation attempts to exceed the limit, you will see an error like the one shown below in your service.log file.

Too many open files 

On Linux nodes

List the current limit with the ulimit command:

ulimit -n

If the limit is low (eg 1024) it should be raised.

You can get the current number of open file descriptors used by the RunDeck server process with lsof:

losf -p <rundeck pid> | wc -l

Increase the limit for a wide margin. Edit /etc/security/limits.conf file to raise the hard and soft limits. Here they are raised to 65535 for the "rundeck" system account:

rundeck hard nofile 65535
rundeck soft nofile 65535

The system file descriptor limit is set in /proc/sys/fs/file-max. The following command will increase the limit to 65535:

echo 65535 > /proc/sys/fs/file-max

In a new shell, run the ulimit command to set the new level:

ulimit -n 65535

The ulimit setting can be set in the rundeckd startup script, or profile.

Restart RunDeck.

8.10.2 Java heap size

The rundeckd startup script sets initial and maximum heap sizes for the server process. For many installations it will be sufficient.

If the Rundeck JVM runs out of memory, the following error occurs:

Exception in thread "main" java.lang.OutOfMemoryError: Java heap space

Heap size is governed by the following startup parameters: -Xms<initial heap size> and -Xmx<maximum heap size>

You can increase these by updating the RunDeck profile. To see the current values, grep the profile for the Xmx and Xms patterns:

• Launcher installs:

  egrep '(Xmx|Xms)' $RDECK_BASE/etc/profile
  

• RPM installs:

  egrep '(Xmx|Xms)' /etc/rundeck/profile
  

The default settings initialized by the installer sets these to 1024 megabytes maximum and 256 megabytes initial:

export RDECK_JVM="$RDECK_JVM -Xmx1024m -Xms256m"

Sizing advice

Several factors drive memory usage in RunDeck:

• User sessions
• Concurrent threads
• Concurrent jobs
• Number of managed nodes

For example, if your installation has dozens of active users that manage a large environment (1000+ nodes), and has sufficient system memory, the following sizings might be more suitable:

export RDECK_JVM="$RDECK_JVM -Xmx4096m -Xms1024m -XX:MaxPermSize=256m"

8.10.3 Quartz job threadCount

The maximum number of threads used by RunDeck for concurrent jobs is set in the quartz.properties file. By default, this is set to 10.

• RPM install: /var/lib/rundeck/server/exp/webapp/WEB-INF/classes/quartz.properties
• Launcher install: $RDECK_BASE/server/exp/webapp/WEB-INF/classes/quartz.properties

To change the maximum threadCount modify this file and alter the line:

org.quartz.threadPool.threadCount = 20

Set the threadCount value to the max number of threads you want to run concurrently.

Please refer to the Quartz site for detailed information: Configuration - Thread Pool

8.10.4 JMX instrumentation

You may wish to monitor the internal operation of your RunDeck server via JMX.

JMX provides introspection on the JVM, the application server, and classes all through a consistent interface. These various components are exposed to the management console via JMX managed beans — MBeans for short.

Note: For more background information on JMX, see "Java theory and practice: Instrumenting applications with JMX.".

Enable local JMX monitoring by adding the com.sun.management.jmxremote flag to the startup parameters in the profile.

export RDECK_JVM="$RDECK_JVM -Dcom.sun.management.jmxremote"

You use a JMX client to monitor JMX agents. This can be a desktop GUI like JConsole run locally.

jconsole <rundeck pid>

For instructions on remote JMX monitoring for Grails, Spring and log4j see: Grails in the enterprise.

9.1.1 Requirements

In order to provide the Resource model data to RunDeck:

1. The data must be either:
   • XML in resource-v10 format
   • YAML in resource-yaml-v12 format
2. Each Node entry must have a unique name value. You may have to convert the external system's identifier to be unique, or create one yourself.
3. The data must be either:
   • accessible on-disk from the RunDeck server,
   • OR accessible via a HTTP URL

This means you can provide the data in the way that best suits your specific use-case. Some examples:

• Hand-crafted XML/YAML data, which you could store in a version control system. The URL for the file in the VCS repository would be provided to RunDeck.
  • To update the data you would commit changes to your VCS, and then tell RunDeck to refresh.
• Data generated from a custom CMDB or other software, and stored on disk.
  • You could do this with a cron-job, or via some external trigger. RunDeck will simply read the resource.xml/resource.yaml file identified in the configuration file.
• Data generated from a simple CGI script which interfaces with another third-party or external service.
  • You could run Apache and host a simple CGI script. The CGI script would communicate to some other system and then return the XML/YAML content. You could tell RunDeck to refresh the Resource model, which would in turn cause the CGI to access the external data and return the reformatted content.

The Resource model data does not have to include the RunDeck server Node, as it is implicitly included.

9.1.2 Configuration

Resource model providers are defined on a per-project basis, in the project.properties file.

Define the file where the resource.xml will be stored on-disk. Each new project will have a good default location, but you may change it.

project.resources.file = ..

This file path is where RunDeck will read the contents from, and also where it will store it to if refreshing from a remote URL. If you specify a file ending in ".xml" then the format is resource-v10 XML. If you specify a file ending in ".yaml" then the format is resource-yaml-v12 YAML.

project.resources.url = http://...

This configures the remote URL for loading the Resources model data.

9.1.3 Implementations and Examples

svn add resources.xml http://svn.acme.com/ops/anvils/resources.xml
svn commit -m "added resource model for anvils" resources.xml

 curl http://svn.acme.com/viewvc/ops/anvils/resources.xml?revision=HEAD

project.resources.file = /etc/rundeck/projects/anvils/resources.xml
project.resources.url  = http://svn.acme.com/viewvc/ops/anvils/resources.xml?revision=HEAD

9.2.1 Requirements

1. Options model data must be JSON formatted.
2. It must be accessible via HTTP or on the local disk for the RunDeck server.
3. It must be in one of two JSON structures, either:
   • An array of string values
   • OR, an array of Maps, each with two entries, name and value.

9.2.2 Configuration

Each Option entry for a Job can be configured to get the set of possible values from a remote URL. If you are authoring the Jobs via job.xml file format, simply add a valuesUrl attribute for the <option>. If you are modifying the Job in the RunDeck web GUI, you can entry a URL in the "Remote URL" field for the Option.

e.g.:

<option valuesUrl="http://site.example.com/values.json" ...

Note: File URL scheme is also acceptable (e.g, file:/path/to/job/options/optA.json).

The value data must be returned in JSON data format described below.

9.2.3 JSON format

Three styles of return data are supported: simple list, simple object, and a name/value list. For a simple list, the list values will be displayed in a pop-up list when running the Job. If a simple object or name/value pairs are returned, then the name will be displayed in the list, but the value will be used as the input.

Examples

Simple List:

["x value for test","y value for test"]

This will populate the select menu with the given values.

Simple Object:

{ "Name": "value1", "Name2":"value2" }

This will populate the select menu to show the names and use the values.

Name Value List:

[
  {name:"X Label", value:"x value"},
  {name:"Y Label", value:"y value"},
  {name:"A Label", value:"a value"}
] 

9.2.4 Variable expansion in remote URLs

The URL declared for the "valuesUrl" can embed variables which will be filled with certain job context items when making the remote request. This helps make the URLs more generic and contextual to the Job.

Two types of expansions are available, Job context, and Option context.

To include job information in the URL, specify a variable of the form ${job.property}.

Properties available for Job context:

• name: Name of the Job
• group: Group of the Job
• description: Job description
• project: Project name
• argString: Default argument string for a job

To include Option information in the URL, specify a variable of the form ${option.property}:

Properties available for Option context:

• name: Name of the current option

Examples

http://server.com/test?name=${option.name}

Passes the option name as the "name" query parameter to the URL.

http://server.com/test?jobname=${job.name}&jobgroup=${job.group}

Passes the job name and group as query parameters.

9.2.5 Remote request failures

If the request for the remote option values fails, then the GUI form will display a warning message:

In this case, the option will be allowed to use a textfield to set the value.

9.2.6 Implementations and Examples

The following two sections describe examples using simple CGI scripts that act as option model providers.

#!/bin/bash
# Requires: curl, xmlstarlet
# Returns a JSON list of key/val pairs
#
# Query Params and their defaults
hudsonUrl=https://build.acme.com:4440/job
hudsonJob=ApplicationBuild
artifactPath=/artifact/bin/dist/RPMS/noarch/

echo Content-type: application/json
echo ""
for VAR in `echo $QUERY_STRING | tr "&" "\t"`
do
  NAME=$(echo $VAR | tr = " " | awk '{print $1}';);
  VALUE=$(echo $VAR | tr = " " | awk '{ print $2}' | tr + " ");
  declare $NAME="$VALUE";
done

curl -s -L -k $hudsonUrl/${hudsonJob}/api/xml?depth=1 | \
  xmlstarlet sel -t -o "{" \
    -t -m "//build[result/text()='SUCCESS']" --sort A:T:L number  \
    -m . -o ""Release" -m changeSet/item -o ' ' -v revision -b \
    -m . -o ", Hudson Build " -v number -o "":" \
    -m 'artifact[position() = 1]' -o """ -v '../number' -o $artifactPath -o "{" -b \
    -m 'artifact[position() != last()]' -v 'fileName' -o "," -b \
    -m 'artifact[position() = last()]' -v 'fileName' -o "}"," \
    -t -o "}"

curl -d "hudsonJob=anvils&artifactPath=/artifact/bin/dist/RPMS/noarch/" \
    --get http://opts.acme.com/cgi/hudson-artifacts.cgi

[ 
  {name:"anvils-1.1.rpm", value:"/artifact/bin/dist/RPMS/noarch/anvils-1.1.rpm"}, 
  {name:"anvils-1.2.rpm", value:"/artifact/bin/dist/RPMS/noarch/anvils-1.2.rpm"} 
]   

 <option name="package" enforcedvalues="true" required="true"
    valuesUrl="http://ops.acme.com/cgi/hudson-artifacts.cgi?hudsonJob=anvils"/> 

#!/bin/bash
# Requires: repoquery
# 
# Query Params and their defaults
repo=acme-staging
label="Anvils Release"
package=anvils
max=30
#
echo Content-type: application/json
echo ""
for VAR in `echo $QUERY_STRING | tr "&" "\t"`
do
  NAME=$(echo $VAR | tr = " " | awk '{print $1}';);
  VALUE=$(echo $VAR | tr = " " | awk '{ print $2}' | tr + " ");
  declare $NAME="$VALUE";
done

echo '{'
repoquery --enablerepo=$repo --show-dupes \
  --qf='"${label} %{VERSION}-%{RELEASE}":"%{NAME}-%{VERSION}-%{RELEASE}",' \
  -q --whatprovides ${package} | sort -t - -k 4,4nr | head -n${max}
echo '}'

curl -d "repo=acme&label=Anvils&package=anvils" \
    --get http://ops.acme.com/cgi/yum-repoquery.cgi

TODO: include JSON example

 <option name="package" enforcedvalues="true" required="true"
    valuesUrl="http://ops.acme.com/cgi/yum-repoquery.cgi?package=anvils"/> 

9.3.1 Definition

The RunDeck resource model document format and the resource-yaml-v12 format provide two attributes that help connect the dots between the RunDeck UI and the editing interface provided by the external data management tool. They can use editUrl or remoteUrl attributes to specify the remote URL. The URLs can embed properties about the node to expand prior to being loaded, which allows you to e.g. submit query parameters using the node name.

editUrl

Specifies a URL to a remote site which will allow editing of the Node. When specified, the Node resource will display an "Edit" link in the RunDeck GUI and clicking it will open a new browser page for the URL.

remoteUrl

Specifies a URL for a remote site which will be loaded in an iframe within a RunDeck page. Clicking the "Edit" link for the Node will load content from the site within the current RunDeck page, allow you to perform your edit at the remote site, and has optional JavaScript hooks to report the state of the editing process back to the RunDeck page for a more streamlined user interface.

9.3.2 Using properties

Properties of the Node can be embedded in the URL and expanded prior to use. The syntax is:

${node.property}

Available properties are:

name, hostname, os-name, os-version, os-family, os-arch, username, description, tags, type, project

You can embed these properties within the url like this:

http://mycmdb:8080/node/edit?name=${node.name}

9.3.3 Using remoteUrl

Using the remoteUrl lets you embed another site into an iframe within the RunDeck page, and optionally allows communication back to the RunDeck page about the state of the editing process.

If you want to embed the remote site without having to make any changes to the remote page content, you can do so simply by specifying the remoteUrl to use. When the user clicks "Edit" the site will load within an iframe, and the user can perform whatever actions on the site are necessary. After they are done they will have to manually click the "Close" button on the RunDeck page to close the iframe.

If you want the user interface in RunDeck to be more streamlined, you will have to be able to modify the web pages produced by the remote site to add simple Javascript calls to communicate back to the RunDeck page. The JavaScript hooks are designed to not add much burden to the developer of the remote site or system, so they are optional.

<script type="text/javascript">
    if(window.self!=window.parent){
        window.parent.postMessage("...message...","http://rundeckserver:port");
    }
</script>

9.3.4 Examples

Here are some examples of using the editUrl and remoteUrl in a resources.xml/resources.yaml file:

Specify a simple URL for editing, which will simply produce a link:

<node name="venkman" editUrl="http://mycmdb:8080/node/edit" ... />

Specify a URL for editing, with embedded "name" property as a parameter:

<node name="venkman" editUrl="http://mycmdb:8080/node/edit?name=${node.name}" ... />

Specify a remote URL with embedded "name" and "project" properties as parameters:

<node name="venkman" remoteUrl="http://mycmdb:8080/node/edit?name=${node.name}&amp;project=${node.project}" ... />

Specify a remote URL with embedded "name" property as part of the path:

<node name="venkman" remoteUrl="http://mycmdb:8080/node/edit/${node.name}"  ... />

In YAML, some examples:

Specify a remote URL with embedded "name" and "project" properties as parameters:

venkman:
  nodename: venkman
  remoteUrl: http://mycmdb:8080/node/edit?name=${node.name}&project=${node.project}

Specify a remote URL with embedded "name" property as part of the path:

venkman:
  nodename: venkman
  remoteUrl: "http://mycmdb:8080/node/edit/${node.name}

remoteUrl="http://localhost:8080/node/edit?name=${node.name}&project=${node.project}"

10.5.1 Item Lists

Many API requests will return an item list as a result. These are typically in the form:

<[items] count="x">
    <[item] ...>
    <[item] ...>
</[items]>

Where the list of specific items are wrapped in a pluralized element name which contains a count attribute.

When an API path declares its results as an "Item List" this is the format that will be returned.

10.6.1 System Info

Get RunDeck server information and stats.

URL:

/system/info

Parameters: none

Result: Success response, with included system info and stats in this format:

<system>
    <timestamp epoch="1305909785806" unit="ms">
        <datetime>2011-05-20T16:43:05Z</datetime>
    </timestamp>
    <rundeck>
        <version>1.2.1</version>
        <build>1.2.1-0-beta</build>
        <node>Venkman.local</node>
        <base>/Users/greg/rundeck121</base>
    </rundeck>
    <os>
        <arch>x86_64</arch>
        <name>Mac OS X</name>
        <version>10.6.7</version>
    </os>
    <jvm>
        <name>Java HotSpot(TM) 64-Bit Server VM</name>
        <vendor>Apple Inc.</vendor>
        <version>19.1-b02-334</version>
    </jvm>
    <stats>
        <uptime duration="300584" unit="ms">
            <since epoch="1305909485222" unit="ms">
                <datetime>2011-05-20T16:38:05Z</datetime>
            </since>
        </uptime>
        <cpu>
            <loadAverage unit="percent">0.40234375</loadAverage>
            <processors>4</processors>
        </cpu>
        <memory unit="byte">
            <max>477233152</max>
            <free>76626216</free>
            <total>257163264</total>
        </memory>
        <scheduler>
            <running>0</running>
        </scheduler>
        <threads>
            <active>24</active>
        </threads>
    </stats>
</system>

Description of included elements:

timestamp describes the current system time known to the server. The @epoch attribute includes the milliseconds since the unix epoch.

datetime

The W3C date and time

rundeck includes information about the RunDeck application.

rundeck/version

RunDeck version

rundeck/build

RunDeck build stamp

rundeck/node

Server node name

rundeck/base

Server base directory

os/arch

Operating System architecture

os/name

Operating System Name

os/version

Operating System Version

jvm/name

JVM name

jvm/vendor

JVM vendor

jvm/version

JVM version

stats section includes some system statistics:

uptime describes the JVM uptime as duration in ms, and includes absolute startup time:

uptime/since

JVM startup time as time since the unix epoch

uptime/since/datetime

JVM startup time as W3C date time.

cpu/loadAverage

JVM load average percentage for the system for the previous minute (see getSystemLoadAverage)

cpu/processors

Number of available system processors. note that loadAverage might be calculated based on the total number of available processors

The memory section describes memory usage in bytes:

max

Maximum JVM memory that can be allocated

free

Free memory of the allocated memory

total

Total allocated memory for the JVM

scheduler/running

Number of running jobs in the scheduler

threads/active

Number of active Threads in the JVM

10.6.2 Listing Jobs

List the jobs that exist for a project.

URL:

/jobs

Required parameters:

• project: the project name

The following parameters can also be used to narrow down the result set.

• idlist: specify a comma-separated list of Job IDs to include
• groupPath: specify a group or partial group path to include all jobs within that group path.
• jobFilter: specify a filter for the job Name

Result: An Item List of jobs. Each job is of the form:

<job id="ID">
    <name>Job Name</name>
    <group>Job Name</group>
    <project>Project Name</project>
    <description>...</description>
</job>

10.6.3 Running a Job

Run a job specified by ID.

URL:

/job/[ID]/run

Optional parameters:

• argString: argument string to pass to the job, of the form: -opt value -opt2 value ....
• Node filter parameters as described under Using Node Filters

Result: An Item List of executions containing a single entry for the execution that was created. See Listing Running Executions.

10.6.4 Exporting Jobs

Export the job definitions for in XML or YAML formats.

URL:

/jobs/export

Required parameters:

• project

Optional parameters:

• format : can be "xml" or "yaml" to specify the output format. Default is "xml"

The following parameters can also be used to narrow down the result set.

• idlist: specify a comma-separated list of Job IDs to export
• groupPath: specify a group or partial group path to include all jbos within that group path.
• jobFilter: specify a filter for the job Name

Result:

If you specify format=xml, then the output will be in jobs-v20(5) format.

If you specify format=yaml, then the output will be in jobs-v20-yaml(5) format.

If an error occurs, then the output will be in XML format, using the common result element described in the Response Format section.

10.6.5 Importing Jobs

Import job definitions in XML or YAML formats.

URL:

/jobs/import

Method: POST

Expected Content-Type: application/x-www-form-urlencoded

Required Content:

• xmlBatch: A x-www-form-urlencoded request parameter containing the input file content.

Optional parameters:

• format : can be "xml" or "yaml" to specify the output format. Default is "xml"
• dupeOption: A value to indicate the behavior when importing jobs which already exist. Value can be "skip", "create", or "update". Default is "create".

Result:

A set of status results. Each imported job definition will be either "succeeded", "failed" or "skipped". These status sections contain a count attribute declaring how many jobs they contain. Within each one there will be 0 or more job elements.

<succeeded count="x">
    <!-- job elements -->
</succeeded>
<failed count="x">
    <!-- job elements -->
</failed>
<skipped count="x">
    <!-- job elements -->
</skipped>

Each Job element will be of the form:

<job>
    <!-- ID may not exist if the job was not created yet -->
    <id>ID</id>
    <name>job name</name>
    <group>job group</group>
    <project>job project</project>
    <!--if within the failed section, then an error section will be included -->
    <error>Error message</error> 
</job>

10.6.6 Getting a Job Definition

Export a single job definition in XML or YAML formats.

URL:

/job/[ID]

Optional parameters:

• format : can be "xml" or "yaml" to specify the output format. Default is "xml"

Result:

If you specify format=xml, then the output will be in jobs-v20(5) format.

If you specify format=yaml, then the output will be in jobs-v20-yaml(5) format.

If an error occurs, then the output will be in XML format, using the common result element described in the Response Format section.

10.6.7 Deleting a Job Definition

Delete a single job definition.

URL:

/job/[ID]

Method: DELETE

Result:

The common result element described in the Response Format section, indicating success or failure and any messages.

If successful, then the result will contain a success/message element with the result message:

<success>
<message>Job was successfully deleted: ... </message>
</success>

10.6.8 Getting Executions for a Job

Get the list of executions for a Job.

URL:

/job/[ID]/executions

Optional Query Parameters:

• status: the status of executions you want to be returned. Must be one of "succeeded", "failed", "aborted", or "running". If this parameter is blank or unset, include all executions.
• Paging parameters:
  • max: indicate the maximum number of results to return. If unspecified, all results will be returned.
  • offset: indicate the 0-indexed offset for the first result to return.

Result: an Item List of executions. See Listing Running Executions.

10.6.9 Listing Running Executions

List the currently running executions for a project

URL:

/executions/running

Required Parameters:

• project: the project name

Result: An Item List of executions. Each execution of the form:

<execution id="[ID]" href="[url]" status="[status]">
    <user>[user]</user>
    <date-started unixtime="[unixtime]">[datetime]</date-started>

    <!-- optional job context if the execution is associated with a job -->
    <job id="jobID">
        <name>..</name>
        <group>..</group>
        <description>..</description>
    </job>

    <!-- description of the execution -->
    <description>...</description>

    <!-- The following elements included only if the execution has ended -->

    <!-- the completion time of the execution -->
    <date-ended unixtime="[unixtime]">[datetime]</date-ended> 

    <!-- if the execution was aborted, the username who aborted it: -->
    <abortedby>[username]</abortedby>

</execution>

The [status] value indicates the execution status. It is one of:

• running: execution is running
• succeeded: execution completed successfully
• failed: execution completed with failure
• aborted: execution was aborted

The [url] value is a URL to the RunDeck server page to view the execution output.

[user] is the username of the user who started the execution.

[unixtime] is the millisecond unix timestamp, and [datetime] is a W3C dateTime string in the format "yyyy-MM-ddTHH:mm:ssZ".

10.6.10 Getting Execution Info

Get the status for an execution by ID.

URL:

/execution/[ID]

Result: an Item List of executions with a single item. See Listing Running Executions.

10.6.11 Aborting Executions

Abort a running execution by ID.

URL:

/execution/[ID]/abort

Result: The result will contain a success/message element will contain a descriptive message. The status of the abort action will be included as an element:

<abort status="[abort-state]">
    <execution id="[id]" status="[status]"/>
</abort>

The [abort-state] will be one of: "pending", "failed", or "aborted".

10.6.12 Running Adhoc Commands

Run a command string.

URL:

/run/command

Required Parameters:

• project: the project name
• exec: the shell command string to run, e.g. "echo hello".

Optional Parameters:

• nodeThreadcount: threadcount to use
• nodeKeepgoing: if "true", continue executing on other nodes even if some fail.

Node filter parameters as described under Using Node Filters

10.6.13 Running Adhoc Scripts

Run a script.

URL:

/run/script

Method: POST

Expected Content-Type: application/x-www-form-urlencoded

Required Parameters:

• project: the project name

Required Content:

• scriptFile: A x-www-form-urlencoded request parameter containing the script file content.

Optional Parameters:

• argString: Arguments to pass to the script when executed.
• nodeThreadcount: threadcount to use
• nodeKeepgoing: if "true", continue executing on other nodes even if some fail.

Node filter parameters as described under Using Node Filters

10.6.14 Listing Projects

List the existing projects on the server.

URL:

/projects

Result: An Item List of projects, each project of the form specified in the Getting Project Info section.

10.6.15 Getting Project Info

Get information about a project.

URL:

/project/NAME

Result: An Item List of projects with one project. The project is of the form:

<project>
    <name>Project Name</name>
    <description>...</description>
    <!-- additional items -->
</project>

If the project defines a Resource Model Provider URL, then the additional items are:

<resources>
    <providerURL>URL</providerURL>
</resources>

10.6.16 Listing History

List the event history for a project.

URL:

/history

Required Parameters:

• project : project name

Optional Parameters:

• History query parameters:
  • jobIdFilter: include events for a job ID.
  • reportIdFilter: include events for an event Name.
  • userFilter: include events created by a user
  • statFilter: include events based on result status. this can be 'succeed','fail', or 'cancel'.
• Date query parameters:
  • recentFilter: Use a simple text format to filter events that occured within a period of time. The format is "XY" where X is an integer, and "Y" is one of:
    • h: hour
    • d: day
    • w: week
    • m: month
    • y: year So a value of "2w" would return events within the last two weeks.
  • begin: Specify exact date for earliest result.
  • end: Specify exact date for latest result.
• Paging parameters:
  • max: indicate the maximum number of events to return. The default maximum to return is 20.
  • offset: indicate the 0-indexed offset for the first event to return.

The format for the end, and begin filters is either: a unix millisecond timestamp, or a W3C dateTime string in the format "yyyy-MM-ddTHH:mm:ssZ".

Result: an Item List of events. Each event has this form:

<event starttime="[unixtime]" endtime="[unixtime]">
  <title>[job title, or "adhoc"]</title>
  <status>[status]</status>
  <summary>[summary text]</summary>
  <node-summary succeeded="[X]" failed="[Y]" total="[Z]"/>
  <user>[user]</user>
  <project>[project]</project>
  <date-started>[start date]</date-started>
  <date-ended>[end date]</date-ended>
  <!-- if the execution was aborted, the username who aborted it: -->
  <abortedby>[username]</abortedby>
  <!-- if associated with an Execution, include the execution id: -->
  <execution id="[execid]"/>
  <!-- if associated with a Job, include the Job ID: -->
  <job id="[jobid]"/>
</event>

The events element will also have max, offset, and total attributes, to indicate the state of paged results. E.G:

<events count="8" total="268" max="20" offset="260">
...
</events>

total is the total number of events matching the query parameters. count is the number of events included in the results. max is the paging size as specified in the request, or with the default value of 20. offset is the offset specified, or default value of 0.

10.6.17 Creating History Event Reports

Create a history event report for any external process.

URL:

/report/create

Required Parameters:

• project : project name
• status : report status, one of "succeeded", "failed" or "aborted"
• title : Title of the report. This should be a short string identifying the process that was run. E.g. RunDeck jobs use the Job Group and Job Name, and adhoc commands use the string "adhoc".
• summary : A descriptive summary of the result.
• nodesuccesscount: number of successful nodes: how many nodes the process succeeded on.
• nodefailedcount: number of failed nodes: how many nodes the process failed on.

Optional Parameters:

• start: Specify exact date for beginning of the process (defaults to the same as end).
• end: Specify exact date for end of the process (defaults to time the report is received).
• script: Full adhoc command or script that was run, if applicable.
• jobID: Any associated RunDeck Job ID
• execID: Any associated RunDeck Execution ID.

The format for the end, and start values is either: a unix millisecond timestamp, or a W3C dateTime string in the format "yyyy-MM-ddTHH:mm:ssZ".

10.6.18 Listing Resources

List or query the resources for a project.

URL:

/resources

Required Parameters:

• project : project name

Optional Parameters:

• format : Result format. One of "xml" or "yaml". Default is "xml".

• Node Filter parameters: You can select resources to include and exclude in the result set, see Using Node Filters below.

Note: If no query parameters are included, the result set will include all Node resources for the project.

Result: Depending on the format parameter, a value of "xml" will return resources-v10(5) and "yaml" will return resources-v10-yaml(5) formatted results.

10.6.19 Getting Resource Info

Get a specific resource within a project.

URL:

/resource/[name]

Required Parameters:

• project : project name

Optional Parameters:

• format : Result format. One of "xml" or "yaml". Default is "xml".

Result: Depending on the format parameter, a value of "xml" will return resources-v10(5) and "yaml" will return resources-v10-yaml(5) formatted results.

The result will contain a single item for the specified resource.