[[running]]
== Running OsmoS1GW

[[running_requirements]]
=== Requirements

OsmoS1GW requires:

* Erlang/OTP 25 or later.
* A Linux kernel with SCTP support (`sctp` kernel module).
* A reachable UPF that speaks PFCP (e.g. https://osmocom.org/projects/osmo-upf[OsmoUPF]).
* One or more reachable MMEs (e.g. https://github.com/open5gs/open5gs[Open5GS]).

[[running_installation_options]]
=== Installation Options

[[running_binary_packages]]
==== Official Osmocom Binary Packages

Osmocom provides binary packages of OsmoS1GW for a variety of GNU/Linux
distributions, primarily Debian based ones.  This is the recommended
installation method for production deployments.  For up-to-date
instructions on how to add the Osmocom package repository
for your distribution, see:
https://osmocom.org/projects/cellular-infrastructure/wiki/Binary_Packages.

Two packages are provided: `osmo-s1gw` (the gateway itself) and
`osmo-s1gw-cli` (the management CLI, see <<cli>>).  To install both, run:

----
apt install osmo-s1gw osmo-s1gw-cli
----

[[running_building]]
==== Building from Source

OsmoS1GW uses https://rebar3.org[rebar3] as its build tool, wrapped by a
convenience `Makefile` in the project root.  To fetch dependencies and
compile:

----
git clone https://gitea.osmocom.org/osmocom/osmo-s1gw.git
cd osmo-s1gw
make
----

[[running_building_make_targets]]
===== Available Make Targets

The following targets are available:

`make` / `make build`::
  Compile the application and all dependencies (default target).

`make shell` / `make run`::
  Compile and start OsmoS1GW in an interactive Erlang shell.  Intended
  for development and local testing.  The config file used is controlled
  by the `CONFIG` variable (default: `config/sys.config`).

`make check`::
  Run the EUnit test suite.  Additional arguments can be passed to the
  test runner via the `EUNIT_ARGS` variable.

`make analyze`::
  Run Dialyzer static type analysis.

`make release`::
  Build a self-contained Erlang/OTP release package (includes the ERTS
  runtime) under `_build/default/rel/osmo-s1gw/`.

`make run-release`::
  Build the release and immediately start it using the `osmo-s1gw.sh`
  bootstrap script (see <<running_bootstrap_script>>).  The `CONFIG`
  variable selects the config file.

`make install`::
  Build the release and install OsmoS1GW system-wide.  See
  <<running_building_installation>> for details.

`make clean`::
  Remove all build artefacts.

[[running_building_make_variables]]
===== Make Variables

The following variables customise the build and installation:

[options="header",cols="25,50,25"]
|===
| Variable | Description | Default
| `CONFIG` | Config file used by `make shell` and `make run-release` | `config/sys.config`
| `EUNIT_ARGS` | Extra arguments forwarded to `rebar3 eunit` | (none)
| `BINDIR` | Installation directory for executables | `/usr/bin`
| `LIBDIR` | Installation directory for the release package | `/usr/lib`
| `CONFDIR` | Installation directory for the config file | `/etc/osmocom`
| `SYSTEMDUNITDIR` | Installation directory for the systemd unit | `/lib/systemd/system`
| `DESTDIR` | Staging root prefix (for package builds) | (empty)
|===

[[running_building_installation]]
===== Installation

Running `make install` (typically as root, or with `DESTDIR` set for
packaging) installs the release package, bootstrap script, management CLI,
example config file, and systemd unit to their respective directories as
configured by the variables in <<running_building_make_variables>>.

[[running_options]]
=== Running Options

[[running_bootstrap_script]]
==== The `osmo-s1gw` Bootstrap Script

The installed `osmo-s1gw` executable is a POSIX shell script
(`contrib/osmo-s1gw.sh`) that locates the bundled ERTS runtime inside
the release package and launches `erlexec` with the correct boot, config,
and node parameters.  It is the standard entry point both for systemd and
for manual invocation.

Usage:

----
osmo-s1gw [-s] [-r ROOTDIR] [-c CONFIG] [-C COOKIE] [-n NAME@HOST]
----

Options:

`-r ROOTDIR`::
  Path to the Erlang/OTP release root directory.
  Default: `/usr/lib/osmo-s1gw`.

`-c CONFIG`::
  Path to the configuration file.
  Default: `/etc/osmocom/osmo-s1gw.config`.

`-C COOKIE`::
  Erlang distribution cookie used for inter-node communication.
  Default: `osmo-s1gw`.

`-n NAME@HOST`::
  Erlang node name.  Default: `osmo-s1gw@<hostname>`.

`-s`::
  Start with an interactive Erlang shell instead of running headless.
  Useful for debugging on a deployed system.

[[running_systemd]]
==== Running Under systemd

After installation, enable and start OsmoS1GW as a systemd service:

----
systemctl enable osmo-s1gw
systemctl start osmo-s1gw
----

The unit file runs OsmoS1GW as the `osmocom` user and group and requests
the `CAP_NET_ADMIN` capability (required for GTP-U KPI monitoring).
The service is restarted automatically on failure with a 2-second delay.
OsmoS1GW reads its configuration from `/etc/osmocom/osmo-s1gw.config`.

To inspect the log output:

----
journalctl -u osmo-s1gw -f
----

[[running_logging]]
=== Logging

OsmoS1GW uses the standard Erlang/OTP `logger` framework.  Two log
handlers are configured by default:

`default`::
  Writes formatted log lines to standard output.  When running under
  systemd this output is captured by the journal.  The log level is set
  to `info` by default.

`gsmtap`::
  Sends log messages as GSMTAP frames over UDP to a configurable
  destination (default: `127.0.0.1`).

The global minimum log level is controlled by the `logger_level` kernel
parameter; individual handler levels can be overridden independently.
See <<config_kernel>> for the relevant configuration section.

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