Installation

First, please check that your system meets the Requirements for freeDiameter.

Installing from pre-compiled packages

When available, this is the easy way to install freeDiameter framework on your machine, because it takes care of all the software dependencies for you.

• Debian and Ubuntu packages information.
• Fedora, CentOS, and RHEL packages information.
• OpenWRT package information.
• NetBSD, DragonFly BSD and MirBSD packages information.

Installing from source

If there is no pre-compiled package for your platform, or if you need to change some compilation options, please follow these instructions.

Obtaining the source code

The recommended method is to use ​Mercurial SCM to retrieve the source code. This allows to update easily to latest development version, keep track of your changes, and so on.

 # The first time, you need to clone the repository as follow:
$ hg clone http://www.freediameter.net/hg/freeDiameter

 # Later when you want to retrieve the latest changes: 
$ hg pull -u

 # To retrieve a specified tagged version (see with 'hg tags')
$ hg update 1.1.0-rc3

Alternatively, you can retrieve the source code by HTTP protocol as follow:

• Browse to ​http://www.freediameter.net/hg/freeDiameter
• Select any revision in the changes or tags lists (default is 'tip', the latest)
• Then click on one of the bz2, zip, or gz link at the top.
• You can alternatively directly access the following URL to retrieve the most recent source: ​http://www.freediameter.net/hg/freeDiameter/archive/tip.tar.gz.

Configuring the build

This step is equivalent to the traditional ./configure except that we use ​CMake which provides a much nicer interface. You will therefore need to install cmake if it is not yet available on your machine. Note that there are several nice Graphical User Interfaces (GUI) available for CMake.

It is highly recommended to build freeDiameter outside of the source repository.

$ mkdir fDbuild
$ cd fDbuild
$ cmake [CMAKE_OPTIONS] /path/to/freeDiameter/source

Note that you can either specify the CMAKE_OPTIONS directly on the command line, or later by running:

$ cmake /path/to/freeDiameter/source
$ make edit_cache

The following options are available when configuring freeDiameter:

Parameters to control file paths

CMAKE_INSTALL_PREFIX

This is the prefix under which all freeDiameter files will be installed. Default is /usr/local. Overwrite on the command line with for example -DCMAKE_INSTALL_PREFIX:STRING=/usr.

DEFAULT_CONF_PATH

This is the default directory where the freeDiameter framework will look for its configuration file, when specified as a relative file name. The default value is ${CMAKE_INSTALL_PREFIX}/etc/freeDiameter.

INSTALL_HEADERS_SUFFIX

Where the development header files are installed, relative to ${CMAKE_INSTALL_PREFIX}. The default is include/freeDiameter.

INSTALL_DAEMON_SUFFIX

Where the binary executable files are installed, relative to ${CMAKE_INSTALL_PREFIX}. The default is bin.

INSTALL_LIBRARY_SUFFIX

Where the freeDiameter framework libraries are installed, relative to ${CMAKE_INSTALL_PREFIX}. The default is lib.

INSTALL_EXTENSIONS_SUFFIX

Where the freeDiameter extensions files are installed and searched at runtime, relative to ${CMAKE_INSTALL_PREFIX}. The default is ${INSTALL_LIBRARY_SUFFIX}/freeDiameter.

Parameters for dependencies

It is possible to overwrite the default location for libraries and tools dependencies. We are not going to give an exhaustive list here, here are two examples:

Use an alternate GNUTLS library installed under /usr/local

-DGNUTLS_INCLUDE_DIR:PATH=/usr/local/include
-DGCRYPT_INCLUDE_DIR:PATH=/usr/local/include
-DGNUTLS_LIBRARY:FILEPATH=/usr/local/lib/libgnutls.so

Use a different flex executable

-DFLEX_EXECUTABLE:FILEPATH=/usr/local/bin/flex

Parameters to control the framework behavior

CMAKE_BUILD_TYPE

This is specifies the set of flags that are passed to the C compiler and linker. Valid build types are:

• "Debug" -- recommended for developers,
• "Profiling"
• "DebugValgrind" -- use to monitor execution with valgrind
• "DebianPackage" -- use for releases
• "MaxPerformance" -- strips all debug support including error messages, use only for performance tests.

DISABLE_SCTP (BOOL)

Set this option to ON to strip all SCTP-related code from the framework. The default is OFF.

SCTP_USE_MAPPED_ADDRESSES (BOOL)

Previous implementations of the SCTP socket extensions did not have a proper handling of mixed IP and IPv6 situations. This parameter allows to pass all IP addresses in IPv6-mapped format, suppressing the problems. However, with recent implementations, having native IP format should not be an issue.

DIAMID_IDNA_IGNORE (BOOL), DIAMID_IDNA_REJECT (BOOL)

By default, the freeDiameter framework accepts Diameter Identities and Realms provided in native language (UTF-8 encoded), and process these according to the IDN transformation rules (stringprep) (you know, that xn--... thing). It allows to use IDN names in the configuration file. However, by specifying one of these options, you can change this behavior to either pass blindly (will send invalid AVPs in the network) or reject (the framework will terminate) any IDN. Either option removes the dependency of the framework on the GNU libidn library.

Parameters to control extensions build

ALL_EXTENSIONS (BOOL)

Set this value to ON in order to build all available extensions. You can always customize the extensions you will actually load in the framework configuration file. Beware however that some extensions may have additional requirements (such as database support) and the compilation time will increase when this option is set. When the option is not set, you can select/deselect the individual extensions with the next option:

BUILD_* (BOOL)

You can select the extensions individually with these options. For example, set BUILD_APP_ACCT:BOOL=ON in order to build the app_acct.fdx extension.

Parameters for debug / development only

DEBUG_SCTP (BOOL)

If SCTP is not disabled, set this option to turn on extra debug messages in SCTP code. Useful for debugging only.

ERRORS_ON_TODO (BOOL)

The TODO("...") macro is used in the code for incomplete features. Turn on this option to trig a compilation error wherever this macro appears, to find it easily (if you don't like grep)

BUILD_TESTING (BOOL)

Set this value to ON in order to build the tests, then run with make test command.

TEST_TIMEOUT

If this value is set (to an integer), it overwrites the default timeout value for the tests. The default is 120 seconds.

TEST_APP_ACCT (BOOL)

If BUILD_TESTING and BUILD_APP_ACCT are true, this option can be selected to build the additional test for app_acct.fdx. This test requires a PostgreSQL environment installed, this is why it is separated. You also need to specify the TEST_APP_ACCT_CONNINFO variable to allow the test to access its database, as for example TEST_APP_ACCT_CONNINFO="host=localhost port=5432 dbname=acct user=acct".

Compiling

Hopefully, once you have completed the cmake configuration, you only need to run:

$ make

This will compile all source files and produce the binaries.

If you want a more detailed output, you can also use:

$ make VERBOSE=1

Installing

Once the compilation is complete, you can install in the configured paths with:

$ make install

(this might require sudo depending on the configured target directories)

Please note that there is no make uninstall target generated by CMake. Refer to CMake documentation to find how to cleanly remove all that has been installed.

Note that the framework can be run without installation, as long as the configuration file contains the full path to extensions that must be loaded.

---