TIBCO ActiveSpaces®

(1)

Administration

Software Release 2.3 June 2017

(2)

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.

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, The Power of Now, TIB, Information Bus, Rendezvous, TIBCO Rendezvous, and Messaging Appliance are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

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,

INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

TIBCO Software Inc. Confidential Information

(3)

Figures

Client-Server Deployment . . . .10

Deployment with Shared-All Persistence . . . .11

Deployment with Shared-Nothing Persistence . . . .12

Sample Deployment with Host-Aware Replication . . . .13

Remote Client Deployment . . . .14

Concurrency with Remote Clients . . . .15

Selecting an Interface and Network for Optimum Discovery . . . 16

Specifying Multiple TCP Discovery Nodes . . . 17

ASMM Admin Home Page . . . .96

Metaspace Connection Dialog . . . 98

Cross-site Replication Between Two Sites . . . 105

(8)

Documentation for this and other TIBCO products is available on the TIBCO Documentation site. This site is updated more frequently than any documentation that might be included with the product. To ensure that you are accessing the latest available help topics, visit:

https://docs.tibco.com

Product-Specific Documentation

Documentation for TIBCO products is not bundled with the software. Instead, it is available on the TIBCO Documentation site. To directly access documentation for this product, double-click the following file:

TIBCO_HOME/release_notes/TIB_activespaces_version_docinfo.html where TIBCO_HOME is the top-level directory in which TIBCO products are installed. On Windows, the default TIBCO_HOME is ^C:\tibco. On UNIX systems, the default TIBCO_HOME is ^/opt/tibco.

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

● TIBCO ActiveSpaces^® Installation

● TIBCO ActiveSpaces^® Administration

● TIBCO ActiveSpaces^® Monitoring and Management Console Guide

● TIBCO ActiveSpaces^® Developer's Guide

● TIBCO ActiveSpaces^® C API Reference

● TIBCO ActiveSpaces^® Java API Reference

● TIBCO ActiveSpaces^® .NET API Reference

● TIBCO ActiveSpaces^® Release Notes How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO Support:

● For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site:

http://www.tibco.com/services/support

● If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you can request one.

How to Join TIBCO Community

TIBCO Community is an online destination for TIBCO customers, partners, and resident experts. It is a place to share and access the collective experience of the TIBCO community. TIBCO Community offers forums, blogs, and access to a variety of resources. To register, go to the following web address:

https://community.tibco.com

(9)

Overview of Administration

TIBCO ActiveSpaces^® provides an administrative API and two administrative tools: the Admin object provided in Java, .NET, and C, the as-admin command-line tool and the ActiveSpaces Monitoring and Management (ASMM) web-based tool.

as-admin

The main administration utility for ActiveSpaces. Provides a command line interface (CLI) that allows you to manage nodes in the ActiveSpaces data grid. Using as-admin, you can:

● Connect to a metaspace as a full peer or as a remote client.

● Connect to another member of a metaspace.

● Run administrative commands as a member of a metaspace or on other members of the metaspace.

● Run administrative commands that allow you to:

— Display information about the metaspace and its members.

— Export the metaspace.

— Recover the metaspace or one of its spaces.

— Manage metaspace transactions.

— Display information about the spaces in the metaspace and their members, data, and locks.

— Create, join, leave, and alter the definition of spaces in the metaspace.

— Create and validate security policy files and security token files.

— Change logging levels.

The Admin Object

An object provided in the Java, .NET, and C (tibasAdmin) APIs that provides a programmatic interface for executing most of the commands available in as-admin.

ASMM

ActiveSpaces Monitoring and Management (ASMM) provides a GUI that lets you connect to a metaspace, display information about various ActiveSpaces system resources, for example, metaspaces, metaspace members, spaces, entry statistics, and so on, and browse space entries.

The as-agent Process

In addition to the administration tools, ActiveSpaces provides a process called as-agent that is used:

● To facilitate deployment of the ActiveSpaces cluster by connecting to a metaspace, joining all distributed spaces in the specified metaspace as a seeder, and keeping the space active.

● Optionally, to run an as-admin console and issue as-admin administration commands.

The as-dump Utility

ActiveSpaces provides an as-dump utility that you can use to display information about shared- nothing persistence data files.

The as-router Process

ActiveSpaces provides a separate executable called that is used in disaster recovery by

(10)

You can deploy in the following ways:

● Client-server deployment, also known as the leeches-seeders deployment.

● Shared-all persistence

● Shared-nothing persistence

● Host-aware replication

● Remote client

● Cross-site replication

Clients (Leeches) and Servers (Seeders)

When a member joins a space, it can join as a server (seeder) or as a client (leech).

This allows you to distribute the node deployment between seeders and leeches:

● Seeders play an active role in maintaining the space by providing CPU and RAM.

● Leeches play a passive role. They have access to space data but provide no resources.

Client-Server Deployment

For more information on deploying seeders and leeches in the ActiveSpaces network, see TIBCO ActiveSpaces Developer’s Guide.

(11)

Shared-All Persistence

In ActiveSpaces, you can persist data to disk storage and recover it if data loss occurs or if there is a problem with the cluster startup.

For detailed information on persistence, see TIBCO ActiveSpaces Developer’s Guide.

With shared-all persistence, all seeder nodes share a single persister or a set of persisters. Your

application must provide an implementation of the persistence interface before it can interface with the shared persistence layer of choice.

Figure 2, Deployment with Shared-All Persistence shows all of the seeder nodes in an ActiveSpaces cluster sharing a single database for persistence and data recovery.

Deployment with Shared-All Persistence

Shared-Nothing Persistence

With shared-nothing persistence, each node that joins a space as a seeder maintains a copy of the space data on disk. Each node that joins as a seeder writes its data to disk and reads the data when needed for recovery and for cache misses.

Figure 3, Deployment with Shared-Nothing Persistence shows a group of seeder nodes that persist data to local hard disk.

(12)

Host-Aware Replication

Use host-aware replication to ensure that the data for seeders running on the same machine is always replicated by seeders running on a different machine.

If there is only one seeder running on a machine, then host-aware replication is not needed, because data could not be replicated onto the same machine if there are no other seeders running on that machine.

To set up host-aware replication for the seeders on a machine, you logically group the seeders together using the following member naming convention:

<group_name>.<member_name>

where group_name can be any name which helps you to identify the grouping of seeder members. For example, the group_name can be the name of the machine on which the seeders are running or some other arbitrary name that logically identifies the group of seeders.

Host-aware replication is purely based on the group_name part of the member name of the seeder, and not on the IP address of the physical host the process is running on. Ensure that the <group_name> or the <member_name> do not have embedded dots in them. For example, Host.1.Seeder is wrong. It should be Host1.Seeder.

Figure 4, Sample Deployment with Host-Aware Replication shows a topology for host-aware

replication in which each host is running four seeders and a seeder grouping is defined for each host.

(13)

Sample Deployment with Host-Aware Replication

Remember that when replicate all is set, the host aware settings are ignored and all seeders of the spaces get either the original copy or the replica.

The first host is named Host1, and runs four seeders, Seeder1, Seeder2, Seeder3, and Seeder4. The second host is named Host2, and the third host is named Host3. Each of these hosts also runs four seeders.

If you name the seeders according to host-aware replication member naming, then ActiveSpaces always replicates data that is seeded on one of the seeders on a given host to a seeder that is running on

another host. Therefore, if a host or device goes down, the data that was seeded by any of the seeders on that host is not lost, because it is automatically backed up on a seeder that resides on another host.

You can set up this type of topology in several ways:

● By using the TIBCO ActiveSpaces API programs in an application program that implements

<group_name>.<member_name> member names.

For information on the API functions to implement host-aware replication, see TIBCO ActiveSpaces Developer’s Guide.

● By using as-agent and specifying the member names using the -member_name parameter.

The parameter, ^-name is deprecated.

For example, you might use ^as-agentwith the -member_name parameter to start four seeders on each host. For example, on host 1, run as-agent as follows:

java -jar as-agent.jar -metaspace ms -discovery

(14)

● When using as-admin to connect to a metaspace, the member name is specified using the

member_name option of the ^connect command.

Remote Client Architecture

In some situations, where nodes are unable to become full peers in the data grid, for example, when there is a firewall protecting a LAN, you can deploy ActiveSpaces nodes as remote clients. Remote clients can perform puts and gets, but cannot act as seeders or assume a management role in the core cluster.

Using remote clients also has the advantage of saving cluster processing overhead.

Remote Client Deployment

When you use remote clients, the remote clients can update the entries in the database, and ActiveSpaces seeders ensure that concurrency is maintained. Remote clients connect using TCP connections.

When a cluster restarts, ensure that you shutdown and restart all cluster members. Ensure that you shutdown and restart all remote clients ( including Admin if it is connected as a remote client) . Not doing so would result in the REMOTE_CLIENT_TIMED_OUT error. If you do not restart the remote clients, you cannot perform any operation on the cluster.

Figure 6, Concurrency with Remote Clients, shows remote clients updating to a seeder (Member 1). The seeders in the metaspace ensure that the data replicated on Member 2 is synchronized with the data on Member 1.

(15)

Concurrency with Remote Clients

Cross-site Replication

Cross-site replication is used to dynamically backup changes to the data in your metaspace to another metaspace in a different geographical location.

See the section Cross-Site Replication Concepts for more detailed information.

(16)

Specifying discovery when using ActiveSpaces security, choosing the right discovery point, and specifying multiple TCP discovery nodes for fault tolerance are some approaches you can use for node discovery.

Specify Discovery When Using ActiveSpaces Security If you are implementing ActiveSpaces security:

● The discovery transport type must be TCP.

● The discovery list on both the requestor and controller members for the given metaspace binding must be the same.

Also, when you implement ActiveSpaces security, you do not need to specify the discovery URL for a member that is joining the metaspace, because the discovery URL is retrieved from the security policy file or security token file used to start a node. If you do specify the discovery URL, it is ignored and ActiveSpaces uses the value for the metaspace as specified in the security configuration files.

For more information on ActiveSpaces security, see TIBCO ActiveSpaces Developer’s Guide.

Choose the Right Discovery Point

When you specify the discovery attribute (either in the discovery attribute of the MemberDef object for the space member or in the ^discovery parameter for the as-admin ^connect command), you can specify the IP address of the network interface to use for discovery.

It is important to specify the optimum discovery IP address. For example, in a network where you have several subnetworks, or where you have a relatively fast network and also a slower network,

performance will be best if you choose the faster network. Figure 7 shows a network topology that has a fast network and a slower network.

Selecting an Interface and Network for Optimum Discovery

In the network shown in Figure 7, there are two networks: network 1 is fast and network 2 is slow.

To ensure that you use the interface connected to the faster network for discovery, specify the interface for the faster network. In the example, we specify the tibpgm discovery protocol and the IP address of the interface for the faster network:

tibpgm://10.10.10.1

(17)

This ensures that discovery uses the faster network.

Specification of Multiple TCP Discovery Nodes for Fault Tolerance

If you are using the TCP discovery method, you can specify multiple TCP discovery nodes to provide fault tolerance.

Figure 8, Specifying Multiple TCP Discovery Nodes illustrates how to specify multiple TCP discovery nodes in a network with four TCP hosts.

In the example, we specify the tcp discovery method and two node address/port pairs:

tcp://10.10.10.1:6000;10.10.10.2:6000

When setting up the discovery attribute in the MemberDef object for the space or with the ^discovery parameter for the ^connect command, you can specify additional IP addresses and ports, separated by semicolons.

Specifying Multiple TCP Discovery Nodes

(18)

Administrative tasks for TIBCO ActiveSpaces are performed through a utility called as-admin, or the Administration Command Line Interface (Admin CLI). These tasks include connecting to a metaspace, creating a space, and displaying information about existing spaces and members.

To start the TIBCO ActiveSpaces Admin CLI, you must:

● Set environment variables for TIBCO ActiveSpaces

For information on setting the required environment variables, see the TIBCO ActiveSpaces Installation document.

● Launch the Admin CLI, in a command prompt window

The executable for running the Admin CLI (as-admin) is located in the^/bin directory of ActiveSpaces.

The Java version of as-admin is deprecated.

Additional Characteristics of the Admin CLI

● Arrow keys and the tab key function in the command window as in typical advanced shells.

● You can invoke a shell command by using the escape character ’!’, for example, ^!dir or ^!ls to list the files in the current directory.

● Field names and String literals must be enclosed in single or double quotes.

● In most cases, you will start using the Admin CLI by first using the ^connect command to connect to a metaspace.

● The default discovery mechanism is PGM. If RV discovery or TCP unicast discovery is needed, you must specify the appropriate discovery URL.

For more information on discovery, see the TIBCO ActiveSpaces Developer’s Guide.

The Execute Method

Admin CLI administrative commands (for example defining a space) can be executed directly from within an application. This is done by using the Metaspace object's execute method and passing it a string representing the Admin CLI command. A string is returned containing the output resulting from executing the command.

Launching the Admin CLI

The default location of the Admin CLI program is:

<TIBCO_HOME>\as\<version>\bin

Procedure

1. Open a command window.

2. Make sure that you have set the required environment variables as described in the TIBCO ActiveSpaces Installation document.

3. Enter the following commands:

cd <TIBCO_HOME>\as\<version>\bin as-admin

You can specify the following command line options when starting as-admin:

(19)

[-help] display command line options [-i(nput) <filepath>] specify file which contains admin commands to execute

[-s <start up command>] specify admin command to execute first [-c(onsole_log_level <log level>] console logging level (fatal, error, warning, info, fine, finer, finest)

[-f(ile_log_level) <log level>] enables file logging (fatal, error, warning, info, fine, finer, finest)

[-l(og) <log file>] file to use for file logging, default is <current directory>/log/as-<pid>.log

[-log_level <log level>] same as -file_log_level

[-log_append (true | false)] append to or clear contents of existing log file, default=true, append to

[-log_count <integer>] maximum number of log files, default=1 [-log_size <integer>] byte limit for log file, default=-1, unlimited

[-monitor_system (true | false)] enable or disable performance monitoring, default is false=disabled

[-metaspace <string>] metaspace name, default=ms [-member_name <string>] unique member name, default=autogenerated name

[-discovery <string>] discovery url, default=tibpgm [-listen <string>] listen url, default=tcp [-remote_listen <string>] remote listen url

[-rx_buffer_size <string>] size of receive buffer to use for each transport connection, default 2mb

[-worker_thread_count <integer>] number of threads to use for servicing remote invocations, default 32

[-data_store <string>] data store path

[-member_timeout <integer>] time in milliseconds to wait for a member to reconnect, default 30000

[-cluster_suspend_threshold <integer>]lost hosts allowed before membership operations are suspended, default don't suspend

[-connect_timeout <integer>] time (in ms) to wait to connect to metaspace, default 30000ms

[-security_policy <string>] security policy path [-security_token <string>] security token path

[-history_size <integer>] set size of command history buffer

The Admin CLI prompt appears:

as-admin>

The usage information for as-admin can be obtained by invoking as-admin -help from the ActiveSpaces bin directory in a command window.

You can now enter Admin CLI commands.

Using a Script File to Pass Arguments

Using a script file, you can pass commands for the Admin CLI to begin executing when you launch the Admin CLI.

as-admin -i admin-cmd-filename

Comments can be inserted into the script file by starting a line with #, as follows:

# this is a comment

This mechanism allows execution of commands in a batch mode through the Admin CLI. There are several limitations on the structure of the file:

● No special characters are allowed.

● Each line is executed sequentially by the Admin CLI. Therefore, each individual command must be entered on one line.

● The Admin CLI will not automatically exit and return to the shell after executing the commands of the file unless the script file contains a command.

(20)

connect name "UserMetaspace" discovery "tibpgm"

show members

export metaspace to "export.txt"

quit

######

This will connect to a metaspace, display members, export the metaspace, and exit the Admin CLI . The export metaspace [to <filename>] Admin CLI command generates a file containing the schema for the existing metaspace. For more details, see export metaspace. The admin-cmd-filename

value can be the path to this generated file. In this way, a new metaspace can be created using the exported metaspace schema.

Example

The following example demonstrates the following:

● invoking the Admin CLI using a script file to connect to a metaspace.

● creating a space.

Here is an example of the contents of the script file. In this example, the file is named example01.txt

and is located in the directory^C:\temp2.

connect name 'ms' discovery 'tibpgm' listen 'tcp'

define space name 'testspace' (field name 'key' type 'integer', field name 'value' type 'string') key (type 'hash' fields ('key'))

Launch the Admin CLI using the following syntax:

as-admin -i c:\temp2\example01.txt

alter space

Use alter space command to add a field to an existing space definition, or to add or drop an index from a space definition.

Syntax

alter space <string> add (field name <string> type <string> [nullable <boolean>]

[encrypted <boolean>](, field name <string> type <string> [nullable <boolean>])*)

alter space <string> add index ( name <string> [type <string>] fields (<string> (,

<string>)*))

alter space <string> drop index (<index_name> (, <index_name>)*)

Parameters

The following table describes the parameters for this command.

alter space Parameters

Parameter Description

space The name of the space to be modified.

(21)

add Specifies that a field is to be added:

● name specifies the name of the field to be added.

● type specifies the data type for the field. Must be one of the following: boolean, char, short, integer, long, float, double, string, datetime, blob.

● nullable specifies whether the field is nullable. The nullable value is optional.

The default for nullable is true.

● encrypted (optional) A boolean value specifying whether the field value is encrypted when it is stored in the space (default: false).

add index Specifies that an index is to be added:

● name specifies the name of the index.

● type specifies the type of the index, which can be hash or tree (default: tree).

● fields specifies a comma-separated list of field names to be used in the index.

When you add an index, the new index cannot have fields from an existing index.

drop index Specifies that one or more indexes are to be removed.

The drop index option must be followed by a comma-separated list of one or more index names specifying the indexes to remove.

Examples

Examples for add field:

alter space “myspace” add (field name “average” type “double”)

alter space “myspace” add (field name “average” type “double” nullable true) alter space “myspace” add (field name “average” type “double”, field name “total”

type “long” nullable true)

Examples for add index:

alter space add index (name “index1” type “hash” fields(“a”, “b”, “c”))

alter space add index (name “index1” type “hash” fields(“a”, “b”, “c”)) index (name

“index2” type “hash” fields(“a”, “b”, “c”))

Examples for drop index:

alter space drop index (“index1”)

alter space drop index (“index1”, “index2”)

Example for adding a field and an index:

alter space “myspace” add (field name “average” type “double”) index (name “index1”

type “hash” fields(“a”, “b”, “c”))

The parameters for fields and index use the following format:

(22)

You can perform consecutive updates by adding one field after another.

clear

The ^clearcommand is used to remove all lines of text from the command window except for a single Admin CLI prompt.

Syntax

clear

Parameters None.

clear | set password

Use the clear password command to create a new policy file without a password or a new token file without a password. Use the set password command to create a new policy file or a new token file with a new password.

When you issue the set password command, you are prompted to enter and verify the new password for the domain.

Syntax

clear | set password domain_name <string> policy_file <string>

[new_policy_file <string>]

clear | set password token_file <string> [new_token_file <string>]

Parameters

The following table lists the parameters for this command with a description of each parameter.

clear | set password Parameters

domain_name Specify the domain name for the domain for which you want to set or clear the password.

policy_file Specify the existing policy file to use when creating the new policy file without a password.

new_policy_file This optional parameter specifies the name of a new policy file that is created based on the policy file that you specify with the policy_file parameter.

If you do not specify a new policy filename, then a new policy file is created with the current date and time appended to the existing policy's filename. For example, if you specify an existing policy filename of “policy.txt,” ActiveSpaces creates a policy with the name “policy.txt.2013_01_16_20_38_00."

The policy filename cannot contain a forward slash character (“/”).

(23)

token_file If you are using the clear password command to clear the password in a token file or the set password command to set the password for a token file, specify the token filename.

new_token_file This optional parameter specifies the name of a new token file that is created based on the token file that you specify with the

token_file parameter.

If you do not specify a new token filename, then a new token file is created with the current date and time appended to the existing token's filename. For example, if the token file is named “my token,” ActiveSpaces creates a token file with the name “mytoken.2013_01_16_20_38_00."

Example

clear password domain_name 'AS-DOMAIN' policy_file 'policy.txt' new_policy_file 'newdeal.txt'

Parameter String values must be enclosed in either single or double quotes.

The following examples illustrate the syntax of the clear password command:

● clear password domain_name 'AS-DOMAIN' policy_file 'policy.txt'

● clear password domain_name 'AS-DOMAIN' policy_file 'policy.txt' new_policy_file 'newdeal.txt'

● clear password token_file 'mytoken'

● clear password token_file 'mytoken' new_token_file 'yourtoken'

close

The close command is used in conjunction with the open command which connects to a metaspace through the listen port of another metaspace member.

Any Admin CLI commands used while that connection is open is executed on the other metaspace member. Use the close command to close the connection to the other metaspace member’s listen port.

After using the close command, the Admin CLI will no longer be connected to a metaspace, and you must issue another open command or a connect command to re-establish a metaspace connection.

Syntax

close

Parameters None

connect

connect is used to connect to a metaspace. Connecting to a metaspace is a necessary initializing step for the Admin CLI to begin working with ActiveSpaces, just as it is for an ActiveSpaces application. The Admin CLI can only be connected to one metaspace at a time.

You cannot specify a token file and a policy file at the same time.

(24)

connect [name <string>] [discovery <string>] [listen <string>]

[member_name <string>] [security_token <string>]

[security_policy <string>] [identity_password <string>]

[authentication_domain <string>]

[authentication_username <string>]

[authentication_password <string>]

[authentication_keyfile <string>]

Parameters

The table lists the parameters for this command with a description of each parameter.

connect Parameters

name Optional. If a metaspace with this name does not exist, it will be created as a result of this command. If no name is specified, the Admin CLI will connect to the default metaspace, called

ms.

discovery Optional. The discovery URL can take one of three forms:

NOTE: If you are using ActiveSpaces security, you must use TCP discovery.

● If Unicast discovery is used, then a list of 'well known' IP addresses and ports must be passed in a URL with the following syntax:

tcp://ip1:port1;ip2:port2;...

● If multicast discovery is to be used then the URL must be as follows:

tibpgm://destination port/

interface;discovery group address/optional transport arguments

See “PGM (Pragmatic General Multicast) URL Format” in the TIBC0 ActiveSpaces Developer’s Guide for more

information on PGM discovery URLs.

If you are connecting as a security domain controller or as a security domain requestor, do not specify the discovery parameter. If you do specify a discovery parameter, it will be

overwritten by the discovery parameter specified in the security policy file or the security token file specified with the connect command.

(25)

listen Optional. Specifies which interface and port the administrative process should create its listening TCP socket on.

Syntax:

tcp://interface:port

See “Listen URL Format” in the TIBC0 ActiveSpaces Developer’s Guide for more information on listen URLs.

member_name Optional. Specifies a member name for the member. This helps to identify which member name is associated with which member ID. The show members command displays the member name if one has been assigned; otherwise, a default member name is assigned that is constructed from the member ID.

security_token Optional. Specifies the token file for a security domain requestor that must be authenticated by a security domain controller.

If TIBCO ActiveSpaces security is implemented and you are connecting from a requestor node, and the metaspace to which you are connecting requires a token file, specify the

security_token parameter and provide the directory path and filename for the token file.

If you specify a token file, do not specify the security_policy parameter.

security_policy Optional. If TIBCO ActiveSpaces security is implemented and you are connecting from a domain security controller node, specify the security_policy parameter and provide the directory path and filename for the policy file.

If you specify a policy file, do not specify the security_token parameter.

identity_password Optional. A string containing the password for the identity key in the security policy file.

authentication _domain Optional. A string containing the domain name for user authentication.

authentication_username Optional. A string containing the username to authenticate.

authentication_password Optional. A string containing the password for the username authentication_keyfile Optional. A string containing the full path for a file containing

the key to use for authentication.

member_timeout Specifies the time in milliseconds to wait for a member to reconnect. The default is 30000.

(26)

connect_timeout Specifies the time to wait to connect to the metaspace.

Example

connect name 'ms' discovery 'tcp://192.168.1.10'

Parameter values must be enclosed in either single or double quotes.

The following examples illustrate the syntax of the ^connect command:

● connect

● connect name <metaspace_name>

● connect discovery <discovery_url>

● connect listen <listen_url>

● connect discovery <discovery_url> listen <listen_url>

● connect name <metaspace_name> discovery <discovery_url>

● connect name <metaspace_name> discovery <discovery_url> listen <listen_url>

member_name <member_name>

● connect security_policy ’mypolicy.txt’ name ’ms’ listen ’tcp://127.0.0.1:50000’

● connect security_token ’mytoken.txt’ name ’ms’ listen ’tcp://127.0.0.1:50000’

define | create safe_password

Passwords can be used in different contexts in ActiveSpaces. Depending on the configuration of the security domains, token files, and user authentication requirements, there are different options. The

define | create safe_password command allows you to create safe passwords for different situations.

A new command is now available to generate safe passwords for different purposes.

Syntax

define | create safe_password for (identity | authentication)

Parameters

define | create safe_password Parameters

identity Specify the safe password that is to be used to decrypt identities.

authentication Specify the safe password that is to be used for user password authentication.

Remarks

If you choose to encrypt identities in domain or token files, you must use one of the following commands:

(27)

● define | create security_policy ... encrypt true ... policy_file <string>

● define | create security_token ... create_identity ... encrypt true ...

token_file <string>

The default behavior forces the private key to be encrypted therefore if encrypt true is not used, the generated private key will be protected with the provided password

When safe passwords are created to be used to decrypt identities, use create safe_password for identity .

If client authentication is to be enforced in the security policy for a given cluster, then joining requestor members must provide a valid credential before being able to use cluster resources. If the

authentication scheme is userpwd (authentication=userpwd;...) then the user must normally provide a username and a password (and an additional domain value if using system source and windows authentication where accounts reside on a central/corporate server).

When safe passwords are created to be used in this context, use create safe_password for authentication.

For both of the above cases, the command produces encoded passwords, which can only be used for the purpose created. The password can then be applied in command lines, scripts, APIs and even at

password prompts.

Example:

as-admin> create safe_password for identity Password: ...

Verifying - Password: ...

Safe password: #SAFE#e041rA3TWXxJmhiriab7wG1p+OQqDbxCI0dsrDhTcLdbM=

...

> as-examples -security_policy policy.txt -listen tcp://localhost -role seeder - identity_password #SAFE#e041rA3TWXxJmhiriab7wG1p+OQqDbxCI0dsrDhTcLdbM=

as-admin> create safe_password for authentication Password: ...

Verifying - Password: ...

Safe password: #SAFE#69+OgjeN0tWrlDkvpJQ6D/e81T3pUbLYhOoRH9dxKX/As=

define | create security_policy

Use the define|create security_policy command to create a security policy file.

Syntax

define | create security_policy [policy_name <string>]

[encrypt <boolean>][validity_days <integer>] policy_file <string>

Parameters

(28)

policy_name Optional. Specifies the name of the policy to be created. If you do not specify a policy name, the policy is given the default name AS-POLICY.

You cannot specify a policy file and a security token for the same connection.

You can also specify one or more domains that the policy is associated with:

To specify that the policy is associated with one domain, specify the policy name and the domain as follows:

define | create security_policy policy_name <policy_name>/

<domain name> policy_file <string>.

For example:

create security_policy policy_name "OUR_POLICY/OUR_DOMAIN"

policy_file "ourpolicy.txt"

If you enter the command in this way, the encrypt setting defaults to false:

then if you specify one domain, you are prompted to enter and verify the password for that domain. If you specify multiple domains, you are prompted to enter and verify the password for each domain.

If you specify encrypt=false, ActiveSpaces creates all domains is created with an unencrypted ID, which requires no password, and you are not prompted for a password.

To create multiple domains associated with the policy, specify the policy name and a list of domains that the policy is associated with. Specify the domains separated by commas:

define | create security_policy policy_name "<string/string, string, string ...>" policy_file <string>

For example:

create security_policy policy_name "NEW_POLICY/MD1,MD2,MD3"

policy_file "newpolicy.txt"

encrypt Optional. Indicates whether the private key for the policy is to be encrypted. The default is encrypt true.

If you specify encryption, as-admin prompts you to specify and verify a new domain password and creates an encrypted private key in the Domain Identity section of the policy file.

If you specify encrypt false, the domain does not require a password, and as-admin creates an unencrypted private key in the policy file.

validity_days An integer that specifies how long the domain ID that the command creates remains valid. The default value is 365 days.

Policies can have more than one domain, where (in theory) each of them can have different validity days if the domain definitions are moved between policy files manually.

(29)

policy_file Enter the name of the policy file that is to be created for the policy.

You cannot specify a policy file and a security token for the same connection.

The policy filename cannot contain a forward slash character (“/”).

Example

The following examples illustrate the syntax of the define | create security_policy command:

● create security_policy policy_name 'mypolicy' policy_file 'policy.txt'

● create security_policy policy_name 'mypolicy' encrypt false policy_file 'policy.txt'

● define security_policy "MY_POLICY/MY_DOMAIN" policy_file ’policy.txt’

define | create security_token

Use the define | create security_token command to create a security token for deployment to ActiveSpaces requestor nodes.

When you enter the command, you are prompted to enter and verify a new token password for the security token. Enter and verify the password.

Syntax

define | create security_token domain_name <string>

policy_file <string> [create_identity [common_name <string>]

[encrypt <boolean>][validity_days <integer>]]token_file <string>

Parameters

define | create security_token Parameters

domain_name Specifies the name of the domain for which the security token is to be created.

policy_file Specifies the name of the policy file that is to be used to create the token.

create_id Optional. Enter the ^create_id parameter if you want to create a private key to verify the identify of connecting nodes.

(30)

common_name Optional. If you enter the create_id parameter and you want to provide an X.509 common name to identify the private key, specify a common name. If you do not specify a common name, ActiveSpaces generates a common name that contains the domain name plus a random number; for example "/

CN=AS-REQUESTOR-FEF3A467."

If there is no common name associated with the token, then node connections use a temporary name generated by ActiveSpaces. If you provide a common name for the token file, this name is always used.

encrypt Optional. If you enter the create_id parameter and you want to encrypt the private key, enter encrypt true (the default setting).

If you do not want to encrypt the private key, enter encrypt false. Using encrypt false eliminates having to enter the password each time the node is started.

validity_days Optional. To specify the number of days that the private key is valid for, enter the number of days. The default setting is 365 days.

token_file Provide the name of the token file that is to be created.

Example

The following examples illustrate the syntax of the define | create security_token command:

● create security_token domain_name 'AS-DOMAIN' policy_file 'policy.txt' create_identity common_name 'MyRequestor-123' encrypt true validity_days 90 token_file 'mytoken'

● create security_token domain_name 'AS-DOMAIN' policy_file 'policy.txt' create_identity token_file 'newtoken'

● create security_token domain_name 'AS-DOMAIN' policy_file 'policy.txt' create_identity common_name 'MyRequestor-123' encrypt true validity_days 100 token_file 'mysecurity_token'

define | create space

Used to create a space.

Syntax

define | create space <string>

(field name <string> type <string> [nullable <boolean>] (, field name <string> type

<string> [nullable <boolean>] [encrypted <boolean>)*) key ( [type <string>] fields (<string> (, <string>)*)) distribution_def ('KEY','field0','field1','field2' ...) (index ( name <string> [type <string>] fields (<string>

(, <string>)*)))*

[distribution_fields (<string> (, <string>)* ) [distribution_policy <string>]

[replication_count <integer>] [replication_policy <string>]

[host_aware_replication <boolean>]

[persistence_type <string>] [persistence_policy <string>]

[file_sync_interval <long>]

[cache_policy <string>]

(31)

[min_seeders <integer>]

[capacity <long>] [eviction_policy <string>]

[ttl <long>] [lock_ttl <long>]

[lock_wait <long>] [lock_scope <string>]

[space_wait <long>]

[write_timeout <long>] [read_timeout <long>]

[query_timeout <long>] [query_limit <long>]

[forget_old_value <boolean>]

[virtual_node_count <integer>]

[phase_count <integer>] [phase_interval <long>]

[phase_ratio <integer>]

[routed <boolean>]

Remarks

The supported data types for fields are:

Field types

boolean, char, short, integer, long, float, double, blob, string, datetime Distribution policies

non_distributed, distributed Persistence types

none, share_all, share_nothing Persistence policies

sync, async

Replication policies sync, async

Eviction policies none, lru

Lock scopes thread, process Parameters

The parameters for this command are listed and described in define create space Parameters.

define | create space Parameters

space Required. Specify the name of the space that is to be

created.

field Required.

The data type for a field must be one of the following:

boolean, char, short, integer, long, float, double, string, datetime, blob.

nullable Optional. Can be either true or false (no quotes). By default is equal to false. If a field has nullable set to true, tuples put into the space do not need to contain a field with that name.

(32)

encrypted Optional. If the field is not a key field or an index field and you have enabled ActiveSpaces security, you can specify that the data in the field is encrypted. Each (non-key, non- index) field can be made encrypted, as long as the policy for the corresponding domain allows it.

key Required. Identifies one or more fields (already specified

with the field parameter) that will serve as a unique key for the space.

When you enter the key parameter, you can optionally specify the index type of the key field by including the type keyword. For example:

key (type "hash" fields (...))

The fields keyword is required.

The type keyword is optional. The default index type is the

“hash” index type.

index Optional. Identifies one or more fields already specified with the “field” parameter that will serve as a secondary index. You can specify an index name and index type to be used by entering:

index (name "index1" type "tree" fields (...))

The name keyword is required.

The type keyword is optional. The default is index type is

“tree.”

The fields keyword and fields are required

You can specify as many indexes as desired by specifying the indexes, one by one, after the key parameter. You just need to put them one after other after the key field. For example:

key (...) index(name "index1" ...) index(name

"index2" ...) index (name "index3" ...)

(33)

distribution_fields Defines one or more fields as distribution fields. If a field is defined as a distribution field, then all tuples that have an identical data value for the field are stored on the same seeder.

The distribution fields must be a subset of the key fields.

Otherwise, ActiveSpaces throws an exception.

The following example shows how to set up distribution fields:

key (fields ('KEY','field0','field1','field2')) distribution_fields

('KEY','field0','field1','field2') distribution_policy 'distributed' replication_count 0

In the example, field0, field1, and field2 are defined as key fields and also as distribution fields.

If you define fields as distribution fields, then you must also set distribution_policy to distributed.

distribution_policy Optional. Determines whether management of entries in the space is shared among the seeders that have joined the space (distributed) or a single seeder is responsible for all entries in the space (non_distributed). The default value is distributed.

If you define fields as distribution def fields, then you must also set distribution_policy to

distributed.

replication_count Optional. An integer that specifies the number of times each entry should be replicated on different seeders (default: 0).

replication_policy Optional. A value of ^syncspecifies that replication is done in synchronous mode for the space, before the operation returns. When an operation modifies one of the entries in the space, the operation only returns an indication of success when that modification has been positively replicated up to the degree of replication required for the space. A value of ^async specifies that replication is asynchronous.

host_aware_replication Optional. A boolean indicating whether host aware replication is enabled or disabled. Host aware replication ensures that data is not replicated on any seeders specified to be in the same seeder group (default: true, host aware replication is enabled).

(34)

persistence_type Optional. Specifies whether persistence is enabled for the space, and if so, what type of persistence to use.

To specify no persistence, specify none. To specify shared all persistence (space members designated as persisters maintain data on disk), specify share-all. To specify shared- nothing persistence (each member maintains data on disk), specify share_nothing.

persistence_policy Optional. Specifies the what type of communication is used to maintain persistence: synchronous (sync) or

asynchronous (async).

file_sync_interval A long integer that indicates the amount of time (in milliseconds) to wait between persists to the data store when asynchronous, versus shared-nothing persistence is used (default: 10000).

min_seeders Optional. Specifies the minimum number of seeders that should be joined to the space before the space becomes ready to accept operations. The default value is 1.

capacity Optional. Specifies a maximum number of entries per

seeder for the space. When the capacity is reached the result of any additional request to put (insert) a new entry in the space will depend on the value of the eviction_policy

attribute. The default value is -1 (no capacity).

eviction_policy Optional. If a put operation on a space would cause a seeder to exceed the space's ^capacity attribute, then the value of this attribute will dictate the result of this

operation: if the value is 'none' (in quotes) then there will be no eviction and the operation will fail because the seeder is already at capacity. If the value is 'lru' (in quotes) then the seeder will evict another entry from the space using the 'least recently used' eviction algorithm. The default value is 'none' (no eviction).

ttl Optional. Time to live in milliseconds. The default is -1

(forever).

lock_ttl Optional. Specifies in milliseconds the duration of a lock placed on the space. The default is -1 (forever).

lock_wait Optional. For a space that is locked, specifies how long a member process will wait for it to become unlocked. The default is 0. Other accepted values are only positive values.

The unit of measure is milliseconds.

(35)

lock_scope Optional. Specifies the lock scope to be used for each operation that includes locking.

You can specify the following:

● thread The lock applies to the current thread only.

● process The lock applies to the entire application.

The default value is thread.

space_wait Specifies the space wait for the specified space.

The space wait value is a timeout that applies to operations that cannot be processed because the space is not in the READY state, i.e., the space in the INITIAL, LOADING, RECOVER, or SUSPEND state.

write_timeout A long integer indicating the amount of time (in

milliseconds) a write operation on the space can be blocked from completing the write before failing (default: 60000.) query_timeout A long integer indicating the amount of time (in

milliseconds) a query on the space can take to return its results (default: -1, take forever).

query_limit A long integer specifying the maximum number of entries to be returned by a query on this space (default 10000). The query_limit setting is intended to help you prevent large queries from exhausting the system's memory. By default, all browsers and listeners use the query_limit defined for the space they are browsing or listening on.

When there are multiple seeders for a space, the query limit is divided evenly amongst the seeders of the space so that an even number of resulting entries is taken from each seeder. When the number of entries in the result of a query approaches the query limit, it is possible that some seeders might return fewer entries than others. This is because the algorithm

ActiveSpaces uses to distribute entries amongst seeders does not guarantee the entries will be evenly distributed. You should adjust the query_limit setting to accommodate the largest number of entries you will allow queries to return. When doing so, keep in mind that the query_limit should be slightly larger than the intended amount to account for the uneven distribution of entries amongst seeders.

read_timeout A long integer indicating the amount of time (in

milliseconds) a read operation on the space can be blocked

TIBCO ActiveSpaces®

Administration

Contents

Figures

Overview of Administration

Clients (Leeches) and Servers (Seeders)

Shared-All Persistence

Shared-Nothing Persistence

Host-Aware Replication

Remote Client Architecture

Cross-site Replication

Launching the Admin CLI

Using a Script File to Pass Arguments

alter space

clear

clear | set password

close

connect

define | create safe_password

define | create security_policy

define | create security_token

define | create space