vty: Introduce command 'gsmtap-remote-host' and 'gsmtap-category enable-all'

Related: OS#5306
Change-Id: Ibc6f78c46831b3c90ee3e97300fc13dc441df4c8

2 files changed, 68 insertions, 2 deletions

diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc
index d7789297..ca3963d7 100644
--- a/doc/manuals/chapters/configuration.adoc
+++ b/doc/manuals/chapters/configuration.adoc
@@ -422,3 +422,71 @@ encoded in CS1, so in case any control block is sent from time to time it's
 accomplished and there's no penalty. However, if only EGPRS downlink data is sent
 over that time frame, then the scheduler will force sending a RLCMAC Dummy
 Block.
+
+[[gsmtap]]
+=== Configuring GSMTAP tracing
+
+In addition to being able to obtain pcap protocol traces of the NS/BSSGP
+communication and the text-based logging from the OsmoPCU software, there is
+also the capability of tracing all communication on the radio interface related
+to PS. To do so, OsmoPCU can encapsulate MAC blocks (23-155 byte messages at the
+L2-L1 interface depending on coding scheme) into _GSMTAP_ and send them via
+UDP/IP. At that point, they can be captured with utilities like *tcpdump* or
+*tshark* for further analysis by the *wireshark* protocol analyzer.
+
+In order to activate this feature, you first need to make sure to specify
+the remote address of _GSMTAP_ host in the configuration file.  In most
+cases, using 127.0.0.1 for passing the messages over the loopback (`lo`)
+device will be sufficient:
+
+.Example: Enabling GSMTAP Um-frame logging to localhost
+----
+pcu
+ gsmtap-remote-host 127.0.0.1 <1>
+----
+<1> Destination address for _GSMTAP_ Um-frames
+
+NOTE: Changing this parameter at run-time will not affect the existing
+_GSMTAP_ connection, full program restart is required.
+
+NOTE: Command line parameters `-i` and `--gsmtap-ip` have been deprecated.
+
+OsmoPCU can selectively trace such messages based on different categories, for
+both Ul and Dl. For a complete list of cateogry values, please refer to the
+_OsmoPCU VTY reference manual_ <<vty-ref-osmopcu>>.
+
+For example, to enable GSMTAP tracing for all DL EGPRS rlcmac data blocks, you
+can use the `gsmtap-category dl-data-egprs` command at the `pcu` node of the
+OsmoPCU VTY.
+
+.Example: Enabling  GSMTAP for for all DL EGPRS rlcmac data blocks
+----
+OsmoPCU> enable
+OsmoPCU# configure terminal
+OsmoPCU(config)# pcu
+OsmoPCU(pcu)# gsmtap-category dl-data-egprs
+OsmoPCU(trx)# write <1>
+----
+<1> the `write` command will make the configuration persistent in the
+configuration file.  This is not required if you wish to enable GSMTAP
+only in the current session of OsmoPCU.
+
+De-activation can be performed similarly by using the `no gsmtap-category
+dl-data-egprs` command at the `pcu` node of the OsmoPCU VTY.
+
+It may be useful to enable all categories with a few exceptions, or vice versa
+disable everything using one command.  For this purpose, the VTY provides
+`gsmtap-category enable-all` and `gsmtap-category disable-all` commands.
+
+.Example: Enabling all categoriess except _dl-dummy_
+----
+pcu
+ gsmtap-category enable-all <1>
+ no gsmtap-category dl-dummy <2>
+----
+<1> Enable all available SAPIs
+<2> Exclude DL RLCMAC blocks
+
+From the moment they are enabled via VTY, GSMTAP messages will be
+generated and sent in UDP encapsulation to the IANA-registered UDP port
+for GSMTAP (4729) of the specified remote address.
diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
index 78f79b60..c7639746 100644
--- a/doc/manuals/chapters/running.adoc
+++ b/doc/manuals/chapters/running.adoc
@@ -25,5 +25,3 @@ options:
 	Use the given MCC instead of that provided by BTS via PCU socket
 *-n, --mnc 'MNC'*::
 	Use the given MNC instead of that provided by BTS via PCU socket
-*-i, --gsmtap-ip 'A.B.C.D'*::
-        Send Um interface trace via GSMTAP to specified IP address