Project

General

Profile

Actions
History

Wiki » Configuration Guide »

OsmoNITB Migration Guide

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, but see also the Pros and Cons.

Creating a new Network In The Box from scratch is described at Osmocom Network In The Box, please refer to that page to complement the descriptions found here.

This page aims at describing the steps necessary to move from a working operation of osmo-nitb to the new split components.

Pros and Cons

Features currently not present in the new split components:

  • In osmo-nitb we could easily log/query which BTS and which timeslot a subscriber was served on. Now you need to ask (each) BSC for that and correlate phone number to TMSI manually. We may want to add Osmocom-specific TLVs to the A interface in order to communicate that information to OsmoMSC and re-enable the old feature set. Related:
  • We currently cannot provide Osmocom specific TLVs in SMPP messages, which used to provide information only available on the BSC layer. https://osmocom.org/issues/2390

Things you get from the split repositories:

  • Same subscriber database for CS and PS (OsmoHLR).
  • No blocking of the core network while accessing the db = more scalable.
  • Support for 3G.
  • Support for Milenage (UMTS authentication).
  • Support of a true A interface between BSC and MSC.
  • You're set up for the future: new development focuses here, hardly any effort will be spent on OsmoNITB (without explicit requests and funding).

Components

The OsmoNITB combined the BSC, MSC+VLR, HLR and MGW. In the new setup, SCCP/M3UA is spoken between BSC, MSC and SGSN, and OsmoSTP is used to route messages between them. On a system where OsmoNITB is installed, to replace it, you need to install these components:

apt-get install osmo-bsc osmo-stp osmo-mgw osmo-msc osmo-hlr

Subscriber Database

With OsmoHLR comes osmo-hlr-db-tool, which is capable of importing the most important subscriber data from a database that was used with OsmoNITB.

In a standard installation, the osmo-nitb database should be found at /var/lib/osmocom/hlr.sqlite3, and the osmo-hlr database is expected at /var/lib/osmocom/hlr.db. Hence the migration command becomes:

osmo-hlr-db-tool --database /var/lib/osmocom/hlr.db import-nitb-db /var/lib/osmocom/hlr.sqlite3

If no --database is passed, ./hlr.db is assumed.
If the target hlr.db does not exist yet, it is created.

You may repeat / combine imports to the same hlr.db; any subscribers that already exist will be skipped with an error message. It is possible to do an import while osmo-hlr is actively using the database, but that is not recommended.

Take care that the resulting hlr.db has the proper read and write permissions by the user that will run OsmoHLR. Probably, the same ownership and permissions that the previous OsmoNITB database had is the correct choice.

Note that not all information is copied to the hlr.db, so far just IMSI, MSISDN and 2G auth tokens are migrated -- check the osmo-hlr-db-tool cmdline help to find out what exactly is migrated at the time you're reading this.

To avoid future confusion, it may be desirable to remove the legacy hlr.sqlite3 from the system (i.e. backup to somewhere else), or rename it to something like osmo-nitb.db, so that it is not mistaken for the OsmoHLR database.

Configuration Files

Most of the current OsmoNITB config options still exist, but are now moved to OsmoMSC or OsmoBSC. Few are required in both.

New configuration is available to set up:
  • the GSUP connection from OsmoMSC to the OsmoHLR, and
  • the SCCP connection for the A-interface between OsmoBSC and OsmoMSC, established via OsmoSTP.

Let's take this standard OsmoNITB configuration and split it up in OsmoBSC and OsmoMSC parts:

OsmoNITB config:

# ---------- to OsmoBSC:
e1_input
 e1_line 0 driver ipa
 ipa bind 10.42.42.2
# ---------- to both OsmoBSC and OsmoMSC:
network
 network country code 901
 mobile network code 70
 short name my-nitb
 long name my-nitb
 location updating reject cause 13
 encryption a5 0
 # ---------- to OsmoMSC only:
 auth policy closed
 mm info 1
 # ---------- to OsmoBSC only:
 neci 1
 rrlp mode none
 handover 0
 handover window rxlev averaging 10
 handover window rxqual averaging 1
 handover window rxlev neighbor averaging 10
 handover power budget interval 6
 handover power budget hysteresis 3
 handover maximum distance 9999
 bts 0
  type sysmobts
  band GSM-1800
  cell_identity 0
  location_area_code 23
  training_sequence_code 7
  base_station_id_code 63
  ms max power 33
  cell reselection hysteresis 4
  rxlev access min 0
  channel allocator ascending
  rach tx integer 9
  rach max transmission 7
  ip.access unit_id 1 0
  oml ip.access stream_id 255 line 0
  gprs mode none
  trx 0
   rf_locked 0
   arfcn 868
   nominal power 23
   max_power_red 0
   rsl e1 tei 0
   timeslot 0
    phys_chan_config CCCH+SDCCH4
   timeslot 1
    phys_chan_config SDCCH8
   timeslot 2
    phys_chan_config TCH/F
   timeslot 3
    phys_chan_config TCH/F
   timeslot 4
    phys_chan_config TCH/F
   timeslot 5
    phys_chan_config TCH/F
   timeslot 6
    phys_chan_config TCH/F
   timeslot 7
    phys_chan_config TCH/F
# ---------- to OsmoMSC:
smpp
 local-tcp-ip 10.42.42.2 2775
 system-id test-nitb
 policy closed

OsmoBSC config

To above snippets from the OsmoNITB config, you may want to add a 'cs7 instance' section to configure the SCCP point codes and connection to the OsmoSTP. Note that if omitted, default values apply.

You also need to add an 'msc' section to tell OsmoBSC where to reach the MSC.

additions to OsmoBSC's config:

cs7 instance 0
 point-code 0.0.2
 sccp-address msc_remote
  point-code 0.0.1
msc
 msc-addr msc_remote

You need to drop these sections from OsmoBSC:

  • 'auth policy'
  • 'authorized-regexp'
  • 'authentication'
  • 'mm-info'

This should give you an OsmoBSC config file like:

OsmoBSC config:

e1_input
 e1_line 0 driver ipa
 ipa bind 10.42.42.5
cs7 instance 1
 point-code 0.0.2
 sccp-address msc_remote
  point-code 0.0.1
msc
 ! 'msc_remote' is an address book entry defined above under 'cs7'
 msc-addr msc_remote
network
 network country code 901
 mobile network code 70
 short name my-bsc
 long name my-bsc
 location updating reject cause 13
 encryption a5 0
 neci 1
 rrlp mode none
 handover 0
 handover window rxlev averaging 10
 handover window rxqual averaging 1
 handover window rxlev neighbor averaging 10
 handover power budget interval 6
 handover power budget hysteresis 3
 handover maximum distance 9999
 bts 0
  type sysmobts
  band GSM-1800
  cell_identity 0
  location_area_code 23
  training_sequence_code 7
  base_station_id_code 63
  ms max power 33
  cell reselection hysteresis 4
  rxlev access min 0
  channel allocator ascending
  rach tx integer 9
  rach max transmission 7
  ip.access unit_id 1 0
  oml ip.access stream_id 255 line 0
  gprs mode none
  trx 0
   rf_locked 0
   arfcn 868
   nominal power 23
   max_power_red 0
   rsl e1 tei 0
   timeslot 0
    phys_chan_config CCCH+SDCCH4
   timeslot 1
    phys_chan_config SDCCH8
   timeslot 2
    phys_chan_config TCH/F
   timeslot 3
    phys_chan_config TCH/F
   timeslot 4
    phys_chan_config TCH/F
   timeslot 5
    phys_chan_config TCH/F
   timeslot 6
    phys_chan_config TCH/F
   timeslot 7
    phys_chan_config TCH/F

OsmoMSC config

To the MSC bits copied from OsmoNITB, you may want to add:

  • a 'cs7 instance' section to configure the SCCP point codes and connection to the OsmoSTP. Note that if omitted, default values apply.
  • an 'hlr' section if your OsmoHLR is not running on localhost.
  • an 'msc' section to indicate where to reach the MGW, if it is not on localhost.
cs7 instance 0
 point-code 0.0.1
hlr
 remote-ip 10.42.42.2
msc
 mgcpgw remote-ip 10.42.42.3

You will now use an external HLR to manage the subscriber database, hence change to 'auth policy remote'.

This should give you an OsmoMSC config file like:

OsmoMSC config:

cs7 instance 0
 point-code 0.0.1
msc
 mgcpgw remote-ip 10.42.42.3
hlr
 remote-ip 10.42.42.2
network
 network country code 901
 mobile network code 70
 mm info 1
 short name my-msc
 long name my-msc
 auth policy remote
 location updating reject cause 13
 encryption a5 0
 authentication optional
smpp
 local-tcp-ip 10.42.42.4 2775
 system-id test-msc
 policy closed

Service Files

TODO

Updated by laforge almost 3 years ago · 26 revisions

Add picture from clipboard (Maximum size: 48.8 MB)