Test Application

The test_app.fdx extension is similar to the "ping" utility, for freeDiameter. It allows a client to send a Diameter message to a server, which echoes it. The client then receives the answer and displays the duration of the exchange.

Error: Failed to load processor graphviz

No macro or processor named 'graphviz' found

test_app.fdx allows easy configuration of the routing AVPs in the test message, such as Destination-Realm and Destination-Host, which make it also a convenient tool to check the routing behavior of your Diameter infrastructure.

test_app.fdx provides some additional information, such as the return code value of the answer message. It checks in addition that the answer contents is consistent with the matching request.

This application is not standard. Therefore, at the moment, it cannot be used with any implementation except freeDiameter. However, third-party agents should be able to relay the message without interpreting its contents. Only the client and server must be freeDiameter.

Configuration

test_app.fdx configuration file is optional. If no configuration file is specified, all options will be set with their default parameters, which should be sufficient in many simple test situations.

The complete configuration documentation for test_app.fdx can be found in the source package: [source:freeDiameter/doc/test_app.conf.sample test_app.conf.sample].

Here is a summary of the most useful configuration directives:

dest-realm

By default, the Destination-Realm in the message will be set to the same realm as the client's. If you want your message to reach a peer in a different realm, you must set this value.

dest-host

The Destination-Host is usually not provided. The message would therefore reach any server in the Destination-Realm that supports the Test application (i.e. executes test_app.fdx in server mode). If you want to message to reach a particular peer, setting this value will help a lot.

user-name

In some situations, the User-Name AVP can be also used for routing. For example, freeDiameter has a native support for Decorated NAI as specified in ​RFC4282, ​RFC5729. To check this behavior, one would specify a value such as user-name = "home.realm.net!user@proxy.realm.net";.

Usage

In order to "trig" the client to send the Test request, a signal must be sent to the daemon. The signal is configurable, the default is SIGUSR1. You can check this simple script also, which will send the signal and can do it in loops (of 10 seconds): [source:VirtualTestbed/scripts/freeDiameter-trig.sh freeDiameter-trig.sh].

If you require a different trigger for your particular test, you may change the trigger mechanism in function ta_cli_init(void) of file [source:freeDiameter/extensions/test_app/ta_cli.c ta_cli.c]. Please check this discussion for more details: ​Internal trigger of test_app.

Output

There are three events in test_app.fdx: message sent, echoed, received. When each of these events occur, a message is written on stderr. Bellow is a short explanation about the contents of each of these messages.

Message sent

On the client, when the test_app.fdx action is trigged, you should see a line like this:

SEND 2ae8944a to 'simple.testbed.aaa' (-)

This line shows that a Test request is being sent. This Test request contains a Test-AVP in addition to the normal AVPs from Diameter Base protocol. This Test-AVP contains a random Unsigned32 value, let's call it a nonce. When the message is ready for sending, the extension saves the current time and the nonce value, then displays the message. The content is:

SEND <nonce value> to '<destination realm>' (<destination host | '-' >)

For example, the line given as example at the top of this paragraph should be read as "Sending now a Test request with nonce value 0x2ae8944a and Destination-Realm AVP set to 'simple.testbed.aaa', with no Destination-Host AVP".

Message echo'ed

If the Test request reaches the test_app.fdx server, this server will issue a message like this:

ECHO Test-Request received from 'cli.simple.testbed.aaa', replying...

At this time, the only information displayed is the content of the Origin-Host AVP. If this AVP is not included in the message (which is probably abnormal) then no_Origin-Host will be displayed instead. This is summarized as:

ECHO Test-Request received from <origin host | 'no_Origin-Host'>, replying...

After this message is output, the server creates an answer with Result-Code set to DIAMETER_SUCCESS and copies the nonce value in the answer, then sends this new message.

Answer received

When an answer corresponding to a sent Test request reaches the client, whether it is a reply generated by the server or an error generated by an intermediary node or layer, a message line will be displayed. Here is an example in case of success:

RECV 2ae8944a (Ok) Status: 2001 From 'serv.simple.testbed.aaa' ('simple.testbed.aaa') in 0.022925 sec.

Let's decompose this line in its components:

RECV <nonce info> Status: <error code> From <origin host> (<origin realm>) in <duration>

First comes the nonce information: if the answer contains a Test-AVP, its value is displayed. If this value matches the saved nonce, '(Ok)' is displayed, otherwise it is '(PROBLEM)'.

The error code is simply the content of the Error-Code AVP. For example, 2001 is the value of DIAMETER_SUCCESS. For a list of possible values and their meaning, you may refer to ​IANA Authentication, Authorization, and Accounting (AAA) Parameters registry. In case the Error-Code AVP is not in the message (which would be invalid), the line would display 'no_Result-Code' instead. The following error codes are quite common (this list is not exhaustive):

• 2001 : DIAMETER_SUCCESS
• 3002 : DIAMETER_UNABLE_TO_DELIVER
• 3010 : DIAMETER_UNKNOWN_PEER

Then comes the Origin-Host and Origin-Realm AVP contents indicating which node produced the answer -- which is useful in particular in case of error. As previously, although it is an invalid situation, the absence of one of these AVP would be shown with the message no_Origin-Host or no_Origin-Realm.

The last piece of information displayed is the time elapsed between the emission of the request and reception of the answer. This might be useful for example to measure the reaction time of your infrastructure in case of failover.

Troubleshooting

Here are a few things to check if you cannot get your test_app.fdx to work as expected.

Application Id, Command Id, AVP Id, Vendor Id

If you have changed the default value of any of these parameters, you must ensure that they are the same on the client and server. A different Application Id will probably result in an error DIAMETER_UNABLE_TO_DELIVER or DIAMETER_APPLICATION_UNSUPPORTED (depending if Relay is enabled in the daemon); a different Command Id will give a DIAMETER_COMMAND_UNSUPPORTED error, and the different Test-AVP or Vendor Id will probably prevent the server to find the nonce in the message.

Connection status:

Before any Diameter message can be sent to a peer in freeDiameter, the connection status must be STATE_OPEN. For this reason, it is for example impossible to send the Test request while the extension is initializing. You might use dbg_monitor.fdx extension to help you check the status of the connection.

Routing parameters:

Be sure to specify the Destination-Realm and eventually Destination-Host values as appropriate for your setup. If your two nodes are not in the same realm (might happen accidentally if you use IP addresses for example), the default configuration will prevent the request to reach the server.

---