[[netinst]]
== 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`.