mirror of
https://github.com/ntop/ntopng.git
synced 2026-05-17 03:56:40 +00:00
138 lines
4.5 KiB
Markdown
138 lines
4.5 KiB
Markdown
# 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](README.lua_ntop_api.md) |
|
|
| `interface.*` | 245 | `src/LuaEngineInterface.cpp` | [README.lua_interface_api.md](README.lua_interface_api.md) |
|
|
| `flow.*` | 20 | `src/LuaEngineFlow.cpp` | [README.lua_flow_api.md](README.lua_flow_api.md) |
|
|
| `host.*` | 23 | `src/LuaEngineHost.cpp` | [README.lua_host_api.md](README.lua_host_api.md) |
|
|
| `network.*` | 9 | `src/LuaEngineNetwork.cpp` | [README.lua_network_api.md](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.
|
|
|
|
```lua
|
|
local dirs = ntop.getDirs()
|
|
ntop.setCache("my_key", "value", 3600)
|
|
ntop.traceEvent(TRACE_INFO, "hello")
|
|
```
|
|
|
|
→ [Full reference](README.lua_ntop_api.md)
|
|
|
|
---
|
|
|
|
### `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.
|
|
|
|
```lua
|
|
interface.select(tostring(ifid))
|
|
local stats = interface.getStats()
|
|
local hosts = interface.getHostsInfo({ currentPage = 1, perPage = 10 })
|
|
```
|
|
|
|
→ [Full reference](README.lua_interface_api.md)
|
|
|
|
---
|
|
|
|
### `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).
|
|
|
|
```lua
|
|
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](README.lua_flow_api.md)
|
|
|
|
---
|
|
|
|
### `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.
|
|
|
|
```lua
|
|
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](README.lua_host_api.md)
|
|
|
|
---
|
|
|
|
### `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.
|
|
|
|
```lua
|
|
network.checkContext(network_info.network_cidr)
|
|
local stats = network.getNetworkStats()
|
|
network.setCachedAlertValue("prev_bytes", tostring(bytes), periodicity)
|
|
```
|
|
|
|
→ [Full reference](README.lua_network_api.md)
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
```lua
|
|
-- 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`.
|
|
|