[[configuration]] == Configuration OsmoS1GW is configured through an Erlang/OTP system configuration file. By default this file is `config/sys.config` in the source tree, or `/etc/osmocom/osmo-s1gw.config` after installation. A different path can be supplied at start time via the `-c` option of the `osmo-s1gw` bootstrap script (see <>) or via the `CONFIG` variable when using the project Makefile (see <>). The file uses Erlang term syntax. The top level is a list of `{ApplicationName, [{Key, Value}, ...]}` tuples. OsmoS1GW-specific parameters live under the `osmo_s1gw` application key. Kernel parameters (logging) live under the standard `kernel` key, and metrics reporting parameters under the `exometer_core` key. [[config_sctp_server]] === `sctp_server` — eNB-Facing SCTP Listener This section controls the SCTP socket on which OsmoS1GW listens for incoming connections from eNodeBs. ---- {sctp_server, #{ laddr => "127.0.1.1", %% local bind address lport => 36412, %% local bind port (S1AP standard port) sockopts => #{ } %% optional socket options (see below) }} ---- `laddr`:: IP address to bind to. Accepts a string in dotted-decimal (IPv4) or colon-separated (IPv6) notation, or the atom `any` to bind to all interfaces. Default: `"127.0.1.1"`. `lport`:: TCP/SCTP port to listen on. Default: `36412` (the IANA-assigned S1AP port). `sockopts`:: An optional map of additional SCTP socket options: + [options="header",cols="20,60,20"] |=== | Option | Description | Default | `recbuf` | Receive buffer size in bytes | `65536` | `sndbuf` | Send buffer size in bytes | `65536` | `nodelay` | Disable Nagle algorithm (`true` to disable) | `true` |=== [[config_mme_pool]] === `mme_pool` — MME Pool Configuration The `mme_pool` key defines the list of MMEs that OsmoS1GW may connect to on behalf of connecting eNBs. This is the recommended way to configure MME connectivity; it supports multiple MMEs and TAC-based selection. ---- {mme_pool, [ #{ name => "mme0", %% unique name (required) raddr => "192.168.2.10", %% MME IP address (required) rport => 36412, %% MME SCTP port (default: 36412) laddr => any, %% local bind address (default: any) tac_list => [] %% allowed TACs (default: [] = all) }, #{ name => "mme1", raddr => "192.168.2.20", tac_list => [100, 101, 102] } ]} ---- Each entry in the list is a map with the following fields: `name`:: A unique, human-readable string identifying this MME in log messages, the REST API, and per-MME metrics. Required. `raddr`:: The remote IP address of the MME. Required. `rport`:: The remote SCTP port of the MME. Default: `36412`. `laddr`:: The local IP address to bind to when connecting to this MME. Accepts a string or the atom `any`. Default: `any`. `tac_list`:: A list of Tracking Area Codes (TACs) that this MME is willing to serve. When an eNB connects and sends its S1 Setup Request, OsmoS1GW filters the pool to MMEs whose `tac_list` is a superset of the eNB's advertised TACs. An empty list means the MME accepts all TACs. Default: `[]`. MMEs can also be added and removed at run time via the REST API without restarting OsmoS1GW (see <>). NOTE: The `mme_pool` key is mutually exclusive with the deprecated `sctp_client` key described in the next section. If `mme_pool` is present, keys `laddr`, `raddr`, and `rport` from the `sctp_client` block are ignored. [[config_sctp_client]] === `sctp_client` — Single MME (Deprecated) Prior to the introduction of MME pooling, the outbound MME connection was configured via the `sctp_client` section: ---- {sctp_client, #{ laddr => "127.0.2.1", %% local bind address raddr => "127.0.2.10", %% MME IP address rport => 36412, %% MME SCTP port sockopts => #{ } %% optional socket options (same as sctp_server) }} ---- When OsmoS1GW starts and finds no `mme_pool` key in the configuration, it automatically creates a single `"default"` MME pool entry from the `sctp_client` parameters and logs a deprecation warning. This allows existing single-MME deployments to continue working without changes, but migration to `mme_pool` is strongly recommended. NOTE: The socket options (`sockopts`) from the `sctp_client` section are still used for the outbound SCTP socket regardless of whether `mme_pool` or `sctp_client` is used for MME addressing. [[config_pfcp]] === PFCP — User Plane Function These parameters control the PFCP session between OsmoS1GW and the UPF. ---- {pfcp_peer, #{ laddr => "127.0.1.1", %% local address for PFCP (UDP) raddr => "127.0.1.2" %% remote address of the UPF %% assoc_setup_timeout => 2000, %% optional, milliseconds %% heartbeat_req_timeout => 2000, %% optional, milliseconds %% heartbeat_interval => 0 %% optional, milliseconds (0 = disabled) }}, %% Optional Network Instance IEs: %% {pfcp_net_inst_core, "core-side"}, %% {pfcp_net_inst_access, "radio-side"} ---- `laddr`:: Local IP address on which OsmoS1GW listens for PFCP messages from the UPF. Default: `"127.0.1.1"`. `raddr`:: Remote IP address of the UPF. Default: `"127.0.1.2"`. `assoc_setup_timeout`:: How long (in milliseconds) to wait for a PFCP Association Setup Response before retrying. Default: `2000`. `heartbeat_req_timeout`:: How long (in milliseconds) to wait for a PFCP Heartbeat Response before declaring the heartbeat timed out. Default: `2000`. `heartbeat_interval`:: Interval (in milliseconds) between periodic PFCP Heartbeat Requests sent by OsmoS1GW while associated with the UPF. Set to `0` to disable periodic heartbeats entirely. Default: `10000`. NOTE: The legacy flat keys `pfcp_loc_addr` and `pfcp_rem_addr` are still accepted for backwards compatibility. The `pfcp_peer` map takes priority if both are present. `pfcp_net_inst_core`:: Value for the PFCP Network Instance IE on the core-network side of each GTP-U session. Omit if the UPF does not require Network Instance IEs. `pfcp_net_inst_access`:: Value for the PFCP Network Instance IE on the radio-access side of each GTP-U session. Omit if the UPF does not require Network Instance IEs. [[config_gtpu_kpi]] === GTP-U KPI Reporting (Optional) OsmoS1GW can optionally poll nftables counters to derive per-eNB GTP-U traffic statistics and report them as exometer metrics (see <>). This feature requires a matching nftables ruleset. ---- %% {gtpu_kpi_enable, true}, %% {gtpu_kpi_table_name, "osmo-s1gw"}, %% {gtpu_kpi_ul_addr, s1ap}, %% {gtpu_kpi_dl_addr, s1ap}, %% {gtpu_kpi_interval, 3000} ---- `gtpu_kpi_enable`:: Set to `true` to enable the GTP-U KPI module. Default: `false`. `gtpu_kpi_table_name`:: The nftables table name to read counters from. Default: `"osmo-s1gw"`. `gtpu_kpi_ul_addr`:: Source of the uplink GTP-U address used to match nftables counters. `s1ap` means learn the address from S1AP signalling; `sctp` means use the eNB's SCTP source address. Default: `s1ap`. `gtpu_kpi_dl_addr`:: Source of the downlink GTP-U address. Same options as `gtpu_kpi_ul_addr`. Default: `s1ap`. `gtpu_kpi_interval`:: How often (in milliseconds) to poll the nftables counters. Default: `3000`. [[config_rest]] === REST Interface ---- %% {rest_srv_port, 8080}, %% {rest_srv_swagger_ui, true} ---- `rest_srv_port`:: TCP port on which the HTTP REST server listens. Default: `8080`. `rest_srv_swagger_ui`:: Whether to serve the Swagger UI at `http://host:rest_srv_port/swagger`. Default: `true`. For the full REST API reference see <>. For the interactive CLI tool that wraps the REST API see <>. [[config_kernel]] === `kernel` — Logging OsmoS1GW uses the standard Erlang/OTP `logger` framework. The `kernel` application section controls log levels and handlers. See <> for a description of the log handlers configured by default. ---- {kernel, [ {logger_level, debug}, {logger, [ {handler, gsmtap, logger_gsmtap_h, #{level => debug, config => #{rem_addr => "127.0.0.1", app_name => "OsmoS1GW"}}}, {handler, default, logger_std_h, #{level => info, formatter => {logger_color_formatter, #{...}}}} ]} ]} ---- `logger_level`:: The global minimum log level. Log records below this level are discarded before reaching any handler. Common values: `debug`, `info`, `notice`, `warning`, `error`. For each handler in the `logger` list: `level`:: Handler-specific minimum log level. Can be set independently per handler to, for example, send only `warning` and above to the console while sending all `debug` output over GSMTAP. `gsmtap` handler (`logger_gsmtap_h`):: Sends log messages as GSMTAP frames over UDP. + `rem_addr`::: Destination IP address. Default: `"127.0.0.1"`. `app_name`::: Application name tag embedded in each GSMTAP frame. `default` handler (`logger_std_h`):: Writes log lines to standard output. When OsmoS1GW runs under systemd this output is captured by the journal. [[config_exometer]] === `exometer_core` — Metrics and StatsD Reporting See <> for an introduction to OsmoS1GW metrics and the full list of available counters and gauges. The `exometer_core` section configures reporters — processes that periodically push metric values to an external destination. The default configuration reports all counters and gauges to a StatsD server: ---- {exometer_core, [ {report, [ {reporters, [ {exometer_report_statsd, [ {hostname, "127.0.4.10"}, {port, 8125}, {prefix, "s1gw"}, {type_map, []} ]} ]}, {subscribers, [ {select, {[{ {['_'|'_'], counter, '_'}, [], ['$_']}], exometer_report_statsd, value, 10_000, true, [{report_type, counter}]}}, {select, {[{ {['_'|'_'], gauge, '_'}, [], ['$_']}], exometer_report_statsd, value, 10_000, true, [{report_type, gauge}]}} ]} ]} ]} ---- `hostname`:: IP address or hostname of the StatsD server. `port`:: UDP port of the StatsD server. Default: `8125`. `prefix`:: String prepended to all metric names as reported to StatsD. Default: `"s1gw"`. The `subscribers` list uses exometer's `select` mechanism to automatically subscribe all counters and gauges to the StatsD reporter with a reporting interval of 10 000 ms. To disable StatsD reporting, comment out or remove the `exometer_report_statsd` reporter entry. // vim:set ts=4 sw=4 et: