IPv6 support in Terracotta
This document describes the changes needed in configuration files, tooling, and client side APIs toward enabling IPv6 connections between clients and Terracotta cluster.
Terracotta supports IPv6 addresses as defined in the RFC 5952. Thus, all of following are acceptable:
Full IPv6 address, e.g.
2001:db8:a0b:12f0:0:0:0:1.
Full IPv6 address enclosed in square brackets, e.g.
[2001:db8:a0b:12f0:0:0:0:1].
Full IPv6 address enclosed in square brackets along with port, e.g.
[2001:db8:a0b:12f0:0:0:0:1]:9410.
Shortened IPv6 address, e.g.
2001:db8:a0b:12f0::1.
Shortened IPv6 address enclosed in square brackets, e.g.
[2001:db8:a0b:12f0::1].
Shortened IPv6 address enclosed in square brackets along with port, e.g.
[2001:db8:a0b:12f0::1]:9410.
Note that enclosing an IPv6 address in square brackets is mandatory only if a port is to be specified along with it.
Terracotta Server
If an IPv6 address of a machine hosting the Terracotta server instance is to be specified, the host attribute of the <server> element in tc-config would become the IPv6 address of the said machine, as exemplified below:
<servers>
<server host="2001:db8:a0b:12f0::1" name="server-1"> <!-- 1 -->
<logs>logs1</logs>
</server>
<server host="[2001:db8:a0b:12f0:0:0:0:2]" name="server-2"> <!-- 2 -->
<logs>logs2</logs>
<tsa-port>9510</tsa-port>
<tsa-group-port>9530</tsa-group-port>
</server>
<server host="terracotta-host" name="server-2"> <!-- 3 -->
<logs>logs3</logs>
<tsa-port>9610</tsa-port>
<tsa-group-port>9630</tsa-group-port>
</server>
</servers>
1 | Specifies a server host IP 2001:db8:a0b:12f0::1. Since the <tsa-port> has not been specified, it will default to 9410. |
2 | Specifies a server host IP 2001:db8:a0b:12f0:0:0:0:2 enclosed in square brackets. |
3 | Specifies a server DNS host name terracotta-host which resolves to an IPv6 address. |
IPv6 server sockets bind to ::0 by default, which can be overridden using the bind attribute in the <server> element.
Cluster Tool
Cluster tool commands which accept server addresses need to provide the IPv6 addresses of Terracotta servers as shown in the examples below:
This example below shows the execution of
status command for two IPv6 addresses - one enclosed in square brackets, and the other not enclosed in square brackets (and using the default port).
./cluster-tool.sh status -s [2001:db8:a0b:12f0::2]:9510 -s 2001:db8:a0b:12f0::1
+-----------------------------------+--------------------+--------------------------+
| Host:Port | Status | Member of Cluster |
+-----------------------------------+--------------------+--------------------------+
| [2001:db8:a0b:12f0::2]:9510 | ACTIVE | tc-cluster |
| 2001:db8:a0b:12f0::1 | PASSIVE | tc-cluster |
+-----------------------------------+--------------------+--------------------------+
The example below shows the execution of a
stop command that stops two servers. One server is identified by its host name and the other by its IPv6 address.
./cluster-tool.sh stop -s terracotta-host:9610 -s [2001:db8:a0b:12f0::1]:9410
Stop successful for server at: terracotta-host:9610
Stop successful for server at: [2001:db8:a0b:12f0::1]:9410
Command completed successfully.
Commands which don't accept server addresses directly (e.g.
The "configure" Command of the Cluster Tool using tc-configs) do not need any change to work with IPv6.
Ehcache Client
An Ehcache client can specify the IPv6 addresses of the servers it wants to connect to either through Java APIs or XML configuration, as shown below:
API Example
InetSocketAddress firstServer = InetSocketAddress.createUnresolved("2001:db8:a0b:12f0::1", 0);
InetSocketAddress secondServer = InetSocketAddress.createUnresolved("2001:db8:a0b:12f0:0:0:0:2", 9510);
List<InetSocketAddress> servers = Arrays.asList(firstServer, secondServer);
String cacheManagerIdentifier = "cacheManager-1";
PersistentCacheManager cacheManager = CacheManagerBuilder
.newCacheManagerBuilder()
.with(EnterpriseClusteringServiceConfigurationBuilder.enterpriseCluster(servers,
cacheManagerIdentifier) // 1
.autoCreate())
.build(true);
1 | EnterpriseClusteringServiceConfigurationBuilder.enterpriseCluster(Iterable, String) lets you create a CacheManager by specifying IPv6 addresses of the servers. The first argument is the Iterable<InetSocketAddress> of the servers in the cluster, while the second argument is the cache manager identifier. |
Like other Ehcache APIs, the above API has a secure variant as well with the signature EnterpriseClusteringServiceConfigurationBuilder.enterpriseSecureCluster(Iterable, String, Path), where the last argument is the path to the client's security root directory.
XML Example
<ehcache:config
xmlns:ehcache="http://www.ehcache.org/v3"
xmlns:tc="http://www.terracottatech.com/v3/terracotta/ehcache">
<ehcache:service>
<tc:cluster>
<tc:cluster-connection cluster-tier-manager="cacheManager-1"> <!-- 1 -->
<tc:server host="[2001:db8:a0b:12f0::1]"/> <!-- 2 -->
<tc:server host="2001:db8:a0b:12f0:0:0:0:2" port="9510" /> <!-- 3 -->
</tc:cluster-connection>
</tc:cluster>
</ehcache:service>
</ehcache:config>
1 | Cache manager identifier. |
2 | Terracotta server IP [2001:db8:a0b:12f0::1]. Since the port is not specified, it will default to 9410. |
3 | Terracotta server IP 2001:db8:a0b:12f0:0:0:0:2 and port 9510. |
TCStore Client
InetSocketAddress firstServer = InetSocketAddress.createUnresolved("2001:db8:a0b:12f0::1", 0);
InetSocketAddress secondServer = InetSocketAddress.createUnresolved("2001:db8:a0b:12f0:0:0:0:2", 9510);
List<InetSocketAddress> servers = Arrays.asList(firstServer, secondServer);
DatasetManager datasetManager = DatasetManager.clustered(servers) // 1
.build();
1 | DatasetManager.clustered(Iterable) lets you create a DatasetManager by specifying IPv6 addresses of servers. |
Like other TCStore APIs, the above API has a secure variant as well with the signature DatasetManager.clustered(Iterable, Path), where the last argument is the path to the client's security root directory.
XML Example
<clustered xmlns="http://www.terracottatech.com/v3/store/clustered"> <!-- 1 -->
<cluster-connection>
<server host="[2001:db8:a0b:12f0::1]"/> <!-- 2 -->
<server host="2001:db8:a0b:12f0:0:0:0:2" port="9510" /> <!-- 3 -->
</cluster-connection>
</clustered>
1 | Declares a clustered DatasetManager configuration. |
2 | Terracotta server IP [2001:db8:a0b:12f0::1]. Since the port is not specified, it will default to 9410. |
3 | Terracotta server IP 2001:db8:a0b:12f0:0:0:0:2 and port 9510. |
Terracotta Management Console
To connect to a Terracotta cluster running on IPv6, you can specify the server IPv6 addresses in the Connection URL as shown in the snapshot:
Screenshot: Terracotta Management Console, field for Connection URL
