fixeria has uploaded this change for review.
doc/manuals: document GTP-U KPI monitoring
Change-Id: I2709cd545bfd6c8f6e34358caf9d372c02dd5c3e
Related: OS#6671
---
M doc/manuals/chapters/configuration.adoc
A doc/manuals/chapters/gtpu_kpi.adoc
M doc/manuals/osmo-s1gw-usermanual.adoc
3 files changed, 113 insertions(+), 2 deletions(-)
git pull ssh://gerrit.osmocom.org:29418/erlang/osmo-s1gw refs/changes/66/42366/1
diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc
index 8bd7eea..dc738a4 100644
--- a/doc/manuals/chapters/configuration.adoc
+++ b/doc/manuals/chapters/configuration.adoc
@@ -161,8 +161,8 @@
=== GTP-U KPI Reporting (Optional)
OsmoS1GW can optionally poll nftables counters to derive per-eNB GTP-U
-traffic statistics and report them as exometer metrics. This feature
-requires a matching nftables ruleset.
+traffic statistics and report them as exometer metrics (see <<gtpu_kpi>>).
+This feature requires a matching nftables ruleset.
----
%% {gtpu_kpi_enable, true},
diff --git a/doc/manuals/chapters/gtpu_kpi.adoc b/doc/manuals/chapters/gtpu_kpi.adoc
new file mode 100644
index 0000000..ed43cd1
--- /dev/null
+++ b/doc/manuals/chapters/gtpu_kpi.adoc
@@ -0,0 +1,109 @@
+[[gtpu_kpi]]
+== GTP-U KPI Monitoring
+
+OsmoS1GW includes an optional GTP-U KPI monitoring module that tracks
+per-eNB GTP-U traffic volume. Because OsmoS1GW does not carry GTP-U
+traffic itself (see <<architecture>>), it cannot count packets and bytes
+from the data path directly. Instead, it leverages the Linux
+https://netfilter.org/projects/nftables/[nftables] framework: when an
+eNB connects and its GTP-U transport address becomes known, OsmoS1GW
+dynamically installs nftables rules with named counters to measure the
+traffic for that eNB. The counters are polled at a configurable interval
+and the results are exposed as exometer metrics.
+
+This feature is disabled by default. See <<config_gtpu_kpi>> for the
+configuration parameters.
+
+[[gtpu_kpi_requirements]]
+=== Requirements
+
+* Linux kernel 5.2 or later with nftables support.
+* The `CAP_NET_ADMIN` capability is required to manipulate nftables
+ rules. This is already granted by the installed systemd unit (see
+ <<running_systemd>>).
+
+[[gtpu_kpi_how_it_works]]
+=== How It Works
+
+[[gtpu_kpi_nftables_setup]]
+==== nftables Table and Chains
+
+At startup, the GTP-U KPI module creates a dedicated nftables table (an
+`inet` family table named `osmo-s1gw` by default, configurable via
+`gtpu_kpi_table_name`). The table is marked as process-owned, so the
+kernel automatically removes it if OsmoS1GW terminates unexpectedly. If
+a table with the same name already exists from a previous run, it is
+flushed first.
+
+Inside this table the module creates two base chains:
+
+`gtpu-ul` (hook: `prerouting`)::
+ Counts uplink GTP-U traffic — packets whose source address matches a
+ registered eNB's GTP-U address.
+
+`gtpu-dl` (hook: `postrouting`)::
+ Counts downlink GTP-U traffic — packets whose destination address
+ matches a registered eNB's GTP-U address.
+
+Both chains prepend two rules that fast-skip non-GTP-U packets (i.e.
+anything that is not UDP or whose destination port is not 2152).
+
+[[gtpu_kpi_address_learning]]
+==== GTP-U Address Learning
+
+GTP-U transport addresses are not explicitly configured; they are learned
+at run time from the S1AP signalling exchanged during E-RAB establishment.
+The source of the address used for nftables rule matching is controlled by
+the `gtpu_kpi_ul_addr` and `gtpu_kpi_dl_addr` configuration parameters:
+
+`s1ap` (default)::
+ The GTP-U address is taken from the F-TEID IEs carried in S1AP PDUs
+ (E-RAB Setup, Initial Context Setup, etc.).
+
+`sctp`::
+ The GTP-U address is assumed to be the same as the eNB's SCTP source
+ address. Useful when the GTP-U and S1AP addresses are always the same.
+
+[[gtpu_kpi_per_enb_rules]]
+==== Per-eNB Counter Rules
+
+Once an eNB's GTP-U address is known, the module adds:
+
+* A named nftables counter (`ul-{GlobalENBId}` for uplink,
+ `dl-{GlobalENBId}` for downlink).
+* A rule in the appropriate chain that matches packets by source (UL) or
+ destination (DL) IP address and updates the corresponding counter.
+
+When an eNB disconnects, the matching nftables rule is removed, but the
+counter object is intentionally left in place. This means counters
+accumulate across reconnections of the same eNB and do not reset to zero
+if the eNB briefly drops and re-establishes its connection.
+
+[[gtpu_kpi_polling]]
+==== Counter Polling and Metric Reporting
+
+A periodic timer (interval configurable via `gtpu_kpi_interval`, default
+3000 ms) fires and reads all named counters from the nftables table. For
+each registered eNB the difference since the last poll is computed and
+added to the corresponding exometer counters.
+
+Three metrics are maintained per eNB per direction (see also
+<<metrics_per_enb_counters>>):
+
+`enb.{id}.gtpu.packets.{ul|dl}`::
+ Total number of GTP-U packets seen for this eNB.
+
+`enb.{id}.gtpu.bytes.total.{ul|dl}`::
+ Total bytes seen for this eNB, including the outer IP, UDP, and GTP-U
+ headers (i.e. what nftables reports).
+
+`enb.{id}.gtpu.bytes.ue.{ul|dl}`::
+ Estimated UE payload bytes — total bytes minus the fixed overhead of
+ the outer IP header (20 bytes), UDP header (8 bytes), and GTP-U header
+ (8 bytes), i.e. 36 bytes per packet.
+
+NOTE: The UE payload byte estimate assumes a fixed 20-byte IP header.
+ IPv6 or IP options would result in a slight overcount in the
+ overhead subtraction.
+
+// vim:set ts=4 sw=4 et:
diff --git a/doc/manuals/osmo-s1gw-usermanual.adoc b/doc/manuals/osmo-s1gw-usermanual.adoc
index 7c97192..2427d31 100644
--- a/doc/manuals/osmo-s1gw-usermanual.adoc
+++ b/doc/manuals/osmo-s1gw-usermanual.adoc
@@ -17,6 +17,8 @@
include::{srcdir}/chapters/metrics.adoc[]
+include::{srcdir}/chapters/gtpu_kpi.adoc[]
+
include::{commondir}/chapters/glossary.adoc[]
include::{commondir}/chapters/bibliography.adoc[]
To view, visit change 42366. To unsubscribe, or for help writing mail filters, visit settings.