3. Retrieving statistics

Packet Filter collects a variety of statistics about interfaces, rules, tables, addresses and queues; statistics can be retrieved using the appropriate methods provided by the PacketFilter class, such as PacketFilter.get_status(), PacketFilter.get_tstats() or PacketFilter.get_qstats(). These methods return objects that are basically containers for the internal Packet Filter statistics. These objects will be discussed in the sections below.

3.1 PFStatus objects

For a given interface or interface group (as set with PacketFilter.set_status_if()), Packet Filter collects a wide range of statistics, such as bytes in/out, packets passed/blocked, states, matches and much more.

As seen in the previous chapter, the PacketFilter.get_status() method allows you to retrieve the collected statistics and counters; it takes no arguments and returns a pf.PFStatus object, which is basically a container for the internal Packet Filter statistics.

PFStatus instances have the following attributes:

PFStatus.ifname
The name of the interface or interface group for which PF is gathering statistics.
PFStatus.running
A boolean value indicating whether PF is active or not.
PFStatus.since
The timestamp of when Packet Filter was last started or stopped.
PFStatus.states
The number of current entries in the state table.
PFStatus.src_nodes
The number of current entries in the source tracking table.
PFStatus.debug
The debug level as an integer (see the previous chapter for a list of the debug level constants).
PFStatus.hostid
The host ID, used by pfsync(4) to identify the host that created a state table entry.
PFStatus.reass
A bitmask containing the reassembly flags (as set with PacketFilter.set_reassembly()).
PFStatus.pf_chksum
The MD5 checksum.
PFStatus.cnt
A dictionary containing generic counters, such as match, bad-offset, state-mismatch, etc.
PFStatus.lcnt
A dictionary containing limit counters, i.e. how many times user-defined limits on stateful tracking (such as max-src-nodes, max-src-states, etc.) have been reached.
PFStatus.fcnt
A dictionary containing state table counters, i.e. the number of searches, inserts and removals from the state table.
PFStatus.scnt
A dictionary containing source tracking table counters, i.e. the number of searches, inserts and removals from the source tracking table.
PFStatus.bytes
A dictionary containing byte counters, i.e. the number of bytes in/out: they are divided in in and out, and values are stored as two-item tuples, for IPv4 and IPv6 traffic; a brief example will make this clear:

status = filter.get_status()

print """Bytes in
  IPv4: {0[0]}
  IPv6: {0[1]}""".format(status.bytes["in"])

print """Bytes out
  IPv4: {0[0]}
  IPv6: {0[1]}""".format(status.bytes["out"])
PFStatus.packets
Packet counters, i.e. the number of packets in/out and passed/blocked. Packet counters have a structure similar to byte counters, but values are further divided in passed and blocked; once again, a brief example will best illustrate the point:
status = filter.get_status()

print """Packets in
  Passed
    IPv4: {0[0]}
    IPv6: {0[1]}
  Blocked
    IPv4: {1[0]}
    IPv6: {1[1]}""".format(status.packets["in"][pf.PF_PASS],
                           status.packets["in"][pf.PF_DROP])
print """Packets out
  Passed
    IPv4: {0[0]}
    IPv6: {0[1]}
  Blocked
    IPv4: {1[0]}
    IPv6: {1[1]}""".format(status.packets["out"][pf.PF_PASS],
                           status.packets["out"][pf.PF_DROP])

Printing a PFStatus object will produce an output similar to that of the "pfctl -s info -v" command.

3.2 PFTStats objects

A PFTStats object contains statistics information for a specific address table; it is returned by the PacketFilter.get_tstats() method and has the following attributes:

PFTStats.table
A PFTable object representing the table to which statistics apply.
PFTStats.packets
A dictionary containing packet counters, divided in "in" and "out", for incoming and outgoing packets respectively; values are 3-tuples (Block, Pass, XPass).
PFTStats.bytes
A dictionary containing byte counters, divided in "in" and "out", for incoming and outgoing packets respectively; values are 3-tuples (Block, Pass, XPass).
PFTStats.cleared
The timestamp of when statistics were last cleared for this table.
PFTStats.cnt
The number of addresses in the tables.
PFTStats.evalcnt
A dictionary containing the evaluation counters, divided in "match" and "nomatch".
PFTStats.refcnt
A dictionary containing the reference counters, divided in "rules" and "anchors".

Printing a PFTStats object will produce an output similar to that of the "pfctl -s Tables -vv" command.

3.3 PFIface objects

A PFIface object contains statistics and configuration information for a specific network interface; it is returned by the PacketFilter.get_ifaces() method and has the following attributes:

PFIface.name
The name of the interface.
PFIface.flags
An integer representing the flags set on this interface with PacketFilter.set_ifflags() (the only valid flag is PFI_IFLAG_SKIP).
PFIface.rules
An integer representing the number of rules referencing this interface.
PFIface.states
An integer representing the number of states referencing this interface.
PFIface.packets
Packet counters, i.e. a dictionary containing the number of IPv4/IPv6 packets in/out and passed/blocked; the structure of the dictionary is identical to PFStatus.packets.
PFIface.bytes
Byte counters, i.e. a dictionary containing the number of IPv4/IPv6 bytes in/out and passed/blocked; the structure of the dictionary is identical to PFStatus.packets.

Printing a PFIface object will produce an output similar to that of the "pfctl -s Interfaces -vv" command.

3.4 CBQStats, PriQStats and HFSCStats objects

CBQStats, PriQStats and HFSCStats objects contain statistics information for CBQ, PriQ and HFSC queues respectively; they are returned by the PacketFilter.get_qstats() method and have the following attributes:

CBQStats.packets
PriQStats.packets
HFSCStats.packets
Packet counter, i.e. a two-item tuple containing the number of packets transmitted and dropped.
CBQStats.bytes
PriQStats.bytes
HFSCStats.bytes
Byte counter, i.e. a two-item tuple containing the number of bytes transmitted and dropped.
CBQStats.length
PriQStats.bytes
HFSCStats.bytes
The current number of packets held in the queue.
CBQStats.limit
PriQStats.bytes
HFSCStats.bytes
The maximum number of packets held in the queue.
CBQStats.borrows
Number of times the queue tried to borrow (CBQStats only).
CBQStats.delays
Number of times the queue invoked delay actions (CBQStats only).

Printing CBQStats, PriQStats and HFSCStats objects will produce an output similar to that of the "pfctl -s queue -v" command.