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() or PacketFilter.get_tstats(). 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 = pf.get_status()

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

print """Bytes out
  IPv4: {0[0]:d}
  IPv6: {0[1]:d}""".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 = pf.get_status()

print """Packets in
  Passed
    IPv4: {0[0]:d}
    IPv6: {0[1]:d}
  Blocked
    IPv4: {1[0]:d}
    IPv6: {1[1]:d}""".format(status.packets["in"][PF_PASS],
                             status.packets["in"][PF_DROP])
print """Packets out
  Passed
    IPv4: {0[0]:d}
    IPv6: {0[1]:d}
  Blocked
    IPv4: {1[0]:d}
    IPv6: {1[1]:d}""".format(status.packets["out"][PF_PASS],
                             status.packets["out"][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: