py-pf - Managing OpenBSD's Packet Filter with Python
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_queues(). 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 number of seconds after machine uptime that 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 (except for the "Adaptive Syncookies Watermarks" part).
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 PFQueueStats objects
PFQueueStats objects contain statistics information for queues; they can be retrieved by calling the PacketFilter.get_queues() method, which returns a tuple of PFQueue objects, whose stats attributes are PFQueueStats instances; they have the following attributes:
- PFQueueStats.packets
- Packet counter, i.e. a two-item tuple containing the number of packets transmitted and dropped.
- PFQueueStats.bytes
- Byte counter, i.e. a two-item tuple containing the number of bytes transmitted and dropped.
- PFQueueStats.qlength
- The current number of packets held in the queue.
- PFQueueStats.qlimit
- The maximum number of packets held in the queue.
Printing PFQueue and the relative PFQueueStats objects will produce an output similar to that of the "pfctl -s queue -v" command.
py-pf - Managing OpenBSD's Packet Filter with Python