cellular-infrastructure
/
osmo-gsm-manuals
mirror of https://gerrit.osmocom.org/osmo-gsm-manuals
9
0
Fork 0
Code Releases Activity

chapters/logging: Expand documentation on GSMTAP logging 

Change-Id: I9d7a15fd81bb0f3bc89b97ebfd35e9efc48c94e2
This commit is contained in:
Harald Welte 2023-03-21 20:37:45 +01:00
parent 9ff23bca66
commit 063523d11a
1 changed files with 19 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
common/chapters/logging.adoc
View File

@ -200,9 +200,16 @@ the incoming log messages will push out the oldest messages available in the buf
==== 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 stderr
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