Skip to content

Architecture Overview

This doc captures the high-level design decisions. For what is implemented, see implementation-status.md and features.md. For per-NF detail, see the NF folder under nf/<nf>/; per-procedure designs and conformance are in the members documentation.

flowchart LR
  subgraph RAN
    UE -- Uu --> gNB
  end

  subgraph CP[Control Plane]
    NRF
    AMF
    SMF
    AUSF
    UDM
    UDR
    PCF
    NSSF
    SMSF
    BSF
    NEF
    LMF
  end

  subgraph UP[User Plane]
    UPF
  end

  subgraph DN[Data Networks]
    Internet
    IMS
  end

  subgraph TOOLS["Management plane (non-3GPP)"]
    MCP[MCP server]
    PORTAL[mgmt-portal]
    OBS[Loki / Prometheus / Grafana / Jaeger]
  end

  AF["AF (external)"]
  PG[(PostgreSQL)]
  REDIS[(Redis)]

  UE -. "N1 (NAS, over N2)" .- AMF
  gNB -- "N2 (NGAP/SCTP)" --> AMF
  gNB -- "N3 (GTP-U)" --> UPF
  AMF <-- "N11 (Nsmf / Namf_Communication)" --> SMF
  SMF -- "N4 (PFCP)" --> UPF
  AMF -- "N12 (Nausf)" --> AUSF
  AUSF -- "N13 (Nudm)" --> UDM
  AMF -- "N8 (Nudm)" --> UDM
  SMF -- "N10 (Nudm)" --> UDM
  UDM -- "N35 (Nudr)" --> UDR
  AMF -- "N15 (Npcf)" --> PCF
  SMF -- "N7 (Npcf)" --> PCF
  PCF -- "N36 (Nudr)" --> UDR
  AMF -- "N22 (Nnssf)" --> NSSF
  AMF <-- "N20 (Nsmsf / Namf_Communication)" --> SMSF
  SMSF -- "N21 (Nudm)" --> UDM
  AMF <-- "NL1 (Nlmf / Namf_Location)" --> LMF
  LMF -- "Nudm_SDM" --> UDM
  PCF -- "Nbsf" --> BSF
  NEF -- "Nbsf (discovery)" --> BSF
  NEF -- "N30 (Npcf_PolicyAuthorization)" --> PCF
  AF -- "N33 (Nnef)" --> NEF
  UPF -- "N6" --> Internet
  UPF -- "N6" --> IMS
  PG -.- UDR & AMF & SMF
  REDIS -.- AMF & NRF
  TOOLS -. "metrics, logs, traces, NF APIs" .-> CP

All control-plane NFs register with and discover each other through the NRF (Nnrf edges omitted for readability).

Only relations implemented in code are drawn. Where both NFs call each other, the edge is bidirectional.

Ref. point Between Services used Notes
N1 UE – AMF NAS-5GS Logical; carried over N2
N2 gNB – AMF NGAP/SCTP
N3 gNB – UPF GTP-U
N4 SMF – UPF PFCP
N6 UPF – DN IP One network per DNN
N7 SMF – PCF Npcf_SMPolicyControl
N8 AMF – UDM Nudm_UECM, Nudm_SDM AMF registration + am-data
N10 SMF – UDM Nudm_SDM sm-data only; no SMF registration in UDM
N11 AMF – SMF Nsmf_PDUSession; Namf_Communication (N1N2 transfer) SMF → AMF for paging and secondary authentication
N12 AMF – AUSF Nausf_UEAuthentication, Nausf_NSSAA
N13 AUSF – UDM Nudm_UEAuthentication
N15 AMF – PCF Npcf_AMPolicyControl, Npcf_UEPolicyControl
N20 AMF – SMSF Nsmsf_SMService; Namf_Communication (N1N2 transfer) SMSF → AMF for MT SMS
N21 SMSF – UDM Nudm_UECM SMSF registration only
N22 AMF – NSSF Nnssf_NSSelection
N30 NEF – PCF Npcf_PolicyAuthorization After PCF binding lookup in BSF
N33 AF – NEF Nnef AsSessionWithQoS NEF API is served; no AF is shipped
N35 UDM – UDR Nudr_DataRepository Subscription data
N36 PCF – UDR Nudr_DataRepository Policy data
NL1 AMF – LMF Nlmf_Location; Namf_Location LMF → AMF for DL NRPPa / LPP relay
— LMF – UDM Nudm_SDM LCS privacy data
— PCF, NEF – BSF Nbsf_Management No numbered reference point

Not implemented: N37 (NEF – UDR), N40 (CHF), N9 (I-UPF), SCP, UDSF.

  • PostgreSQL holds UDR subscriber data, AMF UE contexts, SMF sessions and portal data. Redis backs the AMF cache and the NRF registry. They are per-NF stores, not SBI peers, and there is no UDSF (Nudsf).
  • MCP server and mgmt-portal are management-plane clients. They call NF APIs directly (NRF, SMF nsmf-management, UDM, the AMF management API on 9002; the portal also UDR, PCF and LMF), not through the NEF.
  • Observability scrapes /metrics and container logs and receives OTLP traces; it is not an SBI consumer.
Decision Choice Rationale
Communication model Direct, with NRF discovery; no SCP TS 23.501 Annex E models A/B
Transport for SBI HTTP/2 + TLS 1.3, mTLS TS 29.500 §6.2
Auth for SBI OAuth2 client_credentials, NRF as AS TS 33.501 §13.4.1
Service discovery NRF (no DNS-SD) TS 23.501 §6.3.1
Internal NF storage Per-NF state in process (PostgreSQL / Redis backed); UDR for subscriber data; charging not implemented Avoid sharing state between NF instances
Codecs (NGAP/NAS) NGAP/NRPPa: in-repo shared/ngap / shared/nrppa on github.com/free5gc/aper (Apache-2.0); NAS: shared/nas Avoid reimplementing ASN.1 PER
UPF data plane Userspace Go datapath: per-DNN TUN (upfgtpN) + iptables MASQUERADE; Rust + eBPF/XDP later Pragmatic MVP, scale later
Release / capability layer Each NF carries a release profile (rel19 default, rel17 frozen legacy); Rel-18/19 behaviour is gated per feature and per peer (SBI supportedFeatures, NAS capability bits, gNB release inferred at NG Setup). Legacy peers get byte-identical messages Rel-19 baseline with Rel-15/16/17 RAN/UE compatibility; mixed-release NFs coexist (TS 29.500 §6.6.2)
Roaming SEPP (N32-c / N32-f) between PLMNs, vsepp + hsepp TS 23.501 §4.2.4, TS 29.573
Kubernetes vs Compose Compose Fewer moving parts during development
Service mesh None SBA already has NRF; mesh breaks SBI tracing

The default deployment is a standalone deployment (core-only): the NFs, observability and the portal run with no RAN simulator built or started. RAN simulators are opt-in through the root Makefile variable RAN (compose profiles in parentheses):

RAN= Running next to the core Compose profiles added
none (default) nothing — (core, observability, tools as requested)
ueransim UERANSIM gNB + UEs integration-ueransim
packetrusher PacketRusher dual-gNB (PR_SCENARIO=xn|n2|none) handover / handover-n2
both both all of the above

The mgmt-portal detects the mode at runtime from the running containers (GET /api/v1/deployment, override PORTAL_RAN_TOOLS) and hides the UERANSIM / PacketRusher pages when absent. The gNBs (RAN) page works in every mode because its data comes from the AMF, not from Docker: the AMF gNB registry is served on the management port GET :9002/amf/v1/ran/gnbs (plain HTTP, read-only). Commands: getting-started.md.

Network Subnet Purpose Members
sbi-net 172.30.0.0/24 HTTP/2 SBI between control-plane NFs All CP NFs, postgres, redis
n2-net 172.30.1.0/24 NGAP/SCTP between gNB and AMF AMF, gNB simulators
n4-net 172.30.2.0/24 PFCP between SMF and UPF SMF, UPF
n3-net 172.30.3.0/24 GTP-U between gNB and UPF UPF, gNB simulators
n6-net 172.30.6.0/24 + fd00:6::/64 UPF egress for the internet DNN UPF
n6-ims-net 172.30.7.0/24 + fd00:7::/64 UPF egress for the ims DNN UPF
n32-net (5gc-n32) 172.30.5.0/24 N32 inter-PLMN interconnect (roaming); FQDN aliases sepp.5gc.mnc00{1,2}.mcc001.3gppnetwork.org vsepp, hsepp
obs-net (Docker-assigned) Observability Loki, Prometheus, Grafana, Jaeger, NFs

perf profile (opt-in benchmarking, headline figures in performance/summary.md): iperf3-dn 172.30.6.50 and gtpu-bench-dn 172.30.6.51 on n6-net; gtpu-bench 172.30.3.20 on n3-net + n4-net; iperf3-upf-local shares the UPF network namespace (10.60.0.254). iperf3 ports: 5201-5216 (iperf3-dn), 5301-5316 (iperf3-upf-local); none are published to the host.

UE IP pools are per DNN (10.60.0.0/24 internet, 10.61.0.0/24 ims, …); the single source of truth is config/operator.yaml. There is no N9 network yet (no I-UPF).

Component Service port(s) Metrics
NRF 8000 (SBI) 9100
AMF 8001 (SBI), 9002 (management API), 38412/sctp (N2) 9101
AUSF 8002 9102
UDM 8003 9103
UDR 8005 9104
SMF 8004 9105
PCF 8006 9106
UPF 8805/udp (N4), 2152/udp (N3) 9107
NSSF 8007 9109
SMSF 8009 9110
BSF 8010 9111
NEF 8011 9112
LMF 8012 9113
MCP server 9300 (SSE) —
Management portal 8080 —

No port collision exists between UERANSIM and PacketRusher: each simulator runs in its own network namespace and every gNB has its own IP. NGAP uses SCTP PPID 60 (TS 38.412 §7); GTP-U stays on 2152 (TS 29.281 §4.4.2.3).

Endpoint N2 (5gc-n2 / n2-net) N3 (n3-net) gNB ID / NCI
Core: AMF N2 listener 172.30.1.2:38412/sctp — —
Core: UPF N3 listener — 172.30.3.100:2152/udp —
UERANSIM ueransim-gnb dynamic IP, ephemeral SCTP local port 172.30.3.3 gNB-ID 0x00000001 (32-bit), nci 0x000000010
UERANSIM ueransim-gnb-ms dynamic IP 172.30.3.4 gNB-ID 0x10, nci 0x000000100; own aliases ueransim-gnb-ms / ueransim-gnb-ms-n3, so it runs next to ueransim-gnb (make ueransim-all)
PacketRusher gNB1 172.30.1.20:9487 172.30.3.10:2152 gNB-ID 000002 (24-bit)
PacketRusher gNB2 (handover) 172.30.1.21:9488 172.30.3.11:2152 gNB-ID 000003

docker/packetrusher/entrypoint.sh runs ARP duplicate-address detection before adding the secondary .21/.11 addresses (exits 1 with a clear message if taken) and then a gratuitous ARP. Verify with curl -s localhost:9002/amf/v1/ran/gnbs (all gNBs NG_READY).

Three pillars, all wired from Day 0:

  1. Logs — JSON to stdout per NF, scraped by Promtail, indexed by Loki, queried via Grafana. 3GPP-aware fields (SUPI, GUTI, correlation_id, spec_ref) enforced by shared/logging.
  2. Metrics — Prometheus, scraped from each NF on its metrics port (9100–9113, see above). Standard set: fivegc_sbi_requests_total, fivegc_sbi_request_duration_seconds, plus per-procedure/timer metrics.
  3. Traces — OpenTelemetry to Jaeger via OTLP. Per-procedure trace, spans per SBI call and per N1/N2/N4 message.

Plus PCAP per NF via tcpdump sidecar. Wireshark dissects NGAP, NAS-5GS, PFCP, GTP-U, and HTTP/2 SBI natively.

SEPP (wired, REL19-9.6/9.7). Roaming edge proxy for N32-c / N32-f; see docs/procedures/n32-roaming-interconnect.md. Compose: vsepp (profile core; host SBI 8014, N32 8443, metrics 9115), hsepp (profile roaming; 8114 / 8543 / 9215), hnrf (profile roaming; SBI 8100, metrics 9200, PLMN 001/02, in-memory registry), PCAP sidecars vsepp-pcap / hsepp-pcap. Prometheus scrapes vsepp:9115 / hsepp:9115. E2E: make sepp-e2e. The MCP target list and scripts/services-restart-check.sh cover vsepp.

Made and developed by Francisco Javier Curieses Sanz · Docs mirrored from claudia-5gc @ v3.0.0 · Privacy · Legal