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
• pluggable execution system uses SSH by default
• 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
• Web API

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 manager, configuration management 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 criteria 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.

You can also use the Web API to interface with all aspects of the command dispatcher. (See the RunDeck API.)

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 multiple sources, and RunDeck defines several resource model document formats to facilitate the transfer of this information.

Resource Model data sources can be local files on disk, or remotely accessible services. A URL resource model source is an external service accessible via the HTTP GET method that returns data in one of the supported resource document formats.

RunDeck currently supports XML and YAML document formats. See Resource Model Document formats).

Each project can be configured to have multiple sources of Resource Model data. See Resource Model Sources.

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.

See: Authorization.

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|4443' 

tcp46      0      0  *.4440                 *.*                    LISTEN

2.2.2 Installing from Source

Checkout the sources from GitHub

You can build either the launcher jar (self-running archive), or a RPM.

make

Creates the rundeck-launcher.jar

Build the RPM:

make rpm

To build clean:

make clean

Documentation can be built using: make clean docs. Documentation build requires pandoc. The RPM build depends on the the documentation as well.

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

java -jar rundeck-launcher-1.3.0.jar -h

usage: java [JAVA_OPTIONS] -jar rundeck-launcher.jar  [-c PATH] [-d]
       [--installonly] [-s PATH] [-b PATH] [-p PATH] [-h] [-x PATH]
       [--skipinstall] [--serverdir PATH] [--datadir PATH]

Run the rundeck server, installing the necessary components if they do not
exist.
    --skipinstall         Skip the extraction of the utilities from the
                          launcher.
    --installonly         Perform installation only and do not start the
                          server.
 -b,--basedir <PATH>      The basedir
 -c,--configdir <PATH>    The location of the configuration.
 -d                       Show debug information
 -h,--help                Display this message.
 -p,--projectdir <PATH>   The location of Rundeck's project data.
 -s,--sbindir <PATH>      The install directory for the tools used by
                          administrators.
 -x,--bindir <PATH>       The install directory for the tools used by
                          users.

2.4.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.4.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 Resource Model is the set of available Nodes that RunDeck can dispatch commands to, and their associated metadata. Each RunDeck Project has its own Resource Model.

The initial resource model 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: ''

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 basic properties for accessing and storing resource model data:

• project.resources.file: A local file path to read a resource model document
• project.resources.url: URL to an external resource model source (optional)

In addition, multiple pluggable "Resource Model Sources" can be configured for a project to retrieve additional Resource Model content from other sources. See Resource Model Sources.

You can configure RunDeck to retrieve and store resource model data from any source, so long as it can produce one of the RunDeck resource model document formats. (See Resource Model Document formats.) Set the project.resource.url to the URL resource model source of your choice.

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 authoritative tool and expose it as RunDeck URL resource model source. 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.

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

3.2.2 Resource Model Document formats

RunDeck currently has two resource model document formats built in:

• XML: resource-v13(5) XML. Format name: resourcexml.
• Yaml: resource-v13(5) YAML. Format name: resourceyaml.

You can enable more formats using Resource Format Plugins.

3.4.1 Dispatcher options

Dispatcher execution can be controlled by various types of options.

Execution control

Concurrency is controlled by setting the "threadcount". Execution can continue even if some node fails if the "keepgoing" option is set to true.

Node Filters

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

Filter Keywords

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

Filter combinations

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.4.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.4.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.4.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.4.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.4.2.2.1.1 Separate execution 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.4.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.4.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.4.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 -p project
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.6 Plugins

RunDeck supports a plugin model for the execution service, which allows you to fully customize the way that a particular Node, Project or your entire RunDeck installation executes commands and scripts remotely (or locally).

By default RunDeck uses an internal plugin to perform execution via SSH for remote nodes, and local execution on the RunDeck server itself.

Plugins can be installed by copying them to the libext directory of your RunDeck installation.

Plugins are used to add new "providers" for particular "services". The services used for command execution on nodes are the "node-executor" and "file-copier" services.

To use a particular plugin, it must be set as the provider for a service by configuring the framework.properties file, the project.properties file, or by adding attributes to Nodes in your project's resources definitions. For more about configuring the providers, see Using Providers.

The internal SSH command execution plugin is described below, and more information about plugins can be found in the RunDeck Plugins chapter.

3.5.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.5.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.5.3 RSS link

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

RSS link

3.6.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.6.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.3.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.5.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 governing 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.5.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.6.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.6.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.6.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".
   • If you want to specify your own UUID you can enter it in the field. Otherwise a unique value will be set for you.
   • 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.

4.6.4 Node dispatching and filtering

When you create a job you can choose between either running the job only locally (on the RunDeck server), or dispatching it to multiple nodes (including the RunDeck server if you want).

In the GUI, the "Dispatch to Nodes" checkbox lets you enable node dispatching. When you click this box you are presented with the Node Filtering interface:

Node Filtering interface

You can click the different filter fields "Name", and "Tags" to enter filter values for those fields. As you update the values you will see the "Matched Nodes" section updated to reflect the list of nodes that will match the inputs. You can click "More" to see more of the available inclusion filters, and you can click "Extended Filters" to enter exclusion filters for the same fields.

You can set the maximum number of simultaneous threads to use by changing the "Thread Count" box. A value of 1 means all node dispatches happen sequentially, and any greater value means that the node dispatches will happen in parallel.

If you set "Keep going on error?" to "Yes", then if any node dispatches fail for any reason, the rest will continue to be executed until all have been executed. At the end of the workflow for all nodes, the Job Execution will fail if any of the nodes had failed.

If you leave it at the default value of "No", then if any node dispatches fail for any reason, no further dispatches will be executed and the Job Execution will fail immediately.

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 and can include variable expansion to pass any input options for the current job. Format:

-optname <value> -optname <value> ...

The format for specifying options is exactly the same as you would pass to the run commandline tool, and you can substitute values of input options to the current job. For example:

-opt1 something -opt2 ${option.opt2}

This would set the value "something" for the Job's "opt1" option, and then pass the "opt2" option directly from the top-level job to the Job reference.

This is similar to calling the other Job with run:

run [filter-options] -j group/jobname -- -opt1 something -opt2 somethingelse

If the Job has required Options that are not specified on the arguments line, then a "defaultValue" of that option will be used if it is defined. If a required option does not have a default value, then the execution will fail because the option is not specified.

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 administrator 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";
};

grails.serverURL=https://node.fully.qualified.domain.name:4443
grails.mail.default.from=deployer@domain.com

8.2.3 GUI Admin Page

The RunDeck GUI has an Admin Page which contains lets you view and manage some configuration options. If you have admin role access, when you log in you will see an "Admin" link in the header of the page near your username:

Admin page link

Clicking on this link will take you to the Admin Page:

Admin page

This page contains links to two sub-pages, and configuration information about the currently selected Project.

8.2.3.1 System Information Page

The System Information page gives you a breakdown of some of the RunDeck server's system statistics and information:

System Info Page

This information is also available via the API: API > System Info

8.2.3.2 User Profiles Page

The User Profiles page lists all User Profile records in the system. User Profiles are used to store some user preferences, and can be used to generate API Tokens for admin users.

User Profiles Page

8.2.3.3 Project Configuration

The selected project will be displayed with basic configuration options, and the list of configure Resource Model Sources, as well as the default Node Executor and File Copier settings.

If you click on "Configure Project", you will be taken to the Project Configuration form.

Project Configuration Form

The first two fields allow configuration of some simple project basics.

First, you can enter a URL for a Resource Model Source, which will be used as a URL Resource Model Source with default configuration options.

Secondly, you can enter the Default SSH Key File, which is the private SSH Key file used by default for SSH and SCP actions. If you are not using SSH or SCP you do not have to enter one.

There are then several more sections: Resource Model Sources, Default Node Executor, and Default File Copier sections. These are described below:

8.2.3.4 Resource Model Sources Configuration

This section lets you add and modify Resource Model Sources for the project.

To add a new one, click "Add Source". You are prompted to select a type of source. The list shown will include all of the built-in types of sources, as well as any Plugins you have installed.

Add Resource Model Source

When you click "Add" for a type, you will be shown the configuration options for the type.

Configure Resource Model Source

You can then click "Cancel" or "Save" to discard or add the configuration to the list.

Each item you add will be shown in the list:

Configured Source

To edit an item in the list click the "Edit" button. To delete an item in the list click the "Delete" button.

Each type of Resource Model Source will have different configuration settings of its own. The built-in Resource Model Source providers are shown below.

You can install more sources as plugins, see Resource Model Source Plugins.

8.2.3.4.1 File Resource Model Source

This is the File Resource Model Source configuration form:

File Resource Model Source

See File Resource Model Source Configuration for more configuration information.

8.2.3.4.2 Directory Resource Model Source

Allows a directory to be scanned for resource document files. All files with an extension supported by one of the Resource Model Document Formats are included.

Directory Resource Model Source

See Directory Resource Model Source Configuration for more configuration information.

8.2.3.4.3 Script Resource Model Source

This source can run an external script to produce the resource model definitions.

Script Resource Model Source

See Script Resource Model Source Configuration for more configuration information.

8.2.3.4.4 URL Resource Model Source

This source performs a HTTP GET request on a URL to return the resource definitions.

URL Resource Model Source

See URL Resource Model Source Configuration for more configuration information.

8.2.3.5 Default Node Executor Configuration

When RunDeck executes a command on a node, it does so via a "Node Executor". The most common built-in Node Executor is the "SSH" implementation, which uses SSH to connect to the remote node, however other implementations can be used.

Select the Default Node Executor you wish to use for all remote Nodes for the project:

Default Node Executor Choice

You can install more types of Node Executors as plugins, see Node Execution Plugins.

8.2.3.6 Default File Copier Configuration

When RunDeck executes a script on a node, it does so by first copying the script as a file to the node, via a "File Copier". (It then uses a "Node Executor" to execute the script like a command.)

The most common built-in File Copier is the "SCP" implementation, which uses SCP to copy the file to the remote node, however other implementations can be used.

Select the Default File Copier you wish to use for all remote Nodes for the project:

Default File Copier Choice

You can install more types of File Copiers as plugins, see Node Execution Plugins.

8.4.1 Recovery

1. Stop the server. See: startup and shutdown. (RunDeck recovery should only be done with the server down.)

   rundeckd stop
   

2. Restore data/logs dir from backup (Refer to above for appropriate log/data path):

   cp -r /path/to/backup/logs logspath
   cp -r /path/to/backup/data datapath
   

3. Start the server:

   rundeckd start
   

4. Reload the Job definitions. You will have to do this for each project:

   rd-jobs load -f /path/to/backup/dir/project1/jobs.xml -p project1
   rd-jobs load -f /path/to/backup/dir/project2/jobs.xml -p project2
   

8.5.1 Enable rdbsupport

First, you must enable the rundeck.v14.rdbsupport property:

#note, make sure this is set to "true" if you are using Oracle or Mysql
rundeck.v14.rdbsupport=true

This makes RunDeck use table/field names that are compatible with Oracle/Mysql.

Note: It is safe to set this to true if you are using the default file based backend, but only for a fresh install. It will cause a problem if you set it to true for an existing Rundeck 1.3 HSQLDB database. Make sure it is set to "false" or is absent from your config file if you are upgrading from Rundeck 1.3 and using the filesystem storage.

8.5.2 Customize the Datasource

The default dataSource is configured for filesystem storage using HSQLDB:

dataSource.url = jdbc:hsqldb:file:/var/lib/rundeck/data/grailsdb;shutdown=true

Here is an example configuration to use an Oracle backend:

dataSource.url = jdbc:oracle:thin:@localhost:1521:XE
dataSource.driverClassName = oracle.jdbc.driver.OracleDriver
dataSource.username = dbuser
dataSource.password = dbpass
dataSource.dialect = org.hibernate.dialect.Oracle10gDialect

Here is an example configuration to use Mysql:

dataSource.url = jdbc:mysql://myserver/rundeckdb
dataSource.username = dbuser
dataSource.password = dbpass

8.5.3 Add the JDBC Driver

Copy the appropriate JDBC driver, such as "ojdbc14.jar" for Oracle into the server lib dir:

cp ojdbc14.jar $RDECK_BASE/server/lib

Or:

cp mysql-connector-java-5.1.17-bin.jar $RDECK_BASE/server/lib

8.6.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.6.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.6.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.4 Configuring SSH private keys

The built-in SSH connector allows the private key to be specified in several different ways. You can configure it per-node, per-project, or per-RunDeck instance.

When connecting to the remote node, RunDeck will look for a property/attribute specifying the location of the private key file, in this order, with the first match having precedence:

1. Node level: ssh-keypath attribute on the Node. Applies only to the target node.
2. Project level: project.ssh-keypath property in project.properties. Applies to any project node by default.
3. RunDeck level: framework.ssh-keypath property in framework.properties. Applies to all projects by default.
4. RunDeck level: framework.ssh.keypath property in framework.properties. Applies to all projects by default (included for compatibility with Rundeck < 1.3). (default value: ~/.ssh/id_rsa).

8.6.5 Passing environment variables through remote command

To pass environment variables through remote command dispatches, it is required to properly configure the SSH server on the remote end. See the AcceptEnv directive in the "sshd_config(5)" manual page for instructions.

Use a wild card pattern to permit RD_ prefixed variables to provide open access to RunDeck generated environment variables.

8.7.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.7.2 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/rundeck/
   • 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";
       };
   

Note: The bindDn and bindPassword must escape any special characters with \ character. Special characters include \ (backslash), as well as ! (exclamation).

2. To override the default JAAS configuration file, you will need to supply the RunDeck server with the proper path to the new one, and a loginmodule.name Java system property to identify the new login module by name.

   The JAAS configuration file location is specified differently between the Launcher and the RPM.

   For the Launcher: the loginmodule.conf.name Java system property is used to identify the name of the config file, which must be located in the $RDECK_BASE/server/config dir.

   You can simply specify the system properties on the java commandline:

   java -Dloginmodule.conf.name=jaas-activedirectory.conf \
       -Dloginmodule.name=activedirectory \
       -jar rundeck-launcher-x.x.jar
   

   Otherwise, if you are starting the Launcher via the supplied rundeckd script, you can modify the RDECK_JVM value in the $RDECK_BASE/etc/profile file to add two JVM arguments:

   export RDECK_JVM="-Dloginmodule.conf.name=jaas-activedirectory.conf \
       -Dloginmodule.name=activedirectory"
   

   Note: more information about using the launcher and useful properties are under Getting Started - Launcher Options.

   For the RPM installation: the absolute path to the JAAS config file must be specified with the java.security.auth.login.config property.

   Update the RDECK_JVM in /etc/rundeck/profile by changing the following two JVM arguments:

   export 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

   sudo /etc/init.d/rundeckd restart

4. Attempt to logon

   If everything was configured correctly, you will be able to access RunDeck using your AD 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.8.1 Access control policy

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

Please read over this document for information on how to define it, and how to grant access for certain actions to certain resources:

• aclpolicy-v10(5)

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

description: Admin project level access control. Applies to resources within a specific project.
context:
  project: '.*' # all projects
for:
  resource:
    - equals:
        kind: job
      allow: [create] # allow create jobs
    - equals:
        kind: node
      allow: [read,create,update,refresh] # allow refresh node sources
    - equals:
        kind: event
      allow: [read,create] # allow read/create events
  adhoc:
    - allow: [run,kill] # allow running/killing adhoc jobs
  job: 
    - allow: [read,update,delete,run,kill] # allow read/write/delete/run/kill of all jobs
  node:
    - allow: [read,run] # allow read/run for all nodes
by:
  group: admin

---

description: Admin Application level access control, applies to creating/deleting projects, admin of user profiles, viewing projects and reading system information.
context:
  application: 'rundeck'
for:
  resource:
    - equals:
        kind: project
      allow: [create] # allow create of projects
    - equals:
        kind: system
      allow: [read] # allow read of system info
    - equals:
        kind: user
      allow: [admin] # allow modify user profiles
  project:
    - match:
        name: '.*'
      allow: [read,admin] # allow view/admin of all projects
by:
  group: admin

The example policy document above demonstrates the access granted to the users in group "admin".

Two separate policies define two levels of access control. The first is the "project" context, which allows access to actions on resources within a specific project. The second is the "application" level context, which allows access to things like creating projects, access to projects, managing users, and access to system information.

8.8.2 Specific Resources and Resource Types

As described in the aclpolicy-v10(5) definition, access is granted or denied to specific "resources". Resources can take two forms:

• A specific resource, with a type and properties
• Resource types, which applies to all resources of a specific type or "kind"

For example, you might want to restrict access to a job or jobs within a certain group. This corresponds to specific "job" resources with a "group" property matching a certain pattern.

You might also want to restrict who can create new jobs. Since a new job does not exist yet, you cannot create a rule for this action to apply to an existing job. Which means this corresponds to a generic resource with a "kind" called "job".

8.8.3 Special API Token Authentication group

Clients of the Web API may use the Token Authentication method. These clients are placed in the special authorization group called api_token_group.

api_token_group

Special role given to all API Token authenticated access.

8.8.4 RunDeck resource authorizations

RunDeck declares a number of actions that can be referenced inside the access control policy document.

The actions and resources are divided into project scope and application scope:

context:
  application: 'rundeck'

context:
  project: "(regex)"

for:
  resource:
    - equals:
        kind: 'project'
      allow: [create]

for:
  job:
    - equals:
        name: bob
      allow: [run]

description: Limited user access for adm restart action
context:
  project: '.*'
for:
  job:
    - equals:
        group: 'adm'
        name: 'Restart'
      allow: [run,read]
    - equals:
        group: 'adm'
        name: 'stop'
      allow: [run]
    - equals:
        group: 'adm'
        name: 'start'
      allow: [run]
by:
  group: [restart_user]

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

For each entry in the audit log, 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.8.6 Authorization caveats

• aclpolicy changes do not require a restart.

8.9.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.9.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.9.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.11.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.11.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.11.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.11.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. # Integration with External Data Providers

RunDeck can integrate with external data by configuring the use of Providers or Sources. Providers are third-party services or systems that export data that RunDeck can import. Additionally, RunDeck supports an external Editor for Node data.

RunDeck makes use of common data formats (XML, JSON & YAML). Third-party software may produce these formats natively, however it is typical to have to massage the output of one system into the appropriate format to be consumed by RunDeck. Since URLs and HTTP are a lowest-common-denominator for communication, RunDeck only requires that the data Providers make this data available as a file at a URL or on the local disk.

There are a few types of external integration:

Resource Model Source

Provides a set of Nodes in XML or YAML format. E.g. a CMDB or hosted virtual machines service. RunDeck can be configured to use a different provider for each Project, and can refresh the Resources it uses from this provider.

Resource Editor

Provides a web-based editor to manage the Node definitions. RunDeck can link to this editor from the Run page, and has optional JavaScript interactions to make editing externally-managed Node resources integrated with the RunDeck GUI.

Option Model Provider

Provides a dataset in JSON format, used as input option values for Jobs. Each Job Option can be configured to load the set of allowed input values from a remote service, and the RunDeck GUI will prompt the user to choose from those values when running a Job.

8.12.1 Requirements

In order to provide the Resource model data to RunDeck:

1. The data must be in one of the supported Resource Model Document Formats
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.

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.
• Using a Resource Model Source Plugin, the data could come from some other external source

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

8.12.2 Configuration

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

The only required configuration value is project.resources.file, which defines a single file containing resource model data stored on-disk. Each new project will have a good default location, but you may change either the location or the file extension. The file extension determines the format of the data. (See Resource Model Document Formats.)

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.

You may also specify a URL, which will be automatically retrieved and stored in a cache file. The Resource Model data within the content is merged with the previous file.

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

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

In addition, multiple Resource Model Source Plugin can be configured to add additional sources of Resource Model data.

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

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

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

8.13.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"}
] 

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

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

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

8.14.1 Definition

The RunDeck resource model document format and the resource-yaml-v13 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.

8.14.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, project

You can embed these properties within the url like this:

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

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

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

8.15.1 Execution Notification Content

The content of the POST request will be XML, with a single <notification> root element. This element will contain <executions..><execution>...</execution></executions> content. This inner content is of the same format as the XML returned from the Web API for Execution information. See the chapter API - Listing Running Executions for more information.

Attributes of the notification element will include:

trigger

The type of notification trigger. Either "success" or "failure".

executionId

The ID of the Execution

status

The result status of the Execution. Either "succeeded", "failed" or "aborted".

Example

<notification trigger="success" executionId="[ID]" status="[STATUS]">
    <executions count="1">
        <execution ...>
            ...
        </execution>
    </executions>
</notification>

8.15.2 Execution Notification Headers

The POST request will also contain several custom HTTP headers, providing another way to receive some of the webhook information:

X-RunDeck-Notification-Trigger

The notification trigger type, either "success" or "failure".

X-RunDeck-Notification-Execution-ID

The Execution ID

X-RunDeck-Notification-Execution-Status

The status of the execution, either "succeeded", "failed", or "aborted".

8.15.3 Execution Notification URL Token Expansion

As well, the URLs configured for the webhook notification may contain tokens that will be expanded with values taken from the associated job and execution, such as ${job.name}.

Available tokens for expansion are:

job.PROPERTY

Properties about the Job, including:

name

the Job name

group

The Job group, or a blank string

id

the Job Id

project

the Project name

execution.PROPERTY

Properties about the Execution, including:

id

The Execution ID

user

The user who executed the job

status

The execution status, one of "succeeded","failed",or "aborted"

notification.trigger

The trigger associated with the notification, one of "success" or "failure".

So for example, this URL:

http://server/callback?id=${execution.id}&status=${execution.status}&trigger=${notification.trigger}

Will have the tokens replaced with the appropriate values prior to making the webhook request.

10.4.1 Node Execution Plugins

These plugins define ways of executing commands on nodes, and copying files to nodes.

More information:

• Configuration: Node Execution Services
• Lifecycle: When Node Execution Service providers are invoked
• Built-in Providers: Node Execution services
• Included Plugins: Pre-installed plugins

10.4.2 Resource Model Source Plugins

These plugins define mechanisms for retrieving Resource Model information from a specific kind of source (such as a URL, file, or set of files in a directory).

More information:

• Configuration: Resource Model Sources
• Built-in Providers: Resource Model Sources

10.4.3 Resource Format Plugins

These plugins define parsers and generators for different document formats, and are used by the Resource Model Source Plugins, as well as other parts of the RunDeck system.

More information:

• Configuration: Resource Format Generators and Parsers
• Built-in Providers: Resource Format services

10.6.1 Node Execution Services

The two Node services, Node Executor and File Copier, are both configured similarly. They are configured for particular nodes on a node-specific basis, or set as a default provider for a project or for the system.

If multiple providers are defined the most specific definition takes precedence in this order:

1. Node specific
2. Project scope
3. Framework scope

remotehost:
    hostname: remotehost
    node-executor: stub
    file-copier: stub

service.NodeExecutor.default.local.provider=stub
service.FileCopier.default.local.provider=stub

10.6.2 Resource Model Sources

The Resource Model Sources providers can be configured for a single project in the project.properties file.

You can define multiple Resource Model Sources for the project, and can mix and match the specific providers depending on your needs.

When you define multiple Source providers in a project, then the resulting set of Nodes will effectively be a merge of all the sources, in the order in which they are declared. This means that if two or more Sources provide a definition of a node with the same name, then the definition from lowest Source in the list will be used.

The order that the providers are loaded (and thus the nodes are merged) is:

1. project.resources.file: A File Model Source with default configuration.
2. project.resources.url: A URL Model Source with default configuration. (optional)
3. All resources.source.N configurations in order starting at 1

resources.source.N.type=<provider-name>
resources.source.N.config.<property>=<value>
resources.source.N.config.<property2>=<value2>
...

project.resources.file=/home/rundeck/projects/example/etc/resources.xml

resources.source.1.type=url
resources.source.1.url=http://server/nodes.yaml

resources.source.2.type=directory
resources.source.2.directory=/home/rundeck/projects/example/resources

10.6.3 Resource Format Generators and Parsers

Resource Format Generators and Parsers define support for file formats that can be generated from or parsed into a set of Resource Node definitions.

These are used by other parts of the system, such as the Resource Model Sources.

There is no configuration necessary to use these providers, however the specific Provider Name that each generator and parser defines has to be known in order to make use of the provider. The specific Provider Name is used as the "format name" when you want to use the parser or generator.

For example, to enable a particular Resource Format parser to be used by a File Resource Model Source (see File Resource Model Source Configuration), you should specify the Provider Name for the parser as the format for the source:

resources.source.1.format=myformat

This would specify the use of "myformat" provider.

In other cases, the exact name of the provider may not be known (for example when loading content from a remote URL). Each Generator and Parser must define a list of MIME Type strings and file extensions that they support. These are used to determine which parser/generator is to be used.

10.8.1 Node Execution services

For NodeExecutor, these providers:

local

local execution of a command

jsch-ssh

remote execution of a command via SSH, requiring the "hostname", and "username" attributes on a node.

For FileCopier, these providers:

local

creates a local temp file for a script

jsch-scp

remote copy of a command via SCP, requiring the "hostname" and "username" attributes on a node.

10.8.2 Resource Model Sources

RunDeck includes these built-in providers in the core installation:

file

Uses a file on the file system, in any of the supported Resources formats.

url

GETs a URL, and expects one of the supported Resources formats.

directory

looks at all files in a directory for suppored file extensions, and internally uses the file provider for each file that matches.

script

Executes a script and parses the output as one of the supported formats

To configure these providers, refer to Resource Model Source configuration and use the following configuration properties.

resources.source.1.type=file
resources.source.1.file=/home/rundeck/projects/example/etc/resources2.xml
resources.source.1.format=resourcexml
resources.source.1.requireFileExists=true
resources.source.1.includeServerNode=true
resources.source.1.generateFileAutomatically=true

resources.source.1.type=url
resources.source.1.url=file:/home/rundeck/projects/example/etc/resources2.xml
resources.source.1.cache=true
resources.source.1.timeout=0

resources.source.2.type=directory
resources.source.2.directory=/home/rundeck/projects/example/resources

[interpreter] file [args]

resources.source.2.type=script
resources.source.2.file=/home/rundeck/projects/example/etc/generate.sh
resources.source.2.interpreter=bash -c
resources.source.2.args=-project example
resources.source.2.format=resourceyaml

10.8.3 Resource Format services

Resource Format services (Generators and Parsers) typically come in matched pairs, with both a parser and generator for the same format name.

RunDeck includes these built-in providers in the core installation:

resourcexml

Supports the Resource XML document format: resource-v13(5) XML.

Supported MIME types:

• Generator: "text/xml"
• Parser: "*/xml"

Supported File extensions:

• ".xml"

resourceyaml

Supports the Resource YAML document format: resource-v13(5) YAML.

Supported MIME types:

• Generator: "text/yaml", "text/x-yaml", "application/yaml", "application/x-yaml"
• Parser: "*/yaml", "*/x-yaml"

Supported File extensions:

• ".yml", ".yaml"

10.9.1 script-plugin

The script-plugin includes these providers:

• script-exec for the NodeExecutor service
• script-copy for the FileCopier service

(Refer to Using Providers to enable them.)

This plugin provides the ability to specify an external script or command to perform a remote or local execution of a Rundeck command, and remote or local file copies.

It can be a replacement for the built-in SSH-based remote execution and SCP-based file-copy mechanism to allow you to user whatever external mechanism you wish.

Note: this plugin offers similar functionality to the Script Plugin Development model. You may want to use this plugin to test your scripts, and then later package them into a standalone plugin using that model.

mynode:
    node-executor: script-exec
    script-exec: /bin/execremote -host ${node.hostname} -user ${node.username} -- ${exec.command}

mynode:
    node-executor: script-exec
    script-exec-shell: bash -c
    script-exec: ssh -o "some quoted option" ${node.username}@${node.hostname} ${exec.command}

script-exec.default.command= /bin/execremote -host ${node.hostname} \
    -user ${node.username} -- ${exec.command}

mynode:
    file-copier: script-copy
    script-copy: /bin/copyremote -host ${node.hostname} -user ${node.username} -- ${file-copy.file} ${node.destdir}

script-copy.default.command= /bin/copyremote -host ${node.hostname} -user ${node.username} -- ${file-copy.file} ${node.destdir}

mynode:
    file-copier: script-copy
    script-copy: /bin/copyremote -host ${node.hostname} -user ${node.username} -- ${file-copy.file} ${node.destdir}
    script-copy-remote-filepath: ${node.destdir}/${file-copy.filename}

script-copy.default.remote-filepath= ${node.destdir}/${file-copy.filename}

mynode:
    node-executor: script-exec

plugin.script-exec.default.command: /tmp/myexec.sh ${node.hostname} ${node.username} -- ${exec.command}

#!/bin/bash

# args are [hostname] [username] -- [command to exec...]

host=$1
shift
user=$1
shift
command="$*"

REMOTECMD=ssh

exec $REMOTECMD $user@$host $command

mynode:
    file-copier: script-copy
    destdir: /some/node/dir

plugin.script-copy.default.command: /tmp/mycopy.sh ${node.hostname} ${node.username} ${node.destdir} ${file-copy.file}

#!/bin/bash

# args are [hostname] [username] [destdir] [filepath]

host=$1
shift
user=$1
shift
dir=$1
shift
file=$1

name=`basename $file`

# copy to node
CPCMD=scp

exec $CPCMD $file $user@$host:$dir/$name > /dev/null || exit $?

echo "$dir/$name"

mynode:
    hostname: mynode
    username: user1
    node-executor: script-exec
    script-exec: ssh -o "StrictHostKeyChecking no" ${node.username}@${node.hostname} ${exec.command}
    script-exec-shell: bash -c
    file-copier: script-copy
    destdir: /tmp
    script-copy-shell: bash -c
    script-copy: scp ${file-copy.file} ${node.username}@${node.hostname}:${node.destdir}
    script-copy-remote-filepath: ${node.destdir}/${file-copy.filename}

# set default node executor
service.NodeExecutor.default.provider=script-exec

# set script-exec defaults
plugin.script-exec.default.command=ssh -o "StrictHostKeyChecking no" ${node.username}@${node.hostname} ${exec.command}
plugin.script-exec.default.shell=bash -c

#set default file copier
service.FileCopier.default.provider=script-copy

#set script-copy defaults
plugin.script-copy.default.command=scp ${file-copy.file} ${node.username}@${node.hostname}:${node.destdir}
plugin.script-copy.default.shell: bash -c
plugin.script-copy.default.remote-filepath: ${node.destdir}/${file-copy.filename}

mynode:
    hostname: mynode
    username: user1
    destdir: /tmp

10.9.2 stub-plugin

The stub-plugin includes these providers:

• stub for the NodeExecutor service
• stub for the FileCopier service

(Refer to Using Providers to enable them.)

This plugin does not actually perform any remote file copy or command execution, instead it simply echoes the command that was supposed to be executed, and pretends to have copied a file.

This is intended for use in testing new Nodes, Jobs or Workflow sequences without affecting any actual runtime environment.

You can also test some failure scenarios by configuring the following node attributes:

stub-exec-success="true/false"

If set to false, the stub command execution will simulate command failure

stub-result-code

Simulate the return result code from execution

You could, for example, disable or test an entire project's workflows or jobs by simply setting the project.properties node executor provider to stub.

11.1.1 Provider Classes

A "Provider Class" is a java class that implements a particular interface and declares itself as a provider for a particular RunDeck "Service".

Each plugin also defines a "Name" that identifies it for use in RunDeck. The Name of a plugin is also referred to as a "Provider Name", as the plugin class is a provider of a particular service.

You should choose a unique but simple name for your provider.

Each plugin class must have the "com.dtolabs.rundeck.core.plugins.Plugin" annotation applied to it.

@Plugin(name="myprovider", service="NodeExecutor")
public class MyProvider implements NodeExecutor{
...

Your provider class must have at least a zero-argument constructor, and optionally can have a single-argument constructor with a com.dtolabs.rundeck.core.common.Framework parameter, in which case your class will be constructed with this constructor and passed the Framework instance.

You may log messages to the ExecutionListener available via ExecutionContext#getExecutionListener() method.

You can also send output to System.err and System.out and it will be captured as output of the execution.

11.1.2 Jar Dependencies

If your Java classes require external libraries that are not included with the RunDeck runtime, you can include them in your .jar archive. (Look in $RDECK_BASE/tools/lib to see the set of third-party jars that are available for your classes by default at runtime).

Specify the Rundeck-Plugin-Libs attribute in the Main attributes of the Manifest for the jar, set the value to a space-separated list of jar file names as you have included them in the jar.

E.g.:

Rundeck-Plugin-Libs: lib/somejar-1.2.jar lib/anotherjar-1.3.jar

Then include the jar files in the Plugin's jar contents:

META-INF/
META-INF/MANIFEST.MF
com/
com/mycompany/
com/mycompany/rundeck/
com/mycompany/rundeck/plugin/
com/mycompany/rundeck/plugin/test/
com/mycompany/rundeck/plugin/test/TestNodeExecutor.class
lib/
lib/somejar-1.2.jar
lib/anotherjar-1.3.jar

11.1.3 Available Services:

• NodeExecutor - executes a command on a node
• FileCopier - copies a file to a node
• ResourceModelSource - produces a set of Node definitions for a project
• ResourceFormatParser - parses a document into a set of Node resources
• ResourceFormatGenerator - generates a document from a set of Node resources

11.2.1 Node Executor Providers

A Node Executor provider executes a certain command on a remote or local node.

Your provider class must implement the com.dtolabs.rundeck.core.execution.service.NodeExecutor interface:

public interface NodeExecutor {
    public NodeExecutorResult executeCommand(ExecutionContext context, 
        String[] command, INodeEntry node) throws ExecutionException;
}

A Node Executor can be me made Configurable on a per-project basis via the Web GUI by implementing the com.dtolabs.rundeck.core.plugins.configuration.Describable interface. It is up to your plugin implementation to use configuration properties from the FrameworkProject instance to configure itself. You must also be sure to return an appropriate mapping in the getPropertiesMapping method of the Description interface to declare the property names to be used in the project.properties file.

More information is available in the Javadoc.

11.2.2 File Copier Providers

A File Copier provider copies a file or script to a remote or local node.

Your provider class must implement the com.dtolabs.rundeck.core.execution.service.FileCopier interface:

public interface FileCopier {
    public String copyFileStream(final ExecutionContext context, InputStream input, INodeEntry node) throws
        FileCopierException;

    public String copyFile(final ExecutionContext context, File file, INodeEntry node) throws FileCopierException;

    public String copyScriptContent(final ExecutionContext context, String script, INodeEntry node) throws
        FileCopierException;
}

A File Copier can be me made Configurable on a per-project basis via the Web GUI by implementing the com.dtolabs.rundeck.core.plugins.configuration.Describable interface. It is up to your plugin implementation to use configuration properties from the FrameworkProject instance to configure itself. You must also be sure to return an appropriate mapping in the getPropertiesMapping method of the Description interface to declare the property names to be used in the project.properties file.

More information is available in the Javadoc.

11.2.3 Resource Model Source Providers

A Resource Model Source provider is actually a Factory class. An instance of your Resource Model Source provider will be re-used, so each time a new Resource Model Source with a new configuration is required, your Factory class will be invoked to produce it.

Your provider class must implement the com.dtolabs.rundeck.core.resources.ResourceModelSourceFactory interface:

public interface ResourceModelSourceFactory {
    /**
     * Return a resource model source for the given configuration
     */
    public ResourceModelSource createResourceModelSource(Properties configuration) throws ConfigurationException;
}

A Resource Model Source provider can also be Configurable via the Web GUI by implementing the com.dtolabs.rundeck.core.plugins.configuration.Describable interface. This allows you to return a descriptor of the configuration parameters for your plugin, which is used by the GUI to render a web form. The properties the user configures are stored in the project.properties configuration file, and are passed to your factory method as the configuration properties.

More information is available in the Javadoc.

11.2.4 Resource Format Parser and Generator Providers

Resource format Parser and Generator providers are used to serialize a set of Node resources into a textual format for transport or storage.

Each Parser and Generator must declare the set of filename extensions (such as "xml" or "json") that it supports, as well as the set of MIME types that it supports (such as "text/xml" or "application/json".) This lets other services retrieve the appropriate parser or generator when all that is known about the source or destination of serialized data is a filename or a MIME type.

For Parsers, your provider class must implement the com.dtolabs.rundeck.core.resources.format.ResourceFormatParser interface:

public interface ResourceFormatParser {
    /**
     * Return the list of file extensions that this format parser can parse.
     */
    public Set<String> getFileExtensions();

    /**
     * Return the list of MIME types that this format parser can parse. This may include wildcards such as
     * "*&#47;xml".
     */
    public Set<String> getMIMETypes();

    /**
     * Parse a file
     */
    public INodeSet parseDocument(File file) throws ResourceFormatParserException;

    /**
     * Parse an input stream
     */
    public INodeSet parseDocument(InputStream input) throws ResourceFormatParserException;
}

For Generators, your provider class must implement the com.dtolabs.rundeck.core.resources.format.ResourceFormatGenerator interface:

public interface ResourceFormatGenerator {

    /**
     * Return the list of file extensions that this format generator can generate
     */
    public Set<String> getFileExtensions();

    /**
     * Return the list of MIME types that this format generator can generate. If more than one
     * are returned, then the first value will be used by default if necessary.
     */
    public List<String> getMIMETypes();

    /**
     * generate formatted output
     */
    public void generateDocument(INodeSet nodeset, OutputStream stream) throws ResourceFormatGeneratorException,
        IOException;
}

More information is available in the Javadoc.

11.3.1 Provider metadata

Required provider entries:

• name - provider name
• service - service name, one of these valid services:
  • NodeExecutor
  • FileCopier
  • ResourceModelSource
• plugin-type - must be "script" currently.
• script-file - must be the name of a file relative to the contents directory

For ResourceModelSource service, this additional entry is required:

• resource-format - Must be the name of one of the supported Resource Model Document Formats.

Optional entries:

• script-interpreter - A system command that should be used to execute the script. This can be a single binary path, e.g. /bin/bash, or include any args to the command, such as /bin/bash -c.
• script-args - the arguments to use when executing the script file.

11.3.2 Configurable Resource Model Source Script Plugin

The ResourceModelSource service allows the plugins to be configured via the RunDeck Web GUI. You are thus able to declare configuration properties for your plugin, which will be displayed as a web form when the Project is configured, or can be manually configured in the project.properties file.

You can use these metadata entries to declare configuration properties for your plugin:

Create a config entry in each provider definition, containing a sequence of map entries for each configuration property you want to define. In the map entry include:

• type - The type of property. Must be one of:
  • String
  • Boolean must be "true" or "false"
  • Integer
  • Long
  • Select must be on of a set of values
  • FreeSelect may be one of a set of values
• name - Name to identify the property
• title - Title to display in the GUI (optional)
• description - Description to display in the GUI (optional)
• required - (true/false) if true, require a non-empty value (optional)
• default - A default value to use (optional)
• values - A comma-separated list of values to use for Select or FreeSelect. Required for Select/FreeSelect.

When your script is invoked, each configuration property defined for the plugin will be set as config.NAME in the data context passed to your script (see below).

Here is an example providers section for a Resource Model Source plugin that asks for two input properties from the user and produces "resourceyaml" formatted output:

providers:
    - name: mysource
      service: ResourceModelSource
      plugin-type: script
      script-interpreter: bash -c
      script-file: generate.sh
      resource-format: resourceyaml
      config:
        - type: Integer
          name: count
          title: Count
          description: Enter the number of nodes to generate
        - type: FreeSelect
          name: flavor
          title: Flavor
          description: Select a flavor
          required: true
          default: vanilla
          values: vanilla,blueberry,strawberry,chocolate

11.3.3 How script plugin providers are invoked

When the provider is used for node execution or file copying, the script file, interpreter, and args are combined into a commandline executed by the system in this pattern:

[interpreter] [filename] [args...]

If the interpreter is not specified, then the script file is executed directly, and that means it must be acceptable by the system to be executed directly (include any necessary #! line, etc).

script-args can contain data-context properties such as ${node.name}. Additionally, the specific Service will provide some additional context properties that can be used:

• NodeExecutor will define ${exec.command} containing the command to be executed
• FileCopier will define ${file-copy.file} containing the local path to the file that needs to be copied.
• ResourceModelSource will define ${config.KEY} for each configuration property KEY that is defined.

In addition, all of the data-context properties that are available in the script-args are provided as environment variables to the script or interpreter when it is executed.

Environment variables are generated in all-caps with this format:

RD_[KEY]_[NAME]

The KEY and NAME are the same as ${key.name}. Any characters in the key or name that are not valid Bash shell variable characters are replaced with underscore '_'.

Examples:

• ${node.name} becomes $RD_NODE_NAME
• ${node.some-attribute} becomes $RD_NODE_SOME_ATTRIBUTE
• ${exec.command} becomes $RD_EXEC_COMMAND
• ${file-copy.file} becomes $RD_FILE_COPY_FILE

11.3.4 Script provider requirements

The specific service has expectations about the way your provider script behaves:

• Exit code of 0 indicates success
• Any other exit code indicates failure

For NodeExecutor

All output to STDOUT/STDERR will be captured for the job's output

For FileCopier

The first line of output of STDOUT MUST be the filepath of the file copied to the target node. Other output is ignored. All output to STDERR will be captured for the job's output.

For ResourceModelSource

All output on STDOUT will be captured and passed to the p