Cellular Network Infrastructure

h1. Osmocom Network In The Box

This is a brief guide to the most basic and minimal setup of an Osmocom 2G and/or 3G network for voice and data services. It is a good starting point for newcomers to familiarize with the software, and to expand upon by the [[Osmocom Manuals]] and other wiki pages.

h2. OsmoNITB R.I.P., long live the Network In The Box

Historically, Osmocom offered the [[OsmoNITB:]] "Network-In-The-Box" as an actual single program. It was a useful simplification at the time, but in 2017, Osmocom have decided to split OsmoNITB into programs more closely resembling traditional network architecture. It is recommended to use the new separate components instead of the OsmoNITB, since active development focus has moved there.

It is still very much possible to run a complete Osmocom core network in one "box". For example, a sysmoBTS can run the entire core network on the same hardware that drives the TRX, making it a complete network in actually one single box. At the same time, having separate components also allows scaling to large deployments, with properly distributed load and a central subscriber database.

To migrate from OsmoNITB to the new separate programs, see the [[OsmoNITB Migration Guide]].

h2. Part of this Complete Network

Assuming that you have your radio hardware ready (a BTS, a femto cell or an SDR driven by osmo-trx), the core network consists of separate programs providing voice/SMS/USSD ("circuit-switched") and data ("packet-switched") services.

h3. Circuit-Switched Components

To run a circuit-switched core network, you need:

* [[OsmoHLR:]] -- Home Location Register, stores subscriber IMSI, phone number and auth tokens.

* [[OsmoMSC:]] -- Mobile Switching Center, handles signalling, i.e. attach/detach of subscribers, call establishment, messaging (SMS and USSD).

* [[OsmoMGW:]] -- Media Gateway, is instructed by the MSC and/or the BSC to direct RTP streams for active voice calls.

* [[OsmoSTP:]] -- Signal Transfer Point, routes SCCP messages between MSC, BSC, HNBGW and for 3G also the SGSN.

* [[OsmoBSC:]] -- 2G Base Station Controller, manages logical channels and other lower level aspects for one or more 2G BTS; it is technically part of the BSS and not the "core network".

* [[OsmoHNBGW:]] -- 3G HomeNodeB Gateway, receives the Iuh protocol from a 3G femto cell and forwards to MSC and SGSN by SCCP/M3UA via OsmoSTP.

h3. Packet-Switched Components

* [[OpenGGSN:|OsmoGGSN]] -- Gateway GPRS Support Node, "opens" GTP tunnels received from SGSNs to internet uplink.

* [[OsmoSGSN:]] -- Serving GPRS Support Node, handles signalling, i.e. attach/detach of subscribers and PDP contexts.

* [[OsmoHLR:]] -- same as for circuit switched, see above.

* [[OsmoHNBGW:]] -- for 3G packet switched networks, same as for 3G circuit switched, see above.

* ([[OsmoPCU:]] -- for 2G networks, a component closely tied to the BTS, drives the TRX and ties to the SGSN via Gb-interface.)

h1. Have to Know

Each program features a detailed [[Osmocom Manuals|user manual]], your primary source of information to expand on the setup described here.

Osmocom offers [[Nightly Builds|compiled packages for various distributions]]. If you're up to it, you may also [[Build from Source]].

Each Osmocom program typically has

* a distinct configuration file;

* a VTY telnet console for live interaction;

* a CTRL interface for live interaction with 3rd party programs.

See [[Port Numbers]] to find out which program runs VTY on which port.

h1. Configuration Examples

h2. OsmoHLR

See the [[Osmocom Manuals|manual]] on creating a subscriber database, and add one or more subscribers.

While you do need one, your configuration file may actually remain empty. This will serve GSUP on localhost (127.0.0.1), sufficient for a Network In The Box.

h2. OsmoMSC

The VLR component of OsmoMSC needs to connect to the OsmoHLR's GSUP server to know which subscribers are authorized. By default, it will connect to OsmoHLR on localhost, no explicit config needed.

To be reachable by OsmoBSC and OsmoHNBGW, it needs an SCCP point code, and it needs to connect to OsmoSTP to make itself known to SCCP routing.

* There is a default point code, currently 0.23.1 (in 8.8.3 point code format).

* OsmoMSC will by default look for OsmoSTP on localhost's M3UA port, 2905.

To direct RTP streams, OsmoMSC needs an OsmoMGW instance. By default, it will look for an MGW on localhost and the default MGCP port, 4222.

Again, your config file may remain empty.

h2. OsmoMGW

The Media Gateway receives instructions in the form of MGCP messages from OsmoMSC. It forwards RTP streams directly between BTS, femto cells and remote endpoints, e.g. other MGW instances.

Its RTP IP address must be reachable by the BTS / the femto cell.

* In a setup that truly runs in one box (e.g. sysmoBTS or osmo-trx with co-located core network), this may be localhost (127.0.0.1).

* With a separate BTS or RNC (e.g. 3G femto cell or nanoBTS), make sure to configure an IP address that is reachable.

*osmo-mgw.cfg*

<pre>

mgcp

  local ip 192.168.0.3

  bind ip 192.168.0.3

</pre>

The default is to allow any BTS / femto cell IP address to connect.

(Near future: a second OsmoMGW may be needed to run alongside each OsmoBSC instance.)

h2. OsmoSTP

OsmoSTP acts as a server for routing messages. OsmoMSC, OsmoBSC, OsmoHNBGW and OsmoSGSN contact OsmoSTP and announce their own point code, after which they may instruct OsmoSTP to route SCCP messages to each other by these point codes.

The basic configuration that permits dynamic routing is:

*osmo-stp.cfg*

<pre>

cs7 instance 0

 xua rkm routing-key-allocation dynamic-permitted

 listen m3ua 2905

  accept-asp-connections dynamic-permitted

</pre>

h2. OsmoBSC

OsmoBSC needs to register with OsmoSTP, and contact the MSC by its point code.

OsmoBSC also needs complete configuration of all connected BTS. This example shows configuration for a sysmoBTS.

Furthermore, some network properties need to be set.

The 'gprs mode' determines whether packet switched access will be enabled. 'gprs mode none' switches off data services, as osmo-bts will not contact osmo-pcu to establish data service. This is a configuration without packet switched service:

*osmo-bsc.cfg* for voice only

<pre>

network

 network country code 901

 mobile network code 70

 mm info 1

 short name Osmocom

 long name Osmocom

 auth policy closed

 encryption a5 0

 bts 0

  type sysmobts

  band GSM-1800

  cell_identity 0

  location_area_code 23

  ip.access unit_id 1800 0

  gprs mode none

  trx 0

   rf_locked 0

   arfcn 868

   nominal power 23

   timeslot 0

    phys_chan_config CCCH+SDCCH4

   timeslot 1

    phys_chan_config SDCCH8

   timeslot 2

    phys_chan_config TCH/H

   timeslot 3

    phys_chan_config TCH/H

   timeslot 4

    phys_chan_config TCH/H

   timeslot 5

    phys_chan_config TCH/H

   timeslot 6

    phys_chan_config TCH/H

   timeslot 7

    phys_chan_config TCH/H

cs7 instance 0

 ! osmo-bsc's own point code

 point-code 0.42.0

 ! address book entry named 'msc_remote', used below

 sccp-address msc_remote

  point-code 0.23.1

msc 0

 msc-addr msc_remote

</pre>

To allow data service, set a 'gprs mode gprs' or 'gprs mode egprs', and configure PDCH timeslots. Traditionally, a fixed amount of TCH timeslots for voice and PDCH timeslots for data service are configured. OsmoBTS also supports two types of dynamic timeslots, as described in the "Abis manual":http://ftp.osmocom.org/docs/latest/osmobts-abis.pdf, chapter "Dynamic Channel Combinations". The following is a configuration with data service based on Osmocom style dynamic timeslots:

*osmo-bsc.cfg* for voice and data service

<pre>

network

 network country code 901

 mobile network code 70

 mm info 1

 short name Osmocom

 long name Osmocom

 auth policy closed

 encryption a5 0

 bts 0

  type sysmobts

  band GSM-1800

  cell_identity 0

  location_area_code 23

  ip.access unit_id 1800 0

  gprs mode gprs

  trx 0

   rf_locked 0

   arfcn 868

   nominal power 23

   timeslot 0

    phys_chan_config CCCH+SDCCH4

   timeslot 1

    phys_chan_config SDCCH8

   timeslot 2

    phys_chan_config TCH/F_TCH/H_PDCH

   timeslot 3

    phys_chan_config TCH/F_TCH/H_PDCH

   timeslot 4

    phys_chan_config TCH/F_TCH/H_PDCH

   timeslot 5

    phys_chan_config TCH/F_TCH/H_PDCH

   timeslot 6

    phys_chan_config TCH/F_TCH/H_PDCH

   timeslot 7

    phys_chan_config PDCH

cs7 instance 0

 ! osmo-bsc's own point code

 point-code 0.42.0

 ! address book entry named 'msc_remote', used below

 sccp-address msc_remote

  point-code 0.23.1

msc 0

 msc-addr msc_remote

</pre>

h2. OsmoHNBGW

For connecting a 3G hNodeB (femto cell), OsmoHNBGW is needed to receive Iuh and forward IuCS and IuPS. (For a pure 2G setup, no HNBGW is needed.)

OsmoHNBGW needs to connect to OsmoSTP for routing, and needs to know the MSC and SGSN point codes.

It must also be reachable by the hNodeB, hence its Iuh must typically run on a public IP, not a loopback address like 127.0.0.1.

*osmo-hnbgw.cfg*

<pre>

cs7 instance 0

 ! OsmoHNBGW's own local point code

 point-code 0.3.0

 ! Address book entries, used below

 sccp-address msc

  point-code 0.23.1

 sccp-address sgsn

  point-code 0.23.2

hnbgw

 iuh

  local-ip 192.168.0.3

 iucs

  remote-addr msc

 iups

  remote-addr sgsn

</pre>

h2. OsmoGGSN

To provide packet switched service, OsmoGGSN must offer GTP service to the OsmoSGSN. Notably, both OsmoGGSN and OsmoSGSN must use identical port numbers, which an intrinsic requirement of the GTP protocol. Hence they must not run on the same IP address. It is sufficient to, for example, run OsmoGGSN on 127.0.0.2, and OsmoSGSN's GTP on 127.0.0.1.

OsmoGGSN maintains a gsn_restart counter, to be able to reliably communicate to the SGSN that it has restarted. This is kept in the 'state-dir', by default in /tmp.

It also needs access to a tun device. This may be configured ahead of time, so that OsmoGGSN does not need root privileges. If run with 'sudo', OsmoGGSN may also create its own tun device. In below example, the 'tun4' device has been created ahead of time. IPv4 operation is enabled by default, but for future compatibility, it is good to indicate that explicitly.

OsmoGGSN furthermore indicates DNS servers, as well as an IPv4 address range to assign to subscribers' PDP contexts.

*osmo-ggsn.cfg*

<pre>

ggsn ggsn0

 gtp bind-ip 127.0.0.2

 apn internet

  tun-device tun4

  type-support v4

  ip dns 0 192.168.100.1

  ip dns 1 8.8.8.8

  ip ifconfig 176.16.222.0/24

  ip prefix dynamic 176.16.222.0/24

</pre>

h2. OsmoSGSN

OsmoSGSN needs to reach the GGSN to establish GTP tunnels for subscribers. It must have a separate GTP IP address from OsmoGGSN, as mentioned before.

For 2G, OsmoSGSN needs to be reachable by the PCU, and needs a public IP for the Gb interface if it is not running directly on the BTS hardware (e.g. on sysmoBTS or when using osmo-trx). For 2G operation, SGSN and GGSN may both use a local IP address for GTP, as long as they differ (e.g. 127.0.0.1 and 127.0.0.2).

For 3G, OsmoSGSN needs to be reachable by both the HNBGW for IuPS as well as by the hNodeB for GTP, i.e. it definitely needs to have a public IP address for the GTP port. IuPS may remain local if both HNBGW and SGSN are on the same box.

Finally, OsmoSGSN needs access to OsmoHLR to access subscriber data. Set 'auth-policy remote' to use the HLR for subscriber authorization. The default 

*osmo-sgsn.cfg*

<pre>

sgsn

 gtp local-ip 192.168.0.3

 ggsn 0 remote-ip 192.168.0.142

 auth-policy remote

 gsup remote-ip 127.0.0.1

</pre>

h1. Running Examples

Each Osmocom program comes with a systemd service file. It is recommended to place config files in /etc/osmocom/ and launch the individual components using systemd.

When installed from debian or opkg feeds, you will find the systemd service files in /lib/systemd/system/.

Re/starting and stopping then works like this:

<pre>

systemctl restart osmo-hlr

systemctl stop osmo-hlr

</pre>

For illustration, the manual command invocations for the components would look like this:

<pre>

osmo-hlr -l hlr.db -c osmo-hlr.cfg

osmo-msc -c osmo-msc.cfg

osmo-mgw -c osmo-mgw.cfg

osmo-stp -c osmo-stp.cfg

osmo-bsc -c osmo-bsc.cfg

osmo-hnbgw -c osmo-hnbgw.cfg

osmo-ggsn -c osmo-ggsn.cfg

osmo-sgsn -c osmo-sgsn.cfg

</pre>

h1. Logging Examples

Osmocom programs have a common logging mechanism, configurable by the config files as well as the telnet VTY.

Depending on the system's logging configuration, logs may by default be visible in /var/log/daemon.log, or by using journalctl:

<pre>

journalctl -f -u osmo-hlr

</pre>

When journalctl is used, it may be necessary to enable it first, e.g. by setting "Storage=volatile" in /etc/systemd/journald.conf followed by a 'systemctl restart systemd-journald'.

A sure way to see the logs is to connect to the program's telnet VTY and enable logging on the VTY session -- this way you do not modify the application's default logging, but create a separate logging target for your telnet VTY session:

<pre>

$ telnet localhost 4254

OsmoMSC> logging enable 

OsmoMSC> logging level ?

  all      Global setting for all subsystems

  rll      A-bis Radio Link Layer (RLL)

  cc       Layer3 Call Control (CC)

  mm       Layer3 Mobility Management (MM)

  rr       Layer3 Radio Resource (RR)

  rsl      A-bis Radio Siganlling Link (RSL)

  nm       A-bis Network Management / O&M (NM/OML)

  mncc     MNCC API for Call Control application

  pag      Paging Subsystem

  meas     Radio Measurement Processing

  sccp     SCCP Protocol

  msc      Mobile Switching Center

  mgcp     Media Gateway Control Protocol

  ho       Hand-Over

  db       Database Layer

  ref      Reference Counting

  gprs     GPRS Packet Service

  ns       GPRS Network Service (NS)

  bssgp    GPRS BSS Gateway Protocol (BSSGP)

  llc      GPRS Logical Link Control Protocol (LLC)

  sndcp    GPRS Sub-Network Dependent Control Protocol (SNDCP)

  nat      GSM 08.08 NAT/Multiplexer

  ctrl     Control interface

  smpp     SMPP interface for external SMS apps

  filter   BSC/NAT IMSI based filtering

  ranap    Radio Access Network Application Part Protocol

  sua      SCCP User Adaptation Protocol

  pcu      PCU Interface

  vlr      Visitor Location Register

  iucs     Iu-CS Protocol

  sigtran  SIGTRAN Signalling Transport

  lglobal  Library-internal global log family

  llapd    LAPD in libosmogsm

  linp     A-bis Intput Subsystem

  lmux     A-bis B-Subchannel TRAU Frame Multiplex

  lmi      A-bis Input Driver for Signalling

  lmib     A-bis Input Driver for B-Channels (voice)

  lsms     Layer3 Short Message Service (SMS)

  lctrl    Control Interface

  lgtp     GPRS GTP library

  lstats   Statistics messages and logging

  lgsup    Generic Subscriber Update Protocol

  loap     Osmocom Authentication Protocol

  lss7     libosmo-sigtran Signalling System 7

  lsccp    libosmo-sigtran SCCP Implementation

  lsua     libosmo-sigtran SCCP User Adaptation

  lm3ua    libosmo-sigtran MTP3 User Adaptation

  lmgcp    libosmo-mgcp Media Gateway Control Protocol

OsmoMSC> logging level mm ?

everything debug      info       notice     error      fatal      

OsmoMSC> logging level mm debug 

OsmoMSC> logging level rr debug

OsmoMSC> logging filter all 1

</pre>

You will see logging output on your telnet console immediately. Note that the VTY prompt is still listening, so you may at any time issue 'logging filter all 0' to switch off logging, and be able to type commands without being cluttered by ongoing log output.