Allegro Network Multimeter Manual - User contributions [en]

Supported Storage Devices for x300, x310, x400, x410, x500 and x510 Series

2023-09-05T12:22:24Z

Klaus: added comment that SAS is not supported on the x410

Some Allegro Network Multimeter appliances can be equipped with hot-swappable storage devices. This page lists which appliances support which type of storage devices.

In general, we recommend to use devices with similar specs for best performance but there is no technical restriction to use different units.
When using multiple ring buffers (see [[Ring Buffer Configuration Guide]]), it can be beneficial to use different devices, for example, slow but large devices for long-term capturing with packet truncation, and fast but smaller devices for full line rate capturing.

== Allegro x310 (1310/3310/5310/7310) ==

The Allegro Network Multimeter x310 series has 10 x 2.5" device slots with support of SATA3 and U.2. Please note that SAS is NOT supported on any of the ports.

== Allegro x410 (1410/3410/5410/7410) ==

The Allegro Network Multimeter x410 series has 12 x 2.53" device slots. The backplane supports SATA3 and U.2 on all ports. The real support depends on the number of installed extension cards and cables. Please contact the support if you plan it extend you Allegro with more extension cards, HDDs or SSDs if and how this is possible. Please note that SAS is NOT supported on any of the ports.

== Allegro x510 (1510/3510/5510/7510) ==

The Allegro Network Multimeter x510 has 36 x 3.5" device slots, supporting SATA3 or SAS3 devices. A separate hardware option allows to use up to 4 U.2 devices.

U.2 devices can be installed at the rear of the Allegro Network Multimeter (which has 12 slots in total). The U.2 slots are the top slot in the third column and the 3 slots in the last column (at the right):

[[File:3500-back-u2.png|frameless|U.2 slots]]

== Allegro x300 (1300/3300/5300) ==

The Allegro Network Multimeter x300 series has 10 x 2.5" device slots, two of them also support U.2 devices.

{| class="wikitable"
|-
! Slot 0+1 !! Slot 2+3 !! Slot 4+5 !! Slot 6+7 !! Slot 8+9
|-
| 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 2.5" U.2
|-
| 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 2.5" U.2
|}

Note: SAS devices are not supported!

== Allegro x400 (1400/3400/5400) ==

The Allegro Network Multimeter x400 has 12 x 3.5" device slots, supporting SATA3 or SAS3 devices.

A separate hardware option allows to use up to 4 U.2 devices, in the slots highlighted in this picture:

[[File:x400-back-u2.png|frameless|U.2 slots]]

== Allegro x500 (1500/3500/5500) ==

The Allegro Network Multimeter x500 has 36 x 3.5" device slots, supporting SATA3 or SAS3 devices. A separate hardware option allows to use up to 4 U.2 devices.

U.2 devices can be installed at the rear of the Allegro Network Multimeter (which has 12 slots in total). The U.2 slots are the top slot in the third column and the 3 slots in the last column (at the right):

[[File:3500-back-u2.png|frameless|U.2 slots]]

== Allegro 2U/4U JBOD extension ==

The Allegro Network Multimeter JBOD extension has 12x (2U) or 44x (4U) 3.5" device slots, supports SATA3 or SAS3 devices.

Supported Storage Devices for x300, x310, x400, x410, x500 and x510 Series

2023-09-04T09:24:09Z

Klaus: added x310, x410 and x510

Some Allegro Network Multimeter appliances can be equipped with hot-swappable storage devices. This page lists which appliances support which type of storage devices.

In general, we recommend to use devices with similar specs for best performance but there is no technical restriction to use different units.
When using multiple ring buffers (see [[Ring Buffer Configuration Guide]]), it can be beneficial to use different devices, for example, slow but large devices for long-term capturing with packet truncation, and fast but smaller devices for full line rate capturing.

== Allegro x310 (1310/3310/5310/7310) ==

The Allegro Network Multimeter x310 series has 10 x 2.5" device slots with support of SATA3 and U.2. Please note that SAS is NOT supported on any of the ports.

== Allegro x410 (1410/3410/5410/7410) ==

The Allegro Network Multimeter x410 series has 12 x 2.53" device slots. The backplane supports SATA3 and U.2 on all ports. The real support depends on the number of installed extension cards and cables. Please contact the support if you plan it extend you Allegro with more extension cards, HDDs or SSDs if and how this is possible.

== Allegro x510 (1510/3510/5510/7510) ==

The Allegro Network Multimeter x510 has 36 x 3.5" device slots, supporting SATA3 or SAS3 devices. A separate hardware option allows to use up to 2 U.2 devices.

U.2 devices can be installed at the rear of the Allegro Network Multimeter (which has 12 slots in total). The U.2 slots are the top two slots in the last fourth column (at the right):

[[File:3500-back-u2.png|frameless|U.2 slots]]

== Allegro x300 (1300/3300/5300) ==

The Allegro Network Multimeter x300 series has 10 x 2.5" device slots, two of them also support U.2 devices.

{| class="wikitable"
|-
! Slot 0+1 !! Slot 2+3 !! Slot 4+5 !! Slot 6+7 !! Slot 8+9
|-
| 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 2.5" U.2
|-
| 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 2.5" U.2
|}

Note: SAS devices are not supported!

== Allegro x400 (1400/3400/5400) ==

The Allegro Network Multimeter x400 has 12 x 3.5" device slots, supporting SATA3 or SAS3 devices.

A separate hardware option allows to use up to 4 U.2 devices, in the slots highlighted in this picture:

[[File:x400-back-u2.png|frameless|U.2 slots]]

== Allegro x500 (1500/3500/5500) ==

The Allegro Network Multimeter x500 has 36 x 3.5" device slots, supporting SATA3 or SAS3 devices. A separate hardware option allows to use up to 2 U.2 devices.

U.2 devices can be installed at the rear of the Allegro Network Multimeter (which has 12 slots in total). The U.2 slots are the top two slots in the last fourth column (at the right):

[[File:3500-back-u2.png|frameless|U.2 slots]]

== Allegro 2U/4U JBOD extension ==

The Allegro Network Multimeter JBOD extension has 12x (2U) or 44x (4U) 3.5" device slots, supports SATA3 or SAS3 devices.

Supported Storage Devices for x300/x400/x500 Series

2023-09-04T09:17:10Z

Klaus: Klaus moved page Supported Storage Devices for x300/x400/x500 Series to Supported Storage Devices for x300, x310, x400, x410, x500 and x510 Series

#REDIRECT [[Supported Storage Devices for x300, x310, x400, x410, x500 and x510 Series]]

Supported Storage Devices for x300, x310, x400, x410, x500 and x510 Series

2023-09-04T09:17:09Z

Klaus: Klaus moved page Supported Storage Devices for x300/x400/x500 Series to Supported Storage Devices for x300, x310, x400, x410, x500 and x510 Series

Some Allegro Network Multimeter aplliances can be equipped with hot-swappable storage devices. This page lists which appliances support which type of storage devices.

In general, we recommend to use devices with similar specs for best performance but there is no technical restriction to use different units.
When using multiple ring buffers (see [[Ring Buffer Configuration Guide]]), it can be beneficial to use different devices, for example, slow but large devices for long-term capturing with packet truncation, and fast but smaller devices for full line rate capturing.

== Allegro x300 (1300/3300/5300) ==

The Allegro Network Multimeter x300 series has 10 x 2.5" device slots, two of them also support U.2 devices.

{| class="wikitable"
|-
! Slot 0+1 !! Slot 2+3 !! Slot 4+5 !! Slot 6+7 !! Slot 8+9
|-
| 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 2.5" U.2
|-
| 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 || 2.5" SATA3 2.5" U.2
|}

Note: SAS devices are not supported!

== Allegro x400 (1400/3400/5400) ==

The Allegro Network Multimeter x400 has 12 x 3.5" device slots, supporting SATA3 or SAS3 devices.

A separate hardware option allows to use up to 4 U.2 devices, in the slots highlighted in this picture:

[[File:x400-back-u2.png|frameless|U.2 slots]]

== Allegro x500 (1500/3500/5500) ==

The Allegro Network Multimeter x500 has 36 x 3.5" device slots, supporting SATA3 or SAS3 devices. A separate hardware option allows to use up to 2 U.2 devices.

U.2 devices can be installed at the rear of the Allegro Network Multimeter (which has 12 slots in total). The U.2 slots are the top two slots in the last fourth column (at the right):

[[File:3500-back-u2.png|frameless|U.2 slots]]

== Allegro 2U/4U JBOD extension ==

The Allegro Network Multimeter JBOD extension has 12x (2U) or 44x (4U) 3.5" device slots, supports SATA3 or SAS3 devices.

Statistics Export via InfluxDB

2022-12-02T09:51:08Z

Klaus: removed protection

The Influx Export allows to write statistics from the Allegro Network Multimeter to an InfluxDB.
This can be found in the menu "Settings -> Remote access & export -> Influx Export".

==InfluxDB settings==
*'''Enabled''' → Enables the export
*'''URL''' → URL of the InfluxDB (for example <nowiki>http://influx.mycompany.com:8086</nowiki>)
*'''API Token''' → Organization → the organization set in the InfluxDB
*'''Organization''' → the organization set in the InfluxDB
*'''Bucket''' → name of the bucket in which the statistics should be stored
*'''Check TLS Certificates''' → For HTTPS Connections. Disable if a self signed certificate is used for the InfluxDB server.

==Export Settings==

{| class="wikitable"
|+
!Option
!InfluxDB measurement name
!Description
|-
|Interval (seconds)
| -
|Specifies the interval (in seconds) in which the statistics data from the Allegro Network Multimeter are written to the InfluxDB. The value must be greater than or equal to 1.
|-
|Resolution (seconds)
| -
|Specifies the resolution (in seconds) of the statistics. For example, 1 = one measurement every second, 10 = one measurement every 10 seconds. The value must be greater than or equal to 1. The value may not greater than the interval.
|-
|System Load Statistics
|system
|Save the system load, memory load, packet ingress load and statistics-availability.
|-
|System Health
|system
|Save the TBW for each disk.
|-
|Ring Buffer Usage Statistics
|system
|Save the Ring Buffer Usage in bytes
|-
|Global Counters
|global-counters
|Save the global counters mac count, ip count, connection count, connection activ, connection maximum, connection capacity.
|-
|Interface Statistics
|interface-[interface number]
|Save the Bytes and Packets (rx/tx) of all network interfaces.
|-
|Virtual Link Groups Statistics
|virtualLinkGroup-[name]
|Save the Bytes and Packets (rx) of all Virtual Link Groups.
|-
|IP Global Statistics
|ip-global
|Save the Bytes and Packets for each protocol.
|-
|IP Countries Statistics
|ip-countries
|Save the Bytes and Packets (rx/tx) of each country.
|-
|IP Address Statistics
|ip-[address]
|Save the Bytes and Packets (rx/tx) for a list of IP-Devices. Addresses (IPv4/IPv6) separated by comma, without spaces.
|-
|IP Address Deteils Statistics
|ip-[address]
|Save the Bytes and Packets for each protocol for a list of IP-Addresses. Addresses (IPv4/IPv6) separated by comma, without spaces.
|-
|IP Address Peers Statistics
|ip-[address]-peers
|Save the Bytes and Packets for all peers of a list of Addresses. Addresses (IPv4/IPv6) separated by comma, without spaces.
|-
|DNS Statistics
|dns
|Save the global DNS request/replies Statistic.
|-
|ARP Statistics
|arp
|Save the global ARP request/replies Statistic.
|-
|TCP Syn Response Time Statistics
|tcp-syn-response-time
|Save the global TCP syn response time.
|}

==InfluxDB & Grafana setup example with docker-compose==
<pre>
version: '3.6'
services:

influxdb:
image: influxdb:latest
container_name: influxdb
restart: always
environment:
- DOCKER_INFLUXDB_INIT_MODE=setup
- DOCKER_INFLUXDB_INIT_USERNAME=admin
- DOCKER_INFLUXDB_INIT_PASSWORD=a_secure_password
- DOCKER_INFLUXDB_INIT_ORG=MyCompany
- DOCKER_INFLUXDB_INIT_BUCKET=allegro-network-multimeter
ports:
- '8086:8086'
volumes:
- influxdb-data:/var/lib/influxdb2
- influxdb-conf:/etc/influxdb2

grafana:
image: grafana/grafana-oss:latest
container_name: grafana
restart: always
depends_on:
- influxdb
environment:
- GF_SECURITY_ADMIN_USER=admin
- GF_SECURITY_ADMIN_PASSWORD=a_secure_password
links:
- influxdb
ports:
- '3000:3000'
volumes:
- grafana-data:/var/lib/grafana
- grafana-provisioning:/etc/grafana/provisioning
- ./grafana.ini:/etc/grafana/grafana.ini

volumes:
influxdb-data:
influxdb-conf:
grafana-data:
grafana-provisioning:
</pre>

# create the docker-compose.yml
# create a empty grafana.ini file
# run docker-compose up -d
# Login to the influxDB (Load Data -> API Token).
# Create at read API token for grafana and a write API token for the Allegro Network Multimeter.
# Login the Allegro Network Multimeter
# Setup the Influx Export (Settings -> Remote access & export -> Influx Export)
# Login to grafana
# Add a new Data Source from the type InfluxDB (Settings -> Data sources)
#* Query Language: Flux
#* URl: http://influxdb:8086
#* Auth: none
#* InfluxDB Details
#** Organization: your Organization from the docker-compose file
#** Token: your grafana read token
#** Default Bucket: your Bucket from the docker-compose file
#* Save & Test
# Create a new Dashboard (Dashboard -> new Dashboard)
# Create a new Panel and add a flux query (you can generate simple querys in the Date Explorer of the InfluxDB)

REST API description

2022-07-20T11:13:57Z

Klaus: added csv examples

This page describes how to access and use the REST API. It allows to post-process data with 3rd party systems. The Allegro Network Multimeter web interface is itself based on this REST API and all displayed statistics can be extracted from the Allegro Network Multimeter 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).

Here an example of the structured JSON data for the IP overview. This data has been extracted with the Google Chrome developer console while accessing the IP statistics page.

[[File:Rest api chrome console.png|800px]]

=== 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 Packets 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 [https://en.wikipedia.org/wiki/CURL]. 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 )

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

Please note that you might need to use <code>curl.exe</code> 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''' [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-restmethod].
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:

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

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

<pre>-ContentType'application/json; charset=utf-8'</pre>

To disable the certificate check, use:

<pre>-SkipCertificateCheck</pre>

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

<pre>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</pre>

=== jq ===

jq ([https://stedolan.github.io/jq/]) is a powerful tool to extract parameters from a json document. If called without parameters, jq formats the JSON output into a readable format with indenting and new lines. It also allows to select specific values and do basic operations like addition with this values.
Please read the jq documentation for more information.

== API hierarchy ==

=== Query available URIs with OPTIONS ===

The Allegro Network Multimeter REST API has the fixed URI <code>API/stats</code> for statistics. To see all possible subtrees of a specific request, use the '''OPTIONS''' request instead of '''GET'''. It can be set with the parameter <code>-X OPTIONS</code> for curl.

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats' -X OPTIONS
{
"subResources": [
"modules",
"reports",
"incidentReporting",
"time",
"ringBufferReplay",
"pcap",
"reset",
"interfacesError",
"interfaces",
"load",
"processing"
]
}
</pre>

This allows you to query for example for all modules that are available for a specific release of the Allegro Network Multimeter:

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules' -X OPTIONS
{
"subResources": [
"pppoe",
"lldp",
"groups",
"mpls",
"opc_ua",
"quality",
"ipsec",
"profinet",
"multicast",
"burst_analysis",
"global_incidents",
"ptp",
"ntp",
"icmp",
"stp",
"sip",
"smb",
"dpa",
"l4_ports",
"netbios",
"crt",
"dpi",
"http",
"ssl",
"dns",
"dhcp",
"location",
"qos",
"ip",
"mac_protocols",
"vlan",
"arp",
"packet_size",
"mac",
"capture"
]
}
</pre>

=== URI content parameters ===

Some modules allow to use a parameter as part of the URI like the IP or Mac address. The path <code>API/stats/modules/ip/ips</code> allows you to use an IP address as next uri element

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips' -X OPTIONS
{
"subResources": [
"protocol",
":ip"
]
}
</pre>

The path of an IP address shows all further available elements:

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.0.54.254' -X OPTIONS
{
"subResources": [
"sip_request_responses",
"peers_ports",
"sip_responses",
"sip_requests",
"qos",
"ports",
"connections",
"protocols",
"macs",
"peers",
"tcpStats"
]
}
</pre>

== JSON output traffic counters ==

All counters are aggregated counters, either for the selected time interval or since the processing start of the Allegro Network Multimeter. Many traffic counters have 4 separate values. These traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows:
* line 1: '''received packets''', extraction example: jq .lastSecond[0]
* line 2: '''received bytes''', extraction example: jq .lastSecond[1]
* line 3: '''transmitted packets''', extraction example: jq .lastSecond[2]
* line 4: '''transmitted bytes''', extraction example: jq .lastSecond[3]
* additional lines are module specific

The following counters exist for many REST APIs like IP, MAC, l4 protocol, l7 protocol and many more:
* '''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.

Please note that all counters are byte counters, not bit counters. You need to multiply the counters by 8 to get the bitrate.

This example extracts the received bytes of the last second of a specific IP.

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

This example extracts received and transmitted bytes of the last second of a specific IP.

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

== API parameters ==

The Allegro Network Multimeter REST API has a number of query parameters that can be added to modify the request. By default, the API will display the real time counters since the last restart of the processing unit.

This example extracts the amount of received and transmitted bytes for an IP address since the processing start of the Allegro Network Multimeter. It queries via the REST API the JSON and then adds the values second value ( row 1, rx bytes ) and 4th value ( row 3, tx bytes ) of the interval counters together.

<pre>
$ curl --silent -k -u USER:PASSWORD "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254" | jq '.interval[1] + .interval[3]'
</pre>

=== Time interval selection ===

Requests can be given a time interval. If present, the '''interval''' counters are adjusted to this 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). You can use <code>date +%s</code> on your machine to adjust to the best interval. Please consult the man page of date for more parameters.
* '''skiphistorydata''': shall the JSON include the history data without datasets, this reduces the amount of transferred bytes if datasets are required to render a graph, can be false/true default: false
* '''timespan''': required resolution for the graph dataset

This example extracts the amount of received and transmitted bytes for an IP address for the last 24 hours.
<pre>
$ curl --silent -k -u USER:PASSWORD "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?starttime=$(date --date="1 day ago" +%s)&endtime=$(date +%s)&skiphistorydata=true" | jq '.interval[1] + .interval[3]'
</pre>

=== 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 criteria's are supported for most lists:
** bytes: Received and transmitted bytes (either in selected time interval or since start of the Allegro Network 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).

This example shows IP address with the highest amount of traffic

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

This example shows up to 9999 peers of a specific IP address:

<pre>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/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'</pre>

=== Pcap extraction ===

The Allegro Network Multimeter allows to extract the raw packets with the REST API with the special capture URI <code>/API/data/modules/capture</code>

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

The available parameters are:

* '''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. If not specified, the current time will be used.
* '''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). If not specified, unlimited will be used. The end time can also be set to 'now', in this case the timespan parameter will be taken and the corresponding start time will be calculated.
* '''timespan''': The time span in seconds. Will be used if no startTime but endTime with 'now' is set.
* '''expression''': The filter expression. There are no whitespaces allowed. You may use ‘%20’ instead. See [[Capture module]] for available expressions.
* '''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).
* '''captureBufferSlotId''': In case a cluster packet ring buffer is used, the id of the ring buffer must be given. The id of the first ring buffer is 0. If this parameter is omitted, 0 will be taken as default value.
* '''captureToMedia''': Whether to store a pcap on an external storage device (= true) or download to your computer (= false).
* '''mm-id''': If you are extracting a Pcap from a parallel Pcap analysis job or a multi device connected Allegro Network Multimeter, you have to specify the device and the slot where to get the data from. The syntax is: <code>mm-id=<device name>:<slot id></code>. If the capture shall be performed on the local device, the device name can be omited (e.g. mm-id=:1 for the first replay slot on the local device).

Example to capture everything from now on:

<pre>curl -k -u USER:PASSWORD 'https://allegro-mm/API/data/modules/capture' > path_to/capture.pcap</pre>

Example to capture a specific IP of the last hour

<pre>curl -k -u USER:PASSWORD "https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3&starttime=$(($(date --date="1 hour ago" +%s%N)/1000))&endtime=$(($(date +%s%N)/1000))&fromCaptureBuffer=true" > path_to/capture.pcap</pre>

Example to capture a specific IP of a given time span of the first parallel Pcap analysis slot

<pre>curl -k -u USER:PASSWORD "https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3&starttime=$(($(date --date="2020-07-15 08:55:00" +%s%N)/1000))&endtime=$(($(date --date="2020-07-15 09:55:00" +%s%N)/1000))&fromCaptureBuffer=true&mm-id=:1" > path_to/capture.pcap</pre>

=== Pcap upload and analysis ===

Pcap upload and analysis can also be done via API calls.

The PCAP upload is split into 3 commands. First, the replay is being initialized. Then the analyzing is started. In the last step the PCAP is streamed to the Allegro Network Multimeter. Depending on the size of the PCAP the third step could take some time, but the Allegro Network Multimeter already allows access to the statistics of the already analyzed packets via web/API.

The example assumes that PCAP parallel analysis is enabled in the global settings, so the PCAP analysis will be done in slot 1 and a dedicated ring buffer is available.

<pre>
curl -k -u USER:PASSWORD "https://allegro-mm/API/system/replay/upload" -d '{"fileName": "abc.pcapng", "fileSize": '$(stat -c %s abc.pcapng)', "replaySlotID": 1, "forceSlotID": true, "useReplayBuffer": true}'
curl -k -u USER:PASSWORD "https://allegro-mm/API/data/pcap?mm-id=:1" -d '{"command":"start"}'
curl -F 'name=file' -F 'filename=abc.pcapng' -F 'file=@path_to/abc.pcapng' -k -u USER:PASSWORD "https://allegro-mm/API/system/analyze-pcap?replaySlotID=1"
</pre>

=== Virtual Link Groups ===

The Allegro Network Multimeter REST API allows to access all link groups by the parameter '''group'''. The group index starts at zero, which is the default value. If a virtual link group is enabled.

This example extracts the traffic of the IP 10.54.0.254 from the second virtual link group ( index 1 ).

<pre>
$ curl --silent -k -u USER:PASSWORD "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?group=1" | jq '.interval[1] + .interval[3]'
</pre>

=== Parallel pcap analysis ===

The Allegro Network Multimeter can process in parallel offline traffic like a pcap file or a ring buffer. In case a parallel PCAP analysis is running, the API call must be given either the additional header field <code>"X-AllegroPackets-Multimeter-ID: :1"</code> or the parameter mm-id with the PCAP instance ID.

This allows to extract information of automated pcap uploads.

=== Multi-device analysis ===

If the Allegro Network Multimeter is configured as a gateway for multiple Allegro devices by the [[Multi-device settings]], you need to add either the additional header field <code>"X-AllegroPackets-Multimeter-ID: hostname"</code> or the parameter mm-id where the hostname must be the same as configured in the multi-device settings.

== REST API Examples ==

==== MAC statistics ====

Extract the packets per second statistic of the MAC broadcast address

<pre>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/mac/macs/ff:ff:ff:ff:ff:ff'</pre>

==== IP statistics ====

<pre>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.1.2.3'</pre>

==== Pretty displaying JSON output with jq ====

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

==== Capture a specific IP ====

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

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

<pre>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</pre>

==== Output IP Table as CSV file ====
<pre>curl -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips_paged?csv=true' > path_to/file.csv</pre>

==== Output Connection Table as CSV file ====
<pre>curl -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/globalConnections/csv?csv=true' > path_to/file.csv</pre>

Names and look-ups

2020-10-07T13:33:47Z

Klaus:

It is possible to label IP and MAC address with custom names and group them together into categories to allow for easy access to specific systems.
For example, all your internal machines could be labeled to match their actual name and you can categorize them into different departments.

These user defined names are persistent and are available from start on. All entries are assigned per Allegro Appliance and not per user. An assigned name is available for all users.

== Configuration==

'''Web Interface'''
{| class="wikitable"
|-
|[[File:User defined names.png|600px|none]]
|}

'''Adding or remove entries'''

The configuration of the list of names is available via '''Settings -> User defined names'''.

The configuration page shows on top the list of IP and MAC names currently set in the system.
It is possible to search for a specific entry by entering the IP or MAC address, or the category or actual name.

Individual entries may be removed from the list by clicking at the trashcan symbol in the last column.

At the bottom of the table new elements can be added by entering the IP or MAC address, and the category and name of the element.
By clicking at the '''plus''' symbol, the entry is added and will be used without further doing.

The complete IP or MAC address list can be cleared by clicking at the bottom below the table. A dialog will ask for confirmation.

Names may also be set directly at the IP or MAC detail page, see below for more information.

'''Importing IP list'''

The IP names allows importing an IP list from an external URL or from a file in the format:

{| class="wikitable"
|#A line with a commend
1.2.3.1

1.2.3.2

1.2.3.3
|}

By clicking on '''Import list''' a dialog will be openend where you can choose to download such a list from a given URL or specify a file from your system.
The IPs are added to the already existing ones.

'''Uploading or downloading the complete list'''

Depending on the use case, the number of elements to add may be large.
In this case it is also possible to upload a comma separated text file (.csv).
The format is simple as follows:

{| class="wikitable"
|ip,192.168.0.1,category,name
mac,00:00:00:00:00:00,category,name
...
|}

The first column defines whether the line describes an IP or MAC address.
The second column is the actual address and the third and fourth is the category and the name of the entry.

The web page allows to download a template file which may be opened in a spreadsheet application.

The final file can be uploaded by clicking at the upload button and selecting the file from your local directory.

The current list can be downloaded also by clicking at the download button. The CSV file will contain both IP and MAC addresses.

== Name display for user defined names==

If a user defined name is configured for an IP or MAC address, the name will be shown among the alternative names (which also include possible DNS, DHCP name, or other sources of information).

{| class="wikitable"
|-
![[File:Ap-mm-ip-list-user-defined-name.png|800px|none]] !! IP
|}

{| class="wikitable"
! [[File:Ap-mm-mac-list-user-defined-name.png|800px|none]] !! MAC
|-
|}

In the detailed page for a single IP or MAC address, you can click on the pencil symbol to directly set a name for this specific address.

{| class="wikitable"
|-
![[File:Ap-mm-ip-alternative-names.png|800px|none]] !! IP
|}

{| class="wikitable"
! [[File:Ap-mm-mac-alternative-names.png|800px|none]] !! MAC
|-
|}

The IP and MAC overview, the IP or MAC column is highlighted to indicate such special entries for which a name is configured.

== Filtering==

It is possible to enter the category or user defined name for IP and MAC filters.

Also, the '''name''' check in [[Live filtering of tables|complex filters]] matches the user defined name, like in this example:

{| class="wikitable"
|(name=systemA)
|}

It is also possible to filter for specific category by using the '''category''' check:

{| class="wikitable"
|(category=server)
|}

In this example, the list would only show those element for which a user defined name is set and its category contains the string '''server'''.

USB Presenter Capture

2020-09-18T11:46:56Z

Klaus:

This page describes how the Allegro Network Multimeter allows a user to start a capture with a USB presenter. This capture can be actioned 'Back in Time' for a defined period. In addition, the capture files can be uploaded to an SFTP server at a defined time.

This feature has been designed to allow non-IT staff to record pcaps when an error occurs; it also allows for captures without opening a Web interface.

== Requirements ==

This feature is supported by all Allegro Network Multimeters, even for the VM Version starting at firmware Release 3.0. It requires a free USB port on the Allegro with USB 2.0 or higher. One internal or external disk needs to be configured at '''Generic''' → '''Storage''' and a [[Packet ring buffer|ring buffer]] must be configured. Please note that the capture is extracted from the ring buffer and a ring buffer filter rules for packet slicing will affect the exported pcap.

As of now, the Logitech R400 is supported. Allegro will add more presenters on request. An optional USB sound device will play a beep when a key has been pressed.

== USB Capture Trigger Setup ==

Connect the Logitech R400 USB dongle with the Allegro. If you have a Virtual Edition Allegro, please pass-through the USB device directly to the Allegro VM.

Once this is done, navigate to the '''Settings''' -> '''Expert settings''' page and open the '''USB capture trigger'''.

[[File:Presenter dialog.png|600px]]

Once any key has been pressed on the presenter, one pcap will be generated. The pcap end time is when the button has been pressed and the start time is defined by the capture interval. As example, an interval of 60 seconds will generate a capture of the last minute when a presenter key was pressed.

The captures are stored at the root directory of the storage device or, if enabled, in the upload directory for SFTP uploads.

== SFTP Export Setup ==

The Allegro can automatically upload pcap files to an SFTP server from the upload directory on the disk. To configure it, please navigate to '''Settings''' → '''Remote Access and Export''' → '''Pcap export via SFTP'''. This allow to export all captured pcap files at a certain time of day. As example it can be used to transfer pcaps during the night from remote locations to a central SFTP server.

[[File:Sftp export.png|1000px]]

== Advanced Multi-pcap Setup ==

There are situations where the Allegro shall record multiple separate pcaps for a key with specific filters. This can be done by enabling the '''USB capture filter''' in the '''USB capture trigger''' dialog. The filter syntax is described in the [[Capture module]].

A good example is the installation of an Allegro 500 with 2 links and 2 virtual link groups ( see [[Virtual Link Group Configuration Guide]]), one before and one behind the firewall.

[[File:Presenter filter group.png|600px]]

As a second example you can record pcaps of up to 4 different IP addresses at the same time with just one click.

[[File:Presenter filter ip.png|600px]]

USB Presenter Capture

2020-09-03T07:40:14Z

Klaus: /* Advanced Multi-pcap Setup */

<accesscontrol>AC:GroupUsers</accesscontrol>

This page describes how the Allegro Network Multimeter allows to start a capture with a USB presenter. This capture can be done back in time for a defined period. In addition, the capture files can be uploaded to an sftp server at a defined time.

This feature has been designed to allow non-IT staff to record pcaps at when an error happens it also allows to do captures without opening the web interface.

== Requirements ==

This feature is supported by all Allegro Network Multimeters, even for the VM Version starting at firmware version 3.0. It requires a free USB port on the Allegro with USB 2.0 or higher. One internal or external disk needs to be configured at '''Generic''' → '''Storage''' and a ring buffer must be configured. Please note that the capture is extracted from the ring buffer and a ring buffer filter rules for packet slicing will affect the exported pcap.

As of now, the Logitech R400 is supported. Allegro will add more presenter on request. An optional USB sound bar will play a beep when a key has been pressed. TODO: which soundbar

== USB Capture Trigger Setup ==

Please connect the Logitech R400 USB dongle with the Allegro. If you have a virtual Allegro, please pass-through the USB device directly to the Allegro VM.

Once this is done, navigate to the '''Settings''' -> '''Expert Settings''' page and open the '''USB capture trigger'''.

[[File:Presenter dialog.png|600px]]

Once any key has been pressed on the presenter, one pcap will be generated. The pcap end time is when the button has been pressed and the start time is defined by the capture interval. As example, an interval of 60 seconds will generate a capture of the last minute when a presenter key has been pressed.

The captures are stored at the root directory of the storage device or, if enabled, in the upload directory for sftp uploads.

== SFTP Export Setup ==

The Allegro can automatically upload pcap files to an sfp server from the upload directory on the disk. To configure it, please navigate to '''Settings''' → '''Remote Access and Export''' → '''Pcap export via SFTP'''. This allow to export all captured pcap files at a certain time of day. As example it can be used to transfer pcaps during the night from remote locations to a central sftp server.

[[File:Sftp export.png|1000px]]

== Advanced Multi-pcap Setup ==

There are situations where the Allegro shall record multiple separate pcaps for a key with specific filters. This can be done by enabling the '''USB capture filter''' in the '''USB capture trigger''' dialog. The filter syntax is described in the [[Capture module]].

A good example is the installation of an Allegro 500 with 2 links and 2 virtual link groups ( see [[Virtual Link Group Configuration Guide]]), one before and one behind the firewall.

[[File:Presenter filter group.png|600px]]

As a second example you can record Pcaps of up to 4 different IP addresses at the same time with just one click.

[[File:Presenter filter ip.png|600px]]

File:Presenter filter ip.png

2020-09-03T07:39:58Z

Klaus:

File:Presenter filter group.png

2020-09-03T07:38:38Z

Klaus:

USB Presenter Capture

2020-09-02T15:04:30Z

Klaus: /* Advanced Multi-pcap Setup */

<accesscontrol>AC:GroupUsers</accesscontrol>

This page describes how the Allegro Network Multimeter allows to start a capture with a USB presenter. This capture can be done back in time for a defined period. In addition, the capture files can be uploaded to an sftp server at a defined time.

This feature has been designed to allow non-IT staff to record pcaps at when an error happens it also allows to do captures without opening the web interface.

== Requirements ==

This feature is supported by all Allegro Network Multimeters, even for the VM Version starting at firmware version 3.0. It requires a free USB port on the Allegro with USB 2.0 or higher. One internal or external disk needs to be configured at '''Generic''' → '''Storage''' and a ring buffer must be configured. Please note that the capture is extracted from the ring buffer and a ring buffer filter rules for packet slicing will affect the exported pcap.

As of now, the Logitech R400 is supported. Allegro will add more presenter on request. An optional USB sound bar will play a beep when a key has been pressed. TODO: which soundbar

== USB Capture Trigger Setup ==

Please connect the Logitech R400 USB dongle with the Allegro. If you have a virtual Allegro, please pass-through the USB device directly to the Allegro VM.

Once this is done, navigate to the '''Settings''' -> '''Expert Settings''' page and open the '''USB capture trigger'''.

[[File:Presenter dialog.png|600px]]

Once any key has been pressed on the presenter, one pcap will be generated. The pcap end time is when the button has been pressed and the start time is defined by the capture interval. As example, an interval of 60 seconds will generate a capture of the last minute when a presenter key has been pressed.

The captures are stored at the root directory of the storage device or, if enabled, in the upload directory for sftp uploads.

== SFTP Export Setup ==

The Allegro can automatically upload pcap files to an sfp server from the upload directory on the disk. To configure it, please navigate to '''Settings''' → '''Remote Access and Export''' → '''Pcap export via SFTP'''. This allow to export all captured pcap files at a certain time of day. As example it can be used to transfer pcaps during the night from remote locations to a central sftp server.

[[File:Sftp export.png|1000px]]

== Advanced Multi-pcap Setup ==

There are situations where the Allegro shall record multiple separate pcaps for a key with specific filters. This can be done by enabling the '''USB capture filter''' in the '''USB capture trigger''' dialog. The filter syntax is described in the [[Capture module]].

A good example is the installation of an Allegro 500 with 2 links and 2 virtual link groups ( see [[Virtual Link Group Configuration Guide]]), one before and one behind the firewall.

TODO screenshot with 2 configured link groups

As a second example you can record Pcaps of up to 4 different IP addresses at the same time with just one click.

TODO screenshot

USB Presenter Capture

2020-09-02T12:55:32Z

Klaus: /* SFTP Export Setup */

<accesscontrol>AC:GroupUsers</accesscontrol>

This page describes how the Allegro Network Multimeter allows to start a capture with a USB presenter. This capture can be done back in time for a defined period. In addition, the capture files can be uploaded to an sftp server at a defined time.

This feature has been designed to allow non-IT staff to record pcaps at when an error happens it also allows to do captures without opening the web interface.

== Requirements ==

This feature is supported by all Allegro Network Multimeters, even for the VM Version starting at firmware version 3.0. It requires a free USB port on the Allegro with USB 2.0 or higher. One internal or external disk needs to be configured at '''Generic''' → '''Storage''' and a ring buffer must be configured. Please note that the capture is extracted from the ring buffer and a ring buffer filter rules for packet slicing will affect the exported pcap.

As of now, the Logitech R400 is supported. Allegro will add more presenter on request. An optional USB sound bar will play a beep when a key has been pressed. TODO: which soundbar

== USB Capture Trigger Setup ==

Please connect the Logitech R400 USB dongle with the Allegro. If you have a virtual Allegro, please pass-through the USB device directly to the Allegro VM.

Once this is done, navigate to the '''Settings''' -> '''Expert Settings''' page and open the '''USB capture trigger'''.

[[File:Presenter dialog.png|600px]]

Once any key has been pressed on the presenter, one pcap will be generated. The pcap end time is when the button has been pressed and the start time is defined by the capture interval. As example, an interval of 60 seconds will generate a capture of the last minute when a presenter key has been pressed.

The captures are stored at the root directory of the storage device or, if enabled, in the upload directory for sftp uploads.

== SFTP Export Setup ==

The Allegro can automatically upload pcap files to an sfp server from the upload directory on the disk. To configure it, please navigate to '''Settings''' → '''Remote Access and Export''' → '''Pcap export via SFTP'''. This allow to export all captured pcap files at a certain time of day. As example it can be used to transfer pcaps during the night from remote locations to a central sftp server.

[[File:Sftp export.png|1000px]]

== Advanced Multi-pcap Setup ==

There are situations where the Allegro shall record multiple separate pcaps for a key with specific filters. A good example is the installation of an Allegro 500 with 2 linksand 2 virtual link groups ( see [[Virtual Link Group Configuration Guide]]), one before and one behind the firewall.

USB Presenter Capture

2020-09-02T12:54:04Z

Klaus: /* SFTP Export Setup */

<accesscontrol>AC:GroupUsers</accesscontrol>

This page describes how the Allegro Network Multimeter allows to start a capture with a USB presenter. This capture can be done back in time for a defined period. In addition, the capture files can be uploaded to an sftp server at a defined time.

This feature has been designed to allow non-IT staff to record pcaps at when an error happens it also allows to do captures without opening the web interface.

== Requirements ==

This feature is supported by all Allegro Network Multimeters, even for the VM Version starting at firmware version 3.0. It requires a free USB port on the Allegro with USB 2.0 or higher. One internal or external disk needs to be configured at '''Generic''' → '''Storage''' and a ring buffer must be configured. Please note that the capture is extracted from the ring buffer and a ring buffer filter rules for packet slicing will affect the exported pcap.

As of now, the Logitech R400 is supported. Allegro will add more presenter on request. An optional USB sound bar will play a beep when a key has been pressed. TODO: which soundbar

== USB Capture Trigger Setup ==

Please connect the Logitech R400 USB dongle with the Allegro. If you have a virtual Allegro, please pass-through the USB device directly to the Allegro VM.

Once this is done, navigate to the '''Settings''' -> '''Expert Settings''' page and open the '''USB capture trigger'''.

[[File:Presenter dialog.png|600px]]

Once any key has been pressed on the presenter, one pcap will be generated. The pcap end time is when the button has been pressed and the start time is defined by the capture interval. As example, an interval of 60 seconds will generate a capture of the last minute when a presenter key has been pressed.

The captures are stored at the root directory of the storage device or, if enabled, in the upload directory for sftp uploads.

== SFTP Export Setup ==

The Allegro can automatically upload pcap files to an sfp server from the upload directory on the disk. To configure it, please navigate to '''Settings''' → '''Remote Access and Export''' → '''Pcap export via SFTP'''.

[[File:Sftp export.png|1000px]]

== Advanced Multi-pcap Setup ==

There are situations where the Allegro shall record multiple separate pcaps for a key with specific filters. A good example is the installation of an Allegro 500 with 2 linksand 2 virtual link groups ( see [[Virtual Link Group Configuration Guide]]), one before and one behind the firewall.

File:Sftp export.png

2020-09-02T12:53:25Z

Klaus:

USB Presenter Capture

2020-09-02T12:52:38Z

Klaus:

<accesscontrol>AC:GroupUsers</accesscontrol>

This page describes how the Allegro Network Multimeter allows to start a capture with a USB presenter. This capture can be done back in time for a defined period. In addition, the capture files can be uploaded to an sftp server at a defined time.

This feature has been designed to allow non-IT staff to record pcaps at when an error happens it also allows to do captures without opening the web interface.

== Requirements ==

This feature is supported by all Allegro Network Multimeters, even for the VM Version starting at firmware version 3.0. It requires a free USB port on the Allegro with USB 2.0 or higher. One internal or external disk needs to be configured at '''Generic''' → '''Storage''' and a ring buffer must be configured. Please note that the capture is extracted from the ring buffer and a ring buffer filter rules for packet slicing will affect the exported pcap.

As of now, the Logitech R400 is supported. Allegro will add more presenter on request. An optional USB sound bar will play a beep when a key has been pressed. TODO: which soundbar

== USB Capture Trigger Setup ==

Please connect the Logitech R400 USB dongle with the Allegro. If you have a virtual Allegro, please pass-through the USB device directly to the Allegro VM.

Once this is done, navigate to the '''Settings''' -> '''Expert Settings''' page and open the '''USB capture trigger'''.

[[File:Presenter dialog.png|600px]]

Once any key has been pressed on the presenter, one pcap will be generated. The pcap end time is when the button has been pressed and the start time is defined by the capture interval. As example, an interval of 60 seconds will generate a capture of the last minute when a presenter key has been pressed.

The captures are stored at the root directory of the storage device or, if enabled, in the upload directory for sftp uploads.

== SFTP Export Setup ==

The Allegro can automatically upload pcap files to an sfp server from the upload directory on the disk. To configure it, please navigate to '''Settings''' → '''Remote Access and Export''' → '''Pcap export via SFTP'''.

== Advanced Multi-pcap Setup ==

There are situations where the Allegro shall record multiple separate pcaps for a key with specific filters. A good example is the installation of an Allegro 500 with 2 linksand 2 virtual link groups ( see [[Virtual Link Group Configuration Guide]]), one before and one behind the firewall.

Remote access and export

2020-09-02T12:34:08Z

Klaus: /* pcap export via SFTP */

== Statistics Export ==

See [[Statistics Export via POST]] for details about exporting the measurement data via HTTP POST requests.

== SSH port forwarding ==

This option allows to use an external SSH server as an proxy to access the device. Via port forwarding the client PC accesses the SSH proxy which forwards the traffic to the actual Allegro Network Multimeter. See [[Self-hosted_SSH_proxy]] for detailed information how to set up such a server.

== Allegro Remote Service ==

The Allegro Remote Service is similar to the SSH Port Forwarding feature, but the SSH server is provided by Allegro Packets as a public service. Traffic through is proxy is still end-to-end encrypted via your SSL certificate so the data is only accessible to you.

See [[Using the Allegro Remote Service]] for detailed information.

== SNMP ==

See [[SNMP]] for details about SNMP support.

== Pcap export via SFTP ==

The '''Allegro Network Multimeter''' allows the export of captured pcaps via SFTP.
pcap files can be stored in an upload queue and be automatically uploaded to a remote host
once a day.

This feature only works if a disk is attached to the device.

When ''PCAP Export via SFTP'' is enabled, a new checkbox ''Save to SFTP export directory'' is
added to the capture dialogue. If checked, the pcap will be stored to a special
upload directory.

In the configuration view, it is possible to see the files in the upload queue and
delete them or trigger an immediate upload.

SFTP export allows SFTP authentication via public key or via password. The public key
is printed at the top of the configuration view. For public key authentication, the
password field in the SFTP connection parameters can be left empty.

A "Test upload" button uploads a file '''allegro-upload-test.txt''' into the configured
target directory on the remote host.

Remote access and export

2020-09-02T12:33:49Z

Klaus: /* pcap export via SFTP */

== Statistics Export ==

See [[Statistics Export via POST]] for details about exporting the measurement data via HTTP POST requests.

== SSH port forwarding ==

This option allows to use an external SSH server as an proxy to access the device. Via port forwarding the client PC accesses the SSH proxy which forwards the traffic to the actual Allegro Network Multimeter. See [[Self-hosted_SSH_proxy]] for detailed information how to set up such a server.

== Allegro Remote Service ==

The Allegro Remote Service is similar to the SSH Port Forwarding feature, but the SSH server is provided by Allegro Packets as a public service. Traffic through is proxy is still end-to-end encrypted via your SSL certificate so the data is only accessible to you.

See [[Using the Allegro Remote Service]] for detailed information.

== SNMP ==

See [[SNMP]] for details about SNMP support.

== pcap export via SFTP ==

The '''Allegro Network Multimeter''' allows the export of captured pcaps via SFTP.
pcap files can be stored in an upload queue and be automatically uploaded to a remote host
once a day.

This feature only works if a disk is attached to the device.

When ''PCAP Export via SFTP'' is enabled, a new checkbox ''Save to SFTP export directory'' is
added to the capture dialogue. If checked, the pcap will be stored to a special
upload directory.

In the configuration view, it is possible to see the files in the upload queue and
delete them or trigger an immediate upload.

SFTP export allows SFTP authentication via public key or via password. The public key
is printed at the top of the configuration view. For public key authentication, the
password field in the SFTP connection parameters can be left empty.

A "Test upload" button uploads a file '''allegro-upload-test.txt''' into the configured
target directory on the remote host.

File:Presenter dialog.png

2020-09-02T12:13:53Z

Klaus:

USB Presenter Capture

2020-09-02T10:21:58Z

Klaus:

USB Presenter Capture

2020-08-31T12:10:26Z

Klaus: Created page with "<accesscontrol>AC:GroupUsers</accesscontrol> This page describes how the Allegro Network Multimeter allows to start a capture with a USB presenter. This capture can be done b..."

Main Page

2020-08-31T10:11:01Z

Klaus:

__NOTOC__
{|
|[[Image:Combination mark transparent.png|300px|link=https://www.allegro-packets.com]]      
|'''This is the Allegro Packets Product Wiki. Please visit the website of [https://allegro-packets.com Allegro Packets] for more information.'''
|}

{| class="wikitable" style="color:black; background-color:#ffdda3;"
|Translation: Wiki language is English, but you can use [https://translate.google.com/translate?u=allegro-packets.com/wiki automatic Google translation] into your language!
|}

{| class="wikitable" style="color:black; background-color:#fcfcfc; width: 100%;"
|- style="vertical-align:top;"
| style="width: 33%" |
=== Installation ===
* [[Generic Allegro Network Multimeter installation|Generic Allegro Network Multimeter installation and installation guides]]
* Additional installation notes for specific devices:
** [[Allegro 200 series]]
* [[Management interface settings|Configure Management IP address]]
* [[IPMI KVM on Allegro series 1000+]]
* [[User Management|Multi users and permissions]]
* [[Firmware update]]
* [[Performing a factory reset or configuration reset]]
| style="width: 33%" |

=== Typical Installation Setups ===
* [[In-Line Installation|In-Line Installation Guide]]
* [[Mirror Port, TAP and Packet Broker Installation|Mirror Port, TAP and Packet Broker Installation Guide]]
* [[ERSPAN Installation|ERSPAN Installation Guide]]
* [[VMWare Workstation Player/Pro Installation Guide]]
* [[VMWare ESXI Installation Guide]]

| style="width: 33%" |

=== Configuration Guides ===
* [[Setup storage devices for capturing and ring buffer]]
* [[Ring Buffer Configuration Guide]] ( Single Disk, Multiple Cluster,... )
* [[Parallel packet processing|Parallel Packet Processing Configuration Guide]]
* [[Virtual Link Group Configuration Guide]]
* [[Multi-device settings|Multi-Allegro Configuration]]

* [[Performance Optimization Guide]]

|- style="vertical-align:top;"
|

=== Web Interface Manual ===
* [[Introduction]]
* [[Quickstart]]
* [[Usage]]
* [[Measurement modules]]
* [[System Info Page]]
* [[Settings]]
* [[FAQ|FAQ - Frequently Asked Questions]]
* [[Error descriptions]]
* [[Feature documentation]]
|

=== Use Cases ===
* [[Investigate Network Load ]]
* [[Forensic pcap Analysis ]]
* [[Find Profinet problems]]
* [[Network Burst Analysis]]
* [[Burst analysis on a Mirror or Packet Broker input]]
* [[Capturing]]
* [[Investigating network problems on remote sites]]
* [[Debugging Skype Traffic]]
* [[USB Presenter Capture]]
|

=== Data export and third-party tools ===
* [[REST API description]]
* [[Statistics Export via POST]]
* [[SNMP]]
* [[NetFlow/IPFIX interface]]

|- style="vertical-align:top;"
|

=== Remote access ===

* [[Using the Allegro Remote Service]]
* [[Self-hosted SSH proxy]]
|
=== Settings ===

* [[ Global settings]]
* [[ Module settings]]
* [[ Incident settings]]
* [[ User defined names]]
* [[ Management interface settings]]
* [[ Multi-device settings]]
* [[ Virtual_Link_Group_functionality | Virtual link groups]]
* [[ Administration]]
* [[ Ingress filter]]
* [[ Remote access and export]]
* [[ User Management]]
* [[ Firmware update]]
* [[ License upload]]

|

=== Getting support ===

* [[Reaching Allegro Support]]
* [[Reporting bugs]]

|- style="vertical-align:top;"
|
=== Support of third-party hardware ===

* [[List of Supported Transceiver Modules]]
* [[Supported storage devices for x300/x500 series]]
|
=== Addition resources ===
* [[Device icons|Pictograms/Icons/Stencils for all Allegro models]]
|}

Ring Buffer Configuration Guide

2020-06-22T06:37:40Z

Klaus: /* Filter rule examples */

This section describes the '''ring buffer''' configuration and options for the Allegro Network Multimeter.

== What is the '''ring buffer?''' ==

[[File:Historic capture dialog.png|thumb|300px]]
The '''ring buffer''' is a packet buffer. It stores raw Ethernet packets on one or many '''storage devices'''. A '''storage device''' is an internal or external HDD or SSD. If the buffer is full, it will overwrite the oldest packets in a circular manner. The '''ring buffer''' is an optional feature for the Allegro Network Multimeter. It does not store any of the statistics of the In-Memory-Database.

Allegro recommend you to take a look at the [https://allegro-packets.com/en/resources-service/whitepaper/whitepaper-paket-ring-buffer ring buffer White Paper] from the Allegro Packets website.

The '''Webshark''' and the '''pcap''' extraction works with historic dates as in the screenshot here on the right. This dialogue is shown by using the '''pcap''' button in the Allegro User Interface. The Allegro Network Multimeter will search for all packets in the '''ring buffer''' if they match the criteria and extracts the packets.

If there is no '''ring buffer''' configured, the Allegro allows a '''pcap''' extraction of live traffic only.

== Different '''ring buffer''' modes ==

The '''ring buffer''' supports 2 different modes.
The '''single shared ring buffer''' can be used if you need only one ring buffer that fits into your storage device. The '''single shared ring buffer''' uses '''one''' shared storage for the '''ring buffer''' and '''pcap to disk'''. This mode is recommended if only one storage device is used since it allows a '''ring buffer''' and space for '''pcap files''' on the same storage device. Please note that using both features at the same time may lead to a performance bottleneck.

The '''cluster ring buffer''' mode allows to use multiple ring buffers where each ring buffer can have multiple disks. It allows having a separate disk for pcap files which allows fast '''ring buffer''' and fast '''pcap to disk''' writes at the same time.

== '''Single shared ring buffer''' ==

The single shared ring buffer the default setup on all Allegro Network Multimeters that are shipped with '''one''' internal or external storage device. This mode is designed for '''ONE''' internal, external or iSCSI storage device. ( Please see the section [[#iSCSI ring buffer]] for more information ). It does not allow you to use multiple ring buffers with one Allegro Network Multimeter. You can check at '''Generic''' → '''Storage''' if the Allegro Network Multimeter has detected a storage device. Here an example of ONE attached disk:

[[File:Storage no device active.png|border|600px]]

You can activate and deactivate the storage device for pcap files here. You can also format new disks by using the format option and erase the content of a disk if required. If the disk has not been formatted before, press the ''Format'' button here. It will show the dialogue:

[[File:Format disk dialogue.png|border|300px]]

Here you can decide whether disk encryption will be used or not, see [[#Encryption]] below. You can also decide if and how much space can be used for the '''packet ring buffer'''. Please note that you cannot save any pcap files to the external disk when you use '''100 %''' for the '''ring buffer'''.

If the disk has been formatted, you can continue with the configuration of the '''ring buffer''' at '''Generic''' → '''ring buffer'''. If you have created a disk with a ring buffer, you should see the statistics of the buffer as in the screen shot here below.

[[File:Running packet ring buffer.png|border|600px]]

The ring buffer is now running and all pcap buttons will work for historic dates. For advanced setup, please continue at the section [[#Filter Rules]].

== '''Cluster ring buffer''' ==

The cluster ring buffer is the default mode on all Allegro Network Multimeters that are shipped with '''two or more''' internal or external storage devices.

By default, the Allegro Network Multimeter uses '''One''' cluster ring buffer. If you need more, please open the Settings menu at the top right corner.

[[File:Settings button.png|border|100px]]

Here you can increase the number of cluster ring buffers. We will continue this tutorial with 2 ring buffers to show the full flexibility of the Allegro. Please note that you need to restart the processing when you change the parameter. This can be done at '''Settings''' → '''Administration''' → '''Restart processing'''.

To enable the cluster ring buffer mode, please check at '''Generic''' → '''ring buffer''', if the tab ''cluster configuration'' is selected or not. If it is not, selected, delete the non-cluster ring buffer with:

[[File:Delete ring buffer button.png|border|100px]]

Once this is done, you should see the dialogue:

[[File:Select ring buffer.png|border|300px]]

Here you can select '''Create cluster ring buffer'''. Once this is selected, you will see all available clusters of ring buffers. By default, the first cluster is running but has no disk assigned to it. The size of the buffer is 0 Bytes and it drops all packets written into it.

[[File:Cluster ring buffer initial startup.png|border|600px]]

As a next step, please select the configuration for the cluster.

[[File:Cluster ring buffer configuration.png|border|600px]]

Please select here '''Add to cluster''' to format a disk and add it to the cluster. Once you have added disks to a cluster, the packets will be written to the storage device.

[[File:Cluster ring buffer with disks.png|border|600px]]

== Filter Rules ==

Both ring buffer modes support packet filtering mechanisms. Most situations require that only a subset of all packets are stored to the disk. Each ring buffer can be configured by a separate list of rules. All packet that do not match a condition are captured. The first matching condition is applied to the packets.

=== Filter rule conditions ===

The Allegro Network Multimeter supports packet slicing with the following conditions:

* All packets → matches on all Ehternet packets
* MAC address → matches a specific L2 MAC address
* IP Address and IP Subnet → matches a specific IP address and subnet, works for IPv4 and IPv6
* TCP/UDP Ports → matches all TCP or UDP packets with a specific source or destination port
* L7 Protocol → matches one of the built-in L7 protocols
* Outer VLAN Tag → matches a single VLAN tag or the outer VLAN of a double-tagged VLAN frame
* Interface → matches a specific network interface
* SIP Phone Number → matches a specific SIP caller or callee phone number and its correlated RTP flow
* Virtual Link Group → matches a virtual link group

All conditions can be negated to match everything except an IP subnet and similar.

=== Filter rule actions ===

The following items are supported as actions:

* Snapshot Length → byte packet slicing; allows for the capture of only a certain number of bytes per packet
* Discard → do not capture this packet
* Full → capture the full packet
* Header+Data → capture only up to L3 or L4 or a specified quantity of L7 bytes.

=== Filter rule examples ===

Filter rules can be set up below the statistics of each ring buffer. This is a list of the most-used filter rules. Note that you can combine these rules.

==== Capture all traffic from and to a single IP ====

This use case is valid when you need to investigate the packets of one IP but you need the statistics of the total link. This is a common use case where the link bandwidth is above the ring buffer write rate. As an example, it can occur when you monitor a heavy loaded 10G or 40G link with a single HDD as the ring buffer device.

You need to set up 2 rules to capture only one single IP. The first rule matches the IP address and captures the entire payload, the second rule drops all packets. This will also drop all non-IP packets like ARP requests.

[[File:Ring buffer filter one ip.png|border|600px]]

==== Capture SSL traffic only up to L4 ====

Also a common use case is to not capture encrypted content. This can be done by setting up a rule for encrypted L7 protocols to capture only up to the L4 header for IP and TCP investigation. This can be configured with the following settings:

[[File:Ring buffer rule create ssl l4.png|border|400px]]

The configured rule will look like:

[[File:Ring buffer rule ssl l4.png|border|600px]]

==== Capture full SIP, capture RTP to the first 12 bytes of the payload and drop all other packets ====

This is a common VoIP use case where you are allowed to capture the signaling traffic and the RTP header ( 12 bytes ) but not the RTP traffic payload. Here is the example rule setup:

[[File:Ring buffer rule sip rtp.png|border|600px]]

==== Capture all packets except SIP and RTP ====

This use case is very common for all environments where no voice is allowed to be captured. Here is the example rule setup:

[[File:Ring buffer rule drop sip rtp.png|600px]]

== Performance ==

=== Disk read and write performance ===

Note that one disk can have '''one''' shared ring buffer or be part of '''one''' cluster ring buffer. Hard disk drives have a high constant write rate when only one write is active.

The Allegro Network Multimeter has a ''write first'' policy on the ring buffer devices. The Allegro prioritizes writes over reads for storage. A pcap read can be very slow when there is a high write rate to the ring buffer.

=== Concurrent '''ring buffer''' and live '''pcap''' recording ===

Note that HDDs are not made for 2 simultaneous write streams. The write rate will be very low if you capture a live pcap to the single shared storage device while having an active ring buffer. Please use the browser download feature, different disks with the cluster ring buffer or pause the ring buffer while capturing the live pcap.

=== Buffering traffic peaks or disk slowdowns ===

Note that most HDDs and SSDs do not have a guaranteed write rate. Especially HDDs via the USB or SATA3 protocol can have downtimes of hundreds of milliseconds between writes. Each ring buffer uses a certain amount of memory to buffer traffic peaks. This buffer can be configured at the '''Settings''' of the '''ring buffer'''

[[File:Ring buffer queue resize config.png|border|800px]]

You can check if the queue length is large enough with the '''Bytes in Flight''' graph and the '''Dropped Bytes''' graph in the ring buffer statistics.

[[File:Ring buffer data in flight.png|border|800px]]

== iSCSI ring buffer ==

'''''DISCLAIMER''' Whenever possible, use a direct-connected exclusive external storage device via USB. The Allegro Network Multimeter can control the USB channel far better than an iSCSI channel due to exclusivity.''

The iSCSI ring buffer feature allows you to mount an iSCSI volume via the management interface. Allegro recommends to use this feature only for capture rates up to 1GBit/s. The iSCSI controller will have an exclusive low-latency connection to the Allegro Network Multimeter and the rate shall be exclusive to the Allegro Network Multimeter. Also, the management traffic between the Allegro and the iSCSI rate will not be monitored by the Allegro to prevent a write loop.
If the rate is non-exclusive, other reads or writes will heavily reduce the constant write rate. Note that the iSCSI connection is not encrypted.

== Advanced Options ==

=== Disk format ===

The Allegro Network Multimeter uses EXT4 for all formatted file systems for the ring buffer. EXT4 file systems support advanced features that are mandatory to capture with full SSD speed.

=== Encryption ===

The Allegro Network Multimeter uses an '''AES256 LUKS encryption container''' for encrypted single shared ring buffers. You can connect and mount the encrypted disk with many Linux Distributions. It will ask for your password to mount the container.
The Allegro uses hardware encryption if available. The Allegro 200 does not have HW encryption support and can encrypt up to 400MBit/s in software. All other Allegro devices can encrypt with 2GB/s by using the built-in hardware encryption.

The Allegro does ''not'' store the password of the encrypted device on the disk. you need to re-enter the password if you unmount, reboot or power-off the Allegro Network Multimeter.

The encryption is not available for the cluster ring buffer.

File:Ring buffer rule drop sip rtp.png

2020-06-22T06:37:10Z

Klaus:

List of Supported Transceiver Modules

2020-06-19T08:56:40Z

Klaus: /* List of tested third-party modules */

== DISCLAIMER ==

Allegro Packets allows you to use third-party vendor modules in its appliances but guarantees only warranty and support for transceiver modules sold by Allegro Packets. Any malfunction or configuration issue with third-party modules are NOT covered by the warranty.

Allegro Packets does not restrict the use of third-party SFP+ modules for the devices. However, some hardware limitations apply which are described as follows:

== Built-in ports vs. expansion cards ==

The Allegro Network Multimeter 1000/1200/3000/3200 series have two on-board SFP+ ports which are restricted to original or branded '''Intel modules'''.

All non built-in ports are '''not''' vendor locked and can accept all transceiver modules. However, there are modules that do not work because of specific vendor extensions within the modules. This applies for all ports of the Allegro Network Multimeter x300 and x500 series and all expansion cards for the Allegro Network Multimeter 1000/1200/3000/3200.

The following table shows which kind of modules are supported by Allegro by
port type:

{| class="wikitable sortable"
|-
! Port type !!original or branded Intel modules !! non-Intel branded modules
|-
| built-in SFP+ ports || x || -
|-
| SFP+ expansion|| x || x
|-
| SFP28 expansion|| x || x
|-
| QSFP expansion|| x|| x
|-
| QSFP28 expansion|| x || x
|-
|}

The use of Intel branded modules is mandatory for the built-in SFP+ ports. These
restrictions do not apply to the additional network expansion cards
(2 port and 4 port SFP+, high precision GPS card, etc.) that are available for
the Allegro Network Multimeter 1000 and 3000 series. These ports accept
generic modules from a wide range of vendors.

Since auto-negotiation is often not available on 1G/10G SFP+ interfaces, it
may be necessary to manually set the correct speed in the `Interface Stats`
section of the user interface.

QSFP+ breakout cables are NOT supported.

== List of tested third-party modules ==

The following list of modules have been either tested by Allegro or customers and have been reported to operate. Please be aware that this can change due new module revisions.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| SFP+ || Intel E10GSFPSR || Fiber (SR) || supports 1G and 10G operation
|-
| SFP+ || Intel E10GSFPLR || Fiber (LR) || supports 1G and 10G operation
|-
| SFP+ || Intel XDACBL1M, XDACBL3M or XDACBL5M|| DA(Copper, Passive) ||
|-
| SFP+ || Flexoptix P.8596.02 || Fiber (SR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || Flexoptix P.1396.10 || Fiber (LR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || fs.com 36431 || Fiber (SR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP+ || fs.com 36432 || Fiber (LR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP28 || Flexoptix P.8525G.01 || Fiber (SR) || recommended with Intel branding
|-
| SFP28 || Flexoptix P.1325G.10 || Fiber (LR) || recommended with Intel branding
|-
| SFP28 || fs.com 68000 || Fiber (SR) || requires Intel branding
|-
| QSFP+ || Flexoptix Q.8540G.02 || Fiber (SR4) || recommended with Intel branding
|-
| QSFP+ || Flexoptix Q.1640G.10 || Fiber (LR4) || recommended with Intel branding
|-
| QSFP+ || FINISAR FTL4C1QE1C || Fiber (LR4) ||
|-
| QSFP+ || FINISAR FTL410QD2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE1C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE3C || Fiber (SR4) ||
|-
| QSFP+ || Amphenol 603020002, 603020005 || DA(Copper, Passive) ||
|-
| QSFP28 || Flexoptix Q.851HG.02 || Fiber (SR4) ||
|-
| QSFP28 || Flexoptix Q.161HG.10 || Fiber (LR4) ||
|-
| QSFP28 || fs.com 75308 || Fiber (SR4) ||
|-
| QSFP28 || Cisco QSFP-100G-CU (1M, 2M, 3M, 5M) || DA(Copper, Passive) ||
|}

== Non-working modules ==

Original Cisco modules have many issues working in the Allegro. Allegro got the feedback from multiple customers that they have issues with Cisco modules.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| QSFP+ 40G SR BG || Cisco qsfp-40g-sr-bg P/N: 191402 || Fiber (SR4) || only partial support, modules must be (re-) inserted after power up
|-
| QSFP+ 40G SR4 || Cisco qsfp-40g-sr4 P/N: 186602 || Fiber (SR4) || only partial support, modules must be (re-) inserted after power up
|-
| QSFP+ 40G AOC || Cisco qsfp-h40g-aoc10m P/N: 187627 || Fiber (SR) || only partial support, modules must be (re-) inserted after power up
|-
| QFSP+ 40/100 SRBD || Cisco qsfp-40/100-srbd P/N: 199804 || Fiber (SR) || does '''NOT''' work
|-
| QFSP28 || Cisco QSFP-100G-SM-SR || Fiber (LR4 lite) || does '''NOT''' work
|}

List of Supported Transceiver Modules

2020-06-19T08:54:03Z

Klaus: /* Non-working modules */

== DISCLAIMER ==

Allegro Packets allows you to use third-party vendor modules in its appliances but guarantees only warranty and support for transceiver modules sold by Allegro Packets. Any malfunction or configuration issue with third-party modules are NOT covered by the warranty.

Allegro Packets does not restrict the use of third-party SFP+ modules for the devices. However, some hardware limitations apply which are described as follows:

== Built-in ports vs. expansion cards ==

The Allegro Network Multimeter 1000/1200/3000/3200 series have two on-board SFP+ ports which are restricted to original or branded '''Intel modules'''.

All non built-in ports are '''not''' vendor locked and can accept all transceiver modules. However, there are modules that do not work because of specific vendor extensions within the modules. This applies for all ports of the Allegro Network Multimeter x300 and x500 series and all expansion cards for the Allegro Network Multimeter 1000/1200/3000/3200.

The following table shows which kind of modules are supported by Allegro by
port type:

{| class="wikitable sortable"
|-
! Port type !!original or branded Intel modules !! non-Intel branded modules
|-
| built-in SFP+ ports || x || -
|-
| SFP+ expansion|| x || x
|-
| SFP28 expansion|| x || x
|-
| QSFP expansion|| x|| x
|-
| QSFP28 expansion|| x || x
|-
|}

The use of Intel branded modules is mandatory for the built-in SFP+ ports. These
restrictions do not apply to the additional network expansion cards
(2 port and 4 port SFP+, high precision GPS card, etc.) that are available for
the Allegro Network Multimeter 1000 and 3000 series. These ports accept
generic modules from a wide range of vendors.

Since auto-negotiation is often not available on 1G/10G SFP+ interfaces, it
may be necessary to manually set the correct speed in the `Interface Stats`
section of the user interface.

QSFP+ breakout cables are NOT supported.

== List of tested third-party modules ==

The following list of modules have been either tested by Allegro or customers and have been reported to operate. Please be aware that this can change due new module revisions.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| SFP+ || Intel E10GSFPSR || Fiber (SR) || supports 1G and 10G operation
|-
| SFP+ || Intel E10GSFPLR || Fiber (LR) || supports 1G and 10G operation
|-
| SFP+ || Intel XDACBL1M, XDACBL3M or XDACBL5M|| DA(Copper, Passive) ||
|-
| SFP+ || Flexoptix P.8596.02 || Fiber (SR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || Flexoptix P.1396.10 || Fiber (LR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || fs.com 36431 || Fiber (SR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP+ || fs.com 36432 || Fiber (LR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP28 || Flexoptix P.8525G.01 || Fiber (SR) || recommended with Intel branding
|-
| SFP28 || Flexoptix P.1325G.10 || Fiber (LR) || recommended with Intel branding
|-
| SFP28 || fs.com 68000 || Fiber (SR) || requires Intel branding
|-
| QSFP+ || Flexoptix Q.8540G.02 || Fiber (SR4) || recommended with Intel branding
|-
| QSFP+ || Flexoptix Q.1640G.10 || Fiber (LR4) || recommended with Intel branding
|-
| QSFP+ || FINISAR FTL4C1QE1C || Fiber (LR4) ||
|-
| QSFP+ || FINISAR FTL410QD2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE1C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE3C || Fiber (SR4) ||
|-
| QSFP+ || Amphenol 603020002, 603020005 || DA(Copper, Passive) ||
|-
| QSFP28 || Flexoptix Q.851HG.02 || Fiber (SR4) ||
|-
| QSFP28 || Flexoptix Q.161HG.10 || Fiber (LR4) ||
|-
| QSFP28 || fs.com 75308 || Fiber (SR4) ||
|}

== Non-working modules ==

Original Cisco modules have many issues working in the Allegro. Allegro got the feedback from multiple customers that they have issues with Cisco modules.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| QSFP+ 40G SR BG || Cisco qsfp-40g-sr-bg P/N: 191402 || Fiber (SR4) || only partial support, modules must be (re-) inserted after power up
|-
| QSFP+ 40G SR4 || Cisco qsfp-40g-sr4 P/N: 186602 || Fiber (SR4) || only partial support, modules must be (re-) inserted after power up
|-
| QSFP+ 40G AOC || Cisco qsfp-h40g-aoc10m P/N: 187627 || Fiber (SR) || only partial support, modules must be (re-) inserted after power up
|-
| QFSP+ 40/100 SRBD || Cisco qsfp-40/100-srbd P/N: 199804 || Fiber (SR) || does '''NOT''' work
|-
| QFSP28 || Cisco QSFP-100G-SM-SR || Fiber (LR4 lite) || does '''NOT''' work
|}

List of Supported Transceiver Modules

2020-06-19T08:53:52Z

Klaus: /* Non-working modules */

== DISCLAIMER ==

Allegro Packets allows you to use third-party vendor modules in its appliances but guarantees only warranty and support for transceiver modules sold by Allegro Packets. Any malfunction or configuration issue with third-party modules are NOT covered by the warranty.

Allegro Packets does not restrict the use of third-party SFP+ modules for the devices. However, some hardware limitations apply which are described as follows:

== Built-in ports vs. expansion cards ==

The Allegro Network Multimeter 1000/1200/3000/3200 series have two on-board SFP+ ports which are restricted to original or branded '''Intel modules'''.

All non built-in ports are '''not''' vendor locked and can accept all transceiver modules. However, there are modules that do not work because of specific vendor extensions within the modules. This applies for all ports of the Allegro Network Multimeter x300 and x500 series and all expansion cards for the Allegro Network Multimeter 1000/1200/3000/3200.

The following table shows which kind of modules are supported by Allegro by
port type:

{| class="wikitable sortable"
|-
! Port type !!original or branded Intel modules !! non-Intel branded modules
|-
| built-in SFP+ ports || x || -
|-
| SFP+ expansion|| x || x
|-
| SFP28 expansion|| x || x
|-
| QSFP expansion|| x|| x
|-
| QSFP28 expansion|| x || x
|-
|}

The use of Intel branded modules is mandatory for the built-in SFP+ ports. These
restrictions do not apply to the additional network expansion cards
(2 port and 4 port SFP+, high precision GPS card, etc.) that are available for
the Allegro Network Multimeter 1000 and 3000 series. These ports accept
generic modules from a wide range of vendors.

Since auto-negotiation is often not available on 1G/10G SFP+ interfaces, it
may be necessary to manually set the correct speed in the `Interface Stats`
section of the user interface.

QSFP+ breakout cables are NOT supported.

== List of tested third-party modules ==

The following list of modules have been either tested by Allegro or customers and have been reported to operate. Please be aware that this can change due new module revisions.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| SFP+ || Intel E10GSFPSR || Fiber (SR) || supports 1G and 10G operation
|-
| SFP+ || Intel E10GSFPLR || Fiber (LR) || supports 1G and 10G operation
|-
| SFP+ || Intel XDACBL1M, XDACBL3M or XDACBL5M|| DA(Copper, Passive) ||
|-
| SFP+ || Flexoptix P.8596.02 || Fiber (SR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || Flexoptix P.1396.10 || Fiber (LR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || fs.com 36431 || Fiber (SR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP+ || fs.com 36432 || Fiber (LR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP28 || Flexoptix P.8525G.01 || Fiber (SR) || recommended with Intel branding
|-
| SFP28 || Flexoptix P.1325G.10 || Fiber (LR) || recommended with Intel branding
|-
| SFP28 || fs.com 68000 || Fiber (SR) || requires Intel branding
|-
| QSFP+ || Flexoptix Q.8540G.02 || Fiber (SR4) || recommended with Intel branding
|-
| QSFP+ || Flexoptix Q.1640G.10 || Fiber (LR4) || recommended with Intel branding
|-
| QSFP+ || FINISAR FTL4C1QE1C || Fiber (LR4) ||
|-
| QSFP+ || FINISAR FTL410QD2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE1C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE3C || Fiber (SR4) ||
|-
| QSFP+ || Amphenol 603020002, 603020005 || DA(Copper, Passive) ||
|-
| QSFP28 || Flexoptix Q.851HG.02 || Fiber (SR4) ||
|-
| QSFP28 || Flexoptix Q.161HG.10 || Fiber (LR4) ||
|-
| QSFP28 || fs.com 75308 || Fiber (SR4) ||
|}

== Non-working modules ==

Original Cisco modules have many issues working in the Allegro. Allegro got the feedback from multiple customers that they have issues with Cisco modules.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| QSFP+ 40G SR BG || Cisco qsfp-40g-sr-bg P/N: 191402 || Fiber (SR4) || only partial support, modules must be (re-) inserted after power up
|-
| QSFP+ 40G SR4 || Cisco qsfp-40g-sr4 P/N: 186602 || Fiber (SR4) || only partial support, modules must be (re-) inserted after power up
|-
| QSFP+ 40G AOC || Cisco qsfp-h40g-aoc10m P/N: 187627 || Fiber (SR) || only partial support, modules must be (re-) inserted after power up
|-
| QFSP+ 40/100 SRBD || Cisco qsfp-40/100-srbd P/N: 199804 || Fiber (SR) || does '''NOT''' work
|-
| QFSP28 || Cisco QSFP-100G-SM-SR || Fiber (LR lite) || does '''NOT''' work
|}

List of Supported Transceiver Modules

2020-06-19T08:53:04Z

Klaus: /* List of tested third-party modules */

== DISCLAIMER ==

Allegro Packets allows you to use third-party vendor modules in its appliances but guarantees only warranty and support for transceiver modules sold by Allegro Packets. Any malfunction or configuration issue with third-party modules are NOT covered by the warranty.

Allegro Packets does not restrict the use of third-party SFP+ modules for the devices. However, some hardware limitations apply which are described as follows:

== Built-in ports vs. expansion cards ==

The Allegro Network Multimeter 1000/1200/3000/3200 series have two on-board SFP+ ports which are restricted to original or branded '''Intel modules'''.

All non built-in ports are '''not''' vendor locked and can accept all transceiver modules. However, there are modules that do not work because of specific vendor extensions within the modules. This applies for all ports of the Allegro Network Multimeter x300 and x500 series and all expansion cards for the Allegro Network Multimeter 1000/1200/3000/3200.

The following table shows which kind of modules are supported by Allegro by
port type:

{| class="wikitable sortable"
|-
! Port type !!original or branded Intel modules !! non-Intel branded modules
|-
| built-in SFP+ ports || x || -
|-
| SFP+ expansion|| x || x
|-
| SFP28 expansion|| x || x
|-
| QSFP expansion|| x|| x
|-
| QSFP28 expansion|| x || x
|-
|}

The use of Intel branded modules is mandatory for the built-in SFP+ ports. These
restrictions do not apply to the additional network expansion cards
(2 port and 4 port SFP+, high precision GPS card, etc.) that are available for
the Allegro Network Multimeter 1000 and 3000 series. These ports accept
generic modules from a wide range of vendors.

Since auto-negotiation is often not available on 1G/10G SFP+ interfaces, it
may be necessary to manually set the correct speed in the `Interface Stats`
section of the user interface.

QSFP+ breakout cables are NOT supported.

== List of tested third-party modules ==

The following list of modules have been either tested by Allegro or customers and have been reported to operate. Please be aware that this can change due new module revisions.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| SFP+ || Intel E10GSFPSR || Fiber (SR) || supports 1G and 10G operation
|-
| SFP+ || Intel E10GSFPLR || Fiber (LR) || supports 1G and 10G operation
|-
| SFP+ || Intel XDACBL1M, XDACBL3M or XDACBL5M|| DA(Copper, Passive) ||
|-
| SFP+ || Flexoptix P.8596.02 || Fiber (SR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || Flexoptix P.1396.10 || Fiber (LR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || fs.com 36431 || Fiber (SR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP+ || fs.com 36432 || Fiber (LR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP28 || Flexoptix P.8525G.01 || Fiber (SR) || recommended with Intel branding
|-
| SFP28 || Flexoptix P.1325G.10 || Fiber (LR) || recommended with Intel branding
|-
| SFP28 || fs.com 68000 || Fiber (SR) || requires Intel branding
|-
| QSFP+ || Flexoptix Q.8540G.02 || Fiber (SR4) || recommended with Intel branding
|-
| QSFP+ || Flexoptix Q.1640G.10 || Fiber (LR4) || recommended with Intel branding
|-
| QSFP+ || FINISAR FTL4C1QE1C || Fiber (LR4) ||
|-
| QSFP+ || FINISAR FTL410QD2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE1C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE3C || Fiber (SR4) ||
|-
| QSFP+ || Amphenol 603020002, 603020005 || DA(Copper, Passive) ||
|-
| QSFP28 || Flexoptix Q.851HG.02 || Fiber (SR4) ||
|-
| QSFP28 || Flexoptix Q.161HG.10 || Fiber (LR4) ||
|-
| QSFP28 || fs.com 75308 || Fiber (SR4) ||
|}

== Non-working modules ==

Original Cisco modules have many issues working in the Allegro. Allegro got the feedback from multiple customers that they have issues with Cisco modules.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| QFSP+ 40/100 SRBD || Cisco qsfp-40/100-srbd P/N: 199804 || Fiber (SR) || does '''NOT''' work
|-
| QFSP28 || Cisco QSFP-100G-SM-SR || Fiber (LR lite) || does '''NOT''' work

|}

List of Supported Transceiver Modules

2020-06-19T08:52:43Z

Klaus: /* Non-working modules */

== DISCLAIMER ==

Allegro Packets allows you to use third-party vendor modules in its appliances but guarantees only warranty and support for transceiver modules sold by Allegro Packets. Any malfunction or configuration issue with third-party modules are NOT covered by the warranty.

Allegro Packets does not restrict the use of third-party SFP+ modules for the devices. However, some hardware limitations apply which are described as follows:

== Built-in ports vs. expansion cards ==

The Allegro Network Multimeter 1000/1200/3000/3200 series have two on-board SFP+ ports which are restricted to original or branded '''Intel modules'''.

All non built-in ports are '''not''' vendor locked and can accept all transceiver modules. However, there are modules that do not work because of specific vendor extensions within the modules. This applies for all ports of the Allegro Network Multimeter x300 and x500 series and all expansion cards for the Allegro Network Multimeter 1000/1200/3000/3200.

The following table shows which kind of modules are supported by Allegro by
port type:

{| class="wikitable sortable"
|-
! Port type !!original or branded Intel modules !! non-Intel branded modules
|-
| built-in SFP+ ports || x || -
|-
| SFP+ expansion|| x || x
|-
| SFP28 expansion|| x || x
|-
| QSFP expansion|| x|| x
|-
| QSFP28 expansion|| x || x
|-
|}

The use of Intel branded modules is mandatory for the built-in SFP+ ports. These
restrictions do not apply to the additional network expansion cards
(2 port and 4 port SFP+, high precision GPS card, etc.) that are available for
the Allegro Network Multimeter 1000 and 3000 series. These ports accept
generic modules from a wide range of vendors.

Since auto-negotiation is often not available on 1G/10G SFP+ interfaces, it
may be necessary to manually set the correct speed in the `Interface Stats`
section of the user interface.

QSFP+ breakout cables are NOT supported.

== List of tested third-party modules ==

The following list of modules have been either tested by Allegro or customers and have been reported to operate. Please be aware that this can change due new module revisions.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| SFP+ || Intel E10GSFPSR || Fiber (SR) || supports 1G and 10G operation
|-
| SFP+ || Intel E10GSFPLR || Fiber (LR) || supports 1G and 10G operation
|-
| SFP+ || Intel XDACBL1M, XDACBL3M or XDACBL5M|| DA(Copper, Passive) ||
|-
| SFP+ || Flexoptix P.8596.02 || Fiber (SR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || Flexoptix P.1396.10 || Fiber (LR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || fs.com 36431 || Fiber (SR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP+ || fs.com 36432 || Fiber (LR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP28 || Flexoptix P.8525G.01 || Fiber (SR) || recommended with Intel branding
|-
| SFP28 || Flexoptix P.1325G.10 || Fiber (LR) || recommended with Intel branding
|-
| SFP28 || fs.com 68000 || Fiber (SR) || requires Intel branding
|-
| QSFP+ || Flexoptix Q.8540G.02 || Fiber (SR4) || recommended with Intel branding
|-
| QSFP+ || Flexoptix Q.1640G.10 || Fiber (LR4) || recommended with Intel branding
|-
| QSFP+ || FINISAR FTL4C1QE1C || Fiber (LR4) ||
|-
| QSFP+ || FINISAR FTL410QD2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE1C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE3C || Fiber (SR4) ||
|-
| QSFP+ || Amphenol 603020002, 603020005 || DA(Copper, Passive) ||
|-
| QSFP+ 40G SR BG || Cisco qsfp-40g-sr-bg P/N: 191402 || Fiber (SR4) || modules must be (re-) inserted after power up
|-
| QSFP+ 40G SR4 || Cisco qsfp-40g-sr4 P/N: 186602 || Fiber (SR4) || modules must be (re-) inserted after power up
|-
| QSFP+ 40G AOC || Cisco qsfp-h40g-aoc10m P/N: 187627 || Fiber (SR) || modules must be (re-) inserted after power up
|-
| QSFP28 || Flexoptix Q.851HG.02 || Fiber (SR4) ||
|-
| QSFP28 || Flexoptix Q.161HG.10 || Fiber (LR4) ||
|-
| QSFP28 || fs.com 75308 || Fiber (SR4) ||
|}

== Non-working modules ==

Original Cisco modules have many issues working in the Allegro. Allegro got the feedback from multiple customers that they have issues with Cisco modules.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| QFSP+ 40/100 SRBD || Cisco qsfp-40/100-srbd P/N: 199804 || Fiber (SR) || does '''NOT''' work
|-
| QFSP28 || Cisco QSFP-100G-SM-SR || Fiber (LR lite) || does '''NOT''' work

|}

List of Supported Transceiver Modules

2020-06-19T08:48:12Z

Klaus: /* List of tested third-party modules */

== DISCLAIMER ==

Allegro Packets allows you to use third-party vendor modules in its appliances but guarantees only warranty and support for transceiver modules sold by Allegro Packets. Any malfunction or configuration issue with third-party modules are NOT covered by the warranty.

Allegro Packets does not restrict the use of third-party SFP+ modules for the devices. However, some hardware limitations apply which are described as follows:

== Built-in ports vs. expansion cards ==

The Allegro Network Multimeter 1000/1200/3000/3200 series have two on-board SFP+ ports which are restricted to original or branded '''Intel modules'''.

All non built-in ports are '''not''' vendor locked and can accept all transceiver modules. However, there are modules that do not work because of specific vendor extensions within the modules. This applies for all ports of the Allegro Network Multimeter x300 and x500 series and all expansion cards for the Allegro Network Multimeter 1000/1200/3000/3200.

The following table shows which kind of modules are supported by Allegro by
port type:

{| class="wikitable sortable"
|-
! Port type !!original or branded Intel modules !! non-Intel branded modules
|-
| built-in SFP+ ports || x || -
|-
| SFP+ expansion|| x || x
|-
| SFP28 expansion|| x || x
|-
| QSFP expansion|| x|| x
|-
| QSFP28 expansion|| x || x
|-
|}

The use of Intel branded modules is mandatory for the built-in SFP+ ports. These
restrictions do not apply to the additional network expansion cards
(2 port and 4 port SFP+, high precision GPS card, etc.) that are available for
the Allegro Network Multimeter 1000 and 3000 series. These ports accept
generic modules from a wide range of vendors.

Since auto-negotiation is often not available on 1G/10G SFP+ interfaces, it
may be necessary to manually set the correct speed in the `Interface Stats`
section of the user interface.

QSFP+ breakout cables are NOT supported.

== List of tested third-party modules ==

The following list of modules have been either tested by Allegro or customers and have been reported to operate. Please be aware that this can change due new module revisions.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| SFP+ || Intel E10GSFPSR || Fiber (SR) || supports 1G and 10G operation
|-
| SFP+ || Intel E10GSFPLR || Fiber (LR) || supports 1G and 10G operation
|-
| SFP+ || Intel XDACBL1M, XDACBL3M or XDACBL5M|| DA(Copper, Passive) ||
|-
| SFP+ || Flexoptix P.8596.02 || Fiber (SR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || Flexoptix P.1396.10 || Fiber (LR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || fs.com 36431 || Fiber (SR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP+ || fs.com 36432 || Fiber (LR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP28 || Flexoptix P.8525G.01 || Fiber (SR) || recommended with Intel branding
|-
| SFP28 || Flexoptix P.1325G.10 || Fiber (LR) || recommended with Intel branding
|-
| SFP28 || fs.com 68000 || Fiber (SR) || requires Intel branding
|-
| QSFP+ || Flexoptix Q.8540G.02 || Fiber (SR4) || recommended with Intel branding
|-
| QSFP+ || Flexoptix Q.1640G.10 || Fiber (LR4) || recommended with Intel branding
|-
| QSFP+ || FINISAR FTL4C1QE1C || Fiber (LR4) ||
|-
| QSFP+ || FINISAR FTL410QD2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE1C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE3C || Fiber (SR4) ||
|-
| QSFP+ || Amphenol 603020002, 603020005 || DA(Copper, Passive) ||
|-
| QSFP+ 40G SR BG || Cisco qsfp-40g-sr-bg P/N: 191402 || Fiber (SR4) || modules must be (re-) inserted after power up
|-
| QSFP+ 40G SR4 || Cisco qsfp-40g-sr4 P/N: 186602 || Fiber (SR4) || modules must be (re-) inserted after power up
|-
| QSFP+ 40G AOC || Cisco qsfp-h40g-aoc10m P/N: 187627 || Fiber (SR) || modules must be (re-) inserted after power up
|-
| QSFP28 || Flexoptix Q.851HG.02 || Fiber (SR4) ||
|-
| QSFP28 || Flexoptix Q.161HG.10 || Fiber (LR4) ||
|-
| QSFP28 || fs.com 75308 || Fiber (SR4) ||
|}

== Non-working modules ==

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| QFSP+ 40/100 SRBD || Cisco qsfp-40/100-srbd P/N: 199804 || Fiber (SR) || non-standard module, does '''NOT''' work
|}

REST API description

2020-05-28T08:54:52Z

Klaus:

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).

Here an example of the structured JSON data for the IP overview. This data has been extracted with the Google Chrome developer console while accessing the IP statsistics page.

[[File:Rest api chrome console.png|800px]]

=== 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 [https://en.wikipedia.org/wiki/CURL]. 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 )

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

Please note that you might need to use <code>curl.exe</code> 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''' [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-restmethod].
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:

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

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

<code>-ContentType'application/json; charset=utf-8'</code>

To disable the certificate check, use:

<code>-SkipCertificateCheck</code>

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

<code>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</code>

=== jq ===

jq ( [https://stedolan.github.io/jq/] ) is a powerful tool to extract parameters from a json document. If called without parameters, jq formats the JSON output into a readable format with indenting and new lines. It also allows to select specific values and do basic operations like addition with this values.
Please read the jq documentation for more information.

== API hierarchy ==

=== Query available URIs with OPTIONS ===

The Allegro REST API has the fixed URI <code>API/stats</code> for statistics. To see all possible subtrees of a specific request, use the '''OPTIONS''' request instead of '''GET'''. It can be set with the parameter <code>-X OPTIONS</code> for curl.

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats' -X OPTIONS
{
"subResources": [
"modules",
"reports",
"incidentReporting",
"time",
"ringBufferReplay",
"pcap",
"reset",
"interfacesError",
"interfaces",
"load",
"processing"
]
}
</pre>

This allows you to query for example for all modules that are available for a specific release of the Allegro:

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules' -X OPTIONS
{
"subResources": [
"pppoe",
"lldp",
"groups",
"mpls",
"opc_ua",
"quality",
"ipsec",
"profinet",
"multicast",
"burst_analysis",
"global_incidents",
"ptp",
"ntp",
"icmp",
"stp",
"sip",
"smb",
"dpa",
"l4_ports",
"netbios",
"crt",
"dpi",
"http",
"ssl",
"dns",
"dhcp",
"location",
"qos",
"ip",
"mac_protocols",
"vlan",
"arp",
"packet_size",
"mac",
"capture"
]
}
</pre>

=== URI content parameters ===

Some modules allow to use a parameter as part of the URI like the IP or Mac address. The path <code>API/stats/modules/ip/ips</code> allows you to use an IP address as next uri element

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips' -X OPTIONS
{
"subResources": [
"protocol",
":ip"
]
}
</pre>

The path of an IP address shows all further available elements:

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.0.54.254' -X OPTIONS
{
"subResources": [
"sip_request_responses",
"peers_ports",
"sip_responses",
"sip_requests",
"qos",
"ports",
"connections",
"protocols",
"macs",
"peers",
"tcpStats"
]
}
</pre>

== JSON output traffic counters ==

All counters are aggregated counters, either for the selected time interval or since the processing start of the Allegro. Many traffic counters have 4 separate values. These traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows:
* line 1: '''received packets''', extraction example: jq .lastSecond[0]
* line 2: '''received bytes''', extraction example: jq .lastSecond[1]
* line 3: '''transmitted packets''', extraction example: jq .lastSecond[2]
* line 4: '''transmitted bytes''', extraction example: jq .lastSecond[3]
* additional lines are module specific

The following counters exist for many REST APIs like IP, MAC, l4 protocol, l7 protocol and many more:
* '''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.

Please note that all counters are byte counters, not bit counters. You need to multiply the counters by 8 to get the bitrate.

This example extracts the received bytes of the last second of a specific IP.

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

This example extracts received and transmitted bytes of the last second of a specific IP.

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

== API parameters ==

The Allegro REST API has a number of query parameters that can be added to modify the request. By default, the API will display the real time counters since the last restart of the processing unit.

This example extracts the amount of received and transmitted bytes for an IP address since the processing start of the Allegro. It queries via the REST API the JSON and then adds the values second value ( row 1, rx bytes ) and 4th value ( row 3, tx bytes ) of the interval counters together.

<pre>
$ curl --silent -k -u USER:PASSWORD "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254" | jq '.interval[1] + .interval[3]'
</pre>

=== Time interval selection ===

Requests can be given a time interval. If present, the '''interval''' counters are adjusted to this 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). You can use <code>date +%s</code> on your machine to adjust to the best interval. Please consult the man page of date for more parameters.
* '''skiphistorydata''': shall the JSON include the history data without datasets, this reduces the amount of transferred bytes if datasets are required to render a graph, can be false/true default: false
* '''timespan''': required resolution for the graph dataset

This example extracts the amount of received and transmitted bytes for an IP address for the last 24 hours.
<pre>
$ curl --silent -k -u USER:PASSWORD "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?starttime=$(date --date="1 day ago" +%s)&endtime=$(date +%s)&skiphistorydata=true" | jq '.interval[1] + .interval[3]'
</pre>

=== 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).

This example shows IP address with the highest amount of traffic

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

This exampe shows up to 9999 peers of a specific IP address:

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/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'</code>

=== Pcap extraction ===

The Allegro Network Multimeter allows to extract the raw packets with the REST API with the special capture URI <code>/API/data/modules/capture</code>

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

The available parameters are:

* '''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. If not specified, the current time will be used.
* '''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). If not specified, unlimited will be used.
* expression: The filter expression. There are no whitespaces allowed. You may use ‘%20’ instead. See [[Capture module]] for available expressions.
* 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).

Example to capture everything from now on:

<code>curl -k -u USER:PASSWORD 'https://allegro-mm/API/data/modules/capture' > path_to/capture.pcap</code>

Example to capture a specific IP of the last hour

<code>curl -k -u USER:PASSWORD "https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3&starttime=$(date --date="1 hour ago" +%s)&endtime=$(date +%s)&fromCaptureBuffer=true" > path_to/capture.pcap</code>

=== Virtual Link Groups ===

The Allegro REST API allows to access all link groups by the parameter '''group'''. The group index starts at zero, which is the default value. If a virtual link group is enabled.

This example extracts the traffic of the IP 10.54.0.254 from the second virtual link group ( index 1 ).

<pre>
$ curl --silent -k -u USER:PASSWORD "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?group=1" | jq '.interval[1] + .interval[3]'
</pre>

=== Parallel pcap analysis ===

The Allegro can process in parallel offline traffic like a pcap file or a ring buffer. In case a parallel PCAP analysis is running, the API call must be given the additional header field <code>"X-AllegroPackets-Multimeter-ID: :1"</code> with the PCAP instance ID.

This allows to extract information of automated pcap uploads.

=== Multi-device analysis ===

If the Allegro is configured as a gateway for multiple Allegro devices by the [[Multi-device settings]], you need to add the additional header field <code>"X-AllegroPackets-Multimeter-ID: hostname"</code> where the hostname must be the same as configured in the multi-device settings.

== REST API Examples ==

==== MAC statistics ====

Extract the packets per second statistic of the MAC broadcast address

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/mac/macs/ff:ff:ff:ff:ff:ff'</code>

==== IP statistics ====

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.1.2.3'</code>

==== Pretty displaying JSON output with jq ====

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

==== Capture a specific IP ====

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

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

<code>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</code>

Burst analysis on a Mirror or Packet Broker input

2020-05-28T08:49:42Z

Klaus: /* Problem */

<accesscontrol>AC:GroupUsers</accesscontrol>

== Problem ==

The Allegro Network Multimeter is connected to a mirror port or packet broker. By default, this makes it very hard to analyze a specific Link for bursts as the packet are aggregated on the mirror or packet broker port.

Please note that this guide is based on the manual [[Burst analysis]] and on the use case guide [[Network Burst Analysis]].

== Link Burst Measurement ==

By default, each Multimeter measures the Bursts per Interface at '''L2 Ethernet''' → ''' Burst Analysis'''

[[File:Burst link measurement.png|500px]]

Here you can configure the speed per link as the maximum speed.

== MAC Burst measurement ==

To analyze a specific link, you can use the MAC burst analysis. This is shown at the tab '''MACs''' in the burst analysis. It allows to set a specific receive and send packet rate for one mac address. If you have an uplink, simply use the routers MAC address here and the specify the maximum receive and send rate of the routers uplink.

In this example, I have used a test link with 250MBit/s downlink and 40MBit/s uplink for the Router Mac address.

[[File:Burst mac measurement.png|500px]]

Please note that the Burst analysis is done with 1 millisecond resolution by default. In our example, the router is connected with 1 GBit/s and it can send more than the configured bandwidth. This is shown in the display as an utilization of ">> 100%" and indicates a burst that might not be able to be handeled by this uplink.

== Advantage for Mirror Port and Packet Brokers ==

The MAC burst detection can be used for a specific end device ( a file server,... ) or for the gateway of an uplink ( router,... ). It allows to monitor links and end devices even in out-of-band installations.

Burst analysis on a Mirror or Packet Broker input

2020-05-28T08:48:45Z

Klaus:

<accesscontrol>AC:GroupUsers</accesscontrol>

== Problem ==

The Allegro Network Multimeter is connected to a mirror port or packet broker. By default, this makes it very hard to analyze a specific Link for bursts as the packet are aggregated on the mirror or packet broker port.

Please note that this guide is based on the use case guide [[Network Burst Analysis]].

== Link Burst Measurement ==

By default, each Multimeter measures the Bursts per Interface at '''L2 Ethernet''' → ''' Burst Analysis'''

[[File:Burst link measurement.png|500px]]

Here you can configure the speed per link as the maximum speed.

== MAC Burst measurement ==

To analyze a specific link, you can use the MAC burst analysis. This is shown at the tab '''MACs''' in the burst analysis. It allows to set a specific receive and send packet rate for one mac address. If you have an uplink, simply use the routers MAC address here and the specify the maximum receive and send rate of the routers uplink.

In this example, I have used a test link with 250MBit/s downlink and 40MBit/s uplink for the Router Mac address.

[[File:Burst mac measurement.png|500px]]

Please note that the Burst analysis is done with 1 millisecond resolution by default. In our example, the router is connected with 1 GBit/s and it can send more than the configured bandwidth. This is shown in the display as an utilization of ">> 100%" and indicates a burst that might not be able to be handeled by this uplink.

== Advantage for Mirror Port and Packet Brokers ==

The MAC burst detection can be used for a specific end device ( a file server,... ) or for the gateway of an uplink ( router,... ). It allows to monitor links and end devices even in out-of-band installations.

Burst analysis on a Mirror or Packet Broker input

2020-05-28T08:41:07Z

Klaus:

File:Burst mac measurement.png

2020-05-28T08:40:46Z

Klaus:

File:Burst link measurement.png

2020-05-28T08:32:13Z

Klaus:

Main Page

2020-05-28T08:26:57Z

Klaus: /* Use Cases */

__NOTOC__
{|
|[[Image:Combination mark transparent.png|300px|link=https://www.allegro-packets.com]]      
|'''This is the Allegro Packets Documentation Wiki. Please visit the website of [https://allegro-packets.com Allegro Packets] for more information.'''
|}
{| class="wikitable" style="color:black; background-color:#fcfcfc; width: 100%;"
|- style="vertical-align:top;"
| style="width: 33%" |
=== Installation ===
* [[Generic Allegro Network Multimeter installation]]
* Additional installation notes for specific devices:
** [[Allegro 200 series]]
* [[Management interface settings|Configure Management IP address]]
* [[IPMI KVM on Allegro series 1000+]]
* [[User Management|Multi users and permissions]]
* [[Firmware update]]
* [[Performing a factory reset or configuration reset]]
| style="width: 33%" |

=== Typical Installation Setups ===
* [[In-Line Installation|In-Line Installation Guide]]
* [[Mirror Port, TAP and Packet Broker Installation|Mirror Port, TAP and Packet Broker Installation Guide]]
* [[ERSPAN Installation|ERSPAN Installation Guide]]
* [[VMWare Workstation Player/Pro Installation Guide]]
* [[VMWare ESXI Installation Guide]]

| style="width: 33%" |

=== Configuration Guides ===
* [[Setup storage devices for capturing and ring buffer]]
* [[Ring Buffer Configuration Guide]] ( Single Disk, Multiple Cluster,... )
* [[Parallel packet processing|Parallel Packet Processing Configuration Guide]]
* [[Virtual Link Group Configuration Guide]]
* [[Multi-device settings|Multi-Allegro Configuration]]

* [[Performance Optimization Guide]]

|- style="vertical-align:top;"
|

=== Web Interface Manual ===
* [[Introduction]]
* [[Quickstart]]
* [[Usage]]
* [[Measurement modules]]
* [[System Info Page]]
* [[Settings]]
* [[FAQ|FAQ - Frequently Asked Questions]]
* [[Error descriptions]]
* [[Feature documentation]]
|

=== Use Cases ===
* [[Investigate Network Load ]]
* [[Forensic pcap Analysis ]]
* [[Find Profinet problems]]
* [[Network Burst Analysis]]
* [[Burst analysis on a Mirror or Packet Broker input]]
* [[Capturing]]
* [[Investigating network problems on remote sites]]
* [[Debugging Skype Traffic]]
|

=== Data export and third-party tools ===
* [[REST API description]]
* [[Statistics Export via POST]]
* [[SNMP]]
* [[NetFlow/IPFIX_interface]]

|- style="vertical-align:top;"
|

=== Remote access ===

* [[Using the Allegro Remote Service]]
* [[Self-hosted SSH proxy]]
|
=== Settings ===

* [[ Global settings]]
* [[ Module settings]]
* [[ Incident settings]]
* [[ User defined names]]
* [[ Management interface settings]]
* [[ Multi-device settings]]
* [[ Administration]]
* [[ Filter]]
* [[ Remote access and export]]
* [[ User Management]]
* [[ Firmware update]]
* [[ License upload]]

|

=== Getting support ===

* [[Reaching Allegro Support]]
* [[Reporting bugs]]

|- style="vertical-align:top;"
|
=== Support of third-party hardware ===

* [[List of Supported Transceiver Modules]]
* [[Supported storage devices for x300/x500 series]]
|}

List of Supported Transceiver Modules

2020-05-26T09:12:50Z

Klaus: /* List of tested third-party modules */

== DISCLAIMER ==

Allegro Packets allows you to use third-party vendor modules in its appliances but guarantees only warranty and support for transceiver modules sold by Allegro Packets. Any malfunction or configuration issue with third-party modules are NOT covered by the warranty.

Allegro Packets does not restrict the use of third-party SFP+ modules for the devices. However, some hardware limitations apply which are described as follows:

== Built-in ports vs. expansion cards ==

The Allegro Network Multimeter 1000/1200/3000/3200 series have two on-board SFP+ ports which are restricted to original or branded '''Intel modules'''.

All non built-in ports are '''not''' vendor locked and can accept all transceiver modules. However, there are modules that do not work because of specific vendor extensions within the modules. This applies for all ports of the Allegro Network Multimeter x300 and x500 series and all expansion cards for the Allegro Network Multimeter 1000/1200/3000/3200.

The following table shows which kind of modules are supported by Allegro by
port type:

{| class="wikitable sortable"
|-
! Port type !!original or branded Intel modules !! non-Intel branded modules
|-
| built-in SFP+ ports || x || -
|-
| SFP+ expansion|| x || x
|-
| SFP28 expansion|| x || x
|-
| QSFP expansion|| x|| x
|-
| QSFP28 expansion|| x || x
|-
|}

The use of Intel branded modules is mandatory for the built-in SFP+ ports. These
restrictions do not apply to the additional network expansion cards
(2 port and 4 port SFP+, high precision GPS card, etc.) that are available for
the Allegro Network Multimeter 1000 and 3000 series. These ports accept
generic modules from a wide range of vendors.

Since auto-negotiation is often not available on 1G/10G SFP+ interfaces, it
may be necessary to manually set the correct speed in the `Interface Stats`
section of the user interface.

QSFP+ breakout cables are NOT supported.

== List of tested third-party modules ==

The following list of modules have been either tested by Allegro or customers and have been reported to operate. Please be aware that this can change due new module revisions.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| SFP+ || Intel E10GSFPSR || Fiber (SR) || supports 1G and 10G operation
|-
| SFP+ || Intel E10GSFPLR || Fiber (LR) || supports 1G and 10G operation
|-
| SFP+ || Intel XDACBL1M, XDACBL3M or XDACBL5M|| DA(Copper, Passive) ||
|-
| SFP+ || Flexoptix P.8596.02 || Fiber (SR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || Flexoptix P.1396.10 || Fiber (LR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || fs.com 36431 || Fiber (SR) || requires Intel branding, supports only 10G operation, 1G does NOT work
|-
| SFP28 || Flexoptix P.8525G.01 || Fiber (SR) || recommended with Intel branding
|-
| SFP28 || Flexoptix P.1325G.10 || Fiber (LR) || recommended with Intel branding
|-
| QSFP+ || Flexoptix Q.8540G.02 || Fiber (SR4) || recommended with Intel branding
|-
| QSFP+ || Flexoptix Q.1640G.10 || Fiber (LR4) || recommended with Intel branding
|-
| QSFP+ || FINISAR FTL4C1QE1C || Fiber (LR4) ||
|-
| QSFP+ || FINISAR FTL410QD2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE1C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE3C || Fiber (SR4) ||
|-
| QSFP+ || Amphenol 603020002, 603020005 || DA(Copper, Passive) ||
|-
| QSFP+ 40G SR BG || Cisco qsfp-40g-sr-bg P/N: 191402 || Fiber (SR4) || modules must be (re-) inserted after power up
|-
| QSFP+ 40G SR4 || Cisco qsfp-40g-sr4 P/N: 186602 || Fiber (SR4) || modules must be (re-) inserted after power up
|-
| QSFP+ 40G AOC || Cisco qsfp-h40g-aoc10m P/N: 187627 || Fiber (SR) || modules must be (re-) inserted after power up
|-
| QSFP28 || Flexoptix Q.851HG.02 || Fiber (SR4) ||
|-
| QSFP28 || fs.com 75308 || Fiber (SR4) ||
|}

== Non-working modules ==

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| QFSP+ 40/100 SRBD || Cisco qsfp-40/100-srbd P/N: 199804 || Fiber (SR) || non-standard module, does '''NOT''' work
|}

List of Supported Transceiver Modules

2020-05-25T06:42:43Z

Klaus: /* List of tested third-party modules */

== DISCLAIMER ==

Allegro Packets allows you to use third-party vendor modules in its appliances but guarantees only warranty and support for transceiver modules sold by Allegro Packets. Any malfunction or configuration issue with third-party modules are NOT covered by the warranty.

Allegro Packets does not restrict the use of third-party SFP+ modules for the devices. However, some hardware limitations apply which are described as follows:

== Built-in ports vs. expansion cards ==

The Allegro Network Multimeter 1000/1200/3000/3200 series have two on-board SFP+ ports which are restricted to original or branded '''Intel modules'''.

All non built-in ports are '''not''' vendor locked and can accept all transceiver modules. However, there are modules that do not work because of specific vendor extensions within the modules. This applies for all ports of the Allegro Network Multimeter x300 and x500 series and all expansion cards for the Allegro Network Multimeter 1000/1200/3000/3200.

The following table shows which kind of modules are supported by Allegro by
port type:

{| class="wikitable sortable"
|-
! Port type !!original or branded Intel modules !! non-Intel branded modules
|-
| built-in SFP+ ports || x || -
|-
| SFP+ expansion|| x || x
|-
| SFP28 expansion|| x || x
|-
| QSFP expansion|| x|| x
|-
| QSFP28 expansion|| x || x
|-
|}

The use of Intel branded modules is mandatory for the built-in SFP+ ports. These
restrictions do not apply to the additional network expansion cards
(2 port and 4 port SFP+, high precision GPS card, etc.) that are available for
the Allegro Network Multimeter 1000 and 3000 series. These ports accept
generic modules from a wide range of vendors.

Since auto-negotiation is often not available on 1G/10G SFP+ interfaces, it
may be necessary to manually set the correct speed in the `Interface Stats`
section of the user interface.

QSFP+ breakout cables are NOT supported.

== List of tested third-party modules ==

The following list of modules have been either tested by Allegro or customers and have been reported to operate. Please be aware that this can change due new module revisions.

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| SFP+ || Intel E10GSFPSR || Fiber (SR) || supports 1G and 10G operation
|-
| SFP+ || Intel E10GSFPLR || Fiber (LR) || supports 1G and 10G operation
|-
| SFP+ || Intel XDACBL1M, XDACBL3M or XDACBL5M|| DA(Copper, Passive) ||
|-
| SFP+ || Flexoptix P.8596.02 || Fiber (SR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP+ || Flexoptix P.1396.10 || Fiber (LR) || requires Intel branding, supports 1G and 10G operation
|-
| SFP28 || Flexoptix P.8525G.01 || Fiber (SR) || recommended with Intel branding
|-
| SFP28 || Flexoptix P.1325G.10 || Fiber (LR) || recommended with Intel branding
|-
| QSFP+ || Flexoptix Q.8540G.02 || Fiber (SR4) || recommended with Intel branding
|-
| QSFP+ || Flexoptix Q.1640G.10 || Fiber (LR4) || recommended with Intel branding
|-
| QSFP+ || FINISAR FTL4C1QE1C || Fiber (LR4) ||
|-
| QSFP+ || FINISAR FTL410QD2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE1C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE2C || Fiber (SR4) ||
|-
| QSFP+ || FINISAR FTL410QE3C || Fiber (SR4) ||
|-
| QSFP+ || Amphenol 603020002, 603020005 || DA(Copper, Passive) ||
|-
| QSFP+ 40G SR BG || Cisco qsfp-40g-sr-bg P/N: 191402 || Fiber (SR4) || modules must be (re-) inserted after power up
|-
| QSFP+ 40G SR4 || Cisco qsfp-40g-sr4 P/N: 186602 || Fiber (SR4) || modules must be (re-) inserted after power up
|-
| QSFP+ 40G AOC || Cisco qsfp-h40g-aoc10m P/N: 187627 || Fiber (SR) || modules must be (re-) inserted after power up
|}

== Non-working modules ==

{| class="wikitable"
|-
! Optics/Copper Module !! Transceiver P/N !! Media Type !! Remarks
|-
| QFSP+ 40/100 SRBD || Cisco qsfp-40/100-srbd P/N: 199804 || Fiber (SR) || non-standard module, does '''NOT''' work
|}

Burst analysis on a Mirror or Packet Broker input

2020-05-20T12:30:09Z

Klaus: Created page with "<accesscontrol>AC:GroupXZY</accesscontrol> == About =="

<accesscontrol>AC:GroupXZY</accesscontrol>

== About ==

Main Page

2020-05-20T12:27:14Z

Klaus: /* Use Cases */

__NOTOC__
{|
|[[Image:Combination mark transparent.png|300px|link=https://www.allegro-packets.com]]      
|'''This is the Allegro Packets Documentation Wiki. Please visit the website of [https://allegro-packets.com Allegro Packets] for more information.'''
|}
{| class="wikitable" style="color:black; background-color:#fcfcfc; width: 100%;"
|- style="vertical-align:top;"
| style="width: 33%" |
=== Installation ===
* [[Generic Allegro Network Multimeter installation]]
* Additional installation notes for specific devices:
** [[Allegro 200 series]]
* [[Management interface settings|Configure Management IP address]]
* [[IPMI KVM on Allegro series 1000+]]
* [[User Management|Multi users and permissions]]
* [[Firmware update]]
* [[Performing a factory reset or configuration reset]]
| style="width: 33%" |

=== Typical Installation Setups ===
* [[In-Line Installation|In-Line Installation Guide]]
* [[Mirror Port, TAP and Packet Broker Installation|Mirror Port, TAP and Packet Broker Installation Guide]]
* [[ERSPAN Installation|ERSPAN Installation Guide]]
* [[VMWare Workstation Player/Pro Installation Guide]]
* [[VMWare ESXI Installation Guide]]

| style="width: 33%" |

=== Configuration Guides ===
* [[Setup storage devices for capturing and ring buffer]]
* [[Ring Buffer Configuration Guide]] ( Single Disk, Multiple Cluster,... )
* [[Parallel packet processing|Parallel Packet Processing Configuration Guide]]
* [[Virtual Link Group Configuration Guide]]
* [[Multi-device settings|Multi-Allegro Configuration]]

* [[Performance Optimization Guide]]

|- style="vertical-align:top;"
|

=== Web Interface Manual ===
* [[Introduction]]
* [[Quickstart]]
* [[Usage]]
* [[Measurement modules]]
* [[System Info Page]]
* [[Settings]]
* [[FAQ|FAQ - Frequently Asked Questions]]
* [[Error descriptions]]
* [[Feature documentation]]
|

=== Use Cases ===
* [[Investigate Network Load ]]
* [[Forensic pcap Analysis ]]
* [[Find Profinet problems]]
* [[Network burst analysis]]
* [[Burst analysis on a Mirror or Packet Broker input]]
* [[Capturing]]
* [[Investigating network problems on remote sites]]
* [[Debugging Skype Traffic]]
|

=== Data export and third-party tools ===
* [[REST API description]]
* [[Statistics Export via POST]]
* [[SNMP]]
* [[NetFlow/IPFIX_interface]]

|- style="vertical-align:top;"
|

=== Remote access ===

* [[Using the Allegro Remote Service]]
* [[Self-hosted SSH proxy]]
|
=== Settings ===

* [[ Global settings]]
* [[ Module settings]]
* [[ Incident settings]]
* [[ User defined names]]
* [[ Management interface settings]]
* [[ Multi-device settings]]
* [[ Administration]]
* [[ Filter]]
* [[ Remote access and export]]
* [[ User Management]]
* [[ Firmware update]]
* [[ License upload]]

|

=== Getting support ===

* [[Reaching Allegro Support]]
* [[Reporting bugs]]

|- style="vertical-align:top;"
|
=== Support of third-party hardware ===

* [[List of Supported Transceiver Modules]]
* [[Supported storage devices for x300/x500 series]]
|}

Main Page

2020-05-20T12:22:49Z

Klaus: /* Use Cases */

__NOTOC__
{|
|[[Image:Combination mark transparent.png|300px|link=https://www.allegro-packets.com]]      
|'''This is the Allegro Packets Documentation Wiki. Please visit the website of [https://allegro-packets.com Allegro Packets] for more information.'''
|}
{| class="wikitable" style="color:black; background-color:#fcfcfc; width: 100%;"
|- style="vertical-align:top;"
| style="width: 33%" |
=== Installation ===
* [[Generic Allegro Network Multimeter installation]]
* Additional installation notes for specific devices:
** [[Allegro 200 series]]
* [[Management interface settings|Configure Management IP address]]
* [[IPMI KVM on Allegro series 1000+]]
* [[User Management|Multi users and permissions]]
* [[Firmware update]]
* [[Performing a factory reset or configuration reset]]
| style="width: 33%" |

=== Typical Installation Setups ===
* [[In-Line Installation|In-Line Installation Guide]]
* [[Mirror Port, TAP and Packet Broker Installation|Mirror Port, TAP and Packet Broker Installation Guide]]
* [[ERSPAN Installation|ERSPAN Installation Guide]]
* [[VMWare Workstation Player/Pro Installation Guide]]
* [[VMWare ESXI Installation Guide]]

| style="width: 33%" |

=== Configuration Guides ===
* [[Setup storage devices for capturing and ring buffer]]
* [[Ring Buffer Configuration Guide]] ( Single Disk, Multiple Cluster,... )
* [[Parallel packet processing|Parallel Packet Processing Configuration Guide]]
* [[Virtual Link Group Configuration Guide]]
* [[Multi-device settings|Multi-Allegro Configuration]]

* [[Performance Optimization Guide]]

|- style="vertical-align:top;"
|

=== Web Interface Manual ===
* [[Introduction]]
* [[Quickstart]]
* [[Usage]]
* [[Measurement modules]]
* [[System Info Page]]
* [[Settings]]
* [[FAQ|FAQ - Frequently Asked Questions]]
* [[Error descriptions]]
* [[Feature documentation]]
|

=== Use Cases ===
* [[Investigate Network Load ]]
* [[Forensic pcap Analysis ]]
* [[Find Profinet problems]]
* [[Network burst analysis]]
* [[Capturing]]
* [[Investigating network problems on remote sites]]
* [[Debugging Skype Traffic]]
|

=== Data export and third-party tools ===
* [[REST API description]]
* [[Statistics Export via POST]]
* [[SNMP]]
* [[NetFlow/IPFIX_interface]]

|- style="vertical-align:top;"
|

=== Remote access ===

* [[Using the Allegro Remote Service]]
* [[Self-hosted SSH proxy]]
|
=== Settings ===

* [[ Global settings]]
* [[ Module settings]]
* [[ Incident settings]]
* [[ User defined names]]
* [[ Management interface settings]]
* [[ Multi-device settings]]
* [[ Administration]]
* [[ Filter]]
* [[ Remote access and export]]
* [[ User Management]]
* [[ Firmware update]]
* [[ License upload]]

|

=== Getting support ===

* [[Reaching Allegro Support]]
* [[Reporting bugs]]

|- style="vertical-align:top;"
|
=== Support of third-party hardware ===

* [[List of Supported Transceiver Modules]]
* [[Supported storage devices for x300/x500 series]]
|}

Performance Optimization Guide

2020-05-13T11:42:26Z

Klaus:

== About ==

This guide is about performance optimization of the '''Allegro Network Multimeter''' for specific use cases. By default, the device runs in a configuration that fits for the majority of users and you do not need to change any parameter of the configuration. Depending on the actual network traffic and measurement setup, it can be beneficial to adjust some performance-related parameters to achieve better overall performance.

== High level Allegro system layout ==

The '''Allegro Network Multimeter''' has various components that process traffic. These components are:

* I/O threads: responsible for all I/O operations between the network interface cards and the CPUs.
* Analyzer threads: responsible for decoding network traffic and most of the database operations for the statistical values.
* DB threads: optional threads which offload memory intensive database operations, see [[DB mode]].

The '''Allegro Network Multimeter''' uses queues to buffer packets and messages between the hardware instances (interfaces chips, central processing unit, storage) and threads. All threads measure their load individually which can be monitored at '''Info''' → '''System info''' → '''Load'''.

The utilization of the following queues can be monitored to see if and where changes to queue settings are helpful:

== Interface hardware queues ==

The interface hardware queue is between the network interfaces and the I/O threads of the central processing unit. Whenever the I/O threads are too slow to consume all packets from the built-in or extension network interfaces, the '''hardware miss''' counter of the [[Interface statistics]] will increase over time.

The load of the I/O threads can be checked at the '''Info''' → '''System info''' → '''Load'''.

TODO: add overloaded Interface graph.

If the load is near 100%, packet loss can occur and the following countermeasures can be attempted:

# The Bridge mode requires approximately 10% - 30% more load on the I/O threads than the Sink mode. The I/O threads have to sent the incoming traffic to the corresponding outgoing network interface for forwarding. If packet forwarding is not necessary (for example when being deployed at a Mirror Port), switching to '''Sink mode''' will improve the performance of the device. For configuration, please see [[Global_settings#Packet_processing_mode|Global settings]].
# The number of queues can be adjusted at the cost of analyzer threads. Each queue uses a corresponding CPU thread so more queues means less CPU threads available for other components. This option is available on the Allegro 3000 and above due to the large number of internal CPU cores. Allegro Packets recommends to increase the number of queues only on the Allegro 3000 and above if necessary.
:: This setting can be changed at '''Settings''' -> '''Global settings''' → '''Expert settings'''
:: [[File:Rx sockets io thread.png|600px]]
:: Allegro Packets recommends to test with HT enabled and 2 or 4 queue for I/O. If you see a high load on the analyzers, you can also test with 4 queues (I/O threads) without HT for maximum performance.

== Analyzer queues ==

The '''Allegro Network Multimeter''' has a packet queue between I/O threads and the analyzer threads which distributes the incoming packets to the actual processing threads. There are two statistics describing the load of the queues and analyzer threads. If analyzer threads cannot process incoming packets quickly enough, the corresponding queue will eventually overflow and packets must be skipped for processing.

<ol>
<li>Graphs for skipped packets: You can check at the '''Interface stats''' per interface and check whether all I/O threads were able to push all packets to the analyzer queues or not. The corresponding counter is '''Not processed due to overload'''. 
[[File:Interface analyzer packet drop.png|400px]] 
Note that high counters for a few seconds at the initial startup of the device are normal when it is started under high network load scenarios.
</li>
<li>Utilization of individual analyzer threads: The load of the analyzer threads can be checked at the '''Info''' → '''System info''' → '''Load'''. Depending on the Allegro model, there can be two (Allegro 200, Allegro 500) or up to 120 (Allegro 5300 or 5500) analyzer threads.
The load graph gives an indication about the overall utilization of each thread but the important counter is the '''Not processed due to overload''' counter since this is the event when ultimately one or more packets could not be processed due to overload.
</li>
</ol>

There are 3 scenarios where the a queue overload can occur which are described in the following sections:

=== Skipped packets at high analyzer load ===

The '''Allegro Network Multimeter''' has reached its processing limit for current traffic when the load of one or multiple analyzers reaches 100%.

There are a some options to reduce the analyzer load but it always comes with the penalty of no longer seeing the entire measurement data. You can '''disable''' some features or add a '''NIC filter''' to process only parts of the traffic.

<ol>
<li>You can reduce the level of analysis at '''Settings''' -> '''Global settings'''. 
[[File:Detail of traffic analysis.png|600px]] 
Every level reduction will reduce the amount of analyzed data and saved database operations, see [[Global_settings#Limit_module_processing]] for more details of this option. It is possible to adjust the setting so that live traffic is stored as fast possible to the ring buffer without further analysis and re-analyze parts of the recorded traffic with full analysis by using [[Parallel packet processing]].</li>
<li>The NIC filter can be used to reduce the amount of monitored traffic. It excludes traffic from the analyzers for the cost of not seeing all traffic of the link. See the [[Filter|interface filter]] for more details.</li>
</ol>

If none of these options are applicable, you need to upgrade the '''Allegro Network Multimeter''' to a larger model with more performance (Allegro 1000 to 3000 or 3000 to 5000).

=== Skipped packets at low analyzer load ===

The '''Allegro Network Multimeter''' conserves energy in very low traffic situations. Large packet bursts can lead to a high traffic situation so the analyser threads cannot keep up with the incoming packets fast enough during the period of power adjustment. After that small period of time, the analyzer threads are again fast enough to process the traffic.

This can be identified if packets are not processed while the system load is still not very high at the same time.

If this occurs, the option '''Analyzer queue overcommit''' at '''Settings''' → '''Global settings''' → '''Expert settings''' can be enabled. This option can only be used in '''Sink mode''' and it increases the queue size to be able to buffer network burts during a short time period. The disadvantage is that the queues are overcommitted so it can happen that the network card does not have enough buffers available for incoming packets.

[[File:Queue overcommit.png|600px]]

=== Skipped packets due to analyzer load imbalance ===

By default, the Allegro load balances the traffic between the analyzers based on the IP addresses of the client and server. This provides a good balancing in most situations.

Network packets cannot distributed equally among all analyzer threads if there are many connections between only few IP addresses. An example is 2 SIP trunks with many RTP connections.

The load statistics will show parts of the analyzers with a constant high load and others with a significantly lower load.

The load balancing behavior of the '''Allegro Network Multimeter''' can be changed to flow-based load balancing mode at '''Settings''' -> '''Global settings''' → '''Expert settings'''.

[[File:Flow load balancing.png|600px]]

This mode improves the performance only for imbalanced traffic. Use the option only if required since it has a negative performance impact on balanced traffic.

== Database queues ==

The database mode is an extension for large Allegro models with multiple CPU sockets and it is disabled by default. This mode is only recommended for Allegro 3500 rev1 and Allegro 5500 rev1. The database mode helps to improve the performance for very high database loads. This could happen for millions of open and new connections in combination with NUMA bottlenecks. See [[DB mode]] for more details.

If enabled, you can check if there are message drops between the analyzer threads and the DB threads in the load statistics.

The ratio of DB threads vs analyzer threads can be adjusted so that ideally all threads have similar load.

The advantage of the DB mode is that additional message queues are used which can buffer much more information and therefore reduce the load on the analyzer threads. This will reduce the likelihood of skipped packets.

== Disk I/O queues ==

The analyzer threads have to use additional queues for capturing packets to each disk or each disk cluster. Storage devices like HDDs and SSDs do not offer a constant write rate and have sudden write slowdowns. Please read the performance guide for the ring buffer [[Ring_Buffer_Configuration_Guide#Performance]] on how to adjust the options for high capturing performance.

The two generic solutions are to increase the buffer and to use filter rules. Both will reduce the number of bytes that are written to the disk.

REST API description

2020-05-13T06:46:21Z

Klaus:

{| class="wikitable" style="text-align: center; color: red;"
| Warning: This text is under construction
|}

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).

Here an example of the structured JSON data for the IP overview. This data has been extracted with the Google Chrome developer console while accessing the IP statsistics page.

[[File:Rest api chrome console.png|800px]]

=== 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 [https://en.wikipedia.org/wiki/CURL]. 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 )

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

Please note that you might need to use <code>curl.exe</code> 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''' [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-restmethod].
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:

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

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

<code>-ContentType'application/json; charset=utf-8'</code>

To disable the certificate check, use:

<code>-SkipCertificateCheck</code>

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

<code>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</code>

=== jq ===

jq ( [https://stedolan.github.io/jq/] ) is a powerful tool to extract parameters from a json document. If called without parameters, jq formats the JSON output into a readable format with indenting and new lines. It also allows to select specific values and do basic operations like addition with this values.
Please read the jq documentation for more information.

== API hierarchy ==

=== Query available URIs with OPTIONS ===

The Allegro REST API has the fixed URI <code>API/stats</code> for statistics. To see all possible subtrees of a specific request, use the '''OPTIONS''' request instead of '''GET'''. It can be set with the parameter <code>-X OPTIONS</code> for curl.

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats' -X OPTIONS
{
"subResources": [
"modules",
"reports",
"incidentReporting",
"time",
"ringBufferReplay",
"pcap",
"reset",
"interfacesError",
"interfaces",
"load",
"processing"
]
}
</pre>

This allows you to query for example for all modules that are available for a specific release of the Allegro:

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules' -X OPTIONS
{
"subResources": [
"pppoe",
"lldp",
"groups",
"mpls",
"opc_ua",
"quality",
"ipsec",
"profinet",
"multicast",
"burst_analysis",
"global_incidents",
"ptp",
"ntp",
"icmp",
"stp",
"sip",
"smb",
"dpa",
"l4_ports",
"netbios",
"crt",
"dpi",
"http",
"ssl",
"dns",
"dhcp",
"location",
"qos",
"ip",
"mac_protocols",
"vlan",
"arp",
"packet_size",
"mac",
"capture"
]
}
</pre>

=== URI content parameters ===

Some modules allow to use a parameter as part of the URI like the IP or Mac address. The path <code>API/stats/modules/ip/ips</code> allows you to use an IP address as next uri element

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips' -X OPTIONS
{
"subResources": [
"protocol",
":ip"
]
}
</pre>

The path of an IP address shows all further available elements:

<pre>
$ curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.0.54.254' -X OPTIONS
{
"subResources": [
"sip_request_responses",
"peers_ports",
"sip_responses",
"sip_requests",
"qos",
"ports",
"connections",
"protocols",
"macs",
"peers",
"tcpStats"
]
}
</pre>

== JSON output traffic counters ==

All counters are aggregated counters, either for the selected time interval or since the processing start of the Allegro. Many traffic counters have 4 separate values. These traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows:
* line 1: '''received packets''', extraction example: jq .lastSecond[0]
* line 2: '''received bytes''', extraction example: jq .lastSecond[1]
* line 3: '''transmitted packets''', extraction example: jq .lastSecond[2]
* line 4: '''transmitted bytes''', extraction example: jq .lastSecond[3]
* additional lines are module specific

The following counters exist for many REST APIs like IP, MAC, l4 protocol, l7 protocol and many more:
* '''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.

Please note that all counters are byte counters, not bit counters. You need to multiply the counters by 8 to get the bitrate.

This example extracts the received bytes of the last second of a specific IP.

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

This example extracts received and transmitted bytes of the last second of a specific IP.

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

== API parameters ==

The Allegro REST API has a number of query parameters that can be added to modify the request. By default, the API will display the real time counters since the last restart of the processing unit.

This example extracts the amount of received and transmitted bytes for an IP address since the processing start of the Allegro. It queries via the REST API the JSON and then adds the values second value ( row 1, rx bytes ) and 4th value ( row 3, tx bytes ) of the interval counters together.

<pre>
$ curl --silent -k -u USER:PASSWORD "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254" | jq '.interval[1] + .interval[3]'
</pre>

=== Time interval selection ===

Requests can be given a time interval. If present, the '''interval''' counters are adjusted to this 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). You can use <code>date +%s</code> on your machine to adjust to the best interval. Please consult the man page of date for more parameters.
* '''skiphistorydata''': shall the JSON include the history data without datasets, this reduces the amount of transferred bytes if datasets are required to render a graph, can be false/true default: false
* '''timespan''': required resolution for the graph dataset

This example extracts the amount of received and transmitted bytes for an IP address for the last 24 hours.
<pre>
$ curl --silent -k -u USER:PASSWORD "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?starttime=$(date --date="1 day ago" +%s)&endtime=$(date +%s)&skiphistorydata=true" | jq '.interval[1] + .interval[3]'
</pre>

=== 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).

This example shows IP address with the highest amount of traffic

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

This exampe shows up to 9999 peers of a specific IP address:

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/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'</code>

=== Pcap extraction ===

The Allegro Network Multimeter allows to extract the raw packets with the REST API with the special capture URI <code>/API/data/modules/capture</code>

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

The available parameters are:

* '''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. If not specified, the current time will be used.
* '''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). If not specified, unlimited will be used.
* expression: The filter expression. There are no whitespaces allowed. You may use ‘%20’ instead. See [[Capture module]] for available expressions.
* 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).

Example to capture everything from now on:

<code>curl -k -u USER:PASSWORD 'https://allegro-mm/API/data/modules/capture' > path_to/capture.pcap</code>

Example to capture a specific IP of the last hour

<code>curl -k -u USER:PASSWORD "https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3&starttime=$(date --date="1 hour ago" +%s)&endtime=$(date +%s)&fromCaptureBuffer=true" > path_to/capture.pcap</code>

=== Virtual Link Groups ===

The Allegro REST API allows to access all link groups by the parameter '''group'''. The group index starts at zero, which is the default value. If a virtual link group is enabled.

This example extracts the traffic of the IP 10.54.0.254 from the second virtual link group ( index 1 ).

<pre>
$ curl --silent -k -u USER:PASSWORD "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?group=1" | jq '.interval[1] + .interval[3]'
</pre>

=== Parallel pcap analysis ===

The Allegro can process in parallel offline traffic like a pcap file or a ring buffer. In case a parallel PCAP analysis is running, the API call must be given the additional header field <code>"X-AllegroPackets-Multimeter-ID: :1"</code> with the PCAP instance ID.

This allows to extract information of automated pcap uploads.

=== Multi-device analysis ===

If the Allegro is configured as a gateway for multiple Allegro devices by the [[Multi-device settings]], you need to add the additional header field <code>"X-AllegroPackets-Multimeter-ID: hostname"</code> where the hostname must be the same as configured in the multi-device settings.

== REST API Examples ==

==== MAC statistics ====

Extract the packets per second statistic of the MAC broadcast address

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/mac/macs/ff:ff:ff:ff:ff:ff'</code>

==== IP statistics ====

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.1.2.3'</code>

==== Pretty displaying JSON output with jq ====

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

==== Capture a specific IP ====

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

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

<code>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</code>

Performance Optimization Guide

2020-05-13T06:36:32Z

Klaus: /* Database queues */

<accesscontrol>AC:GroupUsers</accesscontrol>

== About ==

This guide is about performance optimization of the '''Allegro Network Multimeter''' for specific use cases. By default, the device runs in a configuration that fits for the majority of users and you do not need to change any parameter of the configuration. Depending on the actual network traffic and measurement setup, it can be beneficial to adjust some performance-related parameters to achieve better overall performance.

== High level Allegro system layout ==

The '''Allegro Network Multimeter''' has various components that process traffic. These components are:

* I/O threads: responsible for all I/O operations between the network interface cards and the CPUs.
* Analyzer threads: responsible for decoding network traffic and most of the database operations for the statistical values.
* DB threads: optional threads which offload memory intensive database operations, see [[DB mode]].

The '''Allegro Network Multimeter''' uses queues to buffer packets and messages between the hardware instances (interfaces chips, central processing unit, storage) and threads. All threads measure their load individually which can be monitored at '''Info''' → '''System info''' → '''Load'''.

The utilization of the following queues can be monitored to see if and where changes to queue settings are helpful:

== Interface hardware queues ==

The interface hardware queue is between the network interfaces and the I/O threads of the central processing unit. Whenever the I/O threads are too slow to consume all packets from the built-in or extension network interfaces, the '''hardware miss''' counter of the [[Interface statistics]] will increase over time.

The load of the I/O threads can be checked at the '''Info''' → '''System info''' → '''Load'''.

TODO: add overloaded Interface graph.

If the load is near 100%, packet loss can occur and the following countermeasures can be attempted:

# The Bridge mode requires approximately 10% - 30% more load on the I/O threads than the Sink mode. The I/O threads have to sent the incoming traffic to the corresponding outgoing network interface for forwarding. If packet forwarding is not necessary (for example when being deployed at a Mirror Port), switching to '''Sink mode''' will improve the performance of the device. For configuration, please see [[Global_settings#Packet_processing_mode|Global settings]].
# The number of queues can be adjusted at the cost of analyzer threads. Each queue uses a corresponding CPU thread so more queues means less CPU threads available for other components. This option is available on the Allegro 3000 and above due to the large number of internal CPU cores. Allegro Packets recommends to increase the number of queues only on the Allegro 3000 and above if necessary.
:: This setting can be changed at '''Settings''' -> '''Global settings''' → '''Expert settings'''
:: [[File:Rx sockets io thread.png|600px]]
:: Allegro Packets recommends to test with HT enabled and 2 or 4 queue for I/O. If you see a high load on the analyzers, you can also test with 4 queues (I/O threads) without HT for maximum performance.

== Analyzer queues ==

The '''Allegro Network Multimeter''' has a packet queue between I/O threads and the analyzer threads which distributes the incoming packets to the actual processing threads. There are two statistics describing the load of the queues and analyzer threads. If analyzer threads cannot process incoming packets quickly enough, the corresponding queue will eventually overflow and packets must be skipped for processing.

<ol>
<li>Graphs for skipped packets: You can check at the '''Interface stats''' per interface and check whether all I/O threads were able to push all packets to the analyzer queues or not. The corresponding counter is '''Not processed due to overload'''. 
[[File:Interface analyzer packet drop.png|400px]] 
Note that high counters for a few seconds at the initial startup of the device are normal when it is started under high network load scenarios.
</li>
<li>Utilization of individual analyzer threads: The load of the analyzer threads can be checked at the '''Info''' → '''System info''' → '''Load'''. Depending on the Allegro model, there can be two (Allegro 200, Allegro 500) or up to 120 (Allegro 5300 or 5500) analyzer threads.
The load graph gives an indication about the overall utilization of each thread but the important counter is the '''Not processed due to overload''' counter since this is the event when ultimately one or more packets could not be processed due to overload.
</li>
</ol>

There are 3 scenarios where the a queue overload can occur which are described in the following sections:

=== Skipped packets at high analyzer load ===

The '''Allegro Network Multimeter''' has reached its processing limit for current traffic when the load of one or multiple analyzers reaches 100%.

There are a some options to reduce the analyzer load but it always comes with the penalty of no longer seeing the entire measurement data. You can '''disable''' some features or add a '''NIC filter''' to process only parts of the traffic.

<ol>
<li>You can reduce the level of analysis at '''Settings''' -> '''Global settings'''. 
[[File:Detail of traffic analysis.png|600px]] 
Every level reduction will reduce the amount of analyzed data and saved database operations, see [[Global_settings#Limit_module_processing]] for more details of this option. It is possible to adjust the setting so that live traffic is stored as fast possible to the ring buffer without further analysis and re-analyze parts of the recorded traffic with full analysis by using [[Parallel packet processing]].</li>
<li>The NIC filter can be used to reduce the amount of monitored traffic. It excludes traffic from the analyzers for the cost of not seeing all traffic of the link. See the [[Filter|interface filter]] for more details.</li>
</ol>

If none of these options are applicable, you need to upgrade the '''Allegro Network Multimeter''' to a larger model with more performance (Allegro 1000 to 3000 or 3000 to 5000).

=== Skipped packets at low analyzer load ===

The '''Allegro Network Multimeter''' conserves energy in very low traffic situations. Large packet bursts can lead to a high traffic situation so the analyser threads cannot keep up with the incoming packets fast enough during the period of power adjustment. After that small period of time, the analyzer threads are again fast enough to process the traffic.

This can be identified if packets are not processed while the system load is still not very high at the same time.

If this occurs, the option '''Analyzer queue overcommit''' at '''Settings''' → '''Global settings''' → '''Expert settings''' can be enabled. This option can only be used in '''Sink mode''' and it increases the queue size to be able to buffer network burts during a short time period. The disadvantage is that the queues are overcommitted so it can happen that the network card does not have enough buffers available for incoming packets.

[[File:Queue overcommit.png|600px]]

=== Skipped packets due to analyzer load imbalance ===

By default, the Allegro load balances the traffic between the analyzers based on the IP addresses of the client and server. This provides a good balancing in most situations.

Network packets cannot distributed equally among all analyzer threads if there are many connections between only few IP addresses. An example is 2 SIP trunks with many RTP connections.

The load statistics will show parts of the analyzers with a constant high load and others with a significantly lower load.

The load balancing behavior of the '''Allegro Network Multimeter''' can be changed to flow-based load balancing mode at '''Settings''' -> '''Global settings''' → '''Expert settings'''.

[[File:Flow load balancing.png|600px]]

This mode improves the performance only for imbalanced traffic. Use the option only if required since it has a negative performance impact on balanced traffic.

== Database queues ==

The database mode is an extension for large Allegro models with multiple CPU sockets and it is disabled by default. This mode is only recommended for Allegro 3500 rev1 and Allegro 5500 rev1. The database mode helps to improve the performance for very high database loads. This could happen for millions of open and new connections in combination with NUMA bottlenecks. See [[DB mode]] for more details.

If enabled, you can check if there are message drops between the analyzer threads and the DB threads in the load statistics.

The ratio of DB threads vs analyzer threads can be adjusted so that ideally all threads have similar load.

The advantage of the DB mode is that additional message queues are used which can buffer much more information and therefore reduce the load on the analyzer threads. This will reduce the likelihood of skipped packets.

== Disk I/O queues ==

The analyzer threads have to use additional queues for capturing packets to each disk or each disk cluster. Storage devices like HDDs and SSDs do not offer a constant write rate and have sudden write slowdowns. Please read the performance guide for the ring buffer [[Ring_Buffer_Configuration_Guide#Performance]] on how to adjust the options for high capturing performance.

The two generic solutions are to increase the buffer and to use filter rules. Both will reduce the number of bytes that are written to the disk.

REST API description

2020-05-12T14:04:30Z

Klaus: /* jquery ( jq ) */

{| class="wikitable" style="text-align: center; color: red;"
| Warning: This text is under construction
|}

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).

Here an example of the structured JSON data for the IP overview. This data has been extracted with the Google Chrome developer console while accessing the IP statsistics page.

[[File:Rest api chrome console.png|800px]]

=== 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 [https://en.wikipedia.org/wiki/CURL]. 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 )

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

Please note that you might need to use <code>curl.exe</code> 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''' [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-restmethod].
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:

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

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

<code>-ContentType'application/json; charset=utf-8'</code>

To disable the certificate check, use:

<code>-SkipCertificateCheck</code>

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

<code>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</code>

=== jq ===

jq ( [https://stedolan.github.io/jq/] ) is a powerful tool to extract parameters from a json document. If called without parameters, jq formats the JSON output into a readable format with indenting and new lines. It also allows to select specific values and do basic operations like addition with this values.
Please read the jq documentation for more information.

== API hierarchy ==

=== Query available URIs with OPTIONS ===

The Allegro REST API has the fixed URI <code>API/stats</code> for statistics. To see all possible subtrees of a specific request, use the '''OPTIONS''' request instead of '''GET'''. It can be set with the parameter <code>-X OPTIONS</code> for curl.

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats' -X OPTIONS
{
"subResources": [
"modules",
"reports",
"incidentReporting",
"time",
"ringBufferReplay",
"pcap",
"reset",
"interfacesError",
"interfaces",
"load",
"processing"
]
}
</pre>

This allows you to query for example for all modules that are available for a specific release of the Allegro:

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules' -X OPTIONS
{
"subResources": [
"pppoe",
"lldp",
"groups",
"mpls",
"opc_ua",
"quality",
"ipsec",
"profinet",
"multicast",
"burst_analysis",
"global_incidents",
"ptp",
"ntp",
"icmp",
"stp",
"sip",
"smb",
"dpa",
"l4_ports",
"netbios",
"crt",
"dpi",
"http",
"ssl",
"dns",
"dhcp",
"location",
"qos",
"ip",
"mac_protocols",
"vlan",
"arp",
"packet_size",
"mac",
"capture"
]
}
</pre>

=== URI content parameters ===

Some modules allow to use a parameter as part of the URI like the IP or Mac address. The path <code>API/stats/modules/ip/ips</code> allows you to use an IP address as next uri element

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules/ip/ips' -X OPTIONS
{
"subResources": [
"protocol",
":ip"
]
}
</pre>

The path of an IP address shows all further available elements:

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules/ip/ips/10.0.54.254' -X OPTIONS
{
"subResources": [
"sip_request_responses",
"peers_ports",
"sip_responses",
"sip_requests",
"qos",
"ports",
"connections",
"protocols",
"macs",
"peers",
"tcpStats"
]
}
</pre>

== JSON output traffic counters ==

All counters are aggregated counters, either for the selected time interval or since the processing start of the Allegro. Many traffic counters have 4 separate values. These traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows:
* line 1: '''received packets''', extraction example: jq .lastSecond[0]
* line 2: '''received bytes''', extraction example: jq .lastSecond[1]
* line 3: '''transmitted packets''', extraction example: jq .lastSecond[2]
* line 4: '''transmitted bytes''', extraction example: jq .lastSecond[3]
* additional lines are module specific

The following counters exist for many REST APIs like IP, MAC, l4 protocol, l7 protocol and many more:
* '''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.

Please note that all counters are byte counters, not bit counters. You need to multiply the counters by 8 to get the bitrate.

This example extracts the received bytes of the last second of a specific IP.

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

This example extracts received and transmitted bytes of the last second of a specific IP.

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

== API parameters ==

The Allegro REST API has a number of query parameters that can be added to modify the request. By default, the API will display the real time counters since the last restart of the processing unit.

This example extracts the amount of received and transmitted bytes for an IP address since the processing start of the Allegro. It queries via the REST API the JSON and then adds the values second value ( row 1, rx bytes ) and 4th value ( row 3, tx bytes ) of the interval counters together.

<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254" | jq '.interval[1] + .interval[3]'
</pre>

=== Time interval selection ===

Requests can be given a time interval. If present, the '''interval''' counters are adjusted to this 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). You can use <code>date +%s</code> on your machine to adjust to the best interval. Please consult the man page of date for more parameters.
* '''skiphistorydata''': shall the JSON include the history data without datasets, this reduces the amount of transferred bytes if datasets are required to render a graph, can be false/true default: false
* '''timespan''': required resolution for the graph dataset

This example extracts the amount of received and transmitted bytes for an IP address for the last 24 hours.
<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?starttime=$(date --date="1 day ago" +%s)&endtime=$(date +%s)&skiphistorydata=true" | jq '.interval[1] + .interval[3]'
</pre>

=== 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).

This example shows IP address with the highest amount of traffic

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

This exampe shows up to 9999 peers of a specific IP address:

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/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'</code>

=== Pcap extraction ===

The Allegro Network Multimeter allows to extract the raw packets with the REST API with the special capture URI <code>/API/data/modules/capture</code>

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

The available parameters are:

* '''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. If not specified, the current time will be used.
* '''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). If not specified, unlimited will be used.
* expression: The filter expression. There are no whitespaces allowed. You may use ‘%20’ instead. See [[Capture module]] for available expressions.
* 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).

Example to capture everything from now on:

<code>curl -k -u USER:PASSWORD 'https://allegro-mm/API/data/modules/capture' > path_to/capture.pcap</code>

Example to capture a specific IP of the last hour

<code>curl -k -u USER:PASSWORD "https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3&starttime=$(date --date="1 hour ago" +%s)&endtime=$(date +%s)&fromCaptureBuffer=true" > path_to/capture.pcap</code>

=== Virtual Link Groups ===

The Allegro REST API allows to access all link groups by the parameter '''group'''. The group index starts at zero, which is the default value. If a virtual link group is enabled.

This example extracts the traffic of the IP 10.54.0.254 from the second virtual link group ( index 1 ).

<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?group=1" | jq '.interval[1] + .interval[3]'
</pre>

=== Parallel pcap analysis ===

The Allegro can process in parallel offline traffic like a pcap file or a ring buffer. In case a parallel PCAP analysis is running, the API call must be given the additional header field <code>"X-AllegroPackets-Multimeter-ID: :1"</code> with the PCAP instance ID.

This allows to extract information of automated pcap uploads.

=== Multi-device analysis ===

If the Allegro is configured as a gateway for multiple Allegro devices by the [[Multi-device settings]], you need to add the additional header field <code>"X-AllegroPackets-Multimeter-ID: hostname"</code> where the hostname must be the same as configured in the multi-device settings.

== REST API Examples ==

==== MAC statistics ====

Extract the packets per second statistic of the MAC broadcast address

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/mac/macs/ff:ff:ff:ff:ff:ff'</code>

==== IP statistics ====

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.1.2.3'</code>

==== Pretty displaying JSON output with jq ====

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

==== Capture a specific IP ====

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

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

<code>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</code>

REST API description

2020-05-12T13:32:28Z

Klaus: /* REST API Examples */

{| class="wikitable" style="text-align: center; color: red;"
| Warning: This text is under construction
|}

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).

Here an example of the structured JSON data for the IP overview. This data has been extracted with the Google Chrome developer console while accessing the IP statsistics page.

[[File:Rest api chrome console.png|800px]]

=== 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 [https://en.wikipedia.org/wiki/CURL]. 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 )

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

Please note that you might need to use <code>curl.exe</code> 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''' [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-restmethod].
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:

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

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

<code>-ContentType'application/json; charset=utf-8'</code>

To disable the certificate check, use:

<code>-SkipCertificateCheck</code>

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

<code>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</code>

=== jquery ( jq ) ===

jquery ( [https://stedolan.github.io/jq/] ) is a powerful tool to extract parameters from a json document. If called without parameters, jq formats the JSON output into a readable format with indenting and new lines. It also allows to select specific values and do basic operations like addition with this values.
Please read the jq documentation for more information.

== API hierarchy ==

=== Query available URIs with OPTIONS ===

The Allegro REST API has the fixed URI <code>API/stats</code> for statistics. To see all possible subtrees of a specific request, use the '''OPTIONS''' request instead of '''GET'''. It can be set with the parameter <code>-X OPTIONS</code> for curl.

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats' -X OPTIONS
{
"subResources": [
"modules",
"reports",
"incidentReporting",
"time",
"ringBufferReplay",
"pcap",
"reset",
"interfacesError",
"interfaces",
"load",
"processing"
]
}
</pre>

This allows you to query for example for all modules that are available for a specific release of the Allegro:

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules' -X OPTIONS
{
"subResources": [
"pppoe",
"lldp",
"groups",
"mpls",
"opc_ua",
"quality",
"ipsec",
"profinet",
"multicast",
"burst_analysis",
"global_incidents",
"ptp",
"ntp",
"icmp",
"stp",
"sip",
"smb",
"dpa",
"l4_ports",
"netbios",
"crt",
"dpi",
"http",
"ssl",
"dns",
"dhcp",
"location",
"qos",
"ip",
"mac_protocols",
"vlan",
"arp",
"packet_size",
"mac",
"capture"
]
}
</pre>

=== URI content parameters ===

Some modules allow to use a parameter as part of the URI like the IP or Mac address. The path <code>API/stats/modules/ip/ips</code> allows you to use an IP address as next uri element

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules/ip/ips' -X OPTIONS
{
"subResources": [
"protocol",
":ip"
]
}
</pre>

The path of an IP address shows all further available elements:

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules/ip/ips/10.0.54.254' -X OPTIONS
{
"subResources": [
"sip_request_responses",
"peers_ports",
"sip_responses",
"sip_requests",
"qos",
"ports",
"connections",
"protocols",
"macs",
"peers",
"tcpStats"
]
}
</pre>

== JSON output traffic counters ==

All counters are aggregated counters, either for the selected time interval or since the processing start of the Allegro. Many traffic counters have 4 separate values. These traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows:
* line 1: '''received packets''', extraction example: jq .lastSecond[0]
* line 2: '''received bytes''', extraction example: jq .lastSecond[1]
* line 3: '''transmitted packets''', extraction example: jq .lastSecond[2]
* line 4: '''transmitted bytes''', extraction example: jq .lastSecond[3]
* additional lines are module specific

The following counters exist for many REST APIs like IP, MAC, l4 protocol, l7 protocol and many more:
* '''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.

Please note that all counters are byte counters, not bit counters. You need to multiply the counters by 8 to get the bitrate.

This example extracts the received bytes of the last second of a specific IP.

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

This example extracts received and transmitted bytes of the last second of a specific IP.

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

== API parameters ==

The Allegro REST API has a number of query parameters that can be added to modify the request. By default, the API will display the real time counters since the last restart of the processing unit.

This example extracts the amount of received and transmitted bytes for an IP address since the processing start of the Allegro. It queries via the REST API the JSON and then adds the values second value ( row 1, rx bytes ) and 4th value ( row 3, tx bytes ) of the interval counters together.

<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254" | jq '.interval[1] + .interval[3]'
</pre>

=== Time interval selection ===

Requests can be given a time interval. If present, the '''interval''' counters are adjusted to this 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). You can use <code>date +%s</code> on your machine to adjust to the best interval. Please consult the man page of date for more parameters.
* '''skiphistorydata''': shall the JSON include the history data without datasets, this reduces the amount of transferred bytes if datasets are required to render a graph, can be false/true default: false
* '''timespan''': required resolution for the graph dataset

This example extracts the amount of received and transmitted bytes for an IP address for the last 24 hours.
<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?starttime=$(date --date="1 day ago" +%s)&endtime=$(date +%s)&skiphistorydata=true" | jq '.interval[1] + .interval[3]'
</pre>

=== 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).

This example shows IP address with the highest amount of traffic

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

This exampe shows up to 9999 peers of a specific IP address:

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/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'</code>

=== Pcap extraction ===

The Allegro Network Multimeter allows to extract the raw packets with the REST API with the special capture URI <code>/API/data/modules/capture</code>

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

The available parameters are:

* '''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. If not specified, the current time will be used.
* '''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). If not specified, unlimited will be used.
* expression: The filter expression. There are no whitespaces allowed. You may use ‘%20’ instead. See [[Capture module]] for available expressions.
* 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).

Example to capture everything from now on:

<code>curl -k -u USER:PASSWORD 'https://allegro-mm/API/data/modules/capture' > path_to/capture.pcap</code>

Example to capture a specific IP of the last hour

<code>curl -k -u USER:PASSWORD "https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3&starttime=$(date --date="1 hour ago" +%s)&endtime=$(date +%s)&fromCaptureBuffer=true" > path_to/capture.pcap</code>

=== Virtual Link Groups ===

The Allegro REST API allows to access all link groups by the parameter '''group'''. The group index starts at zero, which is the default value. If a virtual link group is enabled.

This example extracts the traffic of the IP 10.54.0.254 from the second virtual link group ( index 1 ).

<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?group=1" | jq '.interval[1] + .interval[3]'
</pre>

=== Parallel pcap analysis ===

The Allegro can process in parallel offline traffic like a pcap file or a ring buffer. In case a parallel PCAP analysis is running, the API call must be given the additional header field <code>"X-AllegroPackets-Multimeter-ID: :1"</code> with the PCAP instance ID.

This allows to extract information of automated pcap uploads.

=== Multi-device analysis ===

If the Allegro is configured as a gateway for multiple Allegro devices by the [[Multi-device settings]], you need to add the additional header field <code>"X-AllegroPackets-Multimeter-ID: hostname"</code> where the hostname must be the same as configured in the multi-device settings.

== REST API Examples ==

==== MAC statistics ====

Extract the packets per second statistic of the MAC broadcast address

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/mac/macs/ff:ff:ff:ff:ff:ff'</code>

==== IP statistics ====

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.1.2.3'</code>

==== Pretty displaying JSON output with jq ====

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

==== Capture a specific IP ====

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

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

<code>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</code>

REST API description

2020-05-12T13:31:02Z

Klaus: /* Pcap parameters */

{| class="wikitable" style="text-align: center; color: red;"
| Warning: This text is under construction
|}

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).

Here an example of the structured JSON data for the IP overview. This data has been extracted with the Google Chrome developer console while accessing the IP statsistics page.

[[File:Rest api chrome console.png|800px]]

=== 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 [https://en.wikipedia.org/wiki/CURL]. 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 )

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

Please note that you might need to use <code>curl.exe</code> 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''' [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-restmethod].
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:

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

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

<code>-ContentType'application/json; charset=utf-8'</code>

To disable the certificate check, use:

<code>-SkipCertificateCheck</code>

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

<code>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</code>

=== jquery ( jq ) ===

jquery ( [https://stedolan.github.io/jq/] ) is a powerful tool to extract parameters from a json document. If called without parameters, jq formats the JSON output into a readable format with indenting and new lines. It also allows to select specific values and do basic operations like addition with this values.
Please read the jq documentation for more information.

== API hierarchy ==

=== Query available URIs with OPTIONS ===

The Allegro REST API has the fixed URI <code>API/stats</code> for statistics. To see all possible subtrees of a specific request, use the '''OPTIONS''' request instead of '''GET'''. It can be set with the parameter <code>-X OPTIONS</code> for curl.

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats' -X OPTIONS
{
"subResources": [
"modules",
"reports",
"incidentReporting",
"time",
"ringBufferReplay",
"pcap",
"reset",
"interfacesError",
"interfaces",
"load",
"processing"
]
}
</pre>

This allows you to query for example for all modules that are available for a specific release of the Allegro:

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules' -X OPTIONS
{
"subResources": [
"pppoe",
"lldp",
"groups",
"mpls",
"opc_ua",
"quality",
"ipsec",
"profinet",
"multicast",
"burst_analysis",
"global_incidents",
"ptp",
"ntp",
"icmp",
"stp",
"sip",
"smb",
"dpa",
"l4_ports",
"netbios",
"crt",
"dpi",
"http",
"ssl",
"dns",
"dhcp",
"location",
"qos",
"ip",
"mac_protocols",
"vlan",
"arp",
"packet_size",
"mac",
"capture"
]
}
</pre>

=== URI content parameters ===

Some modules allow to use a parameter as part of the URI like the IP or Mac address. The path <code>API/stats/modules/ip/ips</code> allows you to use an IP address as next uri element

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules/ip/ips' -X OPTIONS
{
"subResources": [
"protocol",
":ip"
]
}
</pre>

The path of an IP address shows all further available elements:

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules/ip/ips/10.0.54.254' -X OPTIONS
{
"subResources": [
"sip_request_responses",
"peers_ports",
"sip_responses",
"sip_requests",
"qos",
"ports",
"connections",
"protocols",
"macs",
"peers",
"tcpStats"
]
}
</pre>

== JSON output traffic counters ==

All counters are aggregated counters, either for the selected time interval or since the processing start of the Allegro. Many traffic counters have 4 separate values. These traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows:
* line 1: '''received packets''', extraction example: jq .lastSecond[0]
* line 2: '''received bytes''', extraction example: jq .lastSecond[1]
* line 3: '''transmitted packets''', extraction example: jq .lastSecond[2]
* line 4: '''transmitted bytes''', extraction example: jq .lastSecond[3]
* additional lines are module specific

The following counters exist for many REST APIs like IP, MAC, l4 protocol, l7 protocol and many more:
* '''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.

Please note that all counters are byte counters, not bit counters. You need to multiply the counters by 8 to get the bitrate.

This example extracts the received bytes of the last second of a specific IP.

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

This example extracts received and transmitted bytes of the last second of a specific IP.

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

== API parameters ==

The Allegro REST API has a number of query parameters that can be added to modify the request. By default, the API will display the real time counters since the last restart of the processing unit.

This example extracts the amount of received and transmitted bytes for an IP address since the processing start of the Allegro. It queries via the REST API the JSON and then adds the values second value ( row 1, rx bytes ) and 4th value ( row 3, tx bytes ) of the interval counters together.

<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254" | jq '.interval[1] + .interval[3]'
</pre>

=== Time interval selection ===

Requests can be given a time interval. If present, the '''interval''' counters are adjusted to this 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). You can use <code>date +%s</code> on your machine to adjust to the best interval. Please consult the man page of date for more parameters.
* '''skiphistorydata''': shall the JSON include the history data without datasets, this reduces the amount of transferred bytes if datasets are required to render a graph, can be false/true default: false
* '''timespan''': required resolution for the graph dataset

This example extracts the amount of received and transmitted bytes for an IP address for the last 24 hours.
<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?starttime=$(date --date="1 day ago" +%s)&endtime=$(date +%s)&skiphistorydata=true" | jq '.interval[1] + .interval[3]'
</pre>

=== 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).

This example shows IP address with the highest amount of traffic

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

This exampe shows up to 9999 peers of a specific IP address:

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/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'</code>

=== Pcap extraction ===

The Allegro Network Multimeter allows to extract the raw packets with the REST API with the special capture URI <code>/API/data/modules/capture</code>

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

The available parameters are:

* '''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. If not specified, the current time will be used.
* '''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). If not specified, unlimited will be used.
* expression: The filter expression. There are no whitespaces allowed. You may use ‘%20’ instead. See [[Capture module]] for available expressions.
* 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).

Example to capture everything from now on:

<code>curl -k -u USER:PASSWORD 'https://allegro-mm/API/data/modules/capture' > path_to/capture.pcap</code>

Example to capture a specific IP of the last hour

<code>curl -k -u USER:PASSWORD "https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3&starttime=$(date --date="1 hour ago" +%s)&endtime=$(date +%s)&fromCaptureBuffer=true" > path_to/capture.pcap</code>

=== Virtual Link Groups ===

The Allegro REST API allows to access all link groups by the parameter '''group'''. The group index starts at zero, which is the default value. If a virtual link group is enabled.

This example extracts the traffic of the IP 10.54.0.254 from the second virtual link group ( index 1 ).

<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?group=1" | jq '.interval[1] + .interval[3]'
</pre>

=== Parallel pcap analysis ===

The Allegro can process in parallel offline traffic like a pcap file or a ring buffer. In case a parallel PCAP analysis is running, the API call must be given the additional header field <code>"X-AllegroPackets-Multimeter-ID: :1"</code> with the PCAP instance ID.

This allows to extract information of automated pcap uploads.

=== Multi-device analysis ===

If the Allegro is configured as a gateway for multiple Allegro devices by the [[Multi-device settings]], you need to add the additional header field <code>"X-AllegroPackets-Multimeter-ID: hostname"</code> where the hostname must be the same as configured in the multi-device settings.

== REST API Examples ==

==== MAC or IP address statistics ====

Extract the packets per second statistic of the MAC broadcast address

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/mac/macs/ff:ff:ff:ff:ff:ff'</code>

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.1.2.3'</code>

==== Pretty displaying JSON output with jq ====

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

==== Capture a specific IP ====

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

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

<code>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</code>

REST API description

2020-05-12T13:30:43Z

Klaus:

{| class="wikitable" style="text-align: center; color: red;"
| Warning: This text is under construction
|}

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).

Here an example of the structured JSON data for the IP overview. This data has been extracted with the Google Chrome developer console while accessing the IP statsistics page.

[[File:Rest api chrome console.png|800px]]

=== 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 [https://en.wikipedia.org/wiki/CURL]. 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 )

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

Please note that you might need to use <code>curl.exe</code> 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''' [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-restmethod].
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:

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

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

<code>-ContentType'application/json; charset=utf-8'</code>

To disable the certificate check, use:

<code>-SkipCertificateCheck</code>

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

<code>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</code>

=== jquery ( jq ) ===

jquery ( [https://stedolan.github.io/jq/] ) is a powerful tool to extract parameters from a json document. If called without parameters, jq formats the JSON output into a readable format with indenting and new lines. It also allows to select specific values and do basic operations like addition with this values.
Please read the jq documentation for more information.

== API hierarchy ==

=== Query available URIs with OPTIONS ===

The Allegro REST API has the fixed URI <code>API/stats</code> for statistics. To see all possible subtrees of a specific request, use the '''OPTIONS''' request instead of '''GET'''. It can be set with the parameter <code>-X OPTIONS</code> for curl.

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats' -X OPTIONS
{
"subResources": [
"modules",
"reports",
"incidentReporting",
"time",
"ringBufferReplay",
"pcap",
"reset",
"interfacesError",
"interfaces",
"load",
"processing"
]
}
</pre>

This allows you to query for example for all modules that are available for a specific release of the Allegro:

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules' -X OPTIONS
{
"subResources": [
"pppoe",
"lldp",
"groups",
"mpls",
"opc_ua",
"quality",
"ipsec",
"profinet",
"multicast",
"burst_analysis",
"global_incidents",
"ptp",
"ntp",
"icmp",
"stp",
"sip",
"smb",
"dpa",
"l4_ports",
"netbios",
"crt",
"dpi",
"http",
"ssl",
"dns",
"dhcp",
"location",
"qos",
"ip",
"mac_protocols",
"vlan",
"arp",
"packet_size",
"mac",
"capture"
]
}
</pre>

=== URI content parameters ===

Some modules allow to use a parameter as part of the URI like the IP or Mac address. The path <code>API/stats/modules/ip/ips</code> allows you to use an IP address as next uri element

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules/ip/ips' -X OPTIONS
{
"subResources": [
"protocol",
":ip"
]
}
</pre>

The path of an IP address shows all further available elements:

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules/ip/ips/10.0.54.254' -X OPTIONS
{
"subResources": [
"sip_request_responses",
"peers_ports",
"sip_responses",
"sip_requests",
"qos",
"ports",
"connections",
"protocols",
"macs",
"peers",
"tcpStats"
]
}
</pre>

== JSON output traffic counters ==

All counters are aggregated counters, either for the selected time interval or since the processing start of the Allegro. Many traffic counters have 4 separate values. These traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows:
* line 1: '''received packets''', extraction example: jq .lastSecond[0]
* line 2: '''received bytes''', extraction example: jq .lastSecond[1]
* line 3: '''transmitted packets''', extraction example: jq .lastSecond[2]
* line 4: '''transmitted bytes''', extraction example: jq .lastSecond[3]
* additional lines are module specific

The following counters exist for many REST APIs like IP, MAC, l4 protocol, l7 protocol and many more:
* '''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.

Please note that all counters are byte counters, not bit counters. You need to multiply the counters by 8 to get the bitrate.

This example extracts the received bytes of the last second of a specific IP.

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

This example extracts received and transmitted bytes of the last second of a specific IP.

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

== API parameters ==

The Allegro REST API has a number of query parameters that can be added to modify the request. By default, the API will display the real time counters since the last restart of the processing unit.

This example extracts the amount of received and transmitted bytes for an IP address since the processing start of the Allegro. It queries via the REST API the JSON and then adds the values second value ( row 1, rx bytes ) and 4th value ( row 3, tx bytes ) of the interval counters together.

<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254" | jq '.interval[1] + .interval[3]'
</pre>

=== Time interval selection ===

Requests can be given a time interval. If present, the '''interval''' counters are adjusted to this 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). You can use <code>date +%s</code> on your machine to adjust to the best interval. Please consult the man page of date for more parameters.
* '''skiphistorydata''': shall the JSON include the history data without datasets, this reduces the amount of transferred bytes if datasets are required to render a graph, can be false/true default: false
* '''timespan''': required resolution for the graph dataset

This example extracts the amount of received and transmitted bytes for an IP address for the last 24 hours.
<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?starttime=$(date --date="1 day ago" +%s)&endtime=$(date +%s)&skiphistorydata=true" | jq '.interval[1] + .interval[3]'
</pre>

=== 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).

This example shows IP address with the highest amount of traffic

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

This exampe shows up to 9999 peers of a specific IP address:

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/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'</code>

=== Pcap parameters ===

The Allegro Network Multimeter allows to extract the raw packets with the REST API with the special capture URI <code>/API/data/modules/capture</code>

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

The available parameters are:

* '''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. If not specified, the current time will be used.
* '''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). If not specified, unlimited will be used.
* expression: The filter expression. There are no whitespaces allowed. You may use ‘%20’ instead. See [[Capture module]] for available expressions.
* 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).

Example to capture everything from now on:

<code>curl -k -u USER:PASSWORD 'https://allegro-mm/API/data/modules/capture' > path_to/capture.pcap</code>

Example to capture a specific IP of the last hour

<code>curl -k -u USER:PASSWORD "https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3&starttime=$(date --date="1 hour ago" +%s)&endtime=$(date +%s)&fromCaptureBuffer=true" > path_to/capture.pcap</code>

=== Virtual Link Groups ===

The Allegro REST API allows to access all link groups by the parameter '''group'''. The group index starts at zero, which is the default value. If a virtual link group is enabled.

This example extracts the traffic of the IP 10.54.0.254 from the second virtual link group ( index 1 ).

<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?group=1" | jq '.interval[1] + .interval[3]'
</pre>

=== Parallel pcap analysis ===

The Allegro can process in parallel offline traffic like a pcap file or a ring buffer. In case a parallel PCAP analysis is running, the API call must be given the additional header field <code>"X-AllegroPackets-Multimeter-ID: :1"</code> with the PCAP instance ID.

This allows to extract information of automated pcap uploads.

=== Multi-device analysis ===

If the Allegro is configured as a gateway for multiple Allegro devices by the [[Multi-device settings]], you need to add the additional header field <code>"X-AllegroPackets-Multimeter-ID: hostname"</code> where the hostname must be the same as configured in the multi-device settings.

== REST API Examples ==

==== MAC or IP address statistics ====

Extract the packets per second statistic of the MAC broadcast address

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/mac/macs/ff:ff:ff:ff:ff:ff'</code>

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.1.2.3'</code>

==== Pretty displaying JSON output with jq ====

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

==== Capture a specific IP ====

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

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

<code>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</code>

REST API description

2020-05-12T13:27:15Z

Klaus: /* Pcap parameters */

{| class="wikitable" style="text-align: center; color: red;"
| Warning: This text is under construction
|}

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).

Here an example of the structured JSON data for the IP overview. This data has been extracted with the Google Chrome developer console while accessing the IP statsistics page.

[[File:Rest api chrome console.png|800px]]

=== 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 [https://en.wikipedia.org/wiki/CURL]. 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 )

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

Please note that you might need to use <code>curl.exe</code> 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''' [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-restmethod].
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:

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

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

<code>-ContentType'application/json; charset=utf-8'</code>

To disable the certificate check, use:

<code>-SkipCertificateCheck</code>

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

<code>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</code>

=== jquery ( jq ) ===

jquery ( [https://stedolan.github.io/jq/] ) is a powerful tool to extract parameters from a json document. If called without parameters, jq formats the JSON output into a readable format with indenting and new lines. It also allows to select specific values and do basic operations like addition with this values.
Please read the jq documentation for more information.

== API hierarchy ==

=== Query available URIs with OPTIONS ===

The Allegro REST API has the fixed URI <code>API/stats</code> for statistics. To see all possible subtrees of a specific request, use the '''OPTIONS''' request instead of '''GET'''. It can be set with the parameter <code>-X OPTIONS</code> for curl.

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats' -X OPTIONS
{
"subResources": [
"modules",
"reports",
"incidentReporting",
"time",
"ringBufferReplay",
"pcap",
"reset",
"interfacesError",
"interfaces",
"load",
"processing"
]
}
</pre>

This allows you to query for example for all modules that are available for a specific release of the Allegro:

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules' -X OPTIONS
{
"subResources": [
"pppoe",
"lldp",
"groups",
"mpls",
"opc_ua",
"quality",
"ipsec",
"profinet",
"multicast",
"burst_analysis",
"global_incidents",
"ptp",
"ntp",
"icmp",
"stp",
"sip",
"smb",
"dpa",
"l4_ports",
"netbios",
"crt",
"dpi",
"http",
"ssl",
"dns",
"dhcp",
"location",
"qos",
"ip",
"mac_protocols",
"vlan",
"arp",
"packet_size",
"mac",
"capture"
]
}
</pre>

=== URI content parameters ===

Some modules allow to use a parameter as part of the URI like the IP or Mac address. The path <code>API/stats/modules/ip/ips</code> allows you to use an IP address as next uri element

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules/ip/ips' -X OPTIONS
{
"subResources": [
"protocol",
":ip"
]
}
</pre>

The path of an IP address shows all further available elements:

<pre>
$ curl --silent -k -u 'admin:allegro' 'https://allegro-mm/API/stats/modules/ip/ips/10.0.54.254' -X OPTIONS
{
"subResources": [
"sip_request_responses",
"peers_ports",
"sip_responses",
"sip_requests",
"qos",
"ports",
"connections",
"protocols",
"macs",
"peers",
"tcpStats"
]
}
</pre>

== JSON output traffic counters ==

All counters are aggregated counters, either for the selected time interval or since the processing start of the Allegro. Many traffic counters have 4 separate values. These traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows:
* line 1: '''received packets''', extraction example: jq .lastSecond[0]
* line 2: '''received bytes''', extraction example: jq .lastSecond[1]
* line 3: '''transmitted packets''', extraction example: jq .lastSecond[2]
* line 4: '''transmitted bytes''', extraction example: jq .lastSecond[3]
* additional lines are module specific

The following counters exist for many REST APIs like IP, MAC, l4 protocol, l7 protocol and many more:
* '''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.

Please note that all counters are byte counters, not bit counters. You need to multiply the counters by 8 to get the bitrate.

This example extracts the received bytes of the last second of a specific IP.

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

This example extracts received and transmitted bytes of the last second of a specific IP.

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

== API parameters ==

The Allegro REST API has a number of query parameters that can be added to modify the request. By default, the API will display the real time counters since the last restart of the processing unit.

This example extracts the amount of received and transmitted bytes for an IP address since the processing start of the Allegro. It queries via the REST API the JSON and then adds the values second value ( row 1, rx bytes ) and 4th value ( row 3, tx bytes ) of the interval counters together.

<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254" | jq '.interval[1] + .interval[3]'
</pre>

=== Time interval selection ===

Requests can be given a time interval. If present, the '''interval''' counters are adjusted to this 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). You can use <code>date +%s</code> on your machine to adjust to the best interval. Please consult the man page of date for more parameters.
* '''skiphistorydata''': shall the JSON include the history data without datasets, this reduces the amount of transferred bytes if datasets are required to render a graph, can be false/true default: false
* '''timespan''': required resolution for the graph dataset

This example extracts the amount of received and transmitted bytes for an IP address for the last 24 hours.
<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?starttime=$(date --date="1 day ago" +%s)&endtime=$(date +%s)&skiphistorydata=true" | jq '.interval[1] + .interval[3]'
</pre>

=== Pcap parameters ===

The Allegro Network Multimeter allows to extract the raw packets with the REST API with the special capture URI <code>/API/data/modules/capture</code>

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

The available parameters are:

* '''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. If not specified, the current time will be used.
* '''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). If not specified, unlimited will be used.
* expression: The filter expression. There are no whitespaces allowed. You may use ‘%20’ instead. See [[Capture module]] for available expressions.
* 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).

Example to capture everything from now on:

<code>curl -k -u USER:PASSWORD 'https://allegro-mm/API/data/modules/capture' > path_to/capture.pcap</code>

Example to capture a specific IP of the last hour

<code>curl -k -u USER:PASSWORD "https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3&starttime=$(date --date="1 hour ago" +%s)&endtime=$(date +%s)&fromCaptureBuffer=true" > path_to/capture.pcap</code>

=== Virtual Link Groups ===

The Allegro REST API allows to access all link groups by the parameter '''group'''. The group index starts at zero, which is the default value. If a virtual link group is enabled.

This example extracts the traffic of the IP 10.54.0.254 from the second virtual link group ( index 1 ).

<pre>
$ curl --silent -k -u 'admin:allegro' "https://allegro-mm/API/stats/modules/ip/ips/10.54.0.254?group=1" | jq '.interval[1] + .interval[3]'
</pre>

=== Parallel pcap analysis ===

The Allegro can process in parallel offline traffic like a pcap file or a ring buffer. In case a parallel PCAP analysis is running, the API call must be given the additional header field <code>"X-AllegroPackets-Multimeter-ID: :1"</code> with the PCAP instance ID.

This allows to extract information of automated pcap uploads.

=== Multi-device analysis ===

If the Allegro is configured as a gateway for multiple Allegro devices by the [[Multi-device settings]], you need to add the additional header field <code>"X-AllegroPackets-Multimeter-ID: hostname"</code> where the hostname must be the same as configured in the multi-device settings.

== REST API Examples ==

==== MAC or IP address statistics ====

Extract the packets per second statistic of the MAC broadcast address

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/mac/macs/ff:ff:ff:ff:ff:ff'</code>

<code>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.1.2.3'</code>

==== Pretty displaying JSON output with jq ====

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

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

<code>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</code>

PowerShell command:

<code>((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</code>

==== Show all peers of a specific IP address ====

<code>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'</code>

==== Capture a specific IP ====

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

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

<code>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</code>