Defining the Common SBA Gateway Configuration
The common SBA Gateway configuration, provided by the SBA library, defines a default configuration that is shared by every network function.
The gateway.yaml file defines SBA Gateway common configuration. You can override the common configuration using environment variables or by editing the configuration in the nf.yaml file for the network function.
Note: In the nf.yaml file, only supply the properties explicitly changed
from defaults for your deployment.
The following gateway.yaml file shows the common default configuration for the SBA Gateway:
# Settings Related to the SBA Gateway on which a Network Function runs
gateway:
# Interface on which to listen for incoming connections
host: 0.0.0.0
# Unencrypted HTTP port (set to 0 to disable)
port: 9098
# Specify the external URL to access this network function. May be used by network functions to publish the external URI.
externalUri: http://localhost:9098
# Port used for common "operations" (Health check, ready check, metrics)
operationsPort: 9097
# Network function instance id (UUID). Used if registering with an NRF.
nfInstanceId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
# Network function type (e.g. CHF)
nfType: CUSTOM_MATRIXX_SBA_BASE
# If http2PriorKnowledge is false:
#
# HTTP/2.0 and HTTP/1.1 are both supported for TLS connections (ALPN is used to
# upgrade to HTTP/2.0). HTTP/1.1 will be used for non-TLS connections.
#
# If http2PriorKnowledge is true, HTTP/2.0 will used for TLS and non-TLS
# connections. ALPN will not be used so HTTP/1.1 downgrade will not be supported.
http2PriorKnowledge: true
# Initial Http2Settings used by the web client.
# Every connection will use these settings by default
# This and the fields under it are each optional
http2Settings:
headerTableSize: 4096
pushEnabled: true
maxConcurrentStreams: 100
initialWindowSize: 65535
maxFrameSize: 16384
maxHeaderListSize: 8192
# TTL for cached DNS lookups (set to 0 for no TTL)
addressResolverCacheTTLSeconds: 300
security:
# HTTP Basic Authentication Settings
basicAuth:
enabled: false
username: username
password: password
# Transport Layer Security (TLS) i.e. HTTP / SSL
tls:
enabled: false
# Interface on which to listen for incoming secure connections
host: 0.0.0.0
# Secure port
port: 9099
# Defines if we will be loading a cert or java key store for https
securityType: keyStore
# Key store containing signed Network Function certificate.
# NOTE: SBA will look for this path on the filesystem first. If it is not found it will search the classpath.
keystore:
type: JKS
path: /opt/mtx/conf/keystore/keystore.jks
password: password
# Trust store containing Root Certificate.
truststore:
type: JKS
path: /opt/mtx/conf/keystore/truststore.jks
password: password
# Key store containing signed Network Function certificate.
# NOTE: SBA will look for this path on the filesystem second. If it is not found it will search the classpath.
cert:
certPath: /opt/mtx/conf/keystore/cert.crt
keyPath: /opt/mtx/conf/keystore/cert.key
trustcert:
certPath: /opt/mtx/conf/keystore/trustcert.crt
keyPath: /opt/mtx/conf/keystore/trustcert.key
# Is TLS Mutual Auth Authentication enabled
# Is TLS Mutual Auth Authentication enabled
mutualAuth:
enabled: true
# Should all TLS certificates be trusted? (insecure - for testing only)
insecure: false
# OAuth
oauth:
enabled: false
# HMAC/RSA - Use a pre-shared secret or public/private key pair
jwtSigningKeyType: HMAC
hmac:
key: secret_that_must_be_at_least_32_bytes_long
type: PLAIN # plain/base64
# NOTE: SBA will look for this path on the filesystem first. If it is not found it will search the classpath.
keystore:
type: JKS
path: /opt/mtx/conf/keystore/truststore.jks
password: password
nrfCertAlias: nrf
# Which RDN field in the certificate subject to match against
# the issuer of an access token (CommonName by default)
nrfCertSubjectMatch: CN
certificate:
keyPath: /opt/mtx/conf/keystore/cert.key
nrfCertAlias: nrf
algorithm: RSA
# Groovy Settings
groovy:
# The directory in which Groovy Network Function files can be found
nf:
directory: /opt/mtx/lib/groovy
# Message Specification Settings
specifications:
version: R15-2019-12
directory: /opt/mtx/conf/specs
# The MDC types to load
mdc:
rootNames: Mtx5GMsg
# Message Mapper Settings
mapping:
directory: /opt/mtx/conf/mappings
trace: false
# Monitoring-related settings
monitoring:
# Enable the /metrics URL and publish prometheus metrics
prometheus:
enabled: true
applicationName: sba-5gc-gateway
# Distributed Tracing settings
tracing:
openTelemetry:
enabled: true
# The tracing policy. Can be NONE, PROPAGATE or ALWAYS. See https://vertx.io/docs/apidocs/io/vertx/core/tracing/TracingPolicy.html
policy: PROPAGATE
# The url of an endpoint that can accept OpenTelemetry tracing i.e. An OpenTelemetry Collector
endpointUrl: http://localhost:4317
serviceName: chf
# Kafka settings
external:
kafka:
# determines whether records are sent to Kafka
enabled: false
# use the logger kafka producer, only current option
kafkaClientType: LOGGER
# Apache Kafka producer config settings
config: {}
# default pending queue size before bypassing Kafka
# when '0' then disabled
writeQueueMaxSize: 0
logger:
enabled: false # failed records from CHF are NOT logged
# default write-to-disk grace period
shutdownLoggingGraceSeconds: 5
# default logger name as defined in log4j2.xml
loggerName: networkcdr
metrics:
enabled: true
uriPatterns:
- "/nchf-convergedcharging/v2/chargingdata/([^/]+)/update"
- "/nchf-convergedcharging/v2/chargingdata/([^/]+)/release"
# Settings related to debug
# (more debug-related options available in log4j2.xml)
debug:
# Apply JSON pretty-printing to the HTTP body for Debug output
jsonPrettyPrintHttpBody: true
httpClient:
# Max total outstanding requests
maxQueuedRequests: 1000
# Max outstanding requests per host
maxQueuedRequestsPerHost: 100
# timeout
timeout: 60
timeouts:
# The idle timeout in milliseconds after which the channel will be closed.
# (zero is unlimited)
idleTimeout: 0
# The maximum allowed time of reading HTTP request in milliseconds.
# (-1 to disable)
requestParseTimeout: -1
# The amount of time the connection can be idle with no current requests before it is closed
# (-1 to disable)
noRequestTimeout: 60000
throttling:
# Max rate (requests per time interval) allowed from each consumer (by source IP). Requests exceeding this rate will
# be responded to with a 429 Too Many Requests.
maxRatePerConsumer: 0
# Max total rate (requests per time interval).
maxRate: 0
# Time interval used for maxRate calculations (milliseconds)
timeIntervalMillis: 1000
# List of URLs that should be excluded from maxRate calculations
maxRateUrlWhiteList:
- "/healthcheck"
- "/readycheck"
- "/version"
# Definition of Application Errors and the fields that make up the ProblemDetails message that will be returned
errors:
# The HTTP request contains an unsupported API name or API version in the URI.
INVALID_API:
type: "/errors/invalid-api"
title: "Unsupported API name/version"
status: 400 #BadRequest
# The HTTP request contains an unsupported query parameter in the URI.
INVALID_MSG_FORMAT:
type: "/errors/invalid-msg-format"
title: "HTTP Request has an invalid format"
status: 400 #BadRequest
# The HTTP request contains an unsupported query parameter in the URI.
INVALID_QUERY_PARAM:
type: "/errors/invalid-query-param"
title: "Unsupported query parameter in the URI"
status: 400 #BadRequest
# A mandatory query parameter, or a conditional query parameter but mandatory required, for an HTTP method was received in the URI with semantically incorrect value.
MANDATORY_QUERY_PARAM_INCORRECT:
type: "/errors/mandatory-query-param-incorrect"
title: "A mandatory query parameter in the URI received with a semantically incorrect value"
status: 400 #BadRequest
# An optional query parameter for an HTTP method was received in the URI with a semantically incorrect value that prevents successful processing of the service request.
OPTIONAL_QUERY_PARAM_INCORRECT:
type: "/errors/optional-query-param-incorrect"
title: "An optional query parameter in the URI received with a semantically incorrect value"
status: 400 #BadRequest
# Query parameter which is defined as mandatory, or as conditional but mandatory required, for an HTTP method is not included in the URI of the request.
MANDATORY_QUERY_PARAM_MISSING:
type: "/errors/mandatory-query-param-missing"
title: "An mandatory query parameter in the URI was missing"
status: 400 #BadRequest
# A mandatory IE or conditional IE in data structure, but mandatory required, for an HTTP method was received with a semantically incorrect value.
MANDATORY_IE_INCORRECT:
type: "/errors/mandatory-ie-incorrect"
title: "A mandatory IE for an HTTP method was received with a semantically incorrect value"
status: 400 #BadRequest
# An optional IE in data structure for an HTTP method was received with a semantically incorrect value that prevents successful processing of the service request.
OPTIONAL_IE_INCORRECT:
type: "/errors/optional-ie-incorrect"
title: "An optional IE for an HTTP method was received with a semantically incorrect value"
status: 400 #BadRequest
# IE which is defined as mandatory or as conditional in data structure, but mandatory required, for an HTTP method is not included in the payload body of the request.
MANDATORY_IE_MISSING:
type: "/errors/mandatory-ie-missing"
title: "A mandatory IE is not included in the payload of the request"
status: 400 #BadRequest
# The request is rejected due to unspecified client error.
UNSPECIFIED_MSG_FAILURE:
type: "/errors/unspecified-msg-failure"
title: "Unspecified client error"
status: 400 #BadRequest
# The request is rejected because the contained modification instructions attempt to modify IE which is not allowed to be modified.
MODIFICATION_NOT_ALLOWED:
type: "/errors/modification-not-allowed"
title: "Attempt to modify IE which is not allowed to be modified"
status: 403 #Forbidden
# The request for modification or deletion of subscription is rejected because the subscription is not found in the NF.
SUBSCRIPTION_NOT_FOUND:
type: "/errors/subscription-not-found"
title: "Subscription not found in the NF"
status: 404 #NotFound
# The request is rejected because a fixed part after the first variable part of an "apiSpecificResourceUriPart" (as defined in subclause 4.4.1 of 3GPP TS 29.501 [5]) is not found in the NF.
# This fixed part of the URI may represent a sub-resource collection (e.g. contexts, subscriptions, policies) or a custom operation.
RESOURCE_URI_STRUCTURE_NOT_FOUND:
type: "/errors/resource-uri-structure-not-found"
title: "A fixed part after the first variable part of the URI is not found"
status: 404 #NotFound
# The request is rejected due to incorrect value of a Content-length header field.
INCORRECT_LENGTH:
type: "/errors/incorrect-length"
title: "Incorrect content-length header field"
status: 411 #LengthRequired
# The request is rejected due to excessive traffic which, if continued over time, may lead to (or may increase) an overload situation.
NF_CONGESTION_RISK:
type: "/errors/nf-congestion-risk"
title: "Excessive traffic, possible overload"
status: 429 #TooManyRequests
httpHeaders:
Retry-After: 10
# The request is rejected due to insufficient resources.
INSUFFICIENT_RESOURCES:
type: "/errors/insufficient-resources"
title: "Insufficient resources"
status: 500 #InternalError
httpHeaders:
Retry-After: 10
# The request is rejected due to unspecified reason at the NF.
UNSPECIFIED_NF_FAILURE:
type: "/errors/unspecified-nf-failure"
title: "Unspecified NF failure"
status: 500 #InternalError
# The request is rejected due to generic error condition in the NF.
SYSTEM_FAILURE:
type: "/errors/system-failure"
title: "Generic error condition in NF"
status: 500 #InternalError
# The NF experiences congestion and performs overload control, which does not allow the request to be processed.
NF_CONGESTION:
type: "/errors/nf-congestion"
title: "Congestion, performing overload control"
status: 503 #Unavailable
httpHeaders:
Retry-After: 10
# The Service is currently unavailable
SERVICE_UNAVAILABLE:
type: "/errors/unavailable"
title: "Service Unavailable"
status: 503 #Unavailable
httpHeaders:
Retry-After: 10
# Configuration for returning an HTTP 307 with an alternative CHF specified in the Location Header.
# This is triggered on outage related errors by default
redirectOnError:
enabled: false
locationHeaderTemplate: https://alternative-chf${originalPath}
errors:
- SERVICE_UNAVAILABLE
- NF_CONGESTION
- INSUFFICIENT_RESOURCES
- NF_CONGESTION_RISK
# AMQP (Apache Active MQ) Settings
jms:
enabled: false
# Settings Related to the Matrixx Engine
engine:
# Is the functionality to connect to the Engine enabled?
enabled: false
# Add ttl configuration values
# To enable set to true
# Grace period for service call
# Will use the engine.requestTimeout with engine.ttl.gracePeriod to define aggregate timeout
ttl:
enabled: true
gracePeriod: 2000
# Delay (milliseconds) between retries to download MDC definitions
loadMdcRetryDelayMillis: 5000
# Optionally disable loading the MDCs from the engine
loadMdcFromEngine: true
# MDC Schema and Extension Version. Leave as 0 for the Engine to decide the level. Specify a value when 'version pinning' during upgrade
mdc:
schemaVersion: 0
extensionVersion: 0
# Retry requests to the engine if an error occurs (e.g. a connection failure)
requestRetry:
# Retry requests
enabled: true
# Max number of retries before responding with an error. Set to 0 for unlimited retries.
# Note: If a connection failure occurs, connections in the pool may not be detected as broken
# until a request is attempted. So this value should be greater than poolsize.
maxRetries: 32
# Interval in milliseconds between retry attempts.
interval: 100
# Engine connection details.
# A "connection" is in fact a pool of TCP connections to a host/port.
#
# Depending on the environment, SBA can connect to:
# * MDC Gateway
# * TRA-LB
# * TRA-RT
# * Gateway Proxy
connection:
# Hostname of one of the above endpoints (e.g. TRA-RT)
# Note: This will be ignored if hosts are specified in the connection.connections section.
host: localhost
# Port to connect to
port: 14060
# Authenticated port (of Gateway Proxy). If connecting via the Authenticated port of
# Gateway Proxy, set Port to the same value as this.
authPort: 14080
# Timeout when creating a connection
connectTimeout: 10000
# Timeout duration each request
requestTimeout: 5000
# Send a ping at this interval (in seconds). Set to zero to disable.
pingInterval: 10
# Max number of successive failed Ping messages before reconnecting
maxPingFailures: 2
# The value of the TrafficRouteData field of the MtxRequestSysQueryDomain message used to ping a connection.
# By default this is set to RTID0 which will route to any available subdomain. In multi-domain deployments
# this may need to be changed to specify a particular subdomain (in 523x) as RTIDx, or domain id (524x onward) as
# DMIDnn. In 524x, the Helm Chart will configure this automatically if a Domain is specified.
pingRouteId: RTID0 # If connecting via the Authenticated port of Gateway Proxy, create login credentials in Gateway Proxy
# for SBA Gateway and specify those credentials here.
credentials:
username: sba_username
password: sba_password
apiKey: sba_apiKey
# Connect to multiple hosts. For each (pool of) connections, a host must be specified.
# The default values for each connection pool will be taken from the connection configuration
# section above. Each value can be overridden per connection pool.
# e.g:
# connections:
# siteA:
# host: sitea.example.com
# siteB:
# host: siteb.example.com
# port: 99999
#
# NOTE: For Kubernetes deployments, a single connection will be routed via a Service, which will provide load balancing
# and failover to multiple TRA-RT instances. This configuration option is more likely required for hybrid deployments
# where the TRA-RT is not inside the Kubernetes cluster.
connections: []
# Failover mode when multiple connections are defined.
# ACTIVE_STANDBY (default): Use the first connection in the list of connections unless it fails. On failure,
# use the next in the list and so-on.
# ACTIVE_ACTIVE: Balance
# Note: If pingInterval is defined, the ping message will be used to determine if a connection pool is available again.
# If pingInterval is set to zero, incoming requests will try to use a pool even if it has previously failed.
failoverMode: "ACTIVE_STANDBY"
# Global variables. These can be used in NRF registration/hearbeating.
# Each variable must have a unique name and can be referenced
# in the NRF configuration section.
variables:
# Define static variables here with a value.
static:
- name: example
value: 1.0
# Define variables that will be populated by querying a REST API here.
# The REST API is assumed to return a JSON payload.
restApi:
-
enabled: false
# Polling interval in seconds (minimum 1)
pollingInterval: 10
# URL to query
# (Example PromQL query to get the CPU usage as a percentage)
url: http://localhost:9090/api/v1/query?query=ceil(100 - (avg (irate(node_cpu_seconds_total{job="node",mode="idle"}[5m])) * 100))
# HTTP method to use
method: GET
# Optional path to a file containing a body (e.g. for POST requests).
# body: /opt/mtx/conf/loadQuery.json
# Optional additional headers to send in the query (e.g. for HTTP BASIC authentication)
# headers:
# Authorization: Basic <credentials>
# Values are read from the JSON response of a REST API query.
# Paths to the values are defined using jsonPath syntax.
values:
- name: load
# default value to use if value not present or error occurs
value: 1
# Path to the value in the JSON response
jsonPath: $.data.result[0].value[1]
# Convert the value received in the JSON to a different data type.
# Allowed values: STRING, NUMBER, BOOLEAN, DECIMAL
convertToType: NUMBER
# Settings related to the NRF
nrf:
# Should we register with an NRF?
registerWithNrf: false
# If registerWithNrf is true and leaderSidecar is enabled,
# the SBA will poll this URL to see if it is the leader.
# If it is the leader it will register/heartbeat.
leaderSidecar:
enabled: false
url: http://localhost:8080/leader
# How long to wait before the first request
delayMillis: 5000
# Interval between requests
pollingIntervalMillis: 10000
# Register with the following NRFs
# Note: Alternatively there is an "nrfs" configuration option
# if different configuration is required per-nrf.
# e.g:
# nrfUris:
# - https://nrf1:9099
# - https://nrf2:9099
nrfUris: []
# Register with the following NRFs and override configuration per NRF.
# For each NRF, the default configuration from the nrf section will be used unless overridden here.
#
# For example, to register with nrf1 and nrf2 using the default configuration, but nrf3
# with a different accessTokenRequest and nfProfile:
# nrfs:
# nrf1:
# uri: https://nrf1:9099
# nrf2:
# uri: https://nrf2:9099
# nrf3:
# uri: https://nrf3:9099
# nfProfile: /opt/mtx/conf/nfProfile.yaml
# accessTokenRequest: /opt/mtx/conf/nrfAccessTokenRequest2.yaml
nrfs: []
# How to handle NRF registration and failure:
# ACTIVE_ACTIVE (default): Register with all NRFs and re-try registering if a failure occurs.
# ACTIVE_STANDBY: Register with the first NRF in the list, and fail over to the next if a failure occurs.
mode: "ACTIVE_ACTIVE"
# Switch back to the original NRF client (Deprecated - will be removed in a future version)
useOldNrfClient: false
# Contents of this file will be sent on registration
nfProfile: /opt/mtx/conf/nfProfile.yaml
# Should we request an OAuth access token from the NRF before registration?
requestAccessTokenBeforeRegistration: true
# If we do request an access token, send this request
accessTokenRequest: /opt/mtx/conf/nrfAccessTokenRequest.yaml
# Payload to send in the Heartbeat message
heartbeatPayload: /opt/mtx/conf/nrfHeartbeatPayload.yaml
# For testing - send the first heartbeat immediately
heartbeatNoDelay: false
# Time to wait (seconds) between retrying NRF registration in the case of failure for ACTIVE_ACTIVE
# or failing-over to another NRF for ACTIVE_STANDBY
retryDelay: 10
# By default, if the NRF returns a Location header in the response to registration, the URL in the
# Location header will be used for all subsequent requests (e.g. Heartbeats). Set this value to false
# to ignore the Location header and just use the configured NRF URI.
useLocationHeader: true
# Default heartbeat interval (seconds). Note - this is a last-resort setting,
# please specify the desired heartBeatTimer in nfProfile.yaml. This will be
# negotiated with the NRF during registration. Only set this if nothing else works.
heartBeatTimerDefault: 0
# Before sending a registration/heartbeat, set the nfProfile field specified in the
# field parameter to the value of the variable from the "variables" config section. The jsonPath
# parameter defines the path to the field (with $ being the root).
registrationVariables: []
# -
# # Set the "load" field to the value of the variable "load"
# jsonPath: $
# field: load
# variable: load
heartbeatVariables: []
# -
# # Set the "value" field in the object with a path equal to '/load' to the value of the variable "load"
# jsonPath: $[?(@.path == '/load')]
# field: value
# variable: load
# Settings relating to the SCP (Service Communication Proxy)
scp:
# Is SCP Support Enabled?
enabled: false
# The URL of the SCP
url: ""
# HTTP Headers to set in the Response (if not already set in the mapping)
responseHeaders:
3gpp-Sbi-Binding: "bl=nf-instance; nfinst=${gateway.nfInstanceId}"
# HTTP Headers to set in the Notify Request (if not already set in the mapping)
notifyRequestHeaders:
3gpp-Sbi-Routing-Binding: "bl=nf-instance; nfinst=${gateway.nfInstanceId}"
# Settings relating to Backstop Processing
backstop:
enabled: false
# What HTTP Status Codes should trigger the Backstop Processing
triggeringStatusCode:
- 0 # Timeout
- 503 # Unavailable
- 500 # Server Error
- 404 # Not Found
# The amount of time (seconds) to wait until marking the NF as ready regardless of the downstream system being ready
secondsUntilReady: 10
scaling:
# Settings related to scaling the number of instances per verticle
# method:
# auto -> scale automatically based on available CPUs and scaling factor, instances will be ignored
# manual -> specify number of instances manually, factor will be ignored
# singleton -> override all instances to 1, both instances and factor will be ignored
# Instances:
# Cardinal number of instances to be deployed.
# Factor:
# A scaling factor with the following formula:
# Available core / factor
# Example - 1 means use all available CPUs, 2 means use half of available CPUs etc.
method: auto
components:
# HTTP server
http:
instances: 4
factor: 1
# Notify client
notify:
instances: 1
factor: 8
# Event Stream client
events:
instances: 2
factor: 2
# Kafka event client
kafka:
instances: 2
factor: 2
# CHF AMQP consumer
amqp:
instances: 1
factor: 8
# Settings for Notification Alarm
# Log a warning for notification when http status code is matched
notificationAlarm:
# HTTP Status Codes that trigger notification alarm
errorHttpResponseCodes:
- 400 #Bad Request
- 401 #Unauthorized
- 403 #Forbidden
- 404 #Not Found
- 411 #Length Required
- 413 #Payload Too Large
- 429 #Too Many Requests
- 500 #Internal Server Error
- 503 #Service UnavailableThe loadMdcRetryDelayMillis and initRetryDelayMillis properties reduce the MATRIXX Data Container (MDC) download rate
and JMS setup retries, preventing a failure loop at start-up when the Traffic Routing Agent (TRA) or ActiveMQ Gateway are also started. Reduce the delay values to speed up start up in resource-constrained environments, such as
test environments, to retry the MDC download or ActiveMQ Gateway connection more often.
The pingRouteId property default value of RTID0 routes to any available sub-domain. This property is set to other values based on the
global.topology.domains[x].id property specified in the MATRIXX Helm values file. For more information see the discussion about domain, sub-domain, and
engine topology in MATRIXX Configuration.