Implement --snaplen
[darkstat] / darkstat.8
1 .\"
2 .\" darkstat 3
3 .\" Copyright 2001-2009, 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 "September 2008" "darkstat 3"
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 \-\-verbose
24 ] [
25 .BI \-\-no\-daemon
26 ] [
27 .BI \-\-no\-promisc
28 ] [
29 .BI \-\-no\-dns
30 ] [
31 .BI \-\-no\-macs
32 ] [
33 .BI \-\-no\-lastseen
34 ] [
35 .BI \-p " port"
36 ] [
37 .BI \-b " bindaddr"
38 ] [
39 .BI \-f " filter"
40 ] [
41 .BI \-l " network/netmask"
42 ] [
43 .BI \-\-chroot " dir"
44 ] [
45 .BI \-\-user " username"
46 ] [
47 .BI \-\-daylog " filename"
48 ] [
49 .BI \-\-import " filename"
50 ] [
51 .BI \-\-export " filename"
52 ] [
53 .BI \-\-pidfile " filename"
54 ] [
55 .BI \-\-hosts\-max " count"
56 ] [
57 .BI \-\-hosts\-keep " count"
58 ] [
59 .BI \-\-ports\-max " count"
60 ] [
61 .BI \-\-ports\-keep " count"
62 ] [
63 .BI \-\-highest\-port " port"
64 ] [
65 .BI \-\-hexdump
66 ]
67 .\"
68 .SH DESCRIPTION
69 .I darkstat
70 is a packet sniffer that runs as a background process on
71 a cable/DSL router, gathers all sorts of statistics about network usage,
72 and serves them over HTTP.
73
74 All settings are passed on the commandline.
75 .\"
76 .SH OPTIONS
77 .\"
78 .TP
79 .BI \-i " interface"
80 Capture traffic on the specified network interface.
81 This is the only mandatory commandline argument.
82 .\"
83 .TP
84 .BI \-r " file"
85 Instead of capturing live traffic, read it from a
86 .BR pcap (3)
87 capture file.
88 This is only useful for development and benchmarking.
89 The
90 .BI \-r
91 and
92 .BI \-i
93 arguments are mutually exclusive.
94 .\"
95 .TP
96 .BI \-\-snaplen " bytes"
97 How many bytes to capture of the start of each packet.
98 You should not need to specify this;
99 \fIdarkstat\fR will calculate it automatically.
100 .\"
101 .TP
102 .BI \-\-pppoe
103 Don't use this.
104 .RS
105
106 Instead, capture on the tunnel interface that your PPPoE software
107 provides, for example \fBtun0\fR on \fIFreeBSD\fR, \fBpppoe0\fR on
108 \fIOpenBSD\fR or \fINetBSD\fR.
109
110 If you really must, you can capture on an Ethernet interface and pass
111 this argument to have \fIdarkstat\fR decode PPPoE frames and ignore
112 everything else.
113 Make sure you also specify your local address with the \fB\-l\fR
114 argument.
115 .RE
116 .\"
117 .TP
118 .BI \-\-verbose
119 Print debugging messages to the terminal.
120 .\"
121 .TP
122 .BI \-\-no\-daemon
123 Do not detach from the controlling terminal;
124 stay in the foreground.
125 .\"
126 .TP
127 .BI \-\-no\-promisc
128 Do not use promiscuous mode to capture.
129 Note that an interface may already be in promiscuous mode.
130 If this is a problem, use an appropriate
131 .BR bpf (4)
132 filter.
133 .\"
134 .TP
135 .BI \-\-no\-dns
136 Do not resolve IPs to host names.
137 This can significantly reduce memory footprint on small systems
138 as an extra process is created for DNS resolving.
139 .\"
140 .TP
141 .BI \-\-no\-macs
142 Do not display MAC addresses in the hosts table.
143 .\"
144 .TP
145 .BI \-\-no\-lastseen
146 Do not display the last seen time in the hosts table.
147 .\"
148 .TP
149 .BI \-p " port"
150 Bind the web interface to the specified port.
151 The default is 667.
152 .\"
153 .TP
154 .BI \-b " bindaddr"
155 Bind the web interface to the specified address.
156 The default is to listen on all interfaces.
157 .\"
158 .TP
159 .BI \-f " filter"
160 Use the specified filter expression when capturing traffic.
161 The filter syntax is beyond the scope of this manual page;
162 please refer to the
163 .BR tcpdump (1)
164 documentation.
165 .\"
166 .TP
167 .BI \-l " network/netmask"
168 Define a "local network" according to the network and netmask addresses.
169 All traffic entering or leaving this network will be graphed, as opposed
170 to the default behaviour of only graphing traffic to and from the local
171 host.
172 .RS
173
174 The rule is that if \fBip_addr & netmask == network\fR,
175 then that address is considered local.
176 See the usage example below.
177 .RE
178 .\"
179 .TP
180 .BI \-\-chroot " dir"
181 Force \fIdarkstat\fR to \fBchroot()\fR into the specified directory.
182 Without this argument, a default directory will be used, which is
183 determined at build time.
184 Usually \fI/var/empty\fR or \fI/var/lib/empty\fR.
185 .RS
186
187 For security reasons, this directory should be empty, and the user that
188 \fIdarkstat\fR is running as should not have write access to it.
189
190 However, if you wish to use \fB\-\-daylog\fR or \fB\-\-export\fR,
191 \fIdarkstat\fR will need write access to the chroot.
192 If you are uncomfortable with the security implications, don't
193 use any functionality that requires write access.
194 .RE
195 .\"
196 .TP
197 .BI \-\-user " username"
198 Force \fIdarkstat\fR to drop privileges to the \fBuid\fR and \fBgid\fR of
199 the specified user.
200 Without this argument, a default value will be used, which is set at
201 build time.
202 Usually \fBnobody\fR.
203 .RS
204
205 For security reasons, this should not be \fBroot\fR.
206 .RE
207 .\"
208 .TP
209 .BI \-\-daylog " filename"
210 .RS
211 Log daily traffic statistics into the named file, relative to the
212 chroot directory.
213 If you wish to use \fB\-\-daylog\fR, you must first specify a
214 \fB\-\-chroot\fR directory, and it must be writeable by the
215 \fIdarkstat\fR user.
216 A writeable chroot has security implications; if you are uncomfortable
217 with this, do not use the \fB\-\-daylog\fR functionality.
218
219 If the daylog argument is not specified, no logging is performed.
220
221 The daylog format is:
222
223 localtime|time_t|bytes_in|bytes_out|pkts_in|pkts_outs
224
225 Lines starting with a # are comments stating when logging started and
226 stopped.
227 .RE
228 .\"
229 .TP
230 .BI \-\-import " filename"
231 Upon starting, import a \fIdarkstat\fR database from the named file,
232 relative to the chroot directory.
233 If you wish to use \fB\-\-import\fR, you must first specify a
234 \fB\-\-chroot\fR directory.
235 If the import is unsuccessful, \fIdarkstat\fR will start with an empty
236 database.
237 .\"
238 .TP
239 .BI \-\-export " filename"
240 On shutdown, and upon receiving SIGUSR1, export the in-memory database
241 to the named file, relative to the chroot directory.
242 If you wish to use \fB\-\-export\fR, you must first specify a
243 \fB\-\-chroot\fR directory, and it must be writeable by the
244 \fIdarkstat\fR user.
245 A writeable chroot has security implications - if you are uncomfortable
246 with this, do not use the \fB\-\-export\fR functionality.
247 .\"
248 .TP
249 .BI \-\-pidfile " filename"
250 .RS
251 Creates a file containing the process ID of \fIdarkstat\fR.
252 This file will be unlinked upon clean shutdown.
253 As with all pidfiles, if \fIdarkstat\fR dies uncleanly, a stale pidfile
254 can be left over.
255
256 For example, start \fIdarkstat\fR with:
257 .IP
258 darkstat \-i fxp0 \-\-chroot /var/run/darkstat \-\-pidfile darkstat.pid
259 .PP
260 And stop with:
261 .IP
262 kill `cat /var/run/darkstat/darkstat.pid`
263 .PP
264 By default,
265 .BR kill (1)
266 will send SIGTERM, which will cause \fIdarkstat\fR to shut down cleanly.
267 .RE
268 .\"
269 .TP
270 .BI \-\-hosts\-max " count"
271 The maximum number of hosts that will be kept in the hosts table.
272 This is used to limit how much accounting data will be kept in memory.
273 The number of
274 .BI \-\-hosts\-max
275 must be greater than
276 .BI \-\-hosts\-keep
277 .\"
278 .TP
279 .BI \-\-hosts\-keep " count"
280 When the hosts table hits
281 .BI \-\-hosts\-max
282 and traffic is seen from a new host, we clean out the hosts table,
283 keeping only the top
284 .BI \-\-hosts\-keep
285 number of hosts, sorted by total traffic.
286 .\"
287 .TP
288 .BI \-\-ports\-max " count"
289 The maximum number of ports that will be tracked for each host.
290 This is used to limit how much accounting data will be kept in memory.
291 The number of
292 .BI \-\-ports\-max
293 must be greater than
294 .BI \-\-ports\-keep
295 .\"
296 .TP
297 .BI \-\-ports\-keep " count"
298 When a ports table fills up, this many ports are kept and the rest are
299 discarded.
300 .\"
301 .TP
302 .BI \-\-highest\-port " port"
303 Ports that are numerically higher than this will not appear in the
304 per-host ports tables, although their traffic will still be accounted
305 for.
306 This can be used to hide ephemeral ports.
307 By default, all ports are tracked.
308 .\"
309 .TP
310 .BI \-\-hexdump
311 Show hex dumps of received traffic.
312 This is only for debugging, and implies \-\-verbose and \-\-no\-daemon.
313 .\"
314 .\" --------------------------------------------------------------------
315 .SH USAGE EXAMPLES
316 To gather statistics on the
317 .I fxp0
318 interface:
319 .IP
320 darkstat \-i fxp0
321 .PP
322 .\"
323 We want to account for traffic on the Internet-facing interface,
324 but only serve web pages to our private local network where we have the
325 IP address 192.168.0.1:
326 .IP
327 darkstat \-i fxp0 \-b 192.168.0.1
328 .PP
329 .\"
330 We want to serve web pages on the standard HTTP port:
331 .IP
332 darkstat \-i fxp0 \-p 80
333 .PP
334 .\"
335 We are on Optus (cable) and don't want to account for the constant ARP
336 traffic we are receiving:
337 .IP
338 darkstat \-i fxp0 \-f "not arp"
339 .PP
340 .\"
341 We only want to account for SSH traffic:
342 .IP
343 darkstat \-i fxp0 \-f "port 22"
344 .PP
345 .\"
346 We don't want to account for network internal traffic:
347 .IP
348 darkstat \-i fxp0 \-f "not (src net 192.168.0 and dst net 192.168.0)"
349 .PP
350 .\"
351 (For a full reference on filter syntax, refer to the
352 .BR tcpdump (1)
353 manpage)
354 .PP
355 .\"
356 We have a network consisting of a gateway server (192.168.1.1) and a few
357 workstations (192.168.1.2, 192.168.1.3, etc.) and we want to graph all
358 traffic entering and leaving the local network, not just the gateway
359 server (which is running \fIdarkstat\fR):
360 .IP
361 darkstat \-i fxp0 \-l 192.168.1.0/255.255.255.0
362 .PP
363 .\"
364 We want to specify the local IP of the gateway manually because it
365 cannot be automatically detected, e.g. \fB\-\-pppoe\fR is in use.
366 Note the /32 netmask:
367 .IP
368 darkstat \-i fxp0 \-\-pppoe \-l 192.168.1.1/255.255.255.255
369 .\"
370 .SH SIGNALS
371 To shut
372 .I darkstat
373 down cleanly, send a SIGTERM or SIGINT signal to the
374 .I darkstat
375 parent process.
376 .PP
377 Sending the SIGUSR1 signal will cause \fIdarkstat\fR to empty out its
378 in-memory database.
379 If an \fB\-\-export\fR file was set, it will first save the database to
380 file.
381 .PP
382 .\"
383 .SH FREQUENTLY ASKED QUESTIONS
384 .SS How many bytes does each bar on the graph represent?
385 Hover your mouse cursor over a bar and you should get a tooltip
386 saying exactly how many bytes in and out the bar represents.
387 .\"
388 .SS Why aren't there labels / tics / a scale on the graphs?
389 Because implementing them is hard.
390 And doing so \fIcorrectly\fR, and in a way that works across all
391 browsers, looks pretty much impossible.
392
393 I might attempt it some day.
394 In the meantime, patches would be gladly accepted.
395 .\"
396 .SS Why are the graphs blank?  All the bars are zero.
397 The graphs only show traffic in/out of the local host, which is
398 determined by getting the IP address of the interface you're sniffing
399 on.
400
401 You can use the \fB\-l\fR argument to override the local address for
402 accounting purposes.
403 You can also use it to do accounting for a whole subnet by specifying
404 an appropriate netmask.
405 .\"
406 .SH SEE ALSO
407 .BR tcpdump (1)
408 .\"
409 .SH HISTORY
410 .I darkstat
411 was written in 2001, largely as a result of a certain Australian
412 cable Internet provider introducing a 3GB monthly traffic limit.
413 .\"
414 .SH AUTHORS
415 Emil Mikulic and others. (see the AUTHORS and THANKS files)
416 .\"
417 .SH WEBSITE
418 http://dmr.ath.cx/net/darkstat/