The IP white-listing 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 caching clients, JMX clients and HTTP clients. The so-called white-list is a list of IPs, and clients running on these IPs are allowed to access the TSA; any client whose IP is not in the white-list will not be allowed to access the TSA. You maintain the white-list of known client IPs in a plain text file. CIDR notations can also be used to cover a range of IPs.

If you want to use white-listing, you need to enable it at server startup. Once the server has started with white-listing enabled, white-listing cannot be turned back off while the server is running. However, you can change the existing IP/CIDR entries in the white-list file while the server is running. Also you can add and delete entries in the white-list file while the server is running, in order to modify the set of clients that need access to the cluster.

If you do not switch on white-listing at server startup, you cannot switch on white-listing while the server is running.

In a multi-stripe cluster, you need to start up all servers (both actives and passives) with the same copy of the white-list file, and when there are updates to the white-list file, you need to ensure that the same changes are mirrored across all stripes. Note that the TSA does not do any cross-stripe validation on the contents of the white-list file, so it is your responsibility as the cluster administrator to make sure that this happens.

To enable white-listing, you need to start the server with the following tc-config property set:

where <location> is the path containing the white-list file, and <file> is the name of the white-list file.

White-listing is enabled/disabled based on the presence of this tc-config property entry. The value of this property is the complete path to the white-list file. If the file is not found at the specified location, the server startup will fail with an appropriate error message. If the file is present but there is an error reading the file, the server startup will continue with white-listing disabled, and the failure will be logged in the server log. If the property is not specified, white-listing is disabled.

The server IPs specified in the tc-config file of the server are always white-listed. 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, server startup will continue with white-listing disabled. So when this IP white-listing feature is used, it is recommended to have only IPs configured for servers in the tc-config file. Similarly, localhost IPs are always white-listed too.

The white-list file is a simple text file. You can choose any name for this file, for example white-list.txt. The entries can be raw IP addresses in IPv4 format or in CIDR notation to represent ranges. IPv6 entries are not supported. Each line in the file can contain either a single IP address or a comma-separated set of IP addresses. Any entry that is not a valid IPv4 address or a valid CIDR will be ignored. Lines starting with a # are skipped. Blank lines are also skipped . Here is a sample white-list file:

The white-list file must be kept in a directory where you have write permissions. Some files will be created by the server in the same directory for book-keeping purposes. If the server fails to create these files, the server startup will also fail.

Once a server is started with white-listing enabled, entries can be dynamically added/removed from the white-list file. The updates to the white-list file are processed by the server only when you signal the server to do so. When you have finished making the changes to the white-list file, you must execute the "update-white-list.sh" script packaged with the kit. The script takes the white-list file path as the argument. After you run the script the updates will take effect in a few moments and the corresponding log statements can be found in the server log.

As already mentioned, every server node (active and passive) has its own copy of the white-list file. So you need to update the white-list file and execute the script on each node separately. When you run the script, the server receives the update signal and reloads the white-list file, and the updated white-list entries are logged in the server log. Thus, after every update operation, you should check the server logs to verify if the updates took effect. Make sure that the updates took effect in all the servers in the cluster.

On every dynamic update, the server reads the contents of the white-list file and the tc-config to update its in-memory white-list. Reading the white-list file involves a disk IO, and reading a tc-config file with hostnames in it involves DNS lookup for hostname resolution. In both cases, failures are very well possible. So if such a failure happens after a dynamic update, the updates will be ignored and the server will continue with the current white-list. No partial updates will be applied. The update won't be retried either until the user signals so by running the update-white-list script again.

This section details different client behaviors with white-listing enabled.

When a client connects to a server on the tsa-port, the server first accepts the socket connection, then verifies if the IP of the incoming client is white-listed and closes the socket connection if the client is not white-listed. In this case, the client will get an EOF on trying to read from the socket connection established with the server. If a client was white-listed initially and was removed from the white-list on a dynamic update, it will not be removed immediately from the cluster. Instead, the client will remain connected to the cluster as long as there is no network disconnection between the client and server. The client will be rejected only on the next reconnect attempt.

Non-white-listed clients that send HTTP requests to the management port will get a 403 Forbidden response.