Microsoft Hyper-V

This tutorial walks you through the steps to set up a single PubSub+ software event broker machine image instance in Microsoft Hyper-V.

Before You Begin

It's assumed that you have a Windows machine with Hyper-V enabled.

System Requirements

The number of CPUs and system memory required by your event broker depends on the number of client connections you need to support. By default, fresh installations of the event broker allow up to 100 client connections.

To achieve desired stability and performance, the infrastructure hosting the PubSub+ Software Event Broker must provide a minimum set of system resources. System resources can be broadly categorized into requirements related to processors, memory, and storage. For details about the type of system resources required and their characteristics, see System Resource Requirements.

You can increase certain system limits using System Scaling Parameters. Increasing these system limits also increases the system resources that are required. For more information, see Using System Scaling Parameters.

Information about configuring storage can be found at Managing Storage for Virtual Machine Images.

If you plan to scale your deployment above the 1,000 client connections level you will need to provision space on a drive to ensure proper functioning of your event broker. The event broker machine image provides a 30 GB disk partition, which is suitable for proof-of-concept use for up to 1,000 clients, but is insufficient for over 1,000 client connections 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 Managing Storage Volumes, and for information on other defaults, see Default Configuration for Software Event Brokers.

The software event broker requires storage with medium to high bandwidth/IOPS and low latency. The virtual machine image uses settings for the widest compatibility; these settings are not tuned for performance. For information about getting the best storage performance for your system, consult the Hyper-V documentation.

High Availability Considerations

To deploy event brokers in high-availability (HA) redundancy groups, you must set up three separate event broker instances and then configure them as an HA group. For more information on how to configure existing event brokers into an HA group, see HA Group Configuration.

Step 1: Get a Software Event Broker

The first step is to download an edition of PubSub+ software event broker. For Hyper-V, the event broker is distributed as a compressed Virtual Hard Disk (.vhd) file.

  1. Download the virtual machine image:
    1. Go to the Solace PubSub+ Event Broker downloads page.
    2. Scroll to the Microsoft Hyper-V section, and then select the required edition of the software event broker.
    3. Fill in your details, and then click Get The Downloads.
    4. Click Download under the PubSub+ edition.

    A file called solace-pubsub-<edition>-<version>.vhd is downloaded.

  2. Verify the MD5 checksum of the downloaded file. For example, run the following command in PowerShell:

    certutil -hashfile <path_to_gz> MD5
  3. Unpack the compressed file to the folder where Hyper-V stores virtual hard disk images (usually C:\Users\Public\Public Documents\Hyper-V\Virtual hard disks).

Step 2: Create a New Virtual Machine

To start an event broker instance in Hyper-V, you must create a new VM image from the VHD file.

To do this, follow these steps:

  1. Open the Hyper-V Manager.
  2. On the left-side menu, right-click the Windows Server instance that will host the new VM and select New > Virtual Machine.

    The New Virtual Machine Wizard opens.

  3. Once you've read the information on the Before You Begin screen of the wizard, click Next.

  4. Provide a Name for the event broker instance, and then click Next.

  5. Select Generation 1 for the virtual machine and click Next.

  6. Assign memory for the event broker instance. Then, click Next.

    The memory required for the event broker depends on the number of client connections you want to support. For details, see System Resource Requirements.

  7. Select a network adapter connected to a virtual switch. Then, click Next.

    You must have an external virtual switch available prior to creating the new virtual machine if the event broker instance is to be reachable from external hosts.

  8. For the virtual hard disk, select the VHD file from Step 1: Get a Software Event Broker. Then, click Next.

  9. Review the settings and then click Finish.

    Wait until the Wizard closes. The Virtual Machines list displays the event broker image.

  10. Right click your newly created event broker and select Settings.

    Under Hardware, select the Processor tab and increase the number of virtual processors to 2, and then click Apply and OK.

  11. Power on the event broker.

    In the Virtual Machines list, right-click the event broker instance, and then click Start.

  12. Open the console.

    Right-click the event broker, then click Connect.

    The event broker is successfully started when the login prompt appears.

  13. Log in to the event broker.

    The software event broker resides in a container that is wrapped within a Linux OS to make an event broker virtual machine image. In its default state, this event broker Linux host environment has remote login disabled and contains no passwords.

    To log into the event 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 a password to these default users to allow remote login.

Step 3: Configure the Host Name

To set the hostname for the new event broker, do the following:

  1. Shut down the Solace service:

    [sysadmin@solace ~]$ solacectl service stop

  2. Configure the hostname:

    [sysadmin@solace ~]$ solacectl hostname configure <hostname>

  3. Restart the Solace service:

    [sysadmin@solace ~]$ solacectl service start

  4. Verify that the hostname has been set to the new one:

    [sysadmin@solace ~]$ hostname

The shell may still reflect the old hostname until a reboot, or a re-login (log out and log back in).

Where:

<name> is the hostname to assign to the event 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 event brokers.

Step 4: Access the Solace CLI

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 event broker’s IP address so that you can enable remote access
  1. 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.

    At the > prompt, you are at the User EXEC level of the Solace CLI command structure.

  2. Within the Solace CLI, enter the following commands to create an admin user named admin (you can choose another name if you wish):
    solace> enable
    solace# configure
    solace(configure)# create username admin password <password>
    solace(configure/username)# global-access-level admin
  3. To determine the IP address assigned to the event broker, enter the following command:
    solace> show ip vrf management

    The displayed output lists the IP addresses assigned to the event broker (listed for intf0:1), which can be used to remotely manage it (that is, not from the VM console).

    Example:

    solace> show ip vrf management
    VRF: management
    Number of interfaces: 1
    
    Interface    V Router   IP Address        Source
    -----------  ---------  ----------------  -------
    intf0:1      static     <IP Address>      system
    intf0:1      static     ::/0              system
    
    Number of active global routes: 5
    
    Destination       Gateway           Network Mask            Interface
    ----------------  ----------------  ----------------------  ----------
    169.254.169.254   *                 255.255.255.255         N/A
    172.17.0.0        *                 255.255.0.0             N/A
    default           192.168.128.1     0.0.0.0                 intf0
    192.168.128.0     *                 255.255.240.0           intf0
    fe80::            *                 ffff:ffff:ffff:ffff::   intf0
  4. To remotely access the Solace CLI for the event broker, you can now ssh to port 2222 of the event broker’s IP address and login as the admin user.
    ssh -p 2222 admin@<public_ip>

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.

Step 5: Review Configuration Defaults

By default, the event broker starts with a basic configuration that has the 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 Default Configuration for Software Event Brokers.

Next Steps

You now have a software event broker container with a basic configuration that is ready for messaging tasks.

There are additional configuration tasks that you can make use of in the following topics:

When you are comfortable with your event broker, you can test messaging using the Solace SDKPerf application. You can download SDKPerf from the Other Software section in the Downloads page.

For more information about working with your event brokers, see the following: