ntopng/doc/README.lua_api.md

ntopng Lua API — Master Reference

This document is the entry point for all ntopng C→Lua bindings documentation. ntopng exposes five Lua namespaces, each defined in a dedicated C++ source file and documented in its own reference file.

---

Namespaces at a glance

Namespace	Functions	Source file	Reference
ntop.*	334	src/LuaEngineNtop.cpp	README.lua_ntop_api.md
interface.*	245	src/LuaEngineInterface.cpp	README.lua_interface_api.md
flow.*	20	src/LuaEngineFlow.cpp	README.lua_flow_api.md
host.*	23	src/LuaEngineHost.cpp	README.lua_host_api.md
network.*	9	src/LuaEngineNetwork.cpp	README.lua_network_api.md

---

When to use each namespace

ntop.* — global system functions

Available everywhere. Covers Redis/cache, preferences, user management, file system, nDPI, alerts, time, geo/ASN lookups, ZMQ, and more.

local dirs = ntop.getDirs()
ntop.setCache("my_key", "value", 3600)
ntop.traceEvent(TRACE_INFO, "hello")

→ Full reference

---

interface.* — per-interface queries

Available everywhere. Requires interface.select(ifid) before use. Covers host/flow/MAC enumeration, nDPI stats, alerts, SNMP, host pools, service/periodicity maps, ClickHouse, RRD, live capture, network discovery, ACLs, nEdge shaping, and more.

interface.select(tostring(ifid))
local stats = interface.getStats()
local hosts = interface.getHostsInfo({ currentPage = 1, perPage = 10 })

→ Full reference

---

flow.* — current-flow accessors

Available only inside flow check scripts (scripts/lua/modules/flow_checks/). Operates on the implicit current flow. Covers endpoints, traffic counters, L7 protocol IDs and names, and L7 metadata (HTTP, DNS, SSH, TLS/QUIC).

local cli   = flow.cli()          -- client IP
local proto = flow.l7_proto_name() -- e.g. "HTTP.Facebook"
local dns   = flow.dns()          -- DNS metadata table
flow.triggerAlert(50, "suspicious flow")

→ Full reference

---

host.* — current-host accessors

Available only inside host check scripts (scripts/lua/modules/host_checks/). Operates on the implicit current host. Covers identity, address-type flags, traffic counters, per-protocol stats, peer contact counters, and alert triggering.

if not host.is_local() then return end
local bytes = host.bytes()
local l7    = host.l7()          -- per-protocol breakdown
host.triggerAlert(80, "anomaly detected")

→ Full reference

---

network.* — current-network accessors

Available only inside network check scripts (scripts/lua/modules/network_checks/). Requires network.select(id) or network.checkContext(cidr) before use. Covers network statistics, alert lifecycle, and the alert context cache.

network.checkContext(network_info.network_cidr)
local stats = network.getNetworkStats()
network.setCachedAlertValue("prev_bytes", tostring(bytes), periodicity)

→ Full reference

---

Availability summary

Namespace	REST endpoints	Periodic scripts	Flow checks	Host checks	Network checks
ntop.*	✓	✓	✓	✓	✓
interface.*	✓ (after select)	✓ (after select)	✓	✓	✓
flow.*	—	—	✓	—	—
host.*	—	—	—	✓	—
network.*	✓ (after select)	✓ (after select)	—	—	✓

---

Standard boilerplate

-- All Lua scripts start with this
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")   -- REST endpoints only

-- REST endpoints: select an interface
local ifid = _GET["ifid"] or interface.getFirstInterfaceId()
interface.select(tostring(ifid))

---

Adding a new C→Lua binding

1. Write static int ntop_my_function(lua_State* vm) in the appropriate src/LuaEngine*.cpp file.
2. Add a /* @brief ... Lua: namespace.FuncName(params) → return_type */ comment on the line immediately before the function.
3. Register it in the _ntop_*_reg[] table at the bottom of the file.
4. Update the corresponding doc/README.lua_*_api.md.