One of the protocols most commonly used in the messaging systems that can be also used for the Internet of Things is the AMQP (Advanced Message Queuing Protocol) that already is OASIS standard and now it is at version 1.0.

The Service Bus offered by Windows Azure supports this protocol, that ensures communication between clients developed on different platforms. In the case of a Microsoft platform we have no problem thanks to the Windows Azure SDK (now at version 2.3) that completely abstracts the underlying communication protocol with the Service Bus (AMQP, SBMP, ...) thanks to its programming model.

if we are working on a non-Microsoft system, one of the best choices is to adopt the libraries of the Apache Qpid project and in particular the Qpid Proton. This library is developed in C and it provides the bindings for other languages ​​including Java, Python, and PHP.

In this tutorial, we will see how to create an Ubuntu Server 12.04 LTS virtual machine on Windows Azure, install and use the Qpid Proton library to send and receive messages through the Service Bus using the AMQP protocol. Obviously, this procedure can also be used in the case of any Ubuntu 12.04 system (client or server) not necessarily on Windows Azure but also on our local PC.

Create the virtual machine on Windows Azure

First we need to create a virtual machine with Ubuntu Server 12.04 LTS  as operating system on Windows Azure. To do this, you must connect to the Management Portal and log in with your account. Once logged in, on the left side select "Virtual Machines" and click on "Create a Virtual Machine"; use the option of "Quick create" ans set the following :

  • DNS Name : DNS name for the virtual machine;
  • Image : operating system image to use. In our case is “Ubuntu Server 12.04 LTS”;
  • Size : the virtual machine “size” according to our needs;
  • New password/Confirm : password and confirmation for the default user named “azureuser”;
  • Region/Affinity Group : region (data center) in which to create our virtual machine;
Click on "Create a virtual machine" to start creating the virtual machine

01_create_vm

At the end of the creation process that takes a few minutes we will have the following confirmation.

02_vm_created

To be able to connect to the virtual machine remotely, you must know the endpoint to access via SSH and we can find it by clicking on the name of the newly created virtual machine (in my case ppatiernoubuntu) and then on the tab "Endpoints" (in my case the port is 22).

03_SSH_endpoint

Download a telnet client such as Putty to be able to connect by entering the host name and the correct port.

04_Putty

When the connected console is opened, type "azureuser" as the user name and the corresponding password that we chose when creating the virtual machine.

Requirements installation

The README file distributed with the Qpid Proton library describes in detail the procedure for installing the library itself but refers to the YUM tool that Ubuntu does not have natively available; in place of it we will use APT tool. In addition, some libraries don’t have exactly the same names as described in the README file.

In general, the first thing I do on a Ubuntu machine is to install the package "build-essential" with all the main tools for compiling. We can do that with the following command:

sudo apt-get install build-essential

The next step is to install the main dependencies including GCC (which we have already installed through the package "build-essential"), CMAKE (build system used by Qpid) and the UUID library for generating unique identifiers (a bit as our dear Guid).

sudo apt-get install gcc cmake uuid-dev

As Qpid uses SSL and the Service Bus has this prerequisite for the connection, we need to install OpenSSL in our system (which actually may already be installed).

sudo apt-get install openssl

The presence of the OpenSSL library does not include the presence of the header files and static libraries needed for development. It is therefore necessary to install the libssl-dev.

sudo apt-get install libssl-dev

Not being interested in any other language bindings, we can avoid installing the packages for Python, PHP and so on, going directly to download the library source code on the official web site. Also, do not install the dependencies that affect the automatic generation of documentation.

Download and build of Qpid Proton

From the official web site we can get one of the mirror from which to download the library in the "Downloads" section and then execute the download using WGET tool.

azureuser@ppatiernoubuntu:~$ wget http://apache.fastbull.org/qpid/proton/0.6/qpid-proton-0.6.tar.gz
--2014-04-16 07:09:52-- 
http://apache.fastbull.org/qpid/proton/0.6/qpid-proton-0.6.tar.gz
Resolving apache.fastbull.org (apache.fastbull.org)... 194.116.84.14
Connecting to apache.fastbull.org (apache.fastbull.org)|194.116.84.14|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 629147 (614K) [application/x-gzip]
Saving to: `qpid-proton-0.6.tar.gz'

100%[======================================>] 629,147     1.00M/s   in 0.6s

2014-04-16 07:09:53 (1.00 MB/s) - `qpid-proton-0.6.tar.gz' saved [629147/629147]

After download, extract the file content.

tar xvfz qpid-proton-0.6.tar.gz

Enter the new folder you just created (Qpid-proton-0.6) and create a "build" folder in which the CMAKE tool will generate the related Makefile to build the library.

mkdir build

cd build

cmake -DCMAKE_INSTALL_PREFIX=/usr ..

The executed command output will be the following

azureuser@ppatiernoubuntu:~/qpid-proton-0.6/build$ cmake -DCMAKE_INSTALL_PREFIX=/usr ..
-- The C compiler identification is GNU
-- Check for working C compiler: /usr/bin/gcc
-- Check for working C compiler: /usr/bin/gcc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- PN_VERSION: 0.6
-- Could NOT find Java (missing:  Java_JAVA_EXECUTABLE Java_JAR_EXECUTABLE Java_JAVAC_EXECUTABLE Java_JAVAH_EXECUTABLE Java_JAVADOC_EXECUTABLE)
-- Found OpenSSL: /usr/lib/x86_64-linux-gnu/libssl.so;/usr/lib/x86_64-linux-gnu/libcrypto.so (found version "1..1")
-- Looking for clock_gettime
-- Looking for clock_gettime - not found.
-- Looking for clock_gettime in rt
-- Looking for clock_gettime in rt - found
-- Looking for uuid_generate
-- Looking for uuid_generate - not found.
-- Looking for uuid_generate in uuid
-- Looking for uuid_generate in uuid - found
-- Looking for strerror_r
-- Looking for strerror_r - found
-- Looking for atoll
-- Looking for atoll - found
-- Could NOT find SWIG (missing:  SWIG_EXECUTABLE SWIG_DIR)
-- Could NOT find Doxygen (missing:  DOXYGEN_EXECUTABLE)
-- Looking for include files INTTYPES_AVAILABLE
-- Looking for include files INTTYPES_AVAILABLE - found
-- Can't locate the valgrind command; no run-time error detection
-- Cannot find ruby, skipping ruby tests
-- Cannot find both Java and Maven: testing disabled for Proton-J and JNI Bindings
-- Configuring done
-- Generating done
-- Build files have been written to: /home/azureuser/qpid-proton-0.6/build

There are some warning related to the impossibility to find the Java runtime, Swig and Doxygen. As already mentioned, we are not interested in binding with other languages ​​and automatic generation of documentation for which we can not worry about these warnings.

The last step is to use the MAKE tool to process the Makefile generated by CMAKE and install the library in the system.

sudo make install

After compilation, the library is installed in the system at /usr folder (as set in the first CMAKE command executed before) and in particular :

  • /usr/share/proton : it contains usage example;
  • /usr/bin e /usr/lib : library related files;
  • /usr/include/proton : header files to develop an application that uses the library;

Send and receive example on Service Bus

In order to test the library we can use send and receive simple examples distributed with the library itself during installation.

cd /usr/share/proton/examples/messenger/

Also in this case we can use the CMAKE tool to generate the Makefile required to build (note that you need to run as Super User).

sudo mkdir build

cd build

sudo cmake ..

sudo make all

At the end of the build we will have the two executables recv and send corresponding to two simple applications that allow you to receive and send messages to a queue via AMQP.

To do this, create a new namespace for the Service Bus on the Windows Azure management portal and also a queue for it. In my case, the namespace is qpidproton.servicebus.windows.net and queue is named “myqueue”. Through the portal we have to get two fundamental paremeters for the connection that are SharedSecretIssuer (typically "owner") and the SharedSecretValue.

05_sb_access

The address to connect to the Service Bus has the following structure:

amqps://username:password@namespace.servicebus.windows.net/queue_name

The Service Bus use an SSL connection so we have to use AMQPS instead of simple AMQP.

In order to send a message with “Hello” into the body, we have to use send application with the following command.

./send –a amqps://username:password@namespace.servicebus.windows.net/queue_name Hello

In order to receive a message from the same queue we can use the recv application with the following command.

./recv amqps://username:password@namespace.servicebus.windows.net/queue_name

The output will be as follow.

Address: amqps://username:password@namespace.servicebus.windows.net/queue_name
Subject: (no subject)
Content: "Hello"