Chapter 2. Network interfaces and socket bindings

Expose Data Grid Server through a network interface by binding it to an IP address. You can then configure endpoints to use the interface so Data Grid Server can handle requests from remote client applications.

2.1. Network interfaces

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.

Internet Protocol (IP) address

XML

<server xmlns="urn:infinispan:server:14.0">
  <!-- 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>
</server>

JSON

{
  "server": {
    "interfaces": [{
      "name": "public",
      "inet-address": {
        "value": "127.0.0.1"
      }
    }]
  }
}

YAML

server:
  interfaces:
    - name: "public"
      inetAddress:
        value: "127.0.0.1"

Loopback address

XML

<server xmlns="urn:infinispan:server:14.0">
  <!-- Selects an IP address in an IPv4 or IPv6 loopback address block. -->
  <interfaces>
    <interface name="public">
      <loopback/>
    </interface>
  </interfaces>
</server>

JSON

{
  "server": {
    "interfaces": [{
      "name": "public",
      "loopback": null
    }]
  }
}

YAML

server:
  interfaces:
    - name: "public"
      loopback: ~

Non-loopback address

XML

<server xmlns="urn:infinispan:server:14.0">
  <!-- Selects an IP address in an IPv4 or IPv6 non-loopback address block. -->
  <interfaces>
    <interface name="public">
      <non-loopback/>
    </interface>
  </interfaces>
</server>

JSON

{
  "server": {
    "interfaces": [{
      "name": "public",
      "non_loopback": null
    }]
  }
}

YAML

server:
  interfaces:
    - name: "public"
      nonLoopback: ~

Any address

XML

<server xmlns="urn:infinispan:server:14.0">
  <!-- 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>
</server>

JSON

{
  "server": {
    "interfaces": [{
      "name": "public",
      "any_address": null
    }]
  }
}

YAML

server:
  interfaces:
    - name: "public"
      anyAddress: ~

XML

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

JSON

{
  "server": {
    "interfaces": [{
      "name": "public",
      "link_local": null
    }]
  }
}

YAML

server:
  interfaces:
    - name: "public"
      linkLocal: ~

Site local

XML

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

JSON

{
  "server": {
    "interfaces": [{
      "name": "public",
      "site_local": null
    }]
  }
}

YAML

server:
  interfaces:
    - name: "public"
      siteLocal: ~

2.1.1. 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.

Match host

XML

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

JSON

{
  "server": {
    "interfaces": [{
      "name": "public",
      "match-host": {
        "value": "my_host_name"
      }
    }]
  }
}

YAML

server:
  interfaces:
    - name: "public"
      matchHost:
        value: "my_host_name"

Match interface

XML

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

JSON

{
  "server": {
    "interfaces": [{
      "name": "public",
      "match-interface": {
        "value": "eth0"
      }
    }]
  }
}

YAML

server:
  interfaces:
    - name: "public"
      matchInterface:
        value: "eth0"

Match address

XML

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

JSON

{
  "server": {
    "interfaces": [{
      "name": "public",
      "match-address": {
        "value": "132\\..*"
      }
    }]
  }
}

YAML

server:
  interfaces:
    - name: "public"
      matchAddress:
        value: "127\\..*"

Fallback

XML

<server xmlns="urn:infinispan:server:14.0">
  <!-- 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>
</server>

JSON

{
  "server": {
    "interfaces": [{
      "name": "public",
      "match-host": {
        "value": "my_host_name"
      },
      "match-address": {
        "value": "132\\..*"
      },
      "any_address": null
    }]
  }
}

YAML

server:
  interfaces:
    - name: "public"
      matchHost:
        value: "my_host_name"
      matchAddress:
        value: "132\\..*"
      anyAddress: ~

2.2. Socket bindings

Socket bindings map endpoint connectors to network interfaces and ports. By default, Data Grid Server includes a socket binding configuration that listens on the localhost interface, 127.0.0.1, at port 11222 for the REST and Hot Rod endpoints. If you enable the Memcached endpoint, the default socket bindings configure Data Grid Server to bind to port 11221.

Default socket bindings

<server xmlns="urn:infinispan:server:14.0">
  <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>
</server>

Configuration element or attributeDescription

socket-bindings

Root element that contains all network interfaces and ports to which Data Grid Server endpoints can bind and listen for client connections.

default-interface

Declare the network interface that Data Grid Server listens on by default.

port-offset

Specifies the offset that Data Grid Server applies to port declarations for socket bindings.

socket-binding

Configures Data Grid Server to bind to a port on a network interface.

Custom socket binding declarations

The following example configuration adds an interface declaration named "private" and a socket-binding declaration that binds Data Grid Server to the private IP address:

XML

<server xmlns="urn:infinispan:server:14.0">
  <interfaces>
    <interface name="public">
      <inet-address value="${infinispan.bind.address:127.0.0.1}"/>
    </interface>
    <interface name="private">
      <inet-address value="10.1.2.3"/>
    </interface>
  </interfaces>

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

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

JSON

{
	"server": {
		"interfaces": [{
			"name": "private",
			"inet-address": {
				"value": "10.1.2.3"
			}
		}, {
			"name": "public",
			"inet-address": {
				"value": "127.0.0.1"
			}
		}],
		"socket-bindings": {
			"port-offset": "0",
			"default-interface": "public",
			"socket-binding": [{
				"name": "private_binding",
				"port": "1234",
				"interface": "private"
			}]
		},
		"endpoints": {
			"endpoint": {
				"socket-binding": "private_binding",
				"security-realm": "default"
			}
		}
	}
}

YAML

server:
  interfaces:
    - name: "private"
      inetAddress:
        value: "10.1.2.3"
    - name: "public"
      inetAddress:
        value: "127.0.0.1"
  socketBindings:
    portOffset: "0"
    defaultInterface: "public"
    socketBinding:
      - name: "private_binding"
        port: "49152"
        interface: "private"
  endpoints:
    endpoint:
      socketBinding: "private_binding"
      securityRealm: "default"

2.3. Changing the bind address for Data Grid Server

Data Grid Server binds to a network IP address to listen for inbound client connections on the Hot Rod and REST endpoints. You can specify that IP address directly in your Data Grid Server configuration or when starting server instances.

Prerequisites

  • Have at least one Data Grid Server installation.

Procedure

Specify the IP address to which Data Grid Server binds in one of the following ways:

  • Open your Data Grid Server configuration and set the value for the inet-address element, for example: 

    <server xmlns="urn:infinispan:server:14.0">
  <interfaces>
    <interface name="custom">
      <inet-address value="${infinispan.bind.address:192.0.2.0}"/>
    </interface>
  </interfaces>
</server>

  • Use the -b option or the infinispan.bind.address system property.

    Linux

    bin/server.sh -b 192.0.2.0

    Windows

    bin\server.bat -b 192.0.2.0

2.3.1. Listening on all addresses

If you specify the 0.0.0.0 meta-address, or INADDR_ANY, as the bind address in your Data Grid Server configuration, it listens for incoming client connections on all available network interfaces.

Client intelligence

Configuring Data Grid to listen on all addresses affects how it provides Hot Rod clients with cluster topology. If there are multiple interfaces to which Data Grid Server binds, then it sends a list of IP addresses for each interface.

For example, a cluster where each server node binds to:

  • 10.0.0.0/8 subnet
  • 192.168.0.0/16 subnet
  • 127.0.0.1 loopback

Hot Rod clients receive IP addresses for server nodes that belong to the interface through which the clients connect. If a client connects to 192.168.0.0, for example, it does not receive any cluster topology details for nodes that listen on 10.0.0.0.

Netmask override

Kubernetes, and some other environments, divide the IP address space into subnets and use those different subnets as a single network. For example, 10.129.2.100/23 and 10.129.4.100/23 are in different subnets but belong to the 10.0.0.0/8 network.

For this reason, Data Grid Server overrides netmasks that the host system provides with netmasks that follow IANA conventions for private and reserved networks:

  • IPv4: 10.0.0.0/8, 100.64.0.0/10, 192.168.0.0/16`, 172.16.0.0/12, 169.254.0.0/16 and 240.0.0.0/4
  • IPv6: fc00::/7 and fe80::/10

See RFC 1112, RFC 1918, RFC 3927, RFC 6598 for IPv4 or RFC 4193, RFC 3513 for IPv6.

Note

You can optionally configure the Hot Rod connector to use the netmask that the host system provides for interfaces with the network-prefix-override attribute in your Data Grid Server configuration.

Additional resources

2.4. Data Grid Server ports and protocols

Data Grid Server provides network endpoints that allow client access with different protocols.

PortProtocolDescription

11222

TCP

Hot Rod and REST

11221

TCP

Memcached (disabled by default)

Single port

Data Grid Server exposes multiple protocols through a single TCP port, 11222. 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.

HTTP/1.1 upgrade headers

Client requests can include the HTTP/1.1 upgrade header field to initiate HTTP/1.1 connections with Data Grid Server. Client applications can then send the Upgrade: protocol header field, where protocol is a server endpoint.

Application-Layer Protocol Negotiation (ALPN)/Transport Layer Security (TLS)

Client requests include Server Name Indication (SNI) mappings for Data Grid Server endpoints to negotiate protocols over a TLS connection.

Note

Applications must use a TLS library that supports the ALPN extension. Data Grid uses WildFly OpenSSL bindings for Java.

Automatic Hot Rod detection

Client requests that include Hot Rod headers automatically route to Hot Rod endpoints.

2.4.1. Configuring network firewalls for Data Grid traffic

Adjust firewall rules to allow traffic between Data Grid Server and client applications.

Procedure

On Red Hat Enterprise Linux (RHEL) workstations, for example, you can allow traffic to port 11222 with firewalld as follows: 

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

To configure firewall rules that apply across a network, you can use the nftables utility.

Reference

2.5. Specifying port offsets

Configure port offsets for multiple Data Grid Server instances on the same host. The default port offset is 0.

Procedure

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.

Linux
bin/server.sh -o 100
Windows
bin\server.bat -o 100