IPv6 support in Terracotta
This document describes the changes needed in config 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
Consider the following example:
node1:hostname=2001:db8:a0b:12f0::1 (1)
node2:hostname=[2001:db8:a0b:12f0:0:0:0:2] (2)
node3:hostname=terracotta-host (3)
(1) Specifies a server host IP 2001:db8:a0b:12f0::1 as hostname for the node named node1.
(2) Specifies a server host IP 2001:db8:a0b:12f0:0:0:0:2 enclosed in square brackets as hostname for the node named node2.
(3) Specifies a server DNS host name terracotta-host which resolves to an IPv6 address as hostname for the node named node3.
IPv6 server sockets bind to ::0 by default, which can be overridden using the bind attribute in the <server> element.
Command-line tools
Command-line tools 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 the cluster tool
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 -connect-to [2001:db8:a0b:12f0::2]:9510 -connect-to 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 |
+-----------------------------------+--------------------+--------------------------+
Command line tools that don't accept server addresses directly 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
