NTOP(8)

NAME
ntop - display top network users

SYNOPSIS
ntop [-a|--access-log-path <path>] [-c|--sticky-hosts] [-f|--traffic-dump-file file>] [-h|--help] [-j|--border-sniffer-mode] [-k|--filter-expression-in-extra-frame] [-l|--pcap-log <path>] [-m|--local-subnets <addresses>] [-n|--numeric-ip-addresses] [-p|--protocols <list>] [-q|--create-suspicious-packets] [-r|--refresh-time <number>] [-s|--no-promiscuous] [-t|--trace-level <number>] [-w|--http-server <port>] [-B|--filter-expression expression] [-D|--domain <name>] [-F|--flow-spec <specs>] [-M|--no-interface-merge] [-N|--no-nmap] [-O|----output-packet-path] [-P|--db-file-path <path>] [-R|--filter-rule <file>] [-S|--store-mode <number>] [-U|--mapper <URL>] [-V|--version] [--throughput-bar-chart] [--no-admin-password-hint] Not available on micro-ntop: [-e|--max-table-rows <number>] Unix options: [-d|--daemon] [-i|--interface <name>] [-u|--user <user>] [-E|--enable-external-tools] [-K|--enable-debug] [-L] [-use-syslog <facility>] Win32 option: [-i|--interface <number>] mySQL options: [-b|--sql-host <host:port>] [-v|--mysql-host <username:password:dbName>] OpenSSL option: [-W|--https-server <port>]

DESCRIPTION
ntop shows the current network usage. It displays a list of hosts that are currently using the network and reports information concerning the (IP and non-IP) traffic generated by each host. ntop can be started either in a terminal window (see intop ) or in web mode. In the latter case, a web browser is needed to use the program.

COMMAND-LINE OPTIONS
By default ntop logs HTTP accesses in the file ntop.access.log in the current directory. Use this flag to specify the path of the file where HTTP accesses will be logged. Each log entry is in Apache-like style. The only difference between Apache and ntop is that ntop added a new column has been added. Such column contains the time (in milliseconds) that ntop needed in order to serve the request. Exports ntop traffic information into a SQL database. The flag specifies (in http-like host format) the address (IP:port) of a SQL client. The database/ directory part of ntop contains a few clients. Please use one of those. By default idle hosts are periodically purged from memory. Use this flag to prevent idle hosts from being purged from memory. NOTE: if idle hosts are kept in memory you can experience severe memory usage. This flag causes ntop to become a daemon, i.e. it is started in background and detached from the terminal. Is the maximum number of HTML table rows that ntop will display. Specifies the file containing tcpdump captured traffic that has to be used by ntop. Note: if you specify -f ntop will not capture any traffic after the file has been read. This option is mostly used for debug purposes. Print help information for ntop , including usage. Specifies the network interface used by ntop If multiple interfaces are used (this feature is available only if ntop is compiled with thread support) they have to be separated with a comma. For instance -i "eth0,lo". Traffic information obtained by all the interfaces is merged together as if the traffic would have been produced by one interface. Use the -M flag for not merging traffic. Win32 note: This is the number of the interface, not it's name. Use ??? to see a list of interfaces. When this flag is used, ntop is supposed to be installed on a line where traffic is mirrored from a switch or another network appliance. When this flag is used, the current filter expression is printed in an extra frame and thus always visible. Dumps the network traffic captured by ntop in a file in pcap format (useful for debug). This flag allows users to specify the subnets whose traffic is considered local. The format is <network address>/<# subnet mask bits>[,<network address>/<# subnet mask bits>]. For instance "131.114.21.0/24,10.0.0.0/255.0.0.0". This causes ntop to show numeric IP addresses instead of the symbolic names. This option can useful when the DNS is not present or quite slow. You can toggle the address format (numeric vs. symbolic) by pressing the n key while ntop is running. It is used to specify the TCP/UDP protocols that ntop will monitor. The format is <label>=<protocol list> [, <label>=<protocol list>], where label is used to symbolically identify the <protocol list>. The format of <protocol list> is <protocol>[|<protocol>], where <protocol> is either a valid protocol specified inside the /etc/services file or a numeric port range (e.g. 80, or 6000-6500). If the -p flag is omitted the following default value is used: "FTP=ftp|ftp-data,HTTP=http|www|https,DNS=name|domain,Telnet=telnet|login,NBios-IP=netbios-ns|netbios-dgm|netbios-ssn,Mail=pop-2|pop-3|kpop|smtp|imap|imap2,SNMP=snmp|snmp-trap,NEWS=nntp,NFS=mount|pcnfs|bwnfs|nfs|nfsd-status,X11=6000-6010,SSH=ssh". If the <protocol list> is very long you may store in a file (for instance protocol.list) the value of the <protocol list> and specify the file name instead of the <protocol list> (in above example you will invoke 'ntop -p protocol.list'). Forces ntop to create a file ntop-suspicious-pkts.XXX.pcap (XXX is the interface name) for each network interface where are stored suspicious packets. The file is in pcap format (tcpdump). Specifies the delay (in seconds) between screen updates (the default is 3 seconds). If the -l flag is used, it specifies how often entries are logged in the log file. Please note that if the delay is very short (1 second for instance), ntop might not be able to process all the network traffic. Use this flag for disabling interface promiscuous mode (i.e. the ability to capture ethernet frames regardless whether they are directed to the local ethernet card or to the ethernet broadcast address). Note that even if you use this flag, the interface could well be in promiscuous mode as other applications can have enabled this functionality. This flag specifies the level of ntop tracings on stdout. The trace level ranges between 0 (no trace) and 5 (full debug tracings). The default trace value is 3. The higher is the trace level the more information are printed. Trace level 1 is used to print errors only, level 2 for both warnings and errors, and so on. Specifies the user ntop should run as after it initializes. The value specified may be either a username or a numeric user id. The group id used will be the primary group of the user specified. Specifies the mySQL database connection information (user:password:database:host). ntop sports an embedded web server so that users can attach their web browsers to the specified port and browse traffic information remotely. Supposing to start ntop at the port 3000 (default port), the URL to access is http://hostname:3000/. Users and URLs to protect with passwords are stored in a database file. By default user/URL administration are accessible uniquely by the user admin with password admin Passwords are stored in an encrypted form into the database for further security. Please note that an HTTP server is NOT needed but it's embedded into the application. If -w is set to 0 the HTTP port will not be enabled ('-w 0' is accepted only if ntop
 has been compiled with HTTPS support and ntop has not been started with '-W 0' [see below]). You can also use the IP:Port notation to bind ntop to the specified IP-Address, e.g. -w 127.0.0.1:3000 ntop , similar to what tcpdump does, allows users to specify an expression that restricts the type of traffic handled by ntop hence to select only the traffic of interest. For instance, suppose to be interested only in the traffic generated/received by the host jake.unipi.it. ntop can then be started with the following filter: 'ntop src host jake.unipi.it or dst host jake.unipi.it'. See the tcpdump man page for further information about this topic. This identifies the local domain suffix, e.g. ntop.org, if ntop is having difficulty determining it from the interface. By default ntop does not take advance of lsof/nmap even if present. Use this flag if you want make ntop aware of such tools (if present). It is used to specify network flows similar to more powerful applications such as NeTraMet. A flow is a stream of captured packets that match a specified rule. The format is <flow-label>='<matching expression>'[,<flow-label>='<matching expression>'], where the label is used to symbolically identify the flow specified by the expression. The expression format is specified in the appendix. If an expression is specified, then the information concerning flows can be accessed following the HTML link named 'List NetFlows'. For instance suppose to define two flows with the following expression "LucaHosts='host jake.unipi.it or host pisanino.unipi.it',GatewayRoutedPkts='gateway gateway.unipi.it'". All the traffic sent/received by hosts jake.unipi.it or pisanino.unipi.it is collected by ntop and added to the LucaHosts flow, whereas all the packet routed by the gateway gateway.unipi.it are added to the GatewayRoutedPkts flow. If the flows list is very long you may store in a file (for instance flows.list) the list of flows and specify the file name instead of the flows list (in above example you will invoke 'ntop -F flows.list'). Use this flag to simplify application debug (eg. fork() is not used etc.) Use this flag for using the syslog instead of stdout. Please note that if ntop (ever) forks a child, in any case the syslog will be used for this child. Use this flag for using the syslog instead of stdout. The parameter value indicates the facility (e.g. daemon, security) to be used for logging. Please note that if ntop (ever) forks a child, in any case the syslog will be used for this child. Forces ntop not to merge network interfaces together. This means that ntop will collect statistics for each interface and will not merge data together. Forces ntop not to use nmap (if it is installed). Base path for the ntop-suspicious-pkts.XXX.pcap and normal packet log file (tcpdump). If the base path is a directory you have to append a / to the string for this to work fine. This allows to specify where db-files are searched or created (default "."). In addition DBPATH/html is added to the searchlist for the WEB-files Use this flag for telling ntop to save information about host traffic on shutdown. Valid values are: 0 = don't store hosts, 1 = store all hosts, 2 = store only local hosts. This flag allows ntop not to loose traffic stats across multiple ntop sessions. Please note that information about TCP session is (obviously) lost. It specifies the UTR of the mapper.pl utility (it's part of the ntop distribution [see www/Perl/mapper.pl]) for displaying host location. If you don't want to install a mapper use http://jake.ntop.org/cgi-bin/mapper.pl Prints ntop version information and then exits. If ntop has been compiled with HTTPS support (via OpenSSL), this flag can be used to set the HTTPS port (default 3001 ). If the user specifies '-W 0', HTTPS support is disabled. Some examples: 1. ntop -w 80 -W 443 (both HTTP and HTTPS have been enabled at their default ports) 2. ntop -w 0 -W 443 (HTTP disabled, HTTPS enabled at the default port). You can also use the IP:Port notation to bind ntop to the specified IP-Address, e.g. -w 127.0.0.1:3001 Format the throughput charts with bars instead of as an area chart. Supppresses the hint about the (default) admin password in the dialog boxes.

WEB VIEWS
While ntop is running, multiple users can access the traffic information using conventional web browsers. The main HTML page, is divided is two frames. The left frame allows users to select the traffic view that will be displayed in the right frame. Available sections are: sort traffic by data sent, sort traffic by data received, traffic statistics, active hosts list, remote to local (i.e. inside the subnet defined for the network board from which the program is currently sniffing) IP traffic, local to remote IP traffic, local to local IP traffic, list of active TCP sessions, IP protocol distribution statistics, IP protocol usage, IP traffic matrix.

NOTES
ntop requires a number of external tools. Other tools are optional, but add to the program's capabilities. Operating system header files and the Gnu gcc compiler and glibc libraries (http://www.gnu.org), including the glibc development libraries. Required libraries include (see the output of ./configure for a fuller listing) Posix threads, ncrypt, readline and: libpcap from http://www.tcpdump.org/ (The Win32 version makes use of libpcap for Win32 which may be downloaded from http://www.netgroup.polito.it/WinPcap/install/). gdb from http://www.gnu.org/software/gdbm/gdbm.html Optional libraries include: The gdchart library, available at http://www.fred.net/brv/chart/. The gd library, for the creation of gif files, available at http://www.boutell.com/gd/ (included with gdchart). The libpng library, for the creation of png files, available at mySQL available at http://www.mysql.com/ openSSL from the OpenSSL project, if an https:// server is desired, available at http://www.openssl.org. The sflow Plugin is courtesy of and supported by InMon Corporation, http://www.inmon.com/sflowTools.htm. Options tools - which ntop will utilize if available - include nmap (http://www.insecure.org) and lsof (ftp://vic.cc.purdue.edu/pub/tools/unix/lsof/README).

SEE ALSO
intop(1), top(1), tcpdump(8).

AUTHOR
Please send bug reports to the ntop mailing list <ntop@ntop.org>. Please code patched to <patch@ntop.org>. ntop's author is Luca Deri and can be reached at deri@ntop.org. Tool locations are current as of February 2002 - please send email to report new locations or dead links.