NTOP

NAME
SYNOPSIS
DESCRIPTION
COMMAND−LINE OPTIONS
WEB VIEWS
NOTES
SEE ALSO
AUTHOR

NAME

ntop − display top network users

SYNOPSIS

ntop [@filename] [-a|--access-log-path <path>] [-b|--disable-decoders] [-c|--sticky-hosts] [-f|--traffic-dump-file file>] [-g|--track-local-hosts] [-h|--help] [-k|--filter-expression-in-extra-frame] [-l|--pcap-log <path>] [-m|--local-subnets <addresses>] [-n|--numeric-ip-addresses] [-o|--no-mac] [-p|--protocols <list>] [-q|--create-suspicious-packets] [-r|--refresh-time <number>] [-s|--no-promiscuous] [-t|--trace-level <number>] [-w|--http-server <port>] [-z|--disable-sessions] [-A|--set-admin-password password] [-B|--filter-expression expression] [-C|--large-network] [-D|--domain <name>] [-F|--flow-spec <specs>] [-M|--no-interface-merge] [-O|----output-packet-path] [-P|--db-file-path <path>] [-R|--filter-rule <file>] <number>] [-U|--mapper <URL>] [-V|--version] [--throughput-bar-chart] [--dynamic-purge-limits] [--reuse-rrd-graphics] [--p3p-cp] [--p3p-uri] [--disable-stopcap]

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>] [--ignore-sigpipe]

Win32 option:

[-i|--interface <number>]

OpenSSL options:

[-W|--https-server <port>] [--use-sslwatchdog]

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 may operate as a front-end collector (sFlow and/or netFlow plugins) or as a stand-alone collector/display program. A web browser is needed to access the information captured by the ntop program.

An older, and unsupported version, intop can be started in a terminal window.

COMMAND−LINE OPTIONS

@filename

The text of filename is copied - ignoring line breaks and comment lines (anything following a #) - into the command line. ntop behaves as if all of the text had simply been typed directly on the command line. For example, if the command line is "-t 3 @d -u ntop" and file d contains just the line ’-d’, then the effective command line is -t 3 -d -u ntop. Multiple @s are permitted.

Remember, most ntop options are "sticky", that is they just set an internal flag. Invoking them multiple times doesn’t change ntop’s behavior. However, options that set a value, such as --trace-level, will use the LAST value given: --trace-level 2 --trace-level 3 will run as --trace-level 3.

-a | --access-log-path

By default ntop does not maintain an http log. 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 an additional column has been added which has the time (in milliseconds) that ntop needed in order to serve the request.

-b | --disable-decoders

This flag disables protocol decoders (e.g. DNS, NetBIOS). Use it for better performance or if you feel ntop has problem handling some protocols.

-c | --sticky-hosts

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.

-d | --daemon

This flag causes ntop to become a daemon, i.e. it is started in background and runs detached from the terminal.

-e | --max-table-rows

Is the maximum number of HTML table rows that ntop will display.

-f | --traffic-dump-file

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.

-g | --track-local-hosts

Use this flag to tell ntop that you do care only about local hosts (use -m to specify local nets). This flag is useful on large networks or those that see many hosts, (e.g. a border router or gateway), yet only the local ones need to be tracked.

-h | --help

Print help information for ntop , including usage.

-i | --interface

Specifies the network interface used by ntop

If multiple interfaces are used (this feature is available only if ntop is compiled with thread support) their names must be separated with a comma. For instance -i "eth0,lo".

By default, traffic information obtained by all the interfaces is merged together as if the traffic were seen by only one interface. Use the -M flag to keep traffic separate by interface.

Win32 note: This is the number of the interface, not it’s name. Run ntop -h to see a list of interface name-number mappings (at the end of the help information).

-k | --filter-expression-in-extra-frame

When this flag is used, the current filter expression is printed in an extra frame and thus always visible.

-l | --pcap-log

Dumps the network traffic captured by ntop in a file in pcap format (useful for debug).

-m | --local-subnets

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>]. Both netmasks and CIDR notation may be used, for instance "131.114.21.0/24,10.0.0.0/255.0.0.0".

-n | --numeric-ip-addresses

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. Under intop, you can toggle the address format (numeric vs. symbolic) by pressing the n key while intop is running.

-o | --no-mac

Specifies the user ntop should not trust MAC addresses but just IP addresses. This option is useful whenever ntop is started on an interface where MAC addresses cannot be really trusted (e.g. port/VLAN mirror).

Be aware that information which is dependent upon the MAC addresses (such as IPX) will not be collected nor displayed.

-p | --protocols

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|3128 3128 is Squid, the HTTP cache DNS=name|domain Telnet=telnet|login NBios-IP=netbios-ns|netbios-dgm|netbios-ssn Mail=pop-2|pop-3|pop3|kpop|smtp|imap|imap2 DHCP-BOOTP=67-68 SNMP=snmp|snmp-trap NNTP=nntp NFS=mount|pcnfs|bwnfs|nfsd|nfsd-status X11=6000-6010 SSH=22

Peer-to-Peer Protocols ---------------------- Gnutella=6346|6347|6348 Kazaa=1214 WinMX=6699|7730 DirectConnect=0 Dummy port as this is a pure P2P protocol eDonkey=4661-4665

Instant Messenger ----------------- Messenger=1863|5000|5001|5190-5193

If the <protocol list> is very long you may store it in a file (for instance protocol.list). To do so, specify the file name instead of the <protocol list> on the command line. e.g. ntop -p protocol.list instead of ntop -p FTP=ftp|ftp-data,HTTP=http|www|https|3128 ...

-q | --create-suspicious-packets

Forces ntop to create a file ntop-suspicious-pkts.XXX.pcap (XXX is the interface name) file. One file is created for each network interface where suspicious packets are found. The file is in pcap format (tcpdump).

-r | --refresh-time

Specifies the delay (in seconds) between screen updates (the default is 3 seconds).

Please note that if the delay is very short (1 second for instance), ntop might not be able to process all the network traffic.

-s | --no-promiscuous

Use this flag for preventing from setting the interface(s) into promiscuous mode.

ntop must probably still be started as root, since the libpcap function on most systems require it to capture raw packets.

This eliminates the ability of capturing ethernet frames regardless of whether they are directed to the local ethernet card or to the ethernet broadcast address.

Even if you use this flag, the interface could well be in promiscuous mode as other applications may have enabled it.

-t | --trace-level

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.

Trace level 4 is called ’noisy’ and it is. It also enables a MSGID-nnnnn tag on every message, which may be useful for log watchers.

-u | --user

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. If this parameter is not specified, ntop will try to switch first to ’nobody’ and then to ’anonymous’ before giving up.

-w | --http-server

ntop offers an embedded web server so that users can attach their web browsers to the program and browse traffic information remotely. This parameter specifies the port (and optionally the address (i.e. interface)) of the ntop web server. For example, if started with -w 3000 (the default port), the URL to access ntop is http://hostname:3000/. If started with a full specification, e.g. -w 192.168.1.1:3000, ntop listens on only that address/port combination.

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 has not been started with ’-W 0’ [see below]).

Some examples:

ntop -w 3000 -W 0 (this is the default setting) HTTP requests on port 3000 and no HTTPS.

ntop -w 80 -W 443 Both HTTP and HTTPS have been enabled on their most common ports.

ntop -w 0 -W 443 HTTP disabled, HTTPS enabled on the common port.

An external HTTP server is NOT required NOR supported. The ntop web server is embedded into the application.

By default user/URL administration are password protected and are accessible initially only user admin with a password set during the first run of ntop

Users can modify/add/delete users/URLs using ntop itself - see the Admin tab.

The passwords, userids and URLs to protect with passwords are stored in a database file. Passwords are stored in an encrypted form in the database for further security.

-z | --disable-sessions

This flag disables TCP session tracking. Use it for better performance or when you don’t really need/care to track sessions.

-A | --set-admin-password

This flag is used to start ntop , set the admin password and quit. It is quite useful for installers that may need to automatically set the password for the admin user.

-A and --set-admin-password (without a value) will prompt the user for the password.

You may set a specific value using --set-admin-password=value. The = is REQUIRED!

-B | --filter-expression

ntop , similar to what tcpdump does (and using the same BPF - Berkeley Packet Filter syntax), this allows the user to specify an expression which restricts the traffic seen by ntop You may use this to select only the traffic of interest. For instance, suppose you are interested only in the traffic generated/received by the host jake.unipi.it. ntop can then be started with the following filter: ’ntop -B "src host jake.unipi.it or dst host jake.unipi.it"’. i

See the ’expression’ section of the tcpdump man page for further information about BPF filters.

-C | --large-network

This flag is a hint for ntop : as the network being analyzed will be large, ntop will build a more efficient hash and save memory by disabling some features (e.g traffic distribution during the day) that take up a large amount of memory.

-D | --domain

This identifies the local domain suffix, e.g. ntop.org. It may be necessary, if ntop is having difficulty determining it from the interface.

-E | --enable-external-tools

By default ntop does not take advance of lsof even if present. Use this flag if you want make ntop enable it’s use of lsof if lsof is present.

-F | --flow-spec

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 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) and specify the file name instead of the actual flows list (in the above example, this would be ’ntop -F flows.list’).

-K | --enable-debug

Use this flag to simplify application debug. It does three things: 1. Does not fork() on the "read only" html pages. 2. Displays mutex values on the configuration (info.html) page. 3. (If available - glibc/gcc) Activates an automated backtrace on application errors.

-L | --use-syslog=facility

Use this flag for using the syslog instead of stdout. Please note that if ntop (ever) forks a child, regardless of this setting, the syslog will be used for this child. The (optional) parameter value indicates the facility (e.g. daemon, security) to be used for logging, using --use-syslog=facility. The = is REQUIRED!

-M | --no-interface-merge

Forces ntop not to merge network interfaces together. This means that ntop will collect statistics for each interface and report them separately - see Admin | Switch NIC to select which interface to report.

Note that the netFlow and sFlow plugins will force the setting of -M.

-O | --output-packet-path

Base path for the ntop-suspicious-pkts.XXX.pcap and normal packet log file (in tcpdump format). If the base path is a directory you have to append a / to the string for this to work.

-P | --db-file-path

This specifies where ntop db files are created.

Note that the default, "." may not be what you expect when running ntop as a daemon or Win32 service. Setting an explicit value is STRONGLY recommended.

-U | --mapper

Specifies the URL of the mapper.pl utility. ntop creates a hyperlink to this URL by appending ?host=xxxxx and creates a clickable button. Any type of host lookup could be performed, but this is intended to lookup the geographical location of the host.

A cgi-based mapper interface to http://www.multimap.com is part of the ntop distribution [see www/Perl/mapper.pl]).

-V | --version

Prints ntop version information and then exits.

-W | --https-server

If ntop has been compiled with HTTPS support (via OpenSSL), this flag can be used to set the HTTPS port and address. If the user specifies ’-W 0’, HTTPS support is disabled. This is the default (disabled).

For more information, see the -w parameter above.

--throughput-bar-chart

Format the throughput charts with bars instead of as an area chart.

--dynamic-purge-limits

Enable a dynamic adjustment of the idle host purge limits. Normally the purge is limited to 1/3 of the hash size or 512 hosts (whichever is smaller) per cycle. This switch allows ntop to dynamically adjust the limit so that the purge takes between 0.5 and 5.0 seconds (but the minimum dynamic limit is 64 per cycle). These values may be adjusted via compile time constants.

--reuse-rrd-graphics

Enable the reuse of rrd graphics if appropriate (no rrd updates in the interim). By default, with the flag not set, the graphics are recreated for each request.

--p3p-cp

Tells ntop what to return in the p3p header, cp="xxxx".

--p3p-uri

Tells ntop what to return in the p3p header, policyref="xxxx".

--disable-stopcap

Return ntop to the old (v2.1) behavior on a memory error. The default of stopcap enabled makes the web interface available albeit with static content until ntop is shutdown.

--ignore-sigpipe

Enable a handler for SIGPIPE errors. This usually happens only under debug (gdb). (also available as a ./configure option, --enable-ignoresigpipe)

--use-sslwatchdog

Enables a ’watchdog’ for ntop webserver hangs. These usually happen when connecting with Netscape 6.2.2 and some other browsers - but only via https:// urls.

The symptom is that the user gets nothing back and other users can’t connect. Internally, the web server hangs in SSL_accept(). While packet processing continues, there is no way to access the data through the web server or shutdown ntop cleanly.

With the watchdog, a timeout occurs after 3 seconds, and processing continues with a log message. Unfortunately, the user sees nothing - it just looks like a failed connection. (also available as a ./configure option, --enable-sslwatchdog)

WEB VIEWS

While ntop is running, multiple users can access the traffic information using conventional web browsers. The main HTML page is divided is three frames. The top frame is a familiar tabbed navigation bar, containing items such as ’Total’, ’Sent’ and ’IP Protos’. The left frame allows users to select the specific traffic view from among those for the tab. The resulting data will be displayed in the right frame.

NOTES

ntop requires a number of external tools. Other tools are optional, but add to the program’s capabilities.

Required libraries include:

libpcap from http://www.tcpdump.org/

The Win32 version makes use of libpcap for Win32 which may be downloaded from http://winpcap.polito.it/install/default.htm). WARNING: The 2.x series of libpcap for Win32 releases will NOT support SMP machines.

gdbm from http://www.gnu.org/software/gdbm/gdbm.html

ntop requires a POSIX threads library. Although a single-threaded version of ntop can be built from the source if requested during ./configure, it is not recommended for more than trivial usage.

intop requires ncrypt and readline.

Optional libraries include:

The gdchart library, available at http://www.fred.net/brv/chart/. Note that ntop distributes an enhanced version of gdchart, 0.94c, as part of the ntop source tree. ntop has not be tested with the (development/beta) releases of gdchart (the 0.10 and 0.11 series).

The gd library, for the creation of gif files, available at http://www.boutell.com/gd/. The 1.8.3 version of gd is included with gdchart 0.94c in the ntop source tree. ntop has not been tested with any other version.

The libpng library, for the creation of png files, available at http://www.libpng.org/pub/png/libpng.html. Note that a version of libpng, 1.2.4, is distributed with the ntop source tree. ntop will also work with the 1.0.x series, which is distributed in many Linux distribtions.

HOWEVER the two series, 1.0 and 1.2, are not compatible nor interoperable. If compiled against one version and executing against another, ntop will fail to create graphics.

There is logic in the build script (gdchart0.94c/buildAll.sh) and in the program to attempt to catch this and rectify the problem or notify the user. This may not work in all cases. If you have a problem with graphics not being produced, check the ntop log and check the installed versions of libpng.

(if an https:// server is desired) openSSL from the OpenSSL project available at http://www.openssl.org.

The rrdtool is required by the rrd plugin. rrdtool creates ’Round-Robin databases’ which are used to hold and graph historical data. The rrdtool home page is http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/

ntop has been tested with rrdtool versions 1.0.38 -> 1.0.41. ntop has NOT been (successfully) tested with the rrdtool development versions, and there are significant differences between the two branches.

Also, please note that there is a patched version of rrdtool 1.0.41 available in the ntop files area of SourceForge. This contains a bug fix (which will be part of rrdtool 1.0.42 when released). Without this fix, ntop may - rarely - crash during the create/update of an rrd.

The sflow Plugin is courtesy of and supported by InMon Corporation, http://www.inmon.com/sflowTools.htm.

There are other optional libraries. See the output of ./configure for a fuller listing.

An optional tool, which ntop will utilize if available, is lsof available from ftp://vic.cc.purdue.edu/pub/tools/unix/lsof/README.

lsof is used to present a remote view of the open files on the ntop host.

Note that lsof must be configured suid root to enable it’s use. The user is cautioned to fully understand the security implications of this setting before enabling it. ntop will function quite properly without the lsof tool.

SEE ALSO

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

AUTHOR

Please send bug reports to the ntop mailing list <ntop@ntop.org>. Please send code patches to <patch@ntop.org>.

ntop’s author is Luca Deri who can be reached at deri@ntop.org.

Tool locations are current as of April 2003 - please send email to report new locations or dead links.