2.1. recording_utils API

Extraction params:
  • time_from: epoch
  • time_to: epoch
  • filter: nBPF filter
Recording configuration params:
  • buffer_size: Buffer size (MB)
  • max_file_size: Max file length (MB)
  • max_file_duration: Max file duration (sec)
  • max_disk_space: Max disk space (MB)
  • snaplen: Capture length
  • writer_core: Writer thread affinity
  • reader_core: Reader thread affinity
  • indexer_cores: Indexer threads affinity
  • zmq_endpoint: ZMQ endpoint (optional)

Functions

function isSupportedZMQInterface(ifid)

Check if an interface is a ZMQ interface that can be used with external interfaces for traffic recording and flow import.

Return
true if supported, false otherwise
Parameters
  • ifid: the interface identifier

function getZMQProbeAddr(ifid)

Return the ZMQ endpoint that should be used by an external process (n2disk) to deliver flows to ntopng.

Return
the endpoint
Parameters
  • ifid: the interface identifier

function isSupportedInterface(ifid)

Check if an interface is supported for recording (packet interface, or ZMQ interface that can be used with external interfaces for traffic dump and flow import)

Return
true if supported, false otherwise
Parameters
  • ifid: the interface identifier

function isExternalProvidersReminderDismissed(ifid)

Check if a reminder that warns the user about available external traffic rec. providers has to be shown.

Return
true if the reminder has to be shown, false otherwise

function dismissExternalProvidersReminder(ifid)

Dismiss the reminder for external traffic recording providers.

Return
nil

function isAvailable()

Check if traffic recording is available and allowed for the current user on an interface.

Return
true if recording is available, false otherwise

function getN2diskInfo()

Return information about the recording service (n2disk) including systemid and version.

Return
a table with the information

function setLicense(key)

Install a license for n2disk.

Return
true if the license is installed, false in case it is not possible
Parameters
  • key: The license key

function getExtInterfaces(ifid)

Return external interfaces, not in use by ntopng, that can be used through ZMQ interface for traffic recording and flow import.

Return
a table with external interfaces information
Parameters
  • ifid: the interface identifier

function getPcapPath(ifid)

Return the root path for recorded pcap data.

Return
the path
Parameters
  • ifid: the interface identifier

function storageInfo(ifid)

Read information about the storage, including storage size and available space.

Return
a table containing storage information (size is in bytes)
Parameters
  • ifid: the interface identifier

function createConfig(ifid, params)

Generate a configuration for the traffic recording service (n2disk)

Parameters
  • ifid: the interface identifier
  • params: the traffic recording settings

function isEnabled(ifid)

Check if traffic recording is available and enabled on an interface.

Return
true if recording is enabled, false otherwise
Parameters
  • ifid: the interface identifier

function isActive(ifid)

Check if the traffic recording service is running.

Return
true if the service is running, false otherwise
Parameters
  • ifid: the interface identifier

function getCurrentTrafficRecordingProviderTimelinePath(ifid)

Returns the path to the timeline of the selected traffic recorder.

Return
the timeline, if found, or nil
Parameters
  • ifid: the interface identifier

function checkExtraction(ifid)

Parse the configuration file of a manually-started n2disk and returns the timeline if found.

Return
true if extraction is possible and false otherwise, along with a check message
Parameters
  • ifid: the interface identifier

function restart(ifid)

Start (or restart) the traffic recording service.

Parameters
  • ifid: the interface identifier

function stop(ifid)

Stop the traffic recording service.

Parameters
  • ifid: the interface identifier

function log(ifid, rows)

Return the log trace of the traffic recording service (n2disk)

Return
the log trace
Parameters
  • ifid: the interface identifier
  • rows: the number of lines to return

function stats(ifid)

Return statistics from the traffic recording service (n2disk)

Return
the statistics
Parameters
  • ifid: the interface identifier

function isDataAvailable(ifid, epoch_begin, epoch_end)

Check if there is pcap data for a specified time interval (fully included in the dump window)

Return
a table with ‘available’ = true if the specified interval is included in the dump window, ‘epoch_begin’/’epoch_end’ are also returned with the actual available window.
Parameters
  • ifid: the interface identifier
  • epoch_begin: the begin time (epoch)
  • epoch_end: the end time (epoch)

function getJobFiles(id)

Return the list of pcap files extracted for a job.

Return
the list of pcap files (paths)
Parameters
  • job_id: the job identifier

function deleteJob(job_id)

Delete an extraction job and its pcap data on disk, if any.

Parameters
  • job_id: the job identifier

function deleteAndStopAllJobs(ifid)

Delete and stop all the extraction jobs for the specified interface.

Parameters
  • ifid: the interface identifier

function extractionJobsInfo(ifid)

Return statistics about the extraction jobs.

Return
the jobs statistics (ready, total)
Parameters
  • ifid: the interface identifier

function getExtractionJobs(ifid)

Return the list of scheduled extraction jobs.

Return
the list of jobs
Parameters
  • ifid: the interface identifier

function stopJob(job_id)

Stop a running extraction job.

Parameters
  • job_id: the job identifier

function scheduleExtraction(ifid, params)

Schedule a new extraction job.

Return
the newly created job
Parameters
  • ifid: the interface identifier
  • params: the extraction parameters. time_from/time_to (epoch) are mandatory. filter (nBPF format) is optional.