B.2.1 Runtime Dependencies

freeDiameter depends on a number of libraries used at runtime and their corresponding header files for compilation.

Disabling SCTP Support

If you do not want to support SCTP, or your system cannot support SCTP, build freeDiameter following these steps:

1. 1. Change to the freeDiameter directory.
2. 2. Create a build directory.
3. 3. Change to the build directory.
4. 4. Type at the prompt:

   

This populates the build directory with subdirectories and files for the build. Once you have run CMake to disable SCTP, you may run CMake again, or ccmake, to make any other build configuration changes.

Interactive Mode for Configuration

freeDiameter offers flexible build configuration with ccmake, an interactive interface to CMake for configuring the build. To use this interactive interface:

1. 1. Change to the freeDiameter directory.
2. 2. Create a build directory if you have not already done so.
3. 3. Change to the build directory.
4. 4. Type at the prompt:

   

   The interactive interface will be displayed. Navigation guidance can be found at the bottom of the screen:

   

5. 5. Press the c key (configure) to list all freeDiameter variables that ccmake needs to configure. If you are missing any dependencies, errors will be displayed, but ccmake will continue on to the variables list similar to the following:

   

6. 6. Press the t key (toggle) to access a full list of the configuration options. By default many options are hidden since they usually do not need to be changed.
7. 7. Use arrow keys to navigate the list and press Enter to edit the selected option.
8. 8. Once you have configured your options, type c again to store this configuration and reiterate the process, as setting some options may have unlocked new features to be configured. That is, when enabling some extensions, new dependencies will need to be resolved.
9. 9. When finished, press the g (generate) key and ccmake will write the Makefiles that are needed for the next step. In addition, ccmake generates the freeDiameter‐host.h file in the include/freeDiameter/ directory that contains values that will be used by the freeDiameter source code, such as system parameters and features.

The following describes a few of the useful options. Refer to the embedded help text for additional information. In general all options prefixed with CMAKE_* are standard options that are documented in the CMake product:

• ALL_EXTENSIONS Setting this to ON will enable the compilation of all the provided extensions. By setting this option to OFF, you can select which extensions are built by configuring the BUILD_* options. For example, set the BUILD_APP_DIAMEAP option to ON to compile the Diameter EAP server application (the app_diameap.fdx extension).
• CMAKE_BUILD_TYPE This configures a set of flags for different profiles. When developing or testing freeDiameter, set this to Debug, which unlocks additional options (the CMake configuration process is iterative).
• CMAKE_C_COMPILER Change here if you want to use a different C compiler.
• CMAKE_INSTALL_PREFIX If the make install command is used, this configuration controls where the files must be installed. See also the INSTALL_*_SUFFIX options described in the installation section below.
• DEBUG_WITH_META Set to ON if you want logs with additional contextual information such as the thread ID, the producing function, etc.
• DEBUG_SCTP Set to ON for more verbose messages in the SCTP code of freeDiameter. Only useful when working on this part of the code.
• SCTP_USE_MAPPED_ADDRESSES Some earlier versions of the SCTP stack did not handle mixed IP and IPv6 arrays, so setting to ON will force the use of IPv4‐mapped IPv6 addresses 1 to work around the issue.
• FLEX_EXECUTABLE This specifies the flex tool that will be used to compile the Lex files.
• GNUTLS_INCLUDE_DIR, GNUTLS_LIBRARY Specify the GnuTLS header files and library to use for compiling freeDiameter. Note that the library used at runtime is selected using the default loader mechanism, which can be controlled with the LD_LIBRARY_PATH environment variable. These options are useful when working with a non‐default GnuTLS library.
• DIAMID_IDNA_REJECT Set to OFF if you do not have the GNU libidn library installed or internationalized domain names are not required in the target deployment.

Instead of using the ccmake interactive process, you can use the CMake command line directly:

B.9.1 Extended Trace

When you are developing and debugging, you may need to have more verbose output of the stack. There are two debugging options that you can apply.

First, in the CMake step, set the DEBUG_WITH_META option to ON. The DEBUG_WITH_META option adds a more precise timestamp, the name of the thread that triggered a log – useful since freeDiameter is multithreaded – and the function name, source file, and line where the log was triggered.

The second debugging option is to increase the verbosity level with the ‐dd switch when you start freeDiameter:

You will now have much more information available on what is happening in the stack:On the downside, the readability of the log decreases when these options are used; in addition, if you are storing the output on disk, the file size will increase rapidly. These options should be used only during the development phase.

The ‐dd command line switch triggers more traces to be displayed. The verbosity can be increased by adding the flag multiple times (e.g., ‐ddd), but the stack will not run properly if too much time is spent producing the traces. You can limit higher verbosity to a source file or a single function only, which may help while developing or debugging a specific module. Here is an example output:

B.9.2 Logging Diameter Messages: dbg_msg_dumps.fdx

It is useful to get a view of all the Diameter messages going in and out of the framework to understand why an application misbehaves. Although network analyzers such as Wireshark are excellent tools for such a purpose, they have some limitations if the traffic is encrypted with TLS or generated locally between two processes instead of sent over a real network. For this reason, freeDiameter comes with a Diameter message logger extension, dbg_msg_dumps.fdx.

To use the dbg_msg_dumps.fdx extension:

1. 1. Enable BUILD_DBG_MSG_DUMPS in your CMake configuration:

   

2. 2. Run make:

   

3. 3. Include the following line in the freeDiameter‐1.conf file:

   

4. 4. Start the same test as in previous section:

   

5. 5. In a separate terminal window, launch the second peer:

   

   The triggered exchange is displayed as follows for peer1:

   

6. 6. When done, press Ctrl‐C in each terminal window to halt the peers.

This format is the most readable for humans, but it is also very space‐ (and therefore time‐) consuming. Another option is to use the value 0x0040 in the configuration line, so that each message is written on a single line and may be reformatted post‐mortem. That may be a better option for pilot runs before actual deployment of an application, for example. Not only are the sent and received messages displayed by this mechanism, but also different internal events, such as peers connections and message routing.

B.9.3 Measuring Processing Time: dbg_msg_timings.fdx

The dbg_msg_timings.fdx extension measures the processing time of the local stack for incoming messages and the network time between sent requests and received answers. This is useful for checking that a local application is fast enough and for determining if more application threads are required.

1. 1. By default, the CMake option BUILD_MSG_TIMINGS is set to ON so you do not have to reconfigure the build.
2. 2. Include the following line in the freeDiameter‐1.conf file:

   

3. 3. Start the same test as in previous section. You will see the following:

   

4. 4. When done, press Ctrl‐C in each terminal window to halt the peers.

B.9.4 Viewing Queue Statistics: dbg_monitor.fdx

The dbg_monitor.fdx extension displays some statistics of the framework every 30 seconds. To add it:

1. 1. By default, the CMake option BUILD_DBG_MONITOR is set to ON so you do not have to reconfigure the build.
2. 2. Include the following line in the freeDiameter‐1.conf file:

   

3. 3. Start the same test as in previous section. You will see the following on peer1:

   

4. 4. When done, press Ctrl‐C in each terminal window to halt the peers.

The first part of the output shows the states of the queues. This can help to identify the location of bottlenecks in a given deployment and adjust the number of consuming threads accordingly. It shows the global queues first and then each peer‐specific queue.

The second part of the output shows the server sockets information. It displays the number of pending connections and may be used to detect some denial‐of‐service attacks, or identify some issues on very busy servers.

B.9.5 Understanding Routing Decisions: dbg_rt.fdx

The dbg_rt.fdx extension relates to the routing mechanism of freeDiameter. When a Diameter request message is to be sent, a specific thread selects the message's next hop. The algorithm is fairly complex. To avoid a lot of manual configuration, which is usually error prone, freeDiameter attempts to manage this task as reasonably and autonomously as possible. As a result, the default behavior of the stack takes into account a number of parameters such as the state of the connection, the applications advertised by the remote peer, the routing AVPs of the message, including Destination‐Host, Destination‐Realm, Route‐Record, and the decorated Network Access Identifier (NAI) in User‐Name.

Additional extensions can influence or change the routing decisions made by the framework; an example of such an extension is rt_load_balance.fdx, which can help to create a load balancer relay. All extensions with names starting with rt_* are related to the routing mechanism.

To be as flexible as possible, the freeDiameter routing mechanism within the framework builds a list of the possible target peers, excluding peers that are temporarily disconnected, then allocates a score to each candidate based on different parameters, as described above. The list is then passed to each routing extension, which can freely change the score of different candidates. Once all routing extensions have been invoked, the framework orders the list and sends the message to the peer with the highest score.

The purpose of the dbg_rt.fdx extension is to help understand routing decisions. For each request being routed, it simply outputs the list of candidate peers and their score to the console. To enable:

1. 1. By default, the CMake option BUILD_DBG_RT is set to ON so you do not have to reconfigure the build.
2. 2. Include the following line in the freeDiameter‐1.conf file:

   

Note that the simple test application that we have been interacting with has only one peer and thus does not provide a useful example of this extension. It is fairly easy to extend this simple setup with two additional peers in order to obtain a result similar to the following.

B.9.6 The Interactive Python Shell Extension: dbg_interactive.fdx

Since one of the design goals of freeDiameter was to enable improvements to the Diameter protocol by allowing easy prototyping of new Diameter applications, the dbg_interactive.fdx extension was created to allow developers with a limited knowledge of the C language to write freeDiameter extensions using the Python language interactively. The conversion to and from Python adds some overhead and a factor of instability; for this reason it is not recommended to use this mechanism for deploying in real production environments, but for prototyping or research activities, using the interpreter is a nice option.

1. 1. Ensure that you have the swig and swig‐python libraries installed. SWIG is a tool that connects programs written in C and C++ with a variety of high‐level programming languages like Python.
2. 2. Enable BUILD_DBG_INTERACTIVE in your CMake configuration:

   

3. 3. Run make:

   

4. 4. Include the following line in the freeDiameter‐1.conf file:

   

5. 5. Start the stack:

   

   The interactive Python interpreter, which interacts directly with the framework, will start:

   

   The Python interface is described in dbg_interactive.py.sample found in the src/doc directory, with examples for each service. This interface may not be complete, but it can be extended fairly easily.

6. 6. Press Ctrl‐D to stop the interpreter.

It becomes possible to create freeDiameter structures from Python and to register Python functions as callbacks to freeDiameter events. The following example shows how to create an AVP:

The first line retrieves a reference to the dictionary that is loaded in the framework. This dictionary contains the base protocol objects defined in the framework as well as any objects loaded by extensions such as dict_sip.fdx. The second line retrieves the definition of the Origin‐Host AVP in this dictionary. The third line creates a new, blank instance of this AVP. The following three lines create and assign a value to the AVP. Finally, the dump() function shows the the content of the AVP as defined in the framework.