1darkstat(8) System Manager's Manual darkstat(8)
2
6 darkstat - network statistics gatherer
7
9 darkstat [ -i interface ] [ -r file ] [ --snaplen bytes ] [ --pppoe ] [
10 --syslog ] [ --verbose ] [ --no-daemon ] [ --no-promisc ] [ --no-dns ]
11 [ --no-macs ] [ --no-lastseen ] [ -p port ] [ -b bindaddr ] [ --base
12 path ] [ -f filter ] [ -l network/netmask ] [ --local-only ] [ --chroot
13 dir ] [ --user username ] [ --daylog filename ] [ --import filename ] [
14 --export filename ] [ --pidfile filename ] [ --hosts-max count ] [
15 --hosts-keep count ] [ --ports-max count ] [ --ports-keep count ] [
16 --highest-port port ] [ --wait secs ] [ --hexdump ]
17
19 darkstat is a packet sniffer that runs as a background process, gathers
20 all sorts of statistics about network usage, and serves them over HTTP.
21 All settings are passed on the commandline.
23
25 -i interface
26 Capture traffic on the specified network interface. This is the
27 only mandatory commandline argument.
28 -r file
30 Instead of capturing live traffic, read it from a pcap(3) cap‐
31 ture file. This is only useful for development and benchmark‐
32 ing. The -r and -i arguments are mutually exclusive.
33 --snaplen bytes
35 How many bytes to capture from the start of each packet. You
36 should not need to specify this; darkstat will calculate it au‐
37 tomatically.
38 --pppoe
40 Don't use this.
41 Instead, capture on the tunnel interface that your PPPoE soft‐
43 ware provides, for example tun0 on FreeBSD, pppoe0 on OpenBSD or
44 NetBSD.
45 If you really must, you can capture on an Ethernet interface and
47 pass this argument to have darkstat decode PPPoE frames and ig‐
48 nore everything else. Make sure you also specify your local ad‐
49 dress with the -l argument!
50 --syslog
52 Errors, warnings, and verbose messages will go to syslog (facil‐
53 ity daemon, priority debug) instead of stderr.
54 On some systems, these messages end up in /var/log/debug by de‐
56 fault.
57 --verbose
59 Produce more verbose debugging messages.
60 --no-daemon
62 Do not detach from the controlling terminal; stay in the fore‐
63 ground.
64 --no-promisc
66 Do not use promiscuous mode to capture. Note that an interface
67 may already be in promiscuous mode, or may later enter promiscu‐
68 ous mode, due to circumstances beyond darkstat's control. If
69 this is a problem, use -f to specify an appropriate bpf(4) fil‐
70 ter.
71 --no-dns
73 Do not resolve IPs to host names. This can significantly reduce
74 memory footprint on small systems as an extra process is created
75 for DNS resolution.
76 --no-macs
78 Do not display MAC addresses in the hosts table.
79 --no-lastseen
81 Do not display the last seen time in the hosts table.
82 -p port
84 Bind the web interface to the specified port. The default is
85 667.
86 -b bindaddr
88 Bind the web interface to the specified address. The default is
89 to listen on all interfaces.
90 --base path
92 Specify the path of the base URL. This can be useful if dark‐
93 stat is accessed via a reverse proxy.
94 For example, if you use Apache's mod_proxy and want to avoid a
96 complicated setup with mod_proxy_html (and mod_header to unset
97 the Accept-Encoding header), just set the base path to something
98 like stats and use a config similar to the following snippet:
99 ProxyPass /stats/ http://localhost:667/stats/
102 ProxyPassReverse /stats/ http://localhost:667/stats/
103 The default is / (i.e. the root).
105 -f filter
107 Use the specified filter expression when capturing traffic. The
108 filter syntax is beyond the scope of this manual page; please
109 refer to the tcpdump(1) documentation.
110 -l network/netmask
112 Define a "local network" according to the network and netmask
113 addresses. All traffic entering or leaving this network will be
114 graphed, as opposed to the default behaviour of only graphing
115 traffic to and from the local host.
116 The rule is that if ip_addr & netmask == network, then that ad‐
118 dress is considered local. See the usage example below.
119 --local-only
121 Make the web interface only display hosts on the "local net‐
122 work." This is intended to be used together with the -l argu‐
123 ment.
124 --chroot dir
126 Force darkstat to chroot() into the specified directory. With‐
127 out this argument, a default directory will be used, which is
128 determined at build time. Usually /var/empty or /var/lib/empty.
129 For security reasons, this directory should be empty, and the
131 user that darkstat is running as should not have write access to
132 it.
133 However, if you wish to use --daylog or --export, darkstat will
135 need write access to the chroot. If you are uncomfortable with
136 the security implications, don't use any functionality that re‐
137 quires write access.
138 --user username
140 Force darkstat to drop privileges to the uid and gid of the
141 specified user. Without this argument, a default value will be
142 used, which is set at build time. Usually nobody.
143 For security reasons, this should not be root.
145 --daylog filename
147 Log daily traffic statistics into the named file, relative to
148 the chroot directory. If you wish to use --daylog, you must
149 first specify a --chroot directory, and it must be writeable by
150 the darkstat user. A writeable chroot has security implica‐
151 tions; if you are uncomfortable with this, do not use the --day‐
152 log functionality.
153 If the daylog argument is not specified, no logging is per‐
155 formed.
156 The daylog format is:
158 localtime|time_t|bytes_in|bytes_out|pkts_in|pkts_outs
160 Lines starting with a # are comments stating when logging
162 started and stopped.
163 --import filename
165 Upon starting, import a darkstat database from the named file,
166 relative to the chroot directory. If you wish to use --import,
167 you must first specify a --chroot directory. If the import is
168 unsuccessful, darkstat will start with an empty database.
169 --export filename
171 On shutdown, or upon receiving SIGUSR1 or SIGUSR2, export the
172 in-memory database to the named file, relative to the chroot di‐
173 rectory. If you wish to use --export, you must first specify a
174 --chroot directory, and it must be writeable by the darkstat
175 user. A writeable chroot has security implications - if you are
176 uncomfortable with this, do not use the --export functionality.
177 --pidfile filename
179 Creates a file containing the process ID of darkstat. This file
180 will be unlinked upon clean shutdown. As with all pidfiles, if
181 darkstat dies uncleanly, a stale pidfile can be left over.
182 For example, start darkstat with:
184 darkstat -i fxp0 --chroot /var/run/darkstat --pidfile
186 darkstat.pid
187 And stop with:
189 kill `cat /var/run/darkstat/darkstat.pid`
191 By default, kill(1) will send SIGTERM, which will cause darkstat
193 to shut down cleanly.
194 --hosts-max count
196 The maximum number of hosts that will be kept in the hosts ta‐
197 ble. This is used to limit how much accounting data will be
198 kept in memory. The number of --hosts-max must be greater than
199 --hosts-keep
200 --hosts-keep count
202 When the hosts table hits --hosts-max and traffic is seen from a
203 new host, we clean out the hosts table, keeping only the top
204 --hosts-keep number of hosts, sorted by total traffic.
205 --ports-max count
207 The maximum number of ports that will be tracked for each host.
208 This is used to limit how much accounting data will be kept in
209 memory. The number of --ports-max must be greater than
210 --ports-keep
211 --ports-keep count
213 When a ports table fills up, this many ports are kept and the
214 rest are discarded.
215 --highest-port port
217 Ports that are numerically higher than this will not appear in
218 the per-host ports tables, although their traffic will still be
219 accounted for. This can be used to hide ephemeral ports. By
220 default, all ports are tracked.
221 --wait secs
223 Don't use this. It's a hack to help victims of NetworkManager
224 and similar systems.
225 You should start darkstat after the capture interface has come
227 up. If you can't, specifying the --wait option will make dark‐
228 stat sleep up to the specified number of seconds for the inter‐
229 face to become ready. Zero means wait indefinitely.
230 --hexdump
232 Show hex dumps of received traffic. This is only for debugging,
233 and implies --verbose and --no-daemon.
234
236 To gather statistics on the fxp0 interface:
237 darkstat -i fxp0
239 We want to account for traffic on the Internet-facing interface, but
241 only serve web pages to our private local network where we have the IP
242 address 192.168.0.1:
243 darkstat -i fxp0 -b 192.168.0.1
245 We want to serve web pages on the standard HTTP port:
247 darkstat -i fxp0 -p 80
249 We are on Optus (cable) and don't want to account for the constant ARP
251 traffic we are receiving:
252 darkstat -i fxp0 -f "not arp"
254 We only want to account for SSH traffic:
256 darkstat -i fxp0 -f "port 22"
258 We don't want to account for traffic between internal IPs:
260 darkstat -i fxp0 -f "not (src net 192.168.0 and dst net
262 192.168.0)"
263 (For a full reference on filter syntax, refer to the tcpdump(1) man‐
265 page)
266 We have a network consisting of a gateway server (192.168.1.1) and a
268 few workstations (192.168.1.2, 192.168.1.3, etc.) and we want to graph
269 all traffic entering and leaving the local network, not just the gate‐
270 way server (which is running darkstat):
271 darkstat -i fxp0 -l 192.168.1.0/255.255.255.0
273 On some systems, we can't capture on a "decoded" interface but only on
275 nas0 which returns PPPoE encapsulated packets. Do PPPoE decoding, and
276 override the local IP manually since it cannot be automatically de‐
277 tected. Note the /32 netmask:
278 darkstat -i nas0 --pppoe -l 192.168.1.1/255.255.255.255
280
282 To shut darkstat down cleanly, send a SIGTERM or SIGINT signal to the
283 darkstat parent process.
284 Sending the SIGUSR1 signal will cause darkstat to empty out its in-mem‐
286 ory database. If an --export file was set, it will first save the
287 database to file. Sending SIGUSR2 will save the database without emp‐
288 tying it.
289
291 How many bytes does each bar on the graph represent?
292 Hover your mouse cursor over a bar and you should get a tooltip saying
293 exactly how many bytes in and out the bar represents.
294 Why aren't there labels / tics / a scale on the graphs?
296 Because implementing them is hard. And doing so correctly, and in a
297 way that works across all browsers, looks pretty much impossible.
298 I might attempt it some day. In the meantime, patches would be gladly
300 accepted.
301 Why are the graphs blank? All the bars are zero.
303 The graphs only show traffic in/out of the local host, which is deter‐
304 mined by getting the IP address of the interface you're sniffing on.
305 You can use the -l argument to override the local address for account‐
307 ing purposes. You can also use it to do accounting for a whole subnet
308 by specifying an appropriate netmask.
309
311 tcpdump(1)
312
314 darkstat was written in 2001, largely as a result of a certain Aus‐
315 tralian cable Internet provider introducing a 3GB monthly traffic
316 limit.
317
319 Emil Mikulic and others. (see the AUTHORS file)
320
322 https://unix4lyfe.org/darkstat/
323darkstat 3.0.721 June 2011 darkstat(8)