Provided by: ntop_3.2-1ubuntu1_i386 bug

NAME

       ntop - display top network users

SYNOPSIS

       ntop  [@filename] [-a|--access-log-file <path>] [-b|--disable-decoders]
       [-c|--sticky-hosts]    [-e|--max-table-rows]    [-f|--traffic-dump-file
       file>] [-g|--track-local-hosts] [-h|--help] [-j|--create-other-packets]
       [-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>]  [-x  <max_num_hash_entries>]  [-w|--http-
       server   <port>]    [-z|--disable-sessions]    [-A|--set-admin-password
       password]   [-B|--filter-expression   expression]   [-C   <configmode>]
       [-D|--domain <name>] [-F|--flow-spec <specs>] [-M|--no-interface-merge]
       [-N|--wwn-map]  [-O|----output-packet-path]  [-P|--db-file-path <path>]
       [-Q|--spool-file-path <path>] [-U|--mapper  <URL>]  [-V|--version]  [-X
       <max_num_TCP_sessions>]   [--disable-instantsessionpurge]   [--disable-
       mutexextrainfo] [--disable-schedyield] [--disable-stopcap]  [--fc-only]
       [--instance]   [--no-fc]   [--no-invalid-lun]   [--p3p-cp]  [--p3p-uri]
       [--skip-version-check] [--w3c] [-4|--ipv4] [-6|--ipv6]

       Unix options:

       [-d|--daemon] [-i|--interface <name>] [-u|--user <user>]  [-K|--enable-
       debug]    [-L]    [--pcap_setnonblock]    [--use-syslog=    <facility>]
       [--webserver-queue <number>]

       Windows option:

       [-i|--interface <number|name>]

       OpenSSL options:

       [-W|--https-server <port>] [--ssl-watchdog]

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 and received 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.

       ntop  is 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.  ntop is 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.

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. Nested @s  (an  @  inside  the
        file) are not permitted.

        Remember,  most  ntop  options  are "sticky", that is they just set an
        internal flag. Invoking them  multiple  times  doesn’t  change  ntops
        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.

        Beginning  with 3.1, many command-line options may also be set via the
        web browser interface.  These changes take effect on the next  run  of
        and on each subsequent run until changed.

       -a | --access-log-file
        By  default  ntop  does  not  maintain  a  log of HTTP requests to the
        internal 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 ntop logs is that an additional column has been added which
        has the time (in milliseconds) that ntop needed 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

        This  parameter is the complete file name of the access log.  In prior
        releases it was erroneously called --access-log-path.

       -b | --disable-decoders
        This parameter disables protocol decoders.

        Protocol decoders  examine  and  collect  information  about  layer  2
        protocols  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 ntop
        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 ntop has
        problems 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.

       -c | --sticky-hosts
        Use  this  parameter  to  prevent  idle  hosts  from being purged from
        memory.

        By default idle hosts are periodically purged from  memory.   An  idle
        host  is  identified  when  no  packets from or to that host have been
        monitored  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 ntop run.

        P2P users, port scans, popular web servers  and  other  activity  will
        cause ntop to 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 ntop tables and
        appear ’active’ for some considerable time after it is truly idle.

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

        WARNING:  If  you are running as a daemon, the messages from ntop will
        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.

       -e | --max-table-rows
        This defines the maximum number of lines that  ntop  will  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.

       -f | --traffic-dump-file
        By default, ntop captures traffic from network interface cards  (NICs)
        or from netFlow/sFlow probes.  However, ntop can also read data from a
        file - typically a tcpdump capture or the output from one of the  ntop
        packet capture options.

        if  you specify -f, ntop will 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.

       -g | --track-local-hosts
        By  default,  ntop tracks all hosts that it sees from packets captured
        on the various NICs.  Use this parameter to tell ntop to 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.

       -h | --help
        Print help information for ntop, including usage and parameters.

       -i | --interface
        Specifies  the  network interface or interfaces to be used by ntop for
        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.
        Especially 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.

        If you do not want ntop to monitor any interfaces, use -i none.

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

       -j | --create-other-packets
        This parameter causes ntop to  create  a  dump  file  of  the  ’other’
        network  traffic  captured.   One  file  is  created  for each network
        interface where <path>/ntop-other-pkts.<device>.pcap, where <path>  is
        defined  by  the  -O  |  --output-packet-path parameter.  This file is
        useful for understanding these unclassifed packets.

       -l | --pcap-log
        This parameter causes a dump file to be created of the network traffic
        captured  by  ntop  in tcpdump (pcap) format.  This file is useful for
        debug, and may be read back into ntop by 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  <path>/<log>.<device>.pcap  (Windows:
        <path>/<log>.pcap  ),  where  <path>  is defined by the -O | --output-
        packet-path parameter and <log> is defined by  this  -l  |  --pcap-log
        parameter.

       -m | --local-subnets
        ntop  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  ntop  reports.
        All other hosts are considered remote.

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

        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.

       -n | --numeric-ip-addresses
        By default, ntop resolves IP addresses using a combination  of  active
        (explicit)   DNS  queries  and  passive  sniffing.   Sniffing  of  DNS
        responses occurs when ntop receives a network  packet  containing  the
        response   to  some  other  user’s  DNS  query.   ntop  captures  this
        information and enters it into ntops DNS  cache,  in  expectation  of
        shortly   seeing  traffic  addressed  to  that  host.  This  way  ntop
        significantly reduces the number of DNS queries it makes.

        This parameter causes  ntop  to  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.

       -o | --no-mac
        ntop is 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 ntop to 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 ntop should not trust the MAC  addresses
        but just use the IP addresses.

        Normally,  since  the  MAC  address  must be globally unique, the dual
        nature of ntop is a benefit and provides far better information  about
        the  network  than  is  available  via  a pure layer 2 or pure layer 3
        monitor.

        Under certain circumstances - whenever ntop is 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.

       -p | --protocols
        This parameter 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).

        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.  ntop -p protocol.list

        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
        specified 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
        looking for.

       -q | --create-suspicious-packets
        This parameter tells ntop to 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.

       -r | --refresh-time
        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 ntop.

        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 of the
        network traffic.

       -s | --no-promiscuous
        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
        network interface (NIC) or not.  This is an essential part of enabling
        ntop to monitor an entire network.  (Without  promiscuous  mode,  ntop
        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
        promiscuous mode if another application enabled it.

        ntop  passes  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 ( ntop captures raw  packets  so  that  we  may  view  and
        analyze the layer 2 - MAC - information).

        Thus on most systems, ntop must 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".

       -t | --trace-level
        This  parameter specifies the ’information’ level of messages that you
        wish ntop to 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 ntop.  Trace level 5 and  above  are
        ’noisy’  plus extra logs, i.e. all possible messages, with a file:line
        tag prepended to every message.

       -u | --user
        Specifies the user ntop should run as after it initializes.

        ntop must normally be started  as  root  so  that  it  has  sufficient
        privileges  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 ntop as a non-root user.

        Shortly  after  starting  up,  ntop becomes the user you specify here,
        which normally has substantially reduced privileges, such as no  login
        shell.   This  is  the  userid  which  owns ntops database 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
        security  risks. In order to prevent this by accident, the only way to
        run ntop as root is to explicitly specify -u root.  Dont do it.

       -x

       -X
        ntop creates a new hash/list entry for each new host/TCP session seen.
        In  case of DOS (Denial Of Service) an attacker can easily exhaust all
        the host available memory because ntop is creating entries  for  dummy
        hosts.  In  order to avoid this you can set an upper limit in order to
        limit the memory ntop can use.

       -w | --http-server

       -W | --https-server
        ntop offers an embedded web server to present the information that has
        been  so  painstakingly  gathered.   An  external  HTTP  server is NOT
        required NOR supported.  The ntop web  server  is  embedded  into  the
        application.   These  parameters  specify 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  web  server  will  not listen for http://
        connections.

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

        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.

        Certain  sensitive,  configuration  pages  of  the ntop web server are
        protected by a userid/password.  By default, these  are  the  user/URL
        administration,   filter,   shutdown  and  reset  stats  are  password
        protected
         and are accessible initially only to 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.  Best practices call for securing  that
        database so that only the ntop user can read it.

        There  is  a  discussion  in  docs/FAQ about further securing the ntop
        environment.

       -z | --disable-sessions
        This parameter 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  parameter  is  used  to  start ntop , 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.   The = is REQUIRED and no spaces are permitted!

        If you attempt to run ntop as a daemon without setting a  password,  a
        FATAL ERROR message is generated and ntop stops.

       -B | --filter-expression
        Filters  allows  the user to restrict the traffic seen by ntop on just
        about any imaginable item.

        The filter expression is set at run time by this parameter, but it may
        be  changed during the ntop run on the Admin | Change Filter web page.

        The basic format is -B filter , where the quotes are REQUIRED

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

        or in shorthand:

        ntop -B host jake.unipi.it or host jake.unipi.it

        See  the  ’expression’  section  of  the  tcpdump  man  page - usually
        available at  http://www.tcpdump.org/tcpdump_man.html  -  for  further
        information  and  the  best  quick  guide  to  BPF  filters  currently
        available.

        WARNING: If you are using complex filter expressions, especially those
        with  =s or meaningful spaces in them, be sure and use the long option
        format, --filter-expression="xxxx" and not -B "xxxx".

       -C |
        This instruments ntop to be  used  in  two  configurations:  host  and
        network  mode.  In  host  mode  (default)  ntop works as usual: the IP
        addresses received are those of  real  hosts.  In  host  mode  the  IP
        addresses  received  are  those  of  the  C-class network to which the
        address belongs. Using ntop in network mode is extremely  useful  when
        installed  in  a traffic exchange (e.g. in the middle of the Internet)
        whereas the host mode should be used when ntop  is  installed  on  the
        edge   of  a  network  (e.g.  inside  a  company).  The  network  mode
        significantly reduces the amount of work ntop has to  perform  and  it
        has  to  be  used  whenever  ntop  is used to find out how the network
        traffic flows and not to pin-point specific hosts.

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

       -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 is a bpf (Berkeley  Packet  Filter)
        expression.  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’).

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

       -K | --enable-debug
        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.

       -L | --use-syslog=facility
        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.  The = is REQUIRED
        and no spaces are allowed!

        This setting applies both to  ntop  and  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
        myFacilityNames.

       -M | --no-interface-merge
        By default, ntop merges 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 ntop not to merge network interfaces together.
        This means that ntop will collect statistics for  each  interface  and
        report them separately.

        Only  ONE  interface  may  be  reported on at a time - use the Admin |
        Switch NIC option 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.

       -N | --wwn-map
        This options names the file providing the map of WWN to FCID/VSAN ids.

       -O | --output-packet-path
        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 ntop as a
        daemon or Windows service. Setting an explicit and absolute path value
        is STRONGLY recommended if you use this facility.

       -P | --db-file-path

       -Q | --spool-file-path
        These parameters specify where ntop stores database files.

        There  are  two  types,  ’temporary’  - that is ones which need not be
        retained from ntop run to ntop run, 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
        ntop  user.  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 ntop as a daemon or
        Windows service.

        Note that on versions of ntop prior 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  ntop  was  run
        from   the   command   line,  vs.  run  via  cron,  vs.  run  from  an
        initialization script.

        Setting an explicit and absolute path value is STRONGLY recommended.

       -U | --mapper
        Specifies the URL of the mapper.pl utility.

        If provided, ntop creates 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
        ntop distribution [see www/Perl/mapper.pl]).

       -V | --version
        Prints ntop version information and then exits.

       -W | --https-server
        (See the joint documentation with the -w parameter, above)

       --disable-instantsessionpurge
        ntop sets completed sessions as ’timed out’ and then purge them almost
        instantly,  which  is  not  the  behavior  you  might  expect from the
        discussions about purge timeouts.  This switch makes ntop respect  the
        timeouts 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 ntop uses.

       --disable-mutexextrainfo
        ntop  stores  extra  information  about  the  locks and unlocks of the
        protective mutexes it uses. Since ntop uses fine-grained locking, this
        information  is  updated  frequently.   On some OSes, the system calls
        used to collect this  informatio  (getpid()  and  gettimeofday())  are
        expensive.   This  option  disables  the extra information.  It should
        have no processing impact on ntop
         -  however  should  ntop  actually  deadlock,  we  would   lose   the
        information that sometimes tells us why.

       --disable-schedyield
        ntop  uses  sched_yield()  calls  for  better interactive performance.
        Under some situations, primarily under  RedHat  Linux  8.0,  this  can
        deadlock,  causing  the  ntop  web server to stop responding, although
        ntop appears to still be operational according to the ps command.  Use
        this switch to disable these calls, IF you are seeing deadlocks.

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

       --fc-only

        Display only Fibre Channel statistics.

       --instance

        You  can  run  multiple instances of ntop simultaneously by specifying
        different -P values (typically through separate ntop.conf files).   If
        you  set  a  value  for  this parameter (available only on the command
        line), you (1) display the ’instance’ name on every web page  and  (2)
        alter the log prefix from "NTOP" to your chosen value.

        If  you want to make the tag more obvious, create a .instance class in
        style.css, e.g.:

           .instance {
             color: #666666;
             font-size: 18pt;
           }

        Note (UNIX): To run completely different versions of the ntop  binary,
        you  need  to  compile  and  install  into  a different library (using
        ./configure --prefix) and  then  specify  the  LD_LIBRARY_PATH  before
        invoking, e.g.

        LD_LIBRARY_PATH=/devel/lib/ntop/:... /devel/bin/ntop ...args...

        If  present,  a file of the form <instance>_ntop_logo.gif will be used
        instead of the normal ntop_logo.gif.  This is tested for ONLY once, at
        the  beginning  of  the run.  The EXACT word(s) of the --instance flag
        are used, without testing if they make a proper file name.  If  -  for
        any reason - the file is not found, an informational message is logged
        and the normal logo file is used.  To construct your own logo, make it
        a 300x40 transparent gif.

        NOTE: On the web pages, ntop uses the dladdr() function.  The original
        Solaris routine had a bug, replicated in FreeBSD (and  possibly  other
        places)  where  it uses the ARGV[0] value - which might be erroneous -
        instead of the actual file name.  If the ’running  from’  value  looks
        bogus but the ’libaries in’ value looks ok, go with the libarary.

       --no-fc

        Disable processing & Display of Fibre Channel

       --no-invalid-lun

        Don’t display Invalid LUN information.

       --p3p-cp

       --p3p-uri

        P3P   is  a  W3C  recommendation  -  http://www.w3.org/TR/P3P/  -  for
        specifying personal information a site collects and what it does  with
        the  information.   These  parameters allow to return P3P information.
        We do not supply samples.

       --pcap_setnonblock
        On some platforms, the ntop web server will hang or appear to hang (it
        actually  just  responds incredibly slowly to the first request from a
        browser session), while the rest of ntop runs just fine. This is known
        to be an issue under FreeBSD 4.x.

        This  option  sets the non-blocking option (assuming it’s available in
        the version of libpcap that is installed).

        While this works around the problem  (by  turing  an  interupt  driven
        process into a poll), it also MAY signifcantly increases the cpu usage
        of ntop.  Although it does not actually  interfere  with  other  work,
        seeing  ntop use 80-90% or more of the cpu is not uncommon - don’t say
        we didn’t warn you.

        THIS OPTION IS OFFICIALLY UNSUPPORTED and used at your own risk.  Read
        the docs/FAQ write-up.

       --skip-version-check
        By  default,  ntop accesses a remote file to periodically check if the
        most current version is running.  This  option  disables  that  check.
        Please  review  the privacy notice at the bottom of this page for more
        information.  By default, the recheck period is slightly more than  15
        days.   This  can be adjusted via a constant in globals-defines.h.  If
        the result of the initial check indicates that the ntop version  is  a
        ’new  development’  version  (that  is newer than the latest published
        development version), the recheck is disabled.  This is because  which
        fixes and enhancements were present/absent from the code.

        NOTE: At present, the recheck does not work under Windows.

       --ssl-watchdog

        Enable  a  watchdog  for  webserver  hangs.  These usually happen when
        connecting with older browsers. The user gets nothing back  and  other
        users can’t connect. Internally, packet processing continues but 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)

       --w3c
        By default, ntop generates displayable but not great html.  There  are
        a  number  of tags we do not generate because they cause problems with
        older browsers which are still commonly used or are important to  look
        good  on  real-world  browsers.   This  flag  tells  ntop  to generate
        ’BETTER’ (but not perfect) w3c compliant html 4.01 output. This in  no
        way  addresses all of the compatibility and markup issues.  Over time,
        we would like to make ntop more compatible, but it will never be 100%.
        If you find any issues, please report them to ntop-dev.

       -4 | --ipv4
        Use IPv4 connections.

       -6 | --ipv6
        Use IPv6 connections

WEB VIEWS

       While   ntop   is  running,  multiple  users  can  access  the  traffic
       information using their web browsers.  ntop does not  generate  ’fancy’
       or ’complex’ html, although it does use frames, shallowly nested tables
       and makes some use of JavaScript and Cascading Style Sheets.

       Beginning with release 3.1,  the  menus  are  cascading  dropdowns  via
       JSCookMenu.  With release 3.2, this extends to plugins.

       We do not expect problems with any current web browser, but our ability
       to test with less common ones is very limited.   Testing  has  included
       Firefox  and  Internet  Explorer,  with  very  limited testing on other
       current common browsers such as Opera.

       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.

NOTES

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

       --webserver-queue
        Specifies the maximum number of web server  requests  for  the  tcp/ip
        stack  to  retain  in  it’s  queue  awaiting  delivery to the ntop web
        server.  Requests in excess of this queue may be dropped (allowing for
        retransmission)  or rejected at the tcp/ip stack level, depending upon
        the OS.  Whatever happens,  happens  at  the  OS  level,  without  any
        information being delivered to ntop

        Required libraries include:

        libpcap from http://www.tcpdump.org/, version 0.7.2 or newer. 0.8.3 or
        newer is strongly recommended.

        The Windows version makes use of WinPcap (libpcap for  Windows)  which
        may be downloaded from http://winpcap.polito.it/install/default.htm.

        WARNING: The 2.x releases of WinPcap will NOT support SMP machines.

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

        ntop  requires  a  POSIX  threads library. As of ntop 3.2, the single-
        threaded version of ntop is no longer available.

        The gd 2.x library, for  the  creation  of  png  files,  available  at
        http://www.boutell.com/gd/.

        The  libpng 1.2.x library, for the creation of png files, available at
        http://www.libpng.org/pub/png/libpng.html.

        ntop should support both gd 1.X and libpng 1.0.x  libraries  but  this
        has  not  been  tested.   Note that there are incompatibilities if you
        compile with one version of these libraries  and  then  run  with  the
        other.   Please  read  the discussion in docs/FAQ before reporting ANY
        problems of this nature.

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

        The  rrdtool  library  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://people.ee.ethz.ch/~oetiker/webtools/rrdtool/

        ntop  includes  a  limited  version  of  rrdtool  1.0.49 in the myrrd/
        directory.  Users of ntop 3.2 should not need to specifically  install
        rrdtool.

        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.

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

SEE ALSO

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

PRIVACY NOTICE

       By default at startup and at periodic intervals, the ntop program  will
       retrieve  a  file  containing current ntop program version information.
       Retrieving this file allows this ntop instance to confirm  that  it  is
       running the most current version.

       The  retrieval  is  done  using  standard  http:// requests, which will
       create log records on the hosting system.  These log records do contain
       information  which  identifies  a specific ntop site.  Accordingly, you
       are being notified that this individually identifiable  information  is
       being transmitted and recorded.

       You  may  request - via the --skip-version-check run-time option - that
       this check be eliminated.  If you  use  this  option,  no  individually
       identifiable information is transmitted or recorded, because the entire
       retrieval and check is skipped.

       We ask you to allow this retrieval and check, because it benefits  both
       you  and  the  ntop  developers.   It  benefits you because you will be
       automatically notified if the ntop program version is obsolete, becomes
       unsupported  or  is  no  longer current.  It benefits the developers of
       ntop because it allows us  to  determine  the  number  of  active  ntop
       instances,  and  the  operating  system/versions that users are running
       ntop under.  This allows us to focus development resources  on  systems
       like those our users are using ntop on.

       The  individually  identifiable  information  is  contained  in the web
       server log records  which  are  automatically  created  each  time  the
       version  file  is  retrieved.  This is a function of the web server and
       not of ntop , but we do take advantage of it.  The log record shows the
       IP address of the requestor (the ntop instance) and a User-Agent header
       field.  We place information in the User-Agent header as follows:

           ntop/<version>
           host/<name from config.guess>
           distro/<if one>
           release/<of the distro, also if one>
           kernrlse/<kernel version or release>
           GCC/<version>
           config() <condensed parameters from ./configure>
           run()    <condensed flags - no data - from the execution line>
           libpcap/<version>
           gdbm/<version>
           openssl/<version>
           zlib/<version>
           access/<http, https, both or none>
           interfaces() <given interface names>

       For example:

           ntop/2.2.98    host/i686-pc-linux-gnu    distro/redhat    release/9
       kernrlse/2.4.20-8smp
           GCC/3.2.2   config(i18n)   run(i;   u;   P;   w;  t;  logextra;  m;
       instantsessionpurge;
           schedyield; d; usesyslog=; t) gdbm/1.8.0 openssl/0.9.7a zlib/1.1.4
           access/http interfaces(eth0,eth1)

       Distro and release  information  is  determined  at  compile  time  and
       consists  of  information  typically  found  in  the  /etc/release  (or
       similar)  file.  See  the  ntop  tool  linuxrelease  for  how  this  is
       determined.

       gcc  compiler version (if available) is the internal version #s for the
       gcc compiler, e.g. 3.2.3.

       kernrlse is the Linux Kernel version or  the  xBSD  ’release’  such  as
       4.9-RELEASE  and is determined from the uname data (if it’s available).

       The ./configure parameters are stripped of directory paths, leading -s,
       etc.  to  create a short form that shows us what ./configure parameters
       people are using.

       Similarly, the run time parameters are stripped of data and paths, just
       showing which flags are being used.

       The  libpcap,  gdbm,  openssl  and  zlib versions come from the strings
       returned by the various inquiry functions (if they’re availabe).

       Here’s a sample log record:

       67.xxx.xxx.xxx  -  -  [28/Dec/2003:12:11:46  -0500]  "GET  /version.xml
       HTTP/1.0"
         200  1568  www.burtonstrauss.com "-" "ntop/2.2.98 host/i686-pc-linux-
       gnu
         distro/redhat release/9 kernrlse/2.4.20-8smp GCC/3.2.2 config(i18n)
         run(i; u; P; w; t; logextra; m; instantsessionpurge; schedyield; d;
         usesyslog=)   libpcap/0.8   gdbm/1.8.0   openssl/0.9.7a    zlib/1.1.4
       access/http
         interfaces(eth0,eth1,eth2)" "-"

USER SUPPORT

       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)
       subscription is required to limit/avoid spam. Please do NOT contact the
       author 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 to <patch@ntop.org>.

AUTHOR

       ntop’s author is Luca Deri (http://luca.ntop.org/) who can  be  reached
       at <deri@ntop.org>.

LICENCE

       ntop is distributed under the GNU GPL licence (http://www.gnu.org/).

ACKNOWLEDGMENTS

       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
       <stefano@ntop.org>  and Rocco Carbone <rocco@ntop.org> for contributing
       to the project.

                            August 2005 (ntop 3.2)                     NTOP(8)