[[overview]]
== Overview

[[about]]
=== About OsmoS1GW

OsmoS1GW is an S1 Gateway for LTE (4G) networks, developed by
https://www.sysmocom.de/[sysmocom].  It acts as a transparent proxy
between eNBs (radio access network) and one or more MMEs (core network),
relaying S1AP signalling over SCTP/IP in both directions.

In addition to S1AP proxying, OsmoS1GW manages GTP-U data plane tunnels
(E-RABs / EPS bearers) by communicating with a co-located UPF (User
Plane Function) via PFCP.  OsmoS1GW does not carry GTP-U traffic itself:
GTP-U flows directly between the eNB and the UPF (access side), and
between the UPF and the S-GW of the core network (core side).  OsmoS1GW
only instructs the UPF — via PFCP Session Establishment, Modification,
and Deletion procedures — to create, update, or tear down the
corresponding forwarding rules.  It also rewrites the GTP-U TEID and
Transport Layer Address (TLA) IEs inside S1AP messages so that eNBs send
their GTP-U traffic to the co-located UPF rather than directly to
the core network.

[[architecture]]
=== Architecture

The following diagram shows the high-level data flow through OsmoS1GW:

[graphviz]
----
digraph overview {
    rankdir=LR;
    node [shape=box];

    subgraph cluster_access {
        label="access network";
        style=dashed;
        color=gray;
        eNB [label="eNB"];
    }

    subgraph cluster_gw {
        label="gateway";
        style=dashed;
        color=gray;
        S1GW [label="OsmoS1GW"];
        UPF  [label="UPF"];
        { rank=same; S1GW; UPF; }
    }

    subgraph cluster_core {
        label="core network";
        style=dashed;
        color=gray;
        MME [label="MME"];
        SGW [label="S-GW"];
        { rank=same; MME; SGW; }
    }

    eNB  -> S1GW [dir=both, label="S1AP/SCTP"];
    S1GW -> MME  [dir=both, label="S1AP/SCTP"];
    S1GW -> UPF  [dir=both, label="PFCP"];
    eNB  -> UPF  [dir=both, label="GTP-U"];
    UPF  -> SGW  [dir=both, label="GTP-U"];
}
----

All S1AP messages are inspected by the gateway.  Most are forwarded
unchanged; those that carry GTP-U endpoint information (E-RAB Setup,
Modify, Release, Initial Context Setup, etc.) are rewritten so that the
UPF's TLA/TEID is substituted before forwarding to the eNB/MME.  GTP-U
traffic itself never passes through OsmoS1GW — it flows directly between
the eNB and the UPF, and between the UPF and the S-GW.

Internally, OsmoS1GW is structured as a set of Erlang/OTP processes:

* *`sctp_server`* — Listens for incoming eNB SCTP connections and spawns
  one `enb_proxy` instance per connection.
* *`enb_proxy`* — One instance per connected eNB.  Manages the outbound
  SCTP connection to the selected MME and drives the S1 Setup handshake.
  Implements MME pooling and retry logic.
* *`s1ap_proxy`* — Paired with each `enb_proxy`.  Inspects S1AP PDUs in
  both directions and manages per-UE `erab_fsm` instances.
* *`erab_fsm`* — One instance per active E-RAB.  Exchanges PFCP Session
  Establishment/Modification/Deletion messages with the UPF and rewrites
  GTP-U F-TEID IEs in S1AP messages.
* *`pfcp_peer`* — Manages the PFCP association with the UPF (UDP-based),
  including periodic heartbeat and SEID allocation.
* *`mme_registry`* — Manages the pool of known MMEs.  MMEs can be
  provisioned statically via the configuration file or dynamically via
  the REST API.
* *`enb_registry`* — Tracks all active eNB connections and their state.
  Queryable via the REST API (see <<rest_enb>>).
* *`rest_server`* — OpenAPI-based HTTP REST interface for monitoring and
  management (see <<rest>>).

[[use_cases]]
=== Use Cases

[[use_case_isolated_networks]]
==== Separated Core and Access Networks

A possible deployment scenario in private or industrial LTE networks is one
where the core network (EPC) and the radio access network (RAN) reside in
strictly separated IP domains with no direct routing between them — for
example, a dedicated operations network for eNBs and a separate
production network for the EPC.

In this configuration, OsmoS1GW is deployed at the boundary between the
two networks.  Each eNB connects to the gateway's access-facing SCTP
listener, and the gateway in turn connects outward to the MME.  The eNBs
never need a route to the core, and the EPC never needs a route to the
radio access domain.

The gateway acts as the sole point of contact between the two networks,
providing a natural place to apply access control, logging, and
monitoring.

[[use_case_mme_pooling]]
==== MME Pooling

OsmoS1GW supports connecting multiple MMEs in a pool.  When an eNB
connects and performs the S1 Setup procedure, the gateway selects an MME
from the pool, establishes an SCTP connection to it, and forwards the S1
Setup Request.  If the selected MME rejects the setup or is unreachable,
the gateway automatically retries with the next candidate in the pool
before returning a failure to the eNB.

Pool members can be filtered by Tracking Area Code (TAC): each MME entry
in the pool can carry an optional list of TACs it is willing to serve.
The gateway uses the TAC list advertised by the eNB in the S1 Setup
Request to restrict selection to compatible MMEs.

MMEs can be configured statically in the configuration file or managed
dynamically at run time via the REST API (see <<rest_mme>>).

// vim:set ts=4 sw=4 et: