Navigation


Changes between Initial Version and Version 1 of test_app.fdx


Ignore:
Timestamp:
Jun 18, 2010, 5:04:51 PM (14 years ago)
Author:
Sebastien Decugis
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • test_app.fdx

    v1 v1  
     1[[PageOutline(2-4)]]
     2== Test Application ==
     3
     4The {{{test_app.fdx}}} extension is similar to the "ping" utility, for freeDiameter.
     5It 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.
     6
     7{{{
     8#!graphviz
     9digraph G {
     10    graph [bgcolor="#E8E8E8C8"]
     11    rankdir = "LR"
     12    node [shape=box];
     13    edge [color=blue];
     14    cli [
     15         label="client"
     16    ]
     17    serv [
     18         label="server"
     19    ]
     20    cli -> serv [label="Request"];
     21    serv -> cli [label="Answer"];
     22}
     23}}}
     24
     25
     26{{{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.
     27
     28{{{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.
     29
     30This 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.
     31
     32=== Configuration ===
     33
     34{{{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.
     35
     36The 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].
     37
     38Here is a summary of the most useful configuration directives:
     39
     40 dest-realm::
     41   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.
     42
     43 dest-host::
     44   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.
     45
     46 user-name::
     47   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 [http://tools.ietf.org/html/rfc4282 RFC4282], [http://tools.ietf.org/html/rfc5729 RFC5729]. To check this behavior, one would specify a value such as {{{user-name = "home.realm.net!user@proxy.realm.net";}}}.
     48
     49=== Usage ===
     50
     51In 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].
     52
     53If 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: [http://lists.freediameter.net/pipermail/help/2010-June/000001.html Internal trigger of test_app].
     54
     55=== Output ===
     56
     57There 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.
     58
     59==== Message sent ====
     60On the client, when the {{{test_app.fdx}}} action is trigged, you should see a line like this:
     61{{{
     62SEND 2ae8944a to 'simple.testbed.aaa' (-)
     63}}}
     64This line shows that a Test request is being sent.
     65This Test request contains a Test-AVP in addition to the normal AVPs from Diameter Base protocol.
     66This Test-AVP contains a random Unsigned32 value, let's call it a ''nonce''.
     67When the message is ready for sending, the extension saves the current time and the nonce value, then displays the message. The content is:
     68{{{
     69SEND <nonce value> to '<destination realm>' (<destination host | '-' >)
     70}}}
     71For 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".
     72
     73==== Message echo'ed ====
     74If the Test request reaches the {{{test_app.fdx}}} server, this server will issue a message like this:
     75{{{
     76ECHO Test-Request received from 'cli.simple.testbed.aaa', replying...
     77}}}
     78At 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:
     79{{{
     80ECHO Test-Request received from <origin host | 'no_Origin-Host'>, replying...
     81}}}
     82
     83After 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.
     84
     85==== Answer received ====
     86When 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:
     87{{{
     88RECV 2ae8944a (Ok) Status: 2001 From 'serv.simple.testbed.aaa' ('simple.testbed.aaa') in 0.022925 sec.
     89}}}
     90Let's decompose this line in its components:
     91{{{
     92RECV <nonce info> Status: <error code> From <origin host> (<origin realm>) in <duration>
     93}}}
     94First 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)'.
     95
     96The 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 [http://www.iana.org/assignments/aaa-parameters/aaa-parameters.xml#aaa-parameters-4 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):
     97 * 2001 : DIAMETER_SUCCESS
     98 * 3002 : DIAMETER_UNABLE_TO_DELIVER
     99 * 3010 : DIAMETER_UNKNOWN_PEER
     100
     101Then 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}}}.
     102
     103The 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.
     104
     105=== Troubleshooting ===
     106
     107Here are a few things to check if you cannot get your {{{test_app.fdx}}} to work as expected.
     108
     109 Application Id, Command Id, AVP Id, Vendor Id::
     110   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.
     111
     112 Connection status:
     113   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 [wiki:dbg_monitor.fdx dbg_monitor.fdx] extension to help you check the status of the connection.
     114
     115 Routing parameters:
     116   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.
     117
     118----