xtables: add xtables-monitor

This is a partial revert of commit 7462e4aa757dc28e74b4a731b3ee13079b04ef23
("iptables-compat: Keep xtables-config and xtables-events out from tree")
and re-adds xtables-events under a new name, with a few enhancements,
this is --trace mode, which replaces printk-based tracing, and an
imroved event mode which will now also display pid/name and new generation id
at the end of a batch.

Example output of xtables-monitor --event --trace

PACKET: 10 fa6b77e1 IN=wlan0 MACSRC=51:14:31:51:XX:XX MACDST=1c:b6:b0:ac:XX:XX MACPROTO=86dd SRC=2a00:3a0:2::1 DST=2b00:bf0:c001::1 LEN=1440 TC=18 HOPLIMIT=61 FLOWLBL=1921 SPORT=22 DPORT=13024 ACK PSH
 TRACE: 10 fa6b77e1 raw:PREROUTING:return:
 TRACE: 10 fa6b77e1 raw:PREROUTING:policy:DROP
 EVENT: -6 -t mangle -A PREROUTING -j DNPT --src-pfx dead::/64 --dst-pfx 1c3::/64
NEWGEN: GENID=6581 PID=15601 NAME=xtables-multi

Signed-off-by: Florian Westphal <fw@strlen.de>

1 files changed, 93 insertions, 0 deletions

diff --git a/iptables/xtables-monitor.8.in b/iptables/xtables-monitor.8.in
new file mode 100644
index 00000000..202842b9
--- /dev/null
+++ b/iptables/xtables-monitor.8.in
@@ -0,0 +1,93 @@
+.TH XTABLES\-MONITOR 8 "" "@PACKAGE_STRING@" "@PACKAGE_STRING@"
+.SH NAME
+xtables-monitor \(em show changes to rule set and trace-events
+.SH SYNOPSIS
+\fBxtables\-monitor\fP [\fB\-t\fP] [\fB\-e\fP] [\fB\-4\fP|\fB|\-6\fB]
+.PP
+\
+.SH DESCRIPTION
+.PP
+.B xtables-monitor
+is used to monitor changes to the ruleset or to show rule evaluation events
+for packets tagged using the TRACE target.
+.B xtables-monitor
+will run until the user aborts execution, typically by using CTRL-C.
+.RE
+.SH OPTIONS
+\fB\-e\fP, \fB\-\-event\fP
+.TP
+Watch for updates to the rule set.
+Updates include creation of new tables, chains and rules and
+the name of the program that caused the rule update.
+.TP
+\fB\-t\fP, \fB\-\-trace\fP
+Watch for trace events generated by packets that have been tagged
+using the TRACE target.
+.TP
+\fB\-4\fP
+Restrict output to ipv4.
+.TP
+\fB\-6\fP
+Restrict output to ipv6.
+.SH EXAMPLE OUTPUT
+.TP
+.B xtables-monitor \-\-trace
+
+ 1 TRACE: 2 fc475095 raw:PREROUTING:rule:0x3:CONTINUE \-4 \-t raw \-A PREROUTING \-p icmp \-j TRACE
+ 2 PACKET: 0 fc475095 IN=lo LL=0x304 0000000000000000000000000800 SRC=127.0.0.1 DST=127.0.0.1 LEN=84 TOS=0x0 TTL=64 ID=38349DF
+ 3 TRACE: 2 fc475095 raw:PREROUTING:return:
+ 4 TRACE: 2 fc475095 raw:PREROUTING:policy:ACCEPT
+ 5 TRACE: 2 fc475095 filter:INPUT:return:
+ 6 TRACE: 2 fc475095 filter:INPUT:policy:DROP
+ 7 TRACE: 2 0df9d3d8 raw:PREROUTING:rule:0x3:CONTINUE \-4 \-t raw \-A PREROUTING \-p icmp \-j TRACE
+.PP
+The first line shows a packet entering rule set evaluation.
+The protocol number is shown (AF_INET in this case), then a packet
+identifier number that allows to correlate messages coming from rule set evaluation of
+this packet.  After this, the rule that was matched by the packet is shown.
+This is the TRACE rule that turns on tracing events for this packet.
+
+The second line dumps information about the packet. Incoming interface
+and packet headers such as source and destination addresses are shown.
+
+The third line shows that the packet completed traversal of the raw table
+PREROUTING chain, and is returning, followed by use the chain policy to make accept/drop
+decision (the example shows accept being applied).
+The fifth line shows that the packet leaves the filter INPUT chain, i.e., no rules in the filter tables
+INPUT chain matched the packet.
+It then got DROPPED by the policy of the INPUT table, as hown by line six.
+The last line shows another packet arriving \-\- the packet id is different.
+
+When using the TRACE target, it is usally a good idea to only select packets
+that are relevant, for example via
+.nf
+iptables \-t raw \-A PREROUTING \-p tcp \-\-dport 80 \-\-syn \-m limit \-\-limit 1/s \-j TRACE
+.fi
+.TP
+.B xtables-monitor \-\-event
+  1 EVENT: nft: NEW table: table filter ip flags 0 use 4 handle 444
+  2 EVENT: # nft: ip filter INPUT use 2 type filter hook input prio 0 policy drop packets 0 bytes 0
+  3 EVENT: # nft: ip filter FORWARD use 0 type filter hook forward prio 0 policy accept packets 0 bytes 0
+  4 EVENT: # nft: ip filter OUTPUT use 0 type filter hook output prio 0 policy accept packets 0 bytes 0
+  5 EVENT: \-4 \-t filter \-N TCP
+  6 EVENT: \-4 \-t filter \-A TCP \-s 192.168.0.0/16 \-p tcp \-m tcp \-\-dport 22 \-j ACCEPT
+  7 EVENT: \-4 \-t filter \-A TCP \-p tcp \-m multiport \-\-dports 80,443 \-j ACCEPT
+  8 EVENT: \-4 \-t filter \-A INPUT \-p tcp \-j TCP
+  9 EVENT: \-4 \-t filter \-A INPUT \-m conntrack \-\-ctstate RELATED,ESTABLISHED \-j ACCEPT
+ 10 NEWGEN: GENID=13904 PID=25167 NAME=iptables-nftables-restore
+.PP
+This example shows event monitoring.  Line one shows creation of a table (filter in this case), followed
+by three base hooks INPUT, FORWARD and OUTPUT.  The iptables-nftables tools all create tables and base
+chains automatically when needed, so this is expected when a table was not yet initialized or when it is
+re-created from scratch by iptables-nftables-restore.  Line five shows a new user-defined chain (TCP)
+being added, followed by addition a few rules. the last line shows that a new ruleset generation has
+become active, i.e., the rule set changes are now active.  This also lists the process id and the programs name.
+.SH LIMITATIONS
+.B xtables-monitor
+only works with rules added using iptables-nftables, rules added using
+iptables-legacy cannot be monitored.
+.SH BUGS
+Should be reported or by sending email to netfilter-devel@vger.kernel.org or
+by filing a report on https://bugzilla.netfilter.org/.
+.SH SEE ALSO
+\fBiptables\fP(8), \fBxtables\fP(8), \fBnft\fP(8)