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.

Parameters: ifid – the interface identifier
Returns: true if supported, false otherwise

function getZMQProbeAddr(ifid)

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

Parameters: ifid – the interface identifier
Returns: the endpoint

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)

Parameters: ifid – the interface identifier
Returns: true if supported, false otherwise

function isExternalProvidersReminderDismissed(ifid)

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

Returns: true if the reminder has to be shown, false otherwise

function dismissExternalProvidersReminder(ifid)

Dismiss the reminder for external traffic recording providers.

Returns: nil

function isExtractionAvailable()

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

Returns: true if extraction is available, false otherwise

function getN2diskInfo()

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

Returns: a table with the information

function setLicense(key)

Install a license for n2disk.

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

function getExtInterfaces(ifid)

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

Parameters: ifid – the interface identifier
Returns: a table with external interfaces information

function getPcapPath(ifid)

Return the root path for recorded pcap data.

Parameters: ifid – the interface identifier
Returns: the path

function volumeInfo(path)

Read information about a volume, including storage size and available space.

Parameters: path – the volume path (or a folder inside the volume)

function storageInfo(ifid, timeout)

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

Parameters

ifid – the interface identifier
timeout – the maxium time to compute the size

Returns

a table containing storage information (size is in bytes)

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.

Parameters: ifid – the interface identifier
Returns: true if recording is enabled, false otherwise

function isExtractionEnabled(ifid)

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

Parameters: ifid – the interface identifier
Returns: true if extraction is available and recording is enabled, false otherwise

function isActive(ifid)

Check if the traffic recording service is running.

Parameters: ifid – the interface identifier
Returns: true if the service is running, false otherwise

function isExtractionActive(ifid)

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

Parameters: ifid – the interface identifier
Returns: true if the service is running and extraction available, false otherwise

function getCurrentTrafficRecordingProviderTimelinePath(ifid)

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

Parameters: ifid – the interface identifier
Returns: the timeline, if found, or nil

function checkExtraction(ifid)

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

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

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)

Parameters

ifid – the interface identifier
rows – the number of lines to return

Returns

the log trace

function stats(ifid)

Return statistics from the traffic recording service (n2disk)

Parameters: ifid – the interface identifier
Returns: the statistics

function isDataAvailable(ifid, epoch_begin, epoch_end)

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

Parameters

ifid – the interface identifier
epoch_begin – the begin time (epoch)
epoch_end – the end time (epoch)

Returns

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.

function getJobFiles(id)

Return the list of pcap files extracted for a job.

Parameters: job_id – the job identifier
Returns: the list of pcap files (paths)

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.

Parameters: ifid – the interface identifier
Returns: the jobs statistics (ready, total)

function getExtractionJobs(ifid)

Return the list of scheduled extraction jobs.

Parameters: ifid – the interface identifier
Returns: the list of jobs

function stopJob(job_id)

Stop a running extraction job.

Parameters: job_id – the job identifier

function scheduleExtraction(ifid, params)

Schedule a new extraction job.

Parameters

ifid – the interface identifier
params – the extraction parameters. time_from/time_to (epoch) are mandatory. filter (nBPF format) is optional.

Returns

the newly created job