Securing the environment and restricting access to clusters is of critical importance for any deployment that stores sensitive data. This guide provides information and security best practices to help you protect Infinispan caches against network intrusion and unauthorized access.

1. Infinispan Security

Infinispan provides security for components as well as data across different layers:

  • Within the core library to provide role-based access control (RBAC) to CacheManagers, Cache instances, and stored data.

  • Over remote protocols to authenticate client requests and encrypt network traffic.

  • Across nodes in clusters to authenticate new cluster members and encrypt the cluster transport.

The Infinispan core library uses standard Java security libraries such as JAAS, JSSE, JCA, JCE, and SASL to ease integration and improve compatibility with custom applications and container environments. For this reason, the Infinispan core library provides only interfaces and a set of basic implementations.

Infinispan servers support a wide range of security standards and mechanisms to readily integrate with enterprise-level security frameworks.

2. Security authorization with role-based access control

Role-based access control (RBAC) capabilities use different permissions levels to restrict user interactions with Infinispan.

2.1. Infinispan user roles and permissions

Infinispan includes several roles that provide users with permissions to access caches and Infinispan resources.

Role Permissions Description

admin

ALL

Superuser with all permissions including control of the Cache Manager lifecycle.

deployer

ALL_READ, ALL_WRITE, LISTEN, EXEC, MONITOR, CREATE

Can create and delete Infinispan resources in addition to application permissions.

application

ALL_READ, ALL_WRITE, LISTEN, EXEC, MONITOR

Has read and write access to Infinispan resources in addition to observer permissions. Can also listen to events and execute server tasks and scripts.

observer

ALL_READ, MONITOR

Has read access to Infinispan resources in addition to monitor permissions.

monitor

MONITOR

Can view statistics via JMX and the metrics endpoint.
Additional resources

2.1.1. Permissions

User roles are sets of permissions with different access levels.

Table 1. Cache Manager permissions

Permission

Function

Description

CONFIGURATION

defineConfiguration

Defines new cache configurations.

LISTEN

addListener

Registers listeners against a Cache Manager.

LIFECYCLE

stop

Stops the Cache Manager.

CREATE

createCache, removeCache

Create and remove container resources such as caches, counters, schemas, and scripts.

MONITOR

getStats

Allows access to JMX statistics and the metrics endpoint.

ALL

-

Includes all Cache Manager permissions.
Table 2. Cache permissions

Permission

Function

Description

READ

get, contains

Retrieves entries from a cache.

WRITE

put, putIfAbsent, replace, remove, evict

Writes, replaces, removes, evicts data in a cache.

EXEC

distexec, streams

Allows code execution against a cache.

LISTEN

addListener

Registers listeners against a cache.

BULK_READ

keySet, values, entrySet, query

Executes bulk retrieve operations.

BULK_WRITE

clear, putAll

Executes bulk write operations.

LIFECYCLE

start, stop

Starts and stops a cache.

ADMIN

getVersion, addInterceptor*, removeInterceptor, getInterceptorChain, getEvictionManager, getComponentRegistry, getDistributionManager, getAuthorizationManager, evict, getRpcManager, getCacheConfiguration, getCacheManager, getInvocationContextContainer, setAvailability, getDataContainer, getStats, getXAResource

Allows access to underlying components and internal structures.

MONITOR

getStats

Allows access to JMX statistics and the metrics endpoint.

ALL

-

Includes all cache permissions.

ALL_READ

-

Combines the READ and BULK_READ permissions.

ALL_WRITE

-

Combines the WRITE and BULK_WRITE permissions.
Additional resources

2.1.2. Role and permission mappers

Infinispan users are implemented with the javax.security.auth.Subject class and represent a grouping of security principals of type java.security.Principal.

Infinispan includes the PrincipalRoleMapper API to associate security principals to roles and the RolePermissionMapper API to associate roles with sets of permissions. Infinispan also provides the following role and permission mapper implementations:

Cluster role mapper

Stores principal to role mappings in the cluster registry.

Cluster permission mapper

Stores role to permission mappings in the cluster registry and allows you to dynamically modify user roles and permissions.

Identity role mapper

Uses the principal name as the role name. The type or format of the principal name depends on the source. For example in an LDAP directory the principal name could be a Distinguished Name (DN).

Common name role mapper

Uses the Common Name (CN) as the role name. You can use this role mapper with an LDAP directory that contains Distinguished Names (DN); for example cn=managers,ou=people,dc=example,dc=com maps to the managers role.

Additional resources

2.1.3. Configuring role mappers

Infinispan enables the cluster role mapper and cluster permission mapper by default. You should configure role mappers if you want to use the identity role mapper, Common Name (CN) role mapper, or a custom implementation. For example, if your deployment integrates with an LDAP directory and you want to use the Distinguished Name (DN) as the security principal you can configure Infinispan to use the Common Name (CN) role mapper.

Procedure

  1. Open your Infinispan configuration for editing.

  2. Declare the role mapper as part of the security authorization in the Cache Manager configuration.

  3. Save the changes to your configuration.

With embedded caches you can programmatically configure role and permission mappers with the principalRoleMapper() and rolePermissionMapper() methods.

Role mapper configuration
XML
<cache-container>
  <security>
    <authorization>
      <common-name-role-mapper />
    </authorization>
  </security>
</cache-container>
JSON
{
  "infinispan" : {
    "cache-container" : {
      "security" : {
        "authorization" : {
          "common-name-role-mapper": {}
        }
      }
    }
  }
}
YAML
infinispan:
  cacheContainer:
    security:
      authorization:
        commonNameRoleMapper: ~
Additional resources

2.2. Granting roles to users

Assign roles to users and grant them permissions to perform cache operations and interact with Infinispan resources.

Grant roles to groups instead of users if you want to assign the same role to multiple users and centrally maintain their permissions.
Prerequisites

  • Have ADMIN permissions for Infinispan.

  • Create Infinispan users.

Procedure

  1. Create a CLI connection to Infinispan.

  2. Assign roles to users with the user roles grant command, for example:

    [//containers/default]> user roles grant --roles=deployer katie
Verification

List roles that you grant to users with the user roles ls command.

[//containers/default]> user roles ls katie
["deployer"]

2.3. Adding users to groups

Groups let you change permissions for multiple users. You assign a role to a group and then add users to that group. Users inherit permissions from the group role.

You use groups as part of a property realm in the Infinispan Server configuration. Each group is a special type of user that also requires a username and password.
Prerequisites

  • Have ADMIN permissions for Infinispan.

  • Create Infinispan users.

Procedure

  1. Create a CLI connection to Infinispan.

  2. Use the user create command to create a group.

    1. Specify a group name with the --groups argument.

    2. Set a username and password for the group.

      [//containers/default]> user create --groups=developers developers -p changeme

  3. List groups.

    [//containers/default]> user ls --groups
["developers"]

  4. Grant a role to the group.

    [//containers/default]> user roles grant --roles=application developers

  5. List roles for the group.

    [//containers/default]> user roles ls developers
["application"]

  6. Add users to the group one at a time.

    [//containers/default]> user groups john --groups=developers
Verification

Open groups.properties and confirm the group exists.

$ cat server/conf/groups.properties

developers=application

2.4. Creating custom roles at runtime

Add roles with custom permission mappings while your Infinispan cluster is running. Infinispan stores any roles that you create dynamically in the server/data directory of your Infinispan Server installation so they are available after cluster restarts.

Dynamically creating and removing roles can have a performance impact because Infinispan recomputes user permissions each time you add or remove a role. You should avoid frequently or repeatedly adding roles at runtime in any production environment.
Prerequisites

  • Have ADMIN permissions for Infinispan.

  • Have access to the command line interface (CLI) for a running Infinispan cluster.

Procedure

  1. Create a CLI connection to Infinispan.

  2. Define a role with set of permissions with the user roles create command.

    [//containers/default]> user roles create --permissions=ALL_WRITE,LISTEN temprole
[//containers/default]> user roles create --permissions=READ,WRITE myrole

  3. Assign those roles to user with the user roles grant command.

    [//containers/default]> user roles grant --roles=temprole myrole username
Verification

List roles for users with the user roles ls command.

[//containers/default]> user roles ls username
["temprole,myrole"]

To confirm user permissions, log in to the CLI or Infinispan Console with those credentials and try performing an operation. If the user does not have permission for an operation, Infinispan denies the request.

Next steps

  • If you are temporarily assigning roles to users, you should remove them when you are done.

    [//containers/default]> user roles deny --roles=temprole username
[//containers/default]> user remove roles temprole

2.5. Adding custom roles to Cache Manager configuration

Add roles with custom permission mappings to your Cache Manager configuration before you start your Infinispan cluster.

Procedure

  1. Open your Infinispan configuration for editing.

  2. Add a security authorization section to your Cache Manager configuration.

  3. Declare each custom role and permission mapping in a role element or field.

  4. Specify a unique name for each custom role with the name attribute.

  5. Specify the permissions for the role with the permissions attribute.

  6. Save the changes to your configuration.

Next steps

Assign roles to Infinispan users with the user roles grant command.

Custom roles and permissions configuration

XML
<infinispan>
  <cache-container name="custom-authorization">
    <security>
      <authorization>
        <role name="temprole" permissions="ALL_WRITE,LISTEN" />
        <role name="myrole" permissions="READ,WRITE"/>
      </authorization>
    </security>
  </cache-container>
</infinispan>
JSON
{
  "infinispan" : {
    "cache-container" : {
      "name" : "custom-authorization",
      "security" : {
         "authorization" : {
          "roles" : {
            "temprole" : {
              "role" : {
                "permissions" : "ALL_WRITE LISTEN"
              }
            },
            "myrole" : {
              "role" : {
                "permissions" : "READ WRITE"
              }
            }
          }
        }
      }
    }
  }
}
YAML
infinispan:
  cacheContainer:
    name: "custom-authorization"
    security:
      authorization:
        roles:
          temprole:
            role:
              permissions: "ALL_WRITE LISTEN"
          myrole:
            role:
              permissions: "READ WRITE"

2.6. Configuring caches with security authorization

Add security authorization to caches to enforce role-based access control (RBAC). This requires Infinispan users to have a role with a sufficient level of permission to perform cache operations.

Prerequisites

  • Create Infinispan users and either grant them with roles or assign them to groups.

Procedure

  1. Open your Infinispan configuration for editing.

  2. Add a security section to the configuration.

  3. Specify roles that users must have to perform cache operations with the authorization element.

    You can implicitly add all roles defined in the Cache Manager or explicitly define a subset of roles.

  4. Save the changes to your configuration.

Implicit role configuration

The following configuration implicitly adds every role defined in the Cache Manager:

XML
<distributed-cache>
  <security>
    <authorization/>
  </security>
</distributed-cache>
JSON
{
  "distributed-cache": {
    "security": {
      "authorization": {
        "enabled": true
      }
    }
  }
}
YAML
distributedCache:
  security:
    authorization:
      enabled: true

Explicit role configuration

The following configuration explicitly adds a subset of roles defined in the Cache Manager. In this case Infinispan denies cache operations for any users that do not have one of the configured roles.

XML
<distributed-cache>
  <security>
    <authorization roles="admin supervisor"/>
  </security>
</distributed-cache>
JSON
{
  "distributed-cache": {
    "security": {
      "authorization": {
        "enabled": true,
        "roles": ["admin","supervisor"]
      }
    }
  }
}
YAML
distributedCache:
  security:
    authorization:
      enabled: true
      roles: ["admin","supervisor"]

2.7. Enabling and configuring authorization for embedded caches

When using embedded caches, you can configure authorization with the GlobalSecurityConfigurationBuilder and ConfigurationBuilder classes.

Procedure

  1. Construct a GlobalConfigurationBuilder and enable security authorization with the security().authorization().enable() method.

  2. Specify a role mapper with the principalRoleMapper() method.

  3. If required, define custom role and permission mappings with the role() and permission() methods.

    GlobalRoleConfigurationBuilder global = new GlobalConfigurationBuilder();
  global.security().authorization().enable()
          .principalRoleMapper(new ClusterRoleMapper())
          .role("admin").permission(AuthorizationPermission.ADMIN)
          .role("reader").permission(AuthorizationPermission.ALL_READ);

  4. Enable authorization for caches in the ConfigurationBuilder.

    • Add all roles from the global configuration.

      ConfigurationBuilder config = new ConfigurationBuilder();
config.security().authorization().enable();

    • Explicitly define roles for a cache so that Infinispan denies access for users who do not have the role.

      ConfigurationBuilder config = new ConfigurationBuilder();
config.security().authorization().enable().role("admin");
Additional resources

2.8. Adding authorization roles at runtime

Dynamically map roles to permissions when using security authorization with Infinispan caches.

Prerequisites

  • Configure authorization for embedded caches.

  • Have ADMIN permissions for Infinispan.

Procedure

  1. Obtain the RolePermissionMapper instance.

  2. Define new roles with the addRole() method.

    MutablePermissionMapper mapper = (MutablePermissionMapper) cacheManager.getCacheManagerConfiguration().security().authorization().rolePermissionMapper();
mapper.addRole(Role.newRole("myroleone", true, AuthorizationPermission.ALL_WRITE, AuthorizationPermission.LISTEN));
mapper.addRole(Role.newRole("myroletwo", true, AuthorizationPermission.READ, AuthorizationPermission.WRITE));
Additional resources

2.9. Executing code with secure caches

When you construct a DefaultCacheManager for an embedded cache that uses security authorization, the Cache Manager returns a SecureCache that checks the security context before invoking any operations. A SecureCache also ensures that applications cannot retrieve lower-level insecure objects such as DataContainer. For this reason, you must execute code with a Infinispan user that has a role with the appropriate level of permission.

Prerequisites

  • Configure authorization for embedded caches.

Procedure

  1. If necessary, retrieve the current Subject from the Infinispan context or AccessControlContext:

    Security.getSubject();

  2. Wrap method calls in a PrivilegedAction to execute them with the Subject.

    Security.doAs(mySubject, PrivilegedAction<String>() -> cache.put("key", "value"));

You can use the Security.doAs() or Subject.doAs() method. Infinispan recommends Security.doAs() for better performance.
Additional resources

2.10. Configuring the access control list (ACL) cache

When you grant or deny roles to users, Infinispan stores details about which users can access your caches internally. This ACL cache improves performance for security authorization by avoiding the need for Infinispan to calculate if users have the appropriate permissions to perform read and write operations for every request.

Whenever you grant or deny roles to users, Infinispan flushes the ACL cache to ensure it applies user permissions correctly. This means that Infinispan must recalculate cache permissions for all users each time you grant or deny roles. For best performance you should not frequently or repeatedly grant and deny roles in production environments.
Procedure

  1. Open your Infinispan configuration for editing.

  2. Specify the maximum number of entries for the ACL cache with the cache-size attribute.

    Entries in the ACL cache have a cardinality of caches * users. You should set the maximum number of entries to a value that can hold information for all your caches and users. For example, the default size of 1000 is appropriate for deployments with up to 100 caches and 10 users.

  3. Set the timeout value, in milliseconds, with the cache-timeout attribute.

    If Infinispan does not access an entry in the ACL cache within the timeout period that entry is evicted. When the user subsequently attempts cache operations then Infinispan recalculates their cache permissions and adds an entry to the ACL cache.

    Specifying a value of 0 for either the cache-size or cache-timeout attribute disables the ACL cache. You should disable the ACL cache only if you disable authorization.

  4. Save the changes to your configuration.

ACL cache configuration

XML
<infinispan>
  <cache-container name="acl-cache-configuration">
    <security cache-size="1000"
              cache-timeout="300000">
      <authorization/>
    </security>
  </cache-container>
</infinispan>
JSON
{
  "infinispan" : {
    "cache-container" : {
      "name" : "acl-cache-configuration",
      "security" : {
        "cache-size" : "1000",
        "cache-timeout" : "300000",
        "authorization" : {}
      }
    }
  }
}
YAML
infinispan:
  cacheContainer:
    name: "acl-cache-configuration"
    security:
      cache-size: "1000"
      cache-timeout: "300000"
      authorization: ~
Additional resources

3. Encrypting cluster transport

Secure cluster transport so that nodes communicate with encrypted messages. You can also configure Infinispan clusters to perform certificate authentication so that only nodes with valid identities can join.

3.1. Securing cluster transport with TLS identities

Add SSL/TLS identities to a Infinispan Server security realm and use them to secure cluster transport. Nodes in the Infinispan Server cluster then exchange SSL/TLS certificates to encrypt JGroups messages, including RELAY messages if you configure cross-site replication.

Prerequisites

  • Install a Infinispan Server cluster.

Procedure

  1. Create a TLS keystore that contains a single certificate to identify Infinispan Server.

    You can also use a PEM file if it contains a private key in PKCS#1 or PKCS#8 format, a certificate, and has an empty password: password="".

    If the certificate in the keystore is not signed by a public certificate authority (CA) then you must also create a trust store that contains either the signing certificate or the public key.

  2. Add the keystore to the $ISPN_HOME/server/conf directory.

  3. Add the keystore to a new security realm in your Infinispan Server configuration.

    You should create dedicated keystores and security realms so that Infinispan Server endpoints do not use the same security realm as cluster transport.

    		 
    <server xmlns="urn:infinispan:server:14.0">
  <security>
    <security-realms>
      <security-realm name="cluster-transport">
        <server-identities>
          <ssl>
            <!-- Adds a keystore that contains a certificate that provides SSL/TLS identity to encrypt cluster transport. -->
            <keystore path="server.pfx"
                      relative-to="infinispan.server.config.path"
                      password="secret"
                      alias="server"/>
          </ssl>
        </server-identities>
      </security-realm>
    </security-realms>
  </security>
</server>

  4. Configure cluster transport to use the security realm by specifying the name of the security realm with the server:security-realm attribute.

    <infinispan>
  <cache-container>
    <transport server:security-realm="cluster-transport"/>
  </cache-container>
</infinispan>
Verification

When you start Infinispan Server, the following log message indicates that the cluster is using the security realm for cluster transport:

[org.infinispan.SERVER] ISPN080060: SSL Transport using realm <security_realm_name>

3.2. JGroups encryption protocols

To secure cluster traffic, you can configure Infinispan nodes to encrypt JGroups message payloads with secret keys.

Infinispan nodes can obtain secret keys from either:

  • The coordinator node (asymmetric encryption).

  • A shared keystore (symmetric encryption).

Retrieving secret keys from coordinator nodes

You configure asymmetric encryption by adding the ASYM_ENCRYPT protocol to a JGroups stack in your Infinispan configuration. This allows Infinispan clusters to generate and distribute secret keys.

When using asymmetric encryption, you should also provide keystores so that nodes can perform certificate authentication and securely exchange secret keys. This protects your cluster from man-in-the-middle (MitM) attacks.

Asymmetric encryption secures cluster traffic as follows:

  1. The first node in the Infinispan cluster, the coordinator node, generates a secret key.

  2. A joining node performs certificate authentication with the coordinator to mutually verify identity.

  3. The joining node requests the secret key from the coordinator node. That request includes the public key for the joining node.

  4. The coordinator node encrypts the secret key with the public key and returns it to the joining node.

  5. The joining node decrypts and installs the secret key.

  6. The node joins the cluster, encrypting and decrypting messages with the secret key.

Retrieving secret keys from shared keystores

You configure symmetric encryption by adding the SYM_ENCRYPT protocol to a JGroups stack in your Infinispan configuration. This allows Infinispan clusters to obtain secret keys from keystores that you provide.

  1. Nodes install the secret key from a keystore on the Infinispan classpath at startup.

  2. Node join clusters, encrypting and decrypting messages with the secret key.

Comparison of asymmetric and symmetric encryption

ASYM_ENCRYPT with certificate authentication provides an additional layer of encryption in comparison with SYM_ENCRYPT. You provide keystores that encrypt the requests to coordinator nodes for the secret key. Infinispan automatically generates that secret key and handles cluster traffic, while letting you specify when to generate secret keys. For example, you can configure clusters to generate new secret keys when nodes leave. This ensures that nodes cannot bypass certificate authentication and join with old keys.

SYM_ENCRYPT, on the other hand, is faster than ASYM_ENCRYPT because nodes do not need to exchange keys with the cluster coordinator. A potential drawback to SYM_ENCRYPT is that there is no configuration to automatically generate new secret keys when cluster membership changes. Users are responsible for generating and distributing the secret keys that nodes use to encrypt cluster traffic.

3.3. Securing cluster transport with asymmetric encryption

Configure Infinispan clusters to generate and distribute secret keys that encrypt JGroups messages.

Procedure

  1. Create a keystore with certificate chains that enables Infinispan to verify node identity.

  2. Place the keystore on the classpath for each node in the cluster.

    For Infinispan Server, you put the keystore in the $ISPN_HOME directory.

  3. Add the SSL_KEY_EXCHANGE and ASYM_ENCRYPT protocols to a JGroups stack in your Infinispan configuration, as in the following example:

    <infinispan>
  <jgroups>
    <!-- Creates a secure JGroups stack named "encrypt-tcp" that extends the default TCP stack. -->
    <stack name="encrypt-tcp" extends="tcp">
      <!-- Adds a keystore that nodes use to perform certificate authentication. -->
      <!-- Uses the stack.combine and stack.position attributes to insert SSL_KEY_EXCHANGE into the default TCP stack after VERIFY_SUSPECT. -->
      <SSL_KEY_EXCHANGE keystore_name="mykeystore.jks"
                        keystore_password="changeit"
                        stack.combine="INSERT_AFTER"
                        stack.position="VERIFY_SUSPECT"/>
      <!-- Configures ASYM_ENCRYPT -->
      <!-- Uses the stack.combine and stack.position attributes to insert ASYM_ENCRYPT into the default TCP stack before pbcast.NAKACK2. -->
      <!-- The use_external_key_exchange = "true" attribute configures nodes to use the `SSL_KEY_EXCHANGE` protocol for certificate authentication. -->
      <ASYM_ENCRYPT asym_keylength="2048"
                    asym_algorithm="RSA"
                    change_key_on_coord_leave = "false"
                    change_key_on_leave = "false"
                    use_external_key_exchange = "true"
                    stack.combine="INSERT_BEFORE"
                    stack.position="pbcast.NAKACK2"/>
    </stack>
  </jgroups>
  <cache-container name="default" statistics="true">
    <!-- Configures the cluster to use the JGroups stack. -->
    <transport cluster="${infinispan.cluster.name}"
               stack="encrypt-tcp"
               node-name="${infinispan.node.name:}"/>
  </cache-container>
</infinispan>
Verification

When you start your Infinispan cluster, the following log message indicates that the cluster is using the secure JGroups stack:

[org.infinispan.CLUSTER] ISPN000078: Starting JGroups channel cluster with stack <encrypted_stack_name>

Infinispan nodes can join the cluster only if they use ASYM_ENCRYPT and can obtain the secret key from the coordinator node. Otherwise the following message is written to Infinispan logs:

[org.jgroups.protocols.ASYM_ENCRYPT] <hostname>: received message without encrypt header from <hostname>; dropping it
Additional resources

3.4. Securing cluster transport with symmetric encryption

Configure Infinispan clusters to encrypt JGroups messages with secret keys from keystores that you provide.

Procedure

  1. Create a keystore that contains a secret key.

  2. Place the keystore on the classpath for each node in the cluster.

    For Infinispan Server, you put the keystore in the $ISPN_HOME directory.

  3. Add the SYM_ENCRYPT protocol to a JGroups stack in your Infinispan configuration.

<infinispan>
  <jgroups>
    <!-- Creates a secure JGroups stack named "encrypt-tcp" that extends the default TCP stack. -->
    <stack name="encrypt-tcp" extends="tcp">
      <!-- Adds a keystore from which nodes obtain secret keys. -->
      <!-- Uses the stack.combine and stack.position attributes to insert SYM_ENCRYPT into the default TCP stack after VERIFY_SUSPECT. -->
      <SYM_ENCRYPT keystore_name="myKeystore.p12"
                   keystore_type="PKCS12"
                   store_password="changeit"
                   key_password="changeit"
                   alias="myKey"
                   stack.combine="INSERT_AFTER"
                   stack.position="VERIFY_SUSPECT"/>
    </stack>
  </jgroups>
  <cache-container name="default" statistics="true">
    <!-- Configures the cluster to use the JGroups stack. -->
    <transport cluster="${infinispan.cluster.name}"
               stack="encrypt-tcp"
               node-name="${infinispan.node.name:}"/>
  </cache-container>
</infinispan>
Verification

When you start your Infinispan cluster, the following log message indicates that the cluster is using the secure JGroups stack:

[org.infinispan.CLUSTER] ISPN000078: Starting JGroups channel cluster with stack <encrypted_stack_name>

Infinispan nodes can join the cluster only if they use SYM_ENCRYPT and can obtain the secret key from the shared keystore. Otherwise the following message is written to Infinispan logs:

[org.jgroups.protocols.SYM_ENCRYPT] <hostname>: received message without encrypt header from <hostname>; dropping it
Additional resources

4. Infinispan Ports and Protocols

As Infinispan distributes data across your network and can establish connections for external client requests, you should be aware of the ports and protocols that Infinispan uses to handle network traffic.

If run Infinispan as a remote server then you might need to allow remote clients through your firewall. Likewise, you should adjust ports that Infinispan nodes use for cluster communication to prevent conflicts or network issues.

4.1. Infinispan Server ports and protocols

Infinispan 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

Infinispan 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 Infinispan clusters. Using a single port also enhances security by minimizing the attack surface on the network.

Infinispan 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 Infinispan 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 Infinispan Server endpoints to negotiate protocols over a TLS connection.

Applications must use a TLS library that supports the ALPN extension. Infinispan uses WildFly OpenSSL bindings for Java.
Automatic Hot Rod detection

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

4.1.1. Configuring network firewalls for Infinispan traffic

Adjust firewall rules to allow traffic between Infinispan 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.

4.2. TCP and UDP ports for cluster traffic

Infinispan uses the following ports for cluster transport messages:

Default Port Protocol Description

7800

TCP/UDP

JGroups cluster bind port

46655

UDP

JGroups multicast

Cross-site replication

Infinispan uses the following ports for the JGroups RELAY2 protocol:

7900

For Infinispan clusters running on Kubernetes.

7800

If using UDP for traffic between nodes and TCP for traffic between clusters.

7801

If using TCP for traffic between nodes and TCP for traffic between clusters.