== Running OsmoHNBGW

The OsmoHNBGW executable (`osmo-hnbgw`) offers the following command-line
arguments:

=== SYNOPSIS

*osmo-hnbgw* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL']

=== OPTIONS

*-h, --help*::
	Print a short help message about the supported options
*-V, --version*::
	Print the compile-time version number of the OsmoHNBGW program
*-d, --debug 'DBGMASK','DBGLEVELS'*::
	Set the log subsystems and levels for logging to stderr. This
	has mostly been superseded by VTY-based logging configuration,
	see <<logging>> for further information.
*-D, --daemonize*::
	Fork the process as a daemon into background.
*-c, --config-file 'CONFIGFILE'*::
	Specify the file and path name of the configuration file to be
	used. If none is specified, use `osmo-msc.cfg` in the current
	working directory.
*-s, --disable-color*::
	Disable colors for logging to stderr. This has mostly been
	deprecated by VTY based logging configuration, see <<logging>>
	for more information.
*-T, --timestamp*::
	Enable time-stamping of log messages to stderr. This has mostly
	been deprecated by VTY based logging configuration, see
	<<logging>> for more information.
*-e, --log-level 'LOGLEVEL'*::
	Set the global log level for logging to stderr. This has mostly
	been deprecated by VTY based logging configuration, see
	<<logging>> for more information.


=== Multiple instances

Running multiple instances of `osmo-hnbgw` on the same computer is possible if
all interfaces (VTY, CTRL, Iuh) are separated using the appropriate
configuration options. The IP based interfaces are binding to local host by
default. In order to separate the processes, the user has to bind those
services to specific but different IP addresses and/or ports.

The VTY and the Control interface can be bound to IP addresses from the loopback
address range, for example:

----
line vty
 bind 127.0.0.2
ctrl
 bind 127.0.0.2
----

The Iuh interface can be bound to an individual port:

----
hnbgw
 iuh
  local-ip 0.0.0.0
  local-port 29169
----

For the following links, OsmoHNBGW acts as a client and does not listen/bind to a
specific interface, and will hence not encounter conflicts for multiple instances
running on the same interface:

- The SCCP/M3UA links are established by OsmoHNBGW contacting an STP.
- The MGCP link is established by OsmoHNBGW contacting an MGW.
- The PFCP link is established by OsmoHNBGW contacting a UPF.

To run multiple OsmoHNBGW instances on the same SCCP routing, each HNBGW has to
configure a distinct point-code, see <<configure_iucs_iups>>.


=== Configure limits

When connecting hundreds of HNB to OsmoHNBGW, it may be necessary to adjust the
operating system's limit on open file descriptors for the osmo-hnbgw process. A
typical default limit imposed by operating systems is 1024; this would be
exceeded by, for example, about 1024 HNB on Iuh, sockets for other interfaces
not considered yet.

It should be ok to set an OS limit on open file descriptors as high as 65536
for osmo-hnbgw, which practically rules out failure from running out of file
descriptors anywhere (<50,000 HNB).

When using systemd, the file descriptor limit may be adjusted in the service
file by the `LimitNOFILE` setting ("Number of Open FILE descriptors").
OsmoHNBGW ships a systemd service file with a high LimitNOFILE setting.


=== Configuring Primary Links

[[configure_iucs_iups]]
==== Configure SCCP/M3UA to connect to an MSC's _IuCS_ and an SGSN's _IuPS_ interface

OsmoHNBGW acts as client to contact an STP instance and establish an SCCP/M3UA
link.

An example configuration of OsmoHNBGW's SCCP link:

----
cs7 instance 0
 point-code 0.23.5
 asp asp-clnt-OsmoHNBGW 2905 0 m3ua
  remote-ip 127.0.0.1
  sctp-role client
 sccp-address msc
  routing-indicator PC
  point-code 0.23.1
 sccp-address sgsn
  routing-indicator PC
  point-code 0.23.2
hnbgw
 iucs
  remote-addr msc
 iups
  remote-addr sgsn
----

This configuration is explained in detail in <<cs7_config>>.

==== Configure RUA to accept Iuh connections from hNodeB

OsmoHNBGW acts as server to accept Iuh connections from hNodeB devices.

An example configuration for OsmoHNBGW's RUA server:

----
hnbgw
 iuh
  local-ip 10.9.8.7
  local-port 29169
----

==== Configure co-located media gateway

OsmoHNBGW requires a co-located OsmoMGW instance. The purpose of the co-located
media gateway is to relay the RTP traffic between hNodeB and the core network.

For security reasons the RAN network is kept separate and isolated from the
core network. Both networks will usually have no transparent routing in between
them. The co-located media gateway provides an interface between hNodeB and core
network across this boundary.

The configuration is done under the hnbgw node along with `iucs` and `iups`.

An example configuration for OsmoHNBGW's MGCP client:

----
hnbgw
 mgw 0
  remote-ip 127.0.0.1
  remote-port 2427
  reset-endpoint rtpbridge/* <1>
----
<1> The 'reset-endpoint' setting instructs the OsmoMGW to send a wildcarded
DLCX to the media gateway. This helps to clear lingering calls from the
media gateway when the OsmoHNBGW is restarted.

OsmoHNBGW is also able to handle a pool of media gateways for load
distribution. See also <<mgw_pooling>>.

[NOTE]
====
Previous versions of OsmoHNBGW didn't have the 'mgw' VTY node and
hence didn't support the MGW pooling feature. Therefore, historically the MGW
related commands where placed under the `mgcp` VTY node. The MGW related commands
under the `mgcp` VTY are still parsed and used but its use is deprecated and
hence discouraged in favour of the new `mgw` node. Writing the config to a file
from within OsmoHNBGW will automatically convert the config to use the new `mgw`
node.
====

==== Configure co-located User Plane Function

OsmoHNBGW optionally supports relaying the GTP user plane via a co-located UPF,
which is controlled by the PFCP protocol.

PFCP support is optional at compile time, as well as run time. To use a co-located UPF,

* osmo-hnbgw needs to be compiled with 'configure --enable-pfcp',
* and osmo-hnbgw.cfg needs to configure a 'pfcp' / 'remote-addr' and
  'local-addr'.

The following example configures OsmoHNBGW to associate via PFCP with a UPF
listening on UDP 127.0.0.2:8805, ready to setup GTP tunnel relays.

----
hnbgw
 pfcp
  remote-addr 127.0.0.2
  local-addr 127.0.0.1
----

3GPP TS 29.244 4.2.2 specifies that PFCP Request messages shall be sent to UDP
port 8805, i.e. the PFCP port is fixed as 8805 and currently not configurable in
osmo-hnbgw.

Setting a 'local-addr' is required: the PFCP protocol features a Node ID, which
uniquely identifies PFCP peers across different interfaces. According to the
PFCP specification, the Node ID can be a fully-qualified domain name (FQDN) or
an IP address. Currently, osmo-hnbgw has no support for using an FQDN as Node
ID, and so far uses the 'local-addr' as local Node ID -- hence the 'local-addr'
must not be "0.0.0.0", which is an unfortunate consequence. This is likely to
improve in the future, see https://osmocom.org/issues/5647 .
