manual: explain new netinst cfg

Related: SYS#6192
Change-Id: I1d636b8a6ae7628b4369734a45e60f2eaf437dce

doc/manuals/chapters/netinst.adoc

@@ -0,0 +1,56 @@
+== Local GTP Addresses / Network Instance
+
+PFCP features optional Network Instance IEs, in which the CPF may tell the UPF which local network interface to use for
+a PDR and/or a FAR.
+
+NOTE:: osmo-upf only evaluates the Network Instances configured in PDRs. Since osmo-upf always pairs a PDR+FAR with
+another PDR+FAR in reverse direction, each side's PDR is sufficient.
+
+Network Instance IEs affect both the tunend and the tunmap use cases, as well as which local IP address is returned
+in the PFCP response
+
+1. Look up Network Instance name in the osmo-upf.cfg `netinst` section, to obtain a local IP address.
+2. Depending on use case:
+  - tunend: create the tunnel on a GTP device matching the local IP address, see <<gtp_module>>.
+  - tunmap: use the local IP address in the netfilter ruleset, see <<nftables>>.
+3. Usually, return the chosen local IP address in the F-TEID IE of the Created PDR IE in the PFCP response.
+
+Network Instance configuration consists of {name, IP address} pairs.
+
+NOTE:: As soon as a `netinst` configuration is nonempty, receiving an undefined Network Instance name results in a PFCP
+Reject response, and a log message on cateogry `session`, level `NOTICE`. To make the PFCP return success, add the
+failing name to the `netinst` config.
+
+=== netinst for tunend
+
+The following configuration sets up two GTP devices for tunend, expecting Network Instance names `access1` or `access2`:
+
+----
+tunend
+ dev create apn1 10.0.0.1
+ dev create apn2 10.0.0.2
+netinst
+ add access1 10.0.0.1
+ add access2 10.0.0.2
+----
+
+For example, if a Create PDR IE indicates Network Instance = `access1`, a GTP tunnel is set up in GTP kernel device
+`apn1`. For `access2`, use `apn2`.
+
+=== netinst for tunmap
+
+For the tunmap use case, it is sufficient to configure `netinst` entries, without any addition to the `tunmap` section.
+The following example configures various interfaces for tunmap, to match Network Instance names received in PFCP:
+
+----
+tunmap
+ table-name osmo-upf
+netinst
+ add access1 10.0.0.1
+ add access2 10.0.0.2
+ add core1 9.0.0.1
+ add core2 9.0.0.2
+----
+
+For example, a Create PDR indicating a Network Instance of `core1` will result in an nftables rule that receives packets
+on local address `9.0.0.1`.

doc/manuals/osmoupf-usermanual.adoc

@@ -11,6 +11,8 @@ include::{srcdir}/chapters/overview.adoc[]
 
 include::{srcdir}/chapters/running.adoc[]
 
+include::{srcdir}/chapters/netinst.adoc[]
+
 include::./common/chapters/vty.adoc[]
 
 include::./common/chapters/logging.adoc[]