TIBCO ActiveSpaces

(1)

Administration

Software Release 3.3 October 2017

Document Updated: November 2017

Two-Second Advantage^®

(2)

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE

SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

THE SOFTWARE ITEMS IDENTIFIED BELOW ARE AVAILABLE UNDER SEPARATE SOFTWARE LICENSE TERMS AND ARE NOT PART OF A TIBCO PRODUCT. AS SUCH, THEY ARE NOT COVERED BY THE TERMS OF YOUR AGREEMENT WITH TIBCO, INCLUDING ANY TERMS CONCERNING SUPPORT, MAINTENANCE, WARRANTIES, AND INDEMNITIES. DOWNLOAD AND USE THESE ITEMS IS SOLELY AT YOUR OWN DISCRETION AND SUBJECT TO THE LICENSE TERMS APPLICABLE TO THEM. BY PROCEEDING TO DOWNLOAD, INSTALL OR USE ANY OF THESE ITEMS, YOU ACKNOWLEDGE THE FOREGOING DISTINCTIONS BETWEEN THESE ITEMS AND TIBCO PRODUCTS.

This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written

authorization of TIBCO Software Inc.

TIBCO, Two-Second Advantage, ActiveSpaces, and FTL are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

TIBCO FTL^® is an embedded and bundled component of TIBCO ActiveSpaces^® Enterprises Edition.

Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,

(3)

TIBCO Software Inc. Confidential Information

(4)

About this Product

TIBCO ActiveSpaces^® software is a distributed in-memory data grid product. ActiveSpaces^® features familiar database concepts, high I/O capacity, and network scalability.

ActiveSpaces software features a complete redesign and reimplementation of the product and is straightforward to understand, use, and administer.

Product Editions

ActiveSpaces is now available in a community edition and an enterprise edition.

ActiveSpaces - Community Edition is ideal for getting started with ActiveSpaces, for implementing application projects, including proof of concept projects, for testing, and for deploying applications in a production environment. Although the community license limits the number of production instances, you can easily upgrade to the enterprise edition as your use of ActiveSpaces expands.

The community edition is available free of charge. It is a full installation of the ActiveSpaces product, with the following limitations and exclusions:

● Users may run up to 25 nodes (a total of the copyset nodes or proxies in your data grid)

ActiveSpaces - Community Edition is compatible with both the enterprise and community editions of TIBCO FTL^®.

ActiveSpaces - Enterprise Edition is ideal for all application development projects, and for deploying and managing applications in an enterprise production environment. It includes all features presented in this documentation set, and access to TIBCO Support. Choose the enterprise edition for production deployments with more than 25 nodes (a total of the copyset nodes or proxies in your data grid) and for enterprise monitoring using dashboards.

ActiveSpaces - Enterprise Edition depends on the enterprise edition of TIBCO FTL.

(7)

TIBCO Documentation and Support Services

How to Access TIBCO Documentation

Documentation for TIBCO products is available on the TIBCO Product Documentation website, mainly in HTML and PDF formats.

The TIBCO Product Documentation website is updated frequently and is more current than any other documentation included with the product. To access the latest documentation, visit https://

docs.tibco.com.

Product-Specific Documentation

The following documents for this product can be found on the TIBCO Documentation site:

● TIBCO ActiveSpaces^® Concepts

● TIBCO ActiveSpaces^® Administration

● TIBCO ActiveSpaces^® Release Notes

● TIBCO ActiveSpaces^® Installation

● TIBCO ActiveSpaces^® API Reference

How to Contact TIBCO Support

You can contact TIBCO Support in the following ways:

● For an overview of TIBCO Support, visit http://www.tibco.com/services/support.

● For accessing the Support Knowledge Base and getting personalized content about products you are interested in, visit the TIBCO Support portal at https://support.tibco.com.

● For creating a Support case, you must have a valid maintenance or support contract with TIBCO.

You also need a user name and password to log in to https://support.tibco.com. If you do not have a user name, you can request one by clicking Register on the website.

How to Join TIBCO Community

TIBCO Community is the official channel for TIBCO customers, partners, and employee subject matter experts to share and access their collective experience. TIBCO Community offers access to Q&A forums, product wikis, and best practices. It also offers access to extensions, adapters, solution accelerators, and tools that extend and enable customers to gain full value from TIBCO products. In addition, users can submit and vote on feature requests from within the TIBCO Ideas Portal. For a free registration, go to https://community.tibco.com.

(8)

Administrative Concepts

These concepts and definitions pave the way to a more detailed understanding of ActiveSpaces administration.

Data Grid

A set of cooperating processes that distribute data across a set of host computers.

Three kinds of cooperating processes implement a data grid: nodes, proxies, and state keepers.

Copyset

A data grid partitions the complete set of data into copysets. Each copyset contains a portion of the full data set.

Each table row resides within only one copyset.

For more information, see Copysets.

Partitioning

The data grid horizontally partitions the rows of a table across copysets. So a query or a transaction could span many copysets.

Node

Nodes are processes that implement a copyset. Administrators define nodes and assign them to copysets.

Each copyset requires a primary node. Secondary nodes can provide optional backup protection.

Each node of a copyset maintains one copy of the data (that is, one copy of all the rows in that copyset).

Each node is part of only one copyset.

Replica

The number of replicas in a copyset is identical to the number of nodes that implement that copyset.

Replicas provide fault tolerance and protect data against hardware failures. More replicas yield greater protection.

● In a prototyping or testing environment, you can implement a copyset using only one node.

● In most production environments, two nodes provide adequate protection.

● For even stronger fault tolerance, you can use three nodes.

Replication

The replication feature, when used, provides fault tolerance by preventing data loss when a node (or the machine running the node) fails and cannot be accessed.

All nodes in a given copyset are replicas of each other and they all have the exact same set of data.

There is a single primary replica in a copyset and the other nodes in that copyset are secondary replicas.

Every copyset in the data grid is organized to make sure the slice of data owned by that copyset is stored on as many replicas as desired.

Proxy

Proxies are processes that mediate data grid operations on behalf of application programs.

Application programs connect to proxies, which in turn connect to nodes.

(9)

Proxy processes are independent of one another and do not require persistent state, so you can share the load of operations among multiple proxies.

State Keeper

Fault-tolerant state keeper processes determine and record the crucial internal governing information by which a data grid operates, and supply this information to the proxies and copyset nodes.

For more information, see State Keeper.

Using Multiple Nodes

There are several use cases for using multiple nodes:

● Nodes are created with the goal of scaling horizontally.

As a result multiple copysets are created each, with a slice of the data.

● Nodes are created as replicas in the same copyset.

These contain identical copies of the data.

● In a product environment a combination of the previously described use cases may be used.

For example, you may choose to have two replicas per copyset and multiple copysets (say three) to scale horizontally.

In this example, your environment would have a total of six nodes.

Copysets

A data grid partitions the complete set of data into copysets. Each copyset contains a portion of the full data set.

The data grid horizontally partitions each table, assigning each row to one specific copyset. This partitioning is transparent to application programs.

Programs explicitly interact with tables, but do not refer to copysets.

Tables and Copysets

Tables and copysets are independent concepts.

Tables organize data in a way that makes sense to users of the data. Tables consist of rows, structured by columns.

Copysets store table rows, distributing them across a network in a way that facilitates fast access, fault tolerance, data replication, and flexibility.

State Keeper

The state keeper determines and records the crucial internal governing information by which a data grid operates, and supplies this information to the proxies and copyset nodes.

Governing Information in the State Keeper Primary Nodes

Within each copyset, one node is the primary copy, which both stores data and provides read access.

Other nodes are secondaries that store backup copies of the data. The state keeper records which node is the primary.

Data Distribution Mapping

The state keeper determines the mapping that assigns each table row to a copyset.

(10)

State Keeper Fault Tolerance

A set of fault-tolerant state keeper processes protect this crucial information and ensure nonstop access to it. One state keeper process supplies this information to the proxies and copyset nodes.

In production environments use three processes. In a prototyping or testing environment, only one process suffices.

For added protection, each state keeper process also maintains a copy of the governing decisions in a disk file.

(11)

Development Environment

In many enterprises programmers act as administrators during the development and test phases of a project. To develop and test application programs that use ActiveSpaces software, deploy the following processes.

● Realm server One process

● State keeper One process

● Node One process

● Proxy One process

● Your application programs One or more processes, as appropriate

In a development environment you can run all of these processes on the same host computer.

Sample Scripts

Refer to the TIBCO_HOME/as/<version>/samples/readme.txt before using the sample scripts.

The following scripts are available:

● TIBCO_HOME/as/<version>/samples/scripts/as-start defines a simple data grid and starts its component processes.

● TIBCO_HOME/as/<version>/samples/scripts/as-stop stops those component processes.

Copyset Partitioning Test

To test the partitioning of data rows into copysets, you can define a data grid with more than one copyset, each with its own node process running on a separate host computer.

For more information see 'Defining a Data Grid' in the TIBCO ActiveSpaces^® Administration guide.

(12)

Production Environment

To use ActiveSpaces software in a production environment, deploy the following processes.

● Realm server The minimum arrangement consists of one primary realm server.

Optional. You may run a backup realm server. The primary realm server and its backup must run on two separate host computers.

● State keeper You must run the state keeper processes on separate host computers. The minimum production arrangement consists of three state keeper processes.

At any given time you must maintain a quorum of running state keepers. If you want to run more than one state keeper, configure three state keepers and make sure you have at least two running state keepers.

● Node The minimum production arrangement consists of two node processes per copyset.

Optional. For greater data protection you may run three nodes per copyset.

Additional copies can become expensive in two ways:

● Increasing the node count by one adds one complete copy of all the data.

● Every node process must run on a separate host computer. Usually this requirement determines the number of host computers you must maintain. For example, a data grid with three copysets and two nodes per copyset requires six nodes, all on separate hosts. Increasing to three nodes per copyset would require nine nodes, all on separate hosts.

● Proxy The minimum production arrangement consists of one proxy process.

Optional. You may run additional proxies to increase the capacity for client programs and to improve response time. For best results, run proxy processes on a separate host computers.

● Your application programs Run processes as appropriate.

Components Sharing a Host Computer

You can reduce number of host computers in a production environment by running more than one component per host.

For example, you can run a realm server, a state keeper, a node, and a proxy, all on one host. (In contrast, do not run two state keepers on the same host.)

For effective fault tolerance, run the nodes of each copyset on separate host computers.

Combining component processes on a host computer increases the risk that a single point of failure on the host could disrupt all those processes simultaneously. Assess the risk tolerance of your enterprise.

(13)

Security

ActiveSpaces security provides the following features:

● Authentication and Authorization

● Transport Encryption ActiveSpaces lets you:

● Prevent unauthorized access to your data grid .

● Secure data during transmission within the data grid .

ActiveSpaces allows you to authenticate the users of the data grid. This feature uses username and password authentication. Each ActiveSpaces process authenticates itself to the secure realm server using credentials contained in a password file. Additionally, the ActiveSpaces processes use a trust file to trust a secure realm server. See Enabling Authentication for more information.

Network communication between processes in a data grid can be encrypted to further protect your data from packet sniffing by unauthorized processes. See Enabling Encryption for more information.

Enabling Authentication

Follow these steps to enable authentication and authorization in ActiveSpaces.

Prerequisites

● Set up the realm server.

See "Secure Realm Server" in TIBCO FTL Administration for more information.

● Set up realm server authentication.

See "Realm Server Authentication" in TIBCO FTL Administration for more information.

Procedure

1. For the tibdg administration tool to connect to a secure realm server with authentication credentials:

a) The username using the ^-user option.

b) The password file using the ^-password option.

Use one of the following options:

● pass:<password>

-password pass:mypassword

● file:<password file>

-password file:mypasswordfile

● env:<environment variable>

-password env:%myPassword%

● stdin

You are prompted for the password when the command executes.

c) The location of the trusted realm server using the ^-trustfile option:

-trustfile %TRUST_FILE%

For details, see Trust File.

(14)

Example

tibdg -r %REALM_URL% -s my_script_file.tibdg -user all -password pass:mypasswords -trustfile %TRUST_FILE%

2. For the ^tibdgnode, tibdgkeeper, and ^tibdgproxy processes to connect to a secure realm server with authentication credentials:

a) Specify the password file that these processes will use to connect to the grid.

The password file is specified using the --user-password-file option.

For details, see Password File.

b) Specify the location of the trusted realm server using one of the following options:

● --trust-file: The contents of the specified trust file instructs clients to trust the realm server's certificate.

For details, see Trust File.

● --trust-all: The client trusts any realm server without verifying trust in the server's certificate.

This option should only be used for development and testing.

Example

tibdgproxy -r %REALM_URL% --user-password-file c:\AS\tests\myPasswordfile.txt -- trust-all

Enabling Encryption

Prerequisites

Set up authentication. See Enabling Authentication.

Procedure

● To encrypt your data grid connections create the grid using the encrypted_connections option.

Valid values are ^none and ^all. For example,

grid create encrypted_connections=all

Password File

If the realm server enables authentication and authorization, then you must configure credentials for ActiveSpaces processes such as ^tibdgnode, tibdgkeeper, and ^tibdgproxy .

Each service process authenticates itself to the realm server using credentials that it reads from an ASCII password file. Specify the name and location of that file using the client’s --password-file

command line parameter.

The password file consists of two lines. The first line contains the user name. The second line contains the password string.

Trust File

A secure realm server automatically generates a trust file. The content of the trust file instructs clients to trust the realm server's certificate. Administrators and developers coordinate to supply the trust file to application programs.

A secure realm server generates the trust file in its data directory. The trust file is named ^ftl-

. The file contains one or more PEM-encoded public certificates, each of which is typically 1 -

(15)

Realm administrators give the trust file to the clients: that is, developers and application administrators coordinate so that client programs can access the trust file at run time.

Administrators also supply the trust file directly to ActiveSpaces processes such as ^tibdgnode,

tibdgkeeper, and ^tibdgproxy.

Users can load the trust file into a web browser’s trust store.

Affiliated Realm Servers and the Trust File

An affiliated realm server uses the same trust file as its primary realm server. That is, although a backup or satellite server generates its own keystore file, nonetheless the trust file it generates is an exact copy of the primary server's trust file. As a consequence, you do not need to distribute separate trust files to clients of a family of affiliated servers: one trust file suffices for the whole family.

Regeneration and Redistribution of the Trust File

If a realm server cannot access its TLS data files, or it cannot decrypt the keystore file, then it generates new TLS data files. The newly generated data files replace any existing data files.

If a primary realm server generates new TLS data files, you must redistribute the new trust file to all clients, including affiliated realm servers, other TIBCO FTL components, application programs, and browsers that access the realm server GUI.

Two scenarios can trigger this requirement:

● No Access: A primary realm server restarts and cannot access its TLS data files: for example, they have been deleted or moved, or their file access permissions have changed.

● New Password: An administrator restarts the primary realm server, supplying a different password.

The server cannot decrypt the existing keystore file using the new password.

If a secondary realm server generates new TLS data files, you need not redistribute its trust file.

(16)

Starting a Realm Server

Each ActiveSpaces data grid depends on a TIBCO FTL realm server to supply configuration data to its components. To start a realm server process, complete this task.

Dedicate a separate family of realm servers for each data grid. If your application programs also use FTL communications, arrange a separate family of realm servers for them.

At minimum, a family of affiliated realm servers must include a primary realm server process. It may also include a backup realm server, as appropriate for your enterprise. (For more information, see

"Affiliated Realm Servers" in TIBCO FTL Administration.)

Prerequisites

TIBCO FTL software must already be installed on realm server hosts.

Procedure

1. Navigate to the realm configuration data directory.

cd my_data_dir_1

The realm server uses the current directory as the default location to store its working data files.

● The first time you start a realm server for a data grid, navigate to an empty directory. When the realm server detects an empty working directory, it begins with a default realm definition. As you configure the realm definition, in subsequent tasks, the realm server stores that definition in its data directory.

● If you have already begun to configure the realm definition, then navigate to the same data directory. The realm server reads the realm definition from the working directory.

2. Run the realm server executable.

tibrealmserver -ht my_host:my_port

Specify the HTTP port using the ^-ht parameter. The port must not be bound by any other process.

ActiveSpaces^® component processes initiate contact with the realm server at this address.

Application programs must supply this realm server URL (host:port) to data grid connect call.

(17)

Administration Tool

tibdg is an administrative command line tool for ActiveSpaces. You can use it to define data grid components, tables, and indexes; to see the status of data grid components; and to save and restore the definitions of a data grid.

Usage Help

To see a summary of commands, run the administration tool with no arguments:

tibdg

To see information about a specific command or command area, run the administration tool with that command as an argument. For example:

tibdg copyset tibdg table tibdg status

Realm Server Interactions

Administration tool commands interact with the realm server:

● Storing definitions in the realm server

● Retrieving definitions from the realm server

● Retrieving status information from the realm server

Every interaction command requires the location of the realm server, either as an argument or as the value of an environment variable.

Modes of Operation

You can use the administration tool in two ways:

● Immediate command execution When you execute a ^tibdg command line, the tool makes the change in the realm server workspace, and immediately deploys that change to the realm server's clients (namely, data grid component processes).

This mode is convenient for changes to a running data grid (such as adding a new table), for saving the data grid definition to a file, and for requesting status information about a running data grid.

● Command script Alternatively, you can create a command script file containing several commands.

Then ^tibdg executes that batch of commands, accumulating those changes in the realm server workspace. Finally, the tool deploys all the workspace changes to the realm server's clients before exiting.

This mode is convenient for for a series of related changes, such as defining a data grid, or creating a table and its columns.

Consider the following two examples, which accomplish the same goal: defining a data grid. The first example executes five separate command lines, deploying each change immediately.

tibdg grid create

tibdg copyset create my_copyset tibdg node create my_node tibdg keeper create my_keeper tibdg proxy create my_proxy

In contrast, the second example consists of five commands in a script file, my_script_file.tibdg:

grid create

copyset create my_copyset node create my_node keeper create my_keeper proxy create my_proxy

(18)

Then it executes the script with one command line, deploying all the changes at the end.

tibdg -s my_script_file.tibdg

For more information about the realm server and its workspace, see TIBCO FTL Administration.

Administration Tool Reference

Administrators use ^tibdg to configure and monitor a data grid.

Syntax

tibdg [-r realm_server_URL] [-c path] [-s path] [Command Command_Args] [ConfigurationOption=value]

Command Line Parameters

See also Environment Variables for the Administration Tool.

Parameter Description

-r realm_server_URL

-rs realm_server_URL

--realmserver realm_server_URL

Optional.

URL of the realm server.

tibdg contacts the realm server at this location.

When absent, the default value is the value of the environment variable ^TIBDG_FTL if defined, otherwise localhost:8080.

In a configuration file, specify this parameter with the JSON key "ftl_url".

-c path

--config path

Optional.

When present, ^tibdg reads its command line parameters from the file at path.

-s path

--script path

Optional.

When present, ^tibdg reads commands from the script file at path.

-h --help

Optional.

Output help text about ^tibdg or about a specfic command.

See also Configuration Options for the Administration Tool.

Environment Variables for the Administration Tool

The following environment variables can be used with the ^tibdg command line administrative tool.

Values on the command line override the values of these environment variables.

Environment Variable Description

TIBDG_FTL The administration tool contacts the realm server at this URL (host and port).

(19)

Environment Variable Description

TIBDG_PARAM_FILE The administration tool reads parameters from this file path.

Values in this file override the tool's default values.

Individual values on the command line override values in this file.

If this variable is not set, the tool reads

parameters from the file it finds in either of these two default locations:

● ./.tibdg

● ~/.tibdg

For syntax of the configuration file, see the output of the command tibdg config.

TIBDG_FTL_USER The user name and password used to connect to the secure realm server.

TIBDG_FTL_PASSWD

TIBDG_FTL_TRUSTFILE The value of this property is the location of the trust file.

Configuration Options for the Administration Tool

The following configuration options can be used with the tibdg command line administrative tool.

Option Description

Default

Value Valid Values client_req_timeout The time (in seconds) the client API will

synchronously wait for completion of a request (such as GET or PUT operation), before timing out.

5.0 Minimum:

0.0

consistent_query_limi

t The maximum number of iterators and

statements (queries) that a node can handle concurrently.

64 Minimum: 0

copyset_size The number of nodes in a copyset. 2 Minimum: 1

iter_inactivity_timeou

t The time (in seconds) the proxy will wait for the next client request on a table iterator or statement query before automatically closing the table iterator or statement query.

600.0 Minimum:

0.0

(20)

Option Description

Default

Value Valid Values statekeeper_count The number of state keeper processes

expected to be run.

Due to the requirement that state keepers must be run in a quorum, the supported values are 1 or 3.

3 Minimum: 1

compaction A value less than six indicates more emphasis on performance and less on the compaction of the disk space.

Conversely, a higher value indicates more emphasis on the compaction of the disk space than performance.

7 Minimum: 0

Maximum:

10

minimum_replication

_factor The minimum number of nodes (including the primary and any secondary nodes) in a copyset that must be in an ^Alive state before ^WRITE operations are allowed.

1 Minimum: 1

encrypted_connection

s Specifies which connections in the data

grid get encrypted. ^none ^all or ^none

node_storage_timeou

t The time (in seconds) a node will wait for a successful response from a READ or WRITE operation to complete before timing it out.

60 Minimum: 0

tibdg Status

Run the administrative tool with the ^status command to view the status of the data grid components.

The following information is displayed when you execute the tibdg status command:

The PROCESSES section displays the status of the ^tibdgnode, tibdgkeeper, and ^tibdgproxy processes.

The REINDEXING section displays information for any table that is currently being reindexed or is pending a reindex. If there is no reindexing in progress or pending, this section is not displayed.

(21)

Designing a Data Grid

This task guides you through the design decisions that characterize the structure of a data grid.

Fundamental Decisions

The decisions you make in the following steps define the fundamental characteristics of the data grid.

After completing this task, you cannot change these parameters except by deleting the data grid definition and starting over again.

As you make these design decisions, record them for later reference.

Procedure

1. Determine the number of copysets in the data grid.

The amount of data that the grid can contain depends on the capacity of the host computers and the number of copysets.

A single copyset could suffice for prototyping and development.

2. Determine the number of nodes per copyset.

● For development, use one node per copyset.

● For fault tolerance, use two nodes per copyset.

● For stronger fault tolerance protection, use three nodes per copyset.

Each copyset consists of the same number of nodes.

3. Determine the number of state keeper processes.

● For development, use one state keeper process.

● For fault tolerance, use three state keeper processes.

4. Determine the number of proxy processes.

5. Determine unique process names.

Assign a unique name to each component process of the data grid. You can use these unique names to address the individual processes as you monitor and manage them.

a) Compose a name for each copyset.

For example, ^DG.CS-A, ^DG.CS-B, ^DG.CS-C.

b) Compose a name for each node, incorporating the copyset name.

For example, ^DG.CS-A.N1, ^DG.CS-A.N2. c) Compose a name for each state keeper process.

For example, ^DG.SK-1, ^DG.SK-2, ^DG.SK-3. d) Compose a name for each proxy process.

For example, DG.PX-1, DG.PX-2, DG.PX-3. What to do next

Defining a Data Grid

(22)

Defining a Data Grid

To define and configure a data grid, complete the steps in this task.

This task implements decisions about the structure of your data grid, creating a data grid definition within a TIBCO FTL realm server. The realm server delivers the information to the component processes of the data grid and your application processes that use the grid.

The examples in these steps illustrate adding commands to a configuration script. When the script is complete, the administration tool executes the script to define the data grid.

Alternatively, you could execute each step immediately as a separate administration tool command, instead of accumulating them in a script.

You have already completed the task Designing a Data Grid. This task refers to decisions you recorded during that task.

Prerequisites

A realm server must be running and reachable.

Procedure

1. In a text editor, begin editing a script file.

Follow the convention of naming your script with the ^.tibdg file name extension.

2. Add a script command to create the data grid. For example:

grid create

Define the Component Processes of the Data Grid

3. For each copyset, add a script command to create that copyset. For example:

copyset create copyset_name

4. For each node, add a script command to create that node. For example:

node create --copyset copyset_name node_name

5. For each state keeper, add a script command to create that state keeper. For example:

keeper create keeper_name

6. For each proxy, add a script command to create that proxy. For example:

proxy create proxy_name

7. Optional. Run the script to create the data grid.

Alternatively, you may postpone this step until you have defined the tables of the data base (see the task Defining a Table).

tibdg -s script_file_path -r http://<host>:<port>>

where <host> and <port> refer to the realm server URL.

(23)

Defining a Table

Administrators define tables as needed to structure data. To define a table within the data grid, complete this task.

The examples in these steps illustrate adding commands to a configuration script. When the script is complete, the administration tool executes the script to define the table.

Alternatively, you could execute each step immediately as a separate administration tool command, instead of accumulating them in a script.

Prerequisites

A realm server must be running and reachable.

Either the realm must contain a valid data grid definition, or your configuration script file must contain commands to create a valid data grid definition.

Procedure

1. In a text editor, either begin editing a script file, or continue adding commands to an existing script.

Follow the convention of naming your script with the .tibdg file name extension.

2. Add a script command to create the table. For example:

table create table_name key_column_name key_column_type

table create table_name key_col_1 col_1_type key_col_2 col_2_type

Every table requires a primary key, which can consist of one or more columns. The first example creates a key with one column. The second example creates a key with two columns.

The data type of key columns must be either long or string.

3. Define additional columns.

For each column in the table, add a script command to create the column. For example:

column create table_name column_name column_type

Only the following FTL datatypes are valid as column types:

● Long

● Double

● String

● DateTime

● Opaque

4. Optional. Define secondary indexes.

For each index in the table, add a script command to create the index. For example:

index create table_name index_name column_name

index create table_name index_name column_1 column_2 column_3

The data type of index columns must be either long or string.

5. Run the script to create the tables in the data grid.

tibdg -s script_file_path

(24)

What to do next

If an index is added or deleted from a table, re-indexing will occur in the background. To verify that reindexing has been completed look for log entries such as these in the ^tibdgnode log file:

2017-02-23 09:54:35.309 info ridx: reindexing of table t3 started 2017-02-23 09:54:35.640 info ridx: table t3 has been reindexed

You may repeat this task to define additional tables.

Column Names

Choose column names that follow these rules for SQL identifiers.

● Begin with a letter character.

ActiveSpaces reserves column names that begin with an underscore character for internal use.

● Subsequent characters can be letters, digits, or underscore characters.

● Do not use SQL keywords as column names.

● Column names are not case sensitive.

Invalid column names can cause errors when starting ^tibdgnode.

Secondary Indexes

A secondary index can increase query efficiency by reducing the number of rows to examine.

A secondary index can span one or more columns, and can include columns that are part of the primary key.

You may use the same column in more than one index.

Limit the number of secondary indexes, because each index increases the size of the information stored in the grid, and increases the overhead for each write operation.

As an administrator, create indexes that improve performance of frequent query patterns. Delete indexes that no longer serve that purpose. For information about query performance, see "Efficiency of Filters" in TIBCO ActiveSpaces Concepts.

(25)

Starting the Data Grid Processes

To start the data grid, start its component processes in this order.

Component Command Line Parameters

All three executable components -- state keeper, node, and proxy -- accept the same set of command line parameters, as documented here.

Parameter Description

-n name

--name name

Required. Process name.

Supply one of the names you assigned in Defining a Data Grid.

-r realm_server_URL

-rs realm_server_URL

--realmserver realm_server_URL

Required. Realm server location.

Supply the realm server URL in the form

http://host:port. Use the values of host and port that you supplied as the ^-ht argument in Starting a Realm Server.

-s realm_server_URL

--secondary-realmserver realm_server_URL

Optional.

URL of the backup realm server.

If the regular realm server is unavailable, the process contacts the backup realm server at this location.

(26)

Starting a State Keeper

Start state keeper processes first, because all other ActiveSpaces component processes depend on them.

Prerequisites

● The data grid definition in the realm server must be complete and valid.

Procedure

1. Start the state keeper process.

tibdgkeeper -n name -r realm_server_URL

2. Repeat the previous step for all the state keeper names assigned in the data grid definition.

3. Verify that the state keeper processes are ready.

Check the status using the administration tool.

Keeper Reference

Administrators use tibdgkeeper to start a keeper process.

Syntax

tibdgkeeper -n name -r realm_server_URL [-s realm_server_URL]

For further explanation, see Component Command Line Parameters.

(27)

Starting a Node

Start the node processes that implement the copysets.

Prerequisites

● The state keeper must be running and reachable.

Procedure

1. Start the node process.

tibdgnode -n name -r realm_server_URL

2. Verify that the node process is synchronized and ready.

If number of nodes per copyset is greater than one, and the node you have started is not the primary node, then wait for the node to synchronize with the primary.

To verify synchronization, check the status using the administration tool.

For the fastest and most efficient start sequence, it is important to start only one node process at a time, and wait for it to synchronize before starting the next node process.

3. Repeat the previous steps for all the node names assigned in the data grid definition.

4. Verify communication.

If the number of nodes per copyset is greater than one, verify that the node processes within each copyset can communicate with one another.

One of the nodes will report in its console output that it is active.

Node Reference

Administrators use ^tibdgnode to start a node.

Syntax

tibdgnode -n name -r realm_server_URL [-s realm_server_URL]

Starting Multiple Nodes

There are several use cases for using multiple nodes:

● Additional nodes are created with the goal of scaling horizontally.

For example, if you have three copysets, start the components in the following sequence:

tibrealmserver

tibdg -r http://localhost:8080 -s /<path>/three_copysets.tibdg tibdgkeeper -r http://localhost:8080 -n k1

tibdgproxy -r http://localhost:8080 -n p1 tibdgnode -r http://localhost:8080 -n s1 tibdgnode -r http://localhost:8080 -n s2 tibdgnode -r http://localhost:8080 -n s3

Here <path> refers to the location where three_copysets.tibdg is stored. For a sample script, see three_copysets.tibdg.

● Nodes are created as replicas of the copysets.

(28)

For example, if you have one copyset and two replicas, start the components in the following sequence:

tibrealmserver

tibdg -r http://localhost:8080 -s /<path>/one_copyset_two_replicas.tibdg tibdgkeeper -r http://localhost:8080 -n k1

tibdgproxy -r http://localhost:8080 -n p1 tibdgnode -r http://localhost:8080 -n s1 tibdgnode -r http://localhost:8080 -n s2

Here <path> refers to the location where one_copyset_two_replicas.tibdg is stored. For a sample script, see one_copyset_two_replicas.tibdg.

The sample scripts three_copysets.tibdg and one_copyset_two_replicas.tibdg create nodes and state keepers using the --dir option, for example:

node create --copyset set1 --dir ./s1_data s1 statekeeper create --dir ./k1_data k1

The nodes store the data that applications put in the data grid in the ^s1_data folder and the state keeper stores state information about the primary and secondary nodes in the ^k1_data folder.

three_copysets.tibdg

# Data grid where each copyset has 1 replica grid create copyset_size=1

table create t1 key long

column create t1 col2 string col3 opaque copyset create set1

copyset create set2 copyset create set3

node create --copyset set1 --dir ./s1_data s1 node create --copyset set2 --dir ./s2_data s2 node create --copyset set3 --dir ./s3_data s3 statekeeper create --dir ./k1_data k1

proxy create p1

# Show results status

table list copyset list

one_copyset_two_replicas.tibdg

# Data grid where each copyset has 2 replicas grid create copyset_size=2

table create t1 key long

column create t1 col2 string col3 opaque copyset create set1

node create --copyset set1 --dir ./s1_data s1 node create --copyset set1 --dir ./s2_data s2 statekeeper create --dir ./k1_data k1

proxy create p1

# Show results status

table list

(29)

Starting a Proxy

Start the proxy processes that mediate between application processes and the data grid.

Prerequisites

● The state keeper must be running and reachable.

● At least one node of each copyset must be running and reachable.

Procedure

1. Start the proxy process.

tibdgproxy -n name -r realm_server_URL

Required. Proxy process name. Supply one of the proxy names you assigned in Defining a Data Grid.

2. Verify that the proxy process is ready.

Check the status using the administration tool.

3. Repeat the previous steps for all the proxy names assigned in the data grid definition.

What to do next

The data grid is ready to support data operations. You may start application program processes.

Proxy Reference

Administrators use ^tibdgproxy to start a proxy.

Syntax

tibdgproxy -n name -r realm_server_URL [-s realm_server_URL]

(30)

Adding Copysets

To horizontally scale an existing data grid you can create additional copysets and create nodes to assign to these copysets.

Data grids created using earlier versions of ActiveSpaces have to be upgraded by following the procedures detailed in 'Upgrading an Earlier Installation' in TIBCO ActiveSpaces^® Installation Guide.

Use the copyset create command in the ^tibdg tool to create the copysets and nodes. Once created, though the nodes can be started they will not yet receive any data. Use the grid redistribute

command in the ^tibdg tool to start the data redistribution process.

The tibdg grid redistribute command can be invoked at any time to assign data to newly added copysets. If the nodes involved in the redistribution are not running, they will begin redistributing data once they are started.

For example, to grow a data grid from three copysets to four copysets, the following commands should be used:

tibdg -r host:port copyset create cset4

tibdg -r host:port node create --copyset cset4 --dir ./s4_data s4 tibdgnode -r host:port -n s4

tibdg -r host:port grid redistribute

Before starting any nodes in the new copyset, all members of the copyset must be added via the ^tibdg

node create command. For example, if each copyset has two nodes (as defined by the copyset_size

parameter supplied to the tibdg grid create command), you must create two nodes in the new copyset before starting the ^tibdgnode processes.

View the status of the redistribution by running the ^status command in the ^tibdg tool.

tibdg -r host:port status

Data Redistribution

Data redistribution will be done in the background and will not block ongoing operations while data is being transferred.

When the sending copyset completes its migration of data, it will briefly delay live operations while assigning ownership to the new copyset. During this interval, transactions that were started during the migration process may fail, and iterator creation and query execution may fail. After this, there is a period of time where other processes (nodes and proxies) in the data grid begin to learn about the change in ownership of the data now at the new copyset so it is expected that operations occurring during that window could experience a timeout error at the client while the processes learn about the new configuration.

Statements and table listeners created prior to the data redistribution will be out of date once the data redistribution is completed and will receive an invalid resource error at the client. The object should be destroyed in the client application and recreated.

An existing copyset that sends data to a new copyset will retain its data on disk until the data redistribution process is complete. The rows previously owned by the copyset are deleted as a background operation.

For capacity planning purposes, it is possible that the portion of data being contributed by a copyset at the moment the redistribution is completed exists at both the old copyset and new copyset. In other words, in a one to two copyset redistribution scenario where the one existing copyset contains 100GB of data and is contributing 50GB to a new copyset, there would be a time where the total aggregate disk usage would be 150GB (this does not account for any additional disk usage by background activities like compaction).

(31)

ActiveSpaces Monitoring Service

ActiveSpaces Monitoring Service is a web-based tool to monitor your data grid and its component processes.

The monitoring information includes the user operations on the ActiveSpaces grid and the basic health of the grid. The user operations include put, get, and delete operations. Statistics such as the number of concurrent queries executed and the number of active listeners help you gauge the overall health of the grid.

ActiveSpaces Monitoring Service includes the following dashboards:

● ActiveSpaces Grid Activity

● ActiveSpaces Nodes Activity

● ActiveSpaces Proxies Activity

The following is an example of the ActiveSpaces Grid Activity dashboard when the grid is actively handling put activities, get activities, etc.

If you run the provided samples you get a simple data grid with one node, one state keeper, and one proxy.

The metrics tib_as_node_iterget_op_count and tib_as_node_queryget_op_count represent the number of batch get operations (dependent on the prefetch) and not the number of individual row get operations.

This applies to tib_as_proxy_iterget_op_count and tib_as_proxy_queryget_op_count as well.

(32)

Data Flow of Monitoring Metrics

The following diagram illustrates the flow of the monitoring data.

Starting ActiveSpaces Monitoring Service

Follow these commands to start ActiveSpaces Monitoring Service.

Prerequisites

Make sure the realm server is up and running.

Procedure

1. Open a command window.

2. Navigate to TIBCO_HOME/as/<version>/monitor/scripts

3. Execute the following script. The syntax is:

monitor-start [-r host:port] [--password-file password_file] [--trust-file trust_file] [--trust-all]

where

● host:port is the URL of the realm server.

● --password_file is the file is used for authentication and authorization. See Password File for more information.

● --trust-file is the file used for encryption. See Trust File for more information.

For example,

monitor-start -r QAMac1:8100 --password-file myPasswords --trust-file %TRUST_FILE

%

The --password_file and --trust_file options are required only if authentication has been previously setup. See Security for more information.

4. Open a browser and in the address field enter the URL for the ActiveSpaces Monitoring Service.

The default value is http://<hostname>:3000. Provide the login credentials.

The default login credentials are username ^admin and password ^admin.

(33)

Result

Monitoring data is displayed in the dashboards. The data files are created in <USER_HOME_DIR>/

asmonitor_data/

Update the ASMONITOR_DATA_DIR variable in the TIBCO_HOME/as/version/monitor/setup.bat file to write the data files to another folder.

If the dashboard does not display any data make sure the realm server is running. Check if any errors are logged in the <USER_HOME>/asmonitor_data/logs/tibpromgateway.log file.

If you inadvertently execute the monitor-start script before the realm server process starts, 1. Execute the monitor-stop script.

2. Start the realm server.

3. Execute the monitor-start script.

Stopping ActiveSpaces Monitoring Service

Follow these steps to stop ActiveSpaces Monitoring Service.

Procedure

1. Open a command window.

2. Navigate to TIBCO_HOME/as/version/monitor/scripts. 3. Execute the monitor-stop script.

Data and Log Files

ActiveSpaces Monitoring Service logs files are used for diagnostic purposes.

By default, the data files are created in USER_HOME/as/version/asmonitor_data and the log files are created in USER_HOME/as/version/asmonitor_data/logs/ .

Update the MONITOR_LOGS_DIR variable in the TIBCO_HOME/as/version/monitor/setup.bat file to write the log files to another folder.

Similarly update the ASMONITOR_DATA_DIR variable to write the log files to another folder.

(34)

Stopping a Data Grid Gracefully

To stop a data grid, stop all its component processes in this order.

Clearing a Grid Definition

To delete a data grid definition, complete this task.

Procedure

1. Stop the realm server.

2. Delete the realm server data files from the realm server data directory.

3. Delete the data directories of the nodes and state keepers.

These directories exist only if you have run the grid's component processes.

4. Restart the realm server.

5. Optional. Create the data grid definition anew.

TIBCO ActiveSpaces

Administration

Contents

About this Product

TIBCO Documentation and Support Services

Administrative Concepts

Copysets

State Keeper

Development Environment

Production Environment

Security

Enabling Authentication

Enabling Encryption

Password File

Trust File

Starting a Realm Server

Administration Tool

Administration Tool Reference

Environment Variables for the Administration Tool

Configuration Options for the Administration Tool

tibdg Status

Designing a Data Grid

Defining a Data Grid

Defining a Table

Column Names

Secondary Indexes

Starting the Data Grid Processes

Component Command Line Parameters

Starting a State Keeper

Keeper Reference

Starting a Node

Node Reference

Starting Multiple Nodes

three_copysets.tibdg

one_copyset_two_replicas.tibdg

Starting a Proxy

Proxy Reference

Adding Copysets

Data Redistribution

ActiveSpaces Monitoring Service

Data Flow of Monitoring Metrics

Starting ActiveSpaces Monitoring Service

Stopping ActiveSpaces Monitoring Service

Data and Log Files

Stopping a Data Grid Gracefully

Clearing a Grid Definition