The IP whitelisting feature enables you as the cluster administrator to ensure that only clients from certain explicitly named IP addresses can access the TSA. You can use this feature, for example, to secure the TSA from malicious clients attempting to connect to the TSA. The term "clients" here refers to TSA Clients communicating using the TSA wire protocol.

Terracotta servers also support SSL/TLS based security. For more information on setting up SSL/TLS based security in a Terracotta cluster, see the section SSL/TLS Security Configuration in Terracotta

A whitelist file is a plain-text file containing a list of IPs, such that only the 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 black-listing 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 allow the Terracotta cluster to use the whitelisting feature, the tc-config file must be supplemented with <security-root-directory> and <whitelist> tags under the <security> element, as in the following snippet:

The path in the <security-root-directory> element can be absolute, or relative to the directory where the tc-config file is located. If the whitelist file is not found at the specified location, 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 entries instead of IPs, the server will attempt to resolve these hostnames to IPs. If the resolution fails, the server startup will fail with an appropriate error message. Note that hostname resolution is done for tc-config files only, and any hostnames present inside the whitelist file will be ignored.

A multi-stripe cluster should be started with the same file, or identical copies of the whitelist 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 or removed from the whitelist file without the need for server restarts. To perform a dynamic update, edit the whitelist file as needed, and run the ipwhitelist-reload cluster-tool command to notify the servers in the cluster to reload the whitelist file. Refer to the section Cluster Tool 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-level ipwhitelist-reload command can be used. It also comes in handy 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 in the whitelist file, and running the server-level ipwhitelist-reload command will ensure that cluster tool can configure the cluster later.

If any failures happen while reading the whitelist and the tc-config files during a dynamic update, the updates will be ignored and the server will continue with the current whitelist. No partial updates will be applied. The update will 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 if the IP in the incoming client connection is whitelisted. 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 will remain 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.