Chapter 1. Getting Started with Data Grid CLI

1.1. Creating Data Grid users
Copy link

Add credentials to authenticate with Data Grid Server deployments through Hot Rod and REST endpoints. Before you can access the Data Grid Console or perform cache operations you must create at least one user with the Data Grid command line interface (CLI).

Tip

Data Grid enforces security authorization with role-based access control (RBAC). Create an admin user the first time you add credentials to gain full ADMIN permissions to your Data Grid deployment.

Prerequisites

Download and install Data Grid Server.

Procedure

Open a terminal in $RHDG_HOME.
Create an admin user with the user create command.
```
bin/cli.sh user create admin -p changeme
```
```
bin/cli.sh user create admin -p changeme
```
Copy to Clipboard Toggle word wrap
Tip
Run help user from a CLI session to get complete command details.

Verification

Open user.properties and confirm the user exists.

cat server/conf/users.properties

admin=scram-sha-1\:BYGcIAwvf6b...

cat server/conf/users.properties

admin=scram-sha-1\:BYGcIAwvf6b...

Copy to Clipboard

Toggle word wrap

Note

Adding credentials to a properties realm with the CLI creates the user only on the server instance to which you are connected. You must manually synchronize credentials in a properties realm to each node in the cluster.

1.1.1. Granting roles to users
Copy link

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

Tip

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 Data Grid.
Create Data Grid users.

Procedure

Create a CLI connection to Data Grid.
Assign roles to users with the user roles grant command, for example:
```
user roles grant --roles=deployer katie
```
```
user roles grant --roles=deployer katie
```
Copy to Clipboard Toggle word wrap

Verification

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

user roles ls katie
["deployer"]

user roles ls katie
["deployer"]

Copy to Clipboard

Toggle word wrap

1.1.2. Adding users to groups
Copy link

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.

Note

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

Prerequisites

Have ADMIN permissions for Data Grid.
Create Data Grid users.

Procedure

Create a CLI connection to Data Grid.
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.
  user create --groups=developers developers -p changeme
  Copy to Clipboard Toggle word wrap
List groups.
```
user ls --groups
```
```
user ls --groups
```
Copy to Clipboard Toggle word wrap

Grant a role to the group.

user roles grant --roles=application developers

user roles grant --roles=application developers

Copy to Clipboard

Toggle word wrap

List roles for the group.
```
user roles ls developers
```
```
user roles ls developers
```
Copy to Clipboard Toggle word wrap
Add users to the group one at a time.
```
user groups john --groups=developers
```
```
user groups john --groups=developers
```
Copy to Clipboard Toggle word wrap

Verification

Open groups.properties and confirm the group exists.

cat server/conf/groups.properties

cat server/conf/groups.properties

Copy to Clipboard

Toggle word wrap

1.1.3. Data Grid user roles and permissions
Copy link

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

Expand

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

1.2. Connecting to Data Grid Servers
Copy link

Establish CLI connections to Data Grid.

Prerequisites

Add user credentials and have at least one running Data Grid server instance.

Procedure

Open a terminal in $RHDG_HOME.
Start the CLI.
- Linux:
  bin/cli.sh
  Copy to Clipboard Toggle word wrap
- Microsoft Windows:
  bin\cli.bat
  Copy to Clipboard Toggle word wrap
Run the connect command and enter your username and password when prompted.
- Data Grid Server on the default port of 11222:
  [disconnected]> connect
  Copy to Clipboard Toggle word wrap
- Data Grid Server with a port offset of 100:
  [disconnected]> connect 127.0.0.1:11322
  Copy to Clipboard Toggle word wrap

1.3. Navigating CLI Resources
Copy link

The Data Grid CLI exposes a navigable tree that allows you to list, describe, and manipulate Data Grid cluster resources.

Tip

Press the tab key to display available commands and options. Use the -h option to display help text.

When you connect to a Data Grid cluster, it opens in the context of the default cache container.

[//containers/default]>

[//containers/default]>

Copy to Clipboard

Toggle word wrap

Use ls to list resources.

[//containers/default]> ls
caches
counters
configurations
schemas
tasks

[//containers/default]> ls
caches
counters
configurations
schemas
tasks

Copy to Clipboard

Toggle word wrap

Use cd to navigate the resource tree.
```
cd caches
```
```
cd caches
```
Copy to Clipboard Toggle word wrap

Use describe to view information about resources.

describe

describe

Copy to Clipboard

Toggle word wrap

{
  "name" : "default",
  "version" : "xx.x.x-FINAL",
  "cluster_name" : "cluster",
  "coordinator" : true,
  "cache_configuration_names" : [ "org.infinispan.REPL_ASYNC", "___protobuf_metadata", "org.infinispan.DIST_SYNC", "org.infinispan.LOCAL", "org.infinispan.INVALIDATION_SYNC", "org.infinispan.REPL_SYNC", "org.infinispan.SCATTERED_SYNC", "org.infinispan.INVALIDATION_ASYNC", "org.infinispan.DIST_ASYNC" ],
  "physical_addresses" : "[192.0.2.0:7800]",
  "coordinator_address" : "<hostname>",
  "cache_manager_status" : "RUNNING",
  "created_cache_count" : "1",
  "running_cache_count" : "1",
  "node_address" : "<hostname>",
  "cluster_members" : [ "<hostname1>", "<hostname2>" ],
  "cluster_members_physical_addresses" : [ "192.0.2.0:7800", "192.0.2.0:7801" ],
  "cluster_size" : 2,
  "defined_caches" : [ {
    "name" : "mycache",
    "started" : true
  }, {
    "name" : "___protobuf_metadata",
    "started" : true
  } ]
}

{
  "name" : "default",
  "version" : "xx.x.x-FINAL",
  "cluster_name" : "cluster",
  "coordinator" : true,
  "cache_configuration_names" : [ "org.infinispan.REPL_ASYNC", "___protobuf_metadata", "org.infinispan.DIST_SYNC", "org.infinispan.LOCAL", "org.infinispan.INVALIDATION_SYNC", "org.infinispan.REPL_SYNC", "org.infinispan.SCATTERED_SYNC", "org.infinispan.INVALIDATION_ASYNC", "org.infinispan.DIST_ASYNC" ],
  "physical_addresses" : "[192.0.2.0:7800]",
  "coordinator_address" : "<hostname>",
  "cache_manager_status" : "RUNNING",
  "created_cache_count" : "1",
  "running_cache_count" : "1",
  "node_address" : "<hostname>",
  "cluster_members" : [ "<hostname1>", "<hostname2>" ],
  "cluster_members_physical_addresses" : [ "192.0.2.0:7800", "192.0.2.0:7801" ],
  "cluster_size" : 2,
  "defined_caches" : [ {
    "name" : "mycache",
    "started" : true
  }, {
    "name" : "___protobuf_metadata",
    "started" : true
  } ]
}

Copy to Clipboard

Toggle word wrap

1.3.1. CLI Resources
Copy link

The Data Grid CLI exposes different resources to:

create, modify, and manage local or clustered caches.
perform administrative operations for Data Grid clusters.

Cache Resources

[//containers/default]> ls
caches
counters
configurations
schemas
tasks

[//containers/default]> ls
caches
counters
configurations
schemas
tasks

Copy to Clipboard

Toggle word wrap

caches: Data Grid cache instances. The default cache container is empty. Use the CLI to create caches from templates or infinispan.xml files.
counters: Strong or Weak counters that record the count of objects.
configurations: Data Grid configurations.
schemas: Protocol Buffers (Protobuf) schemas that structure data in the cache.
tasks: Remote tasks creating and managing Data Grid cache definitions.

Cluster Resources

[hostname@cluster/]> ls
containers
cluster
server

[hostname@cluster/]> ls
containers
cluster
server

Copy to Clipboard

Toggle word wrap

containers: Cache containers on the Data Grid cluster.
cluster: Lists Data Grid Servers joined to the cluster.
server: Resources for managing and monitoring Data Grid Servers.

1.4. Shutting down Data Grid Server
Copy link

Stop individually running servers or bring down clusters gracefully.

Procedure

Create a CLI connection to Data Grid.
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

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.4.1. Shutdown and restart of Data Grid clusters
Copy link

Prevent data loss and ensure consistency of your cluster by properly shutting down and restarting nodes.

Cluster shutdown

Data Grid recommends using the shutdown cluster command to stop all nodes in a cluster while saving cluster state and persisting all data in the cache. You can use the shutdown cluster command also for clusters with a single node.

When you bring Data Grid clusters back online, all nodes and caches in the cluster will be unavailable until all nodes rejoin. To prevent inconsistencies or data loss, Data Grid restricts access to the data stored in the cluster and modifications of the cluster state until the cluster is fully operational again. Additionally, Data Grid disables cluster rebalancing and prevents local cache stores purging on startup.

During the cluster recovery process, the coordinator node logs messages for each new node joining, indicating which nodes are available and which are still missing. Other nodes in the Data Grid cluster have the view from the time they join. You can monitor availability of caches using the Data Grid Console or REST API.

However, in cases where waiting for all nodes is not necessary nor desired, it is possible to set a cache available with the current topology. This approach is possible through the CLI, see below, or the REST API.

Important

Manually installing a topology can lead to data loss, only perform this operation if the initial topology cannot be recreated.

Server shutdown

After using the shutdown server command to bring nodes down, the first node to come back online will be available immediately without waiting for other members. The remaining nodes join the cluster immediately, triggering state transfer but loading the local persistence first, which might lead to stale entries. Local cache stores configured to purge on startup will be emptied when the server starts. Local cache stores marked as purge=false will be available after a server restarts but might contain stale entries.

If you shutdown clustered nodes with the shutdown server command, you must restart each server in reverse order to avoid potential issues related to data loss and stale entries in the cache.
For example, if you shutdown server1 and then shutdown server2, you should first start server2 and then start server1. However, restarting clustered nodes in reverse order does not completely prevent data loss and stale entries.

1.1. Creating Data Grid users
Copy link

1.1.1. Granting roles to users
Copy link

1.1.2. Adding users to groups
Copy link

1.1.3. Data Grid user roles and permissions
Copy link

1.2. Connecting to Data Grid Servers
Copy link

1.3. Navigating CLI Resources
Copy link

1.3.1. CLI Resources
Copy link

1.4. Shutting down Data Grid Server
Copy link

1.4.1. Shutdown and restart of Data Grid clusters
Copy link

Cluster shutdown

Server shutdown

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Chapter 1. Getting Started with Data Grid CLI

1.1. Creating Data Grid usersCopy linkLink copied to clipboard!

1.1.1. Granting roles to usersCopy linkLink copied to clipboard!

1.1.2. Adding users to groupsCopy linkLink copied to clipboard!

1.1.3. Data Grid user roles and permissionsCopy linkLink copied to clipboard!

1.2. Connecting to Data Grid ServersCopy linkLink copied to clipboard!

1.3. Navigating CLI ResourcesCopy linkLink copied to clipboard!

1.3.1. CLI ResourcesCopy linkLink copied to clipboard!

1.4. Shutting down Data Grid ServerCopy linkLink copied to clipboard!

1.4.1. Shutdown and restart of Data Grid clustersCopy linkLink copied to clipboard!

Cluster shutdown

Server shutdown

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

1.1. Creating Data Grid users
Copy link

1.1.1. Granting roles to users
Copy link

1.1.2. Adding users to groups
Copy link

1.1.3. Data Grid user roles and permissions
Copy link

1.2. Connecting to Data Grid Servers
Copy link

1.3. Navigating CLI Resources
Copy link

1.3.1. CLI Resources
Copy link

1.4. Shutting down Data Grid Server
Copy link

1.4.1. Shutdown and restart of Data Grid clusters
Copy link