Hyper-V

This tutorial will walk you through the steps required to get a single Solace PubSub+ software event broker machine image instance running in a Microsoft Hyper-V environment and ready for messaging.

Before you begin

It's assumed you have:

  • Access to Windows Server 2012.

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 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,903
up to 1,000 2 5,301
up to 10,000 4 12,892
up to 100,000 8 28,191
up to 200,000 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 event broker. The Solace PubSub+ software event 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 Storage Configuration, and for information on other defaults, see Default Configuration for Software Event Brokers.

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 requirement is to obtain a Solace PubSub+ software event broker. The event broker is distributed as a Virtual Hard Disk (.vhd) file, which allows it to be easily imported into virtualization software.

  • Solace PubSub+ Standard or Solace PubSub+ Enterprise Evaluation Edition: Go to the Solace PubSub+ Event Broker downloads page. Select the Microsoft Hyper-V square in either thePubSub+ Standard or PubSub+ Enterprise Evaluation section, and then select the Download link. A VHD called solace-pubsub-standard-<version>.vhd.gz or solace-pubsub-evaluation-<version>.vhd.gz, as appropriate, will be downloaded.
  • Solace PubSub+ Enterprise: If you have purchased PubSub+ Enterprise, Solace will provide information on how to download a VHD file package from a secure Solace server. Contact Solace Support at support@solace.com if you require assistance.

Step 2: Create a New Virtual Machine

To create a new VM image for the event broker, you must create a new virtual machine from the VHD file.

To a new VM image for the event broker and start it , do the following:

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

    This will launch the New Virtual Machine Wizard.

    New VM

  2. In the “Before You Begin” step of the wizard click Next.
    VMware-image3

    Note:  The .vhd image downloaded in a previous step is compressed using gz compression and will need to be decompressed and placed in a suitable location; the default is “Documents > Hyper-V > Virtual hard drives”.

  3. Name the event broker instance, and click Next.

    Specify VMR Instance Name and Location

  4. Select Generation 1 for the virtual machine and click Next.
  5. Specify VMR Instance Name and Location

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

    Assign Memory

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

    Configure-networking

    Note:  An external virtual switch must be created prior the creating the new virtual machine if the event broker instance is to be reachable from external hosts.

  8. Select the virtual hard disk that the event broker will use, and click Next when complete.

    Connect Virtual Hard Disk

  9. Review the settings, then click Finish.

    Hyper-V Manager

    Wait until the Wizard closes. The event broker image will display in the Hyper-V Manager.

    Hyper-V Manager

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

    Select the Processor tab under Hardware and increase the number of virtual processors to 2.

  11. Power on the event broker.

    In the Hyper-V Manager, right-click the event broker instance you want to start, then click Start.

    Hyper-V Manager

  12. Open the console.

    Right-click the event broker, then click Connect.

    Hyper-V Manager

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

    Console

  13. Login to the event broker.

    The event broker messaging application software resides in a container that is wrapped within a Linux OS to form 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 in to 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.

    Initial Login

    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.

Step 3: Configure the Host Name

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

  1. Shut down Solace PubSub+:

    [sysadmin@solace ~]$ solacectl service stop

  2. Configure the hostname:

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

  3. Restart the Solace PubSub+:

    [sysadmin@solace ~]$ solacectl service start

  4. 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).

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

To access the Solace CLI, do the following:

  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:

    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 address assigned to the event broker (listed for intf0:1), which can be used to remotely manage it (that is, not from the VM console).

    solace> show ip vrf management
    VRF: management
    Number of interfaces: 1
    
    Status Flags:   R=Redundancy,  A=Admin,  O=Oper,  P=Physical
    Status Values:  U=Up,  D=Down,  N=Not Applicable
    
    Status
    Interface       V Router  IP Address          Source  R  A  O  P
    --------------  --------  ------------------  ------  -----------
    intf0:1         static    <IP Address>        system  U  U  U  U
    
    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
    169.254.0.0       *                 255.255.0.0       intf0
    192.168.128.0     *                 255.255.240.0     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 in as the admin user.
  5. 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.

Step 5: Review Configuration Defaults

By default, event 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 Default Configuration for Software Event Brokers.

Next Steps

You now have an event broker machine image 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 begin to configure and manage the event broker’s messaging operations through the Solace CLI. For information on how to perform these configuration and management tasks, refer to the topics in Configuration.