Skip to main content



Configuration layout

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

DEB/RPM layout

├── admin.aclpolicy
├── apitoken.aclpolicy
├── artifact-repositories.yaml
├── jaas-loginmodule.conf
├── profile
├── rundeckpro-license.key
├── ssl
│   ├──
│   ├── 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
├── profile
├── profile.bat

├── artifact-repositories.yaml
├── jaas-loginmodule.conf

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.


Administrator access control policy defined with a aclpolicyopen in new window 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.

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
  • 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.server.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:


Make sure your $RDECK_BASE environment variable is pointed correctly to your current installation, otherwise the tokens wont be loaded in runtime.

You can define the location of a .properties file in

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

The 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 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 by adding a line in the form of project.globals.X=Y and then accessing it as ${globals.X}. - Legacy

Rundeck uses log4jopen in new window as its application logging facility. This file defines the logging configuration for the Rundeck server. - New in Rundeck 3.3.x

Rundeck uses log4j2open in 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 file will be created for you.
If you are using the rpm or deb package a file should be added to your configuration directory when you upgrade the package. If you have customized your old file you will need to ensure that it complies to the log4j2 format, then you can rename it to in your configuration directory

Please refer to the log4j2 documentationopen in new window to see how to update your old to be compliant with the new log4j2 format.


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.

Rundeck project configuration file when using Filesystem based project definitions (see Project Setup - Project Definitionsopen in 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:

project.nameDeclare the project name.
project.ssh-authenticationSSH authentication type (eg, privateKey).
project.ssh-keypathLoad SSH identify file. (Note: this is not a keystorage path but a local file system path.)
service.FileCopier.default.providerDefault script file copier plugin.
service.NodeExecutor.default.providerDefault node executor plugin.
resources.source.N...Defines a Resource model source see Resource Model Sourcesopen in new window.
project.globals.XDefines 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:${}/site_nodes

Additional sources increment the source number. You can reference the project name by using the ${} 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 documentationopen in 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


JAASopen in 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 { required

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

Session timeout

See > Server Settings

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

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 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 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.gui.login.welcomeHtml
  • rundeck.gui.instanceName


  • : 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].

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

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

  • true|false. Allow /api/* requests without requiring matching Referer header. Default: true.

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

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

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

  • rundeck.feature.debug.showTracesOnResponse : true/false. Default: false. The default behavior is to never return 5xx http responses with any stacktrace in it to hide specific information regarding the backend (stacktraces are only present on the log files).

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

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

  • true|false. (Enterprise) This option is enabled by default in version 3.3.0 to allow creation of local Rundeck users. More Infoopen in new window

  • true|false. Enabling this feature adds the admin user and roles . (See Default is false so that no admin user or role is created by default.

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

  • [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


# use x-frame-options: allow-from: 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


# This enables the X-WebKit-CSP header name


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

# 'none'; connect-src 'self' ; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; font-src 'self' data: ; img-src 'self' ; form-action 'self' ;

# Or you can specify individual directives:
# unsafe-inline unsafe-inline unsafe-eval data:

# enable any custom additional headers (default: false)
# 'none';
# value


Security HTTP Firewall

The Spring Security StrictHttpFirewallopen in 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 or Configuration Management.

  • Default false

Host Head Injection Attackopen in new window Protection

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

  • separated hostnames

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

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

In order to add the HSTS (HTTP Strict Transport Security) security header to the static resources of Rundeck, the configuration must be set directly on the server. The following two flags are used for the embedded Jetty server:

  • rundeck.web.jetty.servlet.stsMaxAgeSeconds: time in seconds.

  • rundeck.web.jetty.servlet.stsIncludeSubdomains : true/false. Default false

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.

Logviewer Max Size:

The maximum size for the logs viewed in the GUI can be set with the following property:


If the log file is larger than this value, the log viewer will display a "Whale Log" message indicating that the log is too large to display:

Whale Log

The default value for this property is 3MB.

Metrics Capturing

Rundeck captures metrics using the Metricsopen in 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:[seconds]

Connection timeout

Max wait time attempting to make the connection.

Default value: (no timeout)

Change this by setting:[seconds]

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:[total]

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 pageopen in new window 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 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:"value"

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 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"