GridDBTM Standard Edition Deployment Guide for AWS Marketplace

Revision: 1512

Table of Contents

1 Introduction

1.1 Aim and composition of this document

GridDB Standard 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 Standard Edition, please refer to our GridDB Developers page.

2 Deployment

This section shows how to deploy and connect GridDB instances.

2.1 Deploying on EC2

Please visit the GridDB Standard 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 Setting the environment-dependent parameters" of the GridDB 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
gridstoregsadm/var/lib/gridstore

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

[Note]

  • 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
bin  conf  docs  etc  lib  license  prop  Readme.txt  rpm  web  webapi

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 following documents for more information

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 users are created by default.

UserPassword
adminadmin
systemmanager

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

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

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

$ gs_passwd admin
Password:(Input password)
Retype password:(Input password again)
$ gs_passwd system
Password:(Input password)
Retype password:(Input password again)

When adding a new administrator user (not including the default users), 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)

[Note]

  • 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/              # 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 Setting the environment-dependent parameters" of the GridDB 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

[Note]

  • 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 Cluster configuration

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

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.

{
                             :
                             :
  "cluster":{
    "clusterName":"yourClusterName",
    "replicationNum":2,
    "heartbeatInterval":"5s",
    "loadbalanceCheckInterval":"180s",
    "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}
      }
    ]
  },
                             :
                             :
}

[Note]

  • 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. There are 2 types of client library in GridDB, Java and C.

4.1 Environmental check

Check that the OS version is RHEL 6.8/7.2, or CentOS 6.8/7.2.

$ cat /etc/redhat-release
CentOS Linux release 7.2.1511 (Core)

The following needs to be installed as a Java language development environment.

  • Oracle Java 6/7/8

The following needs to be installed as a C language development environment.

  • GCC 4.4.7 or higher

4.2 Installing client library

This chapter explains the installation procedure of the client library.

Before installing the client library, please copy the client library RPM package to the client instance first.

Package nameFile nameDescription
griddb-se-java_libgriddb-se-java_lib-X.X.X-linux.x86_64.rpmJava library is included.
(/usr/share/java/gridstore.jar)
griddb-se-c_libgriddb-se-c_lib-X.X.X-linux.x86_64.rpmC header file and library are included.
(/usr/include/gridstore.h and /usr/lib64/libgridstore.so)

Client library RPM packages are installed as follows.

/usr/griddb/rpm/
                griddb-se-c_lib-X.X.X-linux.x86_64.rpm
                griddb-se-java_lib-X.X.X-linux.x86_64.rpm

Install using the rpm command as a root user.

# rpm -ivh griddb-se-c_lib-X.X.X-linux.x86_64.rpm 
Preparing...                          ################################# [100%]
Updating / installing...
   1:griddb-se-c_lib-X.X.X-linux      ################################# [100%]

# rpm -ivh griddb-se-java_lib-X.X.X-linux.x86_64.rpm 
Preparing...                          ################################# [100%]
Updating / installing...
   1:griddb-se-java_lib-X.X.X-linux   ################################# [100%]

4.3 Setting up a library

When the Java version of the client is used, add the client library to CLASSPATH.

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

When the C version is used instead, add the client library to LD_LIBRARY_PATH.

$ export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/lib64

4.4 Writing a client program in Java

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

When using the client for GridDB instance, 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.

4.5 Running a sample program in Java

The installed GridDB sample program is shown below.

/usr/griddb/docs/sample/program:
Sample1.java

This sample program is written for using Client Properties File.

By including both directories which contain the properties file "gs_client.properties" and the configuration library "gridstore-conf.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 gs_client.properties for fixed list connection method

store.notificationMember=172.17.xx.xx:10001,172.17.yy.yy:10001,172.17.zz.zz:10001
store.clusterName=yourClusterName
store.user=admin
store.password=yourpassword

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

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

Compile the program and execute it with the following command.

$ javac -d . Sample1.java
$ java gsSample/Sample1

4.6 Writing a client program in C

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

When using the client for GridDB instance, please specify the "notificationMember" instead of "notificationAddress" and "notificationPort".

For details on the NoSQL specifications, please refer to "gsGetGridStore()" of the GridDB API Reference.

4.7 Running a sample program in C

The installed GridDB sample program is shown below.

/usr/griddb/docs/sample/program:
sample1.c

Compile the program and execute it with the following command.

$ gcc -lgridstore -o sample3 sample3.c
$ ./sample1 172.17.xx.xx:10001,172.17.yy.yy:10001,172.17.zz.zz:10001 yourClusterName

5 Operating functions setup

GridDB includes a variety of operating functions:

  • Integrated operation control GUI (gs_admin)
    • Web-based GUI integrating the operating functions of a GridDB cluster.
  • Cluster operation control command interpreter (gs_sh)
    • Command interpreter integrating the operating functions of a GridDB cluster.
  • Operating commands
    • Various operating commands of GridDB.
  • Export/import
    • Data export/import tools for recovering a GridDB database.

These functions are all available in the GridDB instance. For details, please refer to GridDB operation control guide.

If you want to use these functions on other instances, please copy the client and Java library RPM packages to those instances first and then install.

Package nameFile nameDescription
griddb-se-clientgriddb-se-client-X.X.X-linux.x86_64.rpmA variety of operating functions are included.
griddb-se-java_libgriddb-se-java_lib-X.X.X-linux.x86_64.rpmJava library is included.
(/usr/share/java/gridstore.jar)

These RPM packages are installed as follows.

/usr/griddb/rpm/
                griddb-se-client-X.X.X-linux.x86_64.rpm
                griddb-se-c_lib-X.X.X-linux.x86_64.rpm

Install using the rpm command as a root user.

# rpm -ivh griddb-se-client-X.X.X-linux.x86_64.rpm 
Preparing...                          ################################# [100%]

------------------------------------------------------------
Information:
  User gsadm and group gridstore have been registered.
  GridDB uses new user and group.
------------------------------------------------------------

Updating / installing...
   1:griddb-se-client-X.X.X-linux     ################################# [100%]

# rpm -ivh griddb-se-java_lib-X.X.X-linux.x86_64.rpm 
Preparing...                          ################################# [100%]
Updating / installing...
   1:griddb-se-java_lib-X.X.X-linux   ################################# [100%]

6 Operation

If you want to learn about the operation process of GridDB, please refer to "3. Operations" of the GridDB quick start guide.

7 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.
  • Red Hat is a registered trademark or trademark of Red Hat, Inc. in the US and other countries.
  • Amazon Web Services(AWS) is a trademark of Amazon.com, 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 SOLUTIONS CORPORATION