1darkstat(8)                 System Manager's Manual                darkstat(8)
2
3
4

NAME

6       darkstat - network statistics gatherer
7

SYNOPSIS

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

DESCRIPTION

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
22       All settings are passed on the commandline.
23

OPTIONS

25       -i interface
26              Capture traffic on the specified network interface.  This is the
27              only mandatory commandline argument.
28
29       -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
34       --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
39       --pppoe
40              Don't use this.
41
42              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
46              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
51       --syslog
52              Errors, warnings, and verbose messages will go to syslog (facil‐
53              ity daemon, priority debug) instead of stderr.
54
55              On some systems, these messages end up in /var/log/debug by  de‐
56              fault.
57
58       --verbose
59              Produce more verbose debugging messages.
60
61       --no-daemon
62              Do  not  detach from the controlling terminal; stay in the fore‐
63              ground.
64
65       --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
72       --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
77       --no-macs
78              Do not display MAC addresses in the hosts table.
79
80       --no-lastseen
81              Do not display the last seen time in the hosts table.
82
83       -p port
84              Bind the web interface to the specified port.   The  default  is
85              667.
86
87       -b bindaddr
88              Bind the web interface to the specified address.  The default is
89              to listen on all interfaces.
90
91       --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
95              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
100
101                      ProxyPass /stats/ http://localhost:667/stats/
102                      ProxyPassReverse /stats/ http://localhost:667/stats/
103
104              The default is / (i.e. the root).
105
106       -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
111       -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
117              The  rule is that if ip_addr & netmask == network, then that ad‐
118              dress is considered local.  See the usage example below.
119
120       --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
125       --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
130              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
134              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
139       --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
144              For security reasons, this should not be root.
145
146       --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
154              If the daylog argument is not  specified,  no  logging  is  per‐
155              formed.
156
157              The daylog format is:
158
159              localtime|time_t|bytes_in|bytes_out|pkts_in|pkts_outs
160
161              Lines  starting  with  a  #  are  comments  stating when logging
162              started and stopped.
163
164       --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
170       --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
178       --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
183              For example, start darkstat with:
184
185                     darkstat -i  fxp0  --chroot  /var/run/darkstat  --pidfile
186                     darkstat.pid
187
188              And stop with:
189
190                     kill `cat /var/run/darkstat/darkstat.pid`
191
192              By default, kill(1) will send SIGTERM, which will cause darkstat
193              to shut down cleanly.
194
195       --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
201       --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
206       --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
212       --ports-keep count
213              When a ports table fills up, this many ports are  kept  and  the
214              rest are discarded.
215
216       --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
222       --wait secs
223              Don't use this.  It's a hack to help victims  of  NetworkManager
224              and similar systems.
225
226              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
231       --hexdump
232              Show hex dumps of received traffic.  This is only for debugging,
233              and implies --verbose and --no-daemon.
234

USAGE EXAMPLES

236       To gather statistics on the fxp0 interface:
237
238              darkstat -i fxp0
239
240       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
244              darkstat -i fxp0 -b 192.168.0.1
245
246       We want to serve web pages on the standard HTTP port:
247
248              darkstat -i fxp0 -p 80
249
250       We  are on Optus (cable) and don't want to account for the constant ARP
251       traffic we are receiving:
252
253              darkstat -i fxp0 -f "not arp"
254
255       We only want to account for SSH traffic:
256
257              darkstat -i fxp0 -f "port 22"
258
259       We don't want to account for traffic between internal IPs:
260
261              darkstat -i  fxp0  -f  "not  (src  net  192.168.0  and  dst  net
262              192.168.0)"
263
264       (For  a  full  reference on filter syntax, refer to the tcpdump(1) man‐
265       page)
266
267       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
272              darkstat -i fxp0 -l 192.168.1.0/255.255.255.0
273
274       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
279              darkstat -i nas0 --pppoe -l 192.168.1.1/255.255.255.255
280

SIGNALS

282       To shut darkstat down cleanly, send a SIGTERM or SIGINT signal  to  the
283       darkstat parent process.
284
285       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

FREQUENTLY ASKED QUESTIONS

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
295   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
299       I might attempt it some day.  In the meantime, patches would be  gladly
300       accepted.
301
302   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
306       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

SEE ALSO

311       tcpdump(1)
312

HISTORY

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

AUTHORS

319       Emil Mikulic and others. (see the AUTHORS file)
320

WEBSITE

322       https://unix4lyfe.org/darkstat/
323
324
325
326darkstat 3.0.721                   June 2011                       darkstat(8)
Impressum