Skip to main content

Email Settings

Email Settings

This document describes how to configure Rundeck for email support. Email settings are located in the rundeck-config.properties file. Depending on the installer used, the configuration files will be under a base directory:

  • RPM/DEB: /etc/rundeck/rundeck-config.properties
  • Launcher: $RDECK_BASE/server/config/rundeck-config.properties

Refer to the appropriate configuration file paths from Configuration -> Configuration Layout to locate the Rundeck configuration paths depending on your install.

SMTP server settings

By default the plugin assumes an unsecured mail server configured at localhost on port 25. You can specify your own with these settings:

grails.mail.host=localhost
grails.mail.port=25

To add authentication:

grails.mail.username=user
grails.mail.password=pass

Advanced SMTP settings

If you need more advanced configuration (e.g., authenticated and secured over SSL), see the grails Mail plugin configuration: Grails Mail Configurationopen in new window

Tips

For the extended configuration properties, it needs to be appended to the property prefix grails.mail.props.<key_props>. For example, to enable starttls, the property should be grails.mail.props.mail.smtp.starttls.enable=true

Notification email settings

The URL and From: address used in Job email notifications are managed via the settings located in the rundeck-config.properties file.

The two properties are:

  • grails.serverURL
  • grails.mail.default.from

Here's an example:

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

Custom Email Templates

You can define these properties to customize the email notifications. Each property can be defined for a specific Trigger, or for the general case. Available triggers are: success,failure, and start. In addition, you can have custom settings for a project and job name combination as well:

# trigger-specific templating
rundeck.mail.[trigger].template.subject=[custom subject line]
rundeck.mail.[trigger].template.file=[path to template file]
rundeck.mail.[trigger].template.log.formatted=true/false (if true, prefix log lines with context information)

# project and job specific
rundeck.mail.[project].[jobname].template.subject=[custom subject line]
rundeck.mail.[project].[jobname].template.file=[path to template file]
rundeck.mail.[project].[jobname].template.log.formatted=true/false (if true, prefix log lines with context information)

# apply to any triggers not specified
rundeck.mail.template.subject=[Default subject line]
rundeck.mail.template.file=[path to template file]
rundeck.mail.template.log.formatted=true/false (if true, prefix log lines with context information)

If a template filepath ends with .md or .markdown, then it will be interpreted as a Markdown formatted template. Otherwise it is expected that the template file contains HTML.

The Subject line, filepath, and file contents can all contain embedded property references of the form ${group.key}. The available properties are mostly the same as those available for Notification Plugins, including the execution.* and job.* values. See Plugin Developer Guide - Notification Plugin - Execution Data.

The "Context Variables" values used within the execution are available just as they are in the execution, so options would be available as ${option.name}.

In addition these properties are defined:

  • rundeck.href: URL to the Rundeck server
  • notification.trigger: Trigger name
  • notification.eventStatus: A string indicating the combination of execution status, and notification trigger, suitable for an email subject line, such as "KILLED", "FAILURE", "STARTING", "SUCCESS".
  • execution.projectHref: URL to the Project within Rundeck.

Custom Attached Log Output file

When the log output is attached as a file, the file's extension can be defined by adding new settings on rundeck-config.properties. For example:

rundeck.mail.template.log.extension=html
rundeck.mail.template.log.contentType=text/html

rundeck.mail.<PROJECT>.<JOBNAME>.template.log.extension=csv
rundeck.mail.<PROJECT>.<JOBNAME>.template.log.contentType=text/csv

rundeck.mail.<TRIGGER>.template.log.extension=html
rundeck.mail.<TRIGGER>.template.log.contentType=text/html

Troubleshooting

See the service.log for mail error messages.