sbadmin

StreamBase Administration Client — starts the StreamBase Administration Client

SYNOPSIS

sbadmin [OPTIONS] [COMMAND]

DESCRIPTION

The sbadmin command starts the StreamBase Administration Client, which lets you perform StreamBase administration tasks such as addContainer, suspend, resume, and shutdown.

You can optionally limit the use of sbadmin commands to certain designated user accounts by enabling a feature of StreamBase authentication. See the sbuseradmin reference page for more information.

Use the sbc command rather than sbadmin for non-administrative commands.

Suspending and Resuming

You can use sbadmin suspend to request suspension of an application, a container, an adapter, a Java operator, or an embedded adapter. However, not all StreamBase objects respond to a suspend request. If the specified target cannot be suspended, the command succeeds silently, but the specified target continues to run.

In general, embedded adapters supplied by StreamBase respond to suspend requests, while global operators and adapters supplied by StreamBase are not subject to suspension. The suspend and resume commands are best used with custom operators and adapters you write to extend StreamBase functionality, and for which you define suspend state behavior.

The container suspend state is a flag to which custom operators and adapters may respond, depending on how they are coded. Streams ignore the suspend state and instead respond to enqueue and dequeue STREAMSTATUS as set by sbadmin modifyContainer --enqueue= and --dequeue= commands, described below. Suspending a container applies the suspend state to all operators and adapters, but if there are none in the container that have a specific suspend state defined, then the application behavior does not change when receiving a suspend command.

Container Connections

You can set up connections between containers when you add a container with the addContainer command or when you modify existing containers with the modifyContainer addConnection command. Container connections can be one of the following types:

  • Stream-to-stream connections, where an output stream in one container connects to an input stream in another container. These can be asynchronous (default) or synchronous.

  • JMS-mediated connections, where an output stream in one container connects to a Java Messaging Service server, then an input stream in another container connects to the same JMS server. This is a stream-to-stream connection that passes through a JMS server to insure reliable delivery of messages.

  • CSV file connections, where an input or output stream in a container is connected to a URI specifying the path to a CSV file.

Note

The syntax for expressing all forms of container connections is always destination=source, like an assignment statement in some programming languages.

Stream-to-Stream Container Connections

Examples of stream-to-stream container connections: 

sbadmin addContainer A appA.ssql
sbadmin addContainer B appB.sbapp B.InputStream1=A.OutputStream1
sbadmin addContainer C appC.sbar  C.InputStream1=B.OutputStream1

Container connections can refer to containers on remote machines. In this case, surround the remote container URI in parentheses. For example: 

sbadmin addContainer B appB.sbapp \
    (sb://sbserver:10000/OutputStream1)=A.InputStream1
sbadmin addContainer C appC.sbar  \
    C.InputStream1=(sb://sbserver:10000/OutputStream1)

Container connections are asynchronous by default, and are set up with a queue to manage the flow of tuples. To specify a low-latency, direct-connected synchronous container connection, use := (colon-equals) instead of = (equals) in your container connection assignment statement. For example: 

sbadmin addContainer C appC.sbar  C.InputStream1:=B.OutputStream1

Read the cautions in Synchronous Container Connections in the Administration Guide before setting up synchronous container connections.

JMS Container Container Connections

You can optionally connect two streams in containers on separate servers, passing through your site's Java Messaging Service (JMS) infrastructure. This feature allows you to use the reliable delivery feature of JMS to ensure delivery of StreamBase tuples. To use this feature, specify two container connections: from StreamBase Server A to JMS and from JMS to StreamBase Server B. StreamBase supports JNDI-style JMS URIs, as described in Connecting Container Streams Through JMS. 

sbadmin -u sb://hostfirst:10000  addContainer A appA.sbapp \
    A.Outgoing=jms:jndi:jndi-name
sbadmin -u sb://hostsecond:10000 addContainer B appB.sbapp \
    jms:jndi:jndi-name=B.Incoming

CSV Container Connections

You can optionally connect an output stream in a container to a csvfile URI that specifies the absolute path to a CSV file. This is primarily used for debugging and analysis of your application. A CSV container connection has an advantage over dequeuing from an output stream: a CSV container connection starts working immediately on sbd startup (or on startup of the container). This means that even the first few tuples are captured in the specified CSV file. By contrast, it can take some time to start sbd, then start an sbc dequeue command, during which time you can miss the initial tuples. The following is an example CSV container connection to an output stream: 

sbadmin addContainer A appA.sbapp 
    csvfile://server.example.com/home/sbuser/logs/appA-output.csv=A.Outgoing

For paths on Windows machines, you must use the same URI syntax with forward slashes: 

sbadmin addContainer A appA.sbapp 
    csvfile://workstation.example.com/c/logs/appA-output.csv=A.Outgoing

CSV container connections also work with input streams. In this case, the stream is fed from the contents of the incoming CSV file, whose structure must exactly match the schema of the input stream. The following is an example of a CSV container connection with an input stream: 

sbadmin addContainer B appB.sbapp 
    B.Incoming=csvfile://workstation.example.com/c/sbapps/appB-input.csv

In your CSV file URI, you can optionally specify any connection option available in the CSV File Reader and Writer adapters. See Connecting Container Streams To a CSV File for details.

OPTIONS

-h, --help

Displays help for the specified command, then exits. For example, sbadmin shutdown -h.

-u uri

Specifies the URI of the StreamBase Server to communicate with. See the sburi page of the Reference Guide (or see sburi(5) at the UNIX shell prompt) for a discussion of the URI format and its shortcuts. The URI can also be set using the STREAMBASE_SERVER environment variable.

-p TCP-port

Specifies the port number on localhost for the StreamBase Server to communicate with. This is a shortcut alternative to specifying the full URI with -u in cases where the server is running on localhost but on a port other than the default 10000. Thus, the following lines are equivalent:

sbadmin -p 9900 listConnections

sbadmin -u sb://localhost:9900 listConnections

Note

The -p option is not supported for StreamBase applications that have authentication enabled or are using High Availability features.

-o filename

Redirects all non-error output to the specified file.

--version

Prints version information and exits.

COMMANDS

addContainer containerName { file.sbapp | file.ssql | file.sbar } [ containerName.stream=otherContainer.stream, ... ] [--enqueue=STREAMSTATUS] [--dequeue=STREAMSTATUS] [--suspend] [--moduleSearch=path] [--datadir=path] [args]

Adds a container to the running sbd server process, assigns the new container a name, and specifies an application file to run in the context of the new container. The application file formats accepted are EventFlow (extension sbapp), StreamSQL (ssql), and precompiled archive (sbar). For more on precompiled StreamBase application files, see sbargen and Precompiled Application Archives.

When adding containers, you can optionally specify a connection between a stream in the container you are adding to a stream in an existing container, as described in Container Connections.

You can optionally enable or disable enqueuing or dequeuing to the container on startup. This changes the enqueue or dequeue status for in-process adapters and for enqueue and dequeue clients. The STREAMSTATUS values can be:

  • ENABLED. This is the default.

  • DISABLED. The enqueue or dequeue will actively refuse any enqueue or dequeue requests, and throw an exception.

  • DROP_TUPLES. The enqueue or dequeue will silently drop tuples.

Use --suspend to specify that the application in this container should start up suspended. You can start a suspended container with the sbadmin resume command.

Use --moduleSearch to specify an absolute or relative path to a directory containing StreamBase application files that are called by this container's application as modules.

Use --datadir to specify an absolute or relative path to a directory to be used by this container to hold the files that implement disk query tables for the application in this container.

Relative paths for --datadir and --moduleSearch are relative to the runtime location of the sbd server, which is likely to be different between development and deployment environments. For maximum portability, specify full absolute paths.

getLeadershipStatus

Returns one of the strings LEADER or NON_LEADER to describe the leadership status of the specified StreamBase Server.

getOperatorProperty operatorName [propertyName]

Displays a property or all properties for the named Java operator or embedded adapter. Optionally you can request information about a specific property; otherwise, StreamBase displays all properties for the Java operator or embedded adapter.

If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java operator or embedded adapter with the appropriate container name. For example:

sbadmin getOperatorProperty containerB.MyJavaOperator

killAllConnections

Disconnects all connections from the sbd server.

killConnection connection-id

Disconnects the specified connection.

listConnections

Lists all active client connections to the running StreamBase Server (sbd). For each connection, the display shows:

  • The connection ID. (Use this ID with the killConnection command.)

  • Client and server host and port numbers.

  • The names of subscribed streams, if any.

  • The number of tuples currently dequeued and enqueued.

For example: 

id=98F934109DD88177CEFF4E32051B4D00; peer=127.0.0.1:48358; local=127.0.0.1:10000; 
  dequeued=0; enqueued=17
id=FBD7C02E88E0C43CE09E48BD790F086A; peer=127.0.0.1:48350; local=127.0.0.1:10000; 
  memory=12288; subscriptions=OutputStream1,OutputStream2,OutputStream3; 
  dequeued=34; enqueued=0
modifyContainer container-name [addConnection | removeConnection] [--enqueue=STREAMSTATUS] [--dequeue=STREAMSTATUS] [args ...]

Adds or removes a container connection to a running container and/or changes the enqueue or dequeue status of a container. The container connection syntax for the addConnection subcommand are the same as for the addContainer command described in Container Connections above, including support for containers on remote servers. The values for STREAMSTATUS are the same as for the addContainer command above.

removeContainer containerName

Removes the specified container from the running sbd server process. If the StreamBase applications in the server process are connected (for example, if the output stream of one container is the input stream of another container), remove the containers using the reverse order in which they were added to the server.

restart [ operatorName1 [ operatorName2 ... ] ]

Restarts one or more Java operators or embedded adapters in a server process that were previously stopped with the shutdown command. You can separate multiple entities with a space.

If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java operator or embedded adapter with its container name. For example:

sbadmin restart containerB.MyJavaOperator

resume [ containerName | operatorName1 [ operatorName2 ... ] ]

Resumes a suspended StreamBase application, container, Java operator, or embedded adapter. You can separate multiple entities with a space.

If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java operator or embedded adapter with its container name. For example:

sbadmin resume containerB.MyJavaOperator

setLeadershipStatus [ NON_LEADER | LEADER ]

Changes the leadership status of the specified StreamBase Server as a member of a high availability cluster. LEADER is the default status on server startup. Changes in leadership status are announced on the system.control stream of the server.

setOperatorProperty operatorName propertyName value

Sets a property value for the specified Java operator or embedded adapter. Use sbadmin getOperatorProperty to see the list of properties for a Java operator or an embedded adapter. If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java operator or embedded adapter with its container name.

shutdown [ containerName | operatorName1 [ operatorName2 ... ] ]

Shuts down one or more StreamBase applications, containers, Java operators, or embedded adapters. You can separate multiple entities with a space.

If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java operator or embedded adapter with its container name. For example:

sbadmin shutdown containerB.MyJavaOperator

suspend [ containerName | operatorName1 [ operatorName2 ... ] ]

Suspends a running StreamBase application, container, Java operator, or embedded adapter. You can separate multiple entities with a space. If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java operator or embedded adapter with its container name. For example:

sbadmin suspend containerB.MyJavaOperator

The specified target silently accepts the suspend command, but not all StreamBase objects can be suspended, as described above in Suspending and Resuming.

[sbc commands]

For convenience, the sbadmin command also accepts all the sbc commands, as listed in the sbc reference page, including status, list, enqueue, dequeue, describe, and typecheck. In a deployment that uses the StreamBase user administration system to restrict access to the sbadmin command, this feature allows authorized administrators to run the sbc commands with administrative rights.

Note

When invoking one of the sbc command's subcommands, the sbadmin -u option accepts a comma-separated list of URIs, where each URI specifies a different StreamBase Server in a high availability cluster. See the sburi page in the Reference Guide for details.

FILES

There is no configuration file for sbadmin. Enabling or changing the StreamBase authentication setting for sbadmin commands is done by editing the sbd.sbconf configuration file, which contains an authentication section.

ENVIRONMENT

STREAMBASE_SERVER

Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default StreamBase URI for StreamBase commands that take the –u option. If set, commands use the URI in this variable, overriding their built-in default URI, which is sb://localhost:10000. If this variable is set, you must use the –u option to communicate with any server other than the one specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.

STREAMBASE_LOG_LEVEL

Optional. Sets the minimum severity of messages that StreamBase writes to syslog or stderr. Default is 0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to the standard messages), and 2 (which adds DEBUG messages).

SEE ALSO

sbc
sbd
syslog(3)