Understanding Solace Messaging Credentials

This topic describes the credentials that an application bound to a Solace Messaging service instance gains access to. These credentials are stored in the VCAP_SERVICES environment variable. For examples of different ways that developers can configure their applications to consume the credentials, see the sample application GitHub repository.

Example Environment Variable

The VCAP_SERVICES environment variable is a JSON document, and follows the format of the example below:

{
  "VCAP_SERVICES": {

  "solace-messaging": [
   {
     "label": "solace-messaging",
     "name": "solace-medium-ha-1",
     "plan": "medium-ha",
     "provider": null,
     "syslog_drain_url": null,
     "tags": [
       "solace",
       "solace-messaging",
       "rest",
       "mqtt",
       "mq",
       "queue",
       "event-streaming",
       "amqp",
       "jms",
       "messaging",
       "publish-subscribe",
       "message-queuing",
       "request-reply"
     ],
     "volume_mounts": [],
     "credentials": {
       "clientPassword": "4a80bf1c-4b70-4469-90e0-2c3c10e6ee28",
       "clientUsername": "v001.cu000093",
       "msgVpnName": "v001",
       "jmsJndiUris": [
         "smf://192.168.101.17:7000",
         "smf://192.168.101.16:7000"
       ],
       "jmsJndiTlsUris": [
         "smfs://192.168.101.17:7003",
         "smfs://192.168.101.16:7003"
       ],
       "mqttUris": [
         "tcp://192.168.101.17:7008",
         "tcp://192.168.101.16:7008"
       ],
       "mqttTlsUris": [
         "ssl://192.168.101.17:7009",
         "ssl://192.168.101.16:7009"
       ],
       "mqttWsUris": [
         "ws://192.168.101.17:7010",
         "ws://192.168.101.16:7010"
       ],
       "mqttWssUris": [
         "wss://192.168.101.17:7011",
         "wss://192.168.101.16:7011"
       ],
       "restUris": [
         "http://192.168.101.17:7006",
         "http://192.168.101.16:7006"
       ],
       "restTlsUris": [
         "https://192.168.101.17:7007",
         "https://192.168.101.16:7007"
       ],
       "smfHosts": [
         "tcp://192.168.101.17:7000",
         "tcp://192.168.101.16:7000"
       ],
       "smfTlsHosts": [
         "tcps://192.168.101.17:7003",
         "tcps://192.168.101.16:7003"
       ],
       "smfZipHosts": [
         "tcp://192.168.101.17:7001",
         "tcp://192.168.101.16:7001"
       ],
       "webMessagingUris": [
         "http://192.168.101.17:7004",
         "http://192.168.101.16:7004"
       ],
       "webMessagingTlsUris": [
         "https://192.168.101.17:7005",
         "https://192.168.101.16:7005"
       ],
       "managementHostnames": [
         "medium-ha-vmr-2.sys.pie-ci-multi-az.cfplatformeng.com",
         "medium-ha-vmr-1.sys.pie-ci-multi-az.cfplatformeng.com"
       ],
       "managementPassword": "0dbddc9ccf3f4c8db0f38f15359f3aab",
       "managementUsername": "v001-mgmt"
    }
  }, ]
  }
}

If the environment variable VCAP_SERVICES contains more than one service binding, you must search for the Solace Messaging service instance. You can search for the service instance statically by looking up a pre-defined name attribute or dynamically through the tags or label properties. See the Solace sample application for more information about achieving this.

If a VMR service instance was created using the medium-ha or large-ha service plan then it will be highly available. In these cases there will be 2 seperate service URIs for each of the available transports as shown in the example above. Connecting applications use both of these URIs by reconnecting to the other if one of them becomes unavailable. This is known as the host list HA failover mechanism and more information can be found in Solace documentation.

If a VMR service instance was created using the shared, large, or community service plan then it will not be highly available. In these cases there will only be one URI for each of the supported transports.

Credentials Fields

Field Applies to messaging protocol Description
clientUsername All except management (SEMP) The client username used to access the messaging services
clientPassword All except management (SEMP) The client password used to access the messaging services
msgVpnName JMS, SMF, and webMessaging The name of the VPN allocated to the application
jmsJndiUris JMS The JNDI provider URLs: InitialContext.PROVIDER_URL
jmsJndiTlsUris JMS The JNDI provider URLs: InitialContext.PROVIDER_URL
mqttUris MQTT The MQTT service URIs
mqttTlsUris MQTT The MQTT service TLS URIs
mqttWsUris MQTT The MQTT WebSocket URIs
mqttWssUris MQTT The MQTT WebSocket TLS URIs
restUris REST The REST endpoints base URIs
restTlsUris REST The REST TLS endpoints base URIs
smfHosts SMF The SMF HOST Session Property
smfTlsHosts SMF The SMF TLS HOST Session Property
smfZipHosts SMF The compressed SMF HOST Session Property
webMessagingUris Web Messaging The URLs used to connect the session (solclientjs), or the HOST Session Property (CCSMP, .NET API, and JAVA RTO)
webMessagingTlsUris Web Messaging The HTTPS URLs used to connect the session (solclientjs), or the HOST Session Property (CCSMP, .NET API, and JAVA RTO)
managementHostnames Management (SEMP) The DNS hostnames associated with the service instance’s management service. These hostnames can be used by management applications external to PCF, for example SolAdmin, to connect to the VNR associated with the service instance
managementPassword Management (SEMP) The VPN’s administrative username
managementUsername Management (SEMP) The VPN’s administrative password

Messaging Protocols

The table above matches each field to the messaging protocol it uses. The Solace Messaging service supports the following messaging protocols:

Note: The application needs to provide the Message VPN when using the SMF, JMS, or Web Messaging protocols. As a result, the application needs to read the msgVpnName fields when using those protocols.

Each protocol can have multiple possible underlying transports. The field’s prefix specifies the protocol, while the infix specifies the transport underlying the protocol. For example, "mqttUris": ["tcp://192.168.132.14:7026"] specifies the MQTT protocol over TCP.

The application only needs one Host or Uris field to connect to the Message VPN, but which one it needs depends on the required protocol and transport combination.

The following list provides the available infixes:

  • Tls: TLS-encrypted
  • Ws: WebSocket
  • Wss: TLS-encrypted WebSocket
  • Zip: Compressed SMF (SMF with compression enabled)

For example, an application uses JMS plain text must read the following fields:

  • clientUsername
  • clientPassword
  • msgVpnName
  • jmsJndiUri

Management Protocol

The Solace Messaging service supports the Solace Element Management Protocol (SEMP) as its management protocol. To use SEMP or an management application such as SolAdmin that supports SEMP, the following fields are required:

  • managementUsername
  • managementPassword
  • managementHostnames

Usernames and Passwords

  • The credentials required by the various messaging protocols are provided by clientUsername and clientPassword.
  • The credentials required to manage the Message VPN are provided by managementUsername and managementPassword. For more information, see the Managing the Message VPN topic.
Create a pull request or raise an issue on the source for this page in GitHub