Command-line Control Programs

The command-line control programs, soss and geos, together give you the capabilities of the Management Console in the form of commands that can be entered at a console command prompt. The soss command-line program is used to manage a ScaleOut StateServer cluster, and the geos command-line program is used to manage the ScaleOut GeoServer option for either replicating data to a remote SOSS store or accessing data from a remote store.

soss Command

The command-line syntax for the soss command is as follows:

soss command [target] | [gwyspec] [set_options] | [backup_options] | [restore_options] | [auth_options] |
[prov_spec]

where the commands are:

query: Get the current status of the store and of all hosts. Also report the status of an ongoing backup or restore operation when the ALL parameter is supplied.
show: Show the status and configuration information for the selected host or all hosts.
set: Set configuration parameters for the selected host or all hosts.
set_cli: Set configuration parameters for the remote client or for all local clients.
show_remcli: Show remote client configuration parameters.
join: Activate the StateServer service for the selected host or all hosts. This causes the selected host(s) to join the store and accept a portion of the workload.
leave: De-activate the StateServer service for the selected host or all hosts. This causes the selected host(s) to leave the store.

Note

It is important to allow a host to fully leave the store prior to shutting down the host or restarting the StateServer service. Otherwise, the host will abruptly leave the store, and other hosts will trigger recovery actions that further delay resumption of full storage throughput. In some cases, the distributed store can be destabilized, especially if multiple hosts are simultaneously stopped in this manner. Be sure to wait for the command to fully complete (indicated by an inactive status) prior to restarting the host. Use the leave_wait command instead of this command whenever possible.
join_wait: Activate the StateServer service for the selected host or all hosts and wait for the host(s) to complete joining the store and report an active status. This command causes the selected host to join the store. The command times out after three minutes and reports failure if the host has not joined the store.
leave_wait: De-activate the StateServer service for the selected host or all hosts and wait for the host(s) to complete leaving the store and report an inactive status. This command causes the selected host to leave the store. The command times out after three minutes and reports failure if the host has not left the store.
restart: Restart the StateServer service for the selected host or all hosts. This command first attempts to have the selected host leave the store and then restarts the service through the host’s Windows service control manager. If all hosts are selected, the StateServer service is immediately restarted on all hosts.
restart_now: Immediately restart the StateServer service for the selected host or all hosts. This restarts the service through the host’s Windows Service Control Manager.

Note

Do not restart more than one active host until recovery has been allowed to complete. The store’s recovery can require one or more minutes depending on the current storage load. Simultaneously restarting more than one host prior to awaiting complete recovery by the remaining hosts could cause data to be lost, and storage throughput could be affected for several minutes until recovery completes.

Note

On Windows, ScaleOut StateServer uses the Windows Service Control Manager (SCM) to restart the StateServer service. In some cases, the SCM may return an error when attempting to start the service. You can manually configure the SCM to restart the StateServer service as an automatic recovery action if the service fails. Please consult your Windows documentation for more information.
wait: Await and report status change on the selected host or all hosts. This causes the command-line control program to block execution until it is notified of a status change by the local StateServer service.
clear: Clear the store. This command removes all store objects on all reachable hosts. Do not use this command if some hosts are not reachable due to a network outage.
test: Test the store. This command verifies client access to the store on all reachable, active hosts. Do not use this command if some hosts are joining, leaving, temporarily not ready, or not reachable due to a network outage.
show_region_map: Show store-wide region status map.
add: Add a gateway specification (gwyspec) that allows a remote client to access a remote SOSS store.
remove: Remove a gateway specification (gwyspec) that allows a remote client to access a remote SOSS store.
populate: Populate the client configuration file with gateway specifications for all hosts reachable at the remote SOSS store.
backup: Back up objects in the SOSS store to the file system.
restore: Restore objects from the file system to the SOSS store.
cancel_br: Cancel the ongoing backup or restore operation.
connect: Connect the local host to a group of hosts.
create_group: Create a new host group containing only the local host.
disconnect: Disconnect the target host from its group of hosts.
set_ns_auth: Set namespace authorization methods.
clear_ns_auth: Clear namespace authorization methods.
show_ns_auth: Show namespace authorization methods.
set_user_auth: Set user authorization methods. A namespace authorization method must be set before executing this command.
clear_user_auth: Clear user authorization methods.
show_user_auth: Show user authorization methods.
show_logins: Show user logins.
force_relogin: Clear server login state, which forces clients to log out and then login again.
add_prov: Add a store access provider’s configuration information for a specified store.
remove_prov: Remove a store access provider’s configuration information.
select: Select a store access provider for a specified store.
deselect: De-select a store access provider for a specified store.
gen_keypair: Generate a new keypair for encrypting connections.
show_ds: Show hServer Hadoop cache datasets.
remove_ds: Remove the specified Hadoop cache dataset or all datasets.
show_ig: Show a list of invocation grids by name and identifier.
remove_ig: Remove the specified invocation grid or all invocation grids.
add_notify: Add a notify_config directive to the client parameters file.
rem_notify: Remove a notify_config directive from the client parameters file.
help: Display help information.

The target argument specifies the host to which a command should be applied. The possible values are:

(no value): the local host
<IP address>: a selected host’s IP address in dotted notation, e.g., 10.0.1.7
all: all hosts (or any host for the wait command)

The gwyspec argument specifies the management port and a gateway on the remote SOSS store to which a remote client should connect. This argument takes the form:

<mgt_port>,<gateway_IP>,<gateway_port>

where the components are as follows:

<mgt_port>: remote store’s management port
<gateway_IP>: gateway IP address for a host in the remote store, specified in dotted notation, e.g., 10.0.1.7
<gateway_port>: gateway server port for the remote host specified by <gateway_IP>

The components of a gateway specification provide sufficient information for a remote client to establish communications with a remote SOSS store. The remote store’s management port (which is common to all hosts in the remote store) and the gateway IP address and port must be reachable from the local server on which the Remote Client option is installed.

The set_options argument specifies a list of parameters and values in the form parameter=value and separated by spaces, for example:

subnet_mask=255.255.255.0 svr_port=2121

The spelling of the parameter names is the same as that used in the parameters file and described in the section Configuration Parameters.

The set_cli command is used to set the client parameters described in the sub-section Additional Parameters for the Remote Client Option and Local Clients within Configuration Parameters. Note that this command does not have a target argument. Local client parameters are automatically propagated to all servers within the SOSS store, and remote client parameters are only updated on the remote client which runs this command.

The backup_options argument specifies a list of parameters and values for a backup operation in the form parameter=value and separated by spaces; surrounding double quotes can be used to include spaces within character strings. The allowed parameters are:

id: an identifier for the backup used within the file names; if omitted, a date and time stamp is automatically used; characters in the identifier must be alphanumeric characters or spaces;
name: the cache name to be backed up; if omitted, all cache names are backed up; “redis-only” backs up only the Redis database
def_name: if 1 or true, the default cache name (corresponding to application id 0) is backed up; if omitted or 0 or false, the default cache name is not backed up;
path: the file path to the folder in which each SOSS host will create backup files; if omitted, the folder backup within the SOSS installation folder will be used;
max_len: the maximum length in MB for each backup file; if omitted, all objects on each SOSS host will be stored in a single backup file.

The restore_options argument specifies a list of parameters and values for a restore operation in the form parameter=value and separated by spaces; surrounding double quotes can be used to include spaces within character strings. The allowed parameters are:

id: an identifier for the backup files used within the file names; if omitted, all backup files in the target folder will be restored;
name: the cache name to be restored; if omitted, all cache names are backed up;
def_name: if 1 or true, the default cache name (corresponding to application id 0) is restored; if omitted or 0 or false, the default cache name is not restored;
path: the file path to the folder in which each SOSS host will search for backup files; if omitted, the folder backup within the SOSS installation folder will be used;
overwrite: if 1 or true, objects in the SOSS store will be overwritten if necessary; if omitted or 0 or false, objects will not be overwritten.

The auth_options argument specifies a list of parameters and values for an authorization operation in the form parameter=value and separated by spaces; surrounding double quotes can be used to include spaces within character strings. Note that not all options apply to all authorization commands. The allowed parameters are:

name: an identifier the specified namespace unless the def_name or global_name parameters are used;
def_name: if 1 or true, use the default namespace;
global_name: if 1 or true, apply this command to global operations;
all_names: apply a show, clear, or force_relogin command to all names;
user: user name (applies to user authorization commands); this parameter optionally can be specified for the show_user_auth, force_relogin and show_logins commands;
method: specifies the authorization method: default for user-based authorization or custom for provider-based authorization; this is a required parameter for the set_ns_auth command;
path: path of authorization provider for provider-based authorization;
permissions: when setting user-based authorization, r for read-only access or rw for read-write access; this is a required parameter when setting user-based authorization;
timeout: when setting user authorization, timeout value in minutes (2 minutes to 45 days); default is 2 hours if this parameter is not specified;

The prov_spec argument specifies a store access provider’s configuration information for a remote SOSS store to which a remote client should connect. This argument takes the form:

<store>,public|public_secure|private,AWS|Azure,<param1>,<param2>,<param3>,<param4>

where the components are as follows:

<store>: remote store’s name as specified when deployed
public|public_secure|private: use the public vs. the private IP addresses to access the store. public_secure uses the public IP addresses with secure connections
AWS|Azure: select the store access provider for AWS vs. Azure
<param1>: the first parameter (or “null”) for the store access provider
<param2>: the second parameter (or “null”) for the store access provider
<param3>: the third parameter (or “null”) for the store access provider
<param4>: the fourth parameter (or “null”) for the store access provider

The provider specification contains provides sufficient information for a remote client to establish communications with a remote SOSS store running on a cloud provider. The parameters are specific to the cloud provider.

The add_notify argument consists of three components separated by commas without spaces:

<remote_store_name>,<cache_name>,[0|1]

as described in the section Configuration Parameters. If the third component is omitted, the value 0 is assumed.

The rem_notify argument consists of two components:

<remote_store_name>,<cache_name>

Here are some examples of soss commands and their effect:

soss query all: Queries the store’s status, the status of all hosts, and the status of any ongoing backup/restore operation.
soss show 10.0.1.7: Shows the configuration parameters on host 10.0.1.7.
soss show_remcli: Show remote client configuration, including remote gateways and/or store access providers.
soss set svr_port=721: Sets the local host’s svr_port parameter to 721.
soss wait all: Wait for a status change on any host.
soss add 720,10.0.1.5,721: Add a gateway specification for accessing a remote SOSS store.
soss set_cli max_lcl_retries=3: Sets the max_lcl_retries parameter to 3 on all local hosts.
soss backup: Backs up all objects to the backup folder within the SOSS installation folder on every SOSS host.
set_ns_auth name=ns1 method=default: Specifies that the ns1 namespace will use the default user-based authorization provider.
set_user_auth name=ns1 user=bob permissions=rw: Specifies that user bob is authorized to access the ns1 namespace for read-write access.
clear_user_auth name=ns1 user=bob: Removes user bob from the user-based authorization list for the ns1 namespace.
clear_ns_auth name=ns1: Removes the authorization provider from the ns1 namespace (allowing full read-write access to all users).
show_logins all_names=true: Show logins for all namespaces.
soss add_prov myAWSStore,public,AWS,IAJCFT,mrMoGxRBFF,us-east-1,null: Add configuration information for an AWS cloud access provider to connect to myAWSStore.
soss add_prov myAzureStore,public_secure,Azure,MyAzureStoreAccountName,8LZOlBnFajFkWk6BSRtaGs9oWa+SLqV/12AUdgzXbEQIN4mMaT687aCp9+zaJljPChNnMyfNZJN1B7nB9j2B9A==,null,myAzureStore: Add configuration information for a Microsoft Azure cloud access provider to connect to myAzureStore using a secure connection.
soss remove_prov myStore: Remove configuration information for myStore.
soss add_notify remStore,myCache,1: Add a directive to configure the Java Named Cache client to use ScaleOut GeoServer Pro pull mode with the remote store remStore using the notify coherency policy for the named cache myCache; override configuration settings within the application’same code.
soss select myStore: Select myStore’s cloud access provider to use when a remote client starts.

Note

Changing the network interface, subnet mask, multicast IP address, server port, or management port will cause the host’s StateServer service to be restarted. Restarting the StateServer service on the local host will temporarily interrupt management operations using the management console or the command-line control program.

geos Command

The command-line syntax for geos is as follows:

geos command [<name> | all | <remstore_args> | <gateway_args>]

where the commands are:

query: Get the current status of the selected remote store or all remote stores.
show: Show the status and configuration information for the selected remote store or all remote stores.
start: Start replication for the selected remote store or all remote stores.
sync: Start replication for the selected remote store or all remote stores and copy all local objects to the remote store(s).
stop: Stop replication for the selected remote store or all remote stores.
test: Test communications with the specified remote store to ensure that it is reachable. Note that all remote stores cannot be specified for this command.
add remstore: Add a remote store described by <remstore_args> to the client configuration file. Once a remote store has been added, replication to the remote store can be started.
add gateway: Add a gateway described by <gateway_args> to the client configuration file. Adding multiple gateways helps the local store to establish communications in case some of the remote store’s hosts are not active.
remove remstore: Remove a remote store described by <remstore_args> from the client configuration file. This command also removes all gateway addresses associated with the remote store.
remove gateway: Remove a gateway described by <gateway_args> from the client configuration file.
populate remstore: Populate the gateway list for a remote store described by <remstore_args> by contacting the remote store and obtaining a list of all active gateway hosts. The gateways are added to the client configuration file. This command is used to automatically add multiple gateways without manually entering each gateway address. It can also be used from time to time to discover new gateway addresses as hosts are added to the remote store.
set: Set parameter for a specified remote store.
set_local_name name: Set the local store’s name for use in remote access (“pull”) operations.
show_local_name: Show the local store’s name which has been specified for use in remote access (“pull”) operations.
help: Display help information.

The <name> parameter specifies the local name for a remote store. This name is used to identify the store in management commands after the remote store’s access information has been added to the local client parameters file. This parameter must be a string of printable characters, for example, London, and the string cannot contain an embedded comma.

The <remstore_args> argument specifies the remote store to which a command should be applied. This argument takes the form:

<name>,[<access_mode>,]<mgt_port>,<gateway_IP>,<gateway_port>

where the components are as follows:

<name>: string corresponding to a local name for the remote store, for example, London
<access_mode>: access mode for a remote store: push or pull; (default is push if not specified)
<mgt_port>: remote store’s management port
<gateway_IP>: gateway IP address for a host in the remote store, specified in dotted notation, e.g., 10.0.1.7
<gateway_port>: gateway server port for the remote host specified by <gateway_IP>

The components of a remote store specification provide sufficient information for ScaleOut StateServer to establish communications with it. The remote store’s management port (which is common to all hosts in the remote store) and the gateway IP address and port must be reachable from the local SOSS store.

The <gateway_args> argument specifies a gateway address on a remote store. This argument takes the form:

<gateway_IP>,<gateway_port>

where the components are as follows:

<gateway_IP>: gateway IP address for a host in the remote store, specified in dotted notation, e.g., 10.0.1.7
<gateway_port>: gateway server port for the remote host specified by <gateway_IP>

These components provide sufficient information for ScaleOut StateServer to establish communications with a gateway host at the remote store, and they must be reachable from the local SOSS store. Associating multiple gateway addresses with a remote store ensures that the local store can establish communications to start data replication even if some of the hosts at the remote store are not active.

Note

Gateway addresses (i.e., IP address and port pairs) for all remote stores must be unique. It is permissible to use either the same IP address or port in two gateway addresses, but the combination must be unique.

The set command’s parameters are:

auto_start: Automatically start replication to the specified remote store when the local store starts; values are 0 (do not auto-start) and 1 (auto-start).
use_secure_conn: Use secure connections when connecting to the specified remote store; values are 0 (do not use secure connections) and 1 (use secure connections).

Note

When using secure connections, the remote store must be configured to accept secure connections.
conn_timeout: Set a connection timeout when connecting to a remote store, reading, or writing an established TCP connection. This parameter is an integer multiple of 500 msec. with a minimum value of 1, maximum of 64, and default of 4 (2 seconds).

Here are some examples of possible commands and their effect:

geos query London: Queries the status of remote store London.
geos query all: Queries the status of all remote stores.
geos show London: Shows the status and configuration parameters for remote store London.
geos add remstore London,720,10.0.1.4,721: Add a remote store in push mode with management port 720, gateway address 10.0.1.4, and gateway server port 721.
geos add remstore Paris,pull,720,10.0.1.4,721: Add a remote store in pull mode with management port 720, gateway address 10.0.1.4, and gateway server port 721.
geos add gateway London,10.0.1.5,721: Add a gateway to remote store London with gateway address 10.0.1.5 and gateway server port 721.
geos start all: Start replication to all remote stores.
geos remove remstore London: Remove remote store London.