← Overview

OmniSMF Operations Guide

OmniSMF is the Session Management Function (SMF) of the 5G Core. It owns the full lifecycle of PDU sessions: address allocation, policy association, user-plane programming and teardown. This guide covers the 3GPP role, the SBI and N4 interfaces it exposes, and the key procedures it drives, each with a sequence diagram.

3GPP Role and Specification References

Specification	Relevance
TS 23.501	System architecture: SMF role, PDU session concept, QoS model
TS 23.502	Procedures: PDU Session Establishment (§4.3.2), Modification (§4.3.3), Release (§4.3.4), Service Request (§4.2.3)
TS 29.502	Nsmf_PDUSession service API
TS 29.244	N4 interface: PFCP protocol between SMF and UPF
TS 29.503	Nudm_SubscriberDataManagement (sm-data) and Nudm_UEContextManagement (smf-registrations)
TS 29.512	Npcf_SMPolicyControl: SM policy association and notification toward PCF
TS 29.518	Namf_Communication: N1N2MessageTransfer toward AMF
TS 32.290 / TS 32.291	Nchf_ConvergedCharging (N40): converged charging toward the CHF
TS 24.501	5GS NAS (5GSM): PDU session establishment/modification, session type and 5GSM cause handling (§6.4.1.3)
TS 29.571	Common data types: IpAddress, S-NSSAI

Interfaces

Interface	Peer	Protocol	Purpose
N11	AMF	Nsmf_PDUSession (SBI, HTTP/2)	SM context create / retrieve / update / release, N1N2MessageTransfer
N7	PCF	Npcf_SMPolicyControl (SBI)	SM policy association create/delete + policy-notify callback
N10	UDM	Nudm_SDM + Nudm_UECM (SBI)	Session subscription data, SMF registration
N4	UPF	PFCP (UDP)	PFCP association + session establishment/modification/deletion
N40	CHF	Nchf_ConvergedCharging (SBI)	Converged charging: open/update/close a Charging Data Request over the PDU session lifecycle (CHF resolved via NRF discovery with a static fallback URI; disabled by default)
N26	PGW-C	Internal interworking	Adopt / switch / lookup for 4G/5G mobility
n/a	NRF	Nnrf_NFManagement (SBI)	NF registration + heartbeat (no outbound discovery)

SBI Endpoints

All SBI endpoints are served under the base URL {SBI_SCHEME}://{SBI_ADDR}:{SBI_PORT}.

Method	Path	Service	Purpose	Spec
POST	/nsmf-pdusession/v1/sm-contexts	Nsmf_PDUSession	Create SM Context (PDU session establishment)	TS 29.502
POST	/nsmf-pdusession/v1/sm-contexts/{smContextRef}/retrieve	Nsmf_PDUSession	Retrieve SM Context (spec uses POST, not GET)	TS 29.502 §5.2.2.6
POST	/nsmf-pdusession/v1/sm-contexts/{smContextRef}/modify	Nsmf_PDUSession	Update SM Context (N2 info, UP state change, handover, QoS-flow modify, release flag)	TS 29.502
POST	/nsmf-pdusession/v1/sm-contexts/{smContextRef}/release	Nsmf_PDUSession	Release SM Context (session teardown)	TS 29.502
POST	/nsmf-callback/sm-policy-notify/{smContextRef}	Npcf callback	Receive SmPolicyDecision updates from the PCF (dedicated QoS flows)	TS 29.512 §4.2.4.3

Create SM Context

Mandatory request fields: supi, sNssai, servingNetwork, dnn, smContextStatusUri, pduSessionId, anType, servingNfId. Returns 201 Created with Location: {base}/nsmf-pdusession/v1/sm-contexts/{ref}. Error mapping: 400 MANDATORY_IE_MISSING, 404 DNN_DENIED, 500 SYSTEM_FAILURE, 503 NF_DISCOVERY_FAILURE (UDM unreachable).

Retrieve SM Context

The AMF reads the current SM context by referencing it (TS 29.502 §5.2.2.6 uses POST .../sm-contexts/{smContextRef}/retrieve, not GET). The SMF returns 200 OK with the current SM context view for a known reference, or 404 CONTEXT_NOT_FOUND for an unknown one.

Update SM Context

The modify handler dispatches on the first recognized key in the body:

Body key	Scenario
n2SmInfo + n2SmInfoType	N2 SM information from gNB (PDU_RES_SETUP_RSP activates the tunnel; PDU_RES_REL_RSP deactivates it)
upCnxState: "DEACTIVATED"	AN release / UE idle entry (downlink FAR to BUFFER)
upCnxState: "ACTIVATING"	Service request; response carries N2 PDU_RES_SETUP_REQ
hoState	Handover state transition: PREPARING, PREPARED, COMPLETED (re-activates the tunnel), CANCELLED
qosFlows	Post-establishment QoS-flow add/modify (returns 204 No Content; changes conveyed to the gNB via N2 SM info)
release: true	AMF-initiated release (returns 204 No Content)
servingNfId	AMF instance change during mobility (returns 204 No Content)

Release SM Context

The body may include ueLocation for final location recording. Returns 204 No Content.

Key Procedures

PDU Session Establishment (TS 23.502 §4.3.2)

The N1N2MessageTransfer is sent asynchronously so the 201 Created returns to the AMF first. The N1 SM message is a NAS PDU Session Establishment Accept and the N2 SM info is an NGAP PDUSessionResourceSetupRequestTransfer, carried as a multipart/related body (TS 29.518) with the binary NAS/NGAP parts referenced by contentId.

DNN Configuration Sourcing

A DNN's behaviour is defined in two places, and an operator must set both consistently for a DNN to come up correctly:

DNN attribute	Sourced from	How it is provisioned	Notes
Allowed S-NSSAI	AMF/UDM subscription	The AMF supplies sNssai on the Create SM Context; the DNN must exist under a matching S-NSSAI in the subscriber's UDM SM data	The SMF looks up the requested DNN across every subscribed S-NSSAI entry's dnnConfigurations
Session-AMBR	UDM dnnConfiguration.sessionAmbr	Provisioned in PyHSS → UDM/UDR	Sent to the PCF as both subsSessAmbr and sessionAmbr (see Session-AMBR toward the PCF)
Default QoS (5QI + ARP)	UDM dnnConfiguration.5gQosProfile	Provisioned in PyHSS → UDM/UDR	Defaults to 5QI 9, ARP priority 15 when absent; becomes the default QoS flow (QFI 1)
PDU session type(s)	UDM dnnConfiguration.pduSessionTypes	defaultSessionType + allowedSessionTypes	UE request honoured only if in the allowed set, else the default is used; defaults to IPV4
SSC mode	UDM dnnConfiguration.sscModes	defaultSscMode + allowedSscModes (TS 23.501 §5.6.9.2)	UE request honoured only if in the allowed set, else the default is used; defaults to SSC_MODE_1
Static UE IP	UDM dnnConfiguration.staticIpAddress	Provisioned in PyHSS → UDM/UDR	See Static IP field and reservation
UE IP pool (dynamic)	SMF ue_ip_pool subnet_map	SMF configuration	Keyed per-DNN; see DNN-aware pools
DNS / MTU / P-CSCF (ePCO)	SMF dns / dns6 / mtu / :pco	SMF configuration	Handed to the UE in the Establishment Accept ePCO; not per-DNN, except the P-CSCF is only returned when the DNN begins with ims

The rule of thumb: per-subscriber and per-DNN policy (S-NSSAI, AMBR, default QoS, session type, SSC mode, static IP) lives in the UDM subscription; the network resources handed to the UE (dynamic IP pool, DNS, MTU, P-CSCF) live in SMF configuration. A DNN that is present in the SMF subnet_map but absent from the subscriber's UDM SM data is rejected with 404 DNN_DENIED; a DNN present in the UDM but with no matching subnet_map entry and no default pool fails IP allocation with :no_pool_for_dnn.

UE IP Address Allocation

Every PDU session is assigned an IP address (IPv4, IPv6, or both) before the PFCP session is established with the UPF. The IP pool mirrors the 4G PGW-C allocation model. Sources are tried in priority order:

1. N26 adopted address. For a 4G-originated session moving to 5G over N26 (an adoptedIpv4 on the create request), the UE IP the standalone PGW-C already allocated is reused verbatim; the address belongs to the PGW-C's pool, so it is preserved across the handover, not re-allocated. For a dual-stack session the IPv6 portion is then allocated dynamically.
2. Static IP (subscriber-pinned). When the UDM SM subscription data contains a staticIpAddress for the requested DNN, that fixed address is honoured for every session on that DNN. This mirrors the 4G HSS/PGW-C static-IP behaviour and is ultimately provisioned in PyHSS and surfaced through the UDM/UDR. For a dual-stack session the IPv6 portion is allocated dynamically.
3. Dynamic pool. Otherwise an address is allocated from the DNN's configured pool. Allocation picks a random free host address (excluding network/broadcast for IPv4), retries on collision, and is deduplicated across all active sessions.

The UE IP is returned to the pool on any worker exit (explicit release, crash, or supervisor shutdown), so a CPE stuck in an establish/release/retry loop cannot slowly leak pool addresses.

DNN-aware pools (subnet_map)

Pools are selected per-DNN via the subnet_map. Keys are exact DNN names, ^regex patterns, or :default; values are lists of IPv4 and/or IPv6 CIDRs. Matching precedence is exact DNN → regex → :default. For an IPV4V6 session the SMF allocates from both the IPv4 and IPv6 ranges of the matched pool. See UE IP Pool in the Configuration Reference.

Static IP field and reservation

The staticIpAddress field follows TS 29.503 (DnnConfiguration) and TS 29.571 (IpAddress): an array of objects, each optionally carrying ipv4Addr (a single object is also accepted). A static address is reserved in the pool so it is never handed out dynamically:

• A static address inside a configured range is counted against that pool and excluded from dynamic allocation.
• A static address outside every configured range is tracked for duplicate detection only and does not consume pool capacity (static IPs may live on their own routed subnet).
• If the static address is already in use by another live session, the new PDU session is rejected (:static_ip_in_use) rather than issuing a duplicate, matching the 4G PGW-C. This should only occur if the same static IP is misconfigured against two subscribers.

To provision a static IP, set staticIpAddress on the subscriber's DNN configuration (via PyHSS → UDM/UDR); no SMF configuration change is required.

PDU session type reconciliation (TS 24.501 §6.4.1.3)

When a dual-stack (IPV4V6) session is requested but the matched pool only yields one address family, the SMF reconciles the signalled session type down to the family it actually allocated before it builds the N1 Establishment Accept and the N2 PDUSessionResourceSetupRequestTransfer:

• IPv4 allocated, no IPv6 → signal IPV4 with 5GSM cause #50 (PDU session type IPv4 only allowed).
• IPv6 allocated, no IPv4 → signal IPV6 with 5GSM cause #51 (PDU session type IPv6 only allowed).
• Both families present → signal IPV4V6 unchanged.

This is required for interoperability: advertising IPV4V6 while carrying only an IPv4 address makes the RAN reject the N2 resource setup. Operators serving dual-stack subscriptions from IPv4-only pools will therefore see those sessions come up as IPv4 with the corresponding NAS cause, rather than failing.

Monitoring

• GET /api/ip_pool: overall IPv4 capacity plus a per-DNN pool summary.
• GET /api/ip_pool/detail: per-DNN pools with each range's CIDR, total/allocated/available, and the full list of currently-allocated addresses (dynamic + static).

IPv6 note: IPv6 addresses are allocated, reserved, released, and reported by the pool.

P-CSCF Discovery and Advertisement (VoNR / IMS)

For an IMS/VoNR PDU session the UE must learn a P-CSCF to register against. The SMF returns it in the ePCO of the PDU Session Establishment Accept (P-CSCF IPv4 container 0x000C, IPv6 container 0x0001), one container per address, identical to the 4G PGW-C. The P-CSCF is only returned when the DNN begins with ims. Selection order:

1. DNS discovery + health check (preferred). When p_cscf_discovery_enabled, the SMF resolves _sip._tcp.<fqdn> (SRV) to A/AAAA, then health-checks each candidate with a SIP OPTIONS (TCP then UDP). Only servers that answer are advertised, and the set is refreshed on a fixed 60-second cycle, so a P-CSCF that stops answering OPTIONS is dropped from the advertised set within roughly one minute, and a recovered one is re-added on the next cycle. The refresh runs independently of session establishment; new sessions always read the latest healthy set.
2. Static fallback. If discovery is disabled or returns nothing healthy, p_cscf_ipv4_address_list / p_cscf_ipv6_address_list are used.

This mirrors the PGW-C exactly, so a mixed 4G/5G IMS deployment configures P-CSCF the same way on both nodes. See P-CSCF and Protocol Configuration Options.

Dedicated QoS Flow / GBR Bearer (VoNR, 5QI-1)

VoNR needs a dedicated GBR QoS flow (5QI 1) for the voice media, alongside the default non-GBR flow. Both a static (provisioned) and a dynamic (call-driven) path are supported.

Static: the GBR rule is provisioned in policy (PyHSS PCRF charging-rule to UDR sm-policy-data to PCF PCC rule) and returned on the sm-policies decision. It is stashed and installed once the PFCP session exists, so the UPF marks the flow with its 5QI/GBR from the moment the session comes up.

Dynamic (call-driven): the flow is added when the call is answered and removed on BYE, driven by the PCF policy-notify callback:

The notification is delivered to /nsmf-callback/sm-policy-notify/{smContextRef} (the SMF reads smPolicyDecision from the body): a non-null PCC rule installs the flow, a null-valued rule removes it (TS 29.512, a null-valued PCC rule is a rule to remove). The AF app-session to SM-policy matching (by UE IP) is performed on the PCF.

PDU Session Modification: QoS Flow Update

An AMF may also drive a QoS-flow modification directly through the modify endpoint with a qosFlows list, rather than via the PCF. Each entry either updates an existing flow (matched by qfi) or allocates a new QFI. The UPF is re-programmed with the changed QoS, and because SmContextUpdatedData defines no qosFlows JSON member, the response is 204 No Content; the QoS change is conveyed to the gNB via N2 SM information.

PDU Session Release (TS 23.502 §4.3.4)

Teardown order is PCF policy delete → PFCP session delete → UDM deregistration → SM context status notification (resourceStatus: RELEASED) to the AMF callback; the worker then releases the UE IP back to the pool and stops. The same teardown runs for an AMF-initiated release: true modify.

UE Idle / Service Request: UP Connection State (TS 23.502 §4.2.3)

On ACTIVATING, the SMF updates the PTI from the UE's latest establishment request and sends an N1N2MessageTransfer to the AMF to trigger the PDUSessionResourceSetup on the gNB; the 200 response carries upCnxState: ACTIVATING. The user plane is re-pointed at the gNB only once the gNB F-TEID arrives in the follow-up PDU_RES_SETUP_RSP.

Handover State Transitions

An AMF-driven handover progresses the session through hoState values on the modify endpoint:

• PREPARING / PREPARED: state is recorded; the user plane is not changed.
• COMPLETED: the tunnel is re-activated (PFCP modification, downlink FAR to the target gNB) and the handover state cleared.
• CANCELLED: the handover state is cleared with no user-plane change.

N4 PFCP Session Structure

Each PDU session installs the following PFCP IEs on the UPF (TS 29.244):

IE	Direction	Purpose
PDR (uplink)	Access → Core	Match GTP-U traffic from gNB on the UPF N3 F-TEID
PDR (downlink)	Core → Access	Match traffic from N6 by UE IP address
FAR (uplink)	Core	Forward to N6 (no outer header)
FAR (downlink)	Access	Initially BUFFER; updated to GTP-U FORWARD after PDU_RES_SETUP_RSP
QER	Both	Enforce session AMBR (uplink and downlink MBR); dedicated QER added per GBR flow
URR	Both	Time-based usage reporting (threshold derived from heartbeat_interval)

The single URR uses duration-based measurement with a time-threshold trigger. The threshold is derived from heartbeat_interval (six times its value, e.g. 60 s at the default 10 s heartbeat), so it is not independently tunable; raise heartbeat_interval to lengthen the reporting cadence. Usage reports the UPF sends back are recorded and surfaced as the omni_smf_n4_usage_reports_total and omni_smf_n4_usage_report_volume_bytes_total metrics (see Metrics), and, when N40 converged charging is enabled, forwarded to the CHF as interim Charging Data Requests.

The PFCP association with the UPF is established (with heartbeats) before any session request is sent. If the association is lost, it can be re-triggered through the management API (POST /api/oam/pfcp/reassociate).

N26 EPS Interworking (4G ↔ 5G)

The SMF and the standalone PGW-C share a UPF and coordinate over an internal N26 interworking path so a UE keeps its IP address across a handover:

• Adopt (4G → 5G): a 4G-originated EPS session is adopted into 5GS, reusing the PGW-C's already-allocated UE IP. Re-adopting an existing session returns the existing 5G session rather than creating a duplicate.
• Switch: an existing session's access side is switched to :eps (5G → 4G) or :fivegs (4G → 5G) by updating the access tunnel via a PFCP modification (S-GW S5/S8-U TEID/address for EPS, gNB N3 TEID/address for 5GS) while keeping the same UE IP and the same PFCP session on the UPF. The switch returns an EPS view (preserved UE IP, DNN, session AMBR, default EPS bearer id, and the PGW-U F-TEID) that the PGW-C uses to answer the SGW.
• Lookup: a UE's active PDU sessions can be read as EPS PDN-connection views by SUPI/IMSI.

The management API exposes POST /api/eps_handover to drive interworking. The paired PGW-C's S5/S8-C address is advertised via the pgw_c_addr configuration key (see Configuration Reference).