REST API description: Difference between revisions

From Allegro Network Multimeter Manual
Jump to navigation Jump to search
Access restrictions were established for this page. If you see this message, you have no access to this page.
No edit summary
No edit summary
Line 1: Line 1:
* General
== General ==
* Examples
 
– SSL certificate errors
 
– Statistics about MAC or IP addresses
 
– Pretty displaying JSON output with jq
 
– Traffic counters
 
– Time interval selection
 
– Extract received bytes of the last second of a certain IP
 
– Extract received and transmitted bytes of the last second of a certain IP
 
– Extract received and transmitted bytes in a time interval (18/06/11 9:00 - 10:00) of a certain IP
 
– List queries
 
– Show IP address with the highest amount of traffic
 
– Show all peers of a certain IP address
 
– Capture a certain IP
 
– Capture two IP addresses with ports on a certain layer 4 protocol
 
– PCAP parameters
 
 
=='''General'''==


All statistics of the Allegro Network Multimeter are requested as HTTP requests and provided as a JSON object.
All statistics of the Allegro Network Multimeter are requested as HTTP requests and provided as a JSON object.
Line 39: Line 7:
The credentials are the same as of the web interface. A non-admin user has read access to most of the statistics.
The credentials are the same as of the web interface. A non-admin user has read access to most of the statistics.


 
== Examples ==
=='''Examples'''==


In this section some examples are given using PowerShell and Linux curl and jq commands.
In this section some examples are given using PowerShell and Linux curl and jq commands.


 
==== SSL certificate errors ====
'''SSL certificate errors'''


If the default self-signed SSL certificate is used, curl and PowerShell are displaying error messages. You can either
If the default self-signed SSL certificate is used, curl and PowerShell are displaying error messages. You can either
Line 61: Line 27:
|}
|}


 
==== Statistics about MAC or IP addresses ====
'''Statistics about MAC or IP addresses'''
{| class="wikitable"
{| class="wikitable"
|-
|-
Line 69: Line 34:
|}
|}


 
==== Pretty displaying JSON output with jq ====
'''Pretty displaying JSON output with jq'''
{| class="wikitable"
{| class="wikitable"
|-
|-
Line 76: Line 40:
|}
|}


 
==== Traffic counters ====
'''Traffic counters'''


Traffic counters are represented as an JSON array with at least 4 lines. The structure is as follows:
Traffic counters are represented as an JSON array with at least 4 lines. The structure is as follows:
Line 92: Line 55:
* intervalPerSecond: Average per second value of the selected time interval. If no interval is specified, this is similar to lastSecond.
* intervalPerSecond: Average per second value of the selected time interval. If no interval is specified, this is similar to lastSecond.


 
==== Time interval selection ====
'''Time interval selection'''


Requests can be given a time interval. Following GET parameters are necessary:
Requests can be given a time interval. Following GET parameters are necessary:
Line 99: Line 61:
* timespan: Duration of the interval selection in seconds
* timespan: Duration of the interval selection in seconds


 
==== Extract received bytes of the last second of a certain IP ====
'''Extract received bytes of the last second of a certain IP'''


{| class="wikitable"
{| class="wikitable"
Line 107: Line 68:
|}
|}


 
==== Extract received and transmitted bytes of the last second of a certain IP ====
'''Extract received and transmitted bytes of the last second of a certain IP'''
{| class="wikitable"
{| class="wikitable"
|-
|-
Line 114: Line 74:
|}
|}


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


{| class="wikitable"
{| class="wikitable"
Line 122: Line 81:
|}
|}


 
==== List queries ====
'''List queries'''


List queries are requested with pagination parameters to reduce the size of the resulting JSON object and to in-
List queries are requested with pagination parameters to reduce the size of the resulting JSON object and to in-
Line 143: Line 101:
* values: Amount of maximal values in history object
* values: Amount of maximal values in history object


 
==== Show IP address with the highest amount of traffic ====
'''Show IP address with the highest amount of traffic'''


{| class="wikitable"
{| class="wikitable"
Line 158: Line 115:
|}
|}


 
==== Show all peers of a certain IP address ====
 
'''Show all peers of a certain IP address'''


{| class="wikitable"
{| class="wikitable"
Line 167: Line 122:
|}
|}


 
==== Capture a certain IP ====
'''Capture a certain IP'''


{| class="wikitable"
{| class="wikitable"
Line 175: Line 129:
|}
|}


 
==== Capture two IP addresses with ports on a certain layer 4 protocol ====
'''Capture two IP addresses with ports on a certain layer 4 protocol'''
 


{| class="wikitable"
{| class="wikitable"
Line 184: Line 136:
|}
|}


 
==== PCAP parameters ====
'''PCAP parameters'''


Following parameters are possible:
Following parameters are possible:

Revision as of 11:27, 9 April 2020

General

All statistics of the Allegro Network Multimeter are requested as HTTP requests and provided as a JSON object. The requests are stateless, i.e. there are no prerequisites and there is no fixed sequence of requests necessary. Example requests related to a certain module and statistics can be seen quite easily in the web interface by opening the browser development console (Ctrl+Shift+I for Chrome and Firefox, F12 for Edge). The credentials are the same as of the web interface. A non-admin user has read access to most of the statistics.

Examples

In this section some examples are given using PowerShell and Linux curl and jq commands.

SSL certificate errors

If the default self-signed SSL certificate is used, curl and PowerShell are displaying error messages. You can either install another SSL certificate or let the tools ignore the errors. For curl it is

curl -k ...

For PowerShell in recent versions (v6 and later) it is

Invoke-RestMethod -SkipCertificateCheck ...

Statistics about MAC or IP addresses

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

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. 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 certain 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 certain 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 certain 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 object and to in- crease performance. In the resulting JSON object, the list elements are stored in the displayedItems array. 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

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

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 max 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 PCAP on external storage device (= true) or download your computer (= false).
Retrieved from "https://allegro-packets.com/wiki/index.php?title=REST_API_description&oldid=1282"