This tutorial will walk you through the steps required to get a single Solace PubSub+ software message broker Machine image instance running in your environment and ready for messaging.
- Before you begin
- Step 1: Get a Software Message Broker
- Step 2: Import the Software Message Broker
- Step 3: Configure the Host Name
- Step 4: Access the Solace CLI
- Step 5: Review Configuration Defaults
- Next Steps
It's assumed you have:
- Access to Oracle VM VirtualBox Manager.
The number of CPUs and system memory required by your message broker depends on the number of client connections you need to support. By default, fresh installations of the message broker allow up to 100 client connections by default.
The following table lists the minimum system resources required to support each client connection scaling tier.
Minimum System Resources Required For Connection Scaling Tiers
|Client Connections||CPUs*||Virtual Memory (MiB)|
|up to 100||2||1,930|
|up to 1,000||2||5,301|
|up to 10,000||minimum of 4||12,892|
|up to 100,000||minimum of 8||28,191|
|up to 200,000||minimum of 12||53,816|
*The monitoring node in a high-availability (HA ) group needs only 1 CPU.
If you plan to scale your deployment above the 1,000 client connections tier you should note that you're going to need to provision space on a drive to ensure proper functioning of your message broker. The Solace PubSub+ software message broker provides a 30 GB disk partition, which is suitable for proof of concept use for up to 1,000 clients, but is insufficient for client connection tiers above 1,000 and most guaranteed messaging deployments in production environments. For production use, you must provision an additional drive for the message spool, and it's also recommended to provide an additional drive for diagnostics information. For instructions on provisioning additional storage space, see Externalizing the Message Spool & Diagnostics, and for information on other defaults, see Configuration Defaults.
To deploy message brokers in high-availability (HA) redundancy groups, you must set up three separate message broker instances and then configure them as an HA group. For more information on how to configure existing message brokers into an HA group, see HA Group Configuration.
The first task is to download the Solace PubSub+ software message broker. It is distributed as an Open Virtualization Archive (.OVA) file, which allows for easy importation to virtualization software.
- Solace PubSub+ Standard or Solace PubSub+ Enterprise Evaluation Edition: Go to the Downloads page of dev.solace.com. Select the link in the OVA section in either the PubSub+ Standard or PubSub+ Enterprise Evaluation columns.
An OVA called
solace-pubsub-evaluation-<version>.ova, as appropriate, will be downloaded.
- Solace PubSub+ Enterprise: If you have purchased PubSub+ Enterprise, Solace will provide information on how to download an OVA file package from a secure Solace server. Contact Solace Support at firstname.lastname@example.org if you require assistance.
To create a new VM image for the Solace PubSub+ software message broker, you must import the OVA file into the virtual machine manager using the default configuration.
Once it is imported, you must configure the VM image to use one of the interfaces on the host machine that has access to DHCP services.
Note: If you are using Windows 8 or 10, the error “VT-x is not available. (VERR_VMX_NO_VMX)” may occur when starting a message broker. This indicates that Hyper-V is interfering with Intel® VT-x hardware virtualization support, which is required to run message brokers in VirtualBox. In this case, disable Hyper-V virtualization on your Windows system, then reboot.
To import the message broker, do the following:
- In Oracle VM VirtualBox Manager, select File > Import Appliance.
- In the Import Virtual Appliance window that opens, select the OVA file downloaded in the previous step, and then select Next.
- The default appliance settings are sufficient to begin the import. Select Import.
- The Oracle VM VirtualBox Manager will import the message broker OVA.
- In Oracle VM VirtualBox Manager, right-click the message broker image, and select Settings.
- In the virtual machine Settings window, select the System settings, and then select Hardware Clock in UTC.
When checked, VirtualBox will report the system time in UTC format instead of local (host) time.
- Select the Network settings, then for Adapter 1, select the appropriate adapter, attached mode, and name. For DHCP, select Bridged Adapter, and the correct network adapter that the message broker will use.
The above configuration shows a Bridged Adapter. The bridged adapter configuration provides the guest VM a network interface directly on the host computer’s network. It will appear as an independent device on that subnet and must have its network configuration set up using DHCP. This works well for static configurations where the message broker will be accessed from other machines on the network.
One potential drawback of using DHCP on laptops is that they are often re-IP’d as they join different networks. This means the message broker will constantly change addresses as well.
So, for these scenarios it is often simpler to use the Host-only Adapter. A host-only adapter will provide the message broker with a network interface that can only be reached from the host computer. When running in this mode, the message broker is not able to talk to any external networks and, therefore, will not be able to use a DHCP server on that network to retrieve IP configuration information. In this case, it is necessary to either enable DHCP services within the VM Manager or to provide the message broker with a static IP address. To configure either of these situations, refer to IP Addressing in Hypervisor Environments.
- To start the VM, click the virtual machine manager’s Start button.
The message broker has successfully started when the login prompt appears.
- Login to the message broker.
The message broker application software resides in a container that is wrapped within a Linux OS to form a message broker virtual machine image. In its default state, this message broker Linux host environment has remote login disabled and contains no passwords.
To log in to the message broker for the first time you must log in as
sysadmin, which is the default user account for the Linux host environment. You will be prompted to create a password for that user.
When you are logged in as
sysadmin, you can then create passwords for the default users through the console. You must assign these default users passwords to allow remote login.
To set the hostname for the new message broker, do the following:
- Shut down Solace PubSub+:
[sysadmin@solace ~]$ solacectl service stop
- Configure the hostname:
[sysadmin@solace ~]$ solacectl hostname configure <hostname>
- Restart the Solace PubSub+:
[sysadmin@solace ~]$ solacectl service start
- Verify that the hostname has been set to the new one:
[sysadmin@solace ~]$ hostname
Note: The shell may still reflect the old hostname until a reboot, or a re-login (log out and log back in).
<name>is the hostname to assign to the message broker. Host names can contain up to 64 characters, composed of alphanumeric characters 0 to 9, a to z, A to Z, and underscores '_' and hyphens '-'. Note that '_' and '-' cannot be used at the beginning or end of a hostname. Host names must be unique among all configured message brokers.
You can access the Solace CLI from the console in the Linux host environment. This is done through the Solace Control Utility.
When you first access the Solace CLI, you should do the following:
- set a password for the admin user, which has access to all CLI commands
- determine the message broker’s IP address so that you can enable remote access
To access the Solace CLI, do the following:
- To enter the Solace CLI from the console in the Linux host environment, enter the following command in the Linux host shell.
[sysadmin@solace ~]$ solacectl cli
A CLI banner and prompt appears.
>prompt, you are at the User EXEC level of the Solace CLI command structure.
- Within the Solace CLI, enter the following commands to create an admin user named
solace(configure)# create username admin password <password>
solace(configure/username)# global-access-level admin
- To determine the IP address assigned to the message broker, enter the following command:
solace> show ip vrf management
The displayed output lists the IP address assigned to the message broker (listed for
eth0:1), which can be used to remotely manage it (that is, not from the VM console).
- To remotely access the Solace CLI for the message broker, you can now ssh to port 2222 of the message broker’s IP address and login in as the
ssh -p 2222 admin@<public_ip>
Tip: In addition to the admin CLI User, you can create additional CLI and file transfer users through the Solace CLI in the manner described in Management & Shell Users.
- Shut down Solace PubSub+:
By default, a message broker starts with a basic configuration that has most common services enabled and ready for use. This basic configuration and the default ports that are used can be modified as required. For details, see Configuration Defaults.
You now have a message broker with a basic configuration that is ready for messaging tasks. However, there are additional configuration tasks that you can perform. At this stage, you should do the following:
- Review the extra configuration tasks specific to message brokers presented on the Topics Unique to Cloud & Machine Images page.
These additional configurations allow you to further customize your message broker to better suit your particular use-case and to make it more suitable for a production deployment.
- Begin to configure and manage the message broker’s messaging operations through the Solace CLI in the same manner as you would other message brokers (say, a Solace PubSub+ appliance or Solace PubSub+ software message broker Docker container). For information on how to perform these configuration and management tasks, see the topics in the Configuration category of the Solace customer documentation.