Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PFSTAT(8)		  BSD System Manager's Manual		     PFSTAT(8)

     pfstat -- collect packet filter statistics	and generate graphs

     pfstat [-c	config]	[-d database] [-f file]	[-r host[:port]] [-q] [-p]
	    [-t	-days[:days]]

     The pfstat	utility	can query statistics from the packet filter device
     pf(4) and produce graphs from the collected data.

     The options are as	follows:

     -q		  Query	the current set	of statistics from the packet filter
		  and store it in the database.	 This is usually done from a
		  crontab(5) like this:

		  * * *	* * /usr/local/bin/pfstat -q

		  Note that without regular truncating (see below), the	data-
		  base will grow continually.

     -r	host[:port]
		  Query	the statistics from a remote host running pfstatd(8).
		  Default is to	query the local	packet filter through the de-
		  vice special file /dev/pf, not requiring any running

     -p		  Produce the configured set of	graph images based on the sta-
		  tistics collected beforehand.

     -t	days:[days]
		  Truncate the database, removing entries older	than the spec-
		  ified	number of days.	 The first value applies to uncom-
		  pressed entries which	constitute roughly 90 percent of the
		  database, the	second value to	compressed entries.  Uncom-
		  pressed entries are needed only for high-resolution graphs
		  over short time periods.

		  Assuming statistics are queried every	I seconds, and a graph
		  of width W pixels covering a time period of T	seconds	is
		  generated, then uncompressed entries are only	used when T/I
		  < W*10.

		  In other words, removing uncompressed	entries	earlier	than
		  compressed ones drastically reduces the database size.
		  Graphs can be	generated over the entire time range the com-
		  pressed entries cover	(monthly or yearly graphs), and	high
		  resolution graphs over short time periods in the recent past
		  don't	lose any precision.  The precision is gradually	lost
		  for older periods.

		  A typical invokation would be

		  pfstat -t 31:365

		  This removes uncompressed entries older than a month and
		  compressed entries older than	a year,	allowing generation of
		  graphs up to one year	into the past, while keeping full pre-
		  cision for one month.

		  Note that truncating the database does not usually shrink
		  the size of the database file.  Removed entries are only
		  marked as deleted and	their space is later reused for	new

     -f	file	  Copy the database into a new file, skipping removed and in-
		  valid	entries.  This operation takes longer than truncating,
		  but produces a smaller database file.	 This can also be used
		  to recover data from a corrupted database, indicated by the
		  following error during truncating:

		  data_truncate: db->del() returned 1
		  main:	data_truncate()	failed

     -c	config	  Use the specified configuration file instead of the default
		  /usr/local/etc/pfstat.conf.  Syntax:

		  collect = "collect" number = coldef .
		  coldef  = ( global | iface | queue ) [ "diff"	] .
		  global  = "global" ( states |	counter	) .
		  states  = "states" ( "entries" | "inserts" | "removals" |
				       "searches" ) .
		  counter = "counter" (	"match"	| "bad-offset" | ... ) .
		  iface	  = "interface"	name ( "pass" |	"block"	)
					( "bytes" | "packets" )	( "in" | "out" )
					( "ipv4" | "ipv6" ) .
		  queue	  = "queue" name ( "pass" | "drop" | "other" )
				( "packets" | "bytes" |	number )
		  image	  = "image" filename "{"
				time type size [ left ]	[ right	] "}" .
		  time	  = "from" number [ unit ] [ "to" number [ unit	] ] .
		  unit	  = "minutes" |	"hours"	| "days" | "weeks" | "months" |
					"years"	.
		  type	  = "type" ( "jpeg" | "png" ) .
		  size	  = "width" number "height" number .
		  left	  = "left" graphs .
		  right	  = "right" graphs .
		  graphs  = graph [ ","	graphs ] .
		  graph	  = "graph" number [ "bps" ] [ "avg" | "min" | "max" ]
				    label unit "color" red green blue [	"filled" ] .

		  collect lines	define what values to store in the database.
		  Each definition should use a unique number, which is used in
		  graph	lines to reference those values.

		  The diff option causes differential values (change of	value
		  per second) to be stored instead of absolute values.	For
		  example, storing interface byte counters (which count	the
		  number of bytes since	last reset) differentially produces
		  values representing current speed (bytes per second).

		  Several images can be	defined	in the same config file.  An
		  image	can include two	independent y-axes, both of which
		  auto-scale independently to the maximum value	in the se-
		  lected range.	 Each axis can display an arbitrary number of

		  When the bps option is used, values are multiplied by	eight,
		  and the unit prefixes	'k' (kilo), 'm'	(mega),	etc. are mul-
		  tiples of 1024, instead of 1000.

     -d	database  Database file.  Default is /var/db/pfstat.db.

     collect 1 = interface "sis0" pass bytes in	ipv4 diff
     collect 2 = interface "sis0" pass bytes out ipv4 diff
     image "/var/www/htdocs/bandwidth.jpg" {
	     from 7 days to now
	     width 1000	height 400
		     graph 1 bps "in" "bits/s" color 0 192 0 filled
		     graph 2 bps "out" "bits/s"	color 0	0 255
     collect 3 = global	states entries
     image "/var/www/htdocs/states.jpg"	{
	     from 12 months to now
	     width 800 height 200
		     graph 3 "states" "entries"	color 200 0 0

     pf(4), crontab(5),	pfctl(8), pfstatd(8)

BSD				 June 26, 2002				   BSD


Want to link to this manual page? Use this URL:

home | help