Chapter 2. Network Interfaces and Endpoints

Data Grid Server multiplexes endpoints to a single TCP/IP port and automatically detects protocols of inbound client requests. You can configure how Data Grid Server binds to network interfaces to listen for client requests.

<!-- Selects a specific IPv4 address, which can be public, private, or loopback.
     This is the default network interface for Data Grid Server. -->
<interfaces>
  <interface name="public">
    <inet-address value="${infinispan.bind.address:127.0.0.1}"/>
  </interface>
</interfaces>

<!-- Selects an IP address in an IPv4 or IPv6 loopback address block. -->
<interfaces>
  <interface name="public">
    <loopback/>
  </interface>
</interfaces>

<!-- Selects an IP address in an IPv4 or IPv6 non-loopback address block. -->
<interfaces>
  <interface name="public">
    <non-loopback/>
  </interface>
</interfaces>

<!-- Uses the `INADDR_ANY` wildcard address which means Data Grid Server
     listens for inbound client requests on all interfaces. -->
<interfaces>
  <interface name="public">
    <any-address/>
  </interface>
</interfaces>

<!-- Selects a link-local IP address in an IPv4 or IPv6 address block. -->
<interfaces>
  <interface name="public">
    <link-local/>
  </interface>
</interfaces>

<!-- Selects a site-local (private) IP address in an IPv4 or IPv6 address block. -->
<interfaces>
  <interface name="public">
    <site-local/>
  </interface>
</interfaces>

Match and fallback strategies

Data Grid Server can enumerate all network interfaces on the host system and bind to an interface, host, or IP address that matches a value, which can include regular expressions for additional flexibility.

<!-- Selects an IP address that is assigned to a matching host name. -->
<interfaces>
  <interface name="public">
    <match-host value="my_host_name"/>
  </interface>
</interfaces>

<!--Selects an IP address assigned to a matching network interface. -->
<interfaces>
  <interface name="public">
    <match-interface value="eth0"/>
  </interface>
</interfaces>

<!-- Selects an IP address that matches a regular expression. -->
<interfaces>
  <interface name="public">
    <match-address value="132\..*"/>
  </interface>
</interfaces>

<!-- Includes multiple strategies that Data Grid Server tries in the
     declared order until it finds a match. -->
<interfaces>
  <interface name="public">
    <match-host value="my_host_name"/>
    <match-address value="132\..*"/>
    <any-address/>
  </interface>
</interfaces>

Socket bindings map endpoint connectors to server interfaces and ports.

By default, Data Grid servers provide the following socket bindings:

<socket-bindings default-interface="public" port-offset="${infinispan.socket.binding.port-offset:0}">
    <socket-binding name="default" port="${infinispan.bind.port:11222}"/>
    <socket-binding name="memcached" port="11221"/>
</socket-bindings>

To override the default interface for socket-binding declarations, specify the interface attribute.

For example, you add an interface declaration named "private":

<interfaces>
  ...
  <interface name="private">
    <inet-address value="10.1.2.3"/>
  </interface>
</interfaces>

You can then specify interface="private" in a socket-binding declaration to bind to the private IP address, as follows:

<socket-bindings default-interface="public" port-offset="${infinispan.socket.binding.port-offset:0}">
  ...
  <socket-binding name="private_binding" interface="private" port="1234"/>
</socket-bindings>

You can use the server -b switch or the infinispan.bind.address system property to bind to a different address.

For example, bind the public interface to 127.0.0.2 as follows:

$ bin/server.sh -b 127.0.0.2

bin\server.bat -b 127.0.0.2

Configure port offsets with Data Grid servers when running multiple instances on the same host. The default port offset is 0.

Use the -o switch with the Data Grid CLI or the infinispan.socket.binding.port-offset system property to set port offsets.

For example, start a server instance with an offset of 100 as follows. With the default configuration, this results in the Data Grid server listening on port 11322.

$ bin/server.sh -o 100

bin\server.bat -o 100

Data Grid endpoints expose the CacheManager interface over different connector protocols so you can remotely access data and perform operations to manage and maintain Data Grid clusters.

You can define multiple endpoint connectors on different socket bindings.

You configure Data Grid server endpoints with connector declarations that specify socket bindings, authentication mechanisms, and encryption configuration.

The default endpoint connector configuration is as follows:

<endpoints socket-binding="default" security-realm="default"/>

Declaring an empty <endpoints/> element implicitly enables the Hot Rod and REST connectors.

It is possible to have multiple endpoints bound to different sockets. These can use different security realms and offer different authentication and encryption configurations. The following configuration enables two endpoints on distinct socket bindings, each one with a dedicated security realm. Additionally, the public endpoint disables administrative features, such as the console and CLI.

<endpoints socket-binding="public" security-realm="application-realm" admin="false">
   <hotrod-connector/>
   <rest-connector/>
</endpoints>
<endpoints socket-binding="private" security-realm="management-realm">
   <hotrod-connector/>
   <rest-connector/>
</endpoints>

<hotrod-connector name="hotrod">
  <topology-state-transfer />
  <authentication>
    <!-- Hot Rod endpoint authentication configuration. -->
  </authentication>
  <encryption>
    <!-- Hot Rod endpoint SSL/TLS encryption configuration. -->
  </encryption>
</hotrod-connector>

<rest-connector name="rest">
  <authentication>
    <!-- REST endpoint authentication configuration. -->
  </authentication>
  <cors-rules>
    <!-- Cross-Origin Resource Sharing (CORS) rules. -->
  </cors-rules>
  <encryption>
    <!-- REST endpoint SSL/TLS encryption configuration. -->
  </encryption>
</rest-connector>

Data Grid Server exposes endpoints on your network for remote client access.

Data Grid Server exposes multiple protocols through a single TCP port, which is 11222 by default. Handling multiple protocols with a single port simplifies configuration and reduces management complexity when deploying Data Grid clusters. Using a single port also enhances security by minimizing the attack surface on the network.

Data Grid Server handles HTTP/1.1, HTTP/2, and Hot Rod protocol requests from clients via the single port in different ways.

# firewall-cmd --add-port=11222/tcp --permanent
success
# firewall-cmd --list-ports | grep 11222
11222/tcp