Allegro Network Multimeter Manual

REST API description

Revision as of 08:12, 8 May 2020 by Klaus (talk | contribs) (→‎jquery ( jq ))

This page describes how to access and use the REST API. It allows to post-process data with 3rd party systems. The Allegro web interface is itself based on this REST API and all displayed statistics can be extracted from the Allegro with this API.


General API Setup

REST API Interface

All Allegro Network Multimeter statistics are derived from HTTPS requests and provided as JSON objects. The requests are stateless, i.e. there are no prerequisites and there is no fixed sequence of requests necessary. Example requests related to a specific module and statistics can be seen in the web interface by opening the browser development console (Ctrl+Shift+I for Chrome and Firefox, F12 for Edge).

credentials

The credentials are the same as for the web interface. The admin user allows to access all APIs. A non-admin user has read access to most of the statistics. If you have enabled the pcap role, the capture URL is also possible for the API.

Allegro recommends to set up a separate non-admin user with or without the pcap role for the REST API of only statistics shall be gathered. This will prevent to accidentally shut down or change any configuration by calling the REST API.

Useful shell commands and their parameters

Curl

Most examples are written for curl [1]. Curl is available as for many operating systems like Linux or Windows. Curl needs a few parameters for the access of the Allegro Network Multimeter:

The parameter -u allows you to set a user name and password for the request.

The parameter -k will allow self-signed certificates.

The parameter -s or --silent mutes any debugging output.

The URL of the API call is the first argument. It is recommended to enclose the API call with the character ' to avoid replacing the argument ( unless you need to replace parts of it )

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/...'

Please note that you might need to use curl.exe in windows.

PowerShell

The Integrated Windows PowerShell can be used to access the REST API. This guide requires at least PowerShell v6.

The command to call a REST API is Invoke-RestMethod [2]. Invoke-RestMethod on the PowerShell needs a few parameters for the access of the Allegro Network Multimeter:

To set the user name for basic authorization, use the -Headers parameter:

-Headers @{Authorization = ("Basic {0}" -f [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f 'USER', 'PASSWORD'))))}

You also need to announce that you accept JSON as response with:

-ContentType'application/json; charset=utf-8'

To disable the certificate check, use:

-SkipCertificateCheck

The URL must be passed with the parameter -Uri, so the full command is:

Invoke-RestMethod -Uri 'https://allegro-mm-XXXX/...' -Headers @{Authorization = ("Basic {0}" -f [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f 'USER', 'PASSWORD'))))} -ContentType'application/json; charset=utf-8' -Method 'Get' -SkipCertificateCheck

jquery ( jq )

jquery ( [3] ) is a powerful tool to extract parameters from a json document. Please read its documentation if you need to postprocess more data.

Examples

MAC or IP address statistics

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/mac/macs/ff:ff:ff:ff:ff:ff' curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3'

Pretty displaying JSON output with jq

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3' | jq

Traffic counters

Traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows:

  • line 1: received packets.
  • line 2: received bytes.
  • line 3: transmitted packets.
  • line 4: transmitted bytes.
  • other lines are module specific.

The following counters are supported:

  • interval: Values of the selected time interval. If no interval is specified, this is similar to lastSecond.
  • allTime: Values since start of the Allegro Network Multimeter.
  • lastSecond: Values of the last second.
  • intervalPerSecond: Average per second value of the selected time interval. If no interval is specified, this is similar to lastSecond.

Time interval selection

Requests can be given a time interval. The following GET parameters are necessary:

  • starttime, endtime: Start and end time of the interval. Format: seconds since 1970/01/01 UTC (Unix time, epoch).
  • timespan: Duration of the interval selection in seconds.

Extract received bytes of the last second of a specific IP

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3' | jq .lastSecond[1]

Extract received and transmitted bytes of the last second of a specific IP

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3' | jq '.lastSecond[1] + .lastSecond[3]'

Extract received and transmitted bytes in a time interval (18/06/11 9:00 - 10:00) of a specific IP

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3?timespan=3600&starttime=1528700400&endtime=1528704000' | jq '.interval[1] + .interval[3]'

List queries

List queries are requested with pagination parameters to reduce the size of the resulting JSON objects and to increase performance. In the resulting JSON object, the list elements are stored in the displayedItems array. The following list parameters are possible:

  • sort: Sorting criteria for the list. Following criterias are supported for most lists:
    • bytes: Received and transmitted bytes (either in selected time interval or since start of the Multimeter).
    • rxbytes: Received bytes.
    • txbytes: Transmitted bytes.
    • bps: Received and transmitted bytes per second (either average per second value of the selected time interval or last second, if no interval is specified).
    • rxbps: Received bytes per second.
    • txbps: Transmitted bytes per second.
  • reverse: Sort ascending (= false) or descending (= true).
  • page: Requested page.
  • count: Amount of entries in the list. Maximum is 100.
  • values: Amount of maximal values in history object(s).

Show IP address with the highest amount of traffic

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips_paged?sort=bps&reverse=true&page=0&count=1' | jq .displayedItems[0].ip

PowerShell command:

((Invoke-RestMethod -Uri 'https://allegro-mm-XXXX/API/stats/modules/ip/ips_paged?sort=bytes&reverse=true&page=0&count=10&timespan=60&values=50' -Headers @{Authorization = ("Basic {0}" -f [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f 'USER', 'PASSWORD'))))} -ContentType'application/json; charset=utf-8' -Method 'Get' -SkipCertificateCheck). displayedItems[0]).ip

Show all peers of a specific IP address

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3/peers?sort=bytes&reverse=true&page=0&count=9999&timespan=60&values=100' | jq '.displayedItems[].ip'

Capture a specific IP

curl -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/data/modules/capture?expression=ip==10.1.2.3' > path_to/capture.pcap

Capture two IP addresses with ports on a specific Layer 4 protocol

curl -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/data/modules/capture?expression=IP==10.1.2.3:62887 and IP==10.1.2.100:548 and l4Protocol==TCP' > path_to/capture.pcap

Pcap parameters

The following parameters are possible:

  • startTime: The start time of the capture. The first packet with exactly this or a later time will start the capture. The time format must be microseconds after January, 1st 1970 UTC (Unix time, epoch). If the start time is in the past, make sure you set fromCaptureBuffer parameter accordingly.
  • endTime: The end time of the capture. The first packet with exactly this or a later time will stop the capture. The time format must be microseconds after January, 1st 1970 UTC (Unix time, epoch).
  • expression: The filter expression. There are no whitespaces allowed. You may use ‘%20’ instead.
  • snapPacketLength: The maximum size of a packet applied on Layer 2 without frame check sequence. If a packet is larger than this value, it is truncated. Use 65535 for unlimited size.
  • fromCaptureBuffer: Whether to extract data from the packet ring buffer (= true) or just live traffic (= false).
  • captureToMedia: Whether to store a pcap on an external storage device (= true) or download to your computer (= false).
Retrieved from "https://allegro-packets.com/wiki/index.php?title=REST_API_description&oldid=2720"