vrr/ntopng

mirror of https://github.com/ntop/ntopng.git synced 2026-05-17 03:56:40 +00:00

Matteo Biscosi 7a731042b4 Removed site id from old code and added support to networks in site add/edit (#10322 )

2026-05-14 10:45:36 +00:00

42 KiB

Raw Permalink Blame History

ntopng Lua API Reference (`interface.*` bindings)

This document describes all C→Lua bindings exposed as interface.* functions via src/LuaEngineInterface.cpp. It is intended both for human developers writing Lua scripts and as a machine-readable reference for AI-assisted code generation (e.g. Claude Code in this repository).

How interface.* works
REST API development guide
Interface Selection & Identity
Interface Type & Capability Flags
Interface Statistics
Host Information
Flow Information
MAC Address Information
nDPI Protocol & Category
Alerts
SNMP & Flow Devices
Host Pools & Quotas
Network / AS / VLAN / Country Statistics
Service & Periodicity Maps
ACL Management
Network Discovery (mDNS / ARP / Ping)
Live Capture & PCAP
RRD Queue
ClickHouse
sFlow
eBPF / Containers
nEdge / L7 Shaping & Policy
RADIUS Accounting (nEdge)
Miscellaneous

1. How `interface.*` works

Selecting an interface first

All interface.* functions operate on the currently selected interface stored in the Lua VM state. You must call interface.select(ifid) before any other interface.* call — otherwise the VM uses a fallback interface (the first available).

-- Always select an interface first
local ifid = _GET["ifid"] or interface.getFirstInterfaceId()
interface.select(tostring(ifid))

C→Lua registration

Every Lua function in _ntop_interface_reg[] (bottom of src/LuaEngineInterface.cpp) follows this pattern:

// 1. Implement a static C function
static int ntop_my_function(lua_State* vm) {
    NetworkInterface* ntop_interface = getCurrentInterface(vm);
    if (!ntop_interface) return (CONST_LUA_ERROR);

    ntop_lua_check(vm, __FUNCTION__, 1, LUA_TSTRING);
    const char* arg = lua_tostring(vm, 1);

    lua_pushstring(vm, result);
    return CONST_LUA_OK;  // or CONST_LUA_ERROR
}

// 2. Register it
{ "myFunction", ntop_my_function },   // called as interface.myFunction(...)

Standard boilerplate (REST endpoints using interface.*)

local dirs = ntop.getDirs()
package.path = dirs.installdir .. "/scripts/lua/modules/?.lua;" .. package.path

require "lua_utils"
local json       = require("dkjson")
local rest_utils = require("rest_utils")

-- Select interface
local ifid = _GET["ifid"] or interface.getFirstInterfaceId()
interface.select(tostring(ifid))

2. REST API development guide

File location

REST endpoints live at:

scripts/lua/rest/v2/<method>/<resource>/<action>.lua

Examples:

scripts/lua/rest/v2/get/interface/data.lua
scripts/lua/rest/v2/get/host/data.lua
scripts/lua/rest/v2/get/flow/active.lua

Minimal REST endpoint template

-- scripts/lua/rest/v2/get/interface/my_endpoint.lua
local dirs = ntop.getDirs()
package.path = dirs.installdir .. "/scripts/lua/modules/?.lua;" .. package.path

require "lua_utils"
local json       = require("dkjson")
local rest_utils = require("rest_utils")

-- Auth check
if not isAdministratorOrPrintErr() then
  rest_utils.answer(rest_utils.consts.err.not_granted)
  return
end

-- Param validation
local ifid = _GET["ifid"]
if not ifid then
  rest_utils.answer(rest_utils.consts.err.invalid_args)
  return
end

-- Select interface and fetch data
interface.select(tostring(ifid))
local stats = interface.getStats()

rest_utils.answer(rest_utils.consts.success.ok, stats)

`rest_utils.consts` error table (most common)

Constant	HTTP code	Meaning
`success.ok`	200	OK
`err.not_granted`	401	Not authorized
`err.invalid_args`	400	Bad/missing params
`err.internal_error`	500	C-level error
`err.not_found`	404	Resource not found
`err.not_allowed`	405	Method not allowed

Common REST patterns

Pattern 1 — Return interface stats

interface.select(tostring(ifid))
local stats = interface.getStats()
rest_utils.answer(rest_utils.consts.success.ok, stats)

Pattern 2 — Return host info

interface.select(tostring(ifid))
local host = _GET["host"]
local vlan  = _GET["vlan"] or 0
local info  = interface.getHostInfo(host, vlan)
if not info then
  rest_utils.answer(rest_utils.consts.err.not_found)
  return
end
rest_utils.answer(rest_utils.consts.success.ok, info)

Pattern 3 — Paginated flow listing

interface.select(tostring(ifid))
local flows = interface.getFlowsInfo({
  currentPage  = tonumber(_GET["page"]) or 1,
  perPage      = tonumber(_GET["perPage"]) or 10,
  sortColumn   = _GET["sortColumn"] or "bytes",
  sortOrder    = _GET["sortOrder"] or "desc",
})
rest_utils.answer(rest_utils.consts.success.ok, flows)

Pattern 4 — nDPI stats for an interface

interface.select(tostring(ifid))
local ndpi = interface.getnDPIStats()
rest_utils.answer(rest_utils.consts.success.ok, ndpi)

3. Interface Selection & Identity

Lua call	Returns	Description
`interface.getIfNames([exclude_viewed])`	`table`	Returns a table mapping interface IDs (as string keys) to interface names. Pass `true` to exclude viewed sub-interfaces.
`interface.getFirstInterfaceId()`	`integer`	Returns the numeric ID of the first available network interface. Useful as a default when no `ifid` is supplied.
`interface.select(ifid)`	`nil`	Selects the active interface for all subsequent `interface.` calls in this Lua VM. `ifid` may be a number or string. Must be called before any other interface.* function.*
`interface.getId()`	`integer`	Returns the numeric ID of the currently selected interface.
`interface.getName()`	`string`	Returns the name (e.g. `"eth0"`) of the currently selected interface.
`interface.getMasterInterfaceId()`	`integer`	Returns the numeric ID of the parent (master) interface when this is a sub-interface.
`interface.isValidIfId(ifid)`	`boolean`	Returns `true` if the given interface ID or name corresponds to an existing, enabled interface.
`interface.getMaxIfSpeed([ifname_or_id])`	`integer`	Returns the configured maximum speed in bps. Defaults to the current interface if no argument given.
`interface.getEndpoint()`	`string`	Returns the capture endpoint/source string (e.g. `"eth0"`, `"tcp://127.0.0.1:1234"`).
`interface.getIfMac()`	`string`	Returns the hardware MAC address of the currently selected interface.
`interface.name2id(ifname)`	`integer`	Converts an interface name string to its numeric ID.

4. Interface Type & Capability Flags

Lua call	Returns	Description
`interface.isPacketInterface()`	`boolean`	`true` if this is a live packet-capture interface (not ZMQ/sFlow/eBPF).
`interface.isDiscoverableInterface()`	`boolean`	`true` if network discovery is supported on this interface.
`interface.isBridgeInterface()`	`boolean`	`true` if this interface is operating in nEdge bridge/inline mode.
`interface.isPcapDumpInterface()`	`boolean`	`true` if this is a PCAP replay/dump interface.
`interface.isDatabaseViewInterface()`	`boolean`	`true` if this is a ClickHouse/DB view interface.
`interface.isZMQInterface()`	`boolean`	`true` if this interface receives flows via ZMQ (nProbe integration).
`interface.isView()`	`boolean`	`true` if this is an aggregated view interface covering multiple sub-interfaces.
`interface.isViewed()`	`boolean`	`true` if this interface is aggregated by a view interface.
`interface.viewedBy()`	`integer`	Returns the ID of the view interface that aggregates this interface, or `nil`.
`interface.isLoopback()`	`boolean`	`true` if this is a loopback interface.
`interface.isRunning()`	`boolean`	`true` if the interface capture thread is currently running.
`interface.isIdle()`	`boolean`	`true` if the interface is idle (no recent traffic).
`interface.setInterfaceIdleState(is_idle)`	`nil`	Sets the idle state of the interface (used by management scripts).
`interface.isSubInterface()`	`boolean`	`true` if this is a disaggregated sub-interface.
`interface.isSyslogInterface()`	`boolean`	`true` if this interface receives syslog events.
`interface.hasVLANs()`	`boolean`	`true` if the interface has observed VLAN-tagged traffic.
`interface.hasEBPF()`	`boolean`	`true` if the interface has received eBPF process-level events.
`interface.hasExternalAlerts()`	`boolean`	`true` if the interface has received external (injected) alerts.

5. Interface Statistics

Lua call	Returns	Description
`interface.getStats()`	`table`	Returns comprehensive real-time statistics for the interface (bytes, packets, flows, hosts, drops, throughput, etc.).
`interface.getStatsUpdateFreq()`	`integer`	Returns the statistics update frequency in seconds for this interface.
`interface.getSecsToFirstData()`	`integer`	Returns seconds elapsed since the interface first received traffic.
`interface.updateDirectionStats()`	`nil`	Forces an update of per-direction (upload/download) statistics.
`interface.updateTopSites()`	`nil`	Triggers a refresh of the top-sites (popular domains) tracking.
`interface.getThroughput()`	`table`	Returns current throughput in bps and pps in both directions (`{"upload_bps":…, "download_bps":…, …}`).
`interface.getHashTablesStats()`	`table`	Returns size and usage statistics for the interface hash tables (hosts, flows, MACs, etc.).
`interface.getPeriodicActivitiesStats()`	`table`	Returns timing and execution statistics for all periodic scripts on this interface.
`interface.getQueuesStats()`	`table`	Returns enqueue/dequeue statistics for internal interface queues.
`interface.setPeriodicActivityProgress(activity, progress_pct)`	`nil`	Updates the completion percentage for a running periodic script (used internally by periodic scripts).
`interface.getActiveFlowsStats([params])`	`table`	Returns statistics on currently active flows grouped by various dimensions.
`interface.getLiveASNStats(asn)`	`table`	Returns live (real-time) traffic statistics for a specific ASN.
`interface.getAnomalies()`	`table`	Returns a table of currently active behavioral anomalies on this interface.
`interface.getScore()`	`table`	Returns the current alert score breakdown for this interface.
`interface.getProtocolFlowsStats()`	`table`	Returns per-L4-protocol flow and byte statistics.
`interface.getVLANFlowsStats()`	`table`	Returns per-VLAN flow and byte statistics.
`interface.resetCounters([only_drops])`	`nil`	Resets traffic counters for the interface. Pass `true` to reset only drop counters.
`interface.resetBroadcastDomains()`	`nil`	Resets all learned broadcast domain state for the interface.
`interface.incSyslogStats(stat_name, n)`	`nil`	Increments a named syslog processing statistics counter.

6. Host Information

Host counts

Lua call	Returns	Description
`interface.getNumHosts()`	`integer`	Total count of active hosts (local + remote).
`interface.getNumLocalHosts()`	`integer`	Count of currently active local hosts.
`interface.getNumLocalRxOnlyHosts()`	`integer`	Count of local hosts seen only in the receive direction.
`interface.getNumFlows()`	`integer`	Total count of active flows on this interface.

Host listing

Lua call	Returns	Description
`interface.getHostsInfo([params])`	`table`	Returns information for all hosts (local + remote) on the interface. `params` table supports: `currentPage`, `perPage`, `sortColumn`, `sortOrder`, `host`, `vlan`, `country`, `os`, `asn`, `vlan_id`, `pool`, `network`, `filter`.
`interface.getLocalHostsInfo([params])`	`table`	Returns information for local hosts only. Same `params` as `getHostsInfo`.
`interface.getLocalHostsInfoNoTX([params])`	`table`	Returns local hosts that have received but not sent any traffic.
`interface.getLocalHostsInfoNoTXTCP([params])`	`table`	Returns local hosts that have not sent any TCP traffic.
`interface.getRemoteHostsInfo([params])`	`table`	Returns information for remote (non-local) hosts only.
`interface.getRemoteHostsInfoNoTX([params])`	`table`	Returns remote hosts that have received but not sent any traffic.
`interface.getRemoteHostsInfoNoTXTCP([params])`	`table`	Returns remote hosts that have not sent any TCP traffic.
`interface.getRxOnlyHostsList()`	`table`	Returns hosts that have only been seen in the receive direction.
`interface.getBroadcastDomainHostsInfo([params])`	`table`	Returns hosts that are part of broadcast domains on this interface.
`interface.getBroadcastMulticastHostsInfo([params])`	`table`	Returns broadcast/multicast group hosts on this interface.
`interface.getPublicHostsInfo([params])`	`table`	Returns hosts with public (routable) IP addresses.
`interface.getInterfaceHosts([include_details])`	`table`	Returns all active hosts as a flat array.
`interface.getBatchedHostsInfo(cursor, count)`	`table`	Returns a paginated batch of host records for all hosts.
`interface.getBatchedLocalHostsInfo(cursor, count)`	`table`	Returns a paginated batch of local host records.
`interface.getBatchedRemoteHostsInfo(cursor, count)`	`table`	Returns a paginated batch of remote host records.
`interface.getBatchedLocalHostsTs(cursor, count)`	`table`	Returns a paginated batch of local host time-series data.

Single-host queries

Lua call	Returns	Description
`interface.isHostActive(host[,vlan])`	`boolean`	Returns `true` if the specified host is currently active.
`interface.getHostInfo(host[,vlan])`	`table`	Returns comprehensive information for a specific host (bytes, packets, flows, nDPI breakdown, alerts, score, etc.).
`interface.getHostMinInfo(host[,vlan])`	`table`	Returns minimal host info (bytes, packets, score) for lightweight polling.
`interface.getHostCountry(host[,vlan])`	`string`	Returns the 2-letter ISO country code for a host's IP via GeoIP.
`interface.findHost(host[,vlan])`	`table`	Finds a host by IP or name and returns its info, or `nil` if not active.
`interface.findHostByMac(mac)`	`table`	Finds a host by its MAC address and returns its info.
`interface.getHostAttributes(host, vlan)`	`table`	Returns classification attributes for a host (device type, OS, category).
`interface.getHostsByPort(port, proto)`	`table`	Returns hosts using the specified server port and transport protocol.
`interface.getHostsByService(service_name)`	`table`	Returns hosts using a specific application service.
`interface.getHostsPorts(params)`	`table`	Returns a list of server ports used by hosts on this interface.
`interface.getnDPIHostStats(host, vlan)`	`table`	Returns per-protocol nDPI traffic statistics for a specific host.
`interface.getAddressInfo(ip_or_name)`	`table`	Returns comprehensive address information (DNS, geolocation, ASN) for an IP or hostname.

Host modification

Lua call	Returns	Description
`interface.setHostOperatingSystem(host, vlan, os_id)`	`nil`	Overrides the detected operating system for a host.
`interface.setHostResolvedName(host, vlan, name)`	`nil`	Sets the resolved DNS name for a host.
`interface.resetHostStats(host, vlan)`	`nil`	Resets all traffic statistics for a specific host.
`interface.resetHostTopSites(host, vlan)`	`nil`	Resets the top-sites statistics for a specific host.
`interface.deleteHostData(host, vlan)`	`nil`	Permanently deletes all stored data for a specific host.
`interface.updateHostTrafficPolicy(host, vlan)`	`nil`	Forces a traffic policy refresh for a specific host.
`interface.reloadHostPrefs(host[,vlan])`	`nil`	Reloads per-host preference overrides from Redis for a specific host.
`interface.dropHostTraffic(host, vlan)`	`nil`	Marks all traffic for a host for dropping (nEdge inline mode).
`interface.addDataToLocalHostAssets(ip, data_table)`	`nil`	Adds asset attributes to a local host's discovery record.
`interface.removeDataFromLocalHostAssets(ip)`	`nil`	Removes a local host's asset discovery record.
`interface.addMacsIpAddresses()`	`nil`	Forces re-association of MAC addresses with their known IP addresses.

7. Flow Information

Flow listing & search

Lua call	Returns	Description
`interface.getFlowsInfo([params_table])`	`table`	Returns detailed information for all active flows. `params_table` supports `currentPage`, `perPage`, `sortColumn`, `sortOrder`, `host`, `vlan`, `application`, `category`, `l4proto`, `status`, `alert_type`, `traffic_type`.
`interface.getBatchedFlowsInfo(cursor, count[,filter])`	`table`	Returns a paginated batch of active flow records.
`interface.getGroupedFlows(params_table)`	`table`	Returns flows aggregated (grouped) by a specified key field.
`interface.getFlowsStats()`	`table`	Returns aggregate flow statistics counts for the interface.
`interface.getFlowsStatus()`	`table`	Returns flow status distribution (normal, warning, alert) for this interface.
`interface.getLocalServerPorts(proto)`	`table`	Returns server ports observed on local hosts for a given L4 protocol.
`interface.listHTTPhosts([filter])`	`table`	Returns a list of hosts with active HTTP/HTTPS flows.
`interface.findFlowByKeyAndHashId(key, hash_id)`	`table`	Finds and returns an active flow by its hash key and bucket ID.
`interface.findFlowByTuple(src_ip, src_port, dst_ip, dst_port, proto[,vlan])`	`table`	Finds and returns an active flow by its 5-tuple.
`interface.getFlowKey(src_ip, src_port, dst_ip, dst_port, proto[,vlan])`	`integer`	Computes the hash key for a flow 5-tuple.
`interface.findPidFlows(pid)`	`table`	Returns active flows associated with a specific process ID (eBPF).
`interface.findNameFlows(proc_name)`	`table`	Returns active flows associated with a process name (eBPF).

Flow manipulation

Lua call	Returns	Description
`interface.dropFlowTraffic(key, hash_id)`	`nil`	Marks a specific flow for traffic dropping (nEdge inline mode).
`interface.dropMultipleFlowsTraffic(flows_table)`	`nil`	Drops traffic for multiple flows at once (nEdge inline mode).
`interface.processFlow(flow_table)`	`nil`	Injects a flow record from ZMQ/sFlow into the interface for processing (non-nEdge).

ZMQ flow fields

Lua call	Returns	Description
`interface.getAllZMQFlowFieldDescr()`	`table`	Returns descriptions of all ZMQ flow template fields (non-nEdge).
`interface.getZMQFlowFieldDescr(field_id)`	`table`	Returns description of a specific ZMQ flow field (non-nEdge).

8. MAC Address Information

Lua call	Returns	Description
`interface.getActiveMacs([vlan_id])`	`table`	Returns currently active MAC addresses on the interface.
`interface.getMacsInfo([params])`	`table`	Returns detailed information for MAC addresses on the interface.
`interface.getBatchedMacsInfo(cursor, count)`	`table`	Returns a paginated batch of MAC address records.
`interface.isMacActive(mac)`	`boolean`	Returns `true` if the given MAC address is currently active.
`interface.getMacInfo(mac)`	`table`	Returns detailed information for a specific MAC address.
`interface.getMacHosts(mac)`	`table`	Returns all hosts associated with a given MAC address.
`interface.getMacManufacturers([params])`	`table`	Returns a grouped count of MAC addresses by their OUI manufacturer.
`interface.getMacDeviceTypes()`	`table`	Returns a mapping of MAC device type IDs to their names and counts.
`interface.isMulticastMac(mac)`	`boolean`	Returns `true` if the given MAC address is a multicast/broadcast address.
`interface.appendMacEvent(mac, event_type)`	`nil`	Appends a captive-portal event (login/logout) for a MAC address (nEdge).
`interface.findMacPool(mac)`	`integer`	Returns the host pool ID that a MAC address belongs to.
`interface.findMemberPool(host[,vlan])`	`integer`	Returns the host pool ID that a host belongs to.
`interface.resetMacStats(mac)`	`nil`	Resets all traffic statistics for a specific MAC address.
`interface.deleteMacData(mac)`	`nil`	Permanently deletes all stored data for a specific MAC address.

9. nDPI Protocol & Category

Protocol/category lookup

Lua call	Returns	Description
`interface.getnDPIProtocols([category_id])`	`table`	Returns all nDPI protocol IDs and names, optionally filtered by category.
`interface.getnDPICategories()`	`table`	Returns all nDPI category IDs and their names.
`interface.getnDPIProtoName(proto_id)`	`string`	Returns the human-readable name for an nDPI protocol ID.
`interface.getnDPIFullProtoName(proto_id)`	`string`	Returns the full hierarchical name (e.g. `'HTTP.Facebook'`) for an nDPI protocol.
`interface.getnDPIProtoId(proto_name)`	`integer`	Returns the nDPI protocol ID for a given protocol name string.
`interface.getnDPICategoryId(category_name)`	`integer`	Returns the nDPI category ID for a given category name string.
`interface.getnDPICategoryName(category_id)`	`string`	Returns the human-readable name for an nDPI category ID.
`interface.getnDPIProtoBreed(proto_id)`	`string`	Returns the nDPI breed (e.g. `'Safe'`, `'Unsafe'`) for a protocol.

Protocol traffic statistics

Lua call	Returns	Description
`interface.getnDPIFlowsCount()`	`table`	Returns per-protocol flow count statistics for this interface.
`interface.getnDPIStats([host,vlan])`	`table`	Returns per-protocol byte/flow statistics, optionally filtered to a specific host.
`interface.getnDPIHostStats(host, vlan)`	`table`	Returns per-protocol nDPI traffic statistics for a specific host.

nDPI data recording

Lua call	Returns	Description
`interface.dumpnDPIProtocolId(host, vlan, proto_id)`	`nil`	Records a protocol observation for a host to the nDPI dump table.
`interface.dumpnDPICategoryId(host, vlan, cat_id)`	`nil`	Records a category observation for a host to the nDPI dump table.

10. Alerts

Alert store queries

Lua call	Returns	Description
`interface.getAlerts(params_table)`	`table`	Returns alerts matching the given filter criteria. `params_table` supports `status` (`"engaged"`, `"past"`), `alert_type`, `alert_severity`, `entity`, `entity_val`, `page`, `perPage`, `order_by`.
`interface.getEngagedAlerts([params_table])`	`table`	Returns all currently engaged (active/unresolved) alerts for this interface.
`interface.alert_store_query(query[,limit_rows])`	`nil`	Executes a raw SQL query on the interface alert database and streams JSON to the HTTP response.

Alert lifecycle

Lua call	Returns	Description
`interface.storeTriggeredAlert(alert_table)`	`nil`	Stores a triggered alert record in the interface alert database.
`interface.releaseTriggeredAlert(alert_id)`	`nil`	Marks a triggered alert as resolved/released.
`interface.triggerExternalAlert(alert_table)`	`nil`	Stores an externally generated alert into the interface alert store.
`interface.releaseExternalAlert(alert_id)`	`nil`	Marks an external alert as resolved/released.
`interface.releaseEngagedAlerts(script_key, subtype, alert_type)`	`nil`	Bulk-releases engaged alerts matching a script key and type.
`interface.triggerTrafficAlert(params_table)`	`nil`	Triggers a traffic-threshold alert with configurable severity and details.

Alert context (script helpers)

Lua call	Returns	Description
`interface.getCachedAlertValue(key)`	`string`	Retrieves a cached alert context value by key for this interface.
`interface.setCachedAlertValue(key, value[, expiry])`	`nil`	Stores a cached alert context value for this interface.
`interface.checkContext(context_key)`	`nil`	Validates and initializes alert context for a script execution.

11. SNMP & Flow Devices

Lua call	Returns	Description
`interface.getSNMPStats()`	`table`	Returns SNMP-polled statistics for the current interface (Pro only).
`interface.getFlowDevices()`	`table`	Returns flow exporters (NetFlow/IPFIX probes) seen on this interface (Pro).
`interface.getFlowDeviceInfo(device_ip)`	`table`	Returns detailed information for a specific flow-exporting device (Pro).
`interface.getFlowDeviceInfoByIP(ip)`	`table`	Returns flow device information looked up by IP address (Pro).

12. Host Pools & Quotas

Lua call	Returns	Description
`interface.getHostPoolsInfo()`	`table`	Returns configuration and member counts for all host pools on this interface.
`interface.getHostPoolsStats()`	`table`	Returns traffic statistics for all host pools on this interface.
`interface.getHostPoolStats(pool_id)`	`table`	Returns traffic statistics for a specific host pool.
`interface.getHostUsedQuotasStats(host, vlan)`	`table`	Returns quota usage statistics for a specific host (nEdge Pro).
`interface.resetPoolsQuotas([pool_id])`	`nil`	Resets traffic quota counters for all or a specific host pool (nEdge Pro).
`interface.flushPoolDynamicBlacklist(pool_id)`	`nil`	Clears the dynamic blacklist for a host pool (nEdge Pro).
`interface.getPoolDynamicBlacklistStats(pool_id)`	`table`	Returns blacklist statistics for a host pool (nEdge Pro).
`interface.getPoolDynamicBlacklistMembers(pool_id)`	`table`	Returns the current dynamic blacklist members for a pool (nEdge Pro).

13. Network / AS / VLAN / Country Statistics

Networks

Lua call	Returns	Description
`interface.getNetworksStats()`	`table`	Returns per-local-network traffic statistics.
`interface.getNetworkStats(network_id)`	`table`	Returns traffic statistics for a specific local network by ID.

Autonomous Systems

Lua call	Returns	Description
`interface.getASesInfo([params])`	`table`	Returns statistics for all Autonomous Systems observed on this interface.
`interface.getASInfo(asn)`	`table`	Returns traffic statistics for a specific Autonomous System number.
`interface.aggregateASNFlows()`	`nil`	Triggers aggregation of flows by Autonomous System Number.
`interface.aggregateSiteFlows()`	`nil`	Triggers aggregation of flows by site/organization (Pro).

VLANs

Lua call	Returns	Description
`interface.getVLANsList()`	`table`	Returns a list of VLAN IDs seen on this interface.
`interface.getVLANsInfo([params])`	`table`	Returns per-VLAN traffic statistics for this interface.
`interface.getVLANInfo(vlan_id)`	`table`	Returns traffic statistics for a specific VLAN.

Countries

Lua call	Returns	Description
`interface.getCountriesInfo([params])`	`table`	Returns per-country traffic statistics observed on this interface.
`interface.getCountryInfo(country_code)`	`table`	Returns traffic statistics for a specific country on this interface.
`interface.convertCountryCode2U16(code)`	`integer`	Converts a 2-letter ISO country code string to a 16-bit integer.
`interface.convertCountryU162Code(n)`	`string`	Converts a 16-bit country integer back to its ISO country code string.

Observation Points

Lua call	Returns	Description
`interface.getObsPointsInfo([params])`	`table`	Returns statistics for all observation points seen on this interface.
`interface.getObsPointInfo(obs_point_id)`	`table`	Returns statistics for a specific observation point.
`interface.prepareDeleteObsPoint(obs_point_id)`	`nil`	Marks an observation point for deletion (first step of two-step delete).
`interface.deleteObsPoint(obs_point_id)`	`nil`	Completes deletion of a previously prepared observation point.

14. Service & Periodicity Maps

These functions are available in Pro/Enterprise editions with behavioral analysis enabled.

Lua call	Returns	Description
`interface.isBehaviourAnalysisAvailable()`	`boolean`	Returns `true` if behavioral analysis (periodicity/service maps) is available.
`interface.periodicityMap([params])`	`table`	Returns the periodicity map data for hosts and protocols on this interface.
`interface.flushPeriodicityMap()`	`nil`	Clears all learned periodicity map data for this interface.
`interface.periodicityMapFilterList()`	`table`	Returns available filter options for the periodicity map view.
`interface.serviceMap([params])`	`table`	Returns the service map data (host-to-service relationships) for this interface.
`interface.flushServiceMap()`	`nil`	Clears all learned service map data for this interface.
`interface.serviceMapFilterList()`	`table`	Returns available filter options for the service map view.
`interface.serviceMapLearningStatus()`	`table`	Returns whether the service map is in learning or enforcement mode.
`interface.serviceMapSetStatus(key, status)`	`nil`	Sets the learning/active status for a single service map entry.
`interface.serviceMapSetMultipleStatus(entries_table)`	`nil`	Sets status for multiple service map entries in a single call.

15. ACL Management

Lua call	Returns	Description
`interface.insertIPACL(cidr, is_allow)`	`nil`	Inserts an IP CIDR rule into the interface ACL. Pass `true` for allow, `false` for block.
`interface.removeIPACL(cidr)`	`nil`	Removes an IP CIDR rule from the interface ACL.
`interface.insertMacACL(mac, is_allow)`	`nil`	Inserts a MAC address rule into the interface ACL.
`interface.removeMacACL(mac)`	`nil`	Removes a MAC address rule from the interface ACL.
`interface.getACLInfo()`	`table`	Returns the current IP and MAC ACL rules for this interface.

16. Network Discovery (mDNS / ARP / Ping)

Lua call	Returns	Description
`interface.discoverHosts(timeout_ms)`	`table`	Triggers active host discovery (ping sweep) on the interface.
`interface.arpScanHosts()`	`table`	Triggers ARP scan discovery of hosts on the interface.
`interface.mdnsQueueAnyQuery(service_type)`	`nil`	Queues an mDNS ANY query for a service type for background resolution.
`interface.mdnsQueueNameToResolve(name)`	`nil`	Queues an mDNS/Bonjour name resolution request.
`interface.mdnsReadQueuedResponses()`	`table`	Reads and returns pending mDNS resolution results.

17. Live Capture & PCAP

Lua call	Returns	Description
`interface.liveCapture(params_table)`	`table`	Starts a live packet capture session on the interface; returns session info.
`interface.stopLiveCapture(capture_id)`	`nil`	Stops a running live capture session by its ID.
`interface.dumpLiveCaptures()`	`table`	Returns a table listing active live-capture sessions on this interface.
`interface.captureToPcap(params_table)`	`nil`	Starts a PCAP file capture session with BPF filter and duration.
`interface.isCaptureRunning()`	`boolean`	Returns `true` if a PCAP file capture session is currently active.
`interface.stopRunningCapture()`	`nil`	Stops the currently running PCAP file capture session.

18. RRD Queue

The RRD queue is used by periodic scripts to asynchronously persist time-series data.

Lua call	Returns	Description
`interface.rrd_enqueue(rrd_path, value, step)`	`nil`	Enqueues an RRD update for background writing.
`interface.rrd_dequeue()`	`table`	Dequeues a pending RRD update task.
`interface.rrd_queue_length()`	`integer`	Returns the number of pending items in the RRD update queue.
`interface.appendInfluxDB(json_points)`	`nil`	Appends time-series data points to the InfluxDB write queue.

19. ClickHouse

Available in Enterprise/Pro editions with ClickHouse integration enabled.

Lua call	Returns	Description
`interface.clickhouseExecCSVQuery(sql)`	`nil`	Executes a ClickHouse SQL query and streams CSV results to the HTTP response.
`interface.clickhouseArchiveData()`	`nil`	Triggers archival of old interface data to ClickHouse storage.
`interface.execSQLWrite(sql)`	`nil`	Executes a SQL write statement on the ClickHouse interface database.
`interface.chTsEnqueue(json_data)`	`nil`	Enqueues a ClickHouse time-series data batch for async insertion.
`interface.chTsDequeue()`	`string`	Dequeues a pending ClickHouse time-series data batch.
`interface.chTsQueueLen()`	`integer`	Returns the number of pending ClickHouse time-series batches in the queue.
`interface.execInMemoryQuery(sql)`	`table`	Executes a SQL query against the in-memory flow/host tables.
`interface.execSQLQuery(sql)`	`table`	Executes a SQL query against the interface's local SQLite database.

20. sFlow

Lua call	Returns	Description
`interface.getSFlowDevices()`	`table`	Returns sFlow agent devices seen on this interface.
`interface.getSFlowDeviceInfo(agent_ip)`	`table`	Returns per-port statistics for a specific sFlow agent.

21. eBPF / Containers

Lua call	Returns	Description
`interface.getPodsStats()`	`table`	Returns statistics for Kubernetes pods observed on this interface (eBPF).
`interface.getContainersStats()`	`table`	Returns statistics for containers observed on this interface (eBPF).
`interface.reloadCompanions()`	`nil`	Reloads companion interface assignments from Redis configuration.

22. nEdge / L7 Shaping & Policy

These functions are available only in nEdge (inline/bridge) deployments.

Lua call	Returns	Description
`interface.reloadL7Rules(pool_id)`	`nil`	Reloads L7 (nDPI-based) shaping rules for a host pool.
`interface.reloadShapers()`	`nil`	Reloads traffic shaper configurations from Redis.
`interface.updateFlowsShapers()`	`nil`	Triggers an update of traffic shaper state for all active flows.
`interface.getPolicyChangeMarker()`	`integer`	Returns a monotonic counter incremented on each policy change.
`interface.getl7PolicyInfo(pool_id)`	`table`	Returns the L7 policy rules for a host pool.
`interface.addLanIPAddress(ip_cidr)`	`nil`	Adds an IP/CIDR to the LAN address list for nEdge routing decisions.
`interface.updateTrafficMirrored(enabled)`	`nil`	Updates the traffic-mirrored flag for the interface.
`interface.updateSmartRecording(enabled)`	`nil`	Updates the smart-recording setting for the interface.
`interface.updateDynIfaceTrafficPolicy(policy)`	`nil`	Updates the dynamic traffic policy for this interface.
`interface.updatePushFiltersSettings(params)`	`nil`	Updates push-filter settings (e.g. BPF rules) for the interface.
`interface.updateLbdIdentifier(use_mac)`	`nil`	Updates the local broadcast domain host identifier (IP vs MAC).
`interface.updateFlowsOnlyInterface(enabled)`	`nil`	Sets the flows-only flag (no host tracking) on the interface.
`interface.loadScalingFactorPrefs()`	`nil`	Reloads interface throughput scaling factor preferences from Redis.
`interface.reloadGwMacs()`	`nil`	Reloads the list of known gateway MAC addresses from Redis.
`interface.reloadDhcpRanges()`	`nil`	Reloads DHCP address ranges from Redis configuration.

23. RADIUS Accounting (nEdge)

Used by captive portal integrations to send RADIUS accounting packets.

Lua call	Returns	Description
`interface.radiusAccountingStart(params)`	`nil`	Sends a RADIUS Accounting-Start packet for a captive-portal session.
`interface.radiusAccountingStop(params)`	`nil`	Sends a RADIUS Accounting-Stop packet for a captive-portal session.
`interface.radiusAccountingUpdate(params)`	`nil`	Sends a RADIUS Accounting-Update (Interim-Update) for an active session.

24. Miscellaneous

Lua call	Returns	Description
`interface.updateSyslogProducers()`	`nil`	Reloads syslog producer configuration for this interface (non-nEdge).
`interface.updateIPReassignment(params_table)`	`nil`	Handles an IP address reassignment event (DHCP lease change).
`interface.updateRanking(ranking_table)`	`nil`	Updates the site/host ranking data for this interface (Pro).
`interface.swapHostnameIPCache()`	`nil`	Swaps the hostname-to-IP cache with a newly built version.
`interface.incSyslogStats(stat_name, n)`	`nil`	Increments a named syslog processing statistics counter.

Appendix: Complete Function Index

All 245 interface.* functions in alphabetical order:

addDataToLocalHostAssets · addLanIPAddress · addMacsIpAddresses · aggregateASNFlows · aggregateSiteFlows · alert_store_query · appendInfluxDB · appendMacEvent · arpScanHosts · captureToPcap · checkContext · chTsDequeue · chTsEnqueue · chTsQueueLen · clickhouseArchiveData · clickhouseExecCSVQuery · convertCountryCode2U16 · convertCountryU162Code · deleteHostData · deleteMacData · deleteObsPoint · discoverHosts · dropFlowTraffic · dropHostTraffic · dropMultipleFlowsTraffic · dumpLiveCaptures · dumpnDPICategoryId · dumpnDPIProtocolId · execInMemoryQuery · execSQLQuery · execSQLWrite · findFlowByKeyAndHashId · findFlowByTuple · findHost · findHostByMac · findMacPool · findMemberPool · findNameFlows · findPidFlows · flushPeriodicityMap · flushPoolDynamicBlacklist · flushServiceMap · getACLInfo · getASesInfo · getASInfo · getActiveMacs · getActiveFlowsStats · getAddressInfo · getAnomalies · getAlerts · getAllZMQFlowFieldDescr · getBatchedFlowsInfo · getBatchedHostsInfo · getBatchedLocalHostsInfo · getBatchedLocalHostsTs · getBatchedMacsInfo · getBatchedRemoteHostsInfo · getBroadcastDomainHostsInfo · getBroadcastMulticastHostsInfo · getContainersStats · getCountriesInfo · getCountryInfo · getEndpoint · getEngagedAlerts · getFirstInterfaceId · getFlowDeviceInfo · getFlowDeviceInfoByIP · getFlowDevices · getFlowKey · getFlowsInfo · getFlowsStats · getFlowsStatus · getGroupedFlows · getHashTablesStats · getHostAttributes · getHostCountry · getHostInfo · getHostMinInfo · getHostPoolStats · getHostPoolsInfo · getHostPoolsStats · getHostUsedQuotasStats · getHostsByPort · getHostsByService · getHostsPorts · getHostsInfo · getId · getIfMac · getIfNames · getInterfaceHosts · getLocalHostsInfo · getLocalHostsInfoNoTX · getLocalHostsInfoNoTXTCP · getLocalServerPorts · getLiveASNStats · getMacDeviceTypes · getMacHosts · getMacInfo · getMacManufacturers · getMacsInfo · getMasterInterfaceId · getMaxIfSpeed · getName · getNetworkStats · getNetworksStats · getNumFlows · getNumHosts · getNumLocalHosts · getNumLocalRxOnlyHosts · getObsPointInfo · getObsPointsInfo · getPeriodicActivitiesStats · getPolicyChangeMarker · getPoolDynamicBlacklistMembers · getPoolDynamicBlacklistStats · getPodsStats · getProtocolFlowsStats · getPublicHostsInfo · getQueuesStats · getRemoteHostsInfo · getRemoteHostsInfoNoTX · getRemoteHostsInfoNoTXTCP · getRxOnlyHostsList · getSFlowDeviceInfo · getSFlowDevices · getSNMPStats · getScore · getSecsToFirstData · getStats · getStatsUpdateFreq · getThroughput · getVLANFlowsStats · getVLANInfo · getVLANsList · getVLANsInfo · getZMQFlowFieldDescr · getl7PolicyInfo · getnDPICategories · getnDPICategoryId · getnDPICategoryName · getnDPIFlowsCount · getnDPIFullProtoName · getnDPIHostStats · getnDPIProtoBreed · getnDPIProtoId · getnDPIProtoName · getnDPIProtocols · getnDPIStats · hasEBPF · hasExternalAlerts · hasVLANs · insertIPACL · insertMacACL · isBehaviourAnalysisAvailable · isBridgeInterface · isCaptureRunning · isDatabaseViewInterface · isDiscoverableInterface · isHostActive · isIdle · isLoopback · isMacActive · isMulticastMac · isPacketInterface · isPcapDumpInterface · isRunning · isSubInterface · isSyslogInterface · isValidIfId · isView · isViewed · isZMQInterface · liveCapture · listHTTPhosts · loadScalingFactorPrefs · mdnsQueueAnyQuery · mdnsQueueNameToResolve · mdnsReadQueuedResponses · name2id · periodicityMap · periodicityMapFilterList · prepareDeleteObsPoint · processFlow · radiusAccountingStart · radiusAccountingStop · radiusAccountingUpdate · releaseEngagedAlerts · releaseExternalAlert · releaseTriggeredAlert · reloadCompanions · reloadDhcpRanges · reloadGwMacs · reloadHostPrefs · reloadL7Rules · reloadShapers · removeDataFromLocalHostAssets · removeIPACL · removeMacACL · resetBroadcastDomains · resetCounters · resetHostStats · resetHostTopSites · resetMacStats · resetPoolsQuotas · rrd_dequeue · rrd_enqueue · rrd_queue_length · select · serviceMap · serviceMapFilterList · serviceMapLearningStatus · serviceMapSetMultipleStatus · serviceMapSetStatus · setCachedAlertValue · setHostOperatingSystem · setHostResolvedName · setInterfaceIdleState · setPeriodicActivityProgress · stopLiveCapture · stopRunningCapture · storeTriggeredAlert · swapHostnameIPCache · triggerExternalAlert · triggerTrafficAlert · updateDirectionStats · updateDynIfaceTrafficPolicy · updateFlowsOnlyInterface · updateFlowsShapers · updateHostTrafficPolicy · updateIPReassignment · updateLbdIdentifier · updatePushFiltersSettings · updateRanking · updateSmartRecording · updateSyslogProducers · updateTopSites · updateTrafficMirrored · viewedBy

42 KiB Raw Permalink Blame History

ntopng Lua API Reference (interface.* bindings)

Table of Contents

1. How interface.* works