== 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 <> 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 <> for more information. *-T, --timestamp*:: Enable time-stamping of log messages to stderr. This has mostly been deprecated by VTY based logging configuration, see <> 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 <> 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 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 <>. ==== 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 <>. [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 .