Candela Technologies Logo
 
http://www.candelatech.com
sales@candelatech.com
+1 360 380 1618 [PST, GMT -8]
Network Testing and Emulation Solutions

Querying the LANforge GUI for JSON Data

Goal: Learn how to configure and query the LANforge GUI for JSON formatted data.

Updated 2018-05-17:For 5.3.8: there is a permantent change to the URL API.

The LANforge GUI (as of release 5.3.6) can be configured to start a lightweight web service listener that can provide data about ports and layer-3 connections. This service can be queried with with any browser or AJAX connection. This feature provides these benefits:

  • More rapid polling: using CLI scripts to poll ports on the LANforge manager can add stress and contention to the LANforge manager; polling the GUI will not tax your test scenario.
  • Expanded array of data: the views found in the GUI, like Port Mgr and Layer-3 tabs, contain synthesized data columns not available through the CLI scripting API.. These columns can be returned in JSON format.
  • Reduced effort when integrating with third party test libraries: many other testing libraries expect JSON formatted input.

Present and potential drawbacks of the GUI JSON data feature:

  • Actively being developed: the JSON views/schema of the objects is at a demonstation state. URLs and JSON structures have changed in 5.3.8.
  • JSON Features are compiled into the LANforge GUI from Java sources. It is possible to create Groovy plugins to add JSON features.
  • In 5.3.8 we have limited the view of ports, have added URLs to post direct CLI commands, and have applied HTML application/x-www-form-urlencoded form posting submissions in name/value pairs. There is no multipart/form-data JSON submission at this time.

GUI Settings

The LANforge GUI is started using a script (lfclient.bash or lfclient.bat). From a terminal, we call that script with the -httpd switch. By default the GUI will listen on port 8080:

 $ cd /home/lanforge
 $  ./lfclient.bash -httpd

You can specify the port to listen on:

 $ cd /home/lanforge
 $  ./lfclient.bash -httpd 3210

There is not a graphical gui preference to set for the feature at this time.

Example Query

This is a simple example to orient to how the data is delivered.

Getting Started

From the terminal we can query the port to find a basic message from the GUI: curl -sq http://localhost:8080/. This first page [/] will give you a JSON content, but other URLs will give you either HTML or JSON depending on your Accept header. By default, most URLs will treat a default Accept: */* header as text/html. Compare the two techniques below:

 $ curl -sqv -H 'Accept: application/json' http://localhost:8080/port/1/1/1
[{"handler":"candela.lanforge.HttpPort$JsonResponse"},{"uri":"port/:shelf_id/:resource_id/:port_id"},{"1.1.1":{"AP":"","Activity":0.0,"Channel":"","Device":"eth1","Down":false,"IP":"0.0.0.0","Parent Dev":"","Phantom":false,"Port":"1.1.01","SSID":""}}]
 $ curl -sqv -H 'Accept: text/html' http://localhost:8080/port/1/1/1
<!DOCTYPE html>
<html>
<head><title>/port</title>
</head>
<body>

<table border='1'><thead><tr><th>EID</th><th>AP</th><th>Activity</th><th>Channel</th><th>Device</th><th>Down</th><th>IP</th><th>Parent Dev</th><th>Phantom</th><th>Port</th><th>SSID</th></tr></thead>
<tbody>
<tr><td>1.1.1</td><td></td><td>0.0</td><td></td><td>eth1</td><td>false</td><td>0.0.0.0</td><td></td><td>false</td><td>1.1.01</td><td></td></tr>
</table><hr />
</body>
</html>
   

Formatting Results

JSON formatted text is pretty difficult to read, so you might like to know two different utilities that can help you look at it: jq, json_pp, tidy, xmllint and jsonlint. XmlLint is part of the libxml2-util package.

Example of installing formatters

On Fedora, install jq:

 $ sudo dnf install -y jq

On Ubuntu, install jq:

 $ sudo apt install -y jq

Now we can perform a query:

 $ curl -H 'Accept: application/json' -sq http://localhost:8080/port/1/1/1  | jq
[
 {
   "handler": "candela.lanforge.HttpPort$JsonResponse"
 },
 {
   "uri": "port/:shelf_id/:resource_id/:port_id"
 },
 {
   "1.1.1": {
     "AP": "",
     "Activity": 0,
     "Channel": "",
     "Device": "eth1",
     "Down": false,
     "IP": "0.0.0.0",
     "Parent Dev": "",
     "Phantom": false,
     "Port": "1.1.01",
     "SSID": ""
   }
 }
]

Notice that the URI object list paths with colon-tagged positions in them, e.g.: /cli-form/:cmd. These are interpreted as URL parameters and not query string parameters, they cannot be moved into the query string.

We can view a URL in a browser as well:

Columns of data that are returned match the GUI Port Mgr tab of columns selected.

Right-clicking the Port Mgr and selecting Add/Remove Table Columns will allow you to change this.

Clicking the Select All/None button and then Apply will get all the columns displayed, and returned in your queries.

Make sure to Right-Click → Save Table Layout so that your next session will show all the data.

Validating with jsonlint

On Fedora, install php-jsonlint:

 $ sudo dnf install -y php-jsonlint

On Ubuntu, install jsonlint:

 $ sudo apt install -y jsonlint

Running jsonlint-php is not nearly as exciting:

 $ curl -sq http://localhost:8080/ | jsonlint-php
Valid JSON

Data Views

URLs

/shelf/
The /shelf/1/ URL provides a list of resources in your realm:
 $ curl -H 'Accept: application/json' -sq http://localhost:8080/shelf/1/ | jq
[
  {    "handler": "candela.lanforge.HttpResource$JsonResponse"  },
  {    "uri": "shelf/:shelf_id"  },
  {    "href": [ "/resource/1/1", "Resource 1" ]  },
  {    "href": [ "/resource/1/2", "Resource 2" ]  }
]
/resource/

The /resource/ URL provides a digest of ports available at the requested resource.

 $ curl -H 'Accept: application/json' -sq  http://localhost:8080/resource/1/1/ | jq
[
  {    "handler": "candela.lanforge.HttpResource$JsonResponse"  },
  {    "uri": "resource/:shelf_id/:resource_id"  },
  {    "href": "/port/1/1/11/"  },
  {    "href": "/port/1/1/10/"  },
  {    "href": "/port/1/1/9/"  },
  {    "href": "/port/1/1/8/"  },
  {    "href": "/port/1/1/7/"  },
  {    "href": "/port/1/1/6/"  },
  {    "href": "/port/1/1/5/"  },
  {    "href": "/port/1/1/4/"  },
  {    "href": "/port/1/1/3/"  },
  {    "href": "/port/1/1/2/"  },
  {    "href": "/port/1/1/1/"  }
]
/port/
The /port URL provides a digest of ports and their state. You can request multiple ports by ID on this resource by appending the port IDs with commas.
 $ curl -H 'Accept: application/json' -sq  http://localhost:8080/port/1/1/3,4 | jq
[
  {    "handler": "candela.lanforge.HttpPort$JsonResponse"  },
  {    "uri": "port/:shelf_id/:resource_id/:port_id"  },
  {
    "1.1.3": {
      "4Way Time (us)": 0,
      "ANQP Time (us)": 0,
      "AP": "",
      "Activity": 0,
      "Alias": "wiphy1",
      ...
   },
   1.1.4" : {
      "ANQP Time (us)" : 0,
      "TX Crr" : 0,
      "Beacon" : 0,
      "Phantom" : false,
      "RX Frame" : 47160,
      "RX Pkts" : 41331911,
      "RX CRC" : 4061297,
      "Activity" : 0,
      "MTU" : "1500",
      "Mask" : "0.0.0.0",
      "IPv6 Address" : "DELETED",
      "Logout-Fail" : 0,
      "Parent Dev" : "",
      "Login-Fail" : 0,
      "CX Time (us)" : 0,
      "Misc" : 0,
      "TX Pkts" : 7381421,
      ...
   }
  }
]

Creating Ports

It is possible to create ports and connections by using the CLI commands. Your LANforge test scenarios (located in the /home/lanforge/DB/ directory) contain all the CLI commands that create your ports and connections. You can submit those commands over HTTP in two ways:

These methods accept application/x-www-form-urlencoded content type submissions. This is compatible with the NanoHttp library we are using and the default for curl.

These CLI commands do not return data, only a result code. All data that the Perl scripts would collect from command line queries is sent directly to the GUI.

Command help

Commands are often complex and include a number of bitwise flags to set the state and features of ports. There is presently no tag-substitution for port flags, but there is a help utility that can help you compute them.

http://localhost:8080/help/

Select a command to see the field helper screen:

http://localhost:8080/help/set_port

Type values into the field inputs and the CLI command will be refreshed:

Click the Parse Command button and the values in the command box will be displayed in the curl command and the field inputs. (Notice this form is doing a GET request.)

At the bottom of the screen, you may find a list of flag fields that are organized by field names. The text area below the selection list is the sum of the selected fields. Copy the flag values into the input field above to incorporate it into your command.

Creating a WiFi Station

Please refer to the scripts lf_associate_ap.pl and lf_vue_mod.sh for examples of how to produce lists of CLI commands involved in creating stations. Please refer to:

  1. Learn CLI Commands used to operate WiFi stations
  2. and Changing Station WiFi SSID with the CLI API

These will provide ways of collecting the CLI commands in log files for you to place into the command /help/ page.

Connections

Layer-3 features presently disabled pending feedback.


Candela  Technologies, 2417 Main Street, Suite 201, Ferndale, WA 98248, USA
www.candelatech.com | sales@candelatech.com | +1.360.380.1618
Google+ | Facebook | LinkedIn | Blog