Chapter 2. Network interfaces and socket bindings
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="USD{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: ~ Link local 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="USD{infinispan.socket.binding.port-offset:0}"> <socket-binding name="default" port="USD{infinispan.bind.port:11222}"/> <socket-binding name="memcached" port="11221"/> </socket-bindings> </server> Configuration element or attribute Description 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="USD{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="USD{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: Use the -b option or the infinispan.bind.address system property. Linux Windows 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 Data Grid Server schema reference RFC 1112 RFC 1918 RFC 3513 RFC 3927 RFC 4193 RFC 6598 2.4. Data Grid Server ports and protocols Data Grid Server provides network endpoints that allow client access with different protocols. Port Protocol Description 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: To configure firewall rules that apply across a network, you can use the nftables utility. Reference Using and configuring firewalld Getting started with nftables 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 Windows
<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="USD{infinispan.bind.address:127.0.0.1}"/> </interface> </interfaces> </server> { "server": { "interfaces": [{ "name": "public", "inet-address": { "value": "127.0.0.1" } }] } } server: interfaces: - name: "public" inetAddress: value: "127.0.0.1" <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> { "server": { "interfaces": [{ "name": "public", "loopback": null }] } } server: interfaces: - name: "public" loopback: ~ <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> { "server": { "interfaces": [{ "name": "public", "non_loopback": null }] } } server: interfaces: - name: "public" nonLoopback: ~ <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> { "server": { "interfaces": [{ "name": "public", "any_address": null }] } } server: interfaces: - name: "public" anyAddress: ~ <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> { "server": { "interfaces": [{ "name": "public", "link_local": null }] } } server: interfaces: - name: "public" linkLocal: ~ <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> { "server": { "interfaces": [{ "name": "public", "site_local": null }] } } server: interfaces: - name: "public" siteLocal: ~ <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> { "server": { "interfaces": [{ "name": "public", "match-host": { "value": "my_host_name" } }] } } server: interfaces: - name: "public" matchHost: value: "my_host_name" <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> { "server": { "interfaces": [{ "name": "public", "match-interface": { "value": "eth0" } }] } } server: interfaces: - name: "public" matchInterface: value: "eth0" <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> { "server": { "interfaces": [{ "name": "public", "match-address": { "value": "132\\..*" } }] } } server: interfaces: - name: "public" matchAddress: value: "127\\..*" <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> { "server": { "interfaces": [{ "name": "public", "match-host": { "value": "my_host_name" }, "match-address": { "value": "132\\..*" }, "any_address": null }] } } server: interfaces: - name: "public" matchHost: value: "my_host_name" matchAddress: value: "132\\..*" anyAddress: ~ <server xmlns="urn:infinispan:server:14.0"> <socket-bindings default-interface="public" port-offset="USD{infinispan.socket.binding.port-offset:0}"> <socket-binding name="default" port="USD{infinispan.bind.port:11222}"/> <socket-binding name="memcached" port="11221"/> </socket-bindings> </server> <server xmlns="urn:infinispan:server:14.0"> <interfaces> <interface name="public"> <inet-address value="USD{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="USD{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> { "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" } } } } 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" <server xmlns="urn:infinispan:server:14.0"> <interfaces> <interface name="custom"> <inet-address value="USD{infinispan.bind.address:192.0.2.0}"/> </interface> </interfaces> </server> bin/server.sh -b 192.0.2.0 bin\server.bat -b 192.0.2.0 firewall-cmd --add-port=11222/tcp --permanent success firewall-cmd --list-ports | grep 11222 11222/tcp bin/server.sh -o 100 bin\server.bat -o 100