Red Hat Summit Red Hat SummitApoyoConsolaDesarrolladoresIniciar una pruebaContacto

Este contenido no está disponible en el idioma seleccionado.

Chapter 1. Getting started with Data Grid Server

Quickly set up Data Grid Server and learn the basics.

Ansible collection

Automate installation of Data Grid clusters with our Ansible collection that optionally includes Keycloak caches and cross-site replication configuration. The Ansible collection also lets you inject Data Grid caches into the static configuration for each server instance during installation.

The Ansible collection for Data Grid is available from the Red Hat Automation Hub.

1.1. Data Grid Server requirements
Copiar enlace

Data Grid Server requires a Java Virtual Machine. See the Data Grid Supported Configurations for details on supported versions.

1.2. Downloading Data Grid Server distributions
Copiar enlace

The Data Grid Server distribution is an archive of Java libraries (JAR files) and configuration files.

Procedure

  1. Access the Red Hat customer portal.
  2. Download Red Hat Data Grid 8.3 Server from the software downloads section.

  3. Run the md5sum or sha256sum command with the server download archive as the argument, for example: 

    sha256sum jboss-datagrid-${version}-server.zip
    Copy to Clipboard Toggle word wrap
  4. Compare with the MD5 or SHA-256 checksum value on the Data Grid Software Details page.

Reference

1.3. Installing Data Grid Server
Copiar enlace

Install the Data Grid Server distribution on a host system.

Prerequisites

  • Download a Data Grid Server distribution archive.

Procedure

  • Use any appropriate tool to extract the Data Grid Server archive to the host filesystem. 
unzip redhat-datagrid-8.3.1-server.zip
Copy to Clipboard Toggle word wrap

The resulting directory is your $RHDG_HOME.

1.4. Starting Data Grid Server
Copiar enlace

Run Data Grid Server instances in a Java Virtual Machine (JVM) on any supported host.

Prerequisites

  • Download and install the server distribution.

Procedure

  1. Open a terminal in $RHDG_HOME.

  2. Start Data Grid Server instances with the server script.

    Linux
    bin/server.sh
    Copy to Clipboard Toggle word wrap
    Microsoft Windows
    bin\server.bat
    Copy to Clipboard Toggle word wrap

Data Grid Server is running successfully when it logs the following messages: 

ISPN080004: Protocol SINGLE_PORT listening on 127.0.0.1:11222
ISPN080034: Server '...' listening on http://127.0.0.1:11222
ISPN080001: Data Grid Server <version> started in <mm>ms
Copy to Clipboard Toggle word wrap

Verification

  1. Open 127.0.0.1:11222/console/ in any browser.
  2. Enter your credentials at the prompt and continue to Data Grid Console.

1.5. Passing Data Grid Server configuration at startup
Copiar enlace

Specify custom configuration when you start Data Grid Server.

Data Grid Server can parse multiple configuration files that you overlay on startup with the --server-config argument. You can use as many configuration overlay files as required, in any order. Configuration overlay files:

  • Must be valid Data Grid configuration and contain the root server element or field.
  • Do not need to be full configuration as long as your combination of overlay files results in a full configuration.
Important

Data Grid Server does not detect conflicting configuration between overlay files. Each overlay file overwrites any conflicting configuration in the preceding configuration.

Note

If you pass cache configuration to Data Grid Server on startup it does not dynamically create those cache across the cluster. You must manually propagate caches to each node.

Additionally, cache configuration that you pass to Data Grid Server on startup must include the infinispan and cache-container elements.

Prerequisites

  • Download and install the server distribution.
  • Add custom server configuration to the server/conf directory of your Data Grid Server installation.

Procedure

  1. Open a terminal in $RHDG_HOME.

  2. Specify one or more configuration files with the --server-config= or -c argument, for example: 

    bin/server.sh -c infinispan.xml -c datasources.yaml -c security-realms.json
    Copy to Clipboard Toggle word wrap

1.6. Creating and modifying Data Grid users
Copiar enlace

Add Data Grid user credentials and assign permissions to control access to data.

Data Grid server installations use a property realm to authenticate users for the Hot Rod and REST endpoints. This means you need to create at least one user before you can access Data Grid.

By default, users also need roles with permissions to access caches and interact with Data Grid resources. You can assign roles to users individually or add users to groups that have role permissions.

You create users and assign roles with the user command in the Data Grid command line interface (CLI).

Tip

Run help user from a CLI session to get complete command details.

1.6.1. Adding credentials
Copiar enlace

You need an admin user for the Data Grid Console and full control over your Data Grid environment. For this reason you should create a user with admin permissions the first time you add credentials.

Procedure

  1. Open a terminal in $RHDG_HOME.

  2. Create an admin user with the user create command.

    • Add a user assigned to the admin group. 

      bin/cli.sh user create myuser -p changeme -g admin
      Copy to Clipboard Toggle word wrap

    • Use implicit authorization to gain admin permissions. 

      bin/cli.sh user create admin -p changeme
      Copy to Clipboard Toggle word wrap

  3. Open user.properties and groups.properties with any text editor to verify users and groups. 

    $ cat server/conf/users.properties

#$REALM_NAME=default$
#$ALGORITHM=encrypted$
myuser=scram-sha-1\:BYGcIAwvf6b...

$ cat server/conf/groups.properties

myuser=admin
    Copy to Clipboard Toggle word wrap

1.6.2. Assigning roles to users
Copiar enlace

Assign roles to users so they have the correct permissions to access data and modify Data Grid resources.

Procedure

  1. Start a CLI session with an admin user. 

    $ bin/cli.sh
    Copy to Clipboard Toggle word wrap

  2. Assign the deployer role to "katie". 

    [//containers/default]> user roles grant --roles=deployer katie
    Copy to Clipboard Toggle word wrap

  3. List roles for "katie". 

    [//containers/default]> user roles ls katie
["deployer"]
    Copy to Clipboard Toggle word wrap

1.6.3. Adding users to groups
Copiar enlace

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.

Procedure

  1. Start a CLI session with an admin user.

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

    1. Specify "developers" as the group name with the --groups argument.

    2. Set a username and password for the group.

      In a property realm, a group is a special type of user that also requires a username and password. 

      [//containers/default]> user create --groups=developers developers -p changeme
      Copy to Clipboard Toggle word wrap

  3. List groups. 

    [//containers/default]> user ls --groups
["developers"]
    Copy to Clipboard Toggle word wrap

  4. Assign the application role to the "developers" group. 

    [//containers/default]> user roles grant --roles=application developers
    Copy to Clipboard Toggle word wrap

  5. List roles for the "developers" group. 

    [//containers/default]> user roles ls developers
["application"]
    Copy to Clipboard Toggle word wrap

  6. Add existing users, one at a time, to the group as required. 

    [//containers/default]> user groups john --groups=developers
    Copy to Clipboard Toggle word wrap

1.6.4. User roles and permissions
Copiar enlace

Data Grid includes a default set of roles that grant users with permissions to access data and interact with Data Grid resources.

ClusterRoleMapper is the default mechanism that Data Grid uses to associate security principals to authorization roles.

Important

ClusterRoleMapper matches principal names to role names. A user named admin gets admin permissions automatically, a user named deployer gets deployer permissions, and so on.

Expand
RolePermissionsDescription

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 Data Grid resources in addition to application permissions.

application

ALL_READ, ALL_WRITE, LISTEN, EXEC, MONITOR

Has read and write access to Data Grid 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 Data Grid resources in addition to monitor permissions.

monitor

MONITOR

Can view statistics via JMX and the metrics endpoint.

Reference

1.7. Verifying cluster views
Copiar enlace

Data Grid Server instances on the same network automatically discover each other and form clusters.

Complete this procedure to observe cluster discovery with the MPING protocol in the default TCP stack with locally running Data Grid Server instances. If you want to adjust cluster transport for custom network requirements, see the documentation for setting up Data Grid clusters.

Note

This procedure is intended to demonstrate the principle of cluster discovery and is not intended for production environments. Doing things like specifying a port offset on the command line is not a reliable way to configure cluster transport for production.

Prerequisites

Have one instance of Data Grid Server running.

Procedure

  1. Open a terminal in $RHDG_HOME.

  2. Copy the root directory to server2. 

    cp -r server server2
    Copy to Clipboard Toggle word wrap

  3. Specify a port offset and the server2 directory. 

    bin/server.sh -o 100 -s server2
    Copy to Clipboard Toggle word wrap

Verification

You can view cluster membership in the console at 127.0.0.1:11222/console/cluster-membership.

Data Grid also logs the following messages when nodes join clusters: 

INFO  [org.infinispan.CLUSTER] (jgroups-11,<server_hostname>)
ISPN000094: Received new cluster view for channel cluster:
[<server_hostname>|3] (2) [<server_hostname>, <server2_hostname>]

INFO  [org.infinispan.CLUSTER] (jgroups-11,<server_hostname>)
ISPN100000: Node <server2_hostname> joined the cluster
Copy to Clipboard Toggle word wrap

1.8. Shutting down Data Grid Server
Copiar enlace

Stop individually running servers or bring down clusters gracefully.

Procedure

  1. Create a CLI connection to Data Grid.

  2. Shut down Data Grid Server in one of the following ways:

    • Stop all nodes in a cluster with the shutdown cluster command, for example: 

      shutdown cluster
      Copy to Clipboard Toggle word wrap

      This command saves cluster state to the data folder for each node in the cluster. If you use a cache store, the shutdown cluster command also persists all data in the cache.

    • Stop individual server instances with the shutdown server command and the server hostname, for example: 

      shutdown server <my_server01>
      Copy to Clipboard Toggle word wrap
Important

The shutdown server command does not wait for rebalancing operations to complete, which can lead to data loss if you specify multiple hostnames at the same time.

Tip

Run help shutdown for more details about using the command.

Verification

Data Grid logs the following messages when you shut down servers: 

ISPN080002: Data Grid Server stopping
ISPN000080: Disconnecting JGroups channel cluster
ISPN000390: Persisted state, version=<$version> timestamp=YYYY-MM-DDTHH:MM:SS
ISPN080003: Data Grid Server stopped
Copy to Clipboard Toggle word wrap

1.8.1. Data Grid cluster restarts
Copiar enlace

When you bring Data Grid clusters back online after shutting them down, you should wait for the cluster to be available before adding or removing nodes or modifying cluster state.

If you shutdown clustered nodes with the shutdown server command, you must restart each server in reverse order.
For example, if you shutdown server1 and then shutdown server2, you should first start server2 and then start server1.

If you shutdown a cluster with the shutdown cluster command, clusters become fully operational only after all nodes rejoin.
You can restart nodes in any order but the cluster remains in DEGRADED state until all nodes that were joined before shutdown are running.

1.9. Data Grid Server installation directory structure
Copiar enlace

Data Grid Server uses the following folders on the host filesystem under $RHDG_HOME: 

├── bin
├── boot
├── docs
├── lib
├── server
└── static
Copy to Clipboard Toggle word wrap
Tip

See the Data Grid Server README for descriptions of the each folder in your $RHDG_HOME directory as well as system properties you can use to customize the filesystem.

1.9.1. Server root directory
Copiar enlace

Apart from resources in the bin and docs folders, the only folder under $RHDG_HOME that you should interact with is the server root directory, which is named server by default.

You can create multiple nodes under the same $RHDG_HOME directory or in different directories, but each Data Grid Server instance must have its own server root directory. For example, a cluster of 5 nodes could have the following server root directories on the filesystem: 

├── server
├── server1
├── server2
├── server3
└── server4
Copy to Clipboard Toggle word wrap

Each server root directory should contain the following folders: 

├── server
│   ├── conf
│   ├── data
│   ├── lib
│   └── log
Copy to Clipboard Toggle word wrap

server/conf

Holds infinispan.xml configuration files for a Data Grid Server instance.

Data Grid separates configuration into two layers:

Dynamic
Create mutable cache configurations for data scalability.
Data Grid Server permanently saves the caches you create at runtime along with the cluster state that is distributed across nodes. Each joining node receives a complete cluster state that Data Grid Server synchronizes across all nodes whenever changes occur.
Static
Add configuration to infinispan.xml for underlying server mechanisms such as cluster transport, security, and shared datasources.

server/data

Provides internal storage that Data Grid Server uses to maintain cluster state.

Important

Never directly delete or modify content in server/data.

Modifying files such as caches.xml while the server is running can cause corruption. Deleting content can result in an incorrect state, which means clusters cannot restart after shutdown.

server/lib

Contains extension JAR files for custom filters, custom event listeners, JDBC drivers, custom ServerTask implementations, and so on.

server/log

Holds Data Grid Server log files.

Volver arriba
Red Hat logoGithubredditYoutubeTwitter

Aprender

Pruebe, compre y venda

Comunidades

Acerca de la documentación de Red Hat

Ayudamos a los usuarios de Red Hat a innovar y alcanzar sus objetivos con nuestros productos y servicios con contenido en el que pueden confiar. Explore nuestras recientes actualizaciones.

Hacer que el código abierto sea más inclusivo

Red Hat se compromete a reemplazar el lenguaje problemático en nuestro código, documentación y propiedades web. Para más detalles, consulte el Blog de Red Hat.

Acerca de Red Hat

Ofrecemos soluciones reforzadas que facilitan a las empresas trabajar en plataformas y entornos, desde el centro de datos central hasta el perímetro de la red.

Theme

© 2025 Red Hat