vty: Introduce command 'gsmtap-remote-host' and 'gsmtap-category enable-all'
Related: OS#5306
Change-Id: Ibc6f78c46831b3c90ee3e97300fc13dc441df4c8
diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc
index d778929..ca3963d 100644
--- a/doc/manuals/chapters/configuration.adoc
+++ b/doc/manuals/chapters/configuration.adoc
@@ -422,3 +422,71 @@
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.