|
REST API is used by FortiNAC as a method for performing both polling (learning the connected endpoints and location) and applying control by changing the VLAN on the port. The API key allows FortiNAC to bypass the need to authenticate to FortiGate every time it connects. This improves performance when collecting results or applying changes on ports.
 Figure 1. Network diagram of Endpoint Management by FortiNAC in a FortiLink scenario.
Technical Tip: How to configure & use API token to communicate with FortiGate shows how to configure the REST API for FortiGate communication.
REST API access is used for the following functions:
- L2 polling - FortiNAC reads the MAC address table by sending REST API 'GET' method request.
- L3 polling - FortiNAC reads the ARP table by sending REST API 'GET' method request.
- Reading VLANs by sending REST API 'GET' method requests.
- Switching VLANs by sending REST API 'PUT' method request.
In this example, there is a Host connected to Port1 of a FortiSwitch in FortiLink Mode.
To investigate these scenarios, it is required to initially enable rest API logs in FortiGate. This is done through the CLI:
config log setting
set rest-api-set enable
set rest-api-get enable
end
show log setting
config log setting
set rest-api-set enable
set rest-api-get enable
end
At this point, it is possible to see REST API event logs in the FortiGate GUI under Log & Report -> System Events -> Logs -> REST API Events.
For further details in logging, it is necessary to enable debugging in the CLI in both FortiGate and FortiNAC.
Enable FortiGate debugs in the CLI:
diagnose debug console timestamp enable
diagnose debug application httpsd -1
diagnose debug application nodejs -1
diagnose debug application flcfgd -1
diagnose debug application cu_acd -1
diagnose debug application fortilinkd -1
diagnose debug enable
Enable FortiNAC-F debugs in CLI:
execute enter-shell
logs
Device -ip X.X.X.X -setAttr -name DEBUG -value "ForwardingInterface TelnetServer" <- Replace X.X.X.X with the appropriate FortiGate IP.
nacdebug -name BridgeManager true
exit
diagnose tail -F output.master
In this example, the goal is to see the API traffic exchange and confirm that FortiNAC can learn the Host MAC address and its location, in addition to being able to change the VLAN on that port.
Example 1. Learn the Host connected to port1 of FortiSwitch (Visibility).
This can be tested by triggering a manual L2 poll from the FortiNAC GUI in the Polling Tab of the FortiGate. In FortiGate logs, filter for the FortiNAC REST API admin (NAC) to see the requests.
 Figure 2. Verifying a L2 poll from FortiNAC in FortiGate REST API logs
- Filtered FortiNAC debug output from the CLI:
yams INFO :: 2024-09-02 15:57:42:006 :: #883 :: pool-5-thread-3 request uri = https://10.10.10.1:443/api/v2/monitor/user/device/query
yams INFO :: 2024-09-02 15:57:42:804 :: #75 :: PollThread-trap5 com.bsc.forwarding.Fortigate endpoint json = {"port_name":"port1","vlan_id":60,"last_seen":30,"port_id":1,"switch_id":"S108EP5918010780","vdom":"root","mac":"00:0c:29:a2:08:37"}
yams INFO :: 2024-09-02 15:57:42:803 :: #75 :: PollThread-trap5 Fortigate.getClientByMac looking for client with mac 00:0C:29:A2:08:37
yams.BridgeManager INFO :: 2024-09-02 15:57:43:087 :: #75 :: BridgeManager.updateClient setting location of 00:0C:29:A2:08:37 with id 190 to fortiGateLab.fortilab.local:root:S108EP5918010780:port1 ifaceID = 495
- Filtered FortiGate debug output from the CLI:
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] fweb_debug_init[433] -- New GET request for "/api/v2/monitor/user/device/query" from "10.10.10.6:56654"
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] fweb_debug_init[435] -- User-Agent: "FortiNAC/8.7"
[node Web Authentication - 1725285462 info] - Request is authorized with API key/session key.
[node Web Request - 1725285462 info] - New GET reqest for "/api/v2/monitor/user/device/query" from "10.10.10.6:56654"
[node Web Request - 1725285462 info] - User-Agent: "FortiNAC/8.7"
[node Web Request - 1725285462 info] - Checking request content.
[node Web Request - 1725285462 info] - Setting forwarded VDOM header to "root"
[node Web Request - 1725285462 info] - Proxying HTTP/1.1 request to httpsd.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 warning] api_access_check_for_api_key[687] -- API Key request authorized for NAC from 10.10.10.6.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] endpoint_process_req_vdom[1024] -- new API request (action='query',path='user',name='device',vdom='root',user='NAC')
.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] fweb_debug_final[319] -- Completed GET request for "/api/v2/monitor/user/device/query" (HTTP 200)
[node Web Request - 1725285462 info] - Completed request for "/api/v2/monitor/user/device/query" (HTTP 200).
.
.
.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] fweb_debug_init[433] -- New GET request for "/api/v2/monitor/switch-controller/managed-switch/status" from "10.10.10.6:56668"
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] fweb_debug_init[435] -- User-Agent: "FortiNAC/8.7"
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] fweb_debug_init[437] -- Handler "api_monitor_v2-handler" assigned to request
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 warning] api_access_check_for_api_key[687] -- API Key request authorized for NAC from 10.10.10.6.
2024-09-02 15:57:42 [node Web Authentication - 1725285462 info] - Request is authorized with API key/session key.
.
.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] endpoint_process_req_vdom[1024] -- new API request (action='status',path='switch-controller',name='managed-switch',vdom='root',user='NAC')
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] emit_port_cache[296] -- Finding telemetry data for port1 with port number 0.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] emit_port_cache[296] -- Finding telemetry data for port2 with port number 1.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] emit_port_cache[296] -- Finding telemetry data for port3 with port number 2.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] emit_port_cache[296] -- Finding telemetry data for port4 with port number 3.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] emit_port_cache[296] -- Finding telemetry data for port5 with port number 4.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] emit_port_cache[296] -- Finding telemetry data for port6 with port number 5.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] emit_port_cache[296] -- Finding telemetry data for port7 with port number 6.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] emit_port_cache[296] -- Finding telemetry data for port8 with port number 7.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] emit_port_cache[296] -- Finding telemetry data for port9 with port number 8.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] emit_port_cache[296] -- Finding telemetry data for port10 with port number 9.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] endpoint_process_req_vdom[1030] -- completed API request (rss_pre=31040, rss_post=32380, rss_delta=1340)
.
.
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] fweb_debug_init[433] -- New GET request for "/api/v2/monitor/switch-controller/detected-device" from "10.10.10.6:56684"
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] fweb_debug_init[435] -- User-Agent: "FortiNAC/8.7"
2024-09-02 15:57:42 2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] fweb_debug_init[437] -- Handler "api_monitor_v2-handler" assigned to request
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] endpoint_process_req_vdom[1024] -- new API request (action='select',path='switch-controller',name='detected-device',vdom='root',user='NAC')
2024-09-02 15:57:42 01413.607 ==========================cuAcProcInputLocalMsg 6 1=========================
2024-09-02 15:57:42 01413.611 cuAcProcInputLocalMsg: 162 bytes read from /tmp/cuUtilSocket_visibility msg type 0x217
2024-09-02 15:57:42 01413.616 DAEMON HEX DUMP (0x7ffdd94aa3f0, 162) at (77,cuAcProcInputLocalMsg)
2024-09-02 15:57:42 01413.618 cuAcProcInputLocalMsg : client info filename /tmp/cu_sw_clientdbNx7R5g
2024-09-02 15:57:42 01413.621 CLIENT DB retrieval start for switch S108EP5918010780
2024-09-02 15:57:42 01413.624 CLIENT DB retrieval end for switch S108EP5918010780
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] endpoint_process_req_vdom[1030] -- completed API request (rss_pre=34308, rss_post=34308, rss_delta=0)
2024-09-02 15:57:42 [httpsd 2699 - 1725285462 info] fweb_debug_final[319] -- Completed GET request for "/api/v2/monitor/switch-controller/detected-device" (HTTP 200)
[node Web Request - 1725285463 info] - Completed request for "/api/v2/monitor/switch-controller/detected-device" (HTTP 200).
Example 2. Changing the VLAN on the port (control).
In this case, it is possible to change the VLAN on the FortiSwitch port from the FortiNAC GUI by right-clicking the port properties and applying a different VLAN.
FortiGate REST API logs on GUI will show the FortiSwitch SN and port where FNAC updated the resource using 'PUT method'.
 Figure 3. REST API logs showing FNAC applying a change on Port1 using "PUT" method.
- Filtered FortiNAC CLI output will show the following:
yams INFO :: 2024-09-02 16:02:29:881 :: #4666 :: https-jsse-nio-0.0.0.0-8443-exec-83 Fortigate.parseMSPortDB parsing port port1 on switch S108EP5918010780
yams INFO :: 2024-09-02 16:02:29:881 :: #4666 :: https-jsse-nio-0.0.0.0-8443-exec-83 parseMSPortDB returning 1
yams INFO :: 2024-09-02 16:02:29:881 :: #4666 :: https-jsse-nio-0.0.0.0-8443-exec-83 checkDebug checking value ForwardingInterface TelnetServer for element 10.10.10.1
yams INFO :: 2024-09-02 16:02:29:881 :: #4666 :: https-jsse-nio-0.0.0.0-8443-exec-83 Fortigate.switchPortVlan for element 10.10.10.1
yams INFO :: 2024-09-02 16:02:29:881 :: #4666 :: https-jsse-nio-0.0.0.0-8443-exec-83 Port dbid = 495, new vlan = 62
yams INFO :: 2024-09-02 16:02:29:881 :: #4666 :: https-jsse-nio-0.0.0.0-8443-exec-83 Fortigate.switchPortVlanMS_API for element 10.10.10.1
.
.
yams INFO :: 2024-09-02 16:02:29:883 :: #4666 :: https-jsse-nio-0.0.0.0-8443-exec-83 PUT uri = https://10.10.10.1:443/api/v2/cmdb/switch-controller/managed-switch/S108EP5918010780/ports/port1
yams INFO :: 2024-09-02 16:02:30:206 :: #4666 :: https-jsse-nio-0.0.0.0-8443-exec-83 login status = 200, response =
HttpResponseProxy{HTTP/1.1 200 OK [date: Mon, 02 Sep 2024 14:02:30 GMT, x-frame-options: SAMEORIGIN, content-security-policy: frame-ancestors 'self', x-xss-protection: 1; mode=block, cache-control: no-cache, must-revalidate, content-length: 417, content-type: application/json, Connection: keep-alive] ResponseEntityProxy{[Content-Type: application/json,Content-Length: 417,Chunked: false]}}
.
.
yams INFO :: 2024-09-02 16:02:30:276 :: #4666 :: https-jsse-nio-0.0.0.0-8443-exec-83 Fortigate.switchPortVlan returning true
yams INFO :: 2024-09-02 16:02:35:005 :: #883 :: pool-5-thread-3 checkDebug checking value ForwardingInterface TelnetServer for element 10.10.10.1
yams INFO :: 2024-09-02 16:02:35:005 :: #883 :: pool-5-thread-3 Fortigate.getArpCache sending new ARP from API,VPN,AP sources to merge
- Filtered FortiGate CLI output will show the following:
2024-09-02 16:02:30 2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] fweb_debug_init[433] -- New PUT request for "/api/v2/cmdb/switch-controller/managed-switch/S108EP5918010780/ports/port1" from "10.10.10.6:43406"
.
.
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] fweb_debug_init[435] -- User-Agent: "FortiNAC/8.7"
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] fweb_debug_init[437] -- Handler "api_cmdb_v2-handler" assigned to request
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 warning] api_access_check_for_api_key[687] -- API Key request authorized for NAC from 10.10.10.6.
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] api_store_parameter[323] -- add API parameter 'access_token' (type=string)
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] api_store_parameter[323] -- add API parameter 'vdom' (type=string)
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] api_store_parameter[323] -- add API parameter 'json' (type=object)
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] api_cmdb_request_init_by_path[1800] -- new CMDB query (path='switch-controller',name='managed-switch')
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] api_cmdb_request_init_by_path[1829] -- querying CMDB entry (mkey='S108EP5918010780')
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] api_cmdb_request_init_child[1881] -- new CMDB child query for 'switch-controller.managed-switch:ports'
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] api_cmdb_request_init_child[1919] -- querying CMDB child entry (mkey='port1')
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] handle_cli_req_v2[3288] -- new CMDB API request (vdom='root',user='NAC')
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 warning] _api_cmdb_v2_config[1344] -- found legacy 'json' parameter - feature is deprecated
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] _api_cmdb_v2_config[1419] -- editing CLI object (append=0, auto_key=0, path=switch-controller, name=managed-switch, mkey=S108EP5918010780, flags=0)
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] api_set_cmdb_attr[2417] -- 'vlan'
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] cmdb_save_with_children[280] -- appended main node (nret=0, is_new=0)
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] handle_cli_req_v2[3318] -- returning to original vdom "root"
2024-09-02 16:02:30 [httpsd 2727 - 1725285750 info] fweb_debug_final[319] -- Completed PUT request for "/api/v2/cmdb/switch-controller/managed-switch/S108EP5918010780/ports/port1" (HTTP 200)
[node Web Request - 1725285750 info] - Completed request for "/api/v2/cmdb/switch-controller/managed-switch/S108EP5918010780/ports/port1" (HTTP 200).
.
.
2024-09-02 16:02:31 502s:558ms:494us flcfg_cmf_upd_switch_port[385]:flcfg_cmf_upd_switch_port port1 Voice_VLAN native-vid=62
2024-09-02 16:02:31 502s:603ms:959us flcfg_cmdb_managedswitch_port_event_handler[732]:flcfg_cmdb_managedswitch_port_event_handler: flag set for S108EP5918010780 port port1
Disable debugging:
- FortiGate CLI:
diagnose debug disable
- FortiNAC-F CLI:
execute enter-shell
Device -ip X.X.X.X -delAttr -name DEBUG
nacdebug -name BridgeManager false
These examples showcase what to look for when investigating REST API Access when FortiNAC is requesting information or updating FortiGate resources. The same troubleshooting steps and debugs can be used in FortiGate when investigating interactions with other API Admins.
Related documents:
Technical Tip: How to create a REST API Admin user and assign it to an admin profile
Troubleshooting Tip: Rest-API response error codes
Enable FortiGate REST API logs
|
