[[PageOutline(2-4)]]
= Configuration =
This page gives some information on the {{{freeDiameter.conf}}} file that is required by the {{{freeDiameter}}} framework. The complete documentation is included in [source:freeDiameter/doc/freediameter.conf.sample doc/freediameter.conf.sample].
The configuration file consists in three main parts: local framework configuration, extensions, and remote connections. These parts are detailed in the next section.
The remaining of this page gives information on how to configure TLS properly, and some typical configuration files examples.
== freeDiameter.conf ==
=== Local framework configuration ===
==== Diameter Protocol parameters ====
Identity::
The first parameter in this section is {{{Identity}}}, which will be used to identify this peer in the Diameter network. The Diameter protocol mandates that the Identity used is a valid FQDN for the peer. This parameter can be omitted, in that case the framework will attempt to use system default value (as returned by {{{hostname --fqdn}}}).
Realm::
In Diameter, all peers also belong to a ''Realm''. If the realm is not specified, the framework uses the part of the Identity after the first dot.
!TcTimer, !TwTimer::
Change the default reconnection and watchdog timers.
!NoRelay::
By default, {{{freeDiameter}}} acts as a Diameter Relay Agent by forwarding all messages it cannot handle locally. This parameter disables this behavior.
!AppServThreads::
Number of parallel threads that will handle incoming application messages. This parameter may be deprecated later in favor of a dynamic number of threads depending on the load.
==== Network protocols parameters ====
Port, !SecPort, TLS_old_method::
The {{{Port}}} on which freeDiameter framework will listen for incoming Diameter connections. {{{SecPort}}} is the dedicated listening port for TLS connections, as specified by rfc3588bis. Note that {{{freeDiameter}}} supports both RFC3588's flavour TLS (using default Diameter {{{Port}}}, TLS handshake after the CER/CEA exchange) and rfc3588bis's flavour (using a dedicated {{{SecPort}}} where CER/CEA exchange is also TLS protected). {{{TLS_old_method}}} sets a default TLS flavour for outgoing connections, that can be overwritten for each peer.
No_TCP, No_SCTP, Prefer_TCP, No_IP, No_IPv6::
The default is to listen for IP & IPv6 and TCP & SCTP incoming connections, and attempt SCTP first when contacting another peer. Change these parameters to modify this default behavior. Parameters for outgoing connections can also be specified for each peer.
SCTP_streams::
Overwrite the number of SCTP streams. This value should be kept low, especially if you are using TLS over SCTP, because it consumes a lot of resources in that case. See tickets [ticket:19] and [ticket:27] for some additional details on this.
!ListenOn::
Specify the addresses on which to bind the listening server. This must be specified if the framework is unable to auto-detect these addresses, or if the auto-detected values are incorrect. Note that the list of addresses is sent in CER or CEA message, so one should pay attention to this parameter if some adresses should be kept hidden.
==== TLS parameters ====
TLS_Cred::
This parameter is '''mandatory''', even if it is possible to disable TLS for peers connections. A valid certificate for this Diameter Identity is expected.
Other TLS_* parameters are optional but should usually be specified.
See [#tls_tuto How to configure TLS] bellow for instructions on how to get started with this.
=== Extensions ===
!LoadExtension::
Specify either an absolute path, or a relative path, in which case the file will be searched in the active directory first, and in [wiki:Installation#cmakeflags INSTALL_EXTENSIONS_SUFFIX] afterwards. The configuration file name is optional. If specified, it also falls back to files in [wiki:Installation#cmakeflags DEFAULT_CONF_PATH].
See the list of extensions on page [wiki:Extensions]. Note that some extensions are not built by default, refer to [wiki:Installation] for details.
=== Remote connections ===
!ConnectPeer::
Declare a remote peer to which this peer must maintain a connection. In addition, this allows specifying non-default parameters for this peer only (for example disable SCTP with this peer, or use RFC3588-flavour TLS).
Note that by default, if a peer is not listed as a ''!ConnectPeer'' entry, an incoming connection from this peer will be rejected. If you want to accept incoming connections from other peers, see the [wiki:acl_wl.fdx] extension which allows exactly this.
== How to configure TLS == #tls_tuto
Because Diameter protocol conveys sensible information in terms of privacy and security (such as user location, cryptographic material, ...) it must never be sent "in clear" on the wire. The Diameter specification allows either IPsec protection or TLS protection to be used to protect its messages.
There is currently no way for the freeDiameter framework to discover if an IPsec tunnel is setup with any given peer -- it would require for example an API to query the IKEv2 component, but there is no standard API for this.
For these reasons, the {{{freeDiameter}}} policy is to mandate the configuration of valid TLS credentials. Afterwards, TLS can be disabled for each connection in the ''!ConnectPeer'' directive.
{{{Priority}}} setting::
The configuration file allows to specify {{{TLS_Prio}}} parameter. This parameter is directly passed to GNU TLS library, it is not interpreted by freeDiameter. You should check [http://www.gnu.org/software/gnutls/manual/gnutls.html#gnutls_005fpriority_005finit the relevant GNU TLS documentation] for more information on this Priority string.
The following sub-sections show how to configure the TLS credentials properly, depending on your environment.
=== Real PKI ===
If you already have a PKI set up for your Diameter nodes (for example when you join a Diameter consortium), the following hints will help you configuring {{{freeDiameter}}}. If you just want to setup an experimental testbed, please check the next sub-section.
We use the following imaginary PKI hierarchy in this example:
{{{
Our realm: example.net | Other realms: partner1, partner2
=======================================================================
my_root_ca ----------- my_partner1_ca.example.com ------ ....
| |
my_group_ca .....
| |
my_diameter_peer remote_peer
}}}
In case of real PKI (or set of PKIs) the first thing you will need is the list of trusted root Certificate Authorities certificates. Concatenate all these different certificates into one file, as follow:
{{{
#!sh
$ cat my_root_ca.example.net.pem \
my_partner1_ca.example.com.pem \
my_partner2_ca.example.org.pem > ca.pem
}}}
From this point, we assume that you have a file '''ca.pem''' that contains all the trust anchors for your Diameter network (at least for the peers you may connect to).
You should do the same with Certificate Revocation Lists (CRL), with a script to update the file on a regular basis. Note however that currently freeDiameter does not support reloading the CRL (needs improvement, see [ticket:29]). This CRL is saved as '''crl.pem'''.
You need a private key for your Diameter peer. There are many tools to generate such a key. You can use for example ''certtool'' from GNUTLS, or ''openssl''. Once you have generated your private key, save it as '''my_key.pem'''. This is the command with openssl:
{{{
#!sh
$ openssl genrsa -out my_key.pem 2048
}}}
Then, generate a Certificate Signing Request (CSR), that you will send to your PKI administrator. Depending on your realm's PKI policy, the content of the CSR may vary. However, the following points are important (confirm with your PKI administrator, since he can overwrite everything that is set in the CSR in the certificate):
* The Common Name (CN) must be your Diameter Identity ('my_diameter_peer.example.net' in our example). Support for domain-wide certificates has not been tested yet.
* The key usage must allow for TLS client and server usages.
The following example command will generate a CSR after asking a few questions:
{{{
#!sh
$ openssl req -new -out csr.pem -key my_key.pem
}}}
Once you have this CSR, send it to your PKI administrator for certificate signing. In our example, the administrator will use "my_group_ca.example.net" CA to sign the request and issue the certificate, then give this certificate to you, as file {{{cert.pem}}}. In real life, this step usually requires additional checks / paperwork.
If the certificate is not signed directly by the root CA in your realm, you must retrieve all the intermediate CA certificates. In our example, there is only "my_group_ca", but it is possible to have several intermediate CAs. Save all these certificates, in addition to your final certificate, in one file, as follow (the order should be the hierarchical order from bottom to top):
{{{
#!sh
$ cat cert.pem my_group_ca.pem \
> certchain.pem
}}}
Now, you are all set. Configure {{{freeDiameter}}} as follow:
{{{
TLS_Cred = "certchain.pem", "my_key.pem";
TLS_CA = "ca.pem";
TLS_CRL = "crl.pem";
TLS_DH_Bits = 2048;
}}}
=== Testbed ===
In case you are setting a simple experiment with no real traffic expected, the following instructions will help you getting started. However, these do NOT provide a valid secure environment for real operation.
The first sub-section explains how to use a self-signed certificate to make freeDiameter framework happy, and then disable TLS for all connections. The second sub-section explains how to use self-signed certificates to actually use TLS protection in your testbed.
==== Without TLS ====
The most simple situation is when you don't want to use TLS for your communications in your testbed. In that case, you only need to create a ''self-signed certificate'' that corresponds to the Diameter Identity of your peer, and then specify the "No_TLS;" flag for your connections.
* Create the self-signed certificate.
This can be done with many tools, here is an example using ''openssl''.
{{{
#!sh
$ openssl req -new -batch -x509 -days 3650 -nodes \
-newkey rsa:1024 -out cert.pem -keyout privkey.pem \
-subj /CN=my.diameter.identity
}}}
This command should generate a self-signed certificate with Common Name "my.diameter.identity" (change to match your real Identity).
* Create a Diffie-Hellman file.
Although not mandatory, it is recommended to create a DH file, so that the framework does not generate a new one each time it starts.
This again can be done with GNUTLS's ''certtool'' or OpenSSL. Here is an example command with the later:
{{{
#!sh
$ openssl dhparam -out dh.pem 1024
}}}
* Configure freeDiameter.
This is the corresponding part of {{{freeDiameter.conf}}}:
{{{
TLS_Cred = "cert.pem", "privkey.pem";
TLS_CA = "cert.pem";
TLS_DH_File = "dh.pem";
ConnectPeer = ... { No_TLS; };
}}}
Note that it is possible (but not recommended) to have the private key and certificate stored in the same file.
==== With TLS ====
* Case of only two peers
If your testbed consists of only two peers, you may follow the same instructions as in previous section to generate the self-signed certificate on each peer. Then, the following additional step must be performed on both peers:
{{{
#!sh
$ cat peer1.cert.pem peer2.cert.pem > ca.pem
}}}
Then configure freeDiameter.conf with:
{{{
TLS_Cred = "cert.pem", "privkey.pem";
TLS_CA = "ca.pem";
}}}
* Case of more peers
In order to avoid copying the self-signed certificates between all peers (you'd have to copy each peer certificate to all other peers), it is probably easier to set up a fake CA and have this CA sign all your peers certificates.
It is the scenario we are using in our testbed, therefore you might find the following resources useful:
[source:freeDiameter/contrib/PKI contrib/PKI]::
This folder contains some scripts that can help you managing this "fake" CA. You will find a few more details in the [source:freeDiameter/contrib/README contrib/README] file. The easiest way is to have a storage shared with all your peers, and have this fake PKI files reside in this storage. Otherwise you may find the {{{make ship}}} target from {{{ca_script2}}} script in this directory useful.
[source:VirtualTestbed/ca/rebuild_tree.sh rebuild_tree.sh]::
This is the script we use to generate all the certificates of our test machines. It uses the Makefile from {{{ca_script2}}}. It shows an example of how to use this script to generate all the peers certificates. Check the script [source:VirtualTestbed/scripts/ca-install.sh ca-install.sh] for an example of how we use the generated certificates in each node.
== Configuration examples ==
You can find many configuration files examples in our testbed [source:VirtualTestbed/conf here]. Some of the examples are explained in the [wiki:Screenshots] page in more details. You may also check the [wiki:TBEAP EAP Testbed explanation] page that shows how to perform EAP authentication and accounting with freeDiameter.
Here is a typical example of configuration:
{{{
# -------- Local ---------
# Uncomment if the framework cannot resolv it.
#Identity = "backend.localhost";
# TLS configuration (see previous section)
TLS_Cred = "cert.pem" , "privkey.pem";
TLS_CA = "ca.pem";
# Limit the number of SCTP streams
SCTP_streams = 3;
# -------- Extensions ---------
# Uncomment (and create rtd.conf) to specify routing table for this peer.
#LoadExtension = "rt_default.fdx" : "rtd.conf";
# Uncomment (and create acl.conf) to allow incoming connections from other peers.
#LoadExtension = "acl_wl.fdx" : "acl.conf";
# Uncomment to display periodic state information
#LoadExtension = "dbg_monitor.fdx";
# Uncomment to enable an interactive Python interpreter session.
# (see doc/dbg_interactive.py.sample for more information)
#LoadExtension = "dbg_interactive.fdx";
# Load the RFC4005 dictionary objects
LoadExtension = "dict_nasreq.fdx";
# Load RFC4072 dictionary objects
LoadExtension = "dict_eap.fdx";
# Load the Diameter EAP server extension (requires diameap.conf)
LoadExtension = "app_diameap.fdx" : "diameap.conf";
# Load the Accounting Server extension (requires app_acct.conf)
LoadExtension = "app_acct.fdx" : "app_acct.conf";
# -------- Peers ---------
# The framework will actively attempt to establish and maintain a connection
# with the peers listed here.
# For only accepting incoming connections, see the acl_wl.fx extension.
ConnectPeer = "nas.localhost" { No_TLS; };
ConnectPeer = "relay.localhost" { ConnectTo = "2001:DB8:1234::5678"; };
}}}
----