laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/32007 )
Change subject: chapters/logging: Expand documentation on GSMTAP logging ......................................................................
chapters/logging: Expand documentation on GSMTAP logging
Change-Id: I9d7a15fd81bb0f3bc89b97ebfd35e9efc48c94e2 --- M common/chapters/logging.adoc 1 file changed, 28 insertions(+), 3 deletions(-)
git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/07/32007/1
diff --git a/common/chapters/logging.adoc b/common/chapters/logging.adoc index a832ca4..0b31211 100644 --- a/common/chapters/logging.adoc +++ b/common/chapters/logging.adoc @@ -200,9 +200,16 @@
==== Logging via gsmtap
-When debugging complex issues it's handy to be able to reconstruct exact chain of events. This is enabled by using GSMTAP -log output where frames sent/received over the air are intersperced with the log lines. It also simplifies the bug handling -as users don't have to provide separate .pcap and .log files anymore - everything will be inside self-contained packet dump. +GSMTAP is normally a pseudo-header format that enables the IP-transport of GSM (or other telecom) protocols +that are not normally transported over IP. For example, the most common situation is to enable GSMTAP in +OsmoBTS or OsmoPCU to provide GSM-Um air interface capture files over IP, so they can be analyzed in +wireshark. + +GSMTAP logging is now a method how Osmocom software can also encapsulate its own log output in GSMTAP frames. +We're not trying to re-invent rsyslog here, but this is very handy When debugging complex issues. It enables +the reader of the pcap file containing GSMTAP logging together with other protocol traces to reconstruct exact +chain of events. A single pcap file can then contain both the log output of any number of Osmocom programs in +the same timeline of the messages on various interfaces in and out of said Osmocom programs.
It's configured as follows: ---- @@ -230,6 +237,15 @@ OsmoBSC(config-log)# logging level force-all fatal ----
+NOTE: Every time you generate GSMTAP messages and send it to a unicast (non-broadcast/multicast) IP address, +please make sure that the destination IP address actually has a socket open on the specified port, or drops +the packets in its packet filter. If unicast GSMTAP messages arrive at a closed destination UDP port, the +operating system will likely generate ICMP port unreachable messages. Those ICMP messages in turn will, when +arriving at the source (the host on which you run the Osmocom software sending GSMTAP), suppress generation +of further GSMTAP messages for some time, resulting in incomplete files. In case of doubt, either send GSMTAP +to multicast IP addresses, or run something like `nc -l -u -p 4729 > /dev/null` on the destination host to +open the socket at the GSMTAP port and discard anything arriving at it. + ==== Logging to a file
As opposed to Logging to the VTY, logging to files is persistent and