2.4. MACs API

The MACs API exposes functions to query and manage ntopng L2 devices.

Functions

function getMacsInfo(string sortColumn = "column_mac", int maxHits = 32768, int toSkip = 0, bool a2zSortOrder = true, sourceMacsOnly = false, string manufacturer = nil, int pool_filter = nil, int devtype_filter = nil, string location_filter = nil, bool dhcpMacsOnly = false)

Retrieve active L2 devices information.

Return
a table (numMacs, nextSlot, macs) on success, nil otherwise.
Note
it’s better to use the more efficient helper callback_utils.getDevicesIterator for generic devices iteration.
Parameters
  • sortColumn: column to use for sorting.
  • maxHits: maximum number of returned items.
  • toSkip: number of initial items to skip after sorting.
  • a2zSortOrder: if true, enable ascending sort order, otherwise order is descending.
  • sourceMacsOnly: if true, only sender devices will be returned.
  • manufacturer: filter by device manufacturer.
  • pool_filter: filter by host pool ID.
  • devtype_filter: filter by device type.
  • location_filter: filter by device location, “lan” or “wan”.
  • dhcpMacsOnly: if true, only devices which made DHCP requests will be returned.

function getMacInfo(string mac)

Retrieve information about a specific L2 device.

Return
device information on success, nil otherwise.
Parameters
  • mac: the mac to query information for.

function getMacManufacturers(int maxHits = 32768, bool sourceMacsOnly = false, int devtype_filter = nil, string location_filter = nil, bool dhcpMacsOnly = false)

Get a list of MAC manufacturers from active devices.

Return
table (manufacturer -> num_active_devices) on success, nil otherwise.
Parameters
  • maxHits: maximum number of returned items.
  • sourceMacsOnly: if true, only sender devices will be returned.
  • devtype_filter: filter by device type.
  • location_filter: filter by device location, “lan” or “wan”.
  • dhcpMacsOnly: if true, only consider devices which made DHCP requests.

function setMacOperatingSystem(string mac, int os_id)

Set L2 device operating system.

Parameters
  • mac: device MAC address
  • os_id: the operating system id to set.

function setMacDeviceType(string mac, int device_type, bool overwrite)

Set L2 device type.

Parameters
  • mac: device MAC address
  • device_type: the device type id to set.
  • overwrite: if true, the existing device type, if any, will be overwritten.

function getMacDeviceTypes(int max_hits = 32768, bool sourceMacsOnly = false, string manufacturer = nil, string location_filter = nil, bool dhcpMacsOnly = false)

Get a list of device types from active devices.

Return
table (device_type -> num_active_devices) on success, nil otherwise.
Parameters
  • maxHits: maximum number of returned items.
  • sourceMacsOnly: if true, only sender devices will be return
  • manufacturer: filter by device manufacturer.ed.
  • location_filter: filter by device location, “lan” or “wan”.
  • dhcpMacsOnly: if true, only devices which made DHCP requests will be returned.

function findMacPool(string mac)

Get the pool of the specified L2 device. This also works for inactive devices. mac L2 device MAC address.

Return
the device pool id on success, nil otherwise.
Note
nil is also returned for devices which do not belong to any pool.