flowtop.8

   1 .\" netsniff-ng - the packet sniffing beast
   2 .\" Copyright 2013 Daniel Borkmann.
   3 .\" Subject to the GPL, version 2.
   4 .TH FLOWTOP 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
   5 .SH NAME
   6 flowtop \- top-like netfilter TCP/UDP/SCTP/DCCP/ICMP(v6) flow tracking
   7 .PP
   8 .SH SYNOPSIS
   9 .PP
  10 \fBflowtop\fR { [\fIoptions\fR] }
  11 .PP
  12 .SH DESCRIPTION
  13 .PP
  14 flowtop is a top-like connection tracking tool that can run on an end host or
  15 small home router. It is able to present TCP, UDP/UDP-lite, SCTP, DCCP, and
  16 ICMP(v6) flows that have been collected by the kernel's netfilter connection
  17 tracking framework, thus no packet capturing in user space needs to be done.
  18 .PP
  19 flowtop is able to give you a quick overview of current connections on your
  20 local system, e.g. for debugging purposes or to answer questions like:
  21 .PP
  22     * If you access website X, what other connections are being opened in
  23       the background that I'm not aware of?
  24     * What connections are active that pass one's router?
  25     * I have this proprietary binary Y, to where does it connect?
  26     * To which countries am I sending data?
  27     * Are there any suspicious background connections on my machine?
  28     * How many active connections does binary Y have?
  29 .PP
  30 The following information will be presented in flowtop's output:
  31 .PP
  32     * Application name and PID when run on local machine
  33     * Reverse DNS for source and destination
  34     * Geo-location information (country, city)
  35     * Used protocols (IPv4, IPv6, TCP, UDP, SCTP, ICMP, ...)
  36     * Flow port's service name heuristic
  37     * Transport protocol state machine information
  38     * Byte/packet counters (if they are enabled)
  39 .PP
  40 In order for flowtop to work, netfilter must be active and running
  41 on your machine, thus kernel-side connection tracking is active. If netfilter
  42 is not running, you can activate it with iptables(8):
  43 .in +4
  44 .sp
  45 iptables -A INPUT -p tcp -m state --state ESTABLISHED -j ACCEPT
  46 .sp
  47 iptables -A OUTPUT -p tcp -m state --state NEW,ESTABLISHED -j ACCEPT
  48 .in -4
  49 .PP
  50 To dump byte/packet counters flowtop enables the sysctl(8) parameter
  51 \[lq]net.netfilter.nf_conntrack_acct\[rq] via:
  52 .in +4
  53 .sp
  54 echo 1 > /proc/sys/net/netfilter/nf_conntrack_acct
  55 .sp
  56 .in -4
  57 and resets it to the previously set value on exit. These counters will only be
  58 active on connections which were created after accounting was enabled. Thus, to
  59 have these counters be active all the time the parameter should be enabled after
  60 the system is up. To automatically enable it, sysctl.conf(8) or sysctl.d(8)
  61 might be used.
  62 .PP
  63 flowtop's intention is just to get a quick look over your active connections.
  64 If you want logging support, have a look at netfilter's conntrack(8) tools
  65 instead.
  66 .PP
  67 .SH OPTIONS
  68 .PP
  69 .SS -4, --ipv4
  70 Display IPv4 flows. That is the default when flowtop is started without
  71 any arguments.
  72 .PP
  73 .SS -6, --ipv6
  74 Display IPv6 flows. That is the default when flowtop is started without
  75 any arguments.
  76 .PP
  77 .SS -T, --tcp
  78 Display TCP flows. That is the default when flowtop is started without
  79 any arguments.
  80 .PP
  81 .SS -U, --udp
  82 Display UDP and UDP-lite flows.
  83 .PP
  84 .SS -D, --dccp
  85 Display DCCP flows.
  86 .PP
  87 .SS -I, --icmp
  88 Display ICMP version 4 and version 6 flows.
  89 .PP
  90 .SS -S, --sctp
  91 Display SCTP flows.
  92 .PP
  93 .SS -s, --show-src
  94 Also show source information of the flow, not only destination information.
  95 .PP
  96 .SS -u, --update
  97 The built-in database update mechanism will be invoked to get Maxmind's
  98 latest database. To configure search locations for databases, the file
  99 /etc/netsniff-ng/geoip.conf contains possible addresses. Thus, to save
 100 bandwidth or for mirroring Maxmind's databases (to bypass their traffic
 101 limit policy), different hosts or IP addresses can be placed into geoip.conf,
 102 separated by a newline.
 103 .PP
 104 .SS -v, --version
 105 Show version information and exit.
 106 .PP
 107 .SS -h, --help
 108 Show user help and exit.
 109 .PP
 110 .SH USAGE EXAMPLE
 111 .PP
 112 .SS flowtop
 113 Default ncurses output for flowtop that tracks IPv4, IPv6 flows for TCP.
 114 .PP
 115 .SS flowtop -46UTDISs
 116 This example enables the maximum display options for flowtop.
 117 .PP
 118 .SH CONFIG FILES
 119 .PP
 120 Files under /etc/netsniff-ng/ can be modified to extend flowtop's
 121 service resolution and lookup information.
 122 .PP
 123     * tcp.conf - TCP port/services map
 124     * udp.conf - UDP port/services map
 125     * geoip.conf - GeoIP database mirrors
 126 .PP
 127 .SH BUGS
 128 With a fairly high rate of connection tracking updates, flowtop can become
 129 unresponsive for short periods of time while scrolling. The right fix would
 130 be to replace flowtop's connection management backend with a better design
 131 with respect to the locking approach. This is still on the "todo" list.
 132 .PP
 133 .SH LEGAL
 134 flowtop is licensed under the GNU GPL version 2.0.
 135 .PP
 136 .SH HISTORY
 137 .B flowtop
 138 was originally written for the netsniff-ng toolkit by Daniel Borkmann. It
 139 is currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel
 140 Borkmann <dborkma@tik.ee.ethz.ch>.
 141 .PP
 142 .SH SEE ALSO
 143 .BR netsniff-ng (8),
 144 .BR trafgen (8),
 145 .BR mausezahn (8),
 146 .BR ifpps (8),
 147 .BR bpfc (8),
 148 .BR astraceroute (8),
 149 .BR curvetun (8),
 150 .BR iptables (8),
 151 .BR sysctl (8),
 152 .BR sysctl.conf (8),
 153 .BR sysctl.d (8)
 154 .PP
 155 .SH AUTHOR
 156 Manpage was written by Daniel Borkmann.
 157 .PP
 158 .SH COLOPHON
 159 This page is part of the Linux netsniff-ng toolkit project. A description of the project,
 160 and information about reporting bugs, can be found at http://netsniff-ng.org/.