osmo-s1gw
=========

This is an S1AP (S1 Application Protocol) Gateway implementation in Erlang for
the 3GPP EPC (Evolved Packet Core) based (4G/LTE) networks.  It is part of the
[Osmocom](https://osmocom.org/) Open Source Mobile Communications project.

S1AP is a protocol "spoken" between the eNB and the MME.  The S1GW is useful in
scenarios when eNB(s) and the MME co-exist in separate networks and thus unable
to access each other directly.  This is basically a proxy, accepting incoming
connections from eNB(s), establishing the associated outgoing connections
to the MME, and forwarding S1AP PDUs back and forth.

```
          (network A) |
                      |
               +-------------+     +-------------+
               |  osmo-s1gw  |     |     MME     |
+--------+     +-------------+     +-------------+
| eNB(1) | --> |             | --> |             |
+--------+     |             |     |             |
               |             |     |             |
+--------+     |             |     |             |
| eNB(2) | --> |             | --> |             |
+--------+     |             |     |             |
               |             |     |             |
+--------+     |             |     |             |
| eNB(N) | --> |             | --> |             |
+--------+     +-------------+     +-------------+
                      |
                      | (network B)
```


Homepage
--------

This project does not have its own homepage yet, unlike many other
[Osmocom projects](https://osmocom.org/projects/).


GIT Repository
--------------

You can clone from the official osmo-s1gw.git repository using

```
$ git clone https://gitea.osmocom.org/erlang/osmo-s1gw
```

There is a web interface at <https://gitea.osmocom.org/erlang/osmo-s1gw>


Documentation
-------------

The user manual source is in [`doc/manuals/`](doc/manuals/).  It covers
installation, configuration, metrics, the REST API, and the interactive CLI.
A pre-built PDF is published on the
[Osmocom documentation server](https://ftp.osmocom.org/docs/osmo-s1gw).


Contributing
------------

Our coding standards are described at
<https://osmocom.org/projects/cellular-infrastructure/wiki/Coding_standards>.

We use a Gerrit based patch submission/review process for managing
contributions.  Please see
<https://osmocom.org/projects/cellular-infrastructure/wiki/Gerrit> for
more details.

The current patch queue for osmo-s1gw can be seen at
<https://gerrit.osmocom.org/#/q/project:erlang/osmo-s1gw+status:open>.


Building
--------

Install erlang and rebar3 packages (not "rebar", that's version 2! You may need
to compile it from source in some distros).

```
$ make
```


Testing
-------

Unit tests can be run this way:

```
$ make check
```

Additionally, you can run the static analyser (Dialyzer):

```
$ make analyze
```


Running
-------

Once OsmoS1GW is built, you can start it this way:

```
$ make run
```


Installation
------------

Osmocom provides binary packages for common Debian and Ubuntu releases via
the [Osmocom binary package feed](https://osmocom.org/projects/cellular-infrastructure/wiki/Binary_Packages).
Both a stable feed (tracking the latest release) and a nightly feed are
available.  If you are not doing development, using the binary packages is
the recommended approach.

To build and install from source:

```
$ make
$ sudo make install
```

`make install` deploys a complete ERTS release together with a convenience
wrapper script and the interactive CLI tool:

* `/usr/lib/osmo-s1gw` — complete OTP/ERTS release package
* `/usr/bin/osmo-s1gw` — bootstrap script for starting the release
* `/usr/bin/osmo-s1gw-cli` — interactive CLI tool
* `/lib/systemd/system/osmo-s1gw.service` — systemd unit file
* `/etc/osmocom/osmo-s1gw.config` — default configuration file

Installation paths can be adjusted with `DESTDIR`, `LIBDIR`, `BINDIR`,
`CONFDIR`, and `SYSTEMDUNITDIR`.  See the user manual for full details.


Configuration
-------------

The default configuration file is [`config/sys.config`](config/sys.config).
For a full description of all available configuration parameters, see the
Configuration chapter in the user manual
([`doc/manuals/chapters/configuration.adoc`](doc/manuals/chapters/configuration.adoc)).


REST interface
--------------

OsmoS1GW implements a custom (non-standard) REST interface, primarily intended
for state introspection.  The interface is specified using OpenAPI, with the
specification available in [contrib/openapi.yaml](contrib/openapi.yaml).

You can explore the API and available endpoints interactively via
the Swagger UI by opening <http://localhost:8080/swagger> in a browser.

The OpenAPI specification is provided in two formats:

* **YAML** (`contrib/openapi.yaml`) is the primary specification document.
* **JSON** (`priv/openapi.json`) is generated from the YAML using
[contrib/yaml2json.py](contrib/yaml2json.py) and used as input by the
ERF framework for automatic code generation and the request validation.

> **Note:** Both files must be kept in sync.  When making changes to the YAML
document, make sure to update the JSON counterpart by invoking `make openapi`.


Interactive CLI
---------------

OsmoS1GW comes with [`osmo-s1gw-cli.py`](contrib/osmo-s1gw-cli.py) - an interactive
shell based on Python's **cmd2** library.  This script serves as an alternative to the
traditional telnet/VTY interface found in many Osmocom projects.  For more details,
see the respective [documentation](doc/osmo-s1gw-cli.md).