freeDiameter
TutorialIn the real world, Diameter applications are deployed on multiple machines within a single organization or across different organizations and networks. Because such a multi‐machine environment is expensive to set up and challenging to maintain, this book's examples use an environment based on virtual machines.
A virtual machine (VM) is an emulation of a complete computer system with its own operating system and applications. A VM is created using virtualization software that runs on a physical machine. The virtualization software allows for quick and easy configuration of the VM, for example adding a new network interface is just a matter of a few clicks. The interface between the VM (called the guest) and the system running the virtualization software (your computer, the host) is clearly delimited, so there is no problem, for example, for a machine running Microsoft Windows 10 to host a guest that is running Linux and another guest that is running FreeBSD. Using such a VM environment, we can create the network between Diameter peers for our tests, without the need for several physical computers and network equipment. All the examples in the book can run easily on a regular office laptop. However, we recommend that you use a large screen, or several screens, in order to display the multiple VM screens simultaneously.
We have pre‐configured a VM image containing freeDiameter
to reduce your work effort, and we will walk you through the steps to run the examples. At a high level, these steps are as follows:
freeDiameter
with the correct profile.Our VM runs under the Ubuntu operating system. We have chosen Ubuntu mostly because it seems more (new‐)user‐friendly. For more information about working with Ubuntu, please visit https://help.ubuntu.com.
We have chosen Oracle VirtualBox as the virtualization software application. VirtualBox, which is freely available and can be used on Windows, OS X, Linux, and Solaris, should allow you to run all the examples without having to go through painful operating system installations and network configurations.
To install Oracle VirtualBox, visit https://www.virtualbox.org and follow the instructions to retrieve the correct package for your environment and install the application.
You may also use another virtualization software application that supports Open Virtualization Format (OVF) to launch the provided VM.
If you do not want to or cannot use the provided VM environment, you can set up your own environment. Visit the official freeDiameter
website at http://www.freediameter.net where you can find the source code and guidance for building and configuring freeDiameter
. Note that while freeDiameter
source code can be compiled easily on most POSIX systems, it relies on several libraries for specific operations, for example the GNU TLS library for the cryptography, the GNU IDN library for international domain names support, etc. As a result, freeDiameter
can only be used (with reasonable effort) on systems that provide these dependencies within their package system. Fortunately, most modern operating systems provide the necessary packages.
The building and configuration information provided by the freeDiameter
website can also be useful if you want to develop your own Diameter applications on top of this framework. Along with the examples you will also find a description of the network topology used in the respective tests. We believe that this will help you to recreate the setup in a different environment. This book is, however, not a tutorial for configuring IP‐based networks. If you want to go beyond the examples described in the book you will have to consult books covering IP fundamentals.
Download the VM image freeDiameter.ova
from this book's website at https://diameter‐book.info. The file is rather large (2 GB) and may take some time to download.
freeDiameter
freeDiameter.ova
file that you downloaded and click Continue. A summary of the configuration of the imported VM image is displayed. You can review this information then click Import without changing anything.Once the process completes, a new VM called freeDiameter
appears in the list in the main VirtualBox application screen.
freeDiameter
VM booting – exactly as if it was the physical display of a separate machine, starting after power on.Once the boot sequence is complete, the VM will enter the Ubuntu desktop environment.
freeDiameter
VM, click the small gear icon at the upper right of the VM screen, then click the Shut Down… option. The VM window will disappear once the shutdown sequence completes.You are now ready to set up your first example network topology.
The VM's Internet access is enabled by default to make it easy for you to install additional software packages you may want, such as your favorite text editor.
To minimize the risk of breaking the compatibility with the included freeDiameter
, be careful with any system updates of the VM. In general, installing the security updates or additional packages should not cause issues, but if you are upgrading the base Ubuntu distribution to a newer release, some scripts included in this VM may not work as expected and freeDiameter
may need to be updated to support changes in dependent packages.
If you are uncertain about deploying updates, it is safer not to upgrade any package and to avoid using this VM environment to browse the Internet, instead using your host machine for browsing.
It is important to note that the above guidance applies only to your experimental Diameter setups using the provided VM. For operational deployments, you must have a software update process in place to ensure that security vulnerabilities are patched as quickly as possible.
Our first example topology consists of two Diameter peers, named client.example.net and server.example.net, that can exchange data over an IP network, as shown in Figure A.1. The clouds conventionally represent an unspecified IP network, and the small planet represents the Internet, although in our VM environment the communication will be contained in virtual network links. We will create this topology step by step in this section.
We will start by creating the client.example.net peer.
freeDiameter
VM is switched off.Note: Do not delete the master freeDiameter
VM image, or all linked clones will stop functioning.
freeDiameter
VM in the list. From the Machine menu, select Clone. On the New machine name screen, enter ‘fD‐client.example.net’ as the new machine name, and enable the Reinitialize the MAC address of all network cards option. This is important, as otherwise no communication between the cloned machines will be possible.$
followed by a blinking cursor; this is called the shell prompt, and the blinking cursor indicates that it is ready to handle a new command that you will type on your keyboard.When we describe the commands that must be entered in the terminal we will start the line with a bold dollar sign. Enter the command as given after the bold dollar sign.
As the script nw_configure.sh
executes, the following lines will be displayed:
The network has now been configured successfully. You can no longer access the Internet from this VM.
freeDiameter
instance that will run on this machine, enter the following command (the parameter starts with the digit 1, not the lower case letter L):The fD_configure.sh
script builds and configures the freeDiameter
framework and takes some time to complete, outputting many lines of messages. When the terminal returns to the prompt, a fresh set of freeDiameter
framework binaries (libfdproto, libfdcore, and freeDiameterd) can be found in the folder /home/freediameter/freeDiameter/test/
, along with configuration files specific to our first test scenario.
The first VM instance, fD‐client.example.net, is now ready to use, and we will next prepare the second machine of our topology, server.example.net.
You can return to the previous network configuration that enables Internet access by using the command:
However, you must reapply the client.example.net configuration before continuing with these examples.
The creation of this other VM is similar to the creation of the fD‐client.example.net VM.
freeDiameter
VM is switched off. The fD‐client.example.net VM can be left running.freeDiameter
VM in the list. From the Machine menu, select Clone. On the New machine name screen, enter ‘fD‐server.example.net’ as the new machine name, and enable the Reinitialize the MAC address of all network cards option.The test network topology is now configured.
freeDiameter
framework on the server:You can test the IP configuration by running the following command:
You will see a new line of information displayed each second. This line shows the duration of a simple round trip exchange of data over the network with the client.example.net machine. If a time value is displayed, like above, the network configuration on both the client and the server are correctly applied for this test. At the bottom of the VM window, the network sign blinks periodically to show network activity on both virtual machines, emphasizing the exchange of data over the virtual network.
To stop the ping command, press Ctrl‐C. The terminal will display a summary of the packet exchanges, then will return to the prompt, ready to receive the next command.
These lines are produced by the freeDiameter
framework. Each line starts with a timestamp, followed by an indicator of the importance of the line (NOTI for notifications, ERROR for errors, etc.) and the message itself. The above capture shows the initialization sequence of freeDiameter
, starting with the different component versions displayed, followed by a summary of the configuration, and finally a notification that the initialization is complete, which means the framework is ready to handle Diameter connections.
This machine is configured to establish a Diameter connection with client.example.net, so it attempts to establish a connection to that machine periodically. The attempts are failing because there is no Diameter stack running on the other machine to accept the incoming connection.
freeDiameterd
command in the fD‐client.example.net VM window:Note that the following additional lines have appeared in parallel on the fD‐server.example.net screen:
Here is what has happened: after the initialization of freeDiameter
on the fD‐client.example.net VM, the client attempted to connect to server.example.net and succeeded. The client sent a Diameter message called Capabilities‐Exchange‐Request (line starting with SND) to the server, where it appears as a received (RCV) message. The server sends the corresponding answer, Capabilities‐Exchange‐Answer, and each peer displays the information that it is now CONNECTED TO the other peer, and that the connection is moved to the STATE_OPEN state. From this point, the peers are able to exchange Diameter traffic. If a peer does not receive a message on the connection during a configured period (30 seconds by default), it sends a message called Device‐Watchdog‐Request to verify that the connection is still alive. You can observe this if you wait for a few seconds:
freeDiameter
instance running on the fD‐client.example.net VM, ensure that its terminal window has the focus, then enter Ctrl‐C.The above log shows the shutdown sequence of freeDiameter
initiated when we press Ctrl‐C. We can see that the connection is not closed immediately, but a final Disconnect‐Peer‐Request message is sent to the other peer, and connection is kept open waiting for the corresponding answer. This final exchange is also part of the Diameter base protocol and allows the remote peer some control over the connection termination, for example by sending pending messages. After the answer has been received, freeDiameter
terminates and the Terminal prompt reappears.
On the other VM screen, you can see that new periodical attempts are made to re‐establish the connection.
freeDiameter
instance running on the fD‐server.example.net VM by ensuring that its terminal window has the focus, then entering Ctrl‐C.This concludes our first experiment, in which we have configured two VMs and let them establish a Diameter link using the Diameter Base protocol. We have seen three different Diameter commands in action: Capabilities‐Exchange at the initial connection establishment, Device‐Watchdog exchanged periodically over the open connection, and Disconnect‐Peer when the connection is being closed by one of the peers.