sburi

StreamBase URI format — Describes the StreamBase URI format and its shortcut forms.

SYNOPSIS

sburi

DESCRIPTION

A StreamBase URI references an instance of StreamBase Server, or references containers running on the server. Most StreamBase command line utilities address their target server with the -u option, which takes a StreamBase URI. You might also use StreamBase URIs when specifying container connections, or when programming StreamBase client applications.

Important

For StreamBase clients that communicate over an SSL connection, instead of sb:// use the sbs:// protocol, which requires authentication via certificates. For details, see SSL Authentication.

The format of the StreamBase URI is:

sb://[host][:port][/container][;user=xxx;password=yyy]

The following example uses the StreamBase defaults for host, port, and container:

sb://localhost:10000/default;user=sbuser;password=secret

The simplest version of the default URI is used as a default in StreamBase Studio and for all StreamBase utilities:

sb://localhost

See URI Shortcuts for a list of the default values assumed if not specified.

The following example addresses a container named holdingcell running on a remote server that does not require authentication:

sb://streamhost:9900/holdingcell

When using the –u option to specify a URI for a StreamBase command line utility, a space between the –u and the URI is optional. Exception: When used with the jsbc, jsbadmin, and jsbclientgen commands, you cannot have a space after the –u (or –p). Thus, the following commands are all in correct form, and produce the same results:

sbc -u sb://localhost:9900/ha list
sbc  -usb://localhost:9900/ha list
jsbc -usb://localhost:9900/ha list

If you have a non-default URI you use often, you can set it in the STREAMBASE_SERVER environment variable in lieu of typing it every time on the command line. See the Environment section below.

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:

  • javax.net.ssl.trustStore=TrustStorePathName

  • javax.net.ssl.trustStorePassword=TSPassword

  • javax.net.ssl.keyStore=ClientStorePathName

  • javax.net.ssl.keyStorePassword=CSPassword

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

Example: Two-Way SSL Using Self-Signed Certificates

Note

The keytool command is available from the java\bin directory of the JDK available with the StreamBase installation. Run keytool from the same Java version you use to run sbd.

The following commands should be issued on a single line. In the example, line breaks were added for readability).

  1. Set up the keystore on machine 1, the server:

    cd C:\Temp
    keytool -genkeypair -dname "cn=localhost" -alias "normaluser"
            -keypass cl123abc -keystore client.keystore
            -storepass cl123abc -validity 365
    keytool -export -keystore client.keystore -alias "normaluser"
            -file Client.cer -storepass cl123abc
    
  2. Set up the keystore on machine 2, the client:

    cd C:\Temp
    keytool -genkeypair -dname "cn=localhost" -alias "normaluser"
            -keypass cl123abc   -keystore client.keystore
            -storepass cl123abc -validity 365 
    keytool -export -keystore client.keystore -alias "normaluser"
            -file Client.cer -storepass cl123abc
    
  3. Import the client certificate (here named Client.cer) into the server's trustStore:

      keytool -import -alias "normaluser" -file Client.cer
              -keystore server.keystore -keypass 123abc -storepass 123abc
    
  4. Import the server certificate (here named Server.cer) into the client's trustStore:

      keytool -import -alias "server" -file Server.cer
              -keystore client.keystore -keypass cl123abc -storepass cl123abc
    

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:

  • The default host is localhost.

  • The default port is 10000.

  • The default container is named default.

  • An empty container string selects the default container.

  • The default authentication parameters are none. This means that, by default, the server is presumed to not require authentication.

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.

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.