A guide for developers to access a FMADIO using the web based API. Examples are provided for all endpoints.
FMADIO API
The examples show how to use the different parameters for the uri endpoint.
Note : Replace the IP 127.0.0.1 with the host IP of your FMADIO device.
Status
Copy curl -u fmadio:100g "http://127.0.0.1/sysmaster/status" Device Status
Copy curl -u fmadio:100g "http://127.0.0.1/sysmaster/stats_summary" CaptureList
Copy curl -u fmadio:100g "http://127.0.0.1/stream/list" Capture Split By Filesize
Copy curl -u fmadio:100g "http://127.0.0.1/stream/ssize?
StreamName=stream_test_001&
StreamView=split_1GB&" Capture Split By Time
Copy curl -u fmadio:100g "http://127.0.0.1/stream/stime?
StreamName=stream_test_001&
StreamView=split_1sec&" Legacy Interface
Single
StreamName only:
Copy curl -u fmadio:100g "http://127.0.0.1/pcap/single?StreamName=stream_test_001" StreamName and FilterBPF
Copy curl -u fmadio:100g "http://127.0.0.1/pcap/single?StreamName=stream_test_001&" -G --data-urlencode "FilterBPF=tcp" StreamName and Compression
Copy curl -u fmadio:100g "http://127.0.0.1/pcap/single?StreamName=stream_test_001&Compression=fast" StreamName and FilterRE
Copy curl -u fmadio:100g "http://127.0.0.1/pcap/single?StreamName=stream_test_001&" -G --data-urlencode "FilterRE=/login/i" StreamName , Compression and FilterBPF
Copy curl -u fmadio:100g "http://127.0.0.1/pcap/single?StreamName=stream_test_001&Compression=fast&" -G --data-urlencode "FilterBPF=tcp" SplitTime
StreamName , Start and Stop
Copy curl -u fmadio:100g "http://127.0.0.1/pcap/splittime?StreamName=stream_test_001&Start=1530498788000000000&Stop=1530498789000000000&" StreamName , Start, Stop and FilterBPF
Copy curl -u fmadio:100g "http://127.0.0.1/pcap/splittime?StreamName=stream_test_001&Start=1530498788000000000&Stop=1530498789000000000&" -G --data-urlencode "FilterBPF=tcp" StreamName , Start , Stop and FilterPort
Copy curl -u fmadio:100g "http://127.0.0.1/pcap/splittime?StreamName=stream_test_001&Start=1530498788000000000&Stop=1530498789000000000&FilterPort=0" TimeRange
TSBegin and TSEnd
Copy curl -u fmadio:100g "http://127.0.0.1/pcap/timerange?TSBegin=1497329459948411420&TSEnd=1597329469948411420" TSBegin, TSEnd, TSMode and TSMax
Copy curl -u fmadio:100g "http://127.0.0.1/pcap/timerange?TSBegin=1497329459948411420&TSEnd=1597329469948411420&TSMode=nanos&TSMax=1000000" V1 API
The examples show how to use the different parameters for the uri endpoint.
Note : Replace the IP 127.0.0.1 with the host IP of your FMADIO device.
API v1 - Single
StreamName only.
Copy curl -u fmadio:xxxxx "http://127.0.0.1/api/v1/pcap/single?
StreamName=stream_test" StreamName and FilterBPF
Copy curl -u fmadio:xxxxx "http://127.0.0.1/api/v1/pcap/single?
StreamName=stream_test_001"
-G --data-urlencode "FilterBPF=tcp" StreamName and Compression
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/single?
StreamName=stream_test_001&
Compression=fast" StreamName , Compression and FilterBPF
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/single?
StreamName=stream_test_001&
Compression=fast"
-G --data-urlencode "FilterBPF=tcp" API v1 - SplitTime
StreamName , Start and Stop
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/splittime?
StreamName=stream_test_001&
Start=1530498788000000000&
Stop=1530498789000000000" StreamName , Start, Stop and FilterBPF
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/splittime?
StreamName=stream_test_001&
Start=1530498788000000000&
Stop=1530498789000000000"
-G --data-urlencode "FilterBPF=tcp" StreamName , Start, Stop, FilterBPF and Compression
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/splittime?
StreamName=stream_test_001&
Start=1530498788000000000&
Stop=1530498789000000000&
Compression=fast"
-G --data-urlencode "FilterBPF=tcp" StreamName , Start, Stop and Compression
Copy curl -u fmadio:xxxx"http://127.0.0.1/api/v1/pcap/splittime?
StreamName=stream_test_001&
Start=1530498788000000000&
Stop=1530498789000000000&
Compression=fast" API v1 - TimeRange
The Time Range function is very useful as the FMADIO system will work out which (or multiple) captures to check based on the Epoch Time stamp value.
TSBegin and TSEnd
Nanosecond Epoch selection
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1621772572136996000&
TSEnd=1621774913584264000" Second Epoch time Selection
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/timerange?
TSUnit=sec&
TSBegin=1621772572&
TSEnd=1621774913" Year Month Day Hour Min
Using the TSUnit option can use a more friendly time selection.
By default it uses the TimeZone configured on the system
Fetch PCAP from 3AM to 4AM on 2023 / 10 (October) / 1st
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/timerange?
TSUnit=YYYYMMDD_HHMMSS&
TSBegin=20231001_030000&
TSEnd=20231001_040000" Year Month Dat Hour Min with Timezone
Same as above but specifying the timezone.
NOTE: if using the full TSZone = Asia/Singapore for example, CURL will append a ? to the URL. Its recommended to use the City name only to avoid confusing CURL.
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/timerange?
TSUnit=YYYYMMDD_HHMMSS&
TSZone=Singapore&
TSBegin=20231001_030000&
TSEnd=20231001_040000" Year Month Day Hour Min Timzone and BPF Filter with De-encapsulation
Specifying all of the above with a BPF Filter, with BPF De-encapsulation enabled
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/timerange?
TSUnit=YYYYMMDD_HHMMSS&
TSZone=Singapore&
TSBegin=20231001_030000&
TSEnd=20231001_040000&
FilterBPFDecap=true&"
-G --data-urlencode "FilterBPF=icmp"
TSBegin , TSEnd and TSMax
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1621772572136996000&
TSEnd=1621774913584264000&
TSMax=100000" TSBegin , TSEnd and FilterBPF
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1621772572136996000&
TSEnd=1621774913584264000"
-G --data-urlencode "FilterBPF=tcp" TSBegin , TSEnd and Compression
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1621772572136996000&
TSEnd=1621774913584264000&
Compression=fast" TSBegin , TSEnd , FilterBPF and Compression
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1621772572136996000&
TSEnd=1621774913584264000&
Compression=fast"
-G --data-urlencode "FilterBPF=tcp" TSBegin , TSEnd , FilterBPF and FilterFrame
Frame Filters based on FMADIO Capture system
Filter based on FMADIO Capture port number
Copy curl "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1658744408270221800&
TSEnd=1658744501189259300&"
-G --data-urlencode "FilterFrame=capture.port==0"
| tcpdump -r - -nn
| head Filter based on multiple FMADIO Capture port numbers
Copy curl "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1658744408270221800&
TSEnd=1658744501189259300&"
-G --data-urlencode "FilterFrame=capture.port==0,1,2,3"
| tcpdump -r - -nn
| head Filter based on exclude FMADIO Capture port numbers
Copy curl "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1658744408270221800&
TSEnd=1658744501189259300&"
-G --data-urlencode "FilterFrame=capture.port!=0"
| tcpdump -r - -nn
| head Filter for a specific 7130 Device 54932 (any port)
Copy curl "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1658744408270221800&
TSEnd=1658744501189259300&"
-G --data-urlencode "FilterFrame=a7130.srcdevice==54932"
| tcpdump -r - -nn
| head Filter for everything except a specific 7130 Device (not device id 54932)
Copy curl "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1658744408270221800&
TSEnd=1658744501189259300&"
-G --data-urlencode "FilterFrame=a7130.srcdevice!=54932"
| tcpdump -r - -nn
| head Filter for a specific 7130 Port number 1
Copy curl "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1658744408270221800&
TSEnd=1658744501189259300&"
-G --data-urlencode "FilterFrame=a7130.srcport==1"
| tcpdump -r - -nn
| head
Filter for multiple 7130 Port numbers 1, 2, 3, 5, 10
Copy curl "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1658744408270221800&
TSEnd=1658744501189259300&"
-G --data-urlencode "FilterFrame=a7130.srcport==1,2,3,5,10"
| tcpdump -r - -nn
| head Filter for everything except 7130 Port number 10
Copy curl "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1658744408270221800&
TSEnd=1658744501189259300&"
-G --data-urlencode "FilterFrame=a7130.srcport!=10"
| tcpdump -r - -nn
| head Filter on a specific 7130 Port number and use the 7130 Footer Timestamp as the PCAP timestamp. Overriding the current TimeStamp setting
Copy curl "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1658744408270221800&
TSEnd=1658744501189259300&TSMode=arista7130"
-G --data-urlencode "FilterFrame=a7130.srcport!=10"
| tcpdump -r - -nn
| head Filter on a specific ingress port of the Cisco 3550, and use the Footer timestamp as the PCAP timestamp.
Copy curl "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1658744408270221800&
TSEnd=1658744501189259300&TSMode=cisco3550"
-G --data-urlencode "FilterFrame=c3550.srcport==48"
| tcpdump -r - -nn
| head Miscellaneous Examples
Encapsulation Debug
Many times the exact packet encapsulation is unclear, the following uses a wireshark filter expression to extract and show the full encapsulation format of the packet. From this a high speed BPF filter can be used to process the data.
In the below example we are using the Wireshark filter "ip.addr == 192.168.1.1" on a historical capture.
Copy curl -u fmadio:xxxx "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1666706401000000000&
TSEnd=1666706401010000000"
| tshark -r - -T fields -e frame.protocols -e ip.src -e ip.dst
-Y "ip.addr == 192.168.1.1"
Alternatively running on the currently running capture via SSH on the fmadio box looks like the following. This example filters on any UDP traffic.
Copy sudo stream_cat
| tshark -r - -T fields -e frame.protocols -e ip.src -e ip.dst -Y "udp"
| head The output looks like the following
Copy eth:ethertype:vlan:ethertype:ip:udp:ntp 106.10.186.200 192.168.133.10
eth:ethertype:vlan:ethertype:ip:udp:ntp 106.10.186.201 192.168.133.10
eth:ethertype:vlan:ethertype:ip:udp:ntp 167.172.70.21 192.168.133.10
eth:ethertype:vlan:ethertype:ip:udp:ntp 106.10.186.200 192.168.133.10
eth:ethertype:vlan:ethertype:ip:udp:ntp 106.10.186.201 192.168.133.10
eth:ethertype:vlan:ethertype:ip:udp:ntp 167.172.70.21 192.168.133.10
The above output shows there is a single VLAN tag in the packet. Making the equivalent BPF filter
With the final BPF filter using a CURL request
Copy curl -u fmadio:xxxxx "http://127.0.0.1/api/v1/pcap/timerange?
TSBegin=1671407102&
TSEnd=1671407752&
TSMode=sec&"
-G --data-urlencode "FilterBPF=vlan and udp"
| tcpdump -r - -n
| head Output per below
Copy 23:47:45.409489 IP 106.10.186.201.123 > 192.168.133.10.123: NTPv4, Server, length 48
23:52:14.407364 IP 167.172.70.21.123 > 192.168.133.10.123: NTPv4, Server, length 48
23:55:42.405072 IP 106.10.186.200.123 > 192.168.133.10.123: NTPv4, Server, length 48