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
Apply changes:
sudo systemctl restart fastnetmon_web_api
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.
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