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.