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 TSA Clients communicating using the TSA wire protocol.

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 allow the server to start up using white-listing, ensure that you have set up the <security> and <white-list> elements in the tc-config configuration file, as in the following snippet:

White-listing is enabled/disabled based on the presence of the <security> tag in tc-config.

If the <security> tag is not specified, white-listing is disabled. The path in the <white-list> element can be absolute, or relative to the folder where the tc-config configuration file is located.

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 fail with an appropriate error message. 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, the server startup will fail with an appropriate error message.

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.

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.

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 use cluster-tool to notify the server about the change.

Refer to the section The Cluster Tool for details of usage.

TSA will synchronously reload the white-listed IP/CIDRs from the white-list file when you run the cluster-tool, which prints the error message if an error occurs during reloading. 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. Or you can signal the entire cluster (as configured by the cluster-tool configure command) to reload the white-list file on every server in the cluster.

When you run the cluster-tool, 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 a DNS lookup for hostname resolution. In both cases, failures can occur. 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 cluster-tool 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.