Chapter 1. Getting Started with Data Grid Server

Quickly set up Data Grid Server and learn the basics.

1.1. Data Grid Server Requirements

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

1.2. Downloading Server Distributions

The Data Grid server distribution is an archive of Java libraries (JAR files), configuration files, and a data directory.

Procedure

  1. Access the Red Hat customer portal.
  2. Download Red Hat Data Grid 8.1 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
  4. Compare with the MD5 or SHA-256 checksum value on the Data Grid Software Details page.

Reference

1.3. Installing Data Grid Server

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.1.1-server.zip

The resulting directory is your $RHDG_HOME.

1.4. Creating and Modifying Users

Data Grid Server requires users to authenticate against a default property realm. Before you can access Data Grid Server, you must add credentials by creating at least one user and a password. You can also add and modify the security authorization groups to which users belong.

Procedure

  1. Open a terminal in $RHDG_HOME.
  2. Create and modify Data Grid users with the user command.
Tip

Run help user for more details about using the command.

Creating users and passwords

  • Linux 

    $ bin/cli.sh user create myuser -p "qwer1234!"

  • Microsoft Windows 

    $ bin\cli.bat user create myuser -p "qwer1234!"

Creating users with group membership

  • Linux 

    $ bin/cli.sh user create myuser -p "qwer1234!" -g supervisor,reader,writer

  • Microsoft Windows 

    $ bin\cli.bat user create myuser -p "qwer1234!" -g supervisor,reader,writer

1.5. Starting Data Grid Server

Run Data Grid Server on your local host.

Prerequisites

  • Create at least one Data Grid user.

Procedure

  1. Open a terminal in $RHDG_HOME.

  2. Run Data Grid Server with the server script.

    Linux
    $ bin/server.sh
    Microsoft Windows
    bin\server.bat

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

Verification

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

1.6. Verifying Cluster Views

Data Grid nodes 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

  3. Specify a port offset and the server2 directory. 

    $ bin/server.sh -o 100 -s server2

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

Reference

Setting Up Data Grid Clusters

1.7. Shutting Down Data Grid Server

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: 

      [//containers/default]> shutdown cluster

      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: 

      [//containers/default]> shutdown server <my_server01>
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

1.7.1. Restarting Data Grid Clusters

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.8. Data Grid Server Filesystem

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

├── bin
├── boot
├── docs
├── lib
├── server
└── static
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.8.1. Server Root Directory

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

Each server root directory should contain the following folders: 

├── server
│   ├── conf
│   ├── data
│   ├── lib
│   └── log

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.

Reference