### ntopng Execution with Companion Interface Setup Source: https://github.com/ntop/ntopng/blob/dev/doc/README.eBPF.md Example of starting ntopng with a ZMQ interface and other packet interfaces, where one of the packet interfaces will be configured as a companion. ```bash ./ntopng -i tcp://*:1234c -i lo -i ens3 ``` -------------------------------- ### Start ntopng on macOS using Homebrew Source: https://github.com/ntop/ntopng/blob/dev/doc/src/installation.rst Start the ntopng service after installing Redis. This command requires administrative privileges. ```bash sudo ntopng ``` -------------------------------- ### Host Data Retrieval Example (GET) Source: https://github.com/ntop/ntopng/blob/dev/doc/nedge/src/api/rest/api_v2.rst Example of how to retrieve host data using the GET method. Parameters are provided via query string. ```APIDOC ## GET /lua/rest/v2/get/host/data.lua ### Description Retrieves data for a specific host on a given network interface. ### Method GET ### Endpoint /lua/rest/v2/get/host/data.lua ### Parameters #### Query Parameters - **ifid** (string) - Required - The ID of the network interface. - **host** (string) - Required - The IP address or hostname of the host. ### Request Example ```bash curl -s -u admin:admin "http://192.168.1.1:3000/lua/rest/v2/get/host/data.lua?ifid=1&host=192.168.1.2" ``` ### Response #### Success Response (200) - **rc** (integer) - Return code indicating success or failure. - **rc_str** (string) - Human-readable string describing the return code. - **rsp** (object) - The actual response data containing host information. #### Response Example ```json { "rc": 0, "rc_str": "OK", "rsp": { ... } } ``` ``` -------------------------------- ### ntop.* Namespace Example Source: https://github.com/ntop/ntopng/blob/dev/doc/README.lua_api.md Demonstrates basic usage of the ntop.* namespace for system-level operations like getting directories, setting cache values, and tracing events. Available everywhere. ```lua local dirs = ntop.getDirs() ntop.setCache("my_key", "value", 3600) ntop.traceEvent(TRACE_INFO, "hello") ``` -------------------------------- ### Basic nProbe Configuration with ZMQ Source: https://github.com/ntop/ntopng/blob/dev/doc/src/using_with_other_tools/nprobe.rst Example of starting an nProbe instance to capture traffic from 'eth1' and send high-resolution timeseries data to ntopng via ZMQ. ```bash nprobe -i eth1 -n none --zmq "tcp://*:5556" \ -T "@NTOPNG@ %HR_DST_TO_SRC_BYTES %HR_SRC_TO_DST_BYTES" ``` -------------------------------- ### Install ntopng and Redis Packages Source: https://github.com/ntop/ntopng/blob/dev/doc/src/third_party_integrations/pfsense.rst Run this command to install the ntopng and redis packages on pfSense. ```bash pkg install ntopng redis ``` -------------------------------- ### Install ntopng License Key Source: https://github.com/ntop/ntopng/blob/dev/doc/src/third_party_integrations/pfsense.rst Use this command to install your ntopng license key by echoing it to the license file. ```bash echo LICENSE_KEY > /usr/local/etc/ntopng.license ``` -------------------------------- ### Start ntopng Service Source: https://github.com/ntop/ntopng/blob/dev/doc/src/third_party_integrations/pfsense.rst Manually start the ntopng service. ```bash service ntopng start ``` -------------------------------- ### Install Project Dependencies Source: https://github.com/ntop/ntopng/blob/dev/doc/README.frontend.md Run this command once after cloning the repository or after any changes to `package.json` to install all necessary project dependencies. ```bash npm install ``` -------------------------------- ### Start ntopng Service on macOS Source: https://github.com/ntop/ntopng/blob/dev/doc/src/installation.rst Load the ntopng service to start it. This command requires administrative privileges. ```bash sudo launchctl load /Library/LaunchDaemons/org.ntop.ntopng.plist ``` -------------------------------- ### Enable ntopng to Start on Boot Source: https://github.com/ntop/ntopng/blob/dev/doc/README.systemd.md Configure the ntopng service to start automatically upon system boot, typically after it has been disabled. ```bash # systemctl enable ntopng ``` -------------------------------- ### Start ntopng with Network Interface Source: https://github.com/ntop/ntopng/blob/dev/doc/src/example.rst Start ntopng by specifying the network interface to capture traffic from, such as 'wlan0'. ```bash ntopng -i wlan0 ``` -------------------------------- ### Example ntopng.conf Configuration Source: https://github.com/ntop/ntopng/blob/dev/doc/src/how_to_start/configuration_file.rst This example demonstrates various options that can be set in the ntopng.conf file, including network listening ports, HTTP prefixes, DNS resolution modes, memory limits, and flow dumping destinations. Uncomment lines to enable specific configurations. ```bash # Listen on localhost:3000 only --http-port=:3000 # Use prefix due to nginx proxy --http-prefix="/ntopng" # Everybody's admin #--disable-login=1 # Do not resolve any names --dns-mode=3 # Limit memory usage --max-num-flows=200000 --max-num-hosts=250000 # Dump flows to ClickHouse --dump-flows=clickhouse #--verbose ``` -------------------------------- ### Get Host Data Example Source: https://github.com/ntop/ntopng/blob/dev/doc/src/api/rest/api_v1.rst Example of how to retrieve host data using the API. Parameters can be provided via query string (GET) or JSON payload (POST). ```APIDOC ## GET /lua/rest/v1/get/host/data.lua ### Description Retrieves data for a specific host on a given network interface. ### Method GET ### Endpoint `/lua/rest/v1/get/host/data.lua` ### Parameters #### Query Parameters - **ifid** (string) - Required - The ID of the network interface. - **host** (string) - Required - The IP address or hostname of the host. ### Request Example ```bash curl -s -u admin:admin "http://192.168.1.1:3000/lua/rest/v1/get/host/data.lua?ifid=1&host=192.168.1.2" ``` ## POST /lua/rest/v1/get/host/data.lua ### Description Retrieves data for a specific host on a given network interface using a POST request. ### Method POST ### Endpoint `/lua/rest/v1/get/host/data.lua` ### Parameters #### Request Body - **ifid** (string) - Required - The ID of the network interface. - **host** (string) - Required - The IP address or hostname of the host. ### Request Example ```json { "ifid": "1", "host": "192.168.1.2" } ``` ``` -------------------------------- ### Set Up Python Virtual Environment and Install Dependencies Source: https://github.com/ntop/ntopng/blob/dev/doc/README.doc.md Creates a Python virtual environment, activates it, upgrades pip, and installs necessary packages for documentation building. ```bash cd ~/ntopng python3 -m venv venv source venv/bin/activate pip install --upgrade pip setuptools wheel pip install breathe sphinx sphinx-rtd-theme mock rst2pdf sphinxcontrib.swaggerdoc sphinxcontrib.jquery six ``` -------------------------------- ### Start ntopng with Configuration File or Options Source: https://github.com/ntop/ntopng/blob/dev/doc/src/how_to_start/index.rst Use this command to start ntopng, providing either a path to a configuration file or command-line options to modify its behavior. ```bash ntopng ``` ```bash ntopng ``` -------------------------------- ### Get Host Data using GET Request Source: https://github.com/ntop/ntopng/blob/dev/doc/nedge/src/api/rest/api_v2.rst Example of how to retrieve host data using a GET request with curl. Ensure correct authentication and URL parameters are used. ```bash curl -s -u admin:admin "http://192.168.1.1:3000/lua/rest/v2/get/host/data.lua?ifid=1&host=192.168.1.2" ``` -------------------------------- ### Create ntopng.start file for automatic startup Source: https://github.com/ntop/ntopng/blob/dev/doc/src/how_to_start/running_as_a_daemon.rst On systems without systemd, creating an empty 'ntopng.start' file in the configuration directory enables automatic startup on boot. This is shown alongside the configuration file. ```bash root@devel:/etc/ntopng$ ls -lha total 28K drwxr-xr-x 2 root root 4.0K Mar 17 15:44 . drwxr-xr-x 117 root root 12K Mar 11 12:16 .. -rw-r--r-- 1 root root 211 Mar 15 17:54 ntopng.conf -rw-r--r-- 1 root root 0 Mar 17 15:44 ntopng.start ``` -------------------------------- ### Host Data Retrieval Example Source: https://github.com/ntop/ntopng/blob/dev/doc/src/api/rest/api_v2.rst Examples demonstrating how to retrieve host data using the RESTful API v2 via GET and POST requests. ```APIDOC ## GET /lua/rest/v2/get/host/data.lua ### Description Retrieves data for a specific host. ### Method GET ### Endpoint `/lua/rest/v2/get/host/data.lua` ### Parameters #### Query Parameters - **ifid** (string) - Required - Interface ID. - **host** (string) - Required - Host IP address. ### Request Example ```bash curl -s -u admin:admin "http://192.168.1.1:3000/lua/rest/v2/get/host/data.lua?ifid=1&host=192.168.1.2" ``` ## POST /lua/rest/v2/get/host/data.lua ### Description Retrieves data for a specific host using a POST request. ### Method POST ### Endpoint `/lua/rest/v2/get/host/data.lua` ### Parameters #### Request Body - **ifid** (string) - Required - Interface ID. - **host** (string) - Required - Host IP address. ### Request Example ```bash curl -s -u admin:admin -H "Content-Type: application/json" -d '{"ifid": "1", "host": "192.168.1.2"}' "http://192.168.1.1:3000/lua/rest/v2/get/host/data.lua" ``` ### Response Format An API response is usually represented by a JSON message matching a standard structure: ```json { "rc": 0, "rc_str": "OK", "rsp": { ... } } ``` ``` -------------------------------- ### Install ntopng License Key to File Source: https://github.com/ntop/ntopng/blob/dev/doc/src/versions_and_licensing.rst This command demonstrates how to install a generated license key by redirecting it into the '/etc/ntopng.license' file. Ensure the license key is valid and correctly formatted. ```bash # echo "XJQ6U04QIW2ixxzNMfGnWibAySvd8Rd3K4qxymrZNT3DoR0m1K6Ybx1nnG1Y1n+7O4znPE4Zroy+A5EZZfu/i0UzrOhly/HNUgNju+RTP6d/zAvMTs04ZtIG9/BjalrrOfHzw0bU3uTm0z1F+S5N6IFUP6cXzoWP+yrpGmPjzmQHGa5kSw5IJw6YjmPvAgGLHsKn+u2KoA6xP7c4eZ7YGJ/S6MTmYtLFOBse4qoaViSC30RBu54QVG4Zafz4qwhMEnT+hijwbkWJfjZBRzl3eLE05HclnkRWibuYJqKG6c9NRExF0u6a3+P/+ouB7PcczDf8G4O22MWgr2cTNjsmRA==" > /etc/ntopng.license ``` -------------------------------- ### ntopng Configuration File Example Source: https://github.com/ntop/ntopng/blob/dev/doc/src/cli_options/cli_options_example.rst Configuration file options use an equal sign between key and value. For options without a value, an equal sign must still be present. ```bash # The configuration file is similar to the command line, with the exception that an equal # sign '=' must be used between key and value. Example: -i=p1p2 or --interface=p1p2 For # options with no value (e.g. -v) the equal is also necessary. Example: "-v=" must be used. # # # -G|--pid-path # Specifies the path where the PID (process ID) is saved. This option is ignored when # ntopng is controlled with systemd (e.g., service ntopng start). # -G=/var/run/ntopng.pid # # -i|--interface # Specifies the network interface or collector endpoint to be used by ntopng for network # monitoring. On Unix you can specify both the interface name (e.g. lo) or the numeric # interface id as shown by ntopng -h. On Windows you must use the interface number instead. # Note that you can specify -i multiple times in order to instruct ntopng to create multi- # ple interfaces. # # -i=eth1 -i=eno1 -i=eno2 -i=lo -i=tcp://127.0.0.1:5556 # # # -m|--local-networks ``` -------------------------------- ### HTTP GET Request Example Source: https://github.com/ntop/ntopng/blob/dev/doc/README.lua_ntop_api.md Demonstrates how to make an HTTP GET request to an external REST API and parse the JSON response. Ensure the 'dkjson' library is required. ```lua local json = require("dkjson") local body = ntop.httpGet("https://api.example.com/data", nil, nil, 5, true) if body then local data = json.decode(body) end ``` -------------------------------- ### Serve HTML Documentation Locally Source: https://github.com/ntop/ntopng/blob/dev/doc/README.doc.md Starts a local Python web server to test the generated HTML documentation on port 8080. ```bash pushd _build/html; python3 -m http.server 8080; popd ``` -------------------------------- ### Get Alerts Data - cURL Example Source: https://github.com/ntop/ntopng/blob/dev/doc/src/api/rest/examples_v2.rst Retrieve a list of alerts for a given interface using this cURL command. Authentication is required. ```bash curl -u admin:admin -H "Content-Type: application/json" -d '{"ifid": "0"}' http://localhost:3000/lua/rest/v2/get/interface/alert/list.lua ``` -------------------------------- ### Get Alert Type Constants - cURL Example Source: https://github.com/ntop/ntopng/blob/dev/doc/src/api/rest/examples_v2.rst Retrieve a list of alert types and their associated keys using this cURL command. Authentication is required. ```bash curl -u admin:admin http://localhost:3000/lua/rest/v2/get/alert/type/consts.lua ``` -------------------------------- ### n2disk Configuration File Example Source: https://github.com/ntop/ntopng/blob/dev/doc/developers/README.recording.md Example configuration for n2disk, specifying interface, directories, disk limits, file lengths, buffer sizes, indexing, and CPU affinities. Ensure these settings match your capture environment. ```bash --interface=eno1 --dump-directory=/storage/n2disk/eno1/pcap --timeline-dir=/storage/n2disk/eno1/timeline --disk-limit=10% --max-file-len=256 --buffer-len=1024 --index --writer-cpu-affinity=0 --reader-cpu-affinity=1 --indexer-cpu-affinity=2 ``` -------------------------------- ### Get Interface Data Source: https://github.com/ntop/ntopng/blob/dev/doc/src/api/rest/examples_v2.rst This example shows how to retrieve interface data using the REST API. It demonstrates the use of cookies for authentication and specifies the interface ID. ```APIDOC ## GET /lua/rest/get/interface/data.lua ### Description Retrieves data for a specific network interface. ### Method GET ### Endpoint /lua/rest/get/interface/data.lua ### Query Parameters - **ifid** (integer) - Required - The ID of the interface to retrieve data for. ### Request Example ```bash curl --cookie "user=admin; session=3ff5cf2aba7168e9ef955c20291a9ad4" "http://192.168.1.1:3000/lua/rest/get/interface/data.lua?ifid=1" ``` ### Response #### Success Response (200) - **rc_str_hr** (string) - Human-readable status message. - **rsp** (object) - Response data. - **session** (string) - The current session ID. ``` -------------------------------- ### Run ntopng alerts example Source: https://github.com/ntop/ntopng/blob/dev/doc/src/api/python/index.rst Example command to run the alerts.py script, specifying ntopng URL, user, password, and interface ID. ```bash python3 alerts.py -n http://localhost:3000 -i admin -p password -i 0 ``` -------------------------------- ### Get Alert Severity Constants - cURL Example Source: https://github.com/ntop/ntopng/blob/dev/doc/src/api/rest/examples_v2.rst Fetch the available alert severity levels and their corresponding IDs using this cURL command. Authentication is required. ```bash curl -u admin:admin http://localhost:3000/lua/rest/v2/get/alert/severity/consts.lua ``` -------------------------------- ### Example: Connect ntopng to Standalone ClickHouse Source: https://github.com/ntop/ntopng/blob/dev/doc/src/flow_dump/clickhouse/clickhouse.rst Connects ntopng to a local ClickHouse instance using default credentials and database. ```bash ntopng -F "clickhouse;127.0.0.1;ntopng;default;default" ``` -------------------------------- ### ntopng Execution with Multiple Interfaces Source: https://github.com/ntop/ntopng/blob/dev/doc/README.eBPF.md Example of starting ntopng with a ZMQ interface and other packet interfaces. ntopng will match incoming events to these interfaces based on IF_NAME. ```bash ./ntopng -i tcp://*:1234c -i lo -i ens3 -i cbr0 ``` -------------------------------- ### Add Host Pool Examples Source: https://github.com/ntop/ntopng/blob/dev/doc/src/api/rest/examples_v2.rst Demonstrates adding host pools with different configurations, including IP ranges, MAC addresses, and empty pools. Requires authentication and JSON content type. ```bash curl -s -u admin:admin -H "Content-Type: application/json" -d '{"pool_name": "themaina", "pool_members": "192.168.2.0/24@0", "recipients":"0"}' http://localhost:3000/lua/rest/v2/add/host/pool.lua ``` ```bash curl -s -u admin:admin -H "Content-Type: application/json" -d '{"pool_name": "themaina", "pool_members": "192.168.2.0/24@0,192.168.3.0/24@0", "recipients":"0"}' http://localhost:3000/lua/rest/v2/add/host/pool.lua ``` ```bash curl -s -u admin:admin -H "Content-Type: application/json" -d '{"pool_name": "themainamac", "pool_members": "AA:BB:CC:DD:EE:FF", "recipients":"0"}' http://localhost:3000/lua/rest/v2/add/host/pool.lua ``` ```bash curl -s -u admin:admin -H "Content-Type: application/json" -d '{"pool_name": "themainaip", "pool_members": "8.8.8.8/32@2", "recipients":"0"}' http://localhost:3000/lua/rest/v2/add/host/pool.lua ``` ```bash curl -s -u admin:admin -H "Content-Type: application/json" -d '{"pool_name": "themainaempty", "pool_members": "", "recipients":"0"}' http://localhost:3000/lua/rest/v2/add/host/pool.lua ``` -------------------------------- ### Get Alerts Timeseries - cURL Example Source: https://github.com/ntop/ntopng/blob/dev/doc/src/api/rest/examples_v2.rst Use this cURL command to retrieve time-series data for alerts on a specific interface. Requires authentication and specifies time range. ```bash curl -u admin:admin -H "Content-Type: application/json" -d '{"ifid": "0", "status": "historical-flows", "epoch_begin": 1590710400, "epoch_end": 1590796800}' http://localhost:3000/lua/rest/v2/get/alert/ts.lua ``` -------------------------------- ### Example SQL for Alert Views Source: https://github.com/ntop/ntopng/blob/dev/doc/README.clickhouse_schema.md Demonstrates how to create a unified view for host alerts by combining historical and in-memory data. ```sql SELECT * FROM host_alerts UNION ALL SELECT * FROM engaged_host_alerts ``` -------------------------------- ### CSV Pool Import Examples Source: https://github.com/ntop/ntopng/blob/dev/doc/src/user_interface/shared/settings/configurations.rst These examples demonstrate the format for importing pool members via CSV. Supported separators include space, comma, and semicolon. IP addresses can be in CIDR notation with an optional VLAN tag, and MAC addresses in standard colon-separated format. Lines starting with '#' are comments and empty lines are ignored. ```text ``` ```text 192.168.1.2/32@10 myPool 192.168.1.2/32@10,myPool 192.168.1.2/32@10;myPool ``` ```text x.y.z.k/p@v ``` ```text 192.168.1.1/32;myPool 192.168.1.1/32@0;myPool ``` ```text AA:BB:CC:DD:EE:FF;myPool ``` ```text # Office hosts 192.168.1.10/32 OfficePool 192.168.1.0/24 OfficePool # Guest devices 192.168.2.0/24;GuestPool AA:BB:CC:DD:EE:FF,GuestPool # VLAN-tagged host (VLAN 10) 10.0.0.5/32@10 ServerPool ``` -------------------------------- ### Get Interface Data Source: https://github.com/ntop/ntopng/blob/dev/doc/src/api/rest/examples_v1.rst This example shows how to retrieve interface data using a session cookie. You need to obtain a session ID first, typically through a login or similar API call. ```APIDOC ## GET /lua/rest/get/interface/data.lua ### Description Retrieves data for a specific network interface. ### Method GET ### Endpoint /lua/rest/get/interface/data.lua ### Parameters #### Query Parameters - **ifid** (integer) - Required - The ID of the interface to retrieve data for. ### Request Example ```bash curl --cookie "user=admin; session=3ff5cf2aba7168e9ef955c20291a9ad4" "http://192.168.1.1:3000/lua/rest/get/interface/data.lua?ifid=1" ``` ### Response #### Success Response (200) - **rc_str** (string) - Indicates the status of the request (e.g., "OK"). - **rc_str_hr** (string) - A human-readable string describing the status (e.g., "Success"). - **rsp** (object) - Contains the response data. - **session** (string) - The current session ID. ``` -------------------------------- ### Install Redis using Homebrew Source: https://github.com/ntop/ntopng/blob/dev/doc/src/installation.rst Install the Redis in-memory data structure store using Homebrew. This is a prerequisite for ntopng. ```bash brew install redis ``` -------------------------------- ### Get Host Data using POST Request Source: https://github.com/ntop/ntopng/blob/dev/doc/nedge/src/api/rest/api_v2.rst Example of how to retrieve host data using a POST request with curl. This method requires setting the Content-Type header and providing data in the request body. ```bash curl -s -u admin:admin -H "Content-Type: application/json" -d '{"ifid": "1", "host": "192.168.1.2"}' "http://192.168.1.1:3000/lua/rest/v2/get/host/data.lua" ``` -------------------------------- ### Vue Component: TableWithConfig Full Example Source: https://github.com/ntop/ntopng/blob/dev/doc/developers/vue_components/table_with_config.md Demonstrates the full integration of the TableWithConfig component within a Vue.js application. Includes template setup, script logic for props, event handlers, and custom rendering. ```vue ``` -------------------------------- ### Start ntopng with Custom Protocols Source: https://github.com/ntop/ntopng/blob/dev/doc/src/user_interface/shared/settings/applications_and_categories.rst Enable custom application rules by specifying the path to the nDPI protocols file when starting ntopng. ```bash sudo chown ntopng:ntopng /var/lib/ntopng/protos.txt ``` ```bash --ndpi-protocols=/var/lib/ntopng/protos.txt ``` -------------------------------- ### Standard Boilerplate for Network Check Script Source: https://github.com/ntop/ntopng/blob/dev/doc/README.lua_network_api.md This is the standard setup for a network check script in ntopng. It ensures the network context is correctly set before accessing network statistics and provides an example of how to trigger alerts based on network score. ```lua -- scripts/lua/modules/network_checks/my_network_check.lua local dirs = ntop.getDirs() package.path = dirs.installdir .. "/scripts/lua/modules/?.lua;" .. package.path local alert_consts = require("alert_consts") local alerts_api = require("alerts_api") local my_check = {} function my_check.check(network_info) -- network_info.network_cidr contains the CIDR string, e.g. "10.0.0.0/8" -- Ensure the network context is set if not network.checkContext(network_info.network_cidr) then return end local stats = network.getNetworkStats() if not stats then return end -- Example: alert on high score if stats.score and stats.score > 100 then -- store/release alerts via network.storeTriggeredAlert / network.releaseTriggeredAlert end end return my_check ``` -------------------------------- ### Install NodeJS and npm Source: https://github.com/ntop/ntopng/blob/dev/doc/developers/README.GUI.frontend.md Installs NodeJS, npm, and jq on Ubuntu/Debian systems. These are prerequisites for managing ntopng's frontend assets. ```bash sudo apt-get install nodejs npm jq ```