Access the Configuration

To access Contrast configuration options, log in to the Administrative interface and then click on the Settings menu in the navigation bar. Most of the Contrast application's configuration is handled through the configuration menu.

Note: Database settings aren't available after 3.1.0 since the database is embedded and managed outside of the Contrast application.

Authentication Settings

To access the Authentication Settings in Contrast, click on Settings in the navigation bar and then the Authentication tab in the sidebar.

For more information on changing Authentication Settings, go to the Authentication Overview article.

Authentication modes

More Information

Distributed Configuration

About Distributed Configuration

This guide is for Enterprise-On-Premises (EOP) administrators who want to move away from the bundled, self-contained Contrast configuration in favor of a distributed configuration, in which the database and application server are deployed on separate servers. Customers who fit this profile are likely running with 100 or more connected agents, seeking greater performance and scalability, and require additional administration and management by an EOP administrator. (These configurations are introduced in Contrast 3.3.2.) Contrast simplified the configuration of the application for EOP administrators to run their own installations of Tomcat, Java and MySQL, as long as they conform to our version requirements.

Note: While the following instructions guide you through the setup and configuration of additional software, be aware that you're responsible for the monitoring and durability of this software. If you're familiar with installing and administering MySQL and Tomcat, the process is easy to set up and maintain.

EOP customers typically install and update the Contrast application by downloading the installer/updater artifact from the Contrast Hub. This artifact is an executable file that includes all the necessary software and components to install, upgrade and run Contrast. The Contrast application is designed for all embedded components and storage to reside on a single server in a very basic, monolithic configuration.

Before You Get Started

Before you get started configuring a distributed Contrast application, make sure to read through the entire document and complete the following steps before distributing the configuration:

  • Previous installation of Contrast EOP using the provided installer artifact from Hub
  • Successful backup(s) and exports of the Contrast database
  • Installation, configuration and administration of MySQL
  • Installation, configuration and administration of Tomcat
  • Installation, configuration and administration of Java

If you need to go back and set up Contrast again, click here.

Deploy the Distributed Configuration

There are two steps for deploying a distributed Contrast configuration:

  • Step 1: Database (MySQL)
  • Step 2: Application Server (Tomcat)

Contrast provides several code samples using Ansible, an automation framework, as well as Ubuntu that you can use as a starting point for your own configuration. While you may need to make some slight changes to these scripts to run against other operating systems, rest assured that the configuration runs on all platforms supported by Contrast.

Step 1: Separate the Database

With a few changes, you can utilize an external MySQL database - an open-source database that runs on both Windows and Linux - with your existing EOP installation. Complete the following steps:

Install and configure the MySQL Server

Contrast recommends running the application with versions of MySQL as shown in our System Requirements. Contrast also recommend working with your Operations and/or Database team to ensure a secure and durable installation.

Note: Go to the Github repository for a snippet of Ansible that you can use to install the MySQL on Ubuntu 14.04.

You can download the gpg keyfile and additional information from the MySQL documentation. Contrast changes the bind address to "*" above for illustration, but recommends binding your MySQL server to the IP of your application server. Contrast recommend creating a user and grants that offer access to only the Contrast schema and limited to the host IP address or subnet.

Take a backup of MySQL

To back up your database, you can use the embedded tool with your EOP installation:


Move this backup to the external MySQL database host and make a note of the path.

Restore the database

Before you restore to your external database host, make sure that you created your schema, user and correct grants. You can use this sample command to import a local MySQL backup:

$ mysql -u username –p database_name < /path/to/backup.sql

For more information on this process, see the article to Create a MySQL Backup.

Update the Contrast database configuration

You can edit your database configuration through the SuperAdmin portal or the properties editor. If you already shutdown Contrast for the maintenance window, you must use the encrypted property editor. Either of these changes requires you to restart of Contrast.

  • Log in to the Contrast application.
  • Assume SuperAdmin role.
  • Choose System Settings in the user menu.
  • Select the Database tab.
  • Fill in the property values for your external database host. Make sure to adjust the port to match your external database. For new installations, MySQL runs on 3306.

Encrypted Property Editor

Use the encrypted property editor to change your database properties to access your new host. Follow the instructions in the tool to update:

  • jdbc.port
  • jdbc.pass
  • jdbc.url
vagrant@eop:~$ cd /usr/local/contrast/bin/
vagrant@eop:/usr/local/contrast/bin$ ./edit-properties -e ../data/esapi/ -f ../data/conf/
log4j:WARN No appenders could be found for logger (CipherTextSerializer).
log4j:WARN Please initialize the log4j system properly.
log4j:WARN See for more info.
jdbc.type                                         : MYSQL                                 : /usr/local/contrast/data/db
jdbc.debug                                        : false
jdbc.pass                                         : fAf5hPAsPV
jdbc.schema                                       : contrast                                         : eop
database.bk.time                                  : 4:0:0
jdbc.port                                         : 13306
database.bk.enabled                               : true
database.enabled                                  : true
jdbc.url                                          : jdbc:mysql://
jdbc.user                                         : contrast
database.bk.dir                                   : /usr/local/contrast/data/backups/db
jdbc.dialect                                      : com.aspectsecurity.contrast.teamserver.persistence.CustomMySQL5Dialect
jdbc.driver                                       : com.mysql.jdbc.Driver

Enter the name of the property to edit [q to Quit]:

Restart Contrast

Use the following sets of commands to restart Contrast.

This command is slightly different if you chose the non-root installation:

$ sudo service contrast-server restart

At this point, it's helpful to tail the server logs:

$ tail -f $CONTRAST_HOME/logs/server.log

And then the application logs:

$ tail -f $CONTRAST_HOME/logs/contrast.log

If Contrast starts successfully, you will see this message in the server.log:

190116 21.22.15,703 {} {} {} INFO  ( Received code 200 from TeamServer
190116 21.22.15,707 {} {} {} INFO  ( Server start has been verified
190116 21.22.15,709 {} {} {} INFO  ( Contrast TeamServer Ready - Took 208323ms

Step 2: The Application Server

Before you begin, it's important that you work with the Contrast Support team and have access to the Contrast WAR file before beginning this process. If the DNS name of your installation is going to change, you must update teamserver.url in the file to reflect the new hostname. This also impacts agents that have already been deployed.

The following steps outline the process to migrate Contrast to your own Tomcat instance:

  • Collect configuration and license from the Contrast application.
  • Install Tomcat 7 and Java on your new application server.
  • Prepare and configure the application server.
  • Restart Tomcat.


  • Contrast uses Ubuntu and Ansible here as examples only. This software also runs on supported versions of Windows and Linux.
  • Visit Contrast's Github repository for a snippet of Ansible that you can use to install the latest versions of Tomcat 7 and Java 7 on Ubuntu 14.04.

Collect configuration from Contrast

In the example below, Contrast was installed at path /usr/local/contrast. Gather the following files:

  • data/agents/
  • data/conf/
  • data/esapi/
  • data/.contrast
  • data/.initialized
  • data/cache/
  • data/contrast.lic
  • webapp/Contrast.war

The following commands compresses necessary artifacts into your user's home directory:

$ cd /usr/local/contrast
$ tar -czvf ~/ctdc.tar.gz data/agents data/conf data/contrast.lic data/esapi/ data/cache/ data/.initialized data/.contrast webapp/Contrast.war

Install Tomcat and Java

This process varies based on your operating system. You must install:

  • Tomcat 7 (Contrast recommends Tomcat 7.0.61)
  • Supported versions of Java, as shown in System Requirements

Prepare and configure the application server

Set contrast-data

The first thing you need to decide is the location of your contrast-data. In the example above, you created a folder inside /opt/ named "contrast-data", but this could be anywhere. Contrast wants to make sure that this volume is large enough for log files, caches and ActiveMQ persistence. Contrast recommends making this a separate volume to handle growth without impacting your overall system.

Create your contrast-data folder:

$ mkdir /opt/contrast-data

Transfer and unzip configuration and license

Next, the configuration and data files you compressed on your running Contrast application need to be unarchived into the contrast-data directory of your new server.

As a test, run a command.

$ ls /opt/contrast-data/conf

There should be files named and among several others. To be sure that you don't have any issues, adjust the permissions on the contrast-data directory.

$ chown -R tomcat7:tomcat7 /opt/contrast-data


Now, it's time to set your JAVA_OPTS. You must set the contrast.home and to the location where you have unzipped the archive.


Every distribution is different for setting JAVA_OPTS. Please refer to the documentation for your distributions for best practices.

Deploy the WAR

In the compressed archive, Contrast includes the Contrast.war from your EOP installation. Going forward, Contrast will deliver a WAR-only artifact for faster updates and software iterations. This WAR file will be accessible from Hub for download purposes.

Symlink, copy or move the WAR into the Tomcat webapps directory. The path for the default Ubuntu installation is used below. Yours may be different.

$ sudo ln -s /opt/contrast-data/webapp/Contrast.war /var/lib/tomcat7/webapps/Contrast.war


$ cp /opt/contrast-data/webapp/Contrast.war /var/lib/tomcat7/webapps/Contrast.war

Once the WAR is deployed, you should be able to start your newly configured and distributed Contrast application. If you run into any problems, please let Contrast's Technical Support team know right away.

More Information

If you're planning to explore a distributed configuration of Contrast, please contrast our Technical Support Team. They would love to hear from you and keep track of your progress.

Configuring User Directories

About Directories

The user directory is where Contrast stores user information including the user's login name, credentials and other details about how a user is authenticated to the application. The embedded directory stores the username and password in the Contrast database; the password is stored as a one-way hash (non-reversible encryption).

You can also connect to external directories, which store only the username in the Contrast database. Credentials for login remain in the connected directory, and that directory is responsible for performing the actual authentication of the user.

Contrast supports Lightweight Directory Access Protocol (LDAP) and Microsoft Active Directory (AD).

Configure Directories

User directory

To configure your user directory:

  • Login to the SuperAdmin application.
  • Go to Settings from the navigation bar.
  • Select Authentication from the left navigation.
  • Select Embedded, LDAP, or Active Directory.

Internal directory

Within the directory configuration, there isn't a specific configuration for the internal directory. However, you can configure your password policy when you're using the internal directory. To access the Password Policy configuration from Settings, select the Security tab from the left navigation.

Option Description Value
Maximum Failed Login Attempts The number of failed attempts before an account is locked out 3
Minimum Length The minimum length for user passwords 8
Minimum Numbers The minimum number of numbers required in a password 0
Minimum Upper Case The minimum number of uppercase letters required in a password 0
Minimum Lower Case The minimum number or lowercase letters required in a password 0
Minimum Symbols The minimum number of symbols required in a password 0
Password Expiration Time The number of days between password expiration 365
Days after which unused accounts automatically lock The number of days an inactive account remains active until it's automatically marked inactive 180
Active Password History The option to retain a history of user password and disallow password re-use Disabled
Password Retained The number of passwords to retain when password history is enabled 5
Check Minimum Password change time Limits how often a password can be changed. Disabled
Minimum Time The number of hours required between password changes 24
Check Minimum # of different characters Enforces a minimum number of character sets required for a password to be considered valid Disabled
# of Characters The number of character types required 4

Connect to an external directory

When connecting Contrast to an external Directory, Contrast recommends that you create a Contrast Administrators group and a Contrast Users group before configuring the Contrast application.

Contrast manages access control internally, so group and role management isn't delegated to the directory. As a result, only two groups are required to connect Contrast to your directory. The Contrast Administrators group controls which users can access the SuperAdmin interface while the Contrast Users group controls which users can access the user application. Users in the Contrast Users group must be added to new or existing organizations to log in to the application. User's can't belong to both groups. Directory list accounts can be used as both Contrast and Organization Administrators, so specific user accounts aren't tied to those responsibilities.

Configuring Logging

About Logging

Contrast uses a universally accepted logging framework called Log4j. Administrators like you should become familiar with configuring logging thresholds and controlling log file destinations, as well as an overview of each log available in Contrast.

Log Files

You can find Contrast logs under the $CONTRAST_HOME/logs directory. The table below provides a comprehensive overview of the primary log files in Contrast.

File Name Description
Audit.log The audit log captures information about user sessions such as:
  • Logging in and out of the application
  • Impersonating another user
  • Switching organizations
  • Accessing the administrator portal
  • Changes to the configuration and settings of Contrast by a SuperAdmin account
  • User account service issues (locked accounts, password changed, etc.)
  • Deleting traces
  • Changes to a license or an expired license notification
  • API Key changes
Contrast.log The contrast.log is the equivalent of Tomcat's stdout or console log. Most key events happening inside Contrast are logged to this file for informational or debugging purposes. This includes information about applications, servers, libraries, traces and users. This log file also stores Java stack traces for debugging purposes when a server exception takes place.
Migration.log The migration.log contains a summary of all database migrations that occur against the Contrast application between updates. The log file references the version of Contrast, as well as the migration script that ran. The status of the script is also provided in the log message.
Security-events.log Formerly the esapi.log; this log file is used for capturing key events from Contrast, such as the loading of a given property file.

Configure Log Settings

A very basic log setting is available in the SuperAdmin interface by navigating to System Settings and then choosing Log Level. From this location, an EOP administrator can change the logging from informational to any of the following options: FATAL, ERROR, WARNING, INFO, DEBUG and TRACE. A detailed review of log settings for Log4j can be found here.

Changing the XML File

The configurable XML file that's used to host the Log4j configuration is packaged in the Contrast application. Find this file under $CONTRAST_HOME/data/conf.

Contrast recommends that you only make changes to the log4j2.xml file under the direction and support of a Contrast engineer. If a you change the file, it's important to syntactically review the file to ensure the formatting is correct. You should also be aware that a server restart isn't required if changes are entered correctly. The first parameter of the file below is a monitor interval that refreshes the settings based on the variable defined. By default, Contrast checks every 60 seconds and refreshes the logging configuration.

<Configuration monitorInterval="60">

The sections below describe the file components and how to make use of the file for increased or decreased logging purposes.

About Appenders

For a comprehensive introduction to Appenders and delivering LogEvents, refer to the Log4j documentation. Contrast predominantly makes use of the Rolling File Appender, which is an OutputStreamAppender that writes to the file named in the fileName parameter, and rolls the file over according to the TriggeringPolicy and the RolloverPolicy.

In the example below, we show the Appenders for our contrast.log. This example is a daily appender which has a 1GB max file size policy and no more than 15 files of rollover. This Appender also compresses the file and rename it daily.

<RollingFile name="DAILY" fileName="${contrast.logs.dir}/logs/contrast.log"
            filePattern="${contrast.logs.dir}/logs/contrast.%d.%i.log.gz" immediateFlush="true">
        <Pattern>%d{ddMMyy,SSS} {%X{}} {%X{}} {%X{remote.addr}} %-5p (%F:%L) %m%n
        <SizeBasedTriggeringPolicy size="1 GB"/>
    <DefaultRolloverStrategy max="15"/>

Log levels

The logger section of the file defines which Java packages should log to a specific Appender and at a given log level. Below is a summary of each level in ascending order, including the reasons why an Administrator may set it.

Log Level Description
Debug Helps the developer debug the application. Level of the message logged is focused on providing support to an application developer.
Info Gives the progress and chosen state information. This level is useful for the end user.
Warn Gives a warning about an unexpected event to the user. The messages coming out of this level may not halt the progress of the system.
Error Gives information about a serious error that needs to be addressed and may result in an unstable state.
Trace Gives more detailed information than the DEBUG level.

Configuring the JRE

Change the JRE

During the installation process, Contrast provides the option to use either an embedded JRE or a pre-installed JRE. As with all software, there are new releases of Java and you may prefere to use these.

Within the $CONTRAST_HOME directory there is an .install4j directory. Open pref_jre.cfg with a text editor, and add the complete path to the Java version you would like to use. Example:

C:\Program Files\Java\jre7

Configuring Tomcat

About Tomcat

During the installation process, you set some values for the memory used by the embedded Tomcat server on which Contrast runs. As you add more applications or find more vulnerabilities, you may notice a degradation in performance in the Contrast application. This could be because you're bumping against the maximum memory allowed for this server. Fortunately, you can increase your memory settings.

Change Settings

As an Administrator, begin stop the Contrast server by running the contrast-server stop command. Once the server is completely stopped (Contrast/logs/contrast-stdout.log ends with [MysqldResource] shutdown complete), you can change its memory settings. In the Contrast bin directory, c:/Program Files/Contrast/bin or the default /opt/Contrast/bin, open a file named contrast-server.vmoptions. It should look something like this:


You can update the values for Xms, the amount of memory allocated to the server on start, and Xmx, the maximum memory the server can use, as well as the MaxPermSize. These values can change depending on the memory available on the machine hosting Contrast. Once you make the change, save the file and start Contrast back up using the contrast-server start command.

For more information about JVM tuning, see this guide.

Using the Encrypted Editor

About the Encrypted Properties Editor

Contrast is bundled with several configuration files that are encrypted intentionally on first creation. They're located in the $CONTRAST_HOME/data/conf directory. You can modify some of these files through workflows within the Contrast interface.

Contrast also bundled a small tool capable of decrypting the file, and provided a tool for Enterprise-on-Premises (EOP) system administrators to modify the configuration of the Contrast deployment. You can find the tool in the $CONTRAST_HOME/bin directory. On Linux, the file is a simple shell script called edit-properties. On Windows, the file is a Windows command file called edit-properties.cmd. In both cases, you need to run the tool from a command prompt; an user interface isn't provided.

Edit and View an Encrypted File

You must have inputs to view and/or edit an encrypted property. The example below shows how to use the command. The primary inputs that you need to view or edit the file include the path to and the target file for editing purposes.

contrast@EOP-TeamServer:~/contrast/bin$ ./edit-properties 

usage: property-editor
 -c,--comment <text>      The comment for the top of the file
 -e,--esapi <path>        The path to the file
 -f,--targetFile <file>   The properties file to edit
 -o,--print-value         Print out the value of the property and exit
 -p,--property <name>     The name of the property to set
 -v,--value <val>         The value of the property

The following files for EOP are encrypted by default for security purposes:

Name Description Contains information for connecting and configuring Contrast to Active Directory groups for authentication purposes. Contains information for connecting and configuring Contrast to LDAP groups for authentication purposes. Contains host and connection information for configuring communication between Contrast and MySQL. Contains host and connection information for configuring communication between Contrast and Cassandra. Contains SAML keystore information.

The following code is an example of editing an encrypted file in Contrast. Load the file to edit the configuration of your Contrast application that's connecting to ActiveDirectory.

contrast@TeamServer:~/contrast/bin$ ./edit-properties -e ../data/esapi/ -f ../data/conf/

ad.userDn                                         : cn=Directory Manager                        : mail
ad.password                                       : NotaRealPassword
ad.nested.groups.enabled                          : false                                    : cn=ContrastUsers,cn=Users,dc=contrastsecurity,dc=com                                    : cn=ContrastAdmins,cn=Users,dc=contrastsecurity,dc=com
ad.url                                            : ldap://localhost:389
ad.base                                           : dc=contrastsecurity,dc=com

The editor shows all of the existing values encrypted in the file. You can use the flags listed above to view or edit a single property. The editor also asks you to place a comment in the file for auditing purposes. Contrast strongly suggests that you make use of the comment feature for noting any change you make to the file.