Initializing with Cloud-Init

You can initialize a Solace PubSub+ software event broker cloud or machine image with the cloud-init utility. At start-up, cloud-init iterates through a list of provisioned datasources looking for valid meta-data and user-data.

  • meta-data is supplied as key value pairs, and can be used to configure instance specific parameters such as instance-id, hostname, and local IP addresses.
  • user-data can be provided in many forms including files, scripts, and #cloud-config, which provides YAML-formatted cloud-init specific instructions. It can be used to update instance software packages, execute first-boot scripts, install certificates and configure users, groups, and authentication keys.

:  The software event broker doesn't prevent the processing of any user-data (including #cloud-config commands) that are not applicable, or possibly harmful to system stability. Also, the software event broker neither prevents user-data from including scripts, nor does it selectively execute script content.

The following table lists valid datasources for the various software event brokers.

Cloud-Init Datasources

Solace PubSub+ software event broker Datasources
Standard, all VM Images NoCloud
Standard, AMI for Amazon Web Services EC2
Standard, OpenStack OpenStack
Enterprise Evaluation Edition, all VM Images NoCloud
Enterprise Evaluation Edition, AMI for Amazon Web Services EC2
Enterprise Evaluation Edition, OpenStack OpenStack
Enterprise, all VM Images NoCloud
Enterprise, AMI for Amazon Web Services EC2
Enterprise, Open Stack OpenStack

:  The NoCloud datasource can load user provided initial configuration in user-data and meta-data from an ISO loaded in the Virtual Machine Guest CDROM drive. For instructions on how to create the ISO, see Creating NoCloud Datasources.

Setting Configuration Keys

Configuration keys and the configuration_keys directive

You can use a cloud-init module called solace to define configuration keys as environment variables for the software event brokerʾs Docker container. Configuration via environment variables is supported where the variable name consists of the configuration key hierarchy concatenated with the underscore character. Environment variables are specified in /etc/solace/solace-container.env.conf, and configuration keys set by the solace moduleʼs configuration_keys directive are written to /etc/solace/solace-container.env.conf.

The solace module, shown with its associated configuration_keys directive, has the following syntax within #cloud-config.

#cloud-config
solace:
configuration_keys:
<CONFIGURATION_KEY>: <VALUE>
<CONFIGURATION_KEY>: <VALUE>

The software event broker configuration keys that you can use are shown in the following tables.

Solace PubSub+ software event broker Configuration Keys

Configuration Key Description Value
configsync/enable

Enables Config-Sync.

To synchronize the HA pair after the software event brokers are initialized with Cloud-Init, you must manually assert system-level configuration of one event broker over its mate. For more information, see Asserting Event Broker System Configurations.

yes or no

The default value is no.

configsync/tls/enable

Enables the use of TLS encryption.

If enabled, and redundancy is also enabled, a pre-shared-key must be configured for config-sync to be operational.

yes or no

The default value is no.

interface/<ip_intf>/physical

Docker Host (Linux) physical interface bound to the Solace PubSub+ IP interface.

<os interface>

interface/<ip_intf>/virtualrouter virtual router to which the Solace PubSub+ IP interface is assigned

static, primary or backup

The default value is static.

interface/<ip_intf>/enable Enable Solace PubSub+ IP interface

yes or no

The default value is yes.

logging/<log_facility>/output The place where a log stream is sent. For more information, see Configuring Container Logging.

file, stdout, all or none

The default value is file.

Valid values for <log_facility> are debug, command, system, event or kernel.

logging/<log_facility>/format The format of a log stream if it is sent to stdout. For more information, see Configuring Container Logging.

legacy, rfc5424, graylog or raw

The default value is legacy.

If file is specified as the log stream destination, the output is always in the legacy format.

Valid values for <log_facility> are debug, command, system, event or kernel.

messagevpn/<name>/service/amqp/port The port that the AMQP service associated with message VPN <name> uses within the software event broker Docker container. <port_number>
messagevpn/<name>/service/amqp/tlsport The port that the AMQP service associated with message VPN <name> uses for TLS traffic within the software event broker Docker container. <port_number>

This setting takes effect only if a TLS server certificate is configured.

messagevpn/<name>/service/mqtt/port The port that the MQTT service associated with message VPN <name> uses within the software event broker Docker container. <port_number>
messagevpn/<name>/service/mqtt/tlsport The port that the MQTT service associated with message VPN <name> uses for TLS traffic within the software event broker Docker container. <port_number>

This setting takes effect only if a TLS server certificate is configured.

messagevpn/<name>/service/mqtt/webport The port that the MQTT service associated with message VPN <name> uses over WebSockets within the software event broker Docker container. <port_number>
messagevpn/<name>/service/mqtt/tlswebport The port that the MQTT service associated with message VPN <name> uses over WebSockets for TLS traffic within the software event broker Docker container. <port_number>

This setting takes effect only if a TLS server certificate is configured.

messagevpn/<name>/service/rest/port The port that the REST service associated with message VPN <name> uses within the software event broker Docker container. <port_number>
messagevpn/<name>/service/rest/tlsport The port that the REST service associated with message VPN <name> uses for TLS traffic within the software event broker Docker container. <port_number>

This setting takes effect only if a TLS server certificate is configured.

nodetype High-availability (HA) group node type.

message_routing or monitoring

The default value is message_routing.

productkey Installs the given <product-key>. For more information, see Product Keys on Software Event Brokers . <product-key>
redundancy/activestandbyrole The active standby role of message routing nodes in a HA Group.

primary or backup

The default value is primary.

redundancy/authentication/presharedkey/key The base64-encoded key to use as the redundancy pre-shared key. <key>
redundancy/authentication/presharedkey/keyfilepath The path to the file containing the base64-encoded key to use as the redundancy pre-shared key.

<key-file-path>

Only one of either key or keyfilepath must be supplied.

Relative file paths for files containing secrets are relative to the /run/secrets directory.

redundancy/enable Enables redundancy.

yes or no

The default value is no.

redundancy/group/node/<name>/connectvia The fully qualified domain name (FQDN) or IP address (and optional port) of a node in a HA Group. <addr-port>
redundancy/group/node/<name>/nodetype High-availability (HA) group node type.

message_routing or monitoring

The default value is message_routing.

redundancy/matelink/tls/enable Enables mate-link to use TLS encryption.

yes or no

The default value is no.

redundancy/matelink/remote/port The port the mate-links connects to on the HA mate. <port>
redundancy/mate/smf/port

The port that the mate event broker uses for plain-text SMF traffic. This setting is required only when each HA mate listens on a different port.

<port_number>
redundancy/mate/smf/compressedport The port that the mate event broker uses for compressed SMF traffic. This setting is required only when each HA mate listens on a different port. <port_number>
redundancy/mate/smf/tlsport The port that the mate event broker uses for TLS/SSL SMF traffic. This setting is required only when each HA mate listens on a different port. <port_number>
routername The Solace PubSub+ router name.

<router_name>

<router_name> must be constructed using only lowercase letters and numbers from 0 to 9, especially when it is to be used to configure redundancy. The use of other characters will prevent the proper functioning of redundancy.

service/healthcheck/port The port that the health check service will listen on. <port_number>
service/matelink/port The port that the matelink service will listen on. <port_number>
service/ssh/port

The port used by the sshd process within the software event broker Docker container (Corresponds to Solace PubSub+ SSH, see Default Configuration for Software Event Brokers).

<port_number>
service/semp/port The port that SEMP service uses within the software event broker Docker container. <port_number>
service/semp/tlsport The port that the SEMP service uses for TLS traffic within the software event broker Docker container.

<port_number>

This setting takes effect only if a TLS server certificate is configured.

service/smf/compressedport The port that the SMF service uses for compressed traffic within the software event broker Docker container. <port_number>
service/smf/port The port that the SMF service uses within the software event broker Docker container. <port_number>
service/smf/routingport The port that the SMF service uses for routing control traffic within the software event broker Docker container. <port_number>
service/smf/tlsport The port that the SMF service uses for TLS traffic within the software event broker Docker container. <port_number>

This setting takes effect only if a TLS server certificate is configured.

service/amqp/tlsport The global port used by the AMQP service for TLS traffic within the software event broker Docker container

<port>

This setting takes effect only if a TLS server certificate is configured.

service/webtransport/port The port that the Web Transport service uses within the software event broker Docker container. <port_number>
service/webtransport/tlsport The port that the Web Transport service uses for TLS traffic within the software event broker Docker container. <port_number>

This setting takes effect only if a TLS server certificate is configured.

service/redundancy/firstlistenport The first three ports are used for redundancy activity election. The second and third ports are used as required. For more information, see Default Configuration for Software Event Brokers. <port_number>
system/scaling/maxconnectioncount The maximum supported number of client connections. For more information, see Scaling Tiers for Software Event Brokers.

100, 1000, 10000, 100000or 200000

The default value is 100.

tls/crimeexploitprotection/enable Enable protection against the CRIME exploit for TLS+compression. For more information, see Configuring CRIME Exploit Protection yes or no

The default value is yes.

tls/servercertificate/filepath The full path to the file containing the TLS server certificate.

<filepath>

If the TLS server certificate contained in the file is encrypted, then the path to a file containing the passphrase must be provided by the tls/servercertificate/ passphrasefilepath configuration key.

Relative file paths for files containing secrets are relative to the /run/secrets directory.

tls/servercertificate/passphrasefilepath The full path to the file containing the passphrase used to decrypt an encrypted TLS server certificate.

<filepath>

Relative file paths for files containing secrets are relative to the /run/secrets directory.

username/<name>/password A plain text Solace CLI user password for username <name>.

<password>

This configuration key is only suitable for development and testing activities and is not recommended for production deployments as it is not a secure way of transferring credentials to Solace PubSub+.

username/<name>/encryptedpassword An encrypted Solace CLI user password for username <name>.

<encryptedpassword>

SHA-512 is supported.

Salt prior to hashing, and the format should be: $6$salt$hashed-password

username/<name>/globalaccesslevel Creates a Solace CLI user with username <name> and assigns the access to global access level.

none, read-only, read-write, admin. The default value is none.

username/<name>/passwordfilepath The full path to the file containing the password for username <name>.

<passwordfilepath>

Relative file paths for files containing secrets are relative to the /run/secrets directory.

The storage directive

You may assign persistent storage volumes to external storage devices with cloud-init using the solace moduleʼs storage directive. The solace module, shown with its associated configuration_keys and storage directives, has the following syntax within #cloud-config.

#cloud-config
solace:
configuration_keys:
<CONFIGURATION_KEY>: <VALUE>
<CONFIGURATION_KEY>: <VALUE>
storage:
<VOLUME>:
device: <DEVICE>

An example of the use of the storage directive is shown in AWS PubSub+ Initialization.

User Authentication Initialization

By default, the sysadmin user account is unlocked with an undefined password. Remote login is explicitly blocked until the sysadmin user password has been defined.

In cloud environments, the provider typically configures sysadmin users with a qualified cloud-init datasource, and usually sysadmin users are also assigned public/private SSH keys from cloud-init user-data. However, it is also possible for you to define the sysadmin password with cloud-init user-data, and you may also define additional host user accounts using cloud-init user-data.

In enterprise environments, the system administrator is responsible for creating and configuring software event broker instances. Typically, the sysadmin user is assigned a password on first login attempt at the Virtual Machine console. It is also possible to assign the password, or supply a public/private SSH key with cloud-init user-data, provided by an ISO image installed in the virtual machine CD-ROM drive. For example, text similar to the following #cloud-config snippet can be used to set the sysadmin password.

#cloud-config

password: sysadmin chpasswd: {expire: False}

Timezone Initialization

For software event broker 9.4.0 release onwards, you can set the timezone by adding the timezone: <timezone> in the #cloud-config. As shown in the example below, the following #cloud-config snippet sets the timezone to Canada/Eastern.

#cloud-config

password: sysadmin chpasswd: {expire: False} timezone: Canada/Eastern

Connection Scaling Tier Initialization

You can configure a software event brokerʼs connection scaling tier with the system/scaling/maxconnectioncount configuration key. For information about connection scaling tiers, see Scaling Tiers for Software Event Brokers.

The following shows an example of a user-data text snippet that sets the maximum client connection scaling tier to 10,000.

#cloud-config
solace:
configuration_keys:
system_scaling_maxconnectioncount: 10000

Creating NoCloud Datasources

PubSub+ software event brokers that are configured to accept the NoCloud cloud-init datasource can load an initial configuration from an ISO loaded in the Virtual Machine Guest CDROM drive.

To create an ISO, perform the following steps:

  1. Create a text file named meta-data. This file may be empty with a length of 0 bytes, or may contain any valid YAML for cloud-init meta-data.
  2. Create a text file named user-data. This file may be empty with a length 0 bytes, or may contain any valid YAML for cloud-init user-data.
  3. Generate the ISO using genisoimage or mkisofs on the Linux host.
    genisoimage -output docker_subnet.iso -volid cidata -joliet -rock user-data meta-data

    or

    mkisofs -output docker_subnet.iso -volid cidata -joliet -rock user-data meta-data

AWS PubSub+ Initialization

AWS Manual Set Up provides the steps required to get a software event broker cloud image running and ready for messaging in Amazon Web Services (AWS). Step 2: Access the Solace CLI , used for setting the admin userʼs password, can be simplified through the use of the configuration keys username/<name>/globalaccesslevel and username/<name>/password. Setting up the admin user using configuration keys allows you to go directly to SolAdmin to manage the Solace PubSub+ software event broker, skipping additional configuration steps in Solace CLI.

Admin user configuration

To configure the admin user and assign a password during the initial setup of an AWS Solace PubSub+ software event broker Image, you can enter configuration keys as user-data text, where the user-data consists of the configuration key hierarchy concatenated with the underscore character. Configuration keys as user-data text can be entered into the User data block in the Advanced Details section of the Configure Instance Details screen. In the example below, the password is adminpwd.

#cloud-config

solace:
  configuration_keys:
     username_admin_globalaccesslevel: admin
     username_admin_password: adminpwd

Storage provisioning

Storage of software event broker volumes can also be provisioned at initial setup. You can perform the initialization with a two-step process. In this example the volumes adb and internalSpool will be assigned to a block device, and the admin user will be configured and assigned a password.

  1. You can enter the following user-data text into the User data block in the Advanced Details section of the Configure Instance Details screen:

    #cloud-config
    solace:
      configuration_keys:
         username_admin_globalaccesslevel: admin
         username_admin_password: adminpwd
         service_ssh_port: 22
         service_semp_port: 8080
      storage:
         adb:
             device: xvdb
         internalSpool:
             device: xvdb

  2. The storage device will appear in the software event broker host as xvdb.

  3. At AWSʼs Add Storage screen in the software event broker Cloud Image configuration process, add a new volume on which adb and internalSpool will reside. In this example, a 30 GB device called /dev/sdb has been added.
  4. After logging into the software event brokerʼs host, the solacectl storage command can be used to show the new storage assignment.
    >sudo solacectl storage ls
    Block Devices:
    Name Size Note
    xvda 30.0G Main device
    └─xvda1 0.2G
    └─xvda2 29.8G
    xvdb 30.0G
    └─xvdb1 30.0G
    Storage Volumes:
    Name Size Used Available Path
    /dev/mapper/vg01-root 9.8G 1.1G 8.8G /
    /dev/mapper/vg01-solace 9.8G 67M 9.7G /var/lib/docker/volumes
    ├─adbBackup 9.8G 0 9.7G /var/lib/docker/volumes/adbBackup/_data
    ├─diagnostics 9.8G 4.0K 9.7G /var/lib/docker/volumes/diagnostics/_data
    ├─etc 9.8G 4.0K 9.7G /etc/solace/solace-container.d
    ├─jail 9.8G 9.8M 9.7G /var/lib/docker/volumes/jail/_data
    └─var 9.8G 25M 9.7G /var/lib/docker/volumes/var/_data
    /dev/xvdb1 30G 1.3G 29G /mnt/vmr
    ├─adb 30G 1.0G 29G /mnt/vmr/adb
    └─internalSpool 30G 274M 29G /mnt/vmr/internalSpool
    Image Pool:
    Name Size Used Available
    Image pool 8.905 GB 1.033 GB 7.872 GB

Enable CloudWatch

The docker-create-opt directive is used to configure the Amazon CloudWatch Docker logging driver. For more information about that driver, refer to Amazon CloudWatch Logs logging driver at Docker's documentation site.

solace:
  docker-create-opt:
    log-driver: awslogs
    log-opt:
      - awslogs-region=<region>
      - awslogs-group=<LogGroup>
      - awslogs-create-group=true

When configuring the Amazon CloudWatch log driver, you may want to use the logging configuration keys to output additional logs to stdout because anything sent to stdout will be sent to CloudWatch.