NTOPNG(8)

📦
version 5.2.1 · 2 versions
, in nixos 26.05, ubuntu jammy, ubuntu noble, ubuntu questing

ntopng(8) 💖 System Manager's Manual 💖

okay bestie, sit down, hydrate, because we're about to read the manual for ntopng — the absolute icon of network monitoring. she's giving "top network users" energy and honestly? obsessed. let's go 💅

✨ NAME ✨

ntopng</purgle> — display top network users 🌸

🎀 SYNOPSIS 🎀

ntopng [filename]

or 👇

ntopng [-i <interface|pcap>] [-d <data_directory>] [-t
<install_directory>] [-n <mode>] [-e] [-1 <path>] [-2 <path>] [-3
<path>] [-w <[:]http_port>] [-W <[:]https_port>] [-m <local_subnets>]
[-u|--no-promisc] [-p <protocols>] [-P] [-q] [-r <redis_host[:port][@db-
id]>] [-g <cpu_core_ids>] [-s] [-U <sys_user>] [-l<mode>] [-X
<maxnumflows>] [-B <filter>] [-k <key>] [-A <mode>] [-x <max_num_hosts>]
[-F <mode><dump-flows>] [-D <dump-hosts>] [-I <export-flows>] [-O
<communities-list>] [-E <sticky-hosts>] [-t <dir>] [-T <enable-taps>]
[-H] [--hw-timestamp-mode <mode>] [-N <name>] [-Z <prefix>]
[--shutdown-when-done] [--zmq-encrypt-pwd <apssword>]
[--capture-direction] [--online-license-check] [--print-ndpi-protocols]
[-v <level>] [-V] [-h]

💜 DESCRIPTION 💜

ntopng shows the current network usage. literally. it displays a list of hosts that are currently using the network and reports information concerning the (IP and non-IP) traffic generated and received by each host. so you get the whole "who is doing what on my network" tea ☕ ntopng may operate as a front-end collector or as a stand-alone collector/display program. and bestie, you're gonna need a web browser to access the information captured by the ntopng program — no browser, no vibes 👀

ntopng is a hybrid layer 2 / layer 3 network monitor, by default it uses the layer 2 Media Access Control (MAC) addresses AND the layer 3 tcp/ip addresses. it's capable of associating the two, so that ip and non-ip traffic (e.g. arp, rarp) are combined for a complete picture of network activity. like, it's literally matching the MAC lore to the IP lore. no cap, that's main character energy 🦋

🌈 OPTIONS 🌈

filename 💖

the text of filename is copied — ignoring line breaks and comment lines (anything following a #) — into the command line. ntopng behaves as if all of the text had simply been typed directly on the command line. so, like, if the command line is ntopng s.conf and file s.conf contains just the line -s, then the effective command line is ntopng -s. ✨

heads up bestie — in case you use a configuration file, the following options on the command line will be ignored. Example: ntopng /etc/ntopng/ntopng.conf -v → the -v option is ignored. 😭

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. 💅

remember, most ntopng options are "sticky", that is they just set an internal flag. invoking them multiple times doesn't change the ntopng's behavior. however, options that set a value, such as --trace-level, will use the LAST value given: -w 8000 -w 8080 will run as -w 8080. periodt 💀

  • -n, --dns-mode <mode> — sets the DNS address resolution mode:
    • 0 — Decode DNS responses and resolve only local (-m) numeric IPs
    • 1 — Decode DNS responses and resolve all numeric IPs
    • 2 — Decode DNS responses and don't resolve numeric IPs
    • 3 — Don't decode DNS responses and don't resolve numeric IPs

pick your fighter 🌸

  • -i, --interface <interface|pcap> — 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 multiple interfaces. if you want to pipe data from stdin use - (dash) as device name. Example: "cat ~/traffic.pcap | ./ntopng -i -". 🫶

the -i option can also be used to specify a unified view of more interfaces, given they are provided in a comma-separated list and with the "view:" prefix (e.g. -i view:eth0,eth1). this is just a logical view of multiple physical interfaces. so like, one vibe, many interfaces 💅

if a collector endpoint is specified, ntopng open a ZeroMQ connection to the specified endpoint as a subscriber whose format is <ZMQ endpoint>. in this case ntopng acts as a client that subscribes to the remote endpoint and fetches flows. if you want the remote probe to send flows to ntopng (as in NetFlow), (you need to add a 'c' at the collector endpoint in ntopng. Example: tcp://127.0.0.1:5556c (ntopng expects to receive flows on 127.0.0.1:5556) and tcp://127.0.0.1:5556 (ntopng connects to 127.0.0.1:5556 to receive flows). note that you can specify multiple endpoint, commas separated list, in order to instruct ntopng to aggregate it in a single interface. (e.g -i tcp://127.0.0.1:5556,ipc://flows.ipc) 🔥

if you want you can pass a path of a pcap file (e.g. -i dummy.pcap) or a path of a list file contains a path of a pcap file for each line (e.g. -i pcap.list) and ntopng will read packets from the specified pcap file/s. 🎀

nProbe can be instructed to act as a publisher delivering flows to a ZeroMQ endpoint using the --ZMQ <endpoint> parameter.

finally using -i dummy it is possible to create a dummy interface that generates a large number of flows/hosts in order to saturate ntopng resources. this way ntopng can be tested for performance issues as well proper handling of low-memory situations. stress test her, she can take it 💀

  • -d, --data-dir <path> — specifies the data directory (it must be writable). default directory is /var/lib/ntopng 💖
  • -t, --install-dir <path> — specifies the installation directory. default directory is retrieved from common install paths. 🔍
  • -G, --pid-path <path> — specifies the path where the PID (process ID) is saved. default is /var/run/ntopng.pid 🫶
  • -k, --traffic-filtering <key> — set the key used to access httpbl services (default: disabled). please read README.httpbl and README.flashstart for more info. go read the READMEs bestie, they're giving lore 📚
  • -e, --daemon — this parameter causes ntop to become a daemon, i.e. a task which runs in the background without connection to a specific terminal. to use ntop other than as a casual monitoring tool, you probably will want to use this option. she goes ghost mode 👻
  • -1, --httpdocs-dir <path> — directory where HTTP documents are placed. default: httpdocs. 🎀
  • -2, --scripts-dir <path> — directory where lua scripts reside. default: scripts. 🐍
  • -3, --callbacks-dir <path> — directory where callback scripts reside. default: scripts/callbacks. ✨
  • -w, --http-port <[:]http_port[,<alt_http_port>]> — sets the HTTP port of the embedded web server. if set to 0, the http server will be disabled. if you prepend a : before the port (i.e. -w :80) ntopng will listen to the loopback address. you can specify a second HTTP port so that ntopng can isten on both ports. Example: -w 80,3000 will start ntopng on both port 80 adn 3000. note that for enabling the captive portal (not available on the community edition) you need to start ntopng on port 80.
NOTE: omitting the -w option won't disable http: ntopng will fallback to the default http port. 😭 the way she just... serves anyway
  • -W, --https-port <[:]https_port> — sets the HTTPS port of the embedded web server. if not set, it will be set to the value of -w plus one. if you prepend a : before the port (i.e. -w :80) ntopng will listen to the loopback address. 🔒
  • -m, --local-networks <local_nets> — ntopng determines the ip addresses and netmasks for each active interface. any traffic on those networks is considered local. this parameter allows the user to define additional networks and subnetworks whose traffic is also considered local in ntopng reports. all other hosts are considered remote. if not specified the default is set to 192.168.1.0/24. 🏠

commas separate multiple network values. both netmask and CIDR notation may be used, even mixed together, for instance "131.114.21.0/24,10.0.0.0/255.0.0.0". mix and match, she doesn't judge 💅

  • -u, --no-promisc — disable promiscuous mode when capturing from network interfaces (by default promiscuous mode is used). 🙈
  • -p, --ndpi-protocols <file>.protos — this parameter is used to specify a nDPI protocol file. the format is <tcp|udp>:<port>,<tcp|udp>:<port>,.....@<proto> where <port> is a port number and <proto> is a name of a protocol supported by nDPI protocol, or host:"<string>"@<proto> where string is part of an host name. as example see https://svn.ntop.org/svn/ntop/trunk/nDPI/example/protos.txt 📖
  • -P, --disable-host-persistency — disable host persistency in the Redis cache. bye bye persistence ✌️
  • -q, --disable-autologout — disable web interface logout for inactivity. she stays logged in fr fr 💅
  • -l, --disable-login — disable user login. mode can be set to 0 (disable login only for localhost) or 1 (disable login only for all hosts). this is useful for debug purposes, local host access unrestricted, or if you want to let everyone access the web gui.
NOTE: this option lets anyone accessing the web interface (from localhost or from all hosts depending on the parameter) be administrator of the web interface. dangerous bestie — everyone gets admin energy and that is NOT the slay you think it is 😭
  • -r, --redis <redis_host[:port][@db — specifies the redis database host, port, and a database id. on unix <redis_host> can be the redis socket file to connect to. if a socket connection is made, <port> is ignored. in case you plan to run multiple redis-based applications on the same redis server, you need to use a different database id per application. for more information about redis, please refer to http://redis.io/. 🔴
  • -g, --core-affinity <cpu_core_id1[,cpu_core_id2,...]> — bind the capture/processing threads to specific CPU cores, indicated in a comma-separated list. cores are assigned to interface processing loops in the order interfaces are mapped to IDs.
NOTE: ntopng automatically sets affinity of capture/processing threads to different CPU cores. she's already doing it, she's just polite about it 💅
  • -U, --user <user> — run ntopng with the specified system user instead of 'nobody'. 👑
  • -s, --dont-change-user — do not change user (debug only). 🐛
  • -B, --packet-filter <filter> — specifies the packet filter for the specified interface. for pcap/PF_RING interfaces the filter has to be specified in BPF format (Berkeley Packet Filter). 🧚
  • -X, --max-num-flows <num> — specify the maximum number of active flows that ntopng will handle. if more flows are detected they will be discarded. 🗑️
  • -x, --max-num-hosts <num> — specify the maximum number of active hosts that ntopng will handle. if more hosts are detected they will be discarded. 💀
  • -F, --dump-flows <mode> — if ntopng is compiled with sqlite support, flows can dumped persistently on disk using this option. the mode can be set to:
    • es — Dump on ntopng.es queue in Elasticsearch format that be insert on a ES database. in this case the format is "es;<idx type>;<idx name>;<es URL>;<http auth>". Example: -F "es;ntopng;ntopng-%Y.%m.%d;http://localhost:9200/_bulk;user:pwd". the <idx name> accepts the strftime() format. 🌈
    • mysql — Dump flows in MySQL tables. in this case the format is "<host[@port]|unix socket>:<dbname>:<table>:<user>:<pw>". Example: -F "mysql;localhost;ntopng;flows-%Y.%m.%d;root;". 🍓
  • -D, --dump-hosts <mode> — so if ntopng got compiled with sqlite support, you can dump hosts contacts persistently to disk with this one. Databases get created daily under <data directory>/<interface>/contacts. There are three dump modes, bestie: local (only local hosts get dumped), remote (only remote hosts), and all (everybody gets dumped). And if you don't specify anything? Nothing gets dumped to disk. Periodt.
  • -I, --export-flows <endpoint> — this exports the expired flows to whatever endpoint you name. Say you're starting ntopng on host 1.2.3.4 like ntopng -I "tcp://*:3456" — it exports flows on that endpoint, which means you can build a whole hierarchy of ntopngs 🫶. You pull that off by starting a collector ntopng like ntopng -i tcp://1.2.3.4:3456.
  • -O, --communities-list <filename> — parses the file you give it and pulls out a list of communities, which are basically a logical representation of clusters of hosts that live under the same administrative domain. The file has GOT to be in this exact format:
communityX@id1=net1,net2,net3
communityY@id2=net4,net5,net6
...
  • -E, --dump-aggregations <mode> — again, only if ntopng is compiled with sqlite support: hosts contacts can be dumped persistently on disk with this option. Databases are created daily under <data directory>/<interface>/contacts. Three dump modes again: local (dumps only aggregations contacted by local hosts), remote (only aggregations contacted by remote hosts), all (all the aggregations). Not specified? Nothing gets dumped to disk, no cap.
  • -S, --sticky-hosts <mode> — ntopng periodically purges idle hosts, and this option lets you change up that behaviour by telling ntopng NOT to purge the hosts you pick with -S. It needs an argument, and your choices are all (keep all hosts in memory), local (keep only local hosts), remote (keep only remote hosts), and none (flush hosts when idle). Choose wisely 💅
  • --hw-timestamp-mode <mode> — enables hw timestamping/stripping. The supported TS modes are:
    • ixia — timestamped packets by ixiacom.com hardware devices.
  • -t, --install-dir <dir> — forces ntopng to use the HTML/lua files installed in the directory you specify. Lowkey do NOT use this unless you're testing or developing, because packaging systems should be placing those files in the right place themselves. It's giving "don't touch" 🚫
  • -T, --enable-taps <mode> — enables tap interfaces to dump packets on. If you don't specify it, traffic can only be dumped to disk but not sent live to apps.
  • -N, --instance-name <name> — assigns <name> to this ntopng instance. That info is used to uniquely identify the data source, so it's literally the ntopng user's responsibility to make sure the name is unique across all the ntopng instances. If you don't set this option, the instance name is assumed to be the hostname where this ntopng instance is running.
  • -Z, --http-prefix <prefix> — the HTTP prefix that gets prepended to URLs. Super useful when you're running ntopng behind a proxy. E.g. if you want the ntopng web interface reachable through a proxy at a certain IP address with the /ntopng/ base URL, and your proxy's configuration has these lines:
ProxyPass /ntopng/ http://192.168.0.3:3000/ntopng/
ProxyPassReverse /ntopng/ http://192.168.0.3:3000/ntopng/

then you must run ntopng with -Z "/ntopng".

Do NOT use trailing slashes in the HTTP prefix. Just don't. 😭
  • --shutdown-when-done — terminates ntopng when the input pcap file is over (debug only).
  • --zmq-encrypt-pwd — this is the password used by the symmetric encryption on the probe side. Heads up: if you have multiple ZMQ endpoints, the same password is used for all of them.
  • --capture-direction — specifies the packet capture direction for packet capture interfaces (no ZMQ). Supported values are: 0 = RX+TX (default), 1 = RX only, 2 = TX only.
  • --online-license-check — if your license doesn't match (say, you're running ntopng on a VM/container), you can use this to check your license instead of using the local license file. Doing it this way makes sure changes in your system don't interfere with the license check — which is a thing we cannot guarantee with file-based licenses, fr fr.
  • --print-ndpi-protocols — prints the list of nDPI protocols supported by the ntopng instance.
  • -v, --verbose — verbose tracing: level 2 is normal, level 6 is debugging.
  • -V, --version — prints the ntopng version and quits.
  • -h, --help — help 💖

🌸 WEB VIEWS 🌸

While ntopng is running, multiple users can access the traffic information using their web browsers. ntopng makes use of JavaScript and LESS CSS.

We do not expect problems with any current web browser, but our ability to test with the less common ones is very limited, ngl. Testing has included Safari, Chrome, Firefox and Internet Explorer, with very limited testing on other current common browsers such as Opera. So like… if yours is niche, no promises 🙈

⭐ NOTES ⭐

ntopng requires a number of external tools and libraries to operate. Certain other tools are optional, but they add to the program's capabilities.

Required libraries include:

  • libpcap from http://www.tcpdump.org/, version 1.0 or newer.
  • The Windows version makes use of WinPcap (libpcap for Windows) which may be downloaded from http://winpcap.polito.it/install/default.htm.
  • ntopng requires a POSIX threads library.
  • The rrdtool library creates 'Round-Robin databases' which are used to store historical data in a format that permits long duration retention without growing larger over time. The rrdtool home page is http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/
  • The LuaJIT library is a Just-In-Time Compiler for Lua used to execute GUI and periodic scripts.
  • The mongoose library is used to implement the HTTP server part of ntopng.
  • zeromq is a socket library supporting the publish/subscribe pattern used to collect flows from nProbe.

ntopng includes LuaJIT, mongoose, rrdtool and zeromq in the third-party/ directory. Users of ntopng should not need to specifically install such libraries. So you're covered, bestie 🎀

🦋 SEE ALSO 🦋

top(1), tcpdump(8), pcap(3).

💜 USER SUPPORT 💜

Please send bug reports to https://github.com/ntop/ntopng/issues. The ntopng <ntop@ntop.org> mailing list is used for discussing ntopng usage issues. In order to post messages on the lists a (free) subscription is required to limit/avoid spam. Please do NOT contact the authors directly unless this is a personal question.

Commercial support is available upon request. Please see the ntop site for further info.

Please send code patches via the github pull requests mechanism.

👑 LICENCE 👑

ntopng is distributed under the GNU GPLv3 licence (http://www.gnu.org/).

and that's the whole page, bestie 💖 this one's from Dev 2015, living in ntopng 2.2 era — old-school but iconic, and yes, NTOPNG(8) is still the section it calls home. now go read your traffic, main character 🌈✨

📦 where this page comes from