NTOP(8)                                                                NTOP(8)



[1mNAME[0m
       ntop - display top network users

[1mSYNOPSIS[0m
       [1mntop  [22m[[1m@filename[22m] [[1m-a[22m|[1m--access-log-path [4m[22m<path>[24m] [[1m-b[22m|[1m--disable-decoders[22m]
       [[1m-c[22m|[1m--sticky-hosts] [22m[[1m-f[22m|[1m--traffic-dump-file  [4m[22mfile>[24m]  [[1m-g[22m|[1m--track-local-[0m
       [1mhosts[22m]  [[1m-h[22m|[1m--help[22m] [[1m-k[22m|[1m--filter-expression-in-extra-frame[22m] [[1m-l[22m|[1m--pcap-[0m
       [1mlog   [4m[22m<path>[24m]   [[1m-m[22m|[1m--local-subnets   [4m[22m<addresses>[24m]    [[1m-n[22m|[1m--numeric-ip-[0m
       [1maddresses[22m]  [[1m-o[22m|[1m--no-mac[22m]  [[1m-p[22m|[1m--protocols  [4m[22m<list>[24m] [[1m-q[22m|[1m--create-suspi-[0m
       [1mcious-packets[22m]   [[1m-r[22m|[1m--refresh-time   [4m[22m<number>[24m]   [[1m-s[22m|[1m--no-promiscuous[22m]
       [[1m-t[22m|[1m--trace-level  [4m[22m<number>[24m]  [[1m-w[22m|[1m--http-server  [4m[22m<port>[24m] [[1m-z[22m|[1m--disable-[0m
       [1msessions[22m]  [[1m-A[22m|[1m--set-admin-password  [4m[22mpassword[24m]  [[1m-B[22m|[1m--filter-expression[0m
       [4mexpression[24m]  [[1m-D[22m|[1m--domain  [4m[22m<name>[24m]  [[1m-F[22m|[1m--flow-spec  [4m[22m<specs>[24m] [[1m-M[22m|[1m--no-[0m
       [1minterface-merge[22m] [[1m-O[22m|[1m----output-packet-path[22m] [[1m-P[22m|[1m--db-file-path [4m[22m<path>[24m]
       [[1m-Q[22m|[1m--spool-file-path   [4m[22m<path>[24m]   [[1m-R[22m|[1m--filter-rule  [4m[22m<file>[24m]  [4m<number>[24m]
       [[1m-U[22m|[1m--mapper  [4m[22m<URL>[24m]  [[1m-V[22m|[1m--version]  [22m[[1m--disable-stopcap[22m]  [[1m--log-extra[0m
       [4m<number>[24m] [[1m--disable-instantsessionpurge[22m] [[1m--disable-schedyield[22m]

       Unix options:

       [[1m-d[22m|[1m--daemon[22m]  [[1m-i[22m|[1m--interface [4m[22m<name>[24m] [[1m-u[22m|[1m--user [4m[22m<user>[24m] [[1m-K[22m|[1m--enable-[0m
       [1mdebug[22m] [[1m-L[22m] [[1m-use-syslog= [4m[22m<facility>[24m]

       Windows option:

       [[1m-i[22m|[1m--interface [4m[22m<number|name>[24m]

       OpenSSL options:

       [[1m-W[22m|[1m--https-server [4m[22m<port>[24m]


[1mDESCRIPTION[0m
       [1mntop [22mshows 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.  [1mntop [22mmay 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 infor-
       mation captured by the [1mntop [22mprogram.

       [1mntop  [22mis a hybrid layer 2 / layer 3 network monitor, that is by default
       it uses the layer 2 Media Access Control (MAC) addresses AND the  layer
       3 tcp/ip addresses.  [1mntop [22mis 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.



[1mCOMMAND-LINE OPTIONS[0m
       [1m@filename[0m
        The  text  of  [1mfilename  [22mis  copied - ignoring line breaks and comment
        lines (anything following a #) - into the command line.  [1mntop  [22mbehaves
        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. Nested @s  (an  @  inside  the
        file) are not permitted.

        Remember,  most  [1mntop  [22moptions  are "sticky", that is they just set an
        internal flag. Invoking them  multiple  times  doesn't  change  [1mntop's[0m
        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.


       [1m-a | --access-log-path[0m
        By default [1mntop [22mdoes not maintain a log of HTTP requests to the inter-
        nal web server.  Use this parameter to request logging and to  specify
        the location of the file where these HTTP requests are logged.

        Each  log  entry is in Apache-like style.  The only difference between
        Apache and [1mntop [22mlogs is that an additional column has been added which
        has  the time (in milliseconds) that [1mntop [22mneeded to serve the request.
        Log entries look like this:

        192.168.1.1 - - [04/Sep/2003:20:38:55 -0500] - "GET / HTTP/1.1" 200 1489 4
        192.168.1.1 - - [04/Sep/2003:20:38:55 -0500] - "GET /index_top.html HTTP/1.1" 200 1854 4
        192.168.1.1 - - [04/Sep/2003:20:38:55 -0500] - "GET /index_inner.html HTTP/1.1" 200 1441 7
        192.168.1.1 - - [04/Sep/2003:20:38:56 -0500] - "GET /index_left.html HTTP/1.1" 200 1356 4
        192.168.1.1 - - [04/Sep/2003:20:38:56 -0500] - "GET /home_.html HTTP/1.1" 200 154/617 9
        192.168.1.1 - - [04/Sep/2003:20:38:56 -0500] - "GET /home.html HTTP/1.1" 200 1100/3195 10
        192.168.1.1 - - [04/Sep/2003:20:38:56 -0500] - "GET /About.html HTTP/1.1" 200 2010 10

        Although this parameter is called a 'path', it is  actually  the  com-
        plete file name of the access log.


       [1m-b | --disable-decoders[0m
        This parameter disables protocol decoders.

        Protocol decoders examine and collect information about layer 2 proto-
        cols such as NetBIOS or Netware SAP, as well as about specific  tcp/ip
        (layer 3) protocols, such as DNS, http and ftp.

        This  support is specifically coded for each protocol and is different
        from the capability to count raw information (packets  and  bytes)  by
        protocol specified by the -p | --protocols parameter, below.

        Decoding protocols is a significant consumer of resources. If the [1mntop[0m
        host is underpowered or monitoring a very busy network, you  may  wish
        to  disable  protocol  decoding  via  this  parameter.  It may also be
        appropriate to use this parameter if you believe that [1mntop  [22mhas  prob-
        lems handling some protocols that occur on your network.

        Even  if  decoding  is  disabled, ftp-data traffic is still decoded to
        look for passive ftp port commands.


       [1m-c | --sticky-hosts[0m
        Use this parameter to prevent idle hosts from being purged  from  mem-
        ory.

        By  default  idle  hosts are periodically purged from memory.  An idle
        host is identified when no packets from or to that host have been mon-
        itored   for   the   period   of   time   defined   by  the  value  of
        PARM_HOST_PURGE_MINIMUM_IDLE in globals-defines.h.

        If you use this option, all hosts - active and idle - are retained  in
        memory for the duration of the [1mntop [22mrun.

        P2P  users,  port  scans,  popular web servers and other activity will
        cause [1mntop [22mto record data about a large number of hosts.  On an active
        network, this will consume a significant - and always growing - amount
        of memory.  It is  strongly  recommended  that  you  use  a  filtering
        expression  to  limit  the hosts which are stored if you use --sticky-
        hosts.

        The idle purge is a statistical  one  -  a  random  selection  of  the
        eligible  hosts will be purged during each cycle.  Thus it is possible
        on a busy system for an idle host to remain in  the  [1mntop  [22mtables  and
        appear 'active' for some considerable time after it is truly idle.


       [1m-d | --daemon[0m
        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
        [1mntop [22mother than as a casual monitoring tool, you probably will want to
        use this option.

        [1mWARNING: [22mIf you are running as a daemon, the messages from  [1mntop  [22mwill
        be  'printed'  on to stdout and thus dropped.  You probably don't want
        to do this.  So remember to also use the -L or --use-syslog options to
        save the messages into the system log.


       [1m-e | --max-table-rows[0m
        This  defines  the  maximum  number of lines that [1mntop [22mwill display on
        each generated HTML page. If there are more lines to be displayed than
        this  setting permits, only part of the data will be displayed.  There
        will be page forward/back arrows placed at the bottom of the page  for
        navigation between pages.


       [1m-f | --traffic-dump-file[0m
        By  default, [1mntop [22mcaptures traffic from network interface cards (NICs)
        or from netFlow/sFlow probes.  However, [1mntop [22mcan also read data from a
        file  - typically a tcpdump capture or the output from one of the [1mntop[0m
        packet capture options.

        if you specify -f, [1mntop [22mwill not capture any traffic from NICs  during
        or after the file has been read.  netFlow/sFlow capture - if enabled -
        would still be active.

        This option is mostly used for debug purposes.


       [1m-g | --track-local-hosts[0m
        By default, [1mntop [22mtracks all hosts that it sees from  packets  captured
        on  the various NICs.  Use this parameter to tell [1mntop [22mto capture data
        only about  local  hosts.   Local  hosts  are  defined  based  on  the
        addresses  of  the NICs and those networks identified as local via the
        -m | --local-subnets parameter.

        This parameter is useful on large networks  or  those  that  see  many
        hosts,  (e.g.  a  border  router  or gateway), where information about
        remote hosts is not desired/required to be tracked.


       [1m-h | --help[0m
        Print help information for [1mntop, [22mincluding usage and parameters.


       [1m-i | --interface[0m
        Specifies the network interface or interfaces to be used by  [1mntop  [22mfor
        network monitoring.

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

        If not specified, the default is the first Ethernet device, e.g. eth0.
        The specific device that is 'first' is highly system dependent.  Espe-
        cially  on  systems  where  the  device  name reflects the driver name
        instead of the type of interface.

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

        Under Windows, the parameter value is either the number of the  inter-
        face  or  its name, e.g.  {6252C14C-44C9-49D9-BF59-B2DC18C7B811}.  Run
        [1mntop [22m-h to see a list of interface name-number mappings (at the end of
        the help information).


       [1m-k | --filter-expression-in-extra-frame[0m
        When  this  parameter  is  used, the current filter expression is dis-
        played in an extra frame and thus is always visible.  This extra frame
        contains  other  information, including the report creation date, [1mntop[0m
        version information and the active interfaces.


       [1m-l | --pcap-log[0m
        This parameter causes a dump file to be created of the network traffic
        captured  by  [1mntop  [22min tcpdump (pcap) format.  This file is useful for
        debug, and may be read back into [1mntop [22mby the -f |  --traffic-dump-file
        parameter.   The dump is made after processing any filter expression (
        never even sees filtered packets).

        The output file will  be  named  [4m<path>/<log>.<device>.pcap[24m  (Windows:
        [4m<path>/<log>.pcap[24m  ),  where  <path>  is defined by the -O | --output-
        packet-path parameter and <log> is defined by  this  -l  |  --pcap-log
        parameter.


       [1m-m | --local-subnets[0m
        [1mntop  [22mdetermines  the ip addresses and netmasks for each active inter-
        face.  Any traffic on those networks is considered local.  This param-
        eter  allows  the  user  to define additional networks and subnetworks
        whose traffic is also considered local  in  [1mntop  [22mreports.  All  other
        hosts are considered remote.

        Commas  separate multiple network values.  Both netmask and CIDR nota-
        tion   may   be   used,   even   mixed    together,    for    instance
        "131.114.21.0/24,10.0.0.0/255.0.0.0".

        The  local  subnet  - as defined by the interface address(es) - is/are
        always local and do not need to be specified.  If you do give the same
        value  as a NIC's local address, a harmless warning message is issued.


       [1m-n | --numeric-ip-addresses[0m
        By default, [1mntop [22mresolves IP addresses using a combination  of  active
        (explicit)   DNS  queries  and  passive  sniffing.   Sniffing  of  DNS
        responses occurs when [1mntop [22mreceives a network  packet  containing  the
        response  to some other user's DNS query.  [1mntop [22mcaptures this informa-
        tion and enters it into [1mntop's [22mDNS cache, in  expectation  of  shortly
        seeing  traffic  addressed  to  that host. This way [1mntop [22msignificantly
        reduces the number of DNS queries it makes.

        This parameter causes  [1mntop  [22mto  skip  DNS  resolution,  showing  only
        numeric  IP  addresses instead of the symbolic names.  This option can
        useful when the DNS is not present or quite slow.


       [1m-o | --no-mac[0m
        [1mntop [22mis a hybrid layer 2/3 network monitor.  That is, it uses both the
        lower  level, physical device address - the MAC (Media Access Control)
        address - and the higher level, logical, tcp/ip address (the  familiar
        www.ntop.org  or  131.114.21.9 address).  This allows [1mntop [22mto link the
        logical addresses to a physical machine with multiple addresses  (This
        occurs  with  virtual  hosts  or  additional addresses assigned to the
        interface, etc.)  to present consolidated reporting.

        This parameter specifies that [1mntop [22mshould not trust the MAC  addresses
        but just use the IP addresses.

        Normally,  since  the  MAC  address  must be globally unique, the dual
        nature of [1mntop [22mis a benefit and provides far better information  about
        the network than is available via a pure layer 2 or pure layer 3 moni-
        tor.

        Under certain circumstances - whenever [1mntop [22mis started on an interface
        where  MAC  addresses  cannot be really trusted - you may require this
        option.

        Situations which may require this  option  include  port/VLAN  mirror,
        some  cases with switches and spanning tree protocol, and (reportedly)
        some specific models of Ethernet switches which re-write MAC addresses
        of  the packets they process.  Normally, you discover that this option
        is necessary  when  you  observe  that  hosts  seem  to  change  their
        addresses or information about different machines get lumped together.

        Note that with this option, information which is  dependent  upon  the
        MAC  addresses  (non  tcp/ip protocols like IPX) will not be collected
        nor displayed.


       [1m-p | --protocols[0m
        This parameter is used to specify the TCP/UDP protocols that [1mntop [22mwill
        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/ser-
        vices file or a numeric port range (e.g. 80, or 6000-6500).

        A simple example is --protocols="HTTP=http|www|https|3128,FTP=ftp|ftp-
        data", which reduces the protocols displayed  on  the  "IP"  pages  to
        three:

        Host                      Domain Data          HTTP   FTP   Other IP
        ns2.attbi.com             <flag>  954 63.9 %      0     0        954
        64.124.83.112.akamai.com  <flag>  240 16.1 %    240     0          0
        64.124.83.99.akamai.com   <flag>  240 16.1 %    240     0          0
        toolbarqueries.google.com <flag>   60 4.0 %      60     0          0

        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.  [1mntop -p protocol.list[0m

        If the -p parameter 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

        NOTE:  To  resolve protocol names to port numbers, they must be speci-
        fied in the system file used to  list  tcp/udp  protocols  and  ports,
        which  is  typically  /etc/services  file.  You will have to match the
        names in that file, exactly.  Missing  or  unspecified  (non-standard)
        ports must be specified by number, such as 3128 in our examples above.

        If you have a file named /etc/protocols, don't get confused by it,  as
        that's  the Ethernet protocol numbers, which are not what you're look-
        ing for.


       [1m-q | --create-suspicious-packets[0m
        This parameter tells [1mntop [22mto create a dump file of suspicious packets.

        There  are  many,  many,  things  that cause a packet to be labeled as
        'suspicious', including:

          Detected ICMP fragment
          Detected Land Attack against host
          Detected overlapping/tiny packet fragment
          Detected traffic on a diagnostic port
          Host performed ACK/FIN/NULL scan
          Host rejected TCP session
          HTTP/FTP/SMTP/SSH detected at wrong port
          Malformed TCP/UDP/ICMP packet (packet too short)
          Packet # %u too long
          Received a ICMP protocol Unreachable from host
          Sent ICMP Administratively Prohibited packet to host
          Smurf packet detected for host
          TCP connection with no data exchanged
          TCP session reset without completing 3-way handshake
          Two MAC addresses found for the same IP address
          UDP data to a closed port
          Unknown protocol (no HTTP/FTP/SMTP/SSH) detected (on port 80/21/25/22)
          Unusual ICMP options

        When this parameter is used, one file  is  created  for  each  network
        interface  where  suspicious packets are found. The file is in tcpdump
        (pcap) format and is named  <path>/ntop-suspicious-pkts.<device>.pcap,
        where <path> is defined by the -O | --output-packet-path parameter.


       [1m-r | --refresh-time[0m
        Specifies  the delay (in seconds) between automatic screen updates for
        those generated HTML pages which support them.  This parameter  allows
        you  to  leave  your browser window open and have it always displaying
        nearly real-time data from [1mntop.[0m

        The default is 3 seconds.  Please note that if the delay is very short
        (1  second for instance), [1mntop [22mmight not be able to process all of the
        network traffic.


       [1m-s | --no-promiscuous[0m
        Use this parameter to  prevent  from  setting  the  interface(s)  into
        promiscuous mode.

        An  interface  in  promiscuous  mode  will accept ALL Ethernet frames,
        regardless of whether they directed (addressed) to the  specific  net-
        work  interface  (NIC)  or not.  This is an essential part of enabling
        [1mntop [22mto monitor an entire network.  (Without  promiscuous  mode,  [1mntop[0m
        will  only see traffic directed to the specific host it is running on,
        plus broadcast traffic such as the arp and dhcp protocols.

        Even if you use this parameter, the interface could well be in promis-
        cuous mode if another application enabled it.

        [1mntop  [22mpasses  this  setting on to libpcap, the packet capture library.
        On many systems, a non-promiscuous open of the network interface  will
        fail, since the libpcap function on most systems require it to capture
        raw packets ( [1mntop [22mcaptures raw packets so that we may view  and  ana-
        lyze the layer 2 - MAC - information).

        Thus on most systems, [1mntop [22mmust probably still be started as root, and
        this option is largely ornamental.   If  it  fails,  you  will  see  a
        ***FATALERROR***  message  referring  to  pcap_open_live() and then an
        information message, "Sorry, but on this  system,  even  with  -s,  it
        appears that ntop must be started as root".


       [1m-t | --trace-level[0m
        This  parameter specifies the 'information' level of messages that you
        wish [1mntop [22mto display (on stdout or to the log).  The higher the  trace
        level  number the more information that is displayed.  The trace level
        ranges between 0 (no trace) and 5 (full debug tracings).

        The default trace value is 3.

        Trace level 0 is not quite zero messages.  Fatal  errors  and  certain
        startup/shutdown messages are always displayed.  Trace level 1 is used
        to display errors only, level 2 for  both  errors  and  warnings,  and
        level 3 displays error, warning and informational messages.

        Trace  level  4 is called 'noisy' and it is - generating many messages
        about the internal functioning of [1mntop.  [22mTrace level 5 is 'noisy' plus
        --log-extra  1,  i.e.  all  possible  messages,  with  a file:line tag
        prepended to every message.


       [1m-u | --user[0m
        Specifies the user [1mntop [22mshould run as after it initializes.

        [1mntop [22mmust normally be started as root so that it has sufficient privi-
        leges  to  open  the  network  interfaces  in  promiscuous mode and to
        receive raw frames.  See  the  discussion  of  -s  |  --no-promiscuous
        above, if you wish to try starting [1mntop [22mas a non-root user.

        Shortly  after  starting  up,  [1mntop [22mbecomes the user you specify here,
        which normally has substantially reduced privileges, such as no  login
        shell.   This  is  the  userid  which  owns [1mntop's [22mdatabase and output
        files.

        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.

        NOTE: This should not be root unless you really understand  the  secu-
        rity  risks. In order to prevent this by accident, the only way to run
        [1mntop [22mas root is to explicitly specify -u root.  [1mDon't do it.[0m


       [1m-w | --http-server[0m

       [1m-W | --https-server[0m
        [1mntop [22moffers an embedded web server to present the information that has
        been  so  painstakingly  gathered.   An  external  HTTP  server is NOT
        required NOR supported.  The [1mntop [22mweb  server  is  embedded  into  the
        application.   These  parameters  specify the port (and optionally the
        address (i.e. interface)) of the [1mntop [22mweb server.

        For example, if started with -w 3000 (the default port),  the  URL  to
        access [1mntop [22mis http://hostname:3000/.  If started with a full specifi-
        cation,  e.g.  -w  192.168.1.1:3000,  [1mntop  [22mlistens   on   only   that
        address/port combination.

        If  -w  is set to 0 the web server will not listen for http:// connec-
        tions.

        -W operates similarly, but controls the port for the https://  connec-
        tions.

        Some examples:

        [1mntop  -w 3000 -W 0 [22m(this is the default setting) HTTP requests on port
        3000 and no HTTPS.

        [1mntop -w 80 -W 443 [22mBoth HTTP and HTTPS have been enabled on their  most
        common ports.

        [1mntop -w 0 -W 443 [22mHTTP disabled, HTTPS enabled on the common port.

        Certain sensitive, configuration pages of the [1mntop [22mweb server are pro-
        tected by a userid/password.   By  default,  these  are  the  user/URL
        administration,  filter,  shutdown  and  reset stats are password pro-
        tected
         and are accessible initially only to user [1madmin [22mwith a  password  set
        during the first run of [1mntop.[0m

        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.  Best practices call for securing  that
        database so that only the [1mntop [22muser can read it.

        There  is  a  discussion  in  docs/FAQ about further securing the [1mntop[0m
        environment.


       [1m-z | --disable-sessions[0m
        This parameter disables TCP session tracking.  Use it for better  per-
        formance or when you don't really need/care to track sessions.


       [1m-A | --set-admin-password[0m
        This  parameter  is  used  to  start [1mntop [22m, set the admin password and
        quit. It is quite useful for installers that 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 also use this parameter to set a specific value  using  --set-
        admin-password=value.   [1mThe = is REQUIRED and no spaces are permitted![0m

        If you attempt to run [1mntop [22mas a daemon without setting a  password,  a
        FATAL ERROR message is generated and [1mntop [22mstops.


       [1m-B | --filter-expression[0m
        Filters  allows  the user to restrict the traffic seen by [1mntop [22mon just
        about any imaginable item.

        The filter expression is set at run time by this parameter, but it may
        be  changed during the [1mntop [22mrun on the Admin | Change Filter web page.

        The basic format is [1m-B filter [22m, where the quotes are [1mREQUIRED[0m

        The syntax of the filter expression uses the same BPF (Berkeley Packet
        Filter) expressions used by other packages such as tcpdump

        For  instance,  suppose  you are interested only in the traffic gener-
        ated/received by the host jake.unipi.it.  [1mntop  [22mcan  then  be  started
        with the following filter:

        [1mntop -B src host jake.unipi.it or dst host jake.unipi.it[0m

        or in shorthand:

        [1mntop -B host jake.unipi.it or host jake.unipi.it[0m

        See  the 'expression' section of the [1mtcpdump [22mman page - usually avail-
        able at http://www.tcpdump.org/tcpdump_man.html - for further informa-
        tion and the best quick guide to BPF filters currently available.


       [1m-D | --domain[0m
        This  identifies  the  local  domain suffix, e.g. ntop.org.  It may be
        necessary, if [1mntop [22mis having difficulty determining it from the inter-
        face.


       [1m-F | --flow-spec[0m
        It  is used to specify network flows similar to more powerful applica-
        tions such as NeTraMet.  A flow is a stream of captured  packets  that
        match a specified rule. The format is

        "     [1m<flow-label>='<matching    expression>'[,<flow-label>='<matching[0m
        [1mexpression>'] [22m"

        , 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 concern-
        ing  flows  can  be  accessed following the HTML link named 'List Net-
        Flows'.

        For instance define two flows with the following  expression  "  [1mLuca-[0m
        [1mHosts='host  jake.unipi.it  or host pisanino.unipi.it',GatewayRoutedP-[0m
        [1mkts='gateway gateway.unipi.it' [22m".

        All   the   traffic   sent/received   by   hosts   jake.unipi.it    or
        pisanino.unipi.it  is  collected  by  [1mntop  [22mand 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').

        Note that the double quotations around the entire flow expression  are
        required.


       [1m-K | --enable-debug[0m
        Use  this  parameter  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.


       [1m-L | --use-syslog=facility[0m
        Use this parameter to send log messages to the system log  instead  of
        stdout.

        -L  and  the  simple  form  --use-syslog use the default log facility,
        defined as LOG_DAEMON in the #define symbol DEFAULT_SYSLOG_FACILITY in
        globals-defines.h.

        The  complex  form, --use-syslog=facility will set the log facility to
        whatever value (e.g. local3, security) you specify.  [1mThe = is REQUIRED[0m
        [1mand no spaces are allowed![0m

        This  setting  applies  both  to  [1mntop  [22mand  to any child fork()ed for
        reporting.  If this parameter is not  specified,  any  fork()ed  child
        will  use  the  default value and will log it's messages to the system
        log (this occurs because the fork()ed child must give up  it's  access
        to the parents stdout).

        Because  various  systems do not make the permissible names available,
        we have a table at the end of globals-core.c.   Look  for  myFacility-
        Names.


       [1m-M | --no-interface-merge[0m
        By  default, [1mntop [22mmerges the data collected from all of the interfaces
        (NICs) it is monitoring into a single set of counters.

        If you have a simple network, say a small LAN with a connection to the
        internet, merging data is good as it gives you a better picture of the
        whole network.  For larger, more complex networks,  this  may  not  be
        desirable.   You  may  also  have other reasons for wishing to monitor
        each interface separately, for example DMZ vs. LAN traffic.

        This option instructs [1mntop [22mnot to merge network  interfaces  together.
        This  means  that  [1mntop [22mwill collect statistics for each interface and
        report them separately.

        Only ONE interface may be reported on at a time  -  use  the  [1mAdmin  |[0m
        [1mSwitch  NIC  [22moption  on  the  web  server to select which interface to
        report upon.

        Note that activating either the  netFlow  and/or  sFlow  plugins  will
        force the setting of -M.  Once enabled, you cannot go back.


       [1m-O | --output-packet-path[0m
        This   parameter  defines  the  base  path  for  the  ntop-suspicious-
        pkts.XXX.pcap and normal packet dump files.

        If this parameter is not specified, the default value is the  config.h
        parameter  CFG_DBFILE_DIR,  which  is  set during ./configure from the
        --localstatedir= parameter.  If --localstatedir is not  specified,  it
        defaults to the --prefix value plus /var (e.g. /usr/local/var).

        Be  aware  that this may not be what you expect when running [1mntop [22mas a
        daemon or Windows service. Setting an explicit and absolute path value
        is [1mSTRONGLY [22mrecommended if you use this facility.


       [1m-P | --db-file-path[0m

       [1m-Q | --spool-file-path[0m
        These parameters specify where [1mntop [22mstores database files.

        There  are  two  types,  'temporary'  - that is ones which need not be
        retained from [1mntop [22mrun to [1mntop [22mrun, and  'permanent',  which  must  be
        retained (or recreated).

        The 'permanent' databases are the preferences, "prefsCache.db" and the
        password file, "ntop_pw.db".  These are stored in the -P |  --db-file-
        path specified location.

        Certain  plugins  use  the  -P | --db-file-path specified location for
        their database ("LsWatch.db")  or  (as  a  default  value)  for  files
        (.../rrd/...).

        The  'temporary'  databases  are the address queue, "addressQueue.db",
        the cached DNS resolutions, "dnsCache.db" and the MAC  prefix  (vendor
        table), "macPrefix.db".

        If only -P | --db-file-path is specified, it is used for both types of
        databases.

        The directories named must allow read/write and file creation  by  the
        [1mntop  [22muser.  For security, nobody else should have even read access to
        these files.

        Note that the default value is the config.h parameter  CFG_DBFILE_DIR.
        This  is  set  during ./configure from the --localstatedir= parameter.
        If --localstatedir is not specified, it defaults to the --prefix value
        plus /var (e.g. /usr/local/var).

        This  may not be what you expect when running [1mntop [22mas a daemon or Win-
        dows service.

        Note that on versions of [1mntop [22mprior to 2.3, these parameters defaulted
        to "." (the current working directory, e.g.  the value returned by the
        pwd command) and caused havoc as it was different when  [1mntop  [22mwas  run
        from  the  command line, vs. run via cron, vs. run from an initializa-
        tion script.

        Setting an explicit and absolute path value is [1mSTRONGLY [22mrecommended.


       [1m-U | --mapper[0m
        Specifies the URL of the mapper.pl utility.

        If provided, [1mntop [22mcreates a clickable hyperlink  on  the  'Info  about
        host  xxxxxx'  page to this URL by appending ?host=xxxxx.  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
        [1mntop [22mdistribution [see www/Perl/mapper.pl]).


       [1m-V | --version[0m
        Prints [1mntop [22mversion information and then exits.


       [1m-W | --https-server[0m
        (See the joint documentation with the -w parameter, above)


       [1m--disable-stopcap[0m
        Return [1mntop [22mto the old (v2.1) behavior on a memory error.  The default
        of  stopcap  enabled  makes  the  web  interface available albeit with
        static content until [1mntop [22mis shutdown.


       [1m--log-extra[0m
        This optional parameter controls the addition of more  information  to
        each  log  message.   Both  choices  are useful in different ways, for
        debugging and for using log watching and filtering packages.

        Setting 1 adds a [file:line] to the  beginning  of  the  log  message.
        Setting  2  adds  a  [MSGIDnnnnnnn] tag at the end of the log message.
        The nnnnnnn value should be unique number for every message and should
        be stable across [1mntop [22mreleases.


       [1m--disable-instantsessionpurge[0m
        [1mntop [22msets completed sessions as 'timed out' and then purge them almost
        instantly, which is not the behavior you might expect from the discus-
        sions  about purge timeouts.  This switch makes ntop respect the time-
        outs for completed sessions.  It is NOT the default because a busy web
        server  may  have  100s  or 1000s of completed sessions and this would
        significantly increase the amount of memory [1mntop [22muses.


       [1m--disable-schedyield[0m
        [1mntop [22muses sched_yield()  calls  for  better  interactive  performance.
        Under  some  situations,  primarily  under  RedHat Linux 8.0, this can
        deadlock, causing the [1mntop [22mweb server  to  stop  responding,  although
        [1mntop  [22mappears to still be operational according to the ps command. Use
        this switch to disable these calls, IF you are seeing deadlocks.



[1mWEB VIEWS[0m
       While [1mntop [22mis running, multiple users can access the  traffic  informa-
       tion using their web browsers.  [1mntop [22mdoes not generate 'fancy' or 'com-
       plex' html, although it does use frame,  shallowly  nested  tables  and
       makes minimal use of Cascading Style Sheets.

       We do not expect problems with any current web browser, but our ability
       to test less common ones is very limited.

       The main HTML page is divided into three frames. Beginning with release
       2.3,  the menus have been compacted to small text selections stacked on
       top of each other.

       The top frame is a 'tabbed' navigation bar, containing broad items such
       as  'Total',  'Sent' and 'IP Protos'.  The middle frame is the detailed
       navigation or menu bar, containing the items relevant to the top selec-
       tion,  for  example  "IP" traffic statistics from a "Totals" menu.  The
       resulting data is displayed in the bottom frame.

       In documentation and this man page, when we refer to  a  page  such  as
       Admin | Switch NIC, we mean the Broad category "Admin" and the detailed
       item "Switch NIC" on that Admin menu.


[1mNOTES[0m
       [1mntop [22mrequires a number of external  tools  and  libraries  to  operate.
       Certain  other  tools  are optional, but add to the program's capabili-
       ties.


       Required libraries include:

       [1mlibpcap [22mfrom http://www.tcpdump.org/

       The Windows version makes use of [1mWinPcap [22m(libpcap  for  Windows)  which
       may be downloaded from http://winpcap.polito.it/install/default.htm.

       WARNING: The 2.x releases of [1mWinPcap [22mwill NOT support SMP machines.

       [1mgdbm [22mfrom http://www.gnu.org/software/gdbm/gdbm.html

       [1mntop  [22mrequires a POSIX threads library. Although a single-threaded ver-
       sion of  [1mntop  [22mcan  be  built  from  the  source  if  requested  during
       ./configure, it is not recommended for more than trivial usage.

       The   [1mgd   [22mlibrary,  for  the  creation  of  png  files,  available  at
       http://www.boutell.com/gd/.  [1mntop [22msupports both gd 1.X and 2.X

       The [1mlibpng [22mlibrary,  for  the  creation  of  png  files,  available  at
       http://www.libpng.org/pub/png/libpng.html.    [1mntop  [22msupports  both  the
       1.0.x series and the 1.2.x series of libpng, but  cautions  users  that
       there  are  incompatibilities  if you compile with one and run with the
       other.  Please read the discussion in  docs/FAQ  before  reporting  ANY
       problem with libpng.

       (if  an  https://  server  is desired) [1mopenSSL [22mfrom the OpenSSL project
       available at http://www.openssl.org.

       The [1mrrdtool [22mlibrary is required by the  rrd  plugin.   rrdtool  creates
       'Round-Robin  databases'  which  are used to store and graph historical
       data in a format that permits long duration retention  without  growing
       larger   over   time.    The   rrdtool   home   page   is   http://peo-
       ple.ee.ethz.ch/~oetiker/webtools/rrdtool/

       [1mntop [22mincludes a patched and frozen version of  rrdtool  1.0.42  in  the
       myrrd/  directory.   Users of [1mntop [22mv2.3 should not need to specifically
       install rrdtool.

       The [1msflow [22mPlugin 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.

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


[1mSEE ALSO[0m
       [1mtop[22m(1), [1mtcpdump[22m(8).  [1mpcap[22m(3).


[1mUSER SUPPORT[0m
       Please  send  bug  reports  to the ntop-dev <ntop-dev@ntop.org> mailing
       list. The ntop <ntop@ntop.org> mailing list is used for discussing ntop
       usage issues. In order to post messages on the lists a (free) subscrip-
       tion is required in order to limit/avoid spam. Please  do  NOT  contact
       the author directly unless this is a personal question.

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

       Please send code patches to <patch@ntop.org>.


[1mAUTHOR[0m
       ntop's author is Luca Deri (http://luca.ntop.org/) who can  be  reached
       at <deri@ntop.org>.


[1mLICENCE[0m
       ntop is distributed under the GNU GPL licence (http://www.gnu.org/).


[1mACKNOWLEDGMENTS[0m
       The  author  acknowledges  the  Centro Serra of the University of Pisa,
       Italy (http://www-serra.unipi.it/) for hosting the ntop sites (both web
       and mailing lists), and Burton Strauss <burton@ntopsupport.com> for his
       help  and  user  assistance.  Many  thanks  to   Stefano   Suin   <ste-
       fano@ntop.org>  and  Rocco Carbone <rocco@ntop.org> for contributing to
       the project.



                           September 2003 (ntop 2.3)                   NTOP(8)
