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.
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.