Authentication Parameters

The user and password parameters are only necessary if you are communicating with a StreamBase Server instance that has StreamBase authentication enabled. For example:

sb://streamhost:9900/holdingcell;user=rose;password=nuh-UH

When specifying authentication parameters at the UNIX shell prompt, enclose the URI in quotes to escape the shell's interpretation of the semicolon:

"sb://streamhost:9900/holdingcell;user=rose;password=nuh-UH"

SSL Authentication

To connect to a StreamBase server over SSL, you must use the sbs:// protocol. For jsbc and custom Java clients, the client JVM requires the following Java system properties:

The sbs:// protocol requires setting up two-way SSL, in which the certificates for the initiator of the connection and the recipient must be imported into the other's trustStore. Therefore, include the server's certificate in the client's trustStore and the client's certificate in the server's trustStore. The sbs:// protocol cannot be used for one-way SSL.

Configure access to the local trustStore for command-line Java utilities in this manner, substituting actual filenames and passwords (line breaks added for readability):

jsbc -J-Djavax.net.ssl.trustStore=C:/Temp/client.keystore 
     -J-Djavax.net.ssl.trustStorePassword=cl123abc 
     -J-Djavax.net.ssl.keyStore=C:/Temp/client.keystore 
     -J-Djavax.net.ssl.keyStorePassword=cl123abc 
     -usbs://localhost:10002;user=bob;password=secret deq OUT

In sbd.sbconf, access to the local trustStore when sbd initiates the connection additionally requires:

<java-vm>
    <sysproperty name="javax.net.ssl.trustStore" value="C:/Temp/client.keystore"/>
    <sysproperty name="javax.net.ssl.trustStorePassword" value="cl123abc"/>
    <sysproperty name="javax.net.ssl.keyStore" value="C:/Temp/client.keystore"/>
    <sysproperty name="javax.net.ssl.keyStorePassword" value="cl123abc"/>
</java-vm>

Lastly, when sbproxy is the recipient, configure access to the trustStore similar to the client (line breaks added for readability):

sbproxy -J-Djavax.net.ssl.trustStore=C:/Temp/server.keystore
        -J-Djavax.net.ssl.trustStorePassword=123abc
        -J-Djavax.net.ssl.keyStore=C:/Temp/server.keystore
        -J-Djavax.net.ssl.keyStorePassword=123abc
        -f proxy.sbconf 10002 localhost 10001

Remote Container Connection Parameters

When using a StreamBase URI as part of a stream-to-stream container connection string to specify that one side of the container connection is on a remote StreamBase Server, you can optionally specify parameters as part of the remote URI.

For example, you might specify a container connection with the source end of the connection on a remote server, and at the same time specify a reconnection interval of 30 seconds, using a container connection specification like the following:

boxA.instream1=("sb://remotehost:9900/boxB.outstr4;reconnect-interval=30000")

For more on the parameters usable with remote container connections, see Remote Container Connection Parameters.

URI Shortcuts

StreamBase URIs recognize defaults, which lets you enter a shortcut URI in many cases. Any unspecified portion of the URI defaults to the following:

Using the sbc list command for illustration, all of the following commands produce the same results for a server with all default settings:

sbc list
sbc -u sb://localhost list
sbc -u sb://localhost:10000 list
sbc -u sb://localhost:10000/ list
sbc -u sb://localhost:10000/default list
sbc -u :10000 list
sbc -u :10000/default list
sbc -u /default list
sbc -u / list

The following examples illustrate various combinations of default and non-default URI sections:

sbc -u :9900 list        (localhost, port 9900, default container)
sbc -u :9999/ha list     (localhost, port 9999, container named ha)
sbc -u /crosseng list    (localhost, port 10000, container named crosseng)

The following examples show several commands to access a remote server running on the default port, 10000. These commands all produce the same results:

sbc -u sb://streamhost:10000/default list
sbc -u sb://streamhost:10000 list
sbc -u sb://streamhost/default list
sbc -u sb://streamhost list

When using authentication parameters, at least one portion of the URI must be present. That is, you cannot specify only the authentication parameters by themselves, relying on all the URI defaults described above. You can, however, rely on partial defaulting when using authentication. For example:

sbc -u :10000;user=rose;password=nuh-UH      (Windows)
sbc -u ":10000;user=rose;password=nuh-UH"    (UNIX)
sbc -u /default;user=rose;password=nuh-UH    (Windows)
sbc -u "/default;user=rose;password=nuh-UH"  (UNIX)
sbc -u /;user=rose;password=nuh-UH           (Windows)
sbc -u "/;user=rose;password=nuh-UH"         (UNIX)

Most StreamBase utilities recognize the -p option in addition to -u. Use -p to specify only the port number, defaulting to host=localhost and the default container. The -p option is not supported for StreamBase applications that have authentication enabled. The following commands are equivalent:

sbc -p 9900 list
sbc -u :9900 list
sbc -u sb://localhost:9900 list

Multiple URI Syntax for HA Scenarios

Certain commands that accept StreamBase URIs can also accept a comma-separated list of URIs to address more than one StreamBase Server at the same time. The following example requests status information from two local server instances, one running on port 9900, the other on port 9901:

sbc -u sb://localhost:9900,sb://localhost:9901 status --verbose

You can address multiple servers running on separate hosts. The following example assumes that two server instances both have identical containers named app2 in which the running application has an input stream named instream3:

sbc -u sb://primary.example.com:10000,sb://secondary.example.com:10000 enqueue app2.instream3

The same command as above, using defaults for the port number:

sbc -u sb://primary.example.com,sb://secondary.example.com enqueue app2.instream3

You can use the URI shortcuts described above to specify multiple URIs. For example, to check the status of four server instances running on different ports on localhost, use a command like the following:

sbc -u :9900,:10000,:10099,:11000 status

In general, the multiple URI syntax is accepted by programs based on the StreamBaseClient API, including sbc, sbfeedsim, and any client applications you write. By contrast, programs based on the StreamBaseAdminClient API, including sbadmin, are expected to address a single server at a time for administration purposes, and do not accept the multiple URI syntax. For example, you can issue an sbadmin shutdown command only to one server at a time.

The STREAMBASE_SERVER environment variable supports a list of multiple URIs. When writing client code, use the StreamBaseURI.listFromEnvironment class instead of StreamBaseURI.fromEnvironment to make sure your code supports this feature.