epadmin

StreamBase Runtime — Spotfire Streaming command complex

SYNOPSIS

epadmin  [global-parameters]  command  target  [command-parameters]

epadmin help

epadmin help targets --format=[readable|json]

epadmin help target --format=[readable|json]

DESCRIPTION

Use the epadmin command to install, start, manage, administer, and communicate with StreamBase Runtime nodes and clusters. Use epadmin from a configured shell prompt. This means:

Command Syntax

The components of an epadmin command are:

  • global-parameters are always applied on the left side of the command. These are one or more parameter statements from the short list of global parameters that can apply to any epadmin command and target. The epadmin-globals(1) page describes each global parameters. At the command prompt, run epadmin help globals or man epadmin-globals.

  • command is an imperative verb such as display, install, start, stop, and help that is to be applied to the target.

  • target is one of the supported targets for the command to act on, such as node, cluster, application, engine. At the command prompt, run epadmin help targets for the list of supported targets.

  • command-parameters are always applied on the right side of the command and target. These are one or more parameter statements supported by the specific command for that target, as described on each target's page in this reference. At the command prompt, use epadmin help targetname or man epadmin-targetname to see the command-parameters available for that target.

Parameter Syntax

The epadmin command supports two syntaxes for entering parameters:

  • Gnu-style parameter syntax with two hyphens prefixing parameter names. You can enter the fewest number of letters of each parameter's name that maintains that parameter's uniqueness among the current target's supported parameters. This syntax does not require an equals sign between a parameter and its argument, but accepts one if present. For example, the following lines all perform the same action: 

    epadmin --adminport=2000 dequeue stream --verbose=true
epadmin --ad=2000 dequeue stream --ve
epadmin --ad 2000 dequeue stream --ve true
epadmin --ad=2000 dequeue stream --ve true

  • Legacy syntax from previous releases is still supported. In this format, parameters do not use prefixed hyphens, you must type the full parameter name, and the equals signs are required. For example: 

    epadmin adminport=2000 username=sbuser password=secret display node

You cannot mix Gnu and legacy syntax in the same command.

In parameter statements, Boolean true values in command-parameters are optional, and can either be specified as ‑‑param=true or just --param.

Return Codes

The epadmin command uses return codes to indicate success or failure. The return code values have these meanings:

Return code Meaning
0 The command succeeded on all target nodes.
‑1 The command failed on all target nodes.
1...n The command failed on a subset of nodes, where the returned value indicates the number of failing nodes.

Command Output Format

epadmin commands return results by default as rows of text, or optionally as tabular data.

Use the --delimiter global parameter to specify a character to serve as a column separator (The default is "|"), which enables the tabular data option. Tabular data consists of rows and columns. The first row in a result set contains the column names, while subsequent rows return the data. Each tabular result set has a fixed number of columns.

Use the --schema global parameter with --delimiter to return the data type of each column in a row of integers. The integers resolve to data types as shown in the following table.

Value Data Type
1 boolean
2 double
3 int
4 long
5 string
6 timestamp

For example, the default output of the display availability command is like the following example: 

$ epadmin --servicename="A2.sbuser" display availabilityzone
[A2.sbuser] Availability Zone = default-cluster-wide-availability-zone
[A2.sbuser] Data Distribution Policy = default-dynamic-data-distribution-policy
[A2.sbuser] Data Distribution Policy Type = Dynamic
[A2.sbuser] Quorum State = Not Enabled
[A2.sbuser] Rebalances Requested on Node = 1
[A2.sbuser] Rebalances Executed on Node = 1
[A2.sbuser] Re-balancing on Node = false
[A2.sbuser] Last Rebalance on Node = Sep 6 2024 07:35:26 AM PDT
[A2.sbuser] Last Rebalance Duration = 0 minutes 0 seconds 62 milliseconds
[A2.sbuser] Primary Nodes = A1.sbuser,A2.sbuser
[A2.sbuser] Backup Nodes = 
[A2.sbuser] Primary Node Pattern = .*
[A2.sbuser] Backup Node Pattern =

The same command in tabular form: 

$ epadmin --servicename="A2.sbuser" --delimiter=" | " display availabilityzone
[A2.sbuser] | Availability Zone | Data Distribution Policy | Data Distribution Policy Type | Quorum State
            | Rebalances Requested on Node | Rebalances Executed on Node | Rebalancing on Node
            | Last Rebalance on Node | Last Rebalance Duration | Primary Nodes | Backup Nodes
            | Primary Node Pattern | Backup Node Pattern | 
[A2.sbuser] | default-cluster-wide-availability-zone | default-dynamic-data-distribution-policy | Dynamic | Not Enabled
            | 1 | 1 | false
            | Sep 6 2024 07:35:26 AM PDT | 0 minutes 0 seconds 62 milliseconds | A1.sbuser,A2.sbuser | 
            | .* |  |

The same tabular output, including a data type schema: 

$ epadmin --servicename="A2.sbuser" --delimiter=" | " --schema display availabilityzone
[A2.sbuser] | Availability Zone | Data Distribution Policy | Data Distribution Policy Type | Quorum State
            | Rebalances Requested on Node | Rebalances Executed on Node | Rebalancing on Node
            | Last Rebalance on Node | Last Rebalance Duration | Primary Nodes | Backup Nodes
            | Primary Node Pattern | Backup Node Pattern | 
[A2.sbuser] | 5 | 5 | 5 | 5 | 4 | 4 | 1 | 5 | 5 | 5 | 5 | 5 | 5 | 
[A2.sbuser] | default-cluster-wide-availability-zone | default-dynamic-data-distribution-policy | Dynamic | Not Enabled
            | 1 | 1 | false
            | Sep 6 2024 07:35:26 AM PDT | 0 minutes 0 seconds 62 milliseconds | A1.sbuser,A2.sbuser | 
            | .* |  |

Secure Shell

The epadmin command provides administrative access to nodes running on both local and remote hosts. A few of its commands sent to nodes running on remote hosts are executed using Secure Shell (SSH) connections. SSH is a system that provides authentication and confidentiality for network connections to remote hosts.

epadmin uses SSH when there is no node coordinator running on the remote node. To be precise, the following epadmin commands attempt to use SSH when the ‑‑hostname global parameter specifies a non-local host:

epadmin install node
epadmin start node with the --installpath command parameter
epadmin remove node with the --installpath command parameter
epadmin getadminport node with the --installpath command parameter

The ability to use SSH to log into a given host depends on the configuration of that host's SSH daemon. Most servers are configured to require public and private key pairs, and might disallow password-only connections. If your remote machine does not allow password authentication, then you must have SSH public and private keys established on both local and remote machines. Before attempting one of the epadmin commands above, make sure your operating system username can log into to the server with the ssh command. If ssh allows the connection, these commands can work without a TrustedHosts configuration.

Note that there is no native SSH Server for Windows 10 or Windows Server, so the above epadmin commands with hostname parameters pointing at a Windows machine are likely to fail with a connection refused message. It is possible to configure an OpenSSH server from Cygwin or Windows Services for Linux. However, configuring SSH and troubleshooting SSH connections are beyond the scope of this document. Consult your local network administrator or web resources for assistance in setting up SSH keys on both local and remote machines.

Help System

The epadmin command has extensive documentation and built-in usage help, as described in Help System for epadmin.

SEE ALSO

epadmin-globals(1), Target Categories, epadmin-adapter(1), epadmin-application(1), epadmin-artifact(1), epadmin-authentication(1), epadmin-availabilityzone(1), epadmin-breakpoint(1), epadmin-cache(1), epadmin-cluster(1), epadmin-configuration(1), epadmin-connection(1), epadmin-container(1), epadmin-dynvar(1), epadmin-engine(1), epadmin-globaltransaction(1), epadmin-history(1), epadmin-logging(1), epadmin-metric(1), epadmin-node(1), epadmin-object(1), epadmin-operator(1), epadmin-partition(1), epadmin-password(1), epadmin-playback(1), epadmin-querytable(1), epadmin-realm(1), epadmin-record(1), epadmin-router(1), epadmin-secret(1), epadmin-secret(1), epadmin-services(1), epadmin-snapshot(1), epadmin-statistics(1), epadmin-stream(1), epadmin-systemservice(1), epadmin-trusted(1), epadmin-tunable(1), epadmin-user(1), epadmin-version(1), epadmin-web(1)