sburi
StreamBase URI format — Describes the StreamBase URI format and its shortcut forms.
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=username
;password=password
]
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).
-
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
-
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
-
Import the client certificate (here named
) into the server's trustStore:Client.cer
keytool -import -alias "normaluser" -file Client.cer -keystore server.keystore -keypass 123abc -storepass 123abc
-
Import the server certificate (here named
) into the client's trustStore:Server.cer
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 issb://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.