Summary | fmadio documentation

Home

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

{
  "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

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

$ 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

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

$ 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

{
  "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

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

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

$ 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