SessionPropertiesHost Property

The IPv4 or IPv6 address or host name to connect to. Multiple host entries separated by commas (up to sixteen) are allowed. With multiple entries, each is tried in turn until one succeeds.

Host entry

Host contains one or more host entries (up to sixteen). The host entry may also include an optional ProxyHost configuration, separated from the message router configuration by a percent (%) sign. A host entry has the following form:

[Protocol:]Host[:Port][%ProxyService]

Protocol is the protocol used for the transport channel. The valid values are:

• tcp - use a TCP channel for communications between the application and its peers. If no protocol is set, tcp is used as a default.
• tcps - use a SSL channel over TCP for communications between the application and its peers. The encryption with compression is not supported.
• http - use HTTP channels or a WebSocket channel over TCP for communications between the application and its peers. Web Messaging with compression is not supported.
• https - use HTTP channels or a WebSocket channel over SSL for communications between the application and its peers. Web Messaging with compression is not supported.

Host is the IPv4 or IPv6 address or host name to connect to for a connection. IPv6 addresses must be enclosed in brackets ([])

Port is the port to connect to for a connection. A value is only required when using a port other than the automatically assigned default port number. The default port for TCP is 55555 when compression is not in use, or 55003 when compression is in use. The default port for SSL is 55443.

ProxyService is a description of the non-transparent proxy. If it is necessary to configure the proxy server that is used to connect to the message router, then the proxy server is configured in the ProxyService string. The ProxyService string format is specified as:

[ProxyProtocol]://[username:password@]proxyHost[:proxyPort]
ProxyProtocol is 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)

If authentication is required for the proxy server, the username and password may be optionally specified before the proxy host.

proxyHost is the IPv4 or IPv6 address or host name of the proxy server.

proxyPort is the port to connect to for a connection. If the port number is not specified, the default for SOCKS5 is port 1080, and the default for Http-Connect is port 3128.

The following examples show how to specify transport channel types. Unless it is otherwise specified, the default port 55555 is used.

1. 192.168.160.28 - connect to IP address 192.168.160.28 over TCP.
2. [fe80::1] - connect to IPV6 address fe80::1 and the default port 55555 over TCP.
3. tcp:192.168.160.28 - connect to IP address 192.168.160.28 over TCP.
4. tcps:192.168.160.28 - connect to IP address 192.168.160.28 and port 55443 over SSL over TCP.
5. tcps:[fe80::1] - connect to IPV6 address fe80::1 and the default port 55443 over SSL over TCP.
6. tcp:192.168.160.28:44444 - connect to IP address 192.168.160.28 and port 44444 over TCP.
7. tcp:[fe80::1]:44444 - connect to IPV6 address fe80::1 and port 44444 over TCP.
8. http://192.168.160.28 - connect to IP address 192.168.160.28 and the default port 80 over HTTP or WebSocket over TCP.
9. https://192.168.160.28 - connect to IP address 192.168.160.28 and the default port 443 over HTTP or WebSocket over SSL over TCP

The following examples show how to connect to a message router through a proxy server.

1. 192.168.160.28%socks5://192.168.1.1 - connect to message router at 192.168.160.28 through a SOCKS5 proxy server at 192.168.1.1.
2. 192.168.160.28%httpc://192.168.1.1 - connect to message router at 192.168.160.28 through a HTTP-Connect proxy server at 192.168.1.1.
3. tcps:solace.company.com%socks5://User:PassWord@proxy.company.com:13128 - connect to message router at solace.company.com using SSL over TCP through a SOCKS5 proxy server at proxy.company.com, port 13128. Authenticate with the proxy server using username User and password PassWord.
4. tcp://192.168.160.27:44444%httpc://proxy.company.com:11080 - connect to the message router at 192.168.160.28, port 44444, using HTTP Connect through the proxy server at proxy.company.com, port 11080.
5. [fe80::1]\%socks5://[fe80::2] - connect message router at [fe80::1] through a SOCKS5 proxy server at [fe80::2].

Configuring Multiple Hosts for Redundancy and Failover

Some applications might want to have a list of appliances available for connection. Typically these appliances will be in separate geographic locations and use of a host list allows applications to fail over to the alternate connections if the first appliance is unavailable. The host list is configured in the Host property of SessionProperties as a comma separated list of hosts. Each host can optionally include a port number as well. For example, if there are two appliances at 192.168.160.128 and 192.168.160.129, but the second is using the non-default port 50005 for the message bus, the SessionProperties.Host would be configured as:

SessionProperties.Host = "192.168.160.128,192.168.160.129:50005"

In this case, when Connect is called, the API attempts to connect, first to 192.168.160.128, if that connection fails for any reason it attempts to connect to 192.168.160.129:50005. This process is repeated until all entries in the host list are attempted. After each entry has been attempted, if all fail, the session properties ConnectRetries and ReconnectRetriesWaitInMsecs determine the behavior of the API. If ConnectRetries is non-zero, SolClient waits for ReconnectRetriesWaitInMsecs milliseconds then starts connection attempts again from the beginning of the list.

If an established session fails, to any host in the list, when ReconnectRetries is non-zero, then API automatically attempts to reconnect, starting at the beginning of the list. Note that the session connect timer, ConnectTimeoutInMsecs, runs separately for each connection attempt. So an application waiting for a connection established UpNotice or connection failure ConnectFailedError could have to wait up to ( (number of hosts in the hosts list) times (ConnectTimeoutInMsecs) ) for the event.

Multiple Hosts and Guaranteed Messaging

If a client application publishes Guaranteed messages ( NonPersistent or Persistent ) and then a disconnect occurs, the API will automatically reconnect to other listed hosts. However, because another host will not know the state of the publisher flow to the original host, the API must reset publisher flow state. Unacknowledged messages are renumbered and resent by the API. If the alternate router is configured as a replication site this may lead to duplicate messages in the system. It is up to the application to resolve this duplication in what ever way is appropriate to the application.

Applications may wish to configure the session so that auto-reconnect only occurs if no guaranteed messages have been published. This is the legacy behaviour of the API. If this is desired the set the session property GdReconnectFailAction to the value DISCONNECT. This session property can also be set as environment variable which then allows legacy applications to run without modification or recompile.

May be set as an environment variable. (see SessionProperties)

Default: empty string

public string Host { get; set; }