Implement --wait
[darkstat] / darkstat.8
index 081b723..d059c17 100644 (file)
@@ -1,6 +1,6 @@
 .\"
 .\" darkstat 3
-.\" Copyright 2001-2009, Emil Mikulic.
+.\" Copyright 2001-2010, Emil Mikulic.
 .\"
 .\" You may use, modify and redistribute this file under the terms of the
 .\" GNU General Public License version 2. (see COPYING.GPL)
@@ -64,13 +64,15 @@ darkstat \- network statistics gatherer
 ] [
 .BI \-\-highest\-port " port"
 ] [
+.BI \-\-wait " secs"
+] [
 .BI \-\-hexdump
 ]
 .\"
 .SH DESCRIPTION
 .I darkstat
-is a packet sniffer that runs as a background process on
-a cable/DSL router, gathers all sorts of statistics about network usage,
+is a packet sniffer that runs as a background process,
+gathers all sorts of statistics about network usage,
 and serves them over HTTP.
 
 All settings are passed on the commandline.
@@ -96,14 +98,13 @@ arguments are mutually exclusive.
 .\"
 .TP
 .BI \-\-snaplen " bytes"
-How many bytes to capture of the start of each packet.
+How many bytes to capture from the start of each packet.
 You should not need to specify this;
 \fIdarkstat\fR will calculate it automatically.
 .\"
 .TP
 .BI \-\-pppoe
 Don't use this.
-.RS
 
 Instead, capture on the tunnel interface that your PPPoE software
 provides, for example \fBtun0\fR on \fIFreeBSD\fR, \fBpppoe0\fR on
@@ -113,20 +114,19 @@ If you really must, you can capture on an Ethernet interface and pass
 this argument to have \fIdarkstat\fR decode PPPoE frames and ignore
 everything else.
 Make sure you also specify your local address with the \fB\-l\fR
-argument.
-.RE
+argument!
 .\"
 .TP
 .BI \-\-syslog
 Errors, warnings, and verbose messages will go to \fBsyslog\fR (facility
 daemon, priority debug) instead of \fBstderr\fR.
 
-On some systems, these messages end up in \fB/var/log/debug\fR or
-\fBdebug.log\fR by default.
+On some systems, these messages end up in \fB/var/log/debug\fR
+by default.
 .\"
 .TP
 .BI \-\-verbose
-Output verbose debugging messages.
+Produce more verbose debugging messages.
 .\"
 .TP
 .BI \-\-no\-daemon
@@ -136,8 +136,9 @@ stay in the foreground.
 .TP
 .BI \-\-no\-promisc
 Do not use promiscuous mode to capture.
-Note that an interface may already be in promiscuous mode.
-If this is a problem, use an appropriate
+Note that an interface may already be in promiscuous mode, or may later
+enter promiscuous mode, due to circumstances beyond \fIdarkstat\fR's control.
+If this is a problem, use \fB\-f\fR to specify an appropriate
 .BR bpf (4)
 filter.
 .\"
@@ -145,7 +146,7 @@ filter.
 .BI \-\-no\-dns
 Do not resolve IPs to host names.
 This can significantly reduce memory footprint on small systems
-as an extra process is created for DNS resolving.
+as an extra process is created for DNS resolution.
 .\"
 .TP
 .BI \-\-no\-macs
@@ -317,9 +318,22 @@ This can be used to hide ephemeral ports.
 By default, all ports are tracked.
 .\"
 .TP
+.BI \-\-wait " secs"
+Don't use this.
+It's a hack to help victims of \fINetworkManager\fR and similar systems.
+.RS
+
+You should start \fIdarkstat\fR after the capture interface has come up.
+If you can't, specifying the \fB\-\-wait\fR option will make \fIdarkstat\fR
+sleep up to the specified number of seconds for the interface to become ready.
+Zero means wait indefinitely.
+.RE
+.\"
+.TP
 .BI \-\-hexdump
 Show hex dumps of received traffic.
-This is only for debugging, and implies \-\-verbose and \-\-no\-daemon.
+This is only for debugging, and implies \fB\-\-verbose\fR and
+\fB\-\-no\-daemon\fR.
 .\"
 .\" --------------------------------------------------------------------
 .SH USAGE EXAMPLES
@@ -353,7 +367,7 @@ We only want to account for SSH traffic:
 darkstat \-i fxp0 \-f "port 22"
 .PP
 .\"
-We don't want to account for network internal traffic:
+We don't want to account for traffic between internal IPs:
 .IP
 darkstat \-i fxp0 \-f "not (src net 192.168.0 and dst net 192.168.0)"
 .PP
@@ -371,11 +385,13 @@ server (which is running \fIdarkstat\fR):
 darkstat \-i fxp0 \-l 192.168.1.0/255.255.255.0
 .PP
 .\"
-We want to specify the local IP of the gateway manually because it
-cannot be automatically detected, e.g. \fB\-\-pppoe\fR is in use.
+On some systems, we can't capture on a "decoded" interface but
+only on \fInas0\fR which returns PPPoE encapsulated packets.
+Do PPPoE decoding, and override the local IP manually since it
+cannot be automatically detected.
 Note the /32 netmask:
 .IP
-darkstat \-i fxp0 \-\-pppoe \-l 192.168.1.1/255.255.255.255
+darkstat \-i nas0 \-\-pppoe \-l 192.168.1.1/255.255.255.255
 .\"
 .SH SIGNALS
 To shut
@@ -422,7 +438,7 @@ was written in 2001, largely as a result of a certain Australian
 cable Internet provider introducing a 3GB monthly traffic limit.
 .\"
 .SH AUTHORS
-Emil Mikulic and others. (see the AUTHORS and THANKS files)
+Emil Mikulic and others. (see the AUTHORS file)
 .\"
 .SH WEBSITE
 http://dmr.ath.cx/net/darkstat/