Rules Management Guide

Table of Contents

1. Overview
2. Packet Detection Rules (PDR)
3. Forwarding Action Rules (FAR)
4. QoS Enforcement Rules (QER)
5. Usage Reporting Rules (URR)
6. Rule Relationships
7. Common Operations
8. Troubleshooting

Overview

OmniUPF uses a set of interconnected rules to classify, forward, shape, and track user plane traffic. These rules are installed by the SMF via PFCP and stored in eBPF maps for high-performance packet processing. Understanding these rules and their relationships is critical for operating and troubleshooting the UPF.

Rule Types

Rule Type	Purpose	Key Field	Installed By
PDR (Packet Detection Rule)	Classify packets into flows	TEID or UE IP	SMF via PFCP Session Establishment/Modification
FAR (Forwarding Action Rule)	Determine forwarding action	FAR ID	SMF via PFCP Session Establishment/Modification
QER (QoS Enforcement Rule)	Apply bandwidth limits and marking	QER ID	SMF via PFCP Session Establishment/Modification
URR (Usage Reporting Rule)	Track data volumes for charging	URR ID	SMF via PFCP Session Establishment/Modification

Rule Processing Flow

Packet Detection Rules (PDR)

Purpose

PDRs classify incoming packets into traffic flows. They are the entry point for all packet processing in the UPF.

PDR Structure

Uplink PDRs

Uplink PDRs match packets arriving on the N3 interface from the RAN.

Key Field: TEID (Tunnel Endpoint Identifier)

• 32-bit unsigned integer
• Assigned by SMF and signaled to gNB
• Unique per UE traffic flow

Value Fields:

• FAR ID: Reference to forwarding action rule
• QER ID: Reference to QoS enforcement rule (optional)
• URR IDs: List of usage reporting rules (optional)
• Outer Header Removal: Flag to remove GTP-U encapsulation

Lookup Process:

1. Extract TEID from GTP-U header
2. Hash lookup in uplink_pdr_map eBPF map
3. If match found, retrieve FAR ID, QER ID, and URR IDs
4. If no match, drop packet

Example:

TEID: 5678
FAR ID: 2
QER ID: 1
Outer Header Removal: False
SDF Mode: No SDF

Downlink PDRs

Downlink PDRs match packets arriving on the N6 interface from the data network.

Key Field: UE IP Address

• IPv4 address (32-bit) or IPv6 address (128-bit)
• Assigned by SMF during PDU session establishment
• Unique per UE

Value Fields:

• FAR ID: Reference to forwarding action rule
• QER ID: Reference to QoS enforcement rule (optional)
• URR IDs: List of usage reporting rules (optional)
• SDF Mode: Service Data Flow filter mode
  • No SDF: No filtering, all traffic matches
  • SDF Only: Only SDF-matched traffic is forwarded
  • SDF + Default: SDF-matched traffic uses specific rules, other traffic uses default FAR
• SDF Filters: Application-specific filters (ports, protocols, IP ranges)

Lookup Process:

1. Extract destination IP from packet header
2. Hash lookup in downlink_pdr_map (IPv4) or downlink_pdr_map_ip6 (IPv6)
3. If match found, check SDF filters (if configured)
4. Retrieve FAR ID, QER ID, and URR IDs
5. If no match, drop packet

Example:

UE IP: 10.45.0.1
FAR ID: 1
QER ID: 1
Outer Header Removal: False
SDF Mode: No SDF

SDF Filters (Service Data Flow)

SDF filters provide application-specific traffic classification within a PDR.

Use Cases:

• Differentiate YouTube traffic from web browsing
• Apply different QoS to VoIP vs. best-effort data
• Route specific applications through different network paths

Filter Criteria:

• Protocol: TCP, UDP, ICMP
• Port Range: Destination ports (e.g., 443 for HTTPS, 5060 for SIP)
• IP Address Range: Specific destination networks
• Flow Description: 3GPP-defined flow templates

Example SDF Configuration:

PDR ID: 10
UE IP: 10.45.0.1
SDF Mode: SDF Only
SDF Filters:
  - Protocol: UDP, Ports: 5060-5061 → FAR ID 5 (VoIP FAR)
  - Protocol: TCP, Port: 443 → FAR ID 1 (Default FAR)

Forwarding Action Rules (FAR)

Purpose

FARs determine what to do with packets that match a PDR. They define forwarding actions, GTP-U encapsulation parameters, and destination endpoints.

FAR Structure

Action Flags

FAR actions are bitwise flags that can be combined:

Flag	Bit	Value	Description
FORWARD	1	2	Forward packet to destination
BUFFER	2	4	Store packet in buffer
DROP	0	1	Discard packet
NOTIFY	3	8	Send notification to control plane
DUPLICATE	4	16	Duplicate packet to multiple destinations

Common Action Combinations:

• Action: 2 (FORWARD) - Normal forwarding (most common)
• Action: 6 (FORWARD + BUFFER) - Forward and buffer during handover
• Action: 4 (BUFFER) - Buffer only (during path switch)
• Action: 1 (DROP) - Drop packet (rare, usually for policy enforcement)

Buffering Control

The BUFFER flag (bit 2) controls packet buffering during mobility events. Buffering is a critical UPF feature that prevents packet loss during UE state transitions.

When Buffering is Used

Idle-to-Connected Transition: When downlink packets arrive for a UE in IDLE state (not connected to gNB), the UPF:

1. Buffers the packets
2. Sends a Downlink Data Notification (DLDR) to the SMF
3. SMF pages the UE to wake up and connect
4. Once connected, SMF updates the FAR with FORWARD action
5. UPF flushes buffered packets to the UE

Handover (Connected-to-Connected): During gNB-to-gNB handover, the UPF temporarily buffers packets to prevent loss:

1. Old gNB connection is dropped
2. SMF sets FAR action to BUFFER
3. Packets queue during path switch
4. UE connects to new gNB
5. SMF updates FAR with new TEID and FORWARD action
6. UPF flushes packets to new gNB

Buffer Capacity and Limits

Global Buffer Limits:

• Max Total Packets: 100,000 (configurable)
• Max Total Bytes: Based on available memory
• TTL (Time-to-Live): 60 seconds (configurable)
• Packets exceeding TTL: Automatically dropped

Per-FAR Limits:

• Max Packets per FAR: 10,000 (configurable)
• Purpose: Prevent a single FAR from exhausting buffer capacity

Buffer Overflow Behavior:

• When global or per-FAR limit reached, new packets are dropped
• Metrics track drops with reason="global_limit" or reason="far_limit"
• Oldest packets are NOT automatically evicted (explicit drop only on TTL expiration)

Downlink Data Notification (DLDR)

When the UPF buffers a packet for an IDLE UE, it sends a PFCP Session Report Request to the SMF:

DLDR Contents:

• Report Type: Downlink Data Report (DLDR)
• FAR ID: The FAR that triggered buffering
• Downlink Data Service Information: Optional QFI, Paging Policy Indicator

SMF Actions on DLDR:

1. Page the UE via AMF → gNB
2. Wait for UE to establish RRC connection
3. Send PFCP Session Modification Request to update FAR
4. FAR action changes from BUFF+NOCP to FORW
5. UPF flushes buffered packets

Metrics for DLDR:

• upf_dldr_sent_total: Total DLDRs sent
• upf_dldr_send_errors: Failed DLDRs
• upf_buffer_notify_to_flush_duration_seconds: Latency from DLDR to flush

See Metrics Reference for complete list.

Buffering Operations

Enable Buffering (Set BUFF flag):

• FAR Action |= 0x04 (set bit 2)
• Example: Action: 2 (FORW) → Action: 6 (FORW+BUFF)
• Used during handover preparation

Buffer-Only Mode (BUFF without FORW):

• FAR Action = 0x04 (BUFF only)
• Packets are buffered but NOT forwarded
• Used for IDLE UE state (pending paging)

Disable Buffering (Clear BUFF flag):

• FAR Action &= ~0x04 (clear bit 2)
• Example: Action: 6 (FORW+BUFF) → Action: 2 (FORW)
• Buffered packets remain until flushed or cleared

Flush Buffer:

• Replay all buffered packets using current FAR rules
• Packets are forwarded with updated TEID/destination
• Buffer is emptied after successful flush
• FAR must have FORW action set

Clear Buffer:

• Discard all buffered packets without forwarding
• Use when handover fails or session is deleted
• Metrics track with reason="cleared"

Monitoring Buffered Packets

Buffers Page (Web UI): Navigate to Buffers to view:

• Total buffered packets
• Total buffered bytes
• Number of FARs with buffered packets
• Per-FAR packet counts
• Oldest packet timestamp
• Enable/Disable buffering per FAR
• Flush or clear operations

Key Indicators:

• Packets > 10 seconds old: Potential paging delay
• Packets > 30 seconds old: Likely paging failure, clear buffer
• High packet count: Check for stuck sessions or paging failures

Prometheus Metrics:

• upf_buffer_packets_current: Current buffered packets
• upf_buffer_bytes_current: Current buffered bytes
• upf_buffer_fars_active: FARs with buffered packets
• upf_buffer_packets_dropped{reason}: Dropped packet counts

See Metrics Reference for complete buffer metrics.

Common Buffering Scenarios

Scenario 1: IDLE UE Downlink Data

Initial State:
- UE in IDLE mode (no gNB connection)
- FAR Action: 0x04 (BUFF only)

Data Arrival:
1. DN sends downlink packet
2. UPF matches PDR, applies FAR
3. FAR has BUFF flag → packet buffered
4. UPF sends DLDR to SMF
5. SMF pages UE
6. UE connects to gNB
7. SMF modifies FAR: Action = 0x02 (FORW)
8. UPF flushes buffered packets with new TEID

Scenario 2: Handover Preparation

Initial State:
- UE connected to gNB-1 (TEID 1234)
- FAR Action: 0x02 (FORW)

Handover Process:
1. SMF modifies FAR: Action = 0x06 (FORW+BUFF)
2. Packets forwarded to gNB-1 AND buffered
3. UE switches to gNB-2
4. SMF modifies FAR: TEID = 5678, Action = 0x02 (FORW)
5. UPF flushes buffered packets to gNB-2 with new TEID
6. No packet loss during handover

Scenario 3: Path Switch

Initial State:
- UE connected, active data flow

Path Switch:
1. SMF modifies FAR: Action = 0x04 (BUFF only)
2. All incoming packets buffered (not forwarded)
3. Network reconfigures path
4. SMF modifies FAR: Action = 0x02 (FORW), new destination
5. UPF flushes all buffered packets to new path

Outer Header Creation

Determines whether GTP-U encapsulation should be added.

Uplink FAR (N3 → N6):

• Outer Header Creation: False
• Action: Remove GTP-U, forward native IP packet

Downlink FAR (N6 → N3):

• Outer Header Creation: True
• Remote IP: gNB IP address (e.g., 200.198.5.10)
• TEID: Tunnel ID for UE traffic
• Action: Add GTP-U header, forward to gNB

FAR Lookup in Web UI

The Rules Management page provides FAR lookup by ID:

Steps:

1. Navigate to Rules → FARs tab
2. Enter FAR ID in search field
3. Click "Lookup" to view FAR details

Displayed Information:

• FAR ID
• Action (numeric + decoded flags)
• Buffering status (ON/OFF)
• Outer Header Creation
• Remote IP address (with integer representation)
• TEID
• Transport Level Marking

QoS Enforcement Rules (QER)

Purpose

QERs apply Quality of Service parameters to traffic flows, including bandwidth limits and packet marking.

QER Structure

QoS Parameters

QFI (QoS Flow Identifier):

• 6-bit identifier for 5G QoS flows
• Values 1-9 are standardized (e.g., QFI 9 = default bearer)
• Used for packet marking in 5GC

Gate Status:

• Open (0): Traffic allowed
• Closed (non-zero): Traffic blocked

Maximum Bit Rate (MBR):

• Maximum allowed bandwidth for traffic flow
• Specified in kbps
• MBR = 0: No rate limit (unlimited)
• Traffic exceeding MBR is dropped

Guaranteed Bit Rate (GBR):

• Minimum bandwidth guaranteed for traffic flow
• Specified in kbps
• GBR = 0: Best-effort (no guarantee)
• GBR > 0: Prioritized flow with guaranteed bandwidth

QoS Flow Types

Best-Effort Flows (GBR = 0):

QER ID: 1
QFI: 9
MBR Uplink: 100000 kbps (100 Mbps)
MBR Downlink: 100000 kbps (100 Mbps)
GBR Uplink: 0 kbps
GBR Downlink: 0 kbps

Guaranteed Flows (GBR > 0):

QER ID: 2
QFI: 1
MBR Uplink: 10000 kbps (10 Mbps)
MBR Downlink: 10000 kbps (10 Mbps)
GBR Uplink: 5000 kbps (5 Mbps)
GBR Downlink: 5000 kbps (5 Mbps)

QoS Enforcement Algorithm

MBR Enforcement Mechanism

OmniUPF enforces MBR (Maximum Bit Rate) limits using a sliding window rate limiter implemented in the eBPF datapath. This algorithm operates at nanosecond precision directly in the XDP layer, ensuring line-rate performance without kernel context switches.

How It Works

Algorithm: Sliding Window Rate Limiting

For each packet, the UPF performs the following checks:

1. Gate Status Check: If gate status is CLOSED (non-zero), drop packet immediately
2. MBR Check: If MBR = 0, bypass rate limiting (unlimited bandwidth)
3. Transmission Time Calculation:

   tx_time = (packet_size_bytes × 8) × (1,000,000,000 ns/sec) / MBR_kbps

4. Window Check: If current time is within the 5ms sliding window, drop packet
5. Window Advance: If packet is allowed, advance window by tx_time

Example Calculation:

Assume:

• MBR = 100,000 kbps (100 Mbps)
• Packet size = 1500 bytes
• Window size = 5,000,000 ns (5 ms)

Step 1: Calculate transmission time at 100 Mbps
tx_time = (1500 bytes × 8 bits/byte) × (1,000,000,000 ns/sec) / 100,000,000 bps
        = 12,000,000,000 / 100,000,000
        = 120 ns

Step 2: Check if packet fits in window
current_time = 1000000000 ns
window_start = 999990000 ns
if (window_start + tx_time > current_time):
    DROP packet (would exceed rate limit)

Step 3: If allowed, advance window
window_start = window_start + 120 ns
PASS packet

Sliding Window Behavior

5ms Window Size:

• The algorithm uses a 5 millisecond sliding window
• Window automatically resets if idle for more than 5ms
• Prevents burst starvation while enforcing average rate

Burst Handling:

• Small bursts are allowed within the 5ms window
• Sustained traffic above MBR is rate-limited
• More accurate than simple token bucket algorithms

Per-Direction Rate Limiting:

• Uplink MBR uses qer->ul_start timestamp
• Downlink MBR uses qer->dl_start timestamp
• Each direction is rate-limited independently

Rate Limit Enforcement Points

Uplink (N3 → N6):

1. Packet arrives on N3 interface (from gNB)
2. PDR lookup by TEID
3. QER lookup by QER ID
4. Check ul_gate_status → drop if closed
5. Apply limit_rate_sliding_window() with ul_maximum_bitrate
6. If passed, forward to N6 and update URR counters

Downlink (N6 → N3):

1. Packet arrives on N6 interface (from Data Network)
2. PDR lookup by UE IP address
3. QER lookup by QER ID
4. Check dl_gate_status → drop if closed
5. Apply limit_rate_sliding_window() with dl_maximum_bitrate
6. If passed, add GTP-U header and forward to N3

N9 Loopback (SGWU ↔ PGWU):

• Both uplink and downlink QERs may apply in N9 loopback scenarios
• Each QER is checked independently at SGWU and PGWU boundaries

MBR vs. Observed Throughput

Why observed throughput may differ from MBR:

• Protocol Overhead: GTP-U, UDP, IP headers add ~50-60 bytes per packet
• Packet Size Variance: Smaller packets = more overhead, lower efficiency
• Rate Limit Precision: Enforcement happens per-packet, not per-byte
• Window Reset Behavior: 5ms idle periods allow brief bursts above MBR

Example:

Configured MBR: 100 Mbps
Observed Throughput: ~95-98 Mbps (due to GTP-U/UDP/IP overhead)

How to Verify Rate Limiting:

1. Check URR volume counters over time: upf_urr_*_volume_bytes
2. Calculate throughput: (volume_delta_bytes × 8) / time_delta_seconds / 1000 = kbps
3. Compare against configured MBR in QER

GBR (Guaranteed Bit Rate)

Important: OmniUPF does not currently enforce GBR minimums. GBR is stored in the QER but not used for traffic prioritization or admission control.

GBR Behavior:

• GBR values are accepted from SMF via PFCP
• GBR is stored in QER map and visible via API
• No bandwidth reservation or traffic prioritization based on GBR
• GBR serves as metadata for tracking flow type (best-effort vs. guaranteed)

Future Enhancement:

• GBR enforcement requires traffic scheduling or weighted queuing
• May be implemented using eBPF QoS capabilities in future releases

Usage Reporting Rules (URR)

Purpose

URRs track data volumes for charging, analytics, and policy enforcement. They maintain packet and byte counters that are reported to the SMF for charging records.

URR Structure

Volume Tracking

Uplink Volume:

• Bytes transmitted from UE to Data Network
• Measured after GTP-U decapsulation
• Includes IP header and payload

Downlink Volume:

• Bytes transmitted from Data Network to UE
• Measured before GTP-U encapsulation
• Includes IP header and payload

Total Volume:

• Sum of uplink and downlink volumes
• Used for total usage reporting

Usage Reporting Triggers

URRs can trigger reports based on:

Volume Threshold:

• Report when volume exceeds configured limit
• Example: Report every 1 GB of usage

Time Threshold:

• Report at periodic intervals
• Example: Report every 5 minutes

Event-Based:

• Report on session termination
• Report on QoS change
• Report on handover

Volume Display Formatting

The Web UI automatically formats volume in human-readable units:

Bytes	Display
0 - 1023	B (Bytes)
1024 - 1048575	KB (Kilobytes)
1048576 - 1073741823	MB (Megabytes)
1073741824 - 1099511627775	GB (Gigabytes)
1099511627776+	TB (Terabytes)

Example:

URR ID: 0
Uplink Volume: 12.3 KB
Downlink Volume: 9.0 KB
Total Volume: 21.3 KB

URR Reporting Flow

Rule Relationships

PDR → FAR → QER → URR Chain

Each PDR references a FAR, which may reference a QER and one or more URRs.

Example Session Configuration

Uplink PDR:

TEID: 5678
FAR ID: 2
QER ID: 1
URR IDs: [0]
Outer Header Removal: False

Downlink PDR:

UE IP: 10.45.0.1
FAR ID: 1
QER ID: 1
URR IDs: [0]
SDF Mode: No SDF

FAR ID 1 (Downlink):

Action: 2 (FORWARD)
Outer Header Creation: True
Remote IP: 200.198.5.10
TEID: 5678

FAR ID 2 (Uplink):

Action: 2 (FORWARD)
Outer Header Creation: False

QER ID 1:

QFI: 9
MBR Uplink: 100000 kbps
MBR Downlink: 100000 kbps
GBR Uplink: 0 kbps
GBR Downlink: 0 kbps

URR ID 0:

Uplink Volume: 12.3 KB
Downlink Volume: 9.0 KB
Total Volume: 21.3 KB

Common Operations

View Rules for a Session

Via Sessions Page:

1. Navigate to Sessions
2. Find UE by IP or TEID
3. Click "Expand" to view all rules (PDR, FAR, QER, URR)

Via Rules Page:

1. Navigate to Rules
2. Use lookup by TEID (uplink) or UE IP (downlink) in PDR tab
3. Note the FAR ID, QER ID, URR IDs
4. Switch to FAR/QER/URR tabs to view referenced rules

Enable/Disable Buffering

Scenario: During handover, buffer packets to prevent loss

Steps:

1. Navigate to Rules → FARs
2. Enter FAR ID in search field
3. Click "Lookup"
4. If buffering is OFF, click "Enable Buffering"
5. Verify FAR action bit 2 is set (Action value increases by 4)

Alternative via Buffers Page:

1. Navigate to Buffers
2. View FARs with buffering enabled
3. Click "Disable Buffer" when handover completes

Monitor QoS Compliance

Check if traffic is being rate-limited:

1. Navigate to Rules → QERs
2. Find QER ID associated with UE session
3. Note MBR Uplink and MBR Downlink values
4. Compare with URR volume growth rate

Calculate Average Throughput:

Throughput (kbps) = (Volume Delta in bytes × 8) / (Time Delta in seconds × 1000)

If throughput approaches MBR, traffic is being rate-limited.

Track Data Usage

Monitor URR volumes:

1. Navigate to Rules → URRs
2. View uplink, downlink, and total volumes
3. Sort by Total Volume to find highest users
4. Refresh periodically to observe volume growth

Use Cases:

• Verify charging integration
• Detect abnormal data usage
• Plan capacity based on traffic patterns

Troubleshooting

No Traffic Flowing

Check PDR:

1. Verify PDR exists for TEID (uplink) or UE IP (downlink)
2. Confirm FAR ID is valid
3. Check SDF filters aren't blocking traffic

Check FAR:

1. Verify FAR action is FORWARD (not DROP or BUFFER only)
2. Confirm outer header creation matches direction
3. Verify Remote IP and TEID are correct for downlink

Check QER:

1. Verify Gate Status is Open (0)
2. Check MBR is not too restrictive

Packets Being Dropped

Check QER Rate Limiting:

1. Navigate to Rules → QERs
2. Verify MBR is adequate for traffic load
3. Check URR volume growth matches expected throughput

Check FAR Action:

1. Navigate to Rules → FARs
2. Verify action is FORWARD, not DROP
3. Check buffering isn't stuck in BUFFER-only mode

Buffering Issues

Packets stuck in buffer:

1. Navigate to Buffers page
2. Check oldest packet timestamp
3. If > 30 seconds, handover may have failed
4. Manually flush or clear buffer
5. Disable buffering on FAR

Buffer overflow:

1. Check total packets vs. Max Total (default 100,000)
2. Check per-FAR packets vs. Max Per FAR (default 10,000)
3. Clear buffers if full
4. Investigate why buffering wasn't disabled

URR Not Tracking

Volume counters at zero:

1. Verify PDR references URR ID
2. Check that packets are matching PDR
3. Verify FAR is forwarding (not dropping) packets
4. Confirm URR ID exists in URR map

Volume not reporting to SMF:

1. Check PFCP Session Report configuration
2. Verify URR reporting triggers (volume/time thresholds)
3. Review logs for PFCP Session Report messages

Related Documentation

• UPF Operations Guide - Overview of OmniUPF architecture and components
• Web UI Operations Guide - Control panel usage for rule viewing
• Monitoring Guide - Statistics and capacity monitoring
• Troubleshooting Guide - Common issues and diagnostics