From 52046cb77f11204fcf29280154a44b9da3e56182 Mon Sep 17 00:00:00 2001
From: Roger Luethi <roger.luethi@bisdn.de>
Date: Wed, 8 May 2024 09:37:27 +0200
Subject: [PATCH] Add man page for switch_tcpdump(8)

Add a man page for switch_tcpdump which provides information that does
not easily fit into the usage message.

Mention the man page in the program help text to help users find it.

Signed-off-by: Roger Luethi <roger.luethi@bisdn.de>
---
 .../man-pages/files/switch_tcpdump.8          | 116 ++++++++++++++++++
 .../man-pages/man-pages_%.bbappend            |   1 +
 .../ofdpa-tools/ofdpa-tools/switch_tcpdump    |   2 +
 3 files changed, 119 insertions(+)
 create mode 100644 recipes-extended/man-pages/files/switch_tcpdump.8

diff --git a/recipes-extended/man-pages/files/switch_tcpdump.8 b/recipes-extended/man-pages/files/switch_tcpdump.8
new file mode 100644
index 00000000..dfa147d1
--- /dev/null
+++ b/recipes-extended/man-pages/files/switch_tcpdump.8
@@ -0,0 +1,116 @@
+.\" switch_tcpdump.8
+.TH "SWITCH_TCPDUMP" "8" "8 May 2024" "" "documentation"
+.SH "NAME"
+switch_tcpdump \- dump switch port traffic
+.SH "SYNOPSIS"
+.B switch_tcpdump
+.B \-\-inPort
+.I INPORT
+.br
+[
+.B \-\-filePath
+.I FILEPATH
+[
+.B \-\-maxSize
+.I \%MAXSIZE_MB
+]
+]
+.br
+[
+.B \-\-timeout
+.I TIMEOUT_SECONDS
+]
+[
+.I TCPDUMP_OPTIONS
+]
+
+.SH "DESCRIPTION"
+\fIswitch_tcpdump\fP is a wrapper around
+.BR tcpdump (8).
+
+Its main features are:
+
+.IP
+Inserting a rule into the ACL table to redirect ingress traffic for
+the given port to the CPU (i.e., the Linux kernel).
+.IP
+Deleting the rule from the ACL table when the capture is stopped.
+.IP
+Preventing file system overflow by stopping the capture when the
+capture file reaches a certain size (default 100 MB).
+.IP
+Stopping the capture after a certain amount of time (default 0, meaning
+no timeout).
+.PP
+
+\fIswitch_tcpdump\fP captures all packets arriving on the given port
+and all packets seen by the kernel going through that port (i.e.,
+any packets that you are sending out from the switch through that
+port). It cannot see any packets that are treated exclusively in the
+switch ASIC; this includes packets that are eventually sent out through
+the capture port without being seen by the kernel (e.g., packets that
+are bridged in hardware).
+
+.SH "OPTIONS"
+.TP
+.BI \-\-inPort " INPORT"
+Listen on specified port (named portX). This is a mandatory option.
+.TP
+.BI \-\-filePath " FILEPATH"
+Write the captured packets to the specified file. If not specified,
+packet descriptions are printed to stdout (mirroring tcpdump behavior).
+The maximum file size is limited by the \fB\%\-\-maxSize\fR option.
+.TP
+.BI \-\-maxSize " MAXSIZE_MB"
+MAXSIZE_MB is the maximum size of the capture file in megabytes. The
+mechanism checks the file size every 0.1 seconds. The default value is
+100. Setting MAXSIZE_MB to 0 disables the size limit.
+.TP
+.BI \-\-timeout " TIMEOUT_SECONDS"
+Stop the capture after TIMEOUT_SECONDS seconds.
+.TP
+.I "TCPDUMP_OPTIONS"
+All remaining arguments are passed on to tcpdump.
+
+.SH "EXAMPLES"
+.LP
+To capture seen packets on port3 and write /tmp/pcap (defaults to 100 MB
+limit):
+.RS
+.nf
+\fBswitch_tcpdump --inPort port3 --filePath /tmp/pcap\fP
+.fi
+.RE
+.LP
+To write a capture file with no size limit:
+.RS
+.nf
+\fBswitch_tcpdump --inPort port3 --filePath /tmp/pcap --maxSize 0\fP
+.fi
+.RE
+.LP
+To show for ten seconds all packets seen on port3:
+.RS
+.nf
+\fBswitch_tcpdump --inPort port3 --timeout 10\fP
+.fi
+.RE
+.LP
+Extra arguments (all arguments after "port3" in this case) are passed on to
+tcpdump:
+.RS
+.nf
+\fBswitch_tcpdump --inPort port3 -nv arp or icmp\fP
+.fi
+.RE
+
+.SH "EXIT STATUS"
+\fIswitch_tcpdump\fP returns 2 for all errrors except for \fItcpdump\fP
+errors whose exit status (usually 1 in case of errors) is passed through.
+
+.SH "BUGS"
+Fails to remove the ACL rule if terminated by SIGKILL.
+
+Using \fItcpdump\fP options such as \fB\-i\fR or \fB\-w\fR that
+conflict with \fI\%switch_tcpdump\fP options (e.g., \fB\-\-inPort\fR,
+\fB\-\-filePath\fR) is unsupported and may result in unexpected behavior.
diff --git a/recipes-extended/man-pages/man-pages_%.bbappend b/recipes-extended/man-pages/man-pages_%.bbappend
index 8ce6778c..df29e187 100644
--- a/recipes-extended/man-pages/man-pages_%.bbappend
+++ b/recipes-extended/man-pages/man-pages_%.bbappend
@@ -5,6 +5,7 @@ SRC_URI += " \
   file://onie-bisdn-uninstall.1 \
   file://onie-bisdn-upgrade.1 \
   file://onie-bisdn-rescue.1 \
+  file://switch_tcpdump.8 \
 "
 
 do_install:append() {
diff --git a/recipes-extended/ofdpa-tools/ofdpa-tools/switch_tcpdump b/recipes-extended/ofdpa-tools/ofdpa-tools/switch_tcpdump
index 0ef9a280..a12576a8 100755
--- a/recipes-extended/ofdpa-tools/ofdpa-tools/switch_tcpdump
+++ b/recipes-extended/ofdpa-tools/ofdpa-tools/switch_tcpdump
@@ -50,6 +50,8 @@ switch_tcpdump --inPort port3 --timeout 10
 Extra arguments (all arguments after "port3" in this case) are passed on to
 tcpdump:
 switch_tcpdump --inPort port3 -nv arp or icmp
+
+For additional information, see the man page for switch_tcpdump(8).
 """