Installation

Downloading Contrast

Set Up Contrast Hub

Contrast Hub is the central distribution system for customers to obtain installation media, release notes and licenses for Enterprise-on-Premises (EOP) installations. EOP customers are provided with a Hub account when their licenses are provisioned. If you're unsure about who holds access for your company, reach out to the Contrast Support team.

Download the Installer

Once you activate your Contrast Hub account, you can to download the Contrast installer for your operating system.

At this point, you can also download your Contrast license file. The license file is configured with a SuperAdmin account and a regular user account. You'll need the license to complete the installation of the Contrast application.

Our installer comes in two different flavors, one with Contrast cache data bundled and one without. Users who are air-gapped or have no internet connectivity should download the installer that has cache data bundled. Users that want to download our installer (labeled as NO_CACHE) must have internet connectivity to load the latest library data.

Installing Contrast

Gather Information

Before installing the Contrast application, you should download and fill out the information worksheets at the bottom of this article. Preparing this information greatly reduces configuration errors.

Note: If installing on Linux, make sure you installed the required MySQL shared libraries. See the section on Preparing for the Installation in System Requirements for more information.

Run the Installation

It's possible to run the installation as a regular user; however, Contrast recommends that you complete the process as a privileged user. On Windows, you can right-click on the installer and select Run As Administrator. On Linux, use the sudo command to launch the installer.

Once you launch the installer, you're presented with several questions. You can use the information in the worksheets to answer these questions as you step through the installation. More advanced configuration options are available within the application when managing your account after startup. If you're using a distributed setup for the Contrast application, you should use a distributed MySQL instance during setup.

Note: Pay close attention to the value used for the Contrast application URL. This is the URL that client agents use to communicate back to the application. Contrast makes the best attempt to determine the hostname and prepopulate this value; but, if the provided hostname isn't resolvable by clients on the network, they won't be able to communicate back to the server.

After the installation is complete, Contrast performs its initial configuration. If you're upgrading your version of Contrast, this includes performing any required update tasks.

Customize the Installer

Customize the behavior of the Contrast application installer by providing arguments when you run the installation script. This allows you to perform actions such as force console mode or perform an unattended installation.

Command Line Argument Description
-h -help Shows help for common command line arguments.
-c Forces the installation to run in Console Mode.
-q Executes the installer in Unattended Mode.
-g Forces the installation to run in GUI Mode. (Windows Only)
-console If the installer is executed in Unattended Mode and the -console argument is passed on Windows, a second console shows the output of the installer.
-overwrite Forces the installer to overwrite all files in Unattended Mode regardless of the overwrite policy specified in the installer. Caution: This can cause your configuration to be overwritten back to default values.
-dir Only valid in Unattended Mode; specifies the directory where Contrast should be installed.
-Dinstall4j.debug By default, the installer catches all exceptions, creates a crash log and informs the user about the location of that log file. This might be inconvenient when debugging an installer; so, this system property switches off the default mechanism, and exceptions are printed to stderr.
-Dinstall4j.keepLog=true -Dinstall4j.alternativeLogfile=[path] The installer creates a log file prefixed i4j_log for all installations and uninstallation in your temp directory. This log file can be helpful for debugging purposes. If your installer contains an Install files action and terminates successfully, the log file is copied to [installation dir]/.install4j/installation.log. Otherwise, the file is deleted after the installer or uninstaller terminates by default.
When using the -Dinstall4j.keepLog=true option, the log file won't be deleted. With the -Dinstall4j.alternativeLogfile=[path] option, the log file is copied to the file specified with [path]. This should be an absolute path name. Neither option has any effect if the log file has already been copied to the installation directory.
-varfile (filename) Specifies a variable-file to be used. When installing in Unattended Mode, this allows you to provide customizations to the default values set by the installer.
--skip-preflight Skips preflight checks (current user is root, dependencies present). If using this parameter, it must be the first parameter passed on the command line.

Log In to Contrast

You can find the login page to the Contrast application at /Contrast. The first time the Contrast application starts after installation, there are two users that can log into the user interface:

  • Default Username: Your Hub Username
  • Your SuperAdmin username: contrast_superadmin@your-email-domain.com

The default password for both users is default1!.

Note: Contrast recommends that you change both passwords after you install and configure the application.

Use Contrast without Cache

If you downloaded and installed the version of Contrast that doesn't contain cache, enable Hub connectivity in System Settings so that you continue to get the latest library data.

More Information

Information Worksheets:

Distributed Deployment of Contrast

About Distributed Contrast Configuration

This guide is for Enterprise-On-Premises (EOP) administrators who want to intall a distributed configuration of Contrast, 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 TeamServer 3.3.2.)

For more information on the configuration process, go to the article on Distributed Configuration.

Before You Get Started

Before you get started with configuring a distributed Contrast application, read through this entire document, and make sure that the following steps have been completed.

  • Previous successful installation of Contrast EOP with a distributed database configuration
  • Successful backup(s) and exports of the Contrast application database
  • Collect Contrast version numbers for the application and database

EOP customers typically install and update the Contrast application by downloading the installer/updater artifact from the Contrast Hub. Instructions can be found here. If you already installed Contrast and want to use a distributed installation instead, please see the section below to Convert an Installation.

How It Works

In the following example, Contrast has been installed at path /usr/local/contrast. To collect Contrast application version numbers, look in the VERSION file in /usr/local/contrast/VERSION. To collect the Contrast database version, run the following query:

select `version` from schema_version ORDER BY `installed_on` DESC LIMIT 1;

Example: If the application version stands at 3.3.2 and the database is at 3.3.2.012, you can say the versions are the same because it's safe to drop .012 from the database version. As a result, you can have an existing application server (A) running with a separate database (B) on 3.3.2. When you're about to install 3.4.2onto a new application server (C) and connect it to B, you'll need to either stop A before installing 3.4.2 on C or update A before installing on C.

Collect Configuration

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

  • data/conf/
  • data/esapi/
  • data/.contrast
  • data/.initialized
  • data/contrast.lic
  • VERSION

Example: Compress the files above into a zip file or a tar.gz file. Examples of Linux commands that compress necessary artifacts into your user's home directory include:

```
$ cd /usr/local/contrast
$ tar -czvf ~/ctdc.tar.gz data/conf data/contrast.lic data/esapi/ data/.initialized data/.contrast VERSION
```

Distributed Fresh Installation

You can run the installation as a regular user; however, Contrast recommends that you complete the installation to your system as a privileged user. If you're on Windows, you can right-click on the installer and select Run As Administrator. If you're on Linux, use the sudo command to launch the installer.

Once you launch the installer, you're presented with several questions. Select the Application Server Only installation option when prompted. Provide the compressed file you created in the previous section and follow the on-screen steps.

Note: Pay close attention to the value used for the Contrast URL. This is the URL that client agents use to communicate back to the application. Please set this value to a Contrast host or load balancer that's reachable by your agent hosts.

After the installation is complete, the Contrast performs its initial configuration. It can take two to three minutes to fully start up. Check the status of startup by watching server.log and contrast.log. Once the server starts successfully, you will see something similar to the following in server.log:

260916 20.18.25,837 {} {} {} INFO  (Server.java:303) Contrast TeamServer Ready - Took 119305ms

Convert an Installation

Edit the encrypted file $CONTRAST_HOME/data/conf/database.properties using the encrypted editor. Look for database.type; if it doesn't exist, create a new property. Set this value to distributed and modify the database connection values to point to the distributed database you want to use. Restart Contrast for these changes to take effect.

user@ubuntu:/opt/contrast/bin$ ./edit-properties  -e ../data/esapi/ -f ../data/conf/database.properties

jdbc.type                                         : MYSQL
database.prod.dir                                 : /opt/contrast/data/db
jdbc.debug                                        : false
jdbc.pass                                         : pass
jdbc.schema                                       : contrast
jdbc.host                                         : ubuntu
database.bk.time                                  : 6:39:14
jdbc.port                                         : 3306
database.bk.enabled                               : false
database.enabled                                  : true
jdbc.url                                          : jdbc:mysql://ubuntu:3306/contrast
jdbc.user                                         : contrast
database.bk.dir                                   : /opt/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]: database.type
Create new Property [database.type](y/N): y
Enter a value for the property: distributed

jdbc.type                                         : MYSQL
database.prod.dir                                 : /opt/contrast/data/db
jdbc.debug                                        : false
jdbc.pass                                         : pass
jdbc.schema                                       : contrast
jdbc.host                                         : ubuntu
database.bk.time                                  : 6:39:14
jdbc.port                                         : 3306
database.bk.enabled                               : false
database.enabled                                  : true
database.type                                     : distributed
jdbc.url                                          : jdbc:mysql://ubuntu:3306/contrast
jdbc.user                                         : contrast
database.bk.dir                                   : /opt/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]:

Once this is done, you may continue to add more application-only installations.

Note: If you're converting from a default embedded database configuration to a distributed configuration, database.bk.enabled also needs to be set to false. It's your responsibility to configure your own backups when running a distributed database configuration with Contrast.

Disabling SuperAdmin Access

The following steps lead you through the process of disabling SuperAdmin access from Enterprise-on-Premises (EOP) nodes that are accessible to general users.

Disable Access for EOP Nodes

To disable SuperAdmin access from generally accessible nodes, begin by running Contrast in a distributed setup as a new installation. You'll only be prompted to disable SuperAdmin if you're installing as an application-only installation; a full installation won't have this option.

If you already have a distributed Contrast setup, add -Dsuper.admin.disabled=(false or true) to $CONTRAST_HOME/bin/contrast-server.vmoptions. If false, the node allows SuperAdmin logins. If true, the node doesn't allow SuperAdmin logins.

Note: Contrast supports one secret node for each installation.

Disable Access for SAML

To disable SuperAdmin access for a Security Assertion Markup Language (SAML) authentication setup, configure Contrast as two different applications in your identity provider: one for the publicly accessible address and one for the secret node's address. Update the URL in the SAML.properties on the secret node and then restart Contrast.

Example:

authenticator.saml.secret.url : http://secret.internal.contrast.com/Contrast
authenticator.saml.keystore.path : /path/to/jks.jks
authenticator.saml.keystore.default.key : default_keystore
authenticator.saml.keystore.passwordMap : keystore=password
authenticator.saml.keystore.password : keystore_password
authenticator.saml.url : http://app.public.contrastsecurity.com/Contrast

Restarting Contrast

Restart Contrast on Linux by running:

sudo service contrast-server restart

Restart Contrast on Windows by running:

net stop "Contrast Server"

Once the service is completely shutdown on Windows, run:

net start "Contrast Server"

Uninstalling Contrast

About Uninstallation

The following instructions will help you remove the Contrast application from one of your servers safely and cleanly.

Run the Script

Each installation comes with a script for safely uninstalling Contrast plus all embedded components such as Java, Tomcat and MySQL. The script is packaged within the root directory of the Contrast installation. On Unix, the file is an executable script labeled uninstall. On Windows, a command file is packaged in the installation directory called uninstall.cmd.

Contrast recommends that you do the following before performing the uninstallation process:

  • Create a backup of MySQL using the database backup tool provided with Contrast.
  • Shut down Contrast using either the Windows or Unix service script.

To run the uninstaller on Windows:

  • Open the Windows Explorer.
  • Navigate to the Contrast installation directory.
  • Click on the file uninstall.exe and run. If you ran the installation as an Administrator, run this in the same manner.
  • Follow the prompts to perform uninstallation.

Running the uninstaller on Linux:

  • Open a Linux console.
  • Change directory (cd) to the Contrast installation directory.
  • Execute the command uninstall.
  • Follow the prompts to perform uninstallation.

Some Files May Remain

You'll delete the vast majority of files when performing an uninstallation. However, a few key files may be left on the system.

Note: The uninstaller may not delete the following files:

  • The Contrast Home directory
  • The Contrast DATA directory
  • The Contrast LOGS directory
  • The Contrast MYSQL directory

An Administrator can delete these files manually.