Session Properties Required to Establish a Connection
When a session is created, default values are assigned to its settings, but can be modified if required. How to modify the following settings are explained in this section.
For a complete list of session properties, valid parameters, and the default values, see the PubSub+ Messaging APIs documentation for the appropriate PubSub+ Messaging API.
Related Samples
- For the PubSub+ Java RTO API, PubSub+ C API, and PubSub+ .NET API
- For the PubSub+ JavaScript API and PubSub+ Node.js API
For an example of how to define the required session properties when using a basic authentication scheme, which is the default, see the DirectPubSub
sample. Although other PubSub+ Messaging API samples make use of common code, the DirectPubSub
sample explicitly includes the methods used to create session properties and create a session.
See the TopicSubscriber
and TopicPublisher
samples.
Authentication Scheme
When a host event broker initially accepts a connection from a client, that connection is in an unauthenticated state, and the event broker cannot process any requests from the client until the connection is authenticated.
The authentication scheme specifies the credentials that a client will use to authenticate its connection to the event broker. The authentication scheme can be one of the following:
- Basic authentication
- Client certificate authentication
- Kerberos authentication
-
OAuth Authentication
A client authentication scheme that allows a client application to use OAuth to authenticate its connection with event brokers. You can use either OAuth2 or OIDC tokens. For more information, see OAuth Authentication
The default client authentication scheme; it allows a client to authenticate with an event broker using a valid client username and password. For more information, see Basic Authentication.
A client authentication scheme that allows a client to prove its identity to the event broker through an X509v3 client certificate. This authentication scheme also requires the client to use a secure connection. For more information, see Client Certificate Authentication.
A client authentication scheme that uses Kerberos to authenticate a connecting client using a ticket that the client obtains through an approved ticket granting service (TGS). For more information, see Kerberos Authentication.
All of these client authentication schemes require explicit input to successfully authenticate a client. For more information, see Defining Client Authentication Info.
The PubSub+ JavaScript API and PubSub+ Node.js API don't support all authentication schemes. The PubSub+ JavaScript API supports only basic and OAuth authentication, and the PubSub+ Node.js API supports basic, client certificate, and OAuth authentication.
Client Name
When connecting a session to an event broker, a unique client name is required to register that particular client with the event broker. If no client name is entered, the API automatically generates a unique client name. By default, this parameter is not specified.
The client name is also used to uniquely identify the sender in a message’s senderId
field when the session property to generate a sender ID is set.
The client name property is the same as the client
property that can be displayed through the Solace CLI or SolAdmin.
When the session property to generate a sender ID is set, the client name is included the message’s senderId
field to uniquely identify the sender.
PubSub+ Messaging API | Use |
---|---|
PubSub+ Java RTO API |
|
PubSub+ C API |
|
PubSub+ .NET API |
|
PubSub+ JavaScript API and PubSub+ Node.js API |
|
Host
The host event broker to connect or reconnect the Session to. An application can connect directly to a host event broker in one of the following ways:
- Connecting Directly to Host Event Brokers
- Connecting to Host Event Broker Through Proxies in the PubSub+ Java RTO API, PubSub+ C API, PubSub+ .NET API, and PubSub+ JavaScript API
Connecting Directly to Host Event Brokers
To connect to a session directly to an event broker use a host entry composed as follows:
[Protocol:]Host[:Port]
Where:
Protocol
is the protocol used for the transport channel. The valid values are:- For the PubSub+ Java RTO API, PubSub+ C API, and PubSub+ .NET API the valid values are:
tcp:
ortcp://
—Use a TCP channel for communications between the application and the event broker. If no protocol is set, TCP is used by default.tcps:
ortcps://
—Use a TLS/SSL channel over TCP for secure communications between the application and the event broker.ws:
orws://
—Use a WebSockets transport for communication between the application and the event broker.wss:
orwss://
—Use a TLS/SSL channel over WebSockets for secure communication between the application and the event broker.- In addition to the above for the PubSub+ Java RTO API, PubSub+ C API, and PubSub+ .NET API, and only for the PubSub+ JavaScript API and PubSub+ Node.js API the valid values are:
http:
orhttp://
—Use Hypertext Transfer Protocol (HTTP) for communication between the application and the event broker.https:
orhttps://
—Use a TLS/SSL channel over HTTP for secure communication between the application and the event broker.Host
is one or more IP addresses or hostnames of event brokers to connect to.- Up to 16 potential hosts to connect or reconnect to can be listed in a comma‑separated list. Listing more than one host allows a client to attempt to connect or reconnect to alternate hosts should the first event broker be unavailable. Connect or reconnect attempts are made to the hosts in the order in which they are presented in the list. The listed host event brokers may be in separate geographic locations.
- When event brokers are operating in high-availability (HA) redundant pairs, do not list both event brokers in the pair as hosts. The redundant pair use the same IP address for the connection, so they appear as one event broker to the PubSub+ Messaging API.
- The connect and reconnect behavior of a client is controlled by the channel or session properties used for its connection with the event broker. Its reconnect behavior is also affected by whether the client application is publishing Guaranteed messages. For more information, see Connect Retries Per Host.
- In a Windows environment, a fully qualified domain name (FQDN) should be used for the host parameter, and it must match the FQDN that the event broker uses for the Kerberos Service Principal Name (SPN).
Port
is the port number to use to establish the connection.- A value is only required when the client needs to use a port other than the automatically‑assigned default port number. The default port number for TCP is 55555 when compression is not in use, or 55003 when compression is in use. The default port for TLS/SSL is 55443, and you use the same port if you use TLS with compression. The default port numbers for:
http/ws
is 80 for appliances or 8008 for software event brokershttps/wss
is 443 for appliances or 1443 for software event brokers
Examples:
The following examples show how to connect directly to an event broker. Unless it is otherwise specified, the default port 55555 is used.
192.168.160.28
—Connect to IP address 192.168.160.28 over TCP.dev212
— Connect to hostnamedev212
over TCP.dev212.solacesystems.com
—Connect to hostnamedev212.solacesystems.com
over TCP.tcp:192.168.160.28
—Connect to IP address 192.168.160.28 over TCP.tcps:192.168.160.28
—Connect to IP address 192.168.160.28 and port 55443 with TLS/SSL over TCP.tcp:192.168.160.28:65535
—Connect to IP address 192.168.160.28 and port 65535 over TCP.
When a SPN is generated for the client, the following format is used: service_name/<customer-provided_host>@REALM
. The service name portion is configured through the KRB service name session property (by default, it is solace
), and the realm portion is determined by the KRB library’s configuration files. An example of a resulting service principle name is solace/dev212@SIMPLESPNEXAMPLE.COM
.
When using multiple hosts, the host used for the current connection generates the SPN.
Connecting to Host Event Broker Through Proxies in the PubSub+ Java RTO API, PubSub+ C API, PubSub+ .NET API, and PubSub+ JavaScript API
To connect to an event broker through an HTTP or SOCKS protocol version 5 proxy server the configured host setting must include those parameters required for a standard, direct connection to an event broker, but it must also include a proxy service string:
[Protocol:]Host[:Port][%ProxyService]
Where:
ProxyService
—The proxy server that is used to connect to event broker. The proxy service string format is specified as:
[ProxyProtocol]://[username:password@]proxyHost[:proxyPort]
Where:
ProxyProtocol
—The protocol used to communication with the proxy server. The valid values are:socks5
—Connect to the server with the SOCKS protocol version 5, RFC 1928 (IETF standards track document).httpc
—Connect to the server with the HTTP connect protocol, RFC 2817 (IETF standards track document).
username:password@
—If authentication is required for the proxy server, the username and password may be specified before the proxy host.proxyHost
—The IP address (or hostname) of the proxy server.proxyPort
—The port to connect to for a connection. If the port number is not specified, the default is port 1080 for SOCKS5 and port 3128 default for HTTP connect.
Examples:
The following examples show how to connect to an event broker through a proxy server.
192.168.160.28%socks5://192.168.1.1
—connects to an event broker at 192.168.160.28 through a SOCKS5 proxy server at 192.168.1.1.192.168.160.28%httpc://192.168.1.1
—connects to an event broker at 192.168.160.28 through an HTTP-Connect proxy server at 192.168.1.1.tcps:solace.company.com%socks5://User:PassWord@proxy.company.com:13128
—connect to an event broker atsolace.company.com
using SSL over TCP through a SOCKS5 proxy server atproxy.company.com
, port 13128. Authenticate with the proxy server using usernameUser
and passwordPassWord
.http://192.168.160.28:44444%httpc://proxy.company.com:11050
—connect to the event broker at 192.168.160.28, port 44444, using HTTP. Connect through the proxy server at proxy.company.com, port 11050.
PubSub+ Messaging API | Use |
---|---|
PubSub+ Java RTO API |
|
PubSub+ C API |
|
PubSub+ .NET API |
|
PubSub+ JavaScript API and PubSub+ Node.js API |
|
Local Host
The hostname or IP address of the machine on which the application is running. This session property may be required when the application is running on a multi‑homed machine.
On a multi-homed machine, a local hostname or IP address helps ensure that the API uses the correct network interface for communication with the event broker.
PubSub+ Messaging API | Use |
---|---|
PubSub+ Java RTO API |
|
PubSub+ C API |
|
PubSub+ .NET API |
|
PubSub+ JavaScript API and PubSub+ Node.js API |
Not applicable |
Message VPN
The name of the message VPN on the host event broker to connect the client to.
Message VPNs are created on the event broker to provide isolation between groups of clients connecting to PubSub+.
If a specific message VPN is not provided, the message VPN named default
is used. The default
message VPN is always present on an event broker. Although a network administrator can change the configuration settings for default
, it cannot be deleted.
PubSub+ Messaging API | Use |
---|---|
PubSub+ Java RTO API |
|
PubSub+ C API |
|
PubSub+ .NET API |
|
PubSub+ JavaScript API and PubSub+ Node.js API |
|
Web Transport Protocol for PubSub+ Java RTO API, PubSub+ C API or PubSub+ .NET API
Client applications using the PubSub+ Java RTO API, PubSub+ C API or PubSub+ .NET API can use a web transport for a session. Web transport is not available for the PubSub+ JMS API.
The C session property SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL
specifies a web transport protocol in the default web transport protocol downgrade list to use for the session connection. For more information, see Web Transport Protocols.
If an attempt to connect a session with a given transport protocol fails, the API automatically retries with a less-efficient transport protocol. For example, if HTTP_BINARY_STREAMING
is selected, but a connection cannot be established, HTTP_BINARY
is then attempted. The time in milliseconds between transport protocol connection attempts can be specified with the SOLCLIENT_SESSION_PROP_TRANSPORT_PROTOCOL_DOWNGRADE_TIMEOUT_MS
property. By default, the API uses the best available web transport protocol.
Solace recommends leaving SESSION_TRANSPORT_PROTOCOL_DOWNGRADE_TIMEOUT_MS
at its default value of 3000 and setting SESSION_RECONNECT_RETRY_WAIT_MS
to 10000. These settings allow a client to attempt to connect to each protocol type in turn before a reconnect attempt occurs.
A client may instead specify a comma-separated list of transport protocols using the SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL_LIST
property. If a connection attempt fails and a list is specified, the API will automatically retry the connection with the next protocol in the list.
To disable auto-negotiation of the transport protocol, a client may specify a single protocol to use for SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL_LIST
.
Web Transport Protocol for PubSub+ Messaging API for JavaScript and Node.js
For the PubSub+ JavaScript API, the solace.sessionProperties.webTransportProtocolList
property defines the possible web transport protocols to use. For more information about the Web transport Protocols, see Web Transport Protocols.
Guaranteed messaging support requires the use of the WS_BINARY protocol. Guaranteed messaging is automatically disabled if any other protocol support is enabled.
The PubSub+ Node.js API supports only the WS_BINARY web transport protocol.
The PubSub+ JavaScript API with version 7 API behavior profile supports all transport protocols by default. In addition, the behavior profile enables the API to automatically retry a connection attempt with a less-efficient transport protocol if the initial attempt fails. For example, if WS_BINARY
is selected, and a connection cannot be established, HTTP_BINARY_STREAMING
is then attempted. The table below shows the transport protocol that each Web API supports. For more information about the PubSub+ JavaScript API and PubSub+ Node.js API behavior profiles, see Initializing and Monitoring APIs.
Guaranteed Messaging over WebSockets
The PubSub+ Java RTO API, PubSub+ C API, and PubSub+ .NET API allow users to perform guaranteed messaging over WebSockets.
PubSub+ Messaging API | Minimum API Version | Property Name |
---|---|---|
PubSub+ Java RTO API |
7.14.0.8 or newer |
|
PubSub+ C API |
7.14.0.8 or newer |
|
PubSub+ .NET API |
10.9.0 or newer |
|