3 .\" Copyright 2001-2009, 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 "September 2008" "darkstat 3"
10 darkstat \- network statistics gatherer
37 .BI \-l " network/netmask"
41 .BI \-\-user " username"
43 .BI \-\-daylog " filename"
45 .BI \-\-import " filename"
47 .BI \-\-export " filename"
49 .BI \-\-pidfile " filename"
51 .BI \-\-hosts\-max " count"
53 .BI \-\-hosts\-keep " count"
55 .BI \-\-ports\-max " count"
57 .BI \-\-ports\-keep " count"
59 .BI \-\-highest\-port " port"
66 is a packet sniffer that runs as a background process on
67 a cable/DSL router, gathers all sorts of statistics about network usage,
68 and serves them over HTTP.
70 All settings are passed on the commandline.
76 Capture traffic on the specified network interface.
77 This is the only mandatory commandline argument.
81 Instead of capturing live traffic, read it from a
84 This is only useful for development and benchmarking.
89 arguments are mutually exclusive.
96 Instead, capture on the tunnel interface that your PPPoE software
97 provides, for example \fBtun0\fR on \fIFreeBSD\fR, \fBpppoe0\fR on
98 \fIOpenBSD\fR or \fINetBSD\fR.
100 If you really must, you can capture on an Ethernet interface and pass
101 this argument to have \fIdarkstat\fR decode PPPoE frames and ignore
103 Make sure you also specify your local address with the \fB\-l\fR
109 Print debugging messages to the terminal.
113 Do not detach from the controlling terminal;
114 stay in the foreground.
118 Do not use promiscuous mode to capture.
119 Note that an interface may already be in promiscuous mode.
120 If this is a problem, use an appropriate
126 Do not resolve IPs to host names.
127 This can significantly reduce memory footprint on small systems
128 as an extra process is created for DNS resolving.
132 Do not display MAC addresses in hosts table.
136 Bind the web interface to the specified port.
141 Bind the web interface to the specified address.
142 The default is to listen on all interfaces.
146 Use the specified filter expression when capturing traffic.
147 The filter syntax is beyond the scope of this manual page;
153 .BI \-l " network/netmask"
154 Define a "local network" according to the network and netmask addresses.
155 All traffic entering or leaving this network will be graphed, as opposed
156 to the default behaviour of only graphing traffic to and from the local
160 The rule is that if \fBip_addr & netmask == network\fR,
161 then that address is considered local.
162 See the usage example below.
166 .BI \-\-chroot " dir"
167 Force \fIdarkstat\fR to \fBchroot()\fR into the specified directory.
168 Without this argument, a default directory will be used, which is
169 determined at build time.
170 Usually \fI/var/empty\fR or \fI/var/lib/empty\fR.
173 For security reasons, this directory should be empty, and the user that
174 \fIdarkstat\fR is running as should not have write access to it.
176 However, if you wish to use \fB\-\-daylog\fR or \fB\-\-export\fR,
177 \fIdarkstat\fR will need write access to the chroot.
178 If you are uncomfortable with the security implications, don't
179 use any functionality that requires write access.
183 .BI \-\-user " username"
184 Force \fIdarkstat\fR to drop privileges to the \fBuid\fR and \fBgid\fR of
186 Without this argument, a default value will be used, which is set at
188 Usually \fBnobody\fR.
191 For security reasons, this should not be \fBroot\fR.
195 .BI \-\-daylog " filename"
197 Log daily traffic statistics into the named file, relative to the
199 If you wish to use \fB\-\-daylog\fR, you must first specify a
200 \fB\-\-chroot\fR directory, and it must be writeable by the
202 A writeable chroot has security implications; if you are uncomfortable
203 with this, do not use the \fB\-\-daylog\fR functionality.
205 If the daylog argument is not specified, no logging is performed.
207 The daylog format is:
209 localtime|time_t|bytes_in|bytes_out|pkts_in|pkts_outs
211 Lines starting with a # are comments stating when logging started and
216 .BI \-\-import " filename"
217 Upon starting, import a \fIdarkstat\fR database from the named file,
218 relative to the chroot directory.
219 If you wish to use \fB\-\-import\fR, you must first specify a
220 \fB\-\-chroot\fR directory.
221 If the import is unsuccessful, \fIdarkstat\fR will start with an empty
225 .BI \-\-export " filename"
226 On shutdown, and upon receiving SIGUSR1, export the in-memory database
227 to the named file, relative to the chroot directory.
228 If you wish to use \fB\-\-export\fR, you must first specify a
229 \fB\-\-chroot\fR directory, and it must be writeable by the
231 A writeable chroot has security implications - if you are uncomfortable
232 with this, do not use the \fB\-\-export\fR functionality.
235 .BI \-\-pidfile " filename"
237 Creates a file containing the process ID of \fIdarkstat\fR.
238 This file will be unlinked upon clean shutdown.
239 As with all pidfiles, if \fIdarkstat\fR dies uncleanly, a stale pidfile
242 For example, start \fIdarkstat\fR with:
244 darkstat \-i fxp0 \-\-chroot /var/run/darkstat \-\-pidfile darkstat.pid
248 kill `cat /var/run/darkstat/darkstat.pid`
252 will send SIGTERM, which will cause \fIdarkstat\fR to shut down cleanly.
256 .BI \-\-hosts\-max " count"
257 The maximum number of hosts that will be kept in the hosts table.
258 This is used to limit how much accounting data will be kept in memory.
265 .BI \-\-hosts\-keep " count"
266 When the hosts table hits
268 and traffic is seen from a new host, we clean out the hosts table,
271 number of hosts, sorted by total traffic.
274 .BI \-\-ports\-max " count"
275 The maximum number of ports that will be tracked for each host.
276 This is used to limit how much accounting data will be kept in memory.
283 .BI \-\-ports\-keep " count"
284 When a ports table fills up, this many ports are kept and the rest are
288 .BI \-\-highest\-port " port"
289 Ports that are numerically higher than this will not appear in the
290 per-host ports tables, although their traffic will still be accounted
292 This can be used to hide ephemeral ports.
293 By default, all ports are tracked.
297 Show hex dumps of received traffic.
298 This is only for debugging, and implies \-\-verbose and \-\-no\-daemon.
300 .\" --------------------------------------------------------------------
302 To gather statistics on the
309 We want to account for traffic on the Internet-facing interface,
310 but only serve web pages to our private local network where we have the
311 IP address 192.168.0.1:
313 darkstat \-i fxp0 \-b 192.168.0.1
316 We want to serve web pages on the standard HTTP port:
318 darkstat \-i fxp0 \-p 80
321 We are on Optus (cable) and don't want to account for the constant ARP
322 traffic we are receiving:
324 darkstat \-i fxp0 \-f "not arp"
327 We only want to account for SSH traffic:
329 darkstat \-i fxp0 \-f "port 22"
332 We don't want to account for network internal traffic:
334 darkstat \-i fxp0 \-f "not (src net 192.168.0 and dst net 192.168.0)"
337 (For a full reference on filter syntax, refer to the
342 We have a network consisting of a gateway server (192.168.1.1) and a few
343 workstations (192.168.1.2, 192.168.1.3, etc.) and we want to graph all
344 traffic entering and leaving the local network, not just the gateway
345 server (which is running \fIdarkstat\fR):
347 darkstat \-i fxp0 \-l 192.168.1.0/255.255.255.0
350 We want to specify the local IP of the gateway manually because it
351 cannot be automatically detected, e.g. \fB\-\-pppoe\fR is in use.
352 Note the /32 netmask:
354 darkstat \-i fxp0 \-\-pppoe \-l 192.168.1.1/255.255.255.255
359 down cleanly, send a SIGTERM or SIGINT signal to the
363 Sending the SIGUSR1 signal will cause \fIdarkstat\fR to empty out its
365 If an \fB\-\-export\fR file was set, it will first save the database to
369 .SH FREQUENTLY ASKED QUESTIONS
370 .SS How many bytes does each bar on the graph represent?
371 Hover your mouse cursor over a bar and you should get a tooltip
372 saying exactly how many bytes in and out the bar represents.
374 .SS Why aren't there labels / tics / a scale on the graphs?
375 Because implementing them is hard.
376 And doing so \fIcorrectly\fR, and in a way that works across all
377 browsers, looks pretty much impossible.
379 I might attempt it some day.
380 In the meantime, patches would be gladly accepted.
382 .SS Why are the graphs blank? All the bars are zero.
383 The graphs only show traffic in/out of the local host, which is
384 determined by getting the IP address of the interface you're sniffing
387 You can use the \fB\-l\fR argument to override the local address for
389 You can also use it to do accounting for a whole subnet by specifying
390 an appropriate netmask.
397 was written in 2001, largely as a result of a certain Australian
398 cable Internet provider introducing a 3GB monthly traffic limit.
401 Emil Mikulic and others. (see the AUTHORS and THANKS files)
404 http://dmr.ath.cx/net/darkstat/