Bump copyright years.
[darkstat] / darkstat.8.in
1 .\"
2 .\" darkstat 3
3 .\" Copyright 2001-2014, Emil Mikulic.
4 .\"
5 .\" You may use, modify and redistribute this file under the terms of the
6 .\" GNU General Public License version 2. (see COPYING.GPL)
7 .\"
8 .TH darkstat 8 "June 2011" "@PACKAGE_STRING@"
9 .SH NAME
10 darkstat \- network statistics gatherer
11 .\"
12 .SH SYNOPSIS
13 .B darkstat
14 [
15 .BI \-i " interface"
16 ] [
17 .BI \-r " file"
18 ] [
19 .BI \-\-snaplen " bytes"
20 ] [
21 .BI \-\-pppoe
22 ] [
23 .BI \-\-syslog
24 ] [
25 .BI \-\-verbose
26 ] [
27 .BI \-\-no\-daemon
28 ] [
29 .BI \-\-no\-promisc
30 ] [
31 .BI \-\-no\-dns
32 ] [
33 .BI \-\-no\-macs
34 ] [
35 .BI \-\-no\-lastseen
36 ] [
37 .BI \-p " port"
38 ] [
39 .BI \-b " bindaddr"
40 ] [
41 .BI \-\-base " path"
42 ] [
43 .BI \-f " filter"
44 ] [
45 .BI \-l " network/netmask"
46 ] [
47 .BI \-\-local\-only
48 ] [
49 .BI \-\-chroot " dir"
50 ] [
51 .BI \-\-user " username"
52 ] [
53 .BI \-\-daylog " filename"
54 ] [
55 .BI \-\-import " filename"
56 ] [
57 .BI \-\-export " filename"
58 ] [
59 .BI \-\-pidfile " filename"
60 ] [
61 .BI \-\-hosts\-max " count"
62 ] [
63 .BI \-\-hosts\-keep " count"
64 ] [
65 .BI \-\-ports\-max " count"
66 ] [
67 .BI \-\-ports\-keep " count"
68 ] [
69 .BI \-\-highest\-port " port"
70 ] [
71 .BI \-\-wait " secs"
72 ] [
73 .BI \-\-hexdump
74 ]
75 .\"
76 .SH DESCRIPTION
77 .I darkstat
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.
81
82 All settings are passed on the commandline.
83 .\"
84 .SH OPTIONS
85 .\"
86 .TP
87 .BI \-i " interface"
88 Capture traffic on the specified network interface.
89 This is the only mandatory commandline argument.
90 .\"
91 .TP
92 .BI \-r " file"
93 Instead of capturing live traffic, read it from a
94 .BR pcap (3)
95 capture file.
96 This is only useful for development and benchmarking.
97 The
98 .BI \-r
99 and
100 .BI \-i
101 arguments are mutually exclusive.
102 .\"
103 .TP
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.
108 .\"
109 .TP
110 .BI \-\-pppoe
111 Don't use this.
112
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.
116
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
119 everything else.
120 Make sure you also specify your local address with the \fB\-l\fR
121 argument!
122 .\"
123 .TP
124 .BI \-\-syslog
125 Errors, warnings, and verbose messages will go to \fBsyslog\fR (facility
126 daemon, priority debug) instead of \fBstderr\fR.
127
128 On some systems, these messages end up in \fB/var/log/debug\fR
129 by default.
130 .\"
131 .TP
132 .BI \-\-verbose
133 Produce more verbose debugging messages.
134 .\"
135 .TP
136 .BI \-\-no\-daemon
137 Do not detach from the controlling terminal;
138 stay in the foreground.
139 .\"
140 .TP
141 .BI \-\-no\-promisc
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
146 .BR bpf (4)
147 filter.
148 .\"
149 .TP
150 .BI \-\-no\-dns
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.
154 .\"
155 .TP
156 .BI \-\-no\-macs
157 Do not display MAC addresses in the hosts table.
158 .\"
159 .TP
160 .BI \-\-no\-lastseen
161 Do not display the last seen time in the hosts table.
162 .\"
163 .TP
164 .BI \-p " port"
165 Bind the web interface to the specified port.
166 The default is 667.
167 .\"
168 .TP
169 .BI \-b " bindaddr"
170 Bind the web interface to the specified address.
171 The default is to listen on all interfaces.
172 .\"
173 .TP
174 .BI \-\-base " path"
175 .RS
176 Specify the path of the base URL.
177 This can be useful if \fIdarkstat\fR is accessed via a reverse proxy.
178
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:
183
184 .IP
185  ProxyPass /stats/ http://localhost:667/stats/
186  ProxyPassReverse /stats/ http://localhost:667/stats/
187 .PP
188
189 The default is \fI/\fR (i.e. the root).
190 .RE
191 .\"
192 .TP
193 .BI \-f " filter"
194 Use the specified filter expression when capturing traffic.
195 The filter syntax is beyond the scope of this manual page;
196 please refer to the
197 .BR tcpdump (1)
198 documentation.
199 .\"
200 .TP
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
205 host.
206 .RS
207
208 The rule is that if \fBip_addr & netmask == network\fR,
209 then that address is considered local.
210 See the usage example below.
211 .RE
212 .\"
213 .TP
214 .BI \-\-local\-only
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.
217 .\"
218 .TP
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.
224 .RS
225
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.
228
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.
233 .RE
234 .\"
235 .TP
236 .BI \-\-user " username"
237 Force \fIdarkstat\fR to drop privileges to the \fBuid\fR and \fBgid\fR of
238 the specified user.
239 Without this argument, a default value will be used, which is set at
240 build time.
241 Usually \fBnobody\fR.
242 .RS
243
244 For security reasons, this should not be \fBroot\fR.
245 .RE
246 .\"
247 .TP
248 .BI \-\-daylog " filename"
249 .RS
250 Log daily traffic statistics into the named file, relative to the
251 chroot directory.
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
254 \fIdarkstat\fR user.
255 A writeable chroot has security implications; if you are uncomfortable
256 with this, do not use the \fB\-\-daylog\fR functionality.
257
258 If the daylog argument is not specified, no logging is performed.
259
260 The daylog format is:
261
262 localtime|time_t|bytes_in|bytes_out|pkts_in|pkts_outs
263
264 Lines starting with a # are comments stating when logging started and
265 stopped.
266 .RE
267 .\"
268 .TP
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
275 database.
276 .\"
277 .TP
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
284 \fIdarkstat\fR user.
285 A writeable chroot has security implications - if you are uncomfortable
286 with this, do not use the \fB\-\-export\fR functionality.
287 .\"
288 .TP
289 .BI \-\-pidfile " filename"
290 .RS
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
294 can be left over.
295
296 For example, start \fIdarkstat\fR with:
297 .IP
298 darkstat \-i fxp0 \-\-chroot /var/run/darkstat \-\-pidfile darkstat.pid
299 .PP
300 And stop with:
301 .IP
302 kill `cat /var/run/darkstat/darkstat.pid`
303 .PP
304 By default,
305 .BR kill (1)
306 will send SIGTERM, which will cause \fIdarkstat\fR to shut down cleanly.
307 .RE
308 .\"
309 .TP
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.
313 The number of
314 .BI \-\-hosts\-max
315 must be greater than
316 .BI \-\-hosts\-keep
317 .\"
318 .TP
319 .BI \-\-hosts\-keep " count"
320 When the hosts table hits
321 .BI \-\-hosts\-max
322 and traffic is seen from a new host, we clean out the hosts table,
323 keeping only the top
324 .BI \-\-hosts\-keep
325 number of hosts, sorted by total traffic.
326 .\"
327 .TP
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.
331 The number of
332 .BI \-\-ports\-max
333 must be greater than
334 .BI \-\-ports\-keep
335 .\"
336 .TP
337 .BI \-\-ports\-keep " count"
338 When a ports table fills up, this many ports are kept and the rest are
339 discarded.
340 .\"
341 .TP
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
345 for.
346 This can be used to hide ephemeral ports.
347 By default, all ports are tracked.
348 .\"
349 .TP
350 .BI \-\-wait " secs"
351 Don't use this.
352 It's a hack to help victims of \fINetworkManager\fR and similar systems.
353 .RS
354
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.
359 .RE
360 .\"
361 .TP
362 .BI \-\-hexdump
363 Show hex dumps of received traffic.
364 This is only for debugging, and implies \fB\-\-verbose\fR and
365 \fB\-\-no\-daemon\fR.
366 .\"
367 .\" --------------------------------------------------------------------
368 .SH USAGE EXAMPLES
369 To gather statistics on the
370 .I fxp0
371 interface:
372 .IP
373 darkstat \-i fxp0
374 .PP
375 .\"
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:
379 .IP
380 darkstat \-i fxp0 \-b 192.168.0.1
381 .PP
382 .\"
383 We want to serve web pages on the standard HTTP port:
384 .IP
385 darkstat \-i fxp0 \-p 80
386 .PP
387 .\"
388 We are on Optus (cable) and don't want to account for the constant ARP
389 traffic we are receiving:
390 .IP
391 darkstat \-i fxp0 \-f "not arp"
392 .PP
393 .\"
394 We only want to account for SSH traffic:
395 .IP
396 darkstat \-i fxp0 \-f "port 22"
397 .PP
398 .\"
399 We don't want to account for traffic between internal IPs:
400 .IP
401 darkstat \-i fxp0 \-f "not (src net 192.168.0 and dst net 192.168.0)"
402 .PP
403 .\"
404 (For a full reference on filter syntax, refer to the
405 .BR tcpdump (1)
406 manpage)
407 .PP
408 .\"
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):
413 .IP
414 darkstat \-i fxp0 \-l 192.168.1.0/255.255.255.0
415 .PP
416 .\"
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:
422 .IP
423 darkstat \-i nas0 \-\-pppoe \-l 192.168.1.1/255.255.255.255
424 .\"
425 .SH SIGNALS
426 To shut
427 .I darkstat
428 down cleanly, send a SIGTERM or SIGINT signal to the
429 .I darkstat
430 parent process.
431 .PP
432 Sending the SIGUSR1 signal will cause \fIdarkstat\fR to empty out its
433 in-memory database.
434 If an \fB\-\-export\fR file was set, it will first save the database to
435 file.
436 Sending SIGUSR2 will save the database without emptying it.
437 .PP
438 .\"
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.
443 .\"
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.
448
449 I might attempt it some day.
450 In the meantime, patches would be gladly accepted.
451 .\"
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
455 on.
456
457 You can use the \fB\-l\fR argument to override the local address for
458 accounting purposes.
459 You can also use it to do accounting for a whole subnet by specifying
460 an appropriate netmask.
461 .\"
462 .SH SEE ALSO
463 .BR tcpdump (1)
464 .\"
465 .SH HISTORY
466 .I darkstat
467 was written in 2001, largely as a result of a certain Australian
468 cable Internet provider introducing a 3GB monthly traffic limit.
469 .\"
470 .SH AUTHORS
471 Emil Mikulic and others. (see the AUTHORS file)
472 .\"
473 .SH WEBSITE
474 @PACKAGE_URL@