You can enable connection encryption by adding an <ssl-tls> tag to the <security> section of the tc-config.xml file. When an <ssl-tls> tag is specified, you must also supply:

With SSL/TLS configured in the tc-config.xml file, the specified security root directory must contain a valid truststore in the trusted-authority subdirectory and a valid keystore in the identity subdirectory. The identity certificate is required even if file-based or LDAP-based authentication is chosen. The choice of authentication scheme may mean other files are also required in the security root directory.

On the client, the security root directory must contain a trusted authority certificate in the trusted-authority subdirectory. Again, the choice of authentication scheme may mean other files, including an identity certificate, are also required in the security root directory.

To configure authentication in the cluster, add an <authentication> tag to the <security> section of the tc-config.xml file. Inside that tag you should configure the authentication scheme required.

When authentication is configured, a <security-root-directory> tag, with the path to the security root directory, must also be added to the tc-config.xml file.

To configure certificate-based authentication, add an <authentication> tag containing a <certificate/> tag to the <security> section of the tc-config.xml file.

If certificate-based authentication is configured, an <ssl-tls> tag must also appear in the <security> section of the tc-config.xml file. Also, clients must have an appropriate identity certificate keystore in their security root directory.

To configure file-based authentication, add an <authentication> tag containing a <file/> tag to the <security> section of the tc-config.xml file.

If file-based authentication is configured, the server's security root directory must contain a users.xml file. The users.xml file must contain the list of valid users with a password hash for each user. The only password hashing algorithm currently supported is bcrypt.

Example of a users.xml file for authentication:

There is a command line utility for generating bcrypt password hashes. The bcrypt script is located in tools/security/bin under the product installation directory as bcrypt.bat for Windows platforms, and as bcrypt.sh for Unix/Linux.

When running the bcrypt script, you must specify the number of rounds. The number to choose depends on both the performance of the servers on which authentication takes place and also how you decide to trade off security against speed. A higher number creates hashes that are harder for attackers to crack, but are also harder for your servers to verify. Increasing the number of rounds by 1 doubles the difficulty. You may find that a value between 10 and 13 is suitable.

The bcrypt script can read the password from stdin:

or directly from the the command line:

The stdin form of the command is preferred because when a password is used on the command line, it can be written into files such as the command history and also readable using commands such as ps.

To configure LDAP-based authentication, add an <authentication> tag containing an <ldap/> tag to the <security> section of the tc-config.xml file.

If LDAP-based authentication is configured, the server's security root directory must contain a ldap.properties file. The properties in the ldap.properties file are the same properties that are used to configure LDAP integration in other Software AG products. See LDAP Properties for a full list of supported properties.

Example of an ldap.properties file for authentication:

To configure auditing in the cluster, add an <audit-directory> tag to the <security> section of the tc-config.xml file.

The IP whitelisting feature enables you as the cluster administrator to ensure that only clients from known IP addresses can access the TSA. You can use this feature to prevent malicious clients from establishing connections to the TSA. The term "clients" here refers to clients communicating with the Terracotta servers using the TSA wire protocol.

A whitelist file is a plain-text file containing a list of IPs. Only clients running on these IPs are allowed to access the TSA. The server IPs specified in the tc-config, and the localhost IPs of the server are always whitelisted. An empty whitelist file has the semantics of blacklisting all the IPs, except the IPs fetched from the tc-config, and those corresponding to localhost.

The following rules need to be followed for a whitelist file to be considered valid, and the entries in it to be parsed properly:

The following is an example of a valid whitelist file:

To configure IP whitelisting, add a <whitelist> tag to the <security> section of the tc-config.xml file.

When IP whitelisting is configured, a <security-root-directory> tag, with the path to the security root directory, must also be added to the tc-config.xml file.

If the whitelist.txt file is not found in the security root directory, or there is an error reading the file, the server startup will fail with an appropriate error message.

If hostnames are used in the tc-config.xml file instead of IPs, the server attempts to resolve these hostnames to IPs. If the resolution fails, the server startup fails with an appropriate error message. Note that hostname resolution is done for the tc-config.xml file only, and any hostnames present inside the whitelist.txt file are ignored.

A multi-stripe cluster should be started with the same whitelist.txt file, or identical copies of the file. Similarly, when updates to the file are desired, they should be performed on all the stripes, as described in the following section.

After a cluster is started with whitelisting enabled, entries can be dynamically added to or removed from the whitelist without the need for server restarts. To perform a dynamic update, edit the whitelist.txt file as needed, and run the ipwhitelist-reload cluster-tool command to notify the servers in the cluster to reload the whitelist.txt file. Refer to the The "ipwhitelist-reload" Command section for details of the usage.

Errors during whitelist reload, if any, are logged in individual Terracotta Server logs. Thus, after every update operation, server logs should be checked to verify that the updates took effect in all the servers.

If a cluster is not yet configured and the whitelist file needs to be reloaded on the servers, the server-levelipwhitelist-reload command can be used. It may also be helpful when the machine from where the cluster tool is to be used is itself not whitelisted initially. In this scenario, adding this machine's IP to the whitelist, and running the server-level ipwhitelist-reload command ensures that cluster tool can configure the cluster later.

If any failures happen while reading the whitelist.txt or the tc-config.xml files during a dynamic update, the updates are ignored and the server continues with the current whitelist. No partial updates are applied. The update is not be retried, and the ipwhitelist-reload command will have to be run again after resolving the problems.

When a client connects to a server on the tsa-port, the server accepts the socket connection, and verifies the IP of the incoming client connection against the whitelist. If it finds that the client IP is not whitelisted, it closes the socket connection.

If a whitelisted client is removed from the whitelist via a dynamic update, it remains connected to the cluster as long as there is no network disconnection or explicit connection closure from the client. Subsequent connection attempts from the client to cluster will fail.

Here is an example of a tc-config.xml security configuration section that configures auditing, encrypted connections, LDAP authentication and IP whitelisting:

With the configuration in the above example, the server's security root directory would contain a truststore in the trusted-authority subdirectory, a keystore and a credentials.properties in the identity directory, an ldap.properties in the access-control subdirectory and a whitelist.txt file.

The keystore is required so that the server can prove to clients that it is the server they are expecting. The credentials.properties file is required so that the server can connect to other servers in the stripe. If there are no other servers in the stripe, the credentials.properties file should not be present.

To configure a client to connect to a secured cluster, you need to give the client a path to the client's security root directory. This should contain, for example, the credentials that the client needs to connect to the cluster.

To enable the cluster tool to connect to a secure cluster, each cluster tool command must be prefixed with -srd (or long option --security-root-directory) as in the following example:

Attempting to connect to a secure cluster without the -srd option will fail. Commands without this option retain their behavior. For more information on cluster tool commands, see the section Cluster Tool.

An Ehcache client can define either an XML or a programmatic configuration, both of which support security configuration. The following are the examples of usages of each: