3 .\" Copyright 2001-2014, Emil Mikulic.
5 .\" You may use, modify and redistribute this file under the terms of the
6 .\" GNU General Public License version 2. (see COPYING.GPL)
8 .TH darkstat 8 "June 2011" "@PACKAGE_STRING@"
10 darkstat \- network statistics gatherer
19 .BI \-\-snaplen " bytes"
45 .BI \-l " network/netmask"
51 .BI \-\-user " username"
53 .BI \-\-daylog " filename"
55 .BI \-\-import " filename"
57 .BI \-\-export " filename"
59 .BI \-\-pidfile " filename"
61 .BI \-\-hosts\-max " count"
63 .BI \-\-hosts\-keep " count"
65 .BI \-\-ports\-max " count"
67 .BI \-\-ports\-keep " count"
69 .BI \-\-highest\-port " port"
78 is a packet sniffer that runs as a background process,
79 gathers all sorts of statistics about network usage,
80 and serves them over HTTP.
82 All settings are passed on the commandline.
88 Capture traffic on the specified network interface.
89 This is the only mandatory commandline argument.
93 Instead of capturing live traffic, read it from a
96 This is only useful for development and benchmarking.
101 arguments are mutually exclusive.
104 .BI \-\-snaplen " bytes"
105 How many bytes to capture from the start of each packet.
106 You should not need to specify this;
107 \fIdarkstat\fR will calculate it automatically.
113 Instead, capture on the tunnel interface that your PPPoE software
114 provides, for example \fBtun0\fR on \fIFreeBSD\fR, \fBpppoe0\fR on
115 \fIOpenBSD\fR or \fINetBSD\fR.
117 If you really must, you can capture on an Ethernet interface and pass
118 this argument to have \fIdarkstat\fR decode PPPoE frames and ignore
120 Make sure you also specify your local address with the \fB\-l\fR
125 Errors, warnings, and verbose messages will go to \fBsyslog\fR (facility
126 daemon, priority debug) instead of \fBstderr\fR.
128 On some systems, these messages end up in \fB/var/log/debug\fR
133 Produce more verbose debugging messages.
137 Do not detach from the controlling terminal;
138 stay in the foreground.
142 Do not use promiscuous mode to capture.
143 Note that an interface may already be in promiscuous mode, or may later
144 enter promiscuous mode, due to circumstances beyond \fIdarkstat\fR's control.
145 If this is a problem, use \fB\-f\fR to specify an appropriate
151 Do not resolve IPs to host names.
152 This can significantly reduce memory footprint on small systems
153 as an extra process is created for DNS resolution.
157 Do not display MAC addresses in the hosts table.
161 Do not display the last seen time in the hosts table.
165 Bind the web interface to the specified port.
170 Bind the web interface to the specified address.
171 The default is to listen on all interfaces.
176 Specify the path of the base URL.
177 This can be useful if \fIdarkstat\fR is accessed via a reverse proxy.
179 For example, if you use Apache's \fImod_proxy\fR and want to avoid a
180 complicated setup with \fImod_proxy_html\fR (and \fImod_header\fR to unset
181 the \fIAccept-Encoding\fR header), just set the base path to something like
182 \fIstats\fR and use a config similar to the following snippet:
185 ProxyPass /stats/ http://localhost:667/stats/
186 ProxyPassReverse /stats/ http://localhost:667/stats/
189 The default is \fI/\fR (i.e. the root).
194 Use the specified filter expression when capturing traffic.
195 The filter syntax is beyond the scope of this manual page;
201 .BI \-l " network/netmask"
202 Define a "local network" according to the network and netmask addresses.
203 All traffic entering or leaving this network will be graphed, as opposed
204 to the default behaviour of only graphing traffic to and from the local
208 The rule is that if \fBip_addr & netmask == network\fR,
209 then that address is considered local.
210 See the usage example below.
215 Make the web interface only display hosts on the "local network."
216 This is intended to be used together with the \fB\-l\fR argument.
219 .BI \-\-chroot " dir"
220 Force \fIdarkstat\fR to \fBchroot()\fR into the specified directory.
221 Without this argument, a default directory will be used, which is
222 determined at build time.
223 Usually \fI/var/empty\fR or \fI/var/lib/empty\fR.
226 For security reasons, this directory should be empty, and the user that
227 \fIdarkstat\fR is running as should not have write access to it.
229 However, if you wish to use \fB\-\-daylog\fR or \fB\-\-export\fR,
230 \fIdarkstat\fR will need write access to the chroot.
231 If you are uncomfortable with the security implications, don't
232 use any functionality that requires write access.
236 .BI \-\-user " username"
237 Force \fIdarkstat\fR to drop privileges to the \fBuid\fR and \fBgid\fR of
239 Without this argument, a default value will be used, which is set at
241 Usually \fBnobody\fR.
244 For security reasons, this should not be \fBroot\fR.
248 .BI \-\-daylog " filename"
250 Log daily traffic statistics into the named file, relative to the
252 If you wish to use \fB\-\-daylog\fR, you must first specify a
253 \fB\-\-chroot\fR directory, and it must be writeable by the
255 A writeable chroot has security implications; if you are uncomfortable
256 with this, do not use the \fB\-\-daylog\fR functionality.
258 If the daylog argument is not specified, no logging is performed.
260 The daylog format is:
262 localtime|time_t|bytes_in|bytes_out|pkts_in|pkts_outs
264 Lines starting with a # are comments stating when logging started and
269 .BI \-\-import " filename"
270 Upon starting, import a \fIdarkstat\fR database from the named file,
271 relative to the chroot directory.
272 If you wish to use \fB\-\-import\fR, you must first specify a
273 \fB\-\-chroot\fR directory.
274 If the import is unsuccessful, \fIdarkstat\fR will start with an empty
278 .BI \-\-export " filename"
279 On shutdown, or upon receiving SIGUSR1 or SIGUSR2,
280 export the in-memory database
281 to the named file, relative to the chroot directory.
282 If you wish to use \fB\-\-export\fR, you must first specify a
283 \fB\-\-chroot\fR directory, and it must be writeable by the
285 A writeable chroot has security implications - if you are uncomfortable
286 with this, do not use the \fB\-\-export\fR functionality.
289 .BI \-\-pidfile " filename"
291 Creates a file containing the process ID of \fIdarkstat\fR.
292 This file will be unlinked upon clean shutdown.
293 As with all pidfiles, if \fIdarkstat\fR dies uncleanly, a stale pidfile
296 For example, start \fIdarkstat\fR with:
298 darkstat \-i fxp0 \-\-chroot /var/run/darkstat \-\-pidfile darkstat.pid
302 kill `cat /var/run/darkstat/darkstat.pid`
306 will send SIGTERM, which will cause \fIdarkstat\fR to shut down cleanly.
310 .BI \-\-hosts\-max " count"
311 The maximum number of hosts that will be kept in the hosts table.
312 This is used to limit how much accounting data will be kept in memory.
319 .BI \-\-hosts\-keep " count"
320 When the hosts table hits
322 and traffic is seen from a new host, we clean out the hosts table,
325 number of hosts, sorted by total traffic.
328 .BI \-\-ports\-max " count"
329 The maximum number of ports that will be tracked for each host.
330 This is used to limit how much accounting data will be kept in memory.
337 .BI \-\-ports\-keep " count"
338 When a ports table fills up, this many ports are kept and the rest are
342 .BI \-\-highest\-port " port"
343 Ports that are numerically higher than this will not appear in the
344 per-host ports tables, although their traffic will still be accounted
346 This can be used to hide ephemeral ports.
347 By default, all ports are tracked.
352 It's a hack to help victims of \fINetworkManager\fR and similar systems.
355 You should start \fIdarkstat\fR after the capture interface has come up.
356 If you can't, specifying the \fB\-\-wait\fR option will make \fIdarkstat\fR
357 sleep up to the specified number of seconds for the interface to become ready.
358 Zero means wait indefinitely.
363 Show hex dumps of received traffic.
364 This is only for debugging, and implies \fB\-\-verbose\fR and
365 \fB\-\-no\-daemon\fR.
367 .\" --------------------------------------------------------------------
369 To gather statistics on the
376 We want to account for traffic on the Internet-facing interface,
377 but only serve web pages to our private local network where we have the
378 IP address 192.168.0.1:
380 darkstat \-i fxp0 \-b 192.168.0.1
383 We want to serve web pages on the standard HTTP port:
385 darkstat \-i fxp0 \-p 80
388 We are on Optus (cable) and don't want to account for the constant ARP
389 traffic we are receiving:
391 darkstat \-i fxp0 \-f "not arp"
394 We only want to account for SSH traffic:
396 darkstat \-i fxp0 \-f "port 22"
399 We don't want to account for traffic between internal IPs:
401 darkstat \-i fxp0 \-f "not (src net 192.168.0 and dst net 192.168.0)"
404 (For a full reference on filter syntax, refer to the
409 We have a network consisting of a gateway server (192.168.1.1) and a few
410 workstations (192.168.1.2, 192.168.1.3, etc.) and we want to graph all
411 traffic entering and leaving the local network, not just the gateway
412 server (which is running \fIdarkstat\fR):
414 darkstat \-i fxp0 \-l 192.168.1.0/255.255.255.0
417 On some systems, we can't capture on a "decoded" interface but
418 only on \fInas0\fR which returns PPPoE encapsulated packets.
419 Do PPPoE decoding, and override the local IP manually since it
420 cannot be automatically detected.
421 Note the /32 netmask:
423 darkstat \-i nas0 \-\-pppoe \-l 192.168.1.1/255.255.255.255
428 down cleanly, send a SIGTERM or SIGINT signal to the
432 Sending the SIGUSR1 signal will cause \fIdarkstat\fR to empty out its
434 If an \fB\-\-export\fR file was set, it will first save the database to
436 Sending SIGUSR2 will save the database without emptying it.
439 .SH FREQUENTLY ASKED QUESTIONS
440 .SS How many bytes does each bar on the graph represent?
441 Hover your mouse cursor over a bar and you should get a tooltip
442 saying exactly how many bytes in and out the bar represents.
444 .SS Why aren't there labels / tics / a scale on the graphs?
445 Because implementing them is hard.
446 And doing so \fIcorrectly\fR, and in a way that works across all
447 browsers, looks pretty much impossible.
449 I might attempt it some day.
450 In the meantime, patches would be gladly accepted.
452 .SS Why are the graphs blank? All the bars are zero.
453 The graphs only show traffic in/out of the local host, which is
454 determined by getting the IP address of the interface you're sniffing
457 You can use the \fB\-l\fR argument to override the local address for
459 You can also use it to do accounting for a whole subnet by specifying
460 an appropriate netmask.
467 was written in 2001, largely as a result of a certain Australian
468 cable Internet provider introducing a 3GB monthly traffic limit.
471 Emil Mikulic and others. (see the AUTHORS file)