This article describes how to retrieve useful device parameters like MAC address, IP address, vendor details, OS details, firmware version, etc of all the connected devices in the network in real-time from the FortiGate
Scope
FortiGate.
Solution
Retrieving information of devices connected at the present moment in the network would be useful for analysis while troubleshooting, or for monitoring in general. FortiGate provides a simple user interface to collect such information of devices connected in the network in real-time, both from GUI as well as from CLI (& API).
If FortiGate is used to manage FortiSwitches using FortiLink, then the FortiGate inventory list would have more information regarding the connected devices in the managed switch topology.
Device inventory list from FortiGate GUI: From the Dashboards > Users & Devices > Device Inventory shows the list of all connected devices in the network. This inventory list can be filtered to search for any specific device by any of the available parameters like IP address, MAC address, device OS type, connected FortiSwitch ports, etc. The link below illustrates the GUI device inventory feature in FortiGate with examples: Device inventory
Device inventory list from FortiGate CLI: The device inventory list can also be retrieved using the CLI command ‘diagnose user device list’, which prints useful device parameters of all connected devices in the network.
Example:
FortiGate-1# diagnose user device list hosts vd root/0 s3:1c:ge:62:bc:05 gen 2 req OHUA/3c created 2s gen 1 seen 2s port1 gen 1 ip 192.168.10.1 src lldp hardware vendor 'Fortinet' src lldp id 1467 weight 255 type 'Network Generic' src lldp id 1467 weight 255 family 'FortiSwitch' src lldp id 1467 weight 255 os 'FortiSwitch OS' src lldp id 1467 weight 255 hardware version '1048D' src lldp id 1467 weight 255 software version '6.4.9 Build xyz' src lldp id 1467 weight 255 host 'FortiSwitch-2' src lldp <--------- This device information was learnt using lldp vd root/0 s3:1c:ge:62:bc:06 gen 2294807 req OUA/34 created 11416690s gen 81 seen 0s VMware-vlan gen 838876 ip 192.168.10.2 src arp hardware vendor 'Cavium' src fortiguard id 0 weight 129 type 'Home & Office' src fortiguard id 0 weight 129 family 'Computer' src fortiguard id 0 weight 129 os 'Windows' src http id 1453 weight 130 software version '10' src http id 0 weight 130 host 'Windows-1' src mwbs vd root/0 s3:1c:ge:62:bc:07 gen 229201159 req OUA/34 created 11412874s gen 1415 seen 1s VMware-vlan gen 82611 ip 192.168.10.3 src tcp hardware vendor 'Cavium' src fortiguard id 0 weight 84 type 'Home & Office' src fortiguard id 0 weight 84 family 'Computer' src fortiguard id 0 weight 84 os 'Windows' src http id 1444 weight 130 software version '10' src http id 0 weight 130 host 'Vmware-server-1' src dns vd root/0 s3:1c:ge:62:bc:08 gen 229181172 req OUA/34 created 1765267s gen 229179815 seen 1670422s Wireless-vlan gen 829841 ip 192.168.10.4 src arp hardware vendor 'Samsung' src dhcp id 133 weight 255 type 'Phone' src dhcp id 133 weight 255 family 'Galaxy' src dhcp id 133 weight 255 os 'Android' src dhcp id 133 weight 255 hardware version 'A5-2017' src dhcp id 182 weight 232 software version '8.0.0' src dhcp id 133 weight 255 host 'Galaxy-2' src dhcp vd root/0 s3:1c:ge:62:bc:09 gen 229053181 req HU/18 created 29828439s gen 637 seen 0s fortilink gen 756681 vd root/0 s3:1c:ge:62:bc:10 gen 229075579 req OA/24 created 8419753s gen 229075368 seen 0s Wireless-vlan gen 771223 ip 192.168.10.6 src mac os 'Windows' src http id 1077 weight 130 software version '10' src http id 1453 weight 130 host 'Bob-workstation' src dhcp user 'Bob' src kerberos vd root/0 s3:1c:ge:62:bc:15 gen 229052362 req OUA/34 created 11416699s gen 1680 seen 0s Wireless-vlan gen 756043 ip 192.168.10.7 src mac hardware vendor 'Fortinet' src lldp id 1478 weight 255 type 'Network Generic' src lldp id 1478 weight 255 family 'FortiAP' src lldp id 1478 weight 255 os 'FortiAP OS' src lldp id 1478 weight 255 hardware version '231F' src lldp id 1478 weight 255 software version '6.4 Build xyz' src lldp id 1478 weight 255 host 'Forti-AP-1' src lldp . . .
Note: Some of the outputs in the above output like ip/mac/hostname etc are sanitized
Here is a table for reference that describes the available device parameters.
Device parameter Description
vd root/0 This device entry is associated with Vdom ‘root’.
<e8:1d:ba:73:cb:14> MAC address of the device.
created How long ago was the device entry first created.
seen The device was last seen.
<port/vlan> The port or VLAN on which this device was detected.
src The source protocols the FortiGate used to learn the device parameters for this specific device, which can be lldp, arp, mac, dhcp, kerberos, dns, etc..
IP IP address of the device.
hardware vendor hardware vendor of the device.
type Type of device – network or user.
family device family category – switch or AP or phones, etc.
os The OS detected on the device.
hardware version Hardware model details of the device.
software version software/firmware version detected on the device.
host The hostname of the device.
Export the device inventory list in JSON format using API: FortiGate API calls can be used to extract the device inventory list in JSON format, here is an example of an API call for this requirement. First, create a REST API Admin account on FortiGate using the instructions in this document and obtain the API access token that we will use to send the API call in the next step: Generating an API token on FortiGate
Using the API token/access token that was generated, send the API GET request to retrieve the device inventory list from the FortiGate (an API agent like Postman or curl can be used).
GET Request URL: https://172.16.10.1:443/api/v2/monitor/user/device/query?access_token=your-token-here
Curl example:
curl -X GET "https://172.16.10.1:443/api/v2/monitor/user/device/query?access_token=your-token-here" -H "accept: application/json"
Response:
{
"http_method": "GET",
"results": [
{
"ipv4_address": "192.168.20.4",
"mac": "s3:1c:ge:62:bc:05",
"hardware_vendor": "Fortinet",
"hardware_version": "1048D",
"hardware_type": "Network Generic",
"hardware_family": "FortiSwitch",
"vdom": "root",
"os_name": "FortiSwitch OS",
"os_version": "7.0.5 Build xyz",
"hostname": "FortiSwitch-8",
"last_seen": 1721681857,
"host_src": "lldp",
"unjoined_forticlient_endpoint": false,
"is_online": true,
"active_start_time": 1721409964,
"is_fortiguard_src": false,
"master_mac": "s3:1c:ge:62:bc:05",
"detected_interface": "port1",
"is_master_device": true,
"is_detected_interface_role_wan": false,
"detected_interface_fortitelemetry": true,
"online_interfaces": [
"port1"
<snippet>
]
}
],
"vdom": "root",
"query_type": "memory",
"count": 74,
"total": 74,
"start": 0,
"number": 0,
"status": "success",
"serial": "FG-ABCDEFGHIJK",
"version": "v7.0.14",
"build": xyz
}
Common issues and recommendations:
Here are a few issues commonly seen with device inventory in FortiGate, and the remedies/recommendations:
- Device Inventory in FortiGate GUI and ‘diagnose user device list’ both do not show any devices or are incomplete: Check if device detection is enabled on the Fortigate LAN interfaces. If it is disabled, FortiGate will not be able to collect this information. This can be enabled either from Network -> Interfaces -> port<number> -> device detection -> enable or using CLI under the corresponding interface config ‘set device-identification enable’.
- Device inventory is missing some connected devices: To enhance this list further, in a managed FortiSwitch deployment, it is possible to collect additional information on devices connected in the network by using the network-monitoring option as illustrated below.
FortiGate-1 # config switch-controller network-monitor-settings set network-monitoring enable end