# Configuration

# Configuration layout

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

# DEB/RPM layout

├── admin.aclpolicy
├── apitoken.aclpolicy
├── artifact-repositories.yaml
├── framework.properties
├── jaas-loginmodule.conf
├── log4j.properties
├── profile
├── project.properties
├── realm.properties
├── rundeck-config.properties
├── rundeckpro-license.key
├── ssl
│   ├── ssl.properties
│   ├── keystore (not packaged)
│   └── truststore (not packaged)
├── system-job_reader.aclpolicy_template
├── system-job_runner.aclpolicy_template
├── system-job_viewer.aclpolicy_template
├── system-job_writer.aclpolicy_template
└── system-project_admin.aclpolicy_template

├── bootstrap
├── data
├── libext
├── logs
├── projects
├── repository
├── var
└── work

# Launcher layout

├── admin.aclpolicy
├── apitoken.aclpolicy
├── framework.properties
├── preferences.properties
├── profile
├── profile.bat
└── project.properties

├── artifact-repositories.yaml
├── jaas-loginmodule.conf
├── log4j.properties
├── realm.properties
├── rundeck-config.properties
└── ssl.properties

# Configuration files

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

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

# admin.aclpolicy

Administrator access control policy defined with a aclpolicy document.

This file governs the access for the "admin" group and role.

See role based access control for information about setting up policy files for other user groups.

# framework.properties

Configuration file used by shell tools and core Rundeck services. This file will be created for you at install time.

Some important settings:

  • framework.server.hostname: Hostname of the Rundeck server node
  • framework.server.name: Name (identity) of the Rundeck server node
  • framework.projects.dir: Path to the directory containing Rundeck Project directories. Default is $RDECK_BASE/projects.
  • framework.var.dir: Base directory for output and temp files used by the server and CLI tools. Default is $RDECK_BASE/var.
  • framework.logs.dir: Directory for log files written by core services and Rundeck Server's Job executions. Default is $RDECK_BASE/var/logs
  • framework.server.username: Username for connection to the Rundeck server
  • framework.server.password: Password for connection to the Rundeck server
  • framework.rundeck.url: Base URL for Rundeck server.

SSH Connection settings (See Projects - Node Execution - SSH):

  • framework.ssh.keypath: Path to the SSH private key file used for SSH connections
  • framework.ssh.user: Default username for SSH Connections, if not overridden by Node specific value.
  • framework.ssh-connection-timeout: timeout in milliseconds for SSH connections. The default is "0" (no timeout). You can modify this to change the connect/socket timeout. (Deprecated: framework.ssh.timeout.)
  • framework.ssh-command-timeout: timeout in milliseconds for SSH commands. The default is "0" (no timeout). You can modify this to change the maximum time allowed for SSH commands to run.

Other settings:

  • rundeck.server.uuid: This is used to manually specify the server UUID for certain cluster and licensing needs.
  • framework.log.dispatch.console.format: Default format for non-terse node execution logging run by the dispatch CLI tool.
  • execution.script.tokenexpansion.enabled: Whether inline script token expansion is enabled, default true. If false, the "Inline Script Content" syntax described in User Guide - Creating Job Workflows - Context Variables is disabled.
  • communityNews.disabled: Default is not set, or false. Disables the external polling of Community News feed. Link will persist but will not poll, and clicking this link will open a new browser tab and navigate to the web-based version of Community News.

Static authentication tokens for API access:

You can define the location of a .properties file in framework.properties:

  • rundeck.tokens.file=/etc/rundeck/tokens.properties

The tokens.properties file should contain static authentication tokens you wish to use, keyed by the associated username. You MUST also specify the role of the user:

username: token_string, role1
username2: token_string1;token_string2, role2

The token_strings can be used as Authentication tokens to the API.

To ease the rotation of tokens, several tokens can be specified by separating them with a semicolon.

# Global execution variables

Entries in framework.properties in the form framework.globals.X=Y Adds a variable X available in all execution contexts as ${globals.X}.

Global variables can be overridden in the project.properties by adding a line in the form of project.globals.X=Y and then accessing it as ${globals.X}.

# log4.properties - Legacy

Rundeck uses log4j (opens new window) as its application logging facility. This file defines the logging configuration for the Rundeck server.

# log4j2.properties - New in Rundeck 3.3.x

Rundeck uses log4j2 (opens new window) as its application logging facility. This file defines the logging configuration for the Rundeck server.

# Upgrading to log4j 2


If you have custom plugins that used log4j 1.x or logback to do logging, you will need to upgrade them to use slf4j logging apis or log4j2 logging apis.

If you are using the launcher or war in a container, the first time you run Rundeck 3.3.x a log4j2.properties file will be created for you.
If you are using the rpm or deb package a log4j2.properties file should be added to your configuration directory when you upgrade the package. If you have customized your old log4j.properties file you will need to ensure that it complies to the log4j2 format, then you can rename it to log4j2.properties in your configuration directory

Please refer to the log4j2 documentation (opens new window) to see how to update your old log4j.properties to be compliant with the new log4j2 format.

# profile

Shell environment variables used by the shell tools. This file contains several parameters needed during the startup of the shell tools like umask, Java home and classpath, and SSL options.

# project.properties

Rundeck project configuration file when using Filesystem based project definitions (see Project Setup - Project Definitions (opens new window)).

One of these is generated at project setup time. Each project has a directory within the Rundeck projects directory, and the config file is within the etc subdirectory:

Property Description
project.name Declare the project name.
project.ssh-authentication SSH authentication type (eg, privateKey).
project.ssh-keypath Load SSH identify file. (Note: this is not a keystorage path but a local file system path.)
service.FileCopier.default.provider Default script file copier plugin.
service.NodeExecutor.default.provider Default node executor plugin.
resources.source.N... Defines a Resource model source see Resource Model Sources.
project.globals.X Defines a Project Global variable

Here's an example that configures a File source:


Another that configures a URL source:


And one that configures a Directory source:


Additional sources increment the source number. You can reference the project name by using the ${project.name} context variable.

# File copier destination directory

When executing a Script step, the destination file path to be used when copying the script can be set using Node, Project, or Framework configuration values. Please see the plugin documentation (opens new window)

# Project Global execution variables

Project configuration entries of the form project.globals.X=Y Adds a variable X available in all execution contexts as ${globals.X}, and overrides any global with the same name defined in framework.properties.

# jaas-loginmodule.conf

JAAS (opens new window) configuration for the Rundeck server. The listing below shows the file content for a normal RPM installation. One can see it specifies the use of the PropertyFileLoginModule:

RDpropertyfilelogin {
  org.eclipse.jetty.plus.jaas.spi.PropertyFileLoginModule required

# realm.properties

Property file user directory when PropertyFileLoginModule is used. Specified from jaas-loginmodule.conf.

# Session timeout

See rundeck-config.properties > Server Settings

Or set server.servlet.session.timeout via System Properties Configuration.

# rundeck-config.properties

This is the primary Rundeck webapp configuration file. Defines default loglevel, datasource configuration, and GUI customization.

The following sections describe configuration values for this file.

# Live Configuration Refreshing (Enterprise)

You can make changes in the rundeck-config.properties file and then get Rundeck to reload the config without having to restart.
The following steps give the process for live reloading:

  • Make the change to the property
  • Save the rundeck-config.properties file
  • Issue an http POST request to the api endpoint /api/36/config/refresh


Live reloading only works with a small set of properties at this time. Any properties that affect services, storage, or the http server still require the server to be restarted to take effect.

Some of the properties that work with live reloading:

  • All Rundeck remote execution policy settings (e.g. rundeck.clusterMode.remoteExecution.*)
  • rundeck.security.ldap.bindPassword
  • rundeck.gui.login.welcomeHtml
  • rundeck.gui.instanceName

# Security

  • rundeck.security.useHMacRequestTokens : true/false. Default: true. Switches between HMac based request tokens, and the default grails UUID tokens. HMac tokens have a timeout, which may cause submitted forms or actions to fail with a message like "Token has expired". If set to false, UUIDs will be used instead of HMac tokens, and they have no timeouts. The default timeout for tokens can be changed with the java system property -Dorg.rundeck.web.infosec.HMacSynchronizerTokensHolder.DEFAULT_DURATION=[timeout in ms].

  • rundeck.security.apiCookieAccess.enabled: true/false. Default: true. Determines whether access to the API is allowed if the API client authenticates via session cookies (i.e. username and password login.) If set to false, the current CLI tools and API libraries will not operate correctly if they use username and password login.

  • rundeck.api.tokens.duration.max: Duration string indicating maximum lifetime of API Tokens. If unset, the value will be "30d" (30 days). Format: "##{ydhms}" (years, days, hours, minutes, seconds). If you want to disable the max expiration you can set it to 0 and create token with 0 duration that don't expire.

  • rundeck.security.csrf.referer.filterMethod:NONE|POST|*. Set HTTP Method to filter based on Referer header. Can be POST, or "*" for all methods. Default: NONE (disabled)

  • rundeck.security.csrf.referer.allowApi: true|false. Allow /api/* requests without requiring matching Referer header. Default: true.

  • rundeck.security.csrf.referer.requireHttps: true|false. If server URL is HTTPS, Require referer header to be from HTTPS version of server URL, if false allow HTTP as well. Default: true.

  • rundeck.security.enforceMaxSessions: true|false. Only allow users to log in a configured number of times. Oldest sessions are automatically logged out. Default: false.

    Note: If you use the rd tool with the RD_USERNAME/RD_PASSWORD authentication this will use an active session each time your run the command. If you log into the user interface then execute rd commands you could be logged out of your web session. If you have multiple long running rd commands and you exceed the maxSessions limit, you may experience unexpected behavior. If you use api tokens with the rd tool it will not log out your interactive session. If you enable this setting and also use the rd tool, it is recommended that you use api tokens with the rd tool.

  • rundeck.security.maxSessions: If enforceMaxSessions is true, this setting controls the number of active sessions a user is allowed to have. Default: 1

  • rundeck.security.jaasRolePrefix: Prefix string to add to each role determined via JAAS Authentication. Default: none.

  • rundeck.security.requiredRole: roleName. If this property is set, all users must be a member of the role specified.

  • rundeck.security.dblogin.enabled: true|false. (Enterprise) This option is enabled by default in version 3.3.0 to allow creation of local Rundeck users. More Info

  • rundeck.security.dblogin.createAdminUserAndRoles: true|false. Enabling this feature adds the admin user and roles . (See rundeck.security.dblogin.enabled) Default is false so that no admin user or role is created by default.

  • rundeck.security.dblogin.adminUsername: [String] The user name for the admin account that is created if the createAdminUserAndRoles value is set to true. Default is rdadmin.

  • rundeck.security.dblogin.adminPassword: [String] A password value for the admin user created above. If this entry is left blank or missing a password will be generated on boot of Rundeck. The printed message will look like this:

*                                  *
*     <<RANDOMSTRING>>             *
*                                  *

# Security HTTP Headers


The HTTP header 'XSS-Protection' has been deprecated by modern browsers and it use can introduce additional security issues on the client side of the application. Rundeck has deprecated this setting as of version 4.3.0.

Rundeck adds some HTTP headers for XSS prevention and other security reasons, as described below.

By default, these headers are enabled, but they can be individually disabled, or reconfigured.

Additionally, custom headers can be enabled if required.

# enable security headers filter to add these headers (default: true)

# enable x-content-type-options: nosniff  (default: true)

# enable x-frame-options: deny  (default: true)


# Alternate settings for x-frame-options:
# use x-frame-options: sameorigin

# rundeck.security.httpHeaders.provider.xfo.config.sameorigin=true

# use x-frame-options: allow-from: src

# rundeck.security.httpHeaders.provider.xfo.config.allowFrom=src

# enable Content-Security-Policy header (default:true)


# You can enable the `X-` variants of Content-Security-Policy if desired, but they are disabled by default:
# This enables the X-Content-Security-Policy header name

# rundeck.security.httpHeaders.provider.csp.config.include-xcsp-header=true

# This enables the X-WebKit-CSP header name

# rundeck.security.httpHeaders.provider.csp.config.include-xwkcsp-header=true

# You can specify an explicit policy, which will override directives declared below

# rundeck.security.httpHeaders.provider.csp.config.policy=default-src 'none'; connect-src 'self' ; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; font-src 'self' data: ; img-src 'self' https://media.rundeck.org ; form-action 'self' ;

# Or you can specify individual directives:

rundeck.security.httpHeaders.provider.csp.config.style-src=self unsafe-inline
rundeck.security.httpHeaders.provider.csp.config.script-src=self unsafe-inline unsafe-eval
rundeck.security.httpHeaders.provider.csp.config.font-src=self data:
rundeck.security.httpHeaders.provider.csp.config.img-src=self https://media.rundeck.org

# enable any custom additional headers (default: false)
# rundeck.security.httpHeaders.provider.custom.enabled=true
# rundeck.security.httpHeaders.provider.custom.config.name=X-Other-Security-Policy
# rundeck.security.httpHeaders.provider.custom.config.value=default-src 'none';
# rundeck.security.httpHeaders.provider.custom.config.name2=X-other-header
# rundeck.security.httpHeaders.provider.custom.config.value2=some value


# Security HTTP Firewall

The Spring Security StrictHttpFirewall (opens new window) allows the Rundeck Application to validate HTTP requests based on their headers, URL and body. Any invalid request will be rejected with a BAD REQUEST 400 error. To enable use the following setting below in framework.properties or Configuration Management.

  • rundeck.security.httpFirewall.enabled:true/false. Default false

# Host Head Injection Attack (opens new window) Protection

To protect the web application from Host Header Injection attacks it is possible to add a list of trusted hosts:

  • rundeck.security.httpFirewall.allowedHostnames:Comma separated hostnames

The value for this parameter should be a string of comma separated hostnames. E.g.

rundeck.security.httpFirewall.allowedHostnames = localhost,, www.example.com 

The hostname derived from the grails.serverURL parameter is always trusted so there is no need to configure it explicitly.

System Admin needs to configure the trusted hostnames based on the deployment strategy. For example:

  1. If the Rundeck Application Server is exposed directly through a domain name (e.g. my.domain.name) or IP address, the domain name or IP address must be added into the allowedHostName list
  2. If the Rundeck Application Server is exposed through a reverse proxy or load balancer which overwrites the HTTP Host head, then Host head value provided by reserve proxy and load balancer should be added into the allowedHostName list.

# Local Login Form Visibility

  • rundeck.login.localLogin.enabled:true/false. Default true

If you have Single Sign On enabled(Enterprise only) and you want to prevent the ability for your users to login with the non-SSO form, you can set this property to false and it will suppress the non-SSO login form.

# Logout behaviors

  • rundeck.logout.expire.cookies: comma separated list of cookie names to expire on logout

  • rundeck.logout.redirect.url: Redirect to this url after logout. This can either be a fully qualified url or a relative path.

# Server Settings

  • server.servlet.session.timeout: timeout in seconds.

Note: This setting applies only to the embedded Jetty server, which is used for standalone war launcher, rpm or deb installs. It does not work for Tomcat installation.

If you are deploying the Rundeck war file to Tomcat, you can manage the session timeout setting in the $TomcatBase/conf/web.xml file. The setting is in minutes.

    <session-config> <session-timeout>30</session-timeout> </session-config>

# Multi-URL Setting

Make sure the grails.serverURL is specified (with or without server.servlet.context-path), Set rundeck.multiURL.enabled=true and access the service through grails.serverURL using a secondary DNS pointing to the same server, the server IP, etc.

  • Each of accessed urls will ask for login and password
  • The address in navigation bar will not change
  • Notifications will use grails.serverURL

# Primary Server Id (optional)

If you are running Rundeck in a cluster set up you'll want to set one of the servers as the primary server. Once set as primary, that server will be the one that applies any data updates that might need to be run on bootstrap. If no server is set as primary in a cluster set up, then all servers will try to apply the updates on startup. This can lead to record contention in the database that will cause the updates to fail.

To set a server as primary set the server UUID in the property: rundeck.primaryServerId


# Execution Mode

  • rundeck.executionMode:active/passive. Default active. Set the Execution Mode for the Rundeck server.

Rundeck can be in active or passive execution mode.

  • active mode: Jobs, scheduled Jobs, and adhoc executions can be run.
  • passive mode: No Jobs or adhoc executions can be run.

Setting Rundeck to passive mode prevents users from running anything on the system and is useful when managing Rundeck server clusters.

# Project Configuration Storage settings

The Project Setup - Project Definitions mechanism is configured within this file, see:

# Key Storage settings

The Key storage mechanism is configured within this file, see:

# Notification email settings

See Email Settings: Notification email settings

# Custom Email Templates

See Email Settings: Custom Email Templates

# Execution finalize retry settings

If a sporadic DB connection failure happens when an execution finishes, Rundeck may fail to update the state of the execution in the database, causing the execution to appear is if it is still "running".

Rundeck now attempts to retry the update to correctly register the final state of the execution. You can tune how many times and how often this retry occurs with these config values:

# attempt to retry the final state update

# attempt to retry updating job statistics after execution finishes

Delay is in milliseconds. If a max is set to -1, then retries will happen indefinitely.

# Execution log settings

You can globally specify for all your jobs (regardless of which project they belong to) a log size limit and action as needed. If a job is configured with other values, the process will take the minimum value for output limit and prioritize "Halt" over "Truncate".

rundeck.execution.logs.output.limit = 5MB
rundeck.execution.logs.output.limitAction = truncate
  • rundeck.execution.logs.output.limit. Show an error when that limit is exceeded. Could be entered either maximum total line-count (e.g. "100"), maximum per-node line-count ("100/node"), or maximum log file size ("100MB", "100KB", etc.), using "GB","MB","KB","B" as Giga- Mega- Kilo- and bytes.
  • rundeck.execution.logs.output.limitAction. Is the action applied when the limit is achieved. It is triggered only if there is a value at rundeck.execution.logs.output.limit. The values accepted are ‘truncate' or 'halt’. The default value if it does not set is 'halt'.
    • a. halt: kills the step and leave the job with status 'failed'.
    • b. truncate: the step will not stop, but no more log output will be generated.

# Metrics Capturing

Rundeck captures metrics using the Metrics (opens new window) library.

You can disable all metrics capturing with:


Additional configuration for metrics:

# capture metrics for requests via a filter

# use JMX

# Metrics API Endpoints

Rundeck exposes Metrics data via API endpoints, which are enabled by default.

You can disable all metrics API endpoints with:


You can also selectively disable each endpoint by setting these config values:


Metrics names are:

  • metrics
  • threads
  • ping
  • healthcheck

See: API > List Metrics.

# Pagination defaults

Default paging size for the Activity page and results from execution API queries can be changed.


# Job Remote Option URL connection parameters

Change the defaults for for Job Remote Option Value URLs loading.

Socket read timeout

Max wait time reading from socket.

Default value: 10 (seconds)

Change this by setting:


Connection timeout

Max wait time attempting to make the connection.

Default value: (no timeout)

Change this by setting:


No response retry

If the request is sent, but the server disconnects without a response (e.g. server is overloaded), retry the request this many times.

Default value: 5

Change this by setting:


# Job File Option Uploads

Values to configure file uploads for File type Job options:

Max temp file size. File size in bytes or with a suffix of k,m,g,t (kilo,mega,giga,tera).


Max controller file size. File size in bytes. In example: 4096000000 is equivalent to 4g.


Max temp file expiration (duration in milliseconds). The uploaded file will be removed if not used as a job option within ths time period. (This primarily affects Job executions performed via API because the File Upload and Job Run are performed as separate steps.)

# default is 10 minutes

If you need to use large files, make sure your JVM settings have enough free memory to handle it.

For 1GB ~ 2GB files, is recommended to set:

java -Xms4g -Xmx8g -jar rundeck.war


It is also possible to reconfigure the default path for files according to this page using the property in this form:


'''NOTE: In a clustered mode it is important to note that this option, by default, will only upload the file to a single cluster member (whichever server you are uploading the file on). It is recommended to set the desired path to a directory that is shared across all cluster members. (e.g. NFS share mounted on same server path location to each server) By doing so, when a file is uploaded, it will be available for all cluster members.

# Job YAML format

In order to get a human readable export of a Job, all of the line endings in the workflow scripts must not end with a space. Otherwise the YAML exporter will resort to a format the preserves the exact line spaces, but is not as human readable. The following setting will trim all line endings in the job's workflow scripts so that the YAML exporter produces a nice human readable document.


# Load balancer Health endpoint

The endpoint /health will respond with 200 OK without authentication.

You can disable this behavior using a feature flag.

Node Balancer Health endpoint feature flag

# Node Cache

Defaults for the Node caches

Enabled: true/false (default true).
rundeck.nodeService.nodeCache.enabled=true If set to false, no caching is performed.
First Load Asynch: true/false
rundeck.nodeService.nodeCache.firstLoadAsynch=false The default for whether the first load of a project's nodes should be performed synchronously or not. If set to true, and the Project Nodes > Synchronous First Load value is unset, then the initial load of a Project's nodes when the cache is empty will be done in the background asynchronously. Otherwise the initial load is done synchronously, possibly causing a delay at Rundeck startup or Job execution startup. A Project level configuration value will override this default.

# Limit displayed Job execution Log Output

Limit the amount of lines displayed in Log Output when following the execution of a Job that is running (not finished yet) after a configurable limit has been reached. If the value is not defined, default behavior is to display all the generated output

Trim Output: Max size of visible Log Output (not present by default).
rundeck.logviewer.trimOutput=250kb Remove the oldest lines in Log Output after displaying 250kb of logs

# Groovy config format

If you would prefer to use Groovy for the config file, you can use rundeck-config.groovy instead of rundeck-config.properties. Or, you can use a combination of the two (i.e. some settings configured in the properties file and some in the Groovy file).

The groovy format is a java-like language, and it is not the same as properties.

Make sure you put quotes around all string values, but it is not necessary for true/false or numbers.

java properties format:


groovy format:


You can also use nested values using curly brackets, or use dot-notation "a.b.c", but since it is not simple text properties, strings have to be quoted.

E.g. : a.b.c="blah" is the same as:


# Specify config file location

You will need to point rundeck at the new filename when you start up rundeck:

  • Launcher:

      java -jar -Drundeck.config.name=rundeck-config.groovy rundeck-launcher.jar

RPM: Add this to the /etc/sysconfig/rundeckd file:

    export RDECK_CONFIG_FILE="/etc/rundeck/rundeck-config.groovy"

RPM/DEB: Add this to the /etc/default/rundeckd file:

    export RDECK_CONFIG_FILE="/etc/rundeck/rundeck-config.groovy"