Summary

A summary for developers to access a FMADIO device using the API.

FMADIO API

The FMADIO API is simple and designed for easy scripting integration.

Note: Replace the IP 127.0.0.1 with the host IP of your FMADIO device.

Device Operation

Capture Start

GET /sysmaster/capture_start?StreamName=<capture name>

This Command starts a capture running on the device.

Query Parameters

Name

Type

Description

StreamName

string

Stream capture name

{
  "Status": true,
  "Str": "[Fri May 28 09:48:34 2021] successfully started capture [test1234]"
}

Capture Stop

GET /sysmaster/capture_stop

Stops any currently capturing process. NOTE: this does NOT stop scheduled captures.

{
    "Status":true,
    "Str":"[Mon Jul  2 11:26:13 2018] successfully stopped capture [TestCapture]"
}

Capture Status JSON format

GET /sysmaster/capture_status

Returns status of the capture in JSON format

{
  "Status": true,
  "GUIMode": "full",
  "StreamName": "capturetest",
  "CaptureEnable": "false",
  "CaptureTime": 1642057937.6518,
  "CaptureByte": 9960256568,
  "CapturePacket": 36312769,
  "CaptureBps": 687557440,
  "CapturePps": 266806.4375,
  "CurrentTime": "2022/01/13   07:12"
}

General System Status (CSV)

GET /sysmaster/status

Returns Capture status of currently active capture.

$ curl -u fmadio:100g http://192.168.2.75/sysmaster/status
uptime,                                             0D 1H 57M
packets_received,                                222652795259
packets_dropped,                                            0
packets_errors,                                        300000
packets_captured,                                222265863667
bytes_captured,                                20084978997482
bytes_pending,                                              0
bytes_disk,                                    21817945751552
bytes_overflow,                                 230924484608
bytes_overflow_now,                                            0
capture0_link,                                              up
capture0_link_uptime,                                0D 1H 57M
capture0_link_speed,                                     10000
capture1_link,                                              up
capture1_link_uptime,                                0D 1H 57M
capture1_link_speed,                                     10000
capture_bytes,                                              0
capture_packets,                                            0
capture_bps,                                                0
capture_pps,                                                0
capture_name,                                     TestCapture
capture_active,                                          true

Device Management

System Status

GET /sysmaster/stats_summary

Get system status information. Partial example output in parsed JSON format below

{
	"uptime":"0D 7H 16M",
	"packets_received":1454363817,
	"packets_dropped":0,
	"packets_errors":0,
	"packets_captured":1454363968,
	"packets_oldest":"19 May 2014 15:48:38",
	"packets_oldest_ts":"1400482118411568128",
	"capture_days":"1505D  0H 57M",
	"bytes_captured":105800185305,
	"bytes_pending":0,
	"bytes_disk":171117117440,
	"bytes_overflow":0,
	"smart_errors":0,
	"raid_errors":0,
	"raid_status":"clean : raid5",
	"stream_errors":0,
	"chunk_errors":0,
	"ecc_errors":0,
.
.
.
.
}

Delete Capture

GET /pcap/del?StreamName=<full capture name>

Deletes capture off the system

Path Parameters

Name

Type

Description

StreamName

string

full name of the capture file to be deleted

V1 API

The FMADIO V1 API uses endpoints with parameters. All V1 versions of the API endpoints shall have the format:

/api/v1/<operation>/<task>?<params=x>

The V1 API has advantages of the previous API. These are:

Multiple downloads can occur at the same time on the same device (up to 4 concurrently).
Improved download performance
Ability to use compressed and bpf filter parameters on most downloads.

Note: All original API url's shall be available as well as the new V1 endpoints.

Downloading PCAP

Single PCAP Download

GET /api/v1/pcap/single

Download entire capture as a single file. Piping to a file or any other analysis tools is possible.

Query Parameters

Name

Type

Description

FilterBPF

string

BPF Filter to be applied to the stream.

Compression

string

Compress the returned stream with gzip. 'fast' Fastest compression but not smallest. 'best' Slowest compression smallest size. 1-9 The range from 'fast' to 'best'

StreamName*

string

Stream capture name.

FilterFrame

String

Filter on the Packet Frame

a7130.device==<device id>

a7130.srcport==<port id>

c3550.srcport==<portid>

capture.port==<portid>

TSMode

String

Sets the Timestamp of the PCAP

nic - FMADIO FPGA timestamp

arista7130 - Arista 7130 (Metamako)

arista7150_overwrite - Arista 7150 FCS Overwrite

arista7150_insert - Arista 7150 Insert 32bit

arista7280_eth64 - Arista 7280 Ethernet 64bit header

arista7280_mac48 - Arista 7280 SrcMAC 48bit Overwrite

cisco_erspan3 - Cisco ERPSANv3

cisco3550 - Cisco 3550 (Exablaze)

FilterBPFDecap

string

true : Run BPF filter on a De-Encapsulated version of the packet

false : Run BPF on raw packet

Default: false

$ curl -u fmadio:100g "http://192.168.2.75/api/v1/pcap/single?StreamName=TestCapture_20180702_1127&&FilterBPF=tcp" | tcpdump  -r - -nn | head
11:33:08.000000 66:77:88:99:aa:bb > 00:44:44:44:44:44 Null Information, send seq 22, rcv seq 1, Flags [Poll], length 54
        0x0000:  0000 2c03 153a 2d03 153a 2e03 153a 2f03  ..,..:-..:...:/.
        0x0010:  153a 3003 153a 3103 153a 3203 153a 3303  .:0..:1..:2..:3.
        0x0020:  153a 3403 153a 3503 153a 3603 153a 3703  .:4..:5..:6..:7.
        0x0030:  153a a878 4e26                           .:.xN&
11:33:08.000000 66:77:88:99:aa:bb > 00:33:33:33:33:33 Null Information, send seq 22, rcv seq 1, Flags [Poll], length 54
        0x0000:  0000 2c03 152a 2d03 152a 2e03 152a 2f03  ..,..*-..*...*/.
        0x0010:  152a 3003 152a 3103 152a 3203 152a 3303  .*0..*1..*2..*3.
        0x0020:  152a 3403 152a 3503 152a 3603 152a 3703  .*4..*5..*6..*7.
        0x0030:  152a 7b57 491d                           .*{WI.
.
.
.
.
.

Get Specific PCAP timerange (optional BPF filter)

GET /api/v1/pcap/splittime

Gets PCAP from the specified StreamName with Start/Stop EPOCH time with an optional BPF filter

Query Parameters

Name

Type

Description

StreamName*

String

Capture name to fetch from

Start*

String

EPOCH Nanosecond start time

Stop*

String

EPOCH Nanosecond stop time

FilterBPF

String

Escape Encoded BPF filter

FilterFrame

String

Filter on the Packet Frame

a7130.device==<device id>

a7130.srcport==<port id>

c3550.srcport==<portid>

capture.port==<portid>

TSMode

String

Sets the Timestamp of the PCAP

nic - FMADIO FPGA timestamp

arista7130 - Arista 7130 (Metamako)

arista7150_overwrite - Arista 7150 FCS Overwrite

arista7150_insert - Arista 7150 Insert 32bit

arista7280_eth64 - Arista 7280 Ethernet 64bit header

arista7280_mac48 - Arista 7280 SrcMAC 48bit Overwrite

cisco_erspan3 - Cisco ERPSANv3

cisco3550 - Cisco 3550 (Exablaze)

{
    // Response
}

TimeRange PCAP Download (optional BPF and Frame Filter)

GET /api/v1/pcap/timerange

Download a timerange of pcap data that can cross over a multiple pcap files. The timerange results may be a portion of a single pcap stream, or a portion of multiple streams that share a connected time series.

Examples

https://docs.fmad.io/fmadio-documentation/api/usage-guide#timerange-1

TSBegin and TSEnd

curl -u fmadio:xxx "http://127.0.0.1/api/v1/pcap/timerange?TSBegin=1621772572136996000&TSEnd=1621774913584264000"

TSBegin, TSEnd and FilterBPF

curl -u fmadio:xxx "http://127.0.0.1/api/v1/pcap/timerange?TSBegin=1621772572136996000&TSEnd=1621774913584264000" -G --data-urlencode "FilterBPF=tcp"

TSBegin, TSEnd, FilterBPF and Compression

curl -u fmadio:xxx "http://127.0.0.1/api/v1/pcap/timerange?TSBegin=1621772572136996000&TSEnd=1621774913584264000&Compression=fast" -G --data-urlencode "FilterBPF=tcp"

Query Parameters

Name

Type

Description

FilterBPF

string

Compression

string

Compress the returned stream with gzip. 'fast' Fastest compression but not smallest. 'best' Slowest compression smallest size. 1-9 The range from 'fast' to 'best'

TSMax

integer

Maximum nanosecond of packets to download.

TSUnit

string

Time Range mode to use for time selection

nanos : Nanoseconds (default)

msecs : Milliseconds

sec : Seconds

YYYYMMDD_HHMMSS: this year year month day hour min second time format

TSBegin*

integer

Start time in nanoseconds epoch.

TSEnd*

integer

Stop time in nanoseconds epoch.

FilterFrame

String

Filtering based on frame parameters

capture.port==0,1

(fetch data for capture ports 0 and 1 only)

capture.port!=0

(fetch data for capture ports NOT equal to 0)

a7130.srcdevice!=0

(fetch data for anything that has a valid Arista 7130 device id)

a7130.srcdevice==0

(fetch anything that does NOT have a valid Arista 7130 device id)

a7130.srcdevice=54931 and a7130.srcport=1

(fetch data only for Arista 7130 device id 54931 and Arista 7130 port id 1)

a7130.srcdevice==54931 and a7130.srcport=1,2,3,4

(fetch data for Arista 7130 device id 54931 and Arista 7130 ports 1, 2, 3, 4)

a7130.srcdevice==54931 and a7130.srcport!=1

(fetch data for Arista 7130 device ie 54931 and all ports except port 1)

TSMode

String

Sets the Timestamp of the PCAP

nic - FMADIO FPGA timestamp

arista7130 - Arista 7130 (Metamako)

arista7150_overwrite - Arista 7150 FCS Overwrite

arista7150_insert - Arista 7150 Insert 32bit

arista7280_eth64 - Arista 7280 Ethernet 64bit header

arista7280_mac48 - Arista 7280 SrcMAC 48bit Overwrite

cisco_erspan3 - Cisco ERPSANv3

cisco3550 - Cisco 3550 (Exablaze)

FilterBPFDecap

string

true : Run BPF filter on a De-Encapsulated version of the packet

false : Run BPF on raw packet

Default: false

$ curl -u fmadio:100g "http://192.168.2.75/pcap/timerange?TSBegin=1530498788000000000&TSEnd=1530498789000000000&" | tcpdump  -r - -nn | head
11:33:08.000000 66:77:88:99:aa:bb > 00:44:44:44:44:44 Null Information, send seq 22, rcv seq 1, Flags [Poll], length 54
        0x0000:  0000 2c03 153a 2d03 153a 2e03 153a 2f03  ..,..:-..:...:/.
        0x0010:  153a 3003 153a 3103 153a 3203 153a 3303  .:0..:1..:2..:3.
        0x0020:  153a 3403 153a 3503 153a 3603 153a 3703  .:4..:5..:6..:7.
        0x0030:  153a a878 4e26                           .:.xN&
11:33:08.000000 66:77:88:99:aa:bb > 00:33:33:33:33:33 Null Information, send seq 22, rcv seq 1, Flags [Poll], length 54
        0x0000:  0000 2c03 152a 2d03 152a 2e03 152a 2f03  ..,..*-..*...*/.
        0x0010:  152a 3003 152a 3103 152a 3203 152a 3303  .*0..*1..*2..*3.
        0x0020:  152a 3403 152a 3503 152a 3603 152a 3703  .*4..*5..*6..*7.
        0x0030:  152a 7b57 491d                           .*{WI.
.
.
.
.
.

System

Read the current FPGA System Time

GET /api/v1/system/time_current

Returns the current time on the fpga in epoch nanoseconds. This time/clock is used directly to timestamp packets on the FPGA.

$ curl http://127.0.0.1/api/v1/system/time_current
1652273869313808661
$

Get current system version information

GET /api/v1/system/version

Returns the current system version.

Example output:

fmadio@fmadio100v2-228U:$ curl http://127.0.0.1/api/v1/system/version {"version":"9120","device":"fmadio100v2","build":"Wed Sep 27 03:08:27 2023"} fmadio@fmadio100v2-228U:$

Get RMON1 capture port stats

GET /api/v1/system/port_stats

returns RMON1 capture port statistics

Example:

fmadio@fmadio100v2-228U:$ curl -s http://127.0.0.1/api/v1/system/port_stats | jq

{

"cap0":

{ "Pkt": 0, "Byte": 0, "Pkt_RUNT": 0, "Pkt_64": 0, "Pkt_65_127": 0, "Pkt_128_255": 0, "Pkt_256_511": 0, "Pkt_512_1023": 0, "Pkt_1024_1518": 0, "Pkt_1024_2047": 0, "Pkt_2048_4095": 0, "Pkt_4096_8191": 0, "Pkt_8192_9216": 0, "Pkt_OVER": 0 },

"cap1":

"cap2":

"cap3":

"cap4":

"cap5":

"cap6":

{ "Pkt": 7237, "Byte": 1936022, "Pkt_RUNT": 0, "Pkt_64": 55, "Pkt_65_127": 559, "Pkt_128_255": 257, "Pkt_256_511": 6136, "Pkt_512_1023": 180, "Pkt_1024_1518": 50, "Pkt_1024_2047": 50, "Pkt_2048_4095": 0, "Pkt_4096_8191": 0, "Pkt_8192_9216": 0, "Pkt_OVER": 0 },

"cap7":

"port_config": "8x10G"

}

fmadio@fmadio100v2-228U:$

Get IO Statistics on the system

GET /api/v1/system/io_stats

Example:

fmadio@fmadio100v2-228U:$ curl -s http://127.0.0.1/api/v1/system/io_stats | jq { "timestamp": "1696925340903886080", "ioqueue_active": "1" } fmadio@fmadio100v2-228U:$

Get system status

GET /api/v1/system/status

Returns the system status, this is identical to the Telemetry data

https://docs.fmad.io/fmadio-documentation/monitoring/syslog-fmadio100gv2

Example output:

fmadio@fmadio100v2-228U:~$ curl -s http://127.0.0.1/api/v1/system/status

Resulting JSON blob

Pretty print output

Legacy Download

NOTE: These interfaces are legacy, recommend using the V1 API interfaces

List All Captures

GET /stream/list

Lists all captures on the device.

$ curl -u fmadio:100g http://192.168.2.75/stream/list
{"Path":"/capture/","StreamList":true,"List":[
    {"id":"1","Path":"TestCapture_20180702_1127","PCAP":"/pcap/single?StreamName=TestCapture_20180702_1127&","Filter":"/en.filter.html?StreamName=TestCapture_20180702_1127&","Analytics":"/en.analytics.html?StreamName=TestCapture_20180702_1127&","TCPScope":"/en.tcpscope.html?StreamName=TestCapture_20180702_1127&","Link":"/en.files.html?Fn=view&StreamName=TestCapture_20180702_1127&","Date":1.5304988337881e+18,"Size":168169046016,"Del":"/pcap/del?StreamName=TestCapture_20180702_1127&rand=1530498848939065088&","IsActive":false,"Type":"","Desc":"Mon . 11:33:53 . 02-07-2018"},
    {"id":"2","Path":"TestCapture_20180702_1118","PCAP":"/pcap/single?StreamName=TestCapture_20180702_1118&","Filter":"/en.filter.html?StreamName=TestCapture_20180702_1118&","Analytics":"/en.analytics.html?StreamName=TestCapture_20180702_1118&","TCPScope":"/en.tcpscope.html?StreamName=TestCapture_20180702_1118&","Link":"/en.files.html?Fn=view&StreamName=TestCapture_20180702_1118&","Date":1.5304978842841e+18,"Size":0,"Del":"/pcap/del?StreamName=TestCapture_20180702_1118&rand=1530498848939096064&","IsActive":false,"Type":"","Desc":"Mon . 11:18:04 . 02-07-2018"}
]}

Split Capture by filesize

GET /stream/ssize?StreamName=<capture sname>&StreamView=<split mode>

Lists splits for a specific capture based on file size. Usually this is a 2 step process of 1) get the split list 2) download a specific split.

Query Parameters

Name

Type

Description

StreamView

string

Stream time slice name split_10MB split_100MB split_250MB split_1GB split_2GB split_5GB split_10GB split_100GB split_1TB

StreamName

string

Stream capture name

{
  "Path": "/capture/test1234_20210611_1258/split_1GB",
  "SplitFile": true,
  "CloudShark": false,
  "List": [
    {
      "id": "0",
      "Path": "20210611_12:58:47.332.461.824",
      "PCAP": "/pcap/splittime?StreamName=test1234_20210611_1258&Start=1623383927332461824ULL&Stop=1623383937678376671ULL&&",
      "Filter": "/en.filter.html?StreamName=test1234_20210611_1258&StartTS=1623383927332461824&StopTS=1623383937678376671&",
      "Date": 1623383927332500000,
      "Size": 1000079360,
      "PacketCnt": 12357055,
      "ValidPct": 100,
      "Type": "",
      "Desc": "Fri . 12:58:47 . 11-06-2021"
    },
    {
      "id": "1",
      "Path": "20210611_12:58:57.678.376.671",
      "PCAP": "/pcap/splittime?StreamName=test1234_20210611_1258&Start=1623383937678376671ULL&Stop=1623383938108305103ULL&&",
      "Filter": "/en.filter.html?StreamName=test1234_20210611_1258&StartTS=1623383937678376671&StopTS=1623383938108305103&",
      "Date": 1623383937678400000,
      "Size": 1000079360,
      "PacketCnt": 12497940,
      "ValidPct": 100,
      "Type": "",
      "Desc": "Fri . 12:58:57 . 11-06-2021"
    },
    .
    .
  }

Split Capture by time

GET /stream/stime?StreamName=<capture sname>&StreamView=<split mode>

Lists splits for a specific capture based on a time unit. Usually this is a 2 step process of 1) get the split list 2) download a specific split

Query Parameters

Name

Type

Description

StreamView

string

Split options for the time split split_1sec split_10sec split_1min split_10min split_15min split_1hour split_2hour split_4hour split_6hour split_8hour split_12hour

StreamName

string

Stream capture name.

Single PCAP Download

GET /pcap/single?StreamName=<capture name>&FilterRE=<string>

Download entire capture as a single file. Piping to a file or any other analysis tools is possible.

Compression example: curl -u fmadio:100g "http://192.168.2.75/pcap/single?StreamName=TestCapture_20180702_1127&Compression=fast"

FilterBPF example: curl -u fmadio:100g "http://192.168.2.75/pcap/single?StreamName=hitcon_20180702_1503_58&" -G --data-urlencode "FilterBPF=tcp"

Query Parameters

Name

Type

Description

FilterRE

string

Download the capture with using a RegEx DPI filter.

FilterBPF

string

BPF Filter to be applied to the stream

Compression

string

Compress the returned stream with gzip. 'fast' Fastest compression but not smallest 'best' Slowest compression smallest size 1-9 The range from 'fast' to 'best'

StreamName

string

Stream capture name.

Split PCAP Time Download

GET /pcap/splittime?StreamName=<string>&Start=<int>&Stop=<int>&FilterBPF=<string>&FilterPort=<int>

Download the capture with a time filter. Note: the nanosecond Epoch Start is 1530498788000000000. Removing the nanosecond part convert epoch to date/time.

Query Parameters

Name

Type

Description

FilterPort

integer

Download the capture specifying the port capture number.

FilterBPF

string

BPF Filter to be applied to the stream.

StreamName*

string

Stream capture name.

Stop*

integer

Stop time in nanoseconds epoch.

Start*

integer

Start time in nanoseconds epoch.

$ curl -u fmadio:100g "http://192.168.2.75/pcap/splittime?StreamName=TestCapture_20180702_1127&&Start=1530498788000000000&Stop=1530498789000000000&" | tcpdump  -r - -nn | head
11:33:08.000000 66:77:88:99:aa:bb > 00:44:44:44:44:44 Null Information, send seq 22, rcv seq 1, Flags [Poll], length 54
        0x0000:  0000 2c03 153a 2d03 153a 2e03 153a 2f03  ..,..:-..:...:/.
        0x0010:  153a 3003 153a 3103 153a 3203 153a 3303  .:0..:1..:2..:3.
        0x0020:  153a 3403 153a 3503 153a 3603 153a 3703  .:4..:5..:6..:7.
        0x0030:  153a a878 4e26                           .:.xN&
11:33:08.000000 66:77:88:99:aa:bb > 00:33:33:33:33:33 Null Information, send seq 22, rcv seq 1, Flags [Poll], length 54
        0x0000:  0000 2c03 152a 2d03 152a 2e03 152a 2f03  ..,..*-..*...*/.
        0x0010:  152a 3003 152a 3103 152a 3203 152a 3303  .*0..*1..*2..*3.
        0x0020:  152a 3403 152a 3503 152a 3603 152a 3703  .*4..*5..*6..*7.
        0x0030:  152a 7b57 491d                           .*{WI.
.
.
.
.
.

TimeRange PCAP Download

GET /pcap/timerange?TSBegin=<epoch start>&TSEnd=<epoch stop>&TSMax=<size>&TSMode=<nanos or msecs>

Download a timerange of pcap data without any capture file referenced. The system will search all captures for the specified timerange. At most it can cross two pcap files

Query Parameters

Name

Type

Description

TSMax

integer

Maximum nanosecond of packets to download.

TSMode

string

Time Range mode to use for time: nsec | epoch in nano seconds (default) usec | epoch in micro seconds msec | epoch in milli seconds sec: | epoch in seconds

TSBegin*

integer

Start time in epoch (default nano seconds)

TSEnd*

integer

Stop time in epoch (default nano seconds).

Previousfnic_test NextExamples

Last updated 1 year ago