path: root/doc/manuals/chapters/running.adoc

== Running OsmoBSC

The OsmoBSC executable (`osmo-bsc`) offers the following command-line
arguments:

=== SYNOPSIS

*osmo-bsc* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL'] [-l 'IP'] [-r 'RFCTL']

=== OPTIONS

*-h, --help*::
	Print a short help message about the supported options
*-V, --version*::
	Print the compile-time version number of the 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-bsc.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 configu- ration, 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.
*-r, --rf-ctl 'RFCTL'*::
	Offer a Unix domain socket for RF control at the path/filename
	'RFCTL' in the file system.


=== Multiple instances

Running multiple instances of `osmo-bsc` on the same host is possible if all
interfaces (VTY, CTRL) 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
----

For the following links, OsmoBSC 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 OsmoBSC contacting an STP.
- The MGCP link is established by OsmoMSC contacting an MGW.

To run multiple OsmoBSC instances on the same A-interface (SCCP/M3UA), each BSC
has to configure a distinct point-code. See <<cs7_config>>.


=== Configure limits

When connecting hundreds of TRX to OsmoBSC, it may be necessary to adjust the
operating system's limit on open file descriptors for the osmo-bsc process. A
typical default limit imposed by operating systems is 1024; this would be
exceeded by, for example, about 205 BTS with 4 TRX each. (Each BTS with 4 TRX
requires 5 file descriptors for Abis; 205 * 5 already exceeds 1024, 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-bsc, which practically rules out failure from running out of file
descriptors anywhere (<50,000 TRX).

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


=== Configure primary links

==== Connect to an MSC's _A_ interface

===== Configure SCCP/M3UA (AoIP)

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

An example configuration of OsmoBSC's AoIP SCCP link, assuming the BSC at
point-code 1.23.3 and the MSC reachable at point-code 0.23.1 via an SG
listening for M3UA at 127.0.0.1:2905:

----
cs7 instance 0
 point-code 1.23.3
 asp asp-clnt-msc-0 2905 0 m3ua
  remote-ip 127.0.0.1
  role asp
  sctp-role client
 sccp-address msc
  point-code 0.23.1
msc 0
 msc-addr msc
----

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

===== Configure SCCPlite

Traditionally, OsmoBSC implemented only an SCCPlite based A-interface, an
ad-hoc standard encapsulating BSSAP in an IPA Multiplex. Since 2017, OsmoBSC
supports primarily a proper 3GPP compliant SCCP/M3UA A-interface known as AoIP,
by a new libosmo-sigtran implementation. In 2018, SCCPlite compatibility was
added to libosmo-sigtran, re-enabling the option of using an SCCPlite based
A-interface. For details, see the OsmoSTP manual, chapter "IPA / SCCPlite
backwards compatibility".

Here is an example configuration of OsmoBSC for SCCPlite, assuming the BSC at
point-code 1.23.3 and an SCCPlite MSC listening on 127.0.0.1:5000 with own
point-code 0.23.1:

----
cs7 instance 0
 point-code 1.23.3
 asp asp-clnt-msc-0 5000 0 ipa
  remote-ip 127.0.0.1
 as as-clnt-msc-0 ipa
  asp asp-clnt-msc-0
  routing-key 0 1.23.3
  point-code override dpc 0.23.1
 sccp-address remote_msc
  point-code 0.23.1
msc 0
 msc-addr remote_msc
----

==== Configure MGCP to connect to an MGW

OsmoBSC uses a media gateway (typically OsmoMGW) to direct RTP streams. By
default, an MGW is expected to receive MGCP requests on the IANA-registered
default port for MGCP (2427) on local host (127.0.0.1).

Here is an example configuration for a remote MGW:

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

OsmoBSC is also able to handle a pool of media gateways for load
distribution since mid 2021. See also <<mgw_pooling>>.

[NOTE]
====
Previous versions of OsmoBSC 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 `msc` VTY node. The MGW related commands
under the  `msc` 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 OsmoBSC will automatically convert the config to use the new `mgw`
node.
====

===== Pinning a BTS to a specific MGW

It is sometimes desirable to assign a specific MGW to a given BTS, so that all
calls where the BTS is involved use the assigned MGW with a higher precedence if
possible.

This is specially important if the BTS is configured to serve calls using Osmux
instead of RTP. Osmux features trunking optimizations, which allow transmission
of audio payload from different concurrent calls inside the same underlaying UDP
packet, hence reducing the total required throughput and saving costs on the
required link.

In order for Osmux trunking optimization to work, the source and destination IP
address of uderlaying UDP packet must be of course the same for all the calls
involved. That essentially boils down to having all the concurrent calls of the
BTS be connected to the same MGW so that they can be trunked over the same UDP
connection.

The pinning to a specific MGW can be configured per BTS, and hence it is
configured under the `bts` VTY node:

----
OsmoBSC> enable
OsmoBSC# configure terminal
OsmoBSC(config)# network
OsmoBSC(config-net)# bts 1
OsmoBSC(config-bts)# mgw pool-target 1 <1>
OsmoBSC(config-bts)# exit
OsmoBSC(config-net)# bts 2
OsmoBSC(config-mgw)# mgw pool-target 7 strict <2>
OsmoBSC(config-net)# bts 3
OsmoBSC(config-mgw)# no mgw pool-target <3>
----

<1> Pin BTS1 to prefer MGW1 (node `mgw 1`). If MGW1 is not configured,
administrateivly blocked or not connected at the time a new call is to be
established, then another MGW from the pool is selected following the usual
procedures. This allows applying pinning in the usual scenario while still
keeping call service ongoing against another MGW if the preferred MGW is not
available at a given time.

<2> Pin BTS2 to prefer MGW7 (node `mgw 7`). If MGW7 is not configured,
administrateivly blocked or not connected at the time a new call is to be
established, then the MGW assignment will fail and ultimately the call will be
terminated during establishment.

<3> Apply no pinning at all (default). The MGW with the lowest load is the one
being selected for each new call.

==== Configure Lb to connect to an SMLC

Enable the Lb interface. OsmoBSC will then use the default point-codes to
establish a connection to the SMLC.

----
smlc
 enable
----

More detailed configuration is described in <<smlc-config>>.

[[cfg_bsc_co_located_pcu]]
==== Configure BSC co-located PCU

While small IP based BTSs usually come with a built in PCU (BTS co-located
PCU), this does not have to be the case with any BTS. Especially larger E1 BTS
usually make use of a BSC co-located PCU.

In the case of OsmoBSC this means that an instance of OsmoPCU is running next
to OsmoBSC. Both processes share a unix domain socket to exchange signaling
traffic and configuration parameters.

.OsmoBSC with co-located OsmoPCU'
[graphviz]
----
digraph G {
        rankdir=LR;
        BTS [label="BTS"];

        subgraph cluster_ran {
                label="RAN";
                PCU [label="OsmoPCU"];
                BSC [label="OsmoBSC"];
                MGW [label="OsmoMGW"];
	        { rank=same BSC MGW PCU }
        }

        BTS->PCU [label="GPRS/TRAU", style=dotted];
        BTS->BSC [label="Abis"];
        BTS->MGW [label="SPEECH/TRAU", style=dotted];
        BSC->MGW [label="MGCP"];
        BSC->PCU [label="PCU_SOCK"];
}
----

Apart from the configuration of the PCU socket path the configuration is not
much different from those where the PCU is integrated inside the BTS. See also
see also <<config_gprs_pcu_pars>> for a detailed description.

.Configure socket path to co-located PCU
----
network
 pcu-socket /tmp/pcu_bts
----