We offer complete REST based API in FastNetMon Advanced.

API is disabled by default because it has blank password by default. You need to generate new password to enable it.

Generate secure password and specify it as API password:

sudo fcli set main web_api_login admin
sudo fcli set main web_api_password your_password_replace_it
sudo fcli set main web_api_port 10007
sudo fcli set main web_api_host 127.0.0.1

Optionally you can bind API daemon to IPv6 addresses that way:

sudo fcli set main web_api_host ::1

If you experience any issues, we suggest checking logs:

sudo tail -f /var/log/fastnetmon/api_gateway.log

You may enable detailed logging level this way:

sudo fcli set main web_api_trace_queries true
sudo fcli commit

sudo systemctl restart fastnetmon_web_api

After making this change you will see very detailed information about all actions in log file api_gateway.log.

Optionally you can enable SSL/TLS enabled endpoint on another port this way. You need to use your own SSL certificates created manually:

sudo fcli set main web_api_ssl true
sudo fcli set main web_api_ssl_host 127.0.0.1
sudo fcli set main web_api_ssl_port 10443
sudo fcli set main web_api_ssl_private_key_path /etc/ssl.key
sudo fcli set main web_api_ssl_certificate_path /etc/ssl.certificate

sudo systemctl restart fastnetmon_web_api

To listen on localhost and all external interfaces in same time you can set web_api_ssl_host to 0.0.0.0. For security reasons we recommend using only HTTPS enabled API port for external connections.

FastNetMon’s API does not provide fine grained permission control and we advice strongly against exposing it to non trusted systems / clients.

Execute example query to get license:

curl -X GET -u admin:YOU_PASSWORD http://127.0.0.1:10007/license

FastNetMon API based on well known fcli tool.

For debugging purposes, you could switch fcli to JSON mode this way:

JSON_MODE=on sudo -E fcli show bgp

It will provide same messages as API provides.

Instead of “set” command, you will need to use PUT HTTP method, for example (be careful, we use URL Encode for network name because it consists slash symbol):

curl -X PUT -u apiuser:securepass9 http://127.0.0.1:10007/main/networks_list/11.22.33.44%2f22

Instead of “delete” command you will need to use DELETE HTTP method, for example:

curl -X DELETE -u apiuser:securepass9 http://127.0.0.1:10007/main/networks_list/11.22.33.44%2f22

To show something, you could use GET HTTP method:

curl -X GET -u apiuser:securepass9 http://127.0.0.1:10007/hostgroup/global/threshold_mbps

To show whole category use:

curl -X GET -u apiuser:securepass9 http://127.0.0.1:10007/hostgroup

As you can see, in almost all cases you could replace space symbol by slash and use fcli’s format of command to talk with API.

If method failed for some reasons we return following document:

{"success":false,"error_text":"Category name hostgroupddd is not supported"}

If we command returns single value we return it in “value” field.

Example for boolean value:

curl -X GET -u apiuser:securepass9 http://127.0.0.1:10007/main/sflow
{"success":true,"error_text":"","value":true}

Example for string value:

curl -X GET -u apiuser:securepass9 http://127.0.0.1:10007/main/sflow_host
{"success":true,"error_text":"","value":"94.76.167.202"}

If command returns multiple elements, we return it in “values” field:

curl -X GET -u apiuser:securepass9 http://127.0.0.1:10007/main/sflow_ports
{"success":true,"error_text":"","values":["3432","6343"]}

If command returns hash map / table / dictionary FastNetMon encodes them as JSON dictionary:

curl -X GET -u apiuser:securepass9 http://127.0.0.1:10007/main/influxdb_tags_table
{"success":true,"error_text":"","table":{"ddd":"vvvv","foo":"bar"}}

If command returns document (hash map, dictionary) we return it in “object” field:

curl -X GET -u apiuser:securepass9 http://127.0.0.1:10007/bgp/connection_to_my_router
{"success":true,"error_text":"","values":[{"name":"connection_to_my_router","description":"","local_asn":65001,"local_address":"11.22.33.44","subnet_learning":false,"remote_asn":65001,"remote_address":"22.33.44.55","device_vendor":"","device_model":"","multihop":false,"md5_auth":true,"md5_auth_password":"suxx","snmp_address":"","snmp_version":"","snmp_community":"","ipv4_unicast":true,"ipv6_unicast":false,"ipv4_flowspec":true,"ipv6_flowspec":false,"ipv4_unicast_announces_limit":0,"ipv6_unicast_announces_limit":0,"ipv4_flowspec_announces_limit":0,"ipv6_flowspec_announces_limit":0,"active":true}]}

But we have some pretty complicated examples, for example for blackhole announces:

curl -X GET -u apiuser:securepass9 http://127.0.0.1:10007/blackhole
{"success":true,"values":[{"uuid":"6575af53-301a-4dae-ab9d-7e89c2a1fada","ip":"127.0.0.1/32"},{"uuid":"22965d4e-83b0-42c0-a442-848cd80a9ca7","ip":"127.0.0.2/32"}]}

Or flow spec announces:

curl -X GET -u apiuser:securepass9 http://127.0.0.1:10007/flowspec
{"success":true,"values":[{"uuid":"00fde1c5-bce4-4752-9d08-4e5be115e1c0","announce":{"source_prefix":"4.0.0.0/32","destination_prefix":"127.0.0.0/32","destination_ports":[80],"source_ports":[53,5353],"packet_lengths":[777,1122],"protocols":["tcp"],"fragmentation_flags":["is-fragment","dont-fragment"],"tcp_flags":["syn"],"action_type":"rate-limit","action":{"rate":1024}}},{"uuid":"7bc20126-ae1e-4e5b-8bc6-3493a55a0511","announce":{"source_prefix":"4.0.0.0/32","destination_prefix":"127.0.0.0/32","destination_ports":[80],"source_ports":[53,5353],"packet_lengths":[777,444],"protocols":["tcp"],"fragmentation_flags":["is-fragment","dont-fragment"],"tcp_flags":["syn"],"action_type":"rate-limit","action":{"rate":1024}}}]}

To put blackhole host, use this:

curl -X PUT -u admin:securepass9 http://127.0.0.1:10007/blackhole/127.0.0.1

After making any changes, you have to trigger commit command to apply changes for FastNetMon’s engine:

curl -X PUT -u admin:securepass9 http://127.0.0.1:10007/commit

Complete example to ban and then unban host

Ban it:

curl -X PUT -u admin:securepass9 http://127.0.0.1:10007/blackhole/127.0.0.1

Check list of banned hosts:

curl -X GET -u admin:securepass9 http://127.0.0.1:10007/blackhole

Output:

{"success":true,"values":[{"uuid":"a1080f8f-46bb-4fcf-932c-5cc837105589","ip":"127.0.0.1/32"}]}

And finally unban it by UUID:

curl -X DELETE -u admin:securepass9 http://127.0.0.1:10007/blackhole/a1080f8f-46bb-4fcf-932c-5cc837105589

Some some command which expect large JSON documents you may pass JSON documents as part of JSON query:

curl -vv -X PUT -u admin:securepass9 http://127.0.0.1:10007/flowspec  -H "Content-Type: application/json" -d '{"source_prefix":"11.22.33.44/32", "destination_prefix":"11.22.33.44/32", "action_type":"discard"}'

Starting from FastNetMon 2.0.332 you can use single large JSON document to create new hostgroup or completely overwrite configuration for existing hostgroup.

The easiest way to get all field names to manually create hostgroup via fcli and then get JSON output from it this way:

JSON_MODE=on sudo -E fcli show hostgroup servers

You will see document like this:

{
"success":true,
"error_text":"",
"values":[ {
"name":"servers",
"parent_name":"",
"description":"",
"calculation_method":"per_host",
"enable_ban":false,
"ban_for_pps":false,
"ban_for_bandwidth":false,
"ban_for_flows":false,
"threshold_pps":0,
"threshold_mbps":0,
"threshold_flows":0,
"ban_for_tcp_bandwidth":false,
"ban_for_udp_bandwidth":false,
"ban_for_icmp_bandwidth":false,
"ban_for_tcp_pps":false,
"ban_for_udp_pps":false,
"ban_for_icmp_pps":false,
"threshold_tcp_mbps":0,
"threshold_udp_mbps":0,
"threshold_icmp_mbps":0,
"threshold_tcp_pps":0,
"threshold_udp_pps":0,
"threshold_icmp_pps":0,
"ban_for_tcp_syn_pps":false,
"threshold_tcp_syn_pps":0,
"ban_for_tcp_syn_bandwidth":false,
"threshold_tcp_syn_mbps":0,
"ban_for_ip_fragments_pps":false,
"threshold_ip_fragments_pps":0,
"ban_for_ip_fragments_bandwidth":false,
"threshold_ip_fragments_mbps":0,
"enable_ban_incoming":false,
"enable_ban_outgoing":false,
"ban_for_pps_outgoing":false,
"ban_for_bandwidth_outgoing":false,
"ban_for_flows_outgoing":false,
"threshold_pps_outgoing":0,
"threshold_mbps_outgoing":0,
"threshold_flows_outgoing":0,
"ban_for_tcp_bandwidth_outgoing":false,
"ban_for_udp_bandwidth_outgoing":false,
"ban_for_icmp_bandwidth_outgoing":false,
"ban_for_tcp_pps_outgoing":false,
"ban_for_udp_pps_outgoing":false,
"ban_for_icmp_pps_outgoing":false,
"threshold_tcp_mbps_outgoing":0,
"threshold_udp_mbps_outgoing":0,
"threshold_icmp_mbps_outgoing":0,
"threshold_tcp_pps_outgoing":0,
"threshold_udp_pps_outgoing":0,
"threshold_icmp_pps_outgoing":0,
"ban_for_tcp_syn_pps_outgoing":false,
"threshold_tcp_syn_pps_outgoing":0,
"ban_for_tcp_syn_bandwidth_outgoing":false,
"threshold_tcp_syn_mbps_outgoing":0,
"ban_for_ip_fragments_pps_outgoing":false,
"threshold_ip_fragments_pps_outgoing":0,
"ban_for_ip_fragments_bandwidth_outgoing":false,
"threshold_ip_fragments_mbps_outgoing":0
} ] }

You need to use first element from array values to get whole document which describes hostgroup. Then you need to adjust required fields and pass them via API using PUT method to main hostgroup endpoint (/hostgroup) this way:

curl -vv -X PUT -u admin:securepass9 http://127.0.0.1:10007/hostgroup -H "Content-Type: application/json"  -d '{"name":"servers","parent_name":"","description":"","calculation_method":"per_host","enable_ban":false,"ban_for_pps":false,"ban_for_bandwidth":false,"ban_for_flows":false,"threshold_pps":0,"threshold_mbps":0,"threshold_flows":0,"ban_for_tcp_bandwidth":false,"ban_for_udp_bandwidth":false,"ban_for_icmp_bandwidth":false,"ban_for_tcp_pps":false,"ban_for_udp_pps":false,"ban_for_icmp_pps":false,"threshold_tcp_mbps":0,"threshold_udp_mbps":0,"threshold_icmp_mbps":0,"threshold_tcp_pps":0,"threshold_udp_pps":0,"threshold_icmp_pps":0,"ban_for_tcp_syn_pps":false,"threshold_tcp_syn_pps":0,"ban_for_tcp_syn_bandwidth":false,"threshold_tcp_syn_mbps":0,"ban_for_ip_fragments_pps":false,"threshold_ip_fragments_pps":0,"ban_for_ip_fragments_bandwidth":false,"threshold_ip_fragments_mbps":0,"enable_ban_incoming":false,"enable_ban_outgoing":false,"ban_for_pps_outgoing":false,"ban_for_bandwidth_outgoing":false,"ban_for_flows_outgoing":false,"threshold_pps_outgoing":0,"threshold_mbps_outgoing":0,"threshold_flows_outgoing":0,"ban_for_tcp_bandwidth_outgoing":false,"ban_for_udp_bandwidth_outgoing":false,"ban_for_icmp_bandwidth_outgoing":false,"ban_for_tcp_pps_outgoing":false,"ban_for_udp_pps_outgoing":false,"ban_for_icmp_pps_outgoing":false,"threshold_tcp_mbps_outgoing":0,"threshold_udp_mbps_outgoing":0,"threshold_icmp_mbps_outgoing":0,"threshold_tcp_pps_outgoing":0,"threshold_udp_pps_outgoing":0,"threshold_icmp_pps_outgoing":0,"ban_for_tcp_syn_pps_outgoing":false,"threshold_tcp_syn_pps_outgoing":0,"ban_for_tcp_syn_bandwidth_outgoing":false,"threshold_tcp_syn_mbps_outgoing":0,"ban_for_ip_fragments_pps_outgoing":false,"threshold_ip_fragments_pps_outgoing":0,"ban_for_ip_fragments_bandwidth_outgoing":true,"threshold_ip_fragments_mbps_outgoing":12345}'

You can create new hostgroup by setting field “name” to name of new hostgroup.

Starting from 2.0.360 you can control number of entries returned by API calls asn_counters_v4, asn_counters_v6, host_counters_v6, host_counters, host_counters_per_hostgroup_v4, host_counters_per_hostgroup_v6, remote_host_counters using query parameter max_elements

curl -s -X GET -u admin:your_password_replace_it http://[::1]:10007/asn_counters_v4/outgoing?max_elements=50

Examples

We have number of example tools implemented for our API to provide examples:

  • API client which creates and removes networks from FastNetMon
  • API client which can block and unblock IP address

Technical details

FastNetMon REST API is implemented as gateway which accepts HTTP / HTTPS queries from end client and then reaches FastNetMon daemon using internal non public gRPC based API (which listens TCP port 50052 by default ) to execute command. For configuration management commands REST API reached MongoDB or FerretDB directly.

In case of FastNetMon daemon reachability issues you will see following error:

Show function returned error: XXX call failed: rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing dial tcp 127.0.0.1:50052: connect: connection refused"

24/7 Tech Support

support@fastnetmon.com

Email Us

sales@fastnetmon.com