Project

General

Profile

Osmocom Network In The Box » History » Version 77

« Previous - Version 77/85 (diff) - Next » - Current version
neels, 11/12/2017 11:23 PM


WIP

This wiki page is still new and in an alpha state. We're still checking whether it is consistent and contains all the important information.
(status: 2G voice and data is verified to work; 3G pending)

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.

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.

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" or CS) and data ("packet-switched" or PS) services.

Here is a table of the components you need:

Required for Program Description
2G 3G
CS PS CS PS
OsmoHLR Home Location Register, stores subscriber IMSI, phone number and auth tokens.
(1) (1) 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.
(1) 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.
✔ (2) ✔ (2) 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.
(1) OsmoBTS for 2G networks, drives the TRX and ties to the BSC via Abis-interface.
OsmoPCU for 2G networks, a component closely tied to the BTS, drives the TRX for PS timeslots and ties to the SGSN via Gb-interface.
hNodeb 3rd party 3G femto cell hardware to connect to OsmoHNBGW via Iuh

1: PS is always an addition to CS: even though these components do not handle PS requests, you need to have these to be able to setup and register with a network, which is a prerequisite for data services.

2: For the GGSN to successfully route packets to an internet uplink, it needs a tun device set up and usually IP masquerading/forwarding enabled. Please refer to the OsmoGGSN manual for more details.

Topology

Have to Know

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

Osmocom offers 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 from 3rd party programs.

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

Configuration Examples

OsmoHLR

Home Location Register, stores subscriber IMSI, phone number and auth tokens. This is where you configure who is allowed on your network and who has which phone number.

osmo-hlr will automatically bootstrap an empty subscriber database. See the manual on how to add one or more subscribers -- if you don't know your IMSI, it can be useful to attempt a connection and watch the OsmoHLR log for a rejected IMSI. To migrate subscribers from an older OsmoNITB database, see the OsmoNITB migration guide.

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 with MSC and SGSN on the same machine as the HLR.

osmo-hlr.cfg

# empty, the defaults are sufficient

OsmoMSC

Mobile Switching Center, handles signalling, i.e. attach/detach of subscribers, call establishment, messaging (SMS and USSD). The OsmoMSC is your central "manager" of the network.

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, OsmoMSC 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 (see OsmoMGW below).

You only need to set up your MCC, MNC, and how to reach/use the MGW.

osmo-msc.cfg

network
 network country code 901
 mobile network code 70
msc
 mgw remote-ip 192.168.0.5
 mgw endpoint-range 1 32

OsmoMGW

Media Gateway, is instructed by the MSC and/or the BSC to direct RTP streams for active voice calls. The Media Gateway receives instructions in the form of MGCP messages from OsmoMSC/OsmoBSC. It forwards RTP streams directly between BTS, femto cells and remote endpoints, e.g. other MGW instances, and its job is to transcode between codecs (future).

You need an OsmoMGW to serve OsmoMSC's MGCP requests, and an OsmoMGW to serve OsmoBSC's MGCP requests. In fact, these two can be served by one single OsmoMGW instance. If you would like to keep two separate OsmoMGW instances, you need to take care that they don't attempt to bind to identical ports on the same IP address (for MGCP, but also for VTY and CTRL interfaces).

Consider that you have a 2G network with an external BTS (say a sysmoBTS), which means that you need your OsmoBSC's MGW instance to be reachable on a public interface. So far the MSC's MGW can be on a local loopback interface, it only needs to be reachable by the BSC's MGW and by the MSC.

If you also have a 3G femto cell, then the MSC's MGW instance also needs to be on a public interface. At this point you either need two public interface addresses, or you need to put one of the MGWs on a different MGCP port.

If you use one OsmoMGW for both BSC and MSC, there are no port conflicts, but you need to take care that MSC and BSC use differing endpoint identifiers, or they will interfere with each others' RTP stream configurations.

To increase the likelihood that your first setup will work out, below examples pick distinct endpoint ranges so that MSC and BSC could use the same MGW instance, while at the same time provide config files that allow running two MGWs on the same public IP address.

OsmoMGW for OsmoMSC

NOTE: Currently, OsmoMSC still requires the legacy osmo-bsc_mgcp program, which will move to the new osmo-mgw soon. osmo-bsc_mgcp is still available from osmo-mgw.git. For osmo-bsc_mgcp, you can use the identical config as shown for the MSC's MGW here.

  • 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), which is the default, and your config file may omit the 'bind ip'.
  • With a separate BTS and/or RNC (e.g. 3G femto cell or nanoBTS), make sure to configure an IP address that is reachable by the hNodeB and BTS:

osmo-mgw-for-msc.cfg

mgcp
 bind ip 192.168.0.5
 number endpoints 64

OsmoMGW for OsmoBSC

OsmoBSC also requires an OsmoMGW instance to run alongside it. In a setup where OsmoBSC and OsmoMGW run on the same box, they may in fact share the same OsmoMGW instance, as long as BSC and MSC use different endpoint identifiers.

It is semantically more clear to run a separate OsmoMGW instance for the OsmoBSC, which then needs to not interfere with the other MGW's ports, for example:

osmo-mgw-for-bsc.cfg

mgcp
 bind ip 192.168.0.5
 # default port, used for MSC's MGW, is 2427
 bind port 12427
 number endpoints 64
line vty
 # default VTY interface, used for MSC's MGW, is 127.0.0.1
 bind 127.0.0.2

Note that osmo-bsc.cfg below sets the 'mgw remote-port' to the 'bind port' configured here (the method to run two MGW on the same public IP address), and picks a different 'mgw endpoint' range than the OsmoMSC (the method to use the same MGW for both BSC and MSC) -- these are two separate, redundant measures, and you usually would pick only one of them.

OsmoSTP

Signal Transfer Point, acts as a server for routing SCCP 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

cs7 instance 0
 xua rkm routing-key-allocation dynamic-permitted
 listen m3ua 2905
  accept-asp-connections dynamic-permitted

OsmoBSC

2G Base Station Controller, manages logical channels and other lower level aspects for one or more 2G BTS. The BSC tells the MSC what the phones would like to do, and in turn the MSC tells the BSC to establish channels, page phones, and take care of the lower level BTS maintenance.

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

OsmoBSC needs to contact an OsmoMGW to direct RTP streams between BTS and the MSC's MGW, as discussed above under "OsmoMGW".

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

network
 network country code 901
 mobile network code 70
 mm info 1
 short name OsmoBSC
 long name OsmoBSC
 bts 0
  type sysmobts
  band GSM-1800
  location_area_code 23
  ip.access unit_id 1800 0
  trx 0
   rf_locked 0
   arfcn 868
   nominal power 23
   max_power_red 20
   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
e1_input
 e1_line 0 driver ipa
msc 0
 mgw remote-ip 192.168.0.5
 mgw remote-port 12427
 mgw endpoint-range 33 64
 allow-emergency deny
 codec-list hr3

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, 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

network
 network country code 901
 mobile network code 70
 mm info 1
 short name OsmoBSC
 long name OsmoBSC
 bts 0
  type sysmobts
  band GSM-1800
  location_area_code 23
  ip.access unit_id 1800 0
  gprs mode gprs
  gprs nsvc 0 remote ip 192.168.0.5
  gprs nsvc 0 remote udp port 23000
  gprs nsvc 0 local udp port 23000
  gprs nsvc 0 nsvci 1800
  gprs nsei 1800
  gprs cell bvci 1800
  no force-combined-si
  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
e1_input
 e1_line 0 driver ipa
msc 0
 mgw remote-ip 192.168.0.5
 mgw remote-port 12427
 mgw endpoint-range 33 64
 allow-emergency deny
 codec-list hr3

OsmoHNBGW

3G HomeNodeB Gateway, receives the Iuh protocol from a 3G femto cell, separates it into IuCS and IuPS and forwards to the MSC and SGSN.

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

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.5
 iucs
  remote-addr msc
 iups
  remote-addr sgsn

OsmoGGSN

Gateway GPRS Support Node, "opens" GTP tunnels received from SGSNs to internet uplink. 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.

Note that the APN named in this config file (here "internet") needs to be configured on your phone, see APN for Data Service below.

osmo-ggsn.cfg

ggsn ggsn0
 gtp bind-ip 127.0.0.2
 apn internet
  tun-device tun4
  type-support v4
  ip dns 0 192.168.0.1
  ip dns 1 8.8.8.8
  ip ifconfig 192.168.42.0/24
  ip prefix dynamic 192.168.42.0/24
 no shutdown ggsn

OsmoSGSN

Serving GPRS Support Node, handles signalling, i.e. attach/detach of subscribers and PDP contexts for data services.

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

sgsn
 gtp local-ip 192.168.0.5
 ggsn 0 remote-ip 127.0.0.2
 ggsn 0 gtp-version 1
 auth-policy accept-all
 gsup remote-ip 127.0.0.1
ns
 encapsulation udp local-ip 192.168.0.5
 encapsulation udp local-port 23000
 encapsulation framerelay-gre enabled 0

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:

systemctl restart osmo-hlr
systemctl stop osmo-hlr

It can be useful to have an osmo-all script to re/start or stop all components at once, edit to pick yours:

osmo-all script

#!/bin/sh
cmd="${1:-start}" 
set -ex
systemctl $cmd osmo-hlr osmo-msc osmo-mgw osmo-ggsn osmo-sgsn osmo-stp osmo-bsc osmo-hnbgw osmo-bts-sysmo osmo-pcu 

which allows

./osmo-all restart
./osmo-all status
./osmo-all stop

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

osmo-hlr -l hlr.db -c osmo-hlr.cfg
osmo-msc -c osmo-msc.cfg
osmo-mgw -c osmo-mgw-for-msc.cfg
osmo-mgw -c osmo-mgw-for-bsc.cfg
osmo-ggsn -c osmo-ggsn.cfg
osmo-sgsn -c osmo-sgsn.cfg
osmo-stp -c osmo-stp.cfg
osmo-bsc -c osmo-bsc.cfg
osmo-hnbgw -c osmo-hnbgw.cfg
# on a 2G sysmoBTS:
osmo-bts-sysmo -c osmo-bts.cfg -s -M
osmo-pcu -c osmo-pcu.cfg

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:

journalctl -f -u osmo-hlr

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'; you may also need to 'systemctl unmask systemd-journald.service systemd-jounald.socket'. Logging will only start appearing for components that were restarted after these changes.

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:

$ 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)
  [...]
OsmoMSC> logging level all ?
everything debug      info       notice     error      fatal      
OsmoMSC> logging level all debug 
OsmoMSC> logging filter all 1

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.

Troubleshooting

APN for Data Service

For the data service to work, phones generally need an APN added to their
configuration, or they will not even attempt to establish a data connection.
The APN should match the name configured in osmo-ggsn.conf.

The APN configuration steps are usually similar to:

  • Navigate to APN settings:
    • 'Settings'
    • 'Wireless & Networks'
    • 'Mobile networks'
    • 'Access Point Names'
  • You should see the list of APNs (possibly empty)
  • Press the Menu button
  • Choose 'New APN'
  • Enter values for 'Name' as well as 'APN'
  • Again press the Menu button
  • Choose 'Save'
  • The APN should now appear in the list of APNs.
  • Possibly tap the bullet icon to select the APN as default.

nitb.tar - example configuration files (20 KB) neels, 11/23/2017 12:42 AM