Installing Microsoft Message Bus for Windows Server in your Virtual Lab

Note: This is a quick off-the-cuff blog so I don't lose my installation notes.

I created a Microsoft Virtual Lab on my Mac to learn and develop against.  Now I want to add Message Bus for Windows Server to that environment.  The message bus requires SQL Server, for queue persistence. I'll use SQL Server instance / VM I've already installed.  The message bus runs in a cluster configuration with from 1-3 message bus machines. I'll use a single node because I'm learning/devloping and not performance testing it.

Message Bus and SQL Server VMs will all be part of my virtual lab's AD domain, virtdev.freemansoft.com. You don't have to use Active Directory but it makes configuration simpler.  My Windows 7 development machine is not part of the virtual lab domain so we will have some configuration to do to give that client access.

Quick Service Bus Overview

The message bus provides a simple way of implementing asynchronous message passing between different systems or modules.  Producers feed messages into the service bus where they wait for consumption. Messages are stored in a SQL Server database so that no messages are lost even if the consumer or message bus itself go down or are restarted.

There are 4 major components to the Service bus that you pay attention to as a developer.

1. Embedded STS security token service for consumers of the system , including message producers and consumers, not shown in this diagram.
2. Bus configuration, Queue and Subscription/Topic definition and management.
3. Message Queues
4. Topics/Subscriptions, also known as Publish and Subscribe

Security can be handled through the embedded STS which can be integrated with Active Directory.   The STS has it's own port and supports several different authentication methods including windows authentication for AD users and OAuth for non-Domain clients.  Message bus runs on secure ports providing self signed certificates if no CA generated certificates are available.  You have to import the self signed certificate into the client's/caller's certificate store unless you turn off certificate validation.

The system management API makes it possible for authorized client programs to manipulate queues and topics.  This is good because there really isn't any out of the box management GUI.

Queues provide basic message bus functionality where messages is fed into named queues.  Client processes can then read the messages out of the queues.  Any number of consumers can sit act as readers where the load will be spread across the readers.  Each message is read only one time and time.

Topics are another type of message channel where the message is qualified in some  way via headers payload.  Reader clients can then subscribe to the topic with qualifying criteria.  The readers will receive all messages matching their filter qualifiers.   A single message will go to all subscriptions. that match the message's content or headers.

Installation

We are going to follow these basic installation steps when installing the software on a core system. It assumes you have an Active Directory connected VM to install service bus on.

1. Verify you have SQL Server installed on some machine and you know a user id that can login with schema privs.
2. Download the message bits to the system.
3. Install the Message Bus and configure it
4. Open the firewall ports required by the Message Bus
5. Create a Namespace and generate the connection string required to connect to this message bus and namespace
6. Export the certificate and CA from the message bus
7. Copy it to a client machine
8. Install the certificates on the Windows 7 client machine
9. Download the message bus explorer and connect to the message bus.

Acquiring the Installer Package

I installed this on a core machine so there are two basic ways of getting the bits.  Download from the command line or download to a different machine and then copy them over to this machine using the command prompt using the \\<servername>\$C\<path> naming conventions.  

1. Open a command prompt on the machine from Hyper-V Manager.  Select the server form the Virtual Machines list and right mouse and select connect...  
2. Run the Start-BitsTransfer with the path down the download location 
   http://download.microsoft.com/download/8/6/D/86D8676C-CC00-4A21-A4F0-AB36FA2ABE1C/SB_RTM/ServiceBus.exe

3. Run the Service Bus installer. It will show a GUI even if you installed the core version of Windows server.

Configure the Message Bus

1. Set up PowerShell. We're going to use a lot of the commands in the azure reference document http://msdn.microsoft.com/en-us/library/windowsazure/jj200653(v=azure.10).aspx
1. Import the PowerShell command-let library before executing the commands. import-module "$env: programfiles\<pathtoservicebus>.psm1" See  http://msdn.microsoft.com/en-us/library/windowsazure/jj193018(v=azure.10).aspx for available commands. 
2. Create a new farm and point it at a sql server instance.  You should also create a namespace. The message bus was designed to support multi-tenant through the use of namespaces.  You can think of namespaces as tables  or partitions in the message bus. There are a couple ways configuring the message bus
1. Use PowerShell   
1. Use the New-SBFarm command to create the farm.
2. Use the New-SBNamespace command to create a namespace
2. You can run the service bus configuration wizard GUI.

1.  Use c:\Program Files\Service Bus\1.0\GUIMicrosoft.ServiceBus.configWizard.exe even if you are doing this on a core server as long as you connected through the hyper-v manager.
2. Create a Farm
3. Create a Namespace
3. Verify the new farm configuration with the PowerShell command Get-SBFarm.
4. Verify the Namespace configuration with Get-SBNamespace.

Open the Firewall Ports

We need to open the firewall ports, 9350-9355, for the Service bus.  We're going to use the netsh command

netsh advfirewall firewall add rule name="service bus 9350-9355 In" dir=in action=allow localport=9350-9355 protocol=tcp

Get the Namespace Connection String

Use PowerShell to find out the connection string for the message bus and namespace.  We'll use this to with the ServiceBusExplorer and when creating connection strings for applications.

This connection string assumes you are using an AD account to connect to service bus.  We'll ad OAuth authentication to this connect string for programs not using windows authentication. We're using PowerShell probably as a domain account with administrator privileges.

1. Type Get-SBNamespace to see the available namespaces.
   
2. Get the connection string for your service bus and namespace with get-SBClientConfiguration -name <namespace>  I received the following.
   

   Endpoint=sb://ServiceBus1.virtdev.freemansoft.com/FreemanSoft;StsEndpoint=https://ServiceBus1.virtdev.freemansoft.com:9355/FreemanSoft/;RuntimePort=9354;ManagementPort=9355

3. In my case, I needed to use OAuth so I could connect to the message bus with one of my other PCs.  I ended up with 

   Endpoint=sb://ServiceBus1.virtdev.freemansoft.com/FreemanSoft;StsEndpoint=https://ServiceBus1.virtdev.freemansoft.com:9355/FreemanSoft/$STS/OAuth;RuntimePort=9354;ManagementPort=9355;WindowsUsername=Administrator;WindowsDomain=virtdev.freemansoft.com;WindowsPassword=Password!

Copy Autogenerated Certificate to Client

Service expects to use SSL and creates a self signed certificate to get you started.  You need to copy that certificate to any client machine and install it in the certificate store.  You can write programs to ignore this certificate problem but programs like the Service Bus Explorer may fail unless you have a recognized certificate.

1. Export the certificate using the Get-SBAutoGeneratedCA PowerShell command. It will create AutogeneratedCA.cer and AutoGeneratedCA.crl files.
2. Copy these files to the client machine.  I was running on Windows Server 2012 Core so no Gui explorer was available.  I copied with the command line. 
1. copy AutogeneratedCA.* \\client-machine\c$\<some-directory>
3. Install the certificate and authority in the client machines using the MMC Certificate Authority snap in following these instructions http://msdn.microsoft.com/en-us/library/windowsazure/jj192993(v=azure.10).aspx 

Verify Installation 

Use the Service Bus Explorer to verify the installation. I did this on a different machine but you could do it on the Service Bus machine if you were doing this all on your local Windows dev box.  Service bus comes as a Visual Studio project that you have to build.  In my case service bus is a core system so I installed my dev tools and Service Bus Explorer on a different machine.

1. Download Service Bus Explorer from code.microsoft.com Do not use the version on the Microsoft Service Bus download page.  It is out of date.
2. Open the Service Bus Explorer project in Visual Studio and build the project.
3. Run the Service Bus Explorer
4. Select Connect
5. Paste in the connection string built in a step above.  Use the OAuth version if you are not calling from an AD machine and account.
6. You should connect but see no queues or topics

Connection problems are usually certificate errors, an error in the connection string or missing firewall exception rules on the service bus host machine.

Multiple Service Bus Hosts

You add additional configured hosts with the Add-SBHost command. I have not used this command.

Credits.

I'd like to thank Harin and Ryan for their patience with repeated questions.