User Script Hooks

ntopng uses hooks to know when to execute a user script. Hooks are string keys of the plugin hooks table and have a callback function assigned. Hooks are associated to:

  • Predefined events for flows
  • Intervals of time for any other network element such as an host, or a network

Flow User Script Hooks and Other User Script Hooks are discussed below.

Flow User Script Hooks

Available hooks for flow user scripts are the following:

  • protocolDetected: Called after the Layer-7 application protocol has been detected.
  • statusChanged: Called when the internal status of the flow has changed since the previous invocation.
  • periodicUpdate: Called every few minutes on long-lived flows.
  • flowEnd: Called when the flow is considered finished.
  • all: A special hook which will cause the associated callback to be called for all the available hooks.

Flow User Script Hooks Parameters

ntopng calls flow user scripts with two parameters:

  • now: An integer indicating the current epoch
  • script_config: A table containing the user script configuration submitted by the user from the User Scripts GUI. Table can be empty if the script doesn not require user-submitted configuration.

Flow User Script Hook Example

A user script which needs to be called every time a flow goes idle, will implement a callback function and assign it to hook flowEnd.

hooks = {
  flowEnd  = function (now, script_config)
    --[[ Callback function body --]]
  end
}

Other User Script Hooks

Available hooks for non-flow user scripts are the following:

  • min: Called every minute.
  • 5mins: Called every 5 minutes.
  • hour: Called every hour.
  • day: Called every day (at midnight localtime).
  • all: A special hook name which will cause the associated callback to be called for all the available hooks.

Other User Script Hooks Parameters

ntopng calls every user script hook function with a params Lua table as argument. The script hook function is expected to have this structure:

function my_callback(params)
  -- ...
end

The params contains the following keys:

  • granularity: one of aperiodic, min, 5mins, hour, day.
  • alert_entity: A table carrying information on the current entity which can be used to generate alerts.
  • entity_info: A string identifying the current entity.
  • cur_alerts: Currently engaged alert for the entity.
  • user_script_config: The user script configuration submitted by the user from the User Scripts GUI. Table can be empty if the script doesn not require user-submitted configuration.
  • user_script: The name of the user script which is being called.
  • when: An integer indicating the current epoch.
  • ifid: The interface id of the current interface.
  • ts_enabled: True when the timeseries generation is enabled for the current timeseries.

It is ntopng which takes care of calling the hook callback function with table params opportunely populated.

Other User Script Hooks Example

A user script which needs to be called every minute will implement a callback function and assign it to hook min

hooks = {min  = function (params) --[[ Callback function body --]] end }