F5SipSetting

The F5SipSetting Custom Resource (CR) defines a Session Initiation Protocol (SIP) profile for managing SIP traffic through F5 BIG-IP. A SIP setting controls how the system handles SIP sessions, routes messages, detects loops, and connects to upstream peers.

Use the F5SipSetting CR to:

• Configure SIP session persistence, including the persistence key and timeout.

• Control SIP message handling options such as Via header insertion, passthrough mode, and maintenance mode.

• Define loop detection behavior to prevent SIP request routing cycles.

• Set message size and header limits for SIP traffic validation.

• Configure routing headers, including Record-Route and Route header handling.

• Define the SIP router, including pending message limits, retry behavior, and transaction timeouts.

• Create static SIP routes that map URI patterns to upstream peers with transport and Source Network Address Translation (SNAT) configuration.

• Enable the SIP firewall to protect against malicious or invalid requests.

Note

When you enable loop detection (loopDetection.enabled: true), you must also set insertViaHeader: true in the session configuration. The CR validation rejects configurations where loop detection is enabled without Via header insertion.

CR parameters

The sections and list of parameters to define the F5SipSetting CR.

metadata

Parameter	Description
name	The unique identifier for this SIP setting. The name must be a valid Kubernetes resource name within the k8s.f5net.com API group.
namespace	The Kubernetes namespace in which the SIP setting is installed.

spec.session

SIP session profile configuration, including persistence mode and connection handling options.

Parameter	Type	Required	Default	Description
persistType	string	Yes	—	SIP persistence mode for tracking subscriber sessions across connections. Accepted values: Session, None.
persistKey	string	Yes	—	Key used to identify and group related SIP messages. Accepted values: Call-ID, Custom, Src-Addr.
persistTimeout	integer	No	3600	Timeout in seconds before SIP persistence entries expire. Range: 0–4294967295.
honorVia	boolean	No	true	When set to true, inserts and honors the Via header field for SIP response routing.
allowUnknownMethods	boolean	No	false	When set to true, allows SIP requests with unknown or unrecognized method types to be processed.
customVia	string	No	""	Custom Sent-By value used in the Via header when insertViaHeader is enabled. The format must include SIP/SIP-version/protocol followed by a Sent-By value. For example: SIP/2.0/TCP www.siterequest.com:4343 or SIP/2.0/SCTP 10.10.4.32. Maximum 255 characters.
doNotConnectBack	boolean	No	false	When set to true, prevents the system from establishing connections back to the originating client.
generateResponseOnFailure	boolean	No	false	When set to true, generates error responses when SIP request processing fails or times out.
insertViaHeader	boolean	No	false	When set to true, inserts a Via header field into SIP requests for tracking purposes. Must be true when loopDetection.enabled is true.
maintenanceMode	boolean	No	false	When set to true, places the SIP handling configuration in maintenance mode for system updates.
passthruMode	boolean	No	false	When set to true, SIP messages pass through the system without modification or processing.
maxForwardsCheck	boolean	No	false	When set to true, validates and enforces the maximum hops limit in SIP message forwarding.
maxMsgHeaderCount	integer	No	64	Maximum number of header fields allowed in a single SIP message. Range: 0–4294967295.
maxMsgHeaderSize	integer	No	16000	Maximum size in bytes for SIP message headers before the system rejects the message. Range: 0–4294967295.
maxMsgSize	integer	No	65535	Maximum size in bytes for a complete SIP message, including headers and body. Range: 0–4294967295.
servicePort	integer	No	5060	SIP service port number for listening to incoming SIP requests. Range: 0–65535.
enableSipFirewall	boolean	No	false	When set to true, activates the SIP firewall to protect against malicious and invalid requests. Enabling the SIP Firewall also requires configuring SIP DoS within a SIP DoS CR.

spec.session.loopDetection

SIP loop detection settings for managing request propagation cycles.

Parameter	Type	Required	Default	Description
enabled	boolean	No	false	When set to true, activates SIP loop detection and prevention. Requires insertViaHeader: true.
mode	string	No	Strict	Controls the hash calculation used for loop detection. Strict mode includes CSeq, To, From, Call-ID, Route, Request-URI, and chassis serial number. Loose mode skips the To attribute. Accepted values: Loose, Strict.

spec.session.routingHeaders

Configuration for handling SIP Route and Record-Route headers.

Parameter	Type	Required	Default	Description
insertRecordRouteHeaders	boolean	No	false	When set to true, the system inserts Record-Route headers in SIP requests.
recordRouteMode	string	No	Double	Controls how Record-Route headers are inserted. Single inserts one Record-Route header and rewrites it on response per RFC 3261. Double inserts two Record-Route headers per RFC 5658. Accepted values: Single, Double.
honorRouteHeaders	boolean	No	false	When set to true, the system routes messages based on the topmost Route header in SIP requests, unless persistence takes priority.
honorRouteMode	string	No	Loose	Determines how the system handles Record-Route and Route headers. Loose mode follows RFC 3261. Strict mode follows RFC 2543. Accepted values: Loose, Strict.

spec.router

SIP router configuration for managing message routing and session handling.

Parameter	Type	Required	Default	Description
operationMode	string	No	LoadBalancing	SIP router operation mode that determines how messages are routed and processed. Accepted values: LoadBalancing.
maxPendingMessages	integer	No	4096	Maximum number of SIP messages that can be queued while waiting for peer connections. Range: 1–1048576.
maxPendingBytes	integer	No	32768	Maximum bytes of SIP message data held pending while waiting for a peer connection. A value of 0 disables the limit. Range: 0–4294967295.
maxRetries	integer	No	1	Maximum number of times a SIP message can be resubmitted for rerouting. Range: 0–4294967295.
perPeerStats	boolean	No	false	When set to true, SIP statistics are captured per pool member.
useLocalConnection	boolean	No	true	When set to true, routes SIP messages to an existing connection on the same Traffic Management Microkernel (TMM) as the message arrival.
transactionTimeout	integer	No	0	Transaction timeout in seconds for SIP message processing and response handling. A value of 0 disables the timeout. Range: 0–4294967295.

spec.routes[]

A list of static SIP routes. Each route maps URI patterns to upstream peer configurations.

Parameter	Type	Required	Default	Description
requestUri	string	No	""	Request URI pattern for matching this route. If empty, the route matches all SIP requests. Maximum 255 characters.
fromUri	string	No	""	From URI pattern for matching this route. If empty, the route matches all sources. Maximum 255 characters.
toUri	string	No	""	To URI pattern for matching this route. If empty, the route matches all destinations. Maximum 255 characters.
virtualServer	string	No	""	Optional virtual server scope that limits routing to specific virtual servers. Maximum 255 characters.
peerSelectionMode	string	No	Sequential	Method for selecting a peer from the list. Sequential processes peers in order. Ratio distributes traffic by weight. Accepted values: Sequential, Ratio.

spec.routes[].peers[]

A list of upstream peers and their connection configuration for routing SIP messages. Each route must have at least one peer.

Parameter	Type	Required	Default	Description
connectionMode	string	Yes	PerClient	Controls how connections to this peer are managed. PerPeer uses a shared connection pool for the peer. PerClient creates connections per client. Accepted values: PerPeer, PerClient.
pool	string	Yes	—	Name of the pool this peer routes to for distributing traffic. Must be 1–63 characters and match the pattern ^[a-z0-9]([-a-z0-9]{0,251}[a-z0-9])?$.
ratio	integer	No	1	Load balancing weight for distributing traffic across multiple peers. Used when peerSelectionMode is Ratio. Range: 1–100.
numberConnections	integer	No	1	Number of connections between the system and the remote host. Range: 1–4294967295.
autoInitialization	boolean	No	false	When set to true, automatically establishes connections to pool members without waiting for requests.
autoInitializationIntervalMs	integer	No	5000	Time in milliseconds between auto-initialization connection attempts. Range: 500–65535.

spec.routes[].peers[].transportConfig

Transport layer configuration for managing peer connections and protocols.

Parameter	Type	Required	Default	Description
protocol	string	No	udp	Transport protocol for the peer connection. Accepted values: tcp, udp.
protocolProfile	string	Yes	—	Name of the protocol profile to use. Must be 1–255 characters and match the pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$.
iRules	array	No	[]	List of iRule names to apply for customizing transport behavior at the SIP protocol level. Each name must be 1–63 characters.
sourcePort	integer	No	0	Fixed source port for outbound connections. A value of 0 enables dynamic port selection. Range: 0–65535.
sourcePortMode	string	No	change	Controls how source ports are assigned to outbound connections. Accepted values: change, preserve, preserve-strict.

spec.routes[].peers[].transportConfig.snat

Source Network Address Translation (SNAT) configuration for managing peer connection source addresses.

Parameter	Type	Required	Default	Description
type	string	No	none	Type of source address translation to apply. none disables SNAT. automap uses the system's self IP addresses. snat uses a specified SNAT pool. Accepted values: none, automap, snat.
pool	string	No	""	Name of the SNAT pool. Required when type is snat. Must be empty when type is none or automap.

SNAT validation rules:

• When type is none, pool must be empty.

• When type is automap, pool must be empty.

• When type is snat, pool must specify a valid SNAT pool name.

CR shortName

The F5SipSetting CR shortName is sipset.

View CR instances:

oc get sipset -n <namespace>

View CR configuration:

oc get sipset -n <namespace> -o yaml

Prerequisites

Ensure you have:

• A running deployment with the CNF Controller Pods installed. For installation instructions, see Install F5 BIG-IP Cloud-Native Edition.

• Access to the Kubernetes control plane (for example, oc configured with credentials for the target cluster).

• One or more pools configured for routing SIP traffic to upstream peers.

• A protocol profile created for each peer transport configuration that requires one.

Installation

Use the following steps to install the F5SipSetting CR.

1. Create a YAML file for your SIP setting CR. The following examples show common configurations that you can adapt to match your environment.

   • Basic SIP setting with session persistence

     apiVersion: "k8s.f5net.com/v1"
     kind: F5SipSetting
     metadata:
       name: "sip-basic"
       namespace: "cnf-gateway"
     spec:
       session:
         persistType: "Session"
         persistKey: "Call-ID"
         persistTimeout: 3600
         servicePort: 5060
     

   • SIP setting with Via header insertion and loop detection

     apiVersion: "k8s.f5net.com/v1"
     kind: F5SipSetting
     metadata:
       name: "sip-loop-detect"
       namespace: "cnf-gateway"
     spec:
       session:
         persistType: "Session"
         persistKey: "Call-ID"
         insertViaHeader: true
         loopDetection:
           enabled: true
           mode: "Strict"
         maxForwardsCheck: true
     

   • SIP setting with static routes and peer configuration

     apiVersion: "k8s.f5net.com/v1"
     kind: F5SipSetting
     metadata:
       name: "sip-with-routes"
       namespace: "cnf-gateway"
     spec:
       session:
         persistType: "Session"
         persistKey: "Call-ID"
         servicePort: 5060
       router:
         operationMode: "LoadBalancing"
         maxPendingMessages: 4096
         maxRetries: 3
         transactionTimeout: 32
       routes:
         - requestUri: "sip:example.com"
           peerSelectionMode: "Sequential"
           peers:
             - connectionMode: "PerClient"
               pool: "sip-pool-01"
               transportConfig:
                 protocol: "udp"
                 protocolProfile: "sip-udp-profile"
     

   • SIP setting with SNAT automap and multiple peers using ratio selection

     apiVersion: "k8s.f5net.com/v1"
     kind: F5SipSetting
     metadata:
       name: "sip-ratio-routes"
       namespace: "cnf-gateway"
     spec:
       session:
         persistType: "Session"
         persistKey: "Src-Addr"
         servicePort: 5060
       routes:
         - requestUri: ""
           peerSelectionMode: "Ratio"
           peers:
             - connectionMode: "PerPeer"
               pool: "sip-pool-primary"
               ratio: 70
               numberConnections: 10
               autoInitialization: true
               autoInitializationIntervalMs: 3000
               transportConfig:
                 protocol: "tcp"
                 protocolProfile: "sip-tcp-profile"
                 snat:
                   type: "automap"
             - connectionMode: "PerPeer"
               pool: "sip-pool-secondary"
               ratio: 30
               transportConfig:
                 protocol: "tcp"
                 protocolProfile: "sip-tcp-profile"
                 snat:
                   type: "automap"
     

   • SIP setting with SIP firewall and Record-Route headers enabled

     apiVersion: "k8s.f5net.com/v1"
     kind: F5SipSetting
     metadata:
       name: "sip-firewall"
       namespace: "cnf-gateway"
     spec:
       session:
         persistType: "Session"
         persistKey: "Call-ID"
         insertViaHeader: true
         enableSipFirewall: true
         routingHeaders:
           insertRecordRouteHeaders: true
           recordRouteMode: "Double"
           honorRouteHeaders: true
           honorRouteMode: "Loose"
     

2. Edit the CR parameters to match your environment. You must set:

   • session.persistType — the persistence mode (Session or None).

   • session.persistKey — the persistence key (Call-ID, Custom, or Src-Addr).

   • For any static routes, each peer requires connectionMode, pool, and transportConfig.protocolProfile.

3. Apply the F5SipSetting CR:

   oc apply -f cnf-f5sipsetting-cr.yaml
   

4. Verify the SIP setting is installed:

   oc get f5sipsetting -n cnf-gateway -o yaml