man: add flowtop's man page

This is an initial version of flowtop's man page that includes
a writeup of its purpose, what it can do and what its limits are
and what options are available for use.

Signed-off-by: Daniel Borkmann <dborkman@redhat.com>

1 files changed, 132 insertions, 0 deletions

diff --git a/man/flowtop.8 b/man/flowtop.8
new file mode 100644
index 0000000..5d3cb40
--- /dev/null
+++ b/man/flowtop.8
@@ -0,0 +1,132 @@
+.\" netsniff-ng - the packet sniffing beast
+.\" Copyright 2013 Daniel Borkmann.
+.\" Subject to the GPL, version 2.
+
+.TH FLOWTOP 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
+.SH NAME
+flowtop \- top-like netfilter TCP/UDP/SCTP/DCCP/ICMP(v6) flow tracking
+
+.SH SYNOPSIS
+
+\fB flowtop\fR { [\fIoptions\fR] }
+
+.SH DESCRIPTION
+
+flowtop is a top-like connection tracking tool that can run on an end host or
+small home router. It is able to present TCP, UDP/UDP-lite, SCTP, DCCP, ICMP(v6)
+flows that have been collected by the kernel's netfilter connection tracking
+framework, thus no packet capturing in user space needs to be done.
+
+flotwop is able to give you a quick overview of current connections on your
+local system, e.g. for debugging purposes or to answer questions like:
+
+    * If you access website X, what other connections are being opened in
+the background that I'm not aware of?
+    * What connections are active that pass ones router?
+    * I have this proprietary binary Y, where does it connect to?
+    * To which countries am I sending my data?
+    * Are there any suspicious background connections on my machine?
+    * How many connections has binary Z currently active?
+
+The following information will be presented in flowtop's output:
+
+    * Application name and PID when run on local machine
+    * Reverse DNS for source and destination
+    * Geo-location information (country, city)
+    * Used protocols (IPv4, IPv6, TCP, UDP, SCTP, ICMP, ...)
+    * Flow port's service name heuristic
+    * Transport protocol state machine information
+
+In order for flowtop to work, netfilter/iptables must be active resp. running
+on your machine, thus kernel-side connection tracking is active.
+
+flowtop's intention is just to get a quick look over your active connections.
+If you want to have logging, have a look at netfilter's conntrack(8) tools
+instead.
+
+.SH OPTIONS
+
+.SS -4, --ipv4
+Display IPv4 flows. That's default when flowtop is started without
+any arguments.
+
+.SS -6, --ipv6
+Display IPv6 flows. That's default when flowtop is started without
+any arguments.
+
+.SS -T, --tcp
+Display TCP flows. That's default when flowtop is started without
+any arguments.
+
+.SS -U, --udp
+Display UDP and UDP-lite flows.
+
+.SS -D, --dccp
+Display DCCP flows.
+
+.SS -I, --icmp
+Display ICMP version 4 and version 6 flows.
+
+.SS -S, --sctp
+Display SCTP flows.
+
+.SS -s, --show-src
+Also show source information of the flow, not only destination information.
+
+.SS -u, --update
+The built-in database update mechanism will be invoked to get Maxmind's
+latest database. To configure search locations for databases, the file
+/etc/netsniff-ng/geoip.conf contains possible addresses. Thus, to save
+bandwidth or for mirroring Maxmind's databases (to bypass their traffic
+limit policy), different hosts or IP addresses can be placed into geoip.conf,
+separated by a newline.
+
+.SS -v, --version
+Show versioning information.
+
+.SS -h, --help
+Show user help.
+
+.SH USAGE EXAMPLE
+
+.SS flowtop
+Default ncurses output for flowtop that tracks IPv4, IPv6 flows for TCP.
+
+.SS flowtop -46UTDISs
+This example enables maximum display options for flowtop.
+
+.SH CONFIG FILES
+
+Under /etc/netsniff-ng/ there are the following files stored that are used
+by flowtop and can be extended if wished:
+
+    * tcp.conf - TCP port/services map
+    * udp.conf - UDP port/services map
+    * geoip.conf - GeoIP database mirrors
+
+.SH BUGS
+During fairly high till high connection tracking updates, flowtop's scrolling
+can become shortly unresponsive. The right fix would be to replace flowtop's
+connection management backend with a better design resp. locking approach.
+Still on todo.
+
+.SH LEGAL
+flowtop is licensed under the GNU GPL version 2.0.
+
+.SH HISTORY
+.B flowtop
+was originally written for the netsniff-ng toolkit by Daniel Borkmann. It
+is currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel
+Borkmann <dborkma@tik.ee.ethz.ch>.
+
+.SH SEE ALSO
+.BR netsniff-ng (8),
+.BR trafgen (8),
+.BR mausezahn (8),
+.BR ifpps (8),
+.BR bpfc (8),
+.BR astraceroute (8),
+.BR curvetun (8)
+
+.SH AUTHOR
+Manpage was written by Daniel Borkmann.