Chapter 12. Environment Variables

12.1. Image Information

The following environment variables provide information about the image. You should not modify these environment variables.

JBOSS_DATAGRID_VERSION: Displays the version of Red Hat JBoss Data Grid on which the container is based.
JBOSS_HOME: Displays the directory that contains the distribution: /opt/datagrid.
JBOSS_IMAGE_NAME: Displays the name of the image.
JBOSS_IMAGE_RELEASE: Displays the image release label.
JBOSS_IMAGE_VERSION: Displays the image version.
JBOSS_MODULES_SYSTEM_PKGS: Lists JBoss system modules.
JBOSS_PRODUCT: Displays the product label: datagrid.
LAUNCH_JBOSS_IN_BACKGROUND: Allows graceful shutdowns.

12.2. Container Configuration

Configure containers with the following environment variables:

USERNAME

Sets the name for the JBoss Data Grid user.

PASSWORD

Sets the password for the JBoss Data Grid user.

DATAGRID_SPLIT

Determines if the data directory for each node should be split in a mesh. The value is true or false (default).

If you set the value to true, you must also configure a persistent volume mounted on /opt/datagrid/standalone/partitioned_data.

Note

Use the datagrid72-partition template to deploy an example application that preserves cache metadata between restarts. Ensure that the ${APPLICATION_NAME}-datagrid-claim persistent volume claim is available and that the ${APPLICATION_NAME}-datagrid-pvol persistent volume is mounted on /opt/datagrid/standalone/partitioned_data.

JAVA_OPTS_APPEND

Appends options to the JAVA_OPTS environment variable on startup.

For example, JAVA_OPTS_APPEND=-Dfoo=bar

JGROUPS_CLUSTER_PASSWORD

Matches the password for accessing JGroups configuration. It must be the same across the cluster.

By default, the image uses the value for the OPENSHIFT_KUBE_PING_LABELS variable; however, JBoss application templates generate random values.

See Securing Network Traffic for information about using JGroups keystores to encrypt cluster communication.

OPENSHIFT_KUBE_PING_LABELS

Specifies the clustering labels selector.

For example, OPENSHIFT_KUBE_PING_LABELS=application=eap-app

OPENSHIFT_KUBE_PING_NAMESPACE

Specifies the clustering project namespace.

TRANSPORT_LOCK_TIMEOUT

Sets the time to wait to acquire a distributed lock. The default value is 240000.

JBoss Data Grid uses a distributed lock to maintain a coherent transaction log during state transfer or rehashing, which means that only one cache can perform state transfer or rehashing at a time. This constraint is in place because more than one cache could be involved in a transaction.

12.3. Cache Configuration

Configure caches with the following environemnt variables:

CACHE_NAMES

Defines cache instances in your configuration.

If you do not specify cache names, the launch script adds configuration for caches named default and memcached. The default cache configuration is a distributed-cache in SYNC mode.

Tip

Give each cache instance in your configuration a unique name. Use underscore characters (_) and descriptive labels to help you distinguish between cache instances. This ensures that you do not have conflicts when applying cache-specific configuration.

For example, CACHE_NAMES=addressbook, addressbook_indexed

CACHE_CONTAINER_START

Configures how the cache container starts. Specify one of the following:

LAZY Starts the cache container when requested by a service or deployment. This is the default.
EAGER Starts the cache container when the server starts.

CACHE_CONTAINER_STATISTICS

Configures the cache container to collect statistics. The value is true (default) or false. You can set the value to false to improve performance.

DEFAULT_CACHE

Sets the default cache for the cache container.

12.3.1. Cache Container Security Configuration

Configure security for the cache container with the following environment variables:

CONTAINER_SECURITY_CUSTOM_ROLE_MAPPER_CLASS

Specifies the class of the custom principal to role mapper.

For example, CONTAINER_SECURITY_CUSTOM_ROLE_MAPPER_CLASS=com.acme.CustomRoleMapper

CONTAINER_SECURITY_ROLE_MAPPER

Sets a role mapper for this cache container with the following values:

identity-role-mapper Uses the Principal name as the role name. This is the default role mapper if you do not specify one and use the CONTAINER_SECURITY_ROLES environment variable to define role names.
common-name-role-mapper Uses the Common Name (CN) as the role name if the Principal name is a Distinguished Name (DN). For example, the DN cn=managers,ou=people,dc=example,dc=com is mapped to the manager role name.
cluster-role-mapper Uses the ClusterRegistry to store Principal name to role mappings.
custom-role-mapper Takes the fully-qualified class name of an implementation of the org.infinispan.security.impl.PrincipalRoleMapper interface.
For more information see Role Mapping in the Developer Guide.

CONTAINER_SECURITY_ROLES

Defines role names and assigns permissions to them.

For example, CONTAINER_SECURITY_ROLES=admin=ALL, reader=READ, writer=WRITE

12.3.2. Cache Specific Configuration

You can control behavior for each cache in your configuration with these environment variables.

To set an environment variable, you specify the cache name as a prefix for the variable.

Important

You must specify the cache name as a prefix in capital letters (all caps) otherwise the configuration does not take effect.

For example, you create two separate cache instances: MyCache and MYCACHE. You then set MyCache_CACHE_TYPE=replicated to configure the MyCache instance. This configuration does not take effect. However, if you set MYCACHE_CACHE_TYPE=replicated the configuration takes effect for both the MyCache and MYCACHE instances.

<CACHE_NAME>_CACHE_TYPE

Determines whether this cache should be distributed or replicated. You can specify either distributed (default) or replicated.

<CACHE_NAME>_CACHE_START

Configures how the cache starts. Specify one of the following:

LAZY Starts the cache when requested by a service or deployment. This is the default.
EAGER Starts the cache when the server starts.

<CACHE_NAME>_CACHE_BATCHING

Enables invocation batching for this cache. The value is true or false (default).

<CACHE_NAME>_CACHE_STATISTICS

Configures the cache to collect statistics. The value is true (default) or false. You can set the value to false to improve performance.

<CACHE_NAME>_CACHE_MODE

Sets the clustered cache mode. Specify one of the following:

ASYNC for asynchronous operations.
SYNC for synchronous operations.

<CACHE_NAME>_CACHE_QUEUE_SIZE

Sets the threshold at which the replication queue is flushed when the cache is in ASYNC mode. The default value is 0 (flushing is disabled).

<CACHE_NAME>_CACHE_QUEUE_FLUSH_INTERVAL

Specifies the wakeup time, in milliseconds, for the thread that flushes the replication queue in ASYNC mode. The default value is 10.

<CACHE_NAME>_CACHE_REMOTE_TIMEOUT

Specifies the timeout, in milliseconds, to wait for acknowledgement when making remote calls in SYNC mode. If the timeout is reached, the remote call is aborted and an exception is thrown. The default value is 17500.

<CACHE_NAME>_CACHE_OWNERS

Specifies the number of cluster-wide replicas for each cache entry. The default value is 2.

<CACHE_NAME>_CACHE_SEGMENTS

Specifies the number of hash space segments per cluster. The recommended value is 10 * cluster size. The default value is 80.

<CACHE_NAME>_CACHE_L1_LIFESPAN

Specifies the maximum lifespan, in milliseconds, of an entry placed in the L1 cache. The default value is 0 (L1 is disabled).

<CACHE_NAME>_CACHE_MEMORY_EVICTION_TYPE

Defines the maximum limit for entries in the cache. You can set the following values:

COUNT Measures the number of entries in the cache. When the count exceeds the maximum, JBoss Data Grid evicts unused entries.
MEMORY Measures the amount of memory that all entries in the cache take up. When the total amount of memory exceeds the maximum, JBoss Data Grid evicts unused entries.

<CACHE_NAME>_CACHE_MEMORY_STORAGE_TYPE

Defines how JBoss Data Grid stores entries in the cache. You can set the following values:

Storage Type	Description	Eviction Type	Policy
object	Stores entries as objects in the Java heap. This is the default storage type.	COUNT	TinyLFU
binary	Stores entries as `bytes[]` in the Java heap.	COUNT or MEMORY	TinyLFU
off-heap	Stores entries as `bytes[]` in native memory outside the Java.	COUNT or MEMORY	LRU

<CACHE_NAME>_CACHE_MEMORY_EVICTION_SIZE

Configures the size of the cache before eviction starts. Set the value to a number greater than zero.

For COUNT, the size is the maximum number of entries the cache can hold before eviction starts.
For MEMORY, the size is the maximum number of bytes the cache can take from memory before eviction starts. For example, a value of 10000000000 is 10 GB.
Try different cache sizes to determine the optimal setting. A cache size that is too large can cause JBoss Data Grid to run out of memory. At the same time, a cache size that is too small wastes available memory.
Note
If you configure a JDBC store, passivation is automatically enabled when you set the eviction size to a value that is greater than zero.

<CACHE_NAME>_CACHE_MEMORY_EVICTION_STRATEGY

Controls how JBoss Data Grid performs eviction. You can set the following values:

Strategy	Description
NONE	JBoss Data Grid does not evict entries. This is the default setting unless you configure eviction.
REMOVE	JBoss Data Grid removes entries from memory so that the cache does not exceed the configured size. This is the default setting when you configure eviction.
MANUAL	JBoss Data Grid does not perform eviction. Eviction takes place manually by invoking the `evict()` method from the `Cache` API.
EXCEPTION	JBoss Data Grid does not write new entries to the cache if doing so would exceed the configured size. Instead of writing new entries to the cache, JBoss Data Grid throws a `ContainerFullException`.

<CACHE_NAME>_CACHE_MEMORY_OFF_HEAP_ADDRESS_COUNT

Specifies the number of pointers that are available in the hash map to prevent collisions when using OFFHEAP storage. Preventing collisions in the hash map improves performance.

Set the value to a number that is greater than the number of cache entries. By default address-count is 2^20, or 1048576. The parameter is always rounded up to a power of 2.

<CACHE_NAME>_CACHE_EXPIRATION_LIFESPAN

Specifies the maximum lifespan, in milliseconds, of a cache entry, after which the entry is expired cluster-wide. The default value is -1 (entries never expire).

<CACHE_NAME>_CACHE_EXPIRATION_MAX_IDLE

Specifies the maximum idle time, in milliseconds, that cache entries are maintained in the cache. If the idle time is exceeded, then the entry is expired cluster-wide. The default value is -1 (expiration is disabled).

<CACHE_NAME>_CACHE_EXPIRATION_INTERVAL

Specifies the interval, in milliseconds, between runs to purge expired entries from memory and any cache stores. The default value is 5000. Set -1 to disable expiration.

<CACHE_NAME>_JDBC_STORE_TYPE

Sets the type of JDBC store to configure. You can set the following values:

string
binary

<CACHE_NAME>_JDBC_STORE_DATASOURCE

Defines the jndiname of the datasource.

For example, <CACHE_NAME>_JDBC_STORE_DATASOURCE=java:jboss/datasources/ExampleDS

<CACHE_NAME>_KEYED_TABLE_PREFIX

Defines the prefix prepended to the cache name used when composing the name of the cache entry table. The defaule value is ispn_entry.

<CACHE_NAME>_CACHE_INDEX

Sets the indexing mode of the cache. You can set the following values:

NONE This is the default.
LOCAL
ALL

<CACHE_NAME>_INDEXING_PROPERTIES

Specifies a comma-separated list of properties to pass to the indexing system.

For example, <CACHE_NAME>_INDEXING_PROPERTIES=default.directory_provider=ram

<CACHE_NAME>_CACHE_SECURITY_AUTHORIZATION_ENABLED

Enables authorization checks for this cache. The value is true or false (default).

<CACHE_NAME>_CACHE_SECURITY_AUTHORIZATION_ROLES

Sets the roles required to access this cache.

For example, <CACHE_NAME>_CACHE_SECURITY_AUTHORIZATION_ROLES=admin, reader, writer

<CACHE_NAME>_CACHE_PARTITION_HANDLING_ENABLED

Configures the cache to enter degraded mode if it loses too many nodes. The value is true (default) or false.

Deprecated: The CACHE_PARTITION_HANDLING_ENABLED environment variable is deprecated. Use CACHE_PARTITION_HANDLING_WHEN_SPLIT and CACHE_PARTITION_MERGE_POLICY instead.

To achieve the same configuration as

CACHE_PARTITION_HANDLING_ENABLED=false, do not set environment variables so that default values take effect as follows:
```
<CACHE_NAME>_CACHE_PARTITION_HANDLING_WHEN_SPLIT=ALLOW_READ_WRITES
<CACHE_NAME>_CACHE_PARTITION_MERGE_POLICY=NONE
```

CACHE_PARTITION_HANDLING_ENABLED=true, set environment variables as follows:

<CACHE_NAME>_CACHE_PARTITION_HANDLING_WHEN_SPLIT=DENY_READ_WRITES
<CACHE_NAME>_CACHE_PARTITION_MERGE_POLICY=NONE

<CACHE_NAME>_CACHE_PARTITION_HANDLING_WHEN_SPLIT

Configures the strategy for handling partitions between nodes in a cluster when network events isolate nodes from each other. Partitions function as independent clusters until JBoss Data Grid merges cache entries to re-form a single cluster. You can set the following values:

Partition Handling Strategy Description

Partition Handling Strategy	Description
ALLOW_READ_WRITES	Nodes from any partition can read or write cache entries. This is the default value.
DENY_READ_WRITES	Nodes enter degraded mode if: * One or more hash space segments in the partition have no owners. The `owners` are the number of cluster-wide replicas for cache entries. * The partition has less than half the nodes from the most recent stable cluster topology. In degraded mode, only nodes in the same partition can read or write cache entries. All owners, or copies, for a cache entry must exist on the same partition, otherwise the read or write operation fails with an `AvailabilityException`.
ALLOW_READS	Nodes enter degraded mode similarly to the DENY_READ_WRITES strategy. Nodes from any partition can read cache entries. In degraded mode, only nodes in the same partition can write cache entries. All owners, or copies, for a cache entry must exist on the same partition, otherwise the write operation fails with an `AvailabilityException`.

ALLOW_READ_WRITES

Nodes from any partition can read or write cache entries. This is the default value.

DENY_READ_WRITES

Nodes enter degraded mode if:

* One or more hash space segments in the partition have no owners. The owners are the number of cluster-wide replicas for cache entries.

* The partition has less than half the nodes from the most recent stable cluster topology.

In degraded mode, only nodes in the same partition can read or write cache entries. All owners, or copies, for a cache entry must exist on the same partition, otherwise the read or write operation fails with an AvailabilityException.

ALLOW_READS

Nodes enter degraded mode similarly to the DENY_READ_WRITES strategy. Nodes from any partition can read cache entries.

In degraded mode, only nodes in the same partition can write cache entries. All owners, or copies, for a cache entry must exist on the same partition, otherwise the write operation fails with an AvailabilityException.

For more information, see Handling Network Partitions in the Administration and Configuration Guide.

<CACHE_NAME>_CACHE_PARTITION_MERGE_POLICY

Configures how JBoss Data Grid resolves conflicts between cache entries when merging partitions. You can set the following values:

Merge Policy	Description
NONE	Do not resolve conflicts when merging partitions. This is the default value.
PREFERRED_ALWAYS	Always use the `preferredEntry`. The `preferredEntry` is the primary replica of a cache entry that resides in the partition that contains the most nodes. If the number of nodes is equal between partitions, the `preferredEntry` is the cache entry that resides in the partition with the highest topology ID, which means that topology is more recent.
PREFERRED_NON_NULL	Use the `preferredEntry` if it has a value (non-null). If the `preferredEntry` does not have a value, use the first entry defined in `otherEntries`.
REMOVE_ALL	Remove entries (key and value) from the cache if conflicts exist.

<CACHE_NAME>_STATE_TRANSFER_TIMEOUT

Sets the amount of time, in milliseconds, to wait for other cache instances in the cluster to transfer state to the cache. If other cache instances do not transfer state before the timeout occurs, the application throws an exception and aborts startup. The default value is 240000 (4 minutes).

You must use a custom template to set this environment variable. It does not take effect if you set the state transfer timeout in the default JBoss Data Grid for OpenShift templates.

12.4. Endpoint Configuration

Clients can access JBoss Data Grid via REST, Hot Rod, and Memcached endpoints that you define in the cache configuration.

Clients that run in the same project as JBoss Data Grid for OpenShift can access the cache via Hot Rod and receive a full cluster view. These clients can also use consistent hashing capabilities.

However, when clients run in a different project to JBoss Data Grid for OpenShift, they need to access the JBoss Data Grid cluster using an OpenShift service that exposes the HotRod endpoint externally. Depending on your network configuration, clients might not have access to some pods and must use BASIC client intelligence. In these cases, clients might require extra network hops to access data, which can increase network latency.

External access to clients running in OpenShift requires routes with passthrough encryption termination. Clients must also use BASIC client intelligence and the fully qualified domain name as a TLS/SNI host name. Alternatively, you can expose the JBoss Data Grid cluster behind a Load Balancer service that is externally available.

Configure endpoints with the following environment variables:

INFINISPAN_CONNECTORS

Defines a comma-separated list of connectors to configure. Defaults to hotrod, memcached, rest. If authorization or authentication is enabled on the cache then you should remove memcached because this protocol is inherently insecure.

MEMCACHED_CACHE

Sets the cache name for the Memcached connector. Defaults to memcached if you do not specify a cache name with the CACHE_NAMES environment variable.

HOTROD_SERVICE_NAME

Defines the name of the {openshiftshort} service for the external Hot Rod connector.

The external hotrod connector is available only if you define this environment variable.

For example, if you set HOTROD_SERVICE_NAME=DATAGRID_APP_HOTROD the Hot Rod external connector returns DATAGRID_APP_HOTROD:11333.

HOTROD_AUTHENTICATION

Configures the hotrod-connectors with authentication in the ApplicationRealm. The value is true or false (default).

HOTROD_ENCRYPTION

Configures the hotrod-connectors with encryption in the ApplicationRealm. The value is true or false (default).

If you enable this environment variable, you must also set environment variables to encrypt client to server communication. See Securing Network Traffic.

ENCRYPTION_REQUIRE_SSL_CLIENT_AUTH

Specifies if client certificate authentication is required. The value is true or false (default).

REST_SECURITY_DOMAIN

Specifies the security domain to use for authentication and authorization purposes. The default value is none (no authentication).

REST_STORE_AS_STRING

Specifies if JBoss Data Grid saves entries as Java strings when written to the cache via the REST API. The value is true or false (default).

Set the value to true if you are upgrading the image from a previous version and plan to read persisted cache entries.

Note

JBoss Data Grid version 7.1 and earlier: When you write entries to the cache through the REST endpoint, JBoss Data Grid stores them as Java strings.

JBoss Data Grid version 7.2 and later: JBoss Data Grid stores cache entries as bytes[] to enable data interoperability between clients and protocols.

If you upgrade JBoss Data Grid for OpenShift images from an previous version to version 7.2, JBoss Data Grid returns null values when you attempt to read cache entries that are persisted to a data store. To resolve the null values, set REST_STORE_AS_STRING=true.

12.4.1. Exposed Ports

JBoss Data Grid for OpenShift exposes endpoints on the following ports by default:

Port Number	Protocol	Use
8080	TCP	HTTP Access
8443	TCP	HTTPS Access
8778	TCP	Remote JMX Access
11211	TCP	Memcached Access
11222	TCP	Internal Hotrod Access
11333	TCP	External Hotrod Access

Note

From the same OpenShift namespace, the Hot Rod endpoint is accessible at ${pod_IP_address}:11222.

If you set the HOTROD_SERVICE_NAME environment variable, the Hot Rod external connector returns ${service_name}:11333 for the endpoint.

12.5. Datasource Configuration

You can configure datasources with the following environment variables:

DB_SERVICE_PREFIX_MAPPING

Defines a comma-separated list of datasources to configure.

For example, DB_SERVICE_PREFIX_MAPPING=test-mysql=TEST_MYSQL. See Configuring Persistent Datasources for more information.

<NAME>_<DATABASE_TYPE>_SERVICE_HOST

Defines the database server hostname or IP for the datasource connection_url property.

For example, <NAME>_<DATABASE_TYPE>_SERVICE_HOST=192.0.2.0

<NAME>_<DATABASE_TYPE>_SERVICE_PORT

Defines the database server port.

<PREFIX>_USERNAME

Defines the user for the datasource.

<PREFIX>_PASSWORD

Defines the password for the datasource.

<PREFIX>_DATABASE

Defines the database name for the datasource.

For example, <PREFIX>_DATABASE=myDatabase.

<PREFIX>_DRIVER

Defines Java database driver for the datasource.

For example, <PREFIX>_DRIVER=postgresql

<PREFIX>_BACKGROUND_VALIDATION

Specifies if a background thread validates database connections before they are used. The value is true or false (default). By default, the <validate-on-match> method is enabled.

<PREFIX>_BACKGROUND_VALIDATION_MILLIS

Specifies how often validation occurs, in milliseconds, if you set the <PREFIX>_BACKGROUND_VALIDATION environment variable to true. The default value is 10000.

<PREFIX>_CONNECTION_CHECKER

Specifies a connection checker class that validates connections to the database.

For example, <PREFIX>_CONNECTION_CHECKER=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker

<PREFIX>_EXCEPTION_SORTER

Specifies the exception sorter class that detects and cleans up after fatal database connection exceptions.

For example, <PREFIX>_EXCEPTION_SORTER=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter

<PREFIX>_JNDI

Defines the JNDI name for the datasource.

Defaults to java:jboss/datasources/<name>_<database_type>. The launch script automatically generates the value from the DB_SERVICE_PREFIX_MAPPING environment variable.

For example, <PREFIX>_JNDI=java:jboss/datasources/test-postgresql

<PREFIX>_JTA

Defines the Java Transaction API (JTA) option for non-XA datasources. The value is true (default) or false.

<PREFIX>_MAX_POOL_SIZE

Defines the maximum pool size for the datasource.

<PREFIX>_MIN_POOL_SIZE

Defines the minimum pool size for the datasource.

<PREFIX>_NONXA

Defines the datasource as a non-XA datasource. The value is true or false (default).

<PREFIX>_TX_ISOLATION

Defines the java.sql.Connection transaction isolation level for the database.

For example, <PREFIX>_TX_ISOLATION=TRANSACTION_READ_UNCOMMITTED

<PREFIX>_URL

Defines the connection URL for a non-XA datasource.

If you do not specify a connection URL, the launch script automatically generates it from other environment variables as follows: url="jdbc:${DRIVER}://${HOST}:${PORT}/${DATABASE}".

However, the launch script constructs the correct connection URLs only for internal datasources such as PostgreSQL and MySQL. If you use any other non-XA datasource you must specify the connection URL.

For example, <PREFIX>_URL=jdbc:postgresql://localhost:5432/postgresdb

<PREFIX>_XA_CONNECTION_PROPERTY_<PROPERTY_NAME>

Defines connection properties for an XA datasource.

Consult the appropriate driver documentation for your datasource to find which XA properties you can set on the connection.

For example, <PREFIX>_XA_CONNECTION_PROPERTY_DatabaseName=/opt/eap/standalone/data/databases/db/accounts

This example adds the following to the configuration:

<xa-datasource-property name="DatabaseName">/opt/eap/standalone/data/databases/db/accounts</xa-datasource-property>

12.6. Security Domain Configuration

Use the following environment variables to customize the security domain for the container:

SECDOMAIN_NAME

Defines additional security domains.

For example: SECDOMAIN_NAME=myDomain

SECDOMAIN_PASSWORD_STACKING

Enables the password staking module and sets the useFirstPass option. The value is true or false (default).

SECDOMAIN_LOGIN_MODULE

Specifies a login module to use. The default value is UsersRoles

SECDOMAIN_USERS_PROPERTIES

Specifies the properties file that contains user definitions. The default value is users.properties.

SECDOMAIN_ROLES_PROPERTIES

Specifies the properties file that contains role definitions. The default value is roles.properties.

12.1. Image Information

12.2. Container Configuration

12.3. Cache Configuration

12.3.1. Cache Container Security Configuration

12.3.2. Cache Specific Configuration

12.4. Endpoint Configuration

12.4.1. Exposed Ports

12.5. Datasource Configuration

12.6. Security Domain Configuration

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links