07.12.2017

FastNetMon Advanced API

We ship API capability in FastNetMon Advanced mainline distribution since since FastNetMon 2.0.58 and you have to execute few additional steps to enable API.

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 service fastnetmon_web_api restart

Also, for Ubuntu 16.04 or 18.04 you need following command to start API on machine boot:

sudo systemctl enable fastnetmon_web_api

If you experience any issues, we suggest checking logs:

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

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

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