Implement --hexdump
[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 \-\-pppoe
20 ] [
21 .BI \-\-verbose
22 ] [
23 .BI \-\-no\-daemon
24 ] [
25 .BI \-\-no\-promisc
26 ] [
27 .BI \-\-no\-dns
28 ] [
29 .BI \-\-no\-macs
30 ] [
31 .BI \-p " port"
32 ] [
33 .BI \-b " bindaddr"
34 ] [
35 .BI \-f " filter"
36 ] [
37 .BI \-l " network/netmask"
38 ] [
39 .BI \-\-chroot " dir"
40 ] [
41 .BI \-\-user " username"
42 ] [
43 .BI \-\-daylog " filename"
44 ] [
45 .BI \-\-import " filename"
46 ] [
47 .BI \-\-export " filename"
48 ] [
49 .BI \-\-pidfile " filename"
50 ] [
51 .BI \-\-hosts\-max " count"
52 ] [
53 .BI \-\-hosts\-keep " count"
54 ] [
55 .BI \-\-ports\-max " count"
56 ] [
57 .BI \-\-ports\-keep " count"
58 ] [
59 .BI \-\-highest\-port " port"
60 ] [
61 .BI \-\-hexdump
62 ]
63 .\"
64 .SH DESCRIPTION
65 .I darkstat
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.
69
70 All settings are passed on the commandline.
71 .\"
72 .SH OPTIONS
73 .\"
74 .TP
75 .BI \-i " interface"
76 Capture traffic on the specified network interface.
77 This is the only mandatory commandline argument.
78 .\"
79 .TP
80 .BI \-r " file"
81 Instead of capturing live traffic, read it from a
82 .BR pcap (3)
83 capture file.
84 This is only useful for development and benchmarking.
85 The
86 .BI \-r
87 and
88 .BI \-i
89 arguments are mutually exclusive.
90 .\"
91 .TP
92 .BI \-\-pppoe
93 Don't use this.
94 .RS
95
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.
99
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
102 everything else.
103 Make sure you also specify your local address with the \fB\-l\fR
104 argument.
105 .RE
106 .\"
107 .TP
108 .BI \-\-verbose
109 Print debugging messages to the terminal.
110 .\"
111 .TP
112 .BI \-\-no\-daemon
113 Do not detach from the controlling terminal;
114 stay in the foreground.
115 .\"
116 .TP
117 .BI \-\-no\-promisc
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
121 .BR bpf (4)
122 filter.
123 .\"
124 .TP
125 .BI \-\-no\-dns
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.
129 .\"
130 .TP
131 .BI \-\-no\-macs
132 Do not display MAC addresses in hosts table.
133 .\"
134 .TP
135 .BI \-p " port"
136 Bind the web interface to the specified port.
137 The default is 667.
138 .\"
139 .TP
140 .BI \-b " bindaddr"
141 Bind the web interface to the specified address.
142 The default is to listen on all interfaces.
143 .\"
144 .TP
145 .BI \-f " filter"
146 Use the specified filter expression when capturing traffic.
147 The filter syntax is beyond the scope of this manual page;
148 please refer to the
149 .BR tcpdump (1)
150 documentation.
151 .\"
152 .TP
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
157 host.
158 .RS
159
160 The rule is that if \fBip_addr & netmask == network\fR,
161 then that address is considered local.
162 See the usage example below.
163 .RE
164 .\"
165 .TP
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.
171 .RS
172
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.
175
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.
180 .RE
181 .\"
182 .TP
183 .BI \-\-user " username"
184 Force \fIdarkstat\fR to drop privileges to the \fBuid\fR and \fBgid\fR of
185 the specified user.
186 Without this argument, a default value will be used, which is set at
187 build time.
188 Usually \fBnobody\fR.
189 .RS
190
191 For security reasons, this should not be \fBroot\fR.
192 .RE
193 .\"
194 .TP
195 .BI \-\-daylog " filename"
196 .RS
197 Log daily traffic statistics into the named file, relative to the
198 chroot directory.
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
201 \fIdarkstat\fR user.
202 A writeable chroot has security implications; if you are uncomfortable
203 with this, do not use the \fB\-\-daylog\fR functionality.
204
205 If the daylog argument is not specified, no logging is performed.
206
207 The daylog format is:
208
209 localtime|time_t|bytes_in|bytes_out|pkts_in|pkts_outs
210
211 Lines starting with a # are comments stating when logging started and
212 stopped.
213 .RE
214 .\"
215 .TP
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
222 database.
223 .\"
224 .TP
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
230 \fIdarkstat\fR user.
231 A writeable chroot has security implications - if you are uncomfortable
232 with this, do not use the \fB\-\-export\fR functionality.
233 .\"
234 .TP
235 .BI \-\-pidfile " filename"
236 .RS
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
240 can be left over.
241
242 For example, start \fIdarkstat\fR with:
243 .IP
244 darkstat \-i fxp0 \-\-chroot /var/run/darkstat \-\-pidfile darkstat.pid
245 .PP
246 And stop with:
247 .IP
248 kill `cat /var/run/darkstat/darkstat.pid`
249 .PP
250 By default,
251 .BR kill (1)
252 will send SIGTERM, which will cause \fIdarkstat\fR to shut down cleanly.
253 .RE
254 .\"
255 .TP
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.
259 The number of
260 .BI \-\-hosts\-max
261 must be greater than
262 .BI \-\-hosts\-keep
263 .\"
264 .TP
265 .BI \-\-hosts\-keep " count"
266 When the hosts table hits
267 .BI \-\-hosts\-max
268 and traffic is seen from a new host, we clean out the hosts table,
269 keeping only the top
270 .BI \-\-hosts\-keep
271 number of hosts, sorted by total traffic.
272 .\"
273 .TP
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.
277 The number of
278 .BI \-\-ports\-max
279 must be greater than
280 .BI \-\-ports\-keep
281 .\"
282 .TP
283 .BI \-\-ports\-keep " count"
284 When a ports table fills up, this many ports are kept and the rest are
285 discarded.
286 .\"
287 .TP
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
291 for.
292 This can be used to hide ephemeral ports.
293 By default, all ports are tracked.
294 .\"
295 .TP
296 .BI \-\-hexdump
297 Show hex dumps of received traffic.
298 This is only for debugging, and implies \-\-verbose and \-\-no\-daemon.
299 .\"
300 .\" --------------------------------------------------------------------
301 .SH USAGE EXAMPLES
302 To gather statistics on the
303 .I fxp0
304 interface:
305 .IP
306 darkstat \-i fxp0
307 .PP
308 .\"
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:
312 .IP
313 darkstat \-i fxp0 \-b 192.168.0.1
314 .PP
315 .\"
316 We want to serve web pages on the standard HTTP port:
317 .IP
318 darkstat \-i fxp0 \-p 80
319 .PP
320 .\"
321 We are on Optus (cable) and don't want to account for the constant ARP
322 traffic we are receiving:
323 .IP
324 darkstat \-i fxp0 \-f "not arp"
325 .PP
326 .\"
327 We only want to account for SSH traffic:
328 .IP
329 darkstat \-i fxp0 \-f "port 22"
330 .PP
331 .\"
332 We don't want to account for network internal traffic:
333 .IP
334 darkstat \-i fxp0 \-f "not (src net 192.168.0 and dst net 192.168.0)"
335 .PP
336 .\"
337 (For a full reference on filter syntax, refer to the
338 .BR tcpdump (1)
339 manpage)
340 .PP
341 .\"
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):
346 .IP
347 darkstat \-i fxp0 \-l 192.168.1.0/255.255.255.0
348 .PP
349 .\"
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:
353 .IP
354 darkstat \-i fxp0 \-\-pppoe \-l 192.168.1.1/255.255.255.255
355 .\"
356 .SH SIGNALS
357 To shut
358 .I darkstat
359 down cleanly, send a SIGTERM or SIGINT signal to the
360 .I darkstat
361 parent process.
362 .PP
363 Sending the SIGUSR1 signal will cause \fIdarkstat\fR to empty out its
364 in-memory database.
365 If an \fB\-\-export\fR file was set, it will first save the database to
366 file.
367 .PP
368 .\"
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.
373 .\"
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.
378
379 I might attempt it some day.
380 In the meantime, patches would be gladly accepted.
381 .\"
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
385 on.
386
387 You can use the \fB\-l\fR argument to override the local address for
388 accounting purposes.
389 You can also use it to do accounting for a whole subnet by specifying
390 an appropriate netmask.
391 .\"
392 .SH SEE ALSO
393 .BR tcpdump (1)
394 .\"
395 .SH HISTORY
396 .I darkstat
397 was written in 2001, largely as a result of a certain Australian
398 cable Internet provider introducing a 3GB monthly traffic limit.
399 .\"
400 .SH AUTHORS
401 Emil Mikulic and others. (see the AUTHORS and THANKS files)
402 .\"
403 .SH WEBSITE
404 http://dmr.ath.cx/net/darkstat/