GridDB Deployment Guide for AWS Marketplace

Revision: 1515

Table of Contents

1 Introduction

1.1 Aim and composition of this document

GridDB Community Edition is available as AMI on the AWS Marketplace. This manual describes the basic deployment procedure of GridDB on AWS Marketplace.

For details on GridDB Community Edition, please refer to our GitHub page.

2 Deployment

This section shows how to deploy and connect GridDB instances.

2.1 Deploying on EC2

Please visit the GridDB Community Edition Marketplace and follow the onscreen instructions to create GridDB instance in your VPC. We recommend that you create 3 or more instances when configuring a GridDB cluster.

2.2 Security Group

GridDB node requires the following inbound ports to be open:

ProtocolPort rangeDescription
TCP22For operation over SSH.
TCP10001,10010,10020,10040GridDB default ports, to communicate with clients and other nodes.

For details on GridDB ports, please refer to "2.3 Configure environment-dependent parameters." of the Quick Start Guide.

2.3 Connecting to instance

You can connect to the EC2 instances via SSH as the centos default OS user once the instances have been deployed and the security group has been configured.

$ ssh -i your_keypair.pem centos@172.17.xx.xx

3 GridDB instance setup

This section shows how to set up a GridDB instance.

3.1 Default OS user

When you deploy the EC2 instance, the following group and user are created by default in the OS. This OS user is the default operator of GridDB.

GroupUserHome directory

The following environment variables are automatically defined when you login as gsadm.

Environment variablesValueMeaning
GS_HOME/var/lib/gridstoregsadm/GridDB home directory
GS_LOG/var/lib/gridstore/logEvent log file output directory


  • These environment variables are used in the operating commands described in the later section.
  • As gsadm password is not set by default, please login as the root user and set the password.
    • Some of the functions of the operation tools may be necessary.

To log in as gsadm from centos user, please use the following command.

$ sudo su - gsadm

3.2 Directory structure

The following directories and files, as well as the necessary modules and commands are created in the GridDB instance.

/var/lib/gridstore/        # GridDB home directory
     backup/               # Backup directory(unused)
     conf/                 # Directory storing definition files
         gs_cluster.json   # Cluster definition file
         gs_node.json      # Node definition file
         password          # User definition file
     data/                 # Directory storing database files
     log/                  # Directory storing event log files
$ ls /usr/griddb-X.X.X/*

/usr/griddb-X.X.X/3rd_party:            apr              json-simple      picojson  slf4j
activemq-cpp-library    BSD_License.txt  MessagePack      purewell  yield
Apache_License-2.0.txt  ebb              MIT_License.txt  sha2

gridstore-X.X.X.jar       gs_joincluster   gs_startnode
gridstore-conf-X.X.X.jar  gs_leavecluster  gs_stat
gs_adduser                gs_passwd        gs_stopcluster
gs_deluser                gsserver         gs_stopnode

gs_cluster.json  gs_node.json  password

manual  sample

When you access and run a GridDB node, the following files are created in the directories to store database files and event log files.

[Database file]

/var/lib/gridstore/        # GridDB home directory
     data/                 # Directory storing database files
         gs_log_n_m.log    # File recording transaction logs (n, m: positive number)
         gs_cp_n_p.dat     # Checkpoint file recording data regularly (n, p: positive number)

[Event log file]

/var/lib/gridstore/              # GridDB home directory
     log/                        # Directory storing event logs
         gridstore-%Y%m%d-n.log  # Event log file

You can change the directories used to store files by editing the relevant parameters in the node definition file.

Please refer to the document below for more information.

Other documents below are available on our GitHub page.

3.3 Administrator setup

An administrator user is needed for authentication purposes in nodes and clusters. Administrator user information is stored in the User definition file. The default file is shown below.

  • /var/lib/gridstore/conf/password

The following user is created by default.

adminNo settings

Administrator user information including the default admin user can be changed using the following user administration command in the operating commands.

gs_adduserAdd an administrator user
gs_deluserDelete an administrator user
gs_passwdChange the password of an administrator user

Change the default admin password using the gs_passwd command shown below. The password is encrypted during registration.


  • The default admin password is not set by default. Please make sure to change the password as the server will not start if the administrator user password is not set.
    $ gs_passwd admin
    Password:(Input password)
    Retype password:(Input password again)

When adding a new administrator user (not including the default user), the user name has to start with gs#. One or more ASCII alphanumeric characters and the underscore sign "_" can be used after gs#.

An example on adding a new administrator user is shown below.

$ gs_adduser gs#newuser
Password:(Input password)
Retype password:(Input password again)


  • Changes to the administrator user information take effect after the node is restarted.
  • User information is used for client authentication, so the common user information must be registered in all nodes. Please ensure that these information are available in all nodes by copying the user definition file.

3.4 AWS Cluster configuration setup

3.4.1 Editing definition files

There are two types of definition files in GridDB:

  • Cluster definition file
  • Node definition file

The cluster definition file is a file which defines the setting values commonly used in the entire cluster. The node definition file is a file which defines different setting values in each node.

Templates for these definition files are shown below. You can create definition files for GridDB by copying and editing these templates.

/usr/griddb-3.0.0/        # Installation directory
     conf/                # Directory storing definition files
         gs_cluster.json  # Template for cluster definition file
         gs_node.json     # Template for node definition file

Save an edited file with the predetermined name in the predetermined directory shown below.

/var/lib/gridstore/       # GridDB home directory
     conf/                # Directory storing definition files
         gs_cluster.json  # (Edited) Cluster definition file
         gs_node.json     # (Edited) Node definition file

For details on definition files, please refer to "2.3 Configure environment-dependent parameters." of the Quick Start Guide.

3.4.2 Setting the cluster name

Please set the cluster name in advance. The name set will be checked to see if it matches the value specified in the cluster composition command. This verification is used to prevent unintentional composition of the wrong node to a certain cluster in the case of an error in specifying the command.

The following settings in the Cluster definition file are specified in the cluster name.

Cluster definition file

ParameterData typeMeaning
/cluster/clusterNamestringName of cluster to create


  • The nodes will fail to start when the default value ("") is used.
  • We recommend that a unique name on the sub-network is used.
  • A cluster name is a string composed of 1 or more case-insensitive ASCII alphanumeric characters and the underscore "_", with a limitation of 64 characters. However, the first character cannot be a number.

3.4.3 Single node configuration

Please refer to "2.3 Configure environment-dependent parameters." of the Quick Start Guide.

3.4.4 Multiple node configuration

GridDB usually uses multicast to configure a multiple node cluster. However, Amazon VPC does not support multicast out of the instance (as of October 2016). Therefore, GridDB uses fixed list method instead to configure a multiple node cluster.

For details on the other cluster configuration methods, please refer to GridDB CE 3.0.0 RELEASE NOTES.

Cluster definition file

ParameterData typeMeaning
/cluster/notificationMemberstringThe address list when using the fixed list method as the cluster configuration method.

A configuration example of the cluster definition file is shown below. The cluster is composed of 3 nodes.

    "notificationMember": [
        "cluster": {"address":"172.17.xx.xx", "port":10010},
        "sync": {"address":"172.17.xx.xx", "port":10020},
        "system": {"address":"172.17.xx.xx", "port":10040},
        "transaction": {"address":"172.17.xx.xx", "port":10001}
        "cluster": {"address":"172.17.yy.yy", "port":10010},
        "sync": {"address":"172.17.yy.yy", "port":10020},
        "system": {"address":"172.17.yy.yy", "port":10040},
        "transaction": {"address":"172.17.yy.yy", "port":10001}
        "cluster": {"address":"172.17.zz.zz", "port":10010},
        "sync": {"address":"172.17.zz.zz", "port":10020},
        "system": {"address":"172.17.zz.zz", "port":10040},
        "transaction": {"address":"172.17.zz.zz", "port":10001}


  • Please specify the serviceAddress and servicePort of the node definition file in each module (cluster,sync etc.) for each address and port.
  • Please set either the /cluster/notificationAddress or /cluster/notificationMember in the cluster definition file to match the cluster configuration method used.

4 Client instance setup

This section shows how to set up client instance.

4.1 Installing client library

If you use a Java-based client, please copy the client libraries in the GridDB instance to client instance.

The installed GridDB client libraries are shown below.

gridstore-3.0.0.jar     gridstore-conf-3.0.0.jar

4.2 Setting up a library

Add the client library paths to CLASSPATH.

$ export CLASSPATH=${CLASSPATH}:/usr/share/java/gridstore-3.0.0.jar:/usr/share/java/gridstore-conf-3.0.0.jar

4.3 Writing a client program

To connect GridDB instance to the client program on client instance, please specify the connection point and user/password in the client program or Client Properties File.

When using the client for a single node cluster, please specify the "host" and "port" instead of "notificationAddress" and "notificationPort". On the other hand, when using the client for a multiple node cluster, please specify the "notificationMember" instead of "notificationAddress" and "notificationPort".

For details on the NoSQL specifications, please refer to "Class GridStoreFactory" of the GridDB API Reference and "Connection method of client" of the GridDB CE 3.0.0 RELEASE NOTES.

4.4 Running a sample program

The installed GridDB sample program is shown below.


This sample program is written for multicast connection method. In order to use a unicast or fixed list connection method, we recommend that you use Client Properties File and comment out connection settings in the program.

The following lines are needed to comment out of

props.setProperty("notificationAddress", args[0]);
props.setProperty("notificationPort", args[1]);
props.setProperty("clusterName", args[2]);
props.setProperty("user", args[3]);
props.setProperty("password", args[4]);

By including both directories which contain the properties file "" and the configuration library "gridstore-conf-3.0.0.jar" in the classpath, properties of the file are automatically applied to GridStoreFactory. Connection properties can be changed without editing application codes by using the properties file.

Example of for unicast connection method

Example of for fixed list connection method


Add the directory path including the client properties file to CLASSPATH.

$ ls /var/lib/gridstore/client
$ export CLASSPATH=${CLASSPATH}:/var/lib/gridstore/client

Compile the program and execute it with the following command.

$ javac -d .
$ java gsSample/Sample1

5 Operation

If you want to learn about the operation process of GridDB, please refer to "3. Operations" of the Quick Start Guide.

5.1 Updating GridDB instance on AWS

To update GridDB to the latest release, please download the latest RPM package from our GitHub page and perform a manual reinstallation by following this procedure.

  1. Stop the cluster.
  2. Stop each node.
  3. Uninstall the installed RPM package on each instance.
  4. Install the latest RPM package on each instance.

6 Trademarks

  • GridDB is a trademark of Toshiba Corporation.
  • Oracle and Java are registered trademarks of Oracle and/or its affiliates.
  • Linux is a trademark of Linus Torvalds.
  • Amazon Web Services(AWS) is a trademark of, Inc. and its affiliates in the United States and other countries.
  • Other product names are trademarks or registered trademarks of the respective owners.

Copyright (c) 2013-2016 TOSHIBA CORPORATION