2.1. Hosts API

The Hosts API exposes functions to query and manage active ntopng hosts.

Functions

function getHostsInfo(bool show_details = true, string sortColumn = "column_ip", int maxHits = 32768, int toSkip = 0, bool a2zSortOrder = true, string country = nil, string os_filter = nil, int vlan_filter = nil, int asn_filter = nil, int network_filter = nil, string mac_filter = nil, int pool_filter = nil, int ipver_filter = nil, int proto_filter = nil, bool filtered_hosts = false, bool blacklisted_hosts = false, bool hide_top_hidden = false)

Get active hosts information.

Return
a table (numHosts, nextSlot, hosts) where hosts is a table (hostkey -> hostinfo) on success, nil on error.
Note
it’s better to use the more efficient helper callback_utils.foreachHost for generic hosts iteration.
Parameters
  • show_details: enable extended information.
  • 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.
  • country: filter hosts by country code.
  • os_filter: filter hosts by os code.
  • vlan_filter: filter hosts by vlan ID.
  • asn_filter: filter hosts by ASN filter.
  • network_filter: filter hosts by local network id.
  • mac_filter: filter hosts by MAC address.
  • pool_filter: filter hosts by host pool ID.
  • ipver_filter: filter hosts by IP version, must be 4 or 6.
  • proto_filter: filter hosts by nDPI protocol ID.
  • filtered_hosts: if true, only return hosts with blocked flows.
  • blacklisted_hosts: if true, only return blacklisted hosts.
  • hide_top_hidden: if true, avoid returning hosts marked as “top hidden”.

function getLocalHostsInfo(...)

Get active local hosts information. See getHostsInfo for parameters description.

Note
it’s better to use the more efficient helper callback_utils.foreachLocalHost for generic hosts iteration.

function getRemoteHostsInfo(...)

Get active remote hosts information. See getHostsInfo for parameters description.

function getGroupedHosts(bool show_details = true, string groupBy = "column_ip", string country = nil, string os_filter = nil, int vlan_filter = nil, int asn_filter = nil, int network_filter = nil, int pool_filter = nil, int ipver_filter = nil)

Group active hosts by a specific criteria.

Return
table with grouped host information on success, nil otherwise.
Parameters
  • show_details: enable extended information.
  • groupBy: the group criteria.
  • country: filter hosts by country code.
  • os_filter: filter hosts by os code.
  • vlan_filter: filter hosts by vlan ID.
  • asn_filter: filter hosts by ASN filter.
  • network_filter: filter hosts by local network id.
  • pool_filter: filter hosts by host pool ID.
  • ipver_filter: filter hosts by IP version, must be 4 or 6.

function getHostInfo(string host_ip, int vlan_id = nil)

Get host information.

Return
table with host information on success, nil otherwise.
Parameters
  • host_ip: host/host@vlan.
  • vlan_id: specify the host_ip vlan separately.

function getHostCountry(string host_ip)

Get host country.

Return
the host country code on success, nil otherwise.
Parameters
  • host_ip: host/host@vlan.

function findHost(string query)

Search hosts by name, ip or other information.

Return
the found hosts information on success, nil otherwise.
Parameters
  • query: the string to use.

function findHostByMac(string mac)

Search hosts by MAC address.

Return
the found hosts information on success, nil otherwise.
Parameters
  • mac: the mac address filter.