Changes between Initial Version and Version 1 of test_app.fdx

Timestamp:

Jun 18, 2010, 5:04:51 PM (14 years ago)

Author:

Sebastien Decugis

Comment:

--

test_app.fdx

@@ +1 @@
+[[PageOutline(2-4)]]
+== 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.
+
+{{{
+#!graphviz
+digraph G { 
+    graph [bgcolor="#E8E8E8C8"]
+    rankdir = "LR"
+    node [shape=box];
+    edge [color=blue];
+    cli [ 
+         label="client"
+    ]
+    serv [
+         label="server"
+    ]
+    cli -> serv [label="Request"]; 
+    serv -> cli [label="Answer"]; 
+}
+}}}
+
+
+{{{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 [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";}}}.
+
+=== 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: [http://lists.freediameter.net/pipermail/help/2010-June/000001.html 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 [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):
+ * 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 [wiki:dbg_monitor.fdx 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.
+
+----