Command-line Control Programs

The command-line control programs, soss.exe and geos.exe, 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.exe command-line program is used to manage a local ScaleOut StateServer (SOSS) store, and the geos.exe 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.exe

The command-line syntax for soss.exe 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] 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] 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] Note

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.
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;
  • 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.

Here are some examples of soss.exe 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 select myStore
Select myStore’s cloud access provider to use when a remote client starts.
[Note] 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.exe

The command-line syntax for geos.exe 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] 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] Note

    When using secure connections, the remote store must be configured to accept secure connections.

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 London
Remove remote store London.