Project

General

Profile

OsmoNITB Migration Guide » History » Version 19

neels, 12/08/2017 10:59 PM

1 3 neels
{{>toc}}
2 3 neels
3 1 neels
h1. OsmoNITB Migration Guide
4 1 neels
5 2 neels
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.
6 2 neels
7 2 neels
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.
8 2 neels
9 2 neels
This page aims at describing the steps necessary to move from a working operation of osmo-nitb to the new split components.
10 2 neels
11 19 neels
h1. Pros and Cons
12 19 neels
13 19 neels
Features currently *not* present in the new split components:
14 19 neels
15 19 neels
* No subscriber-create-on-demand, i.e. you have to explicitly enter all subscribers' IMSIs in the HLR before they are accepted by the network. The database will not grow automatically. https://osmocom.org/issues/2542
16 19 neels
17 19 neels
* 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:
18 19 neels
19 19 neels
* 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
20 19 neels
21 19 neels
Things you *get* from the split repositories:
22 19 neels
23 19 neels
* Same subscriber database for CS and PS (OsmoHLR).
24 19 neels
* No blocking of the core network while accessing the db = more scalable.
25 19 neels
* Support for 3G.
26 19 neels
* Support for Milenage (UMTS authentication).
27 19 neels
* Support of a true A interface between BSC and MSC.
28 19 neels
* You're set up for the future: new development focuses here, hardly any effort will be spent on OsmoNITB (without explicit requests and funding).
29 19 neels
30 19 neels
31 15 neels
h1. Components
32 15 neels
33 15 neels
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:
34 15 neels
35 15 neels
<pre>apt-get install osmo-bsc osmo-stp osmo-bsc-mgcp osmo-mgw osmo-hlr</pre>
36 15 neels
37 15 neels
*NOTE: at the time of writing, you need to use osmo-bsc-mgcp, but this should move to osmo-mgw in a matter of weeks.*
38 15 neels
39 2 neels
h1. Subscriber Database
40 2 neels
41 4 neels
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.
42 4 neels
43 5 neels
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:
44 5 neels
45 1 neels
<pre>
46 14 lynxis
osmo-hlr-db-tool --database /var/lib/osmocom/hlr.db import-nitb-db /var/lib/osmocom/hlr.sqlite3
47 4 neels
</pre>
48 4 neels
49 8 neels
If no @--database@ is passed, @./hlr.db@ is assumed.
50 1 neels
If the target @hlr.db@ does not exist yet, it is created.
51 8 neels
52 8 neels
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.
53 8 neels
54 8 neels
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.
55 4 neels
56 13 neels
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.
57 5 neels
58 5 neels
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.
59 2 neels
60 2 neels
h1. Configuration Files
61 2 neels
62 6 neels
Most of the current OsmoNITB config options still exist, but are now moved to OsmoMSC or OsmoBSC. Few are required in both.
63 6 neels
64 9 neels
New configuration is available to set up:
65 9 neels
* the GSUP connection from OsmoMSC to the OsmoHLR, and
66 9 neels
* the SCCP connection for the A-interface between OsmoBSC and OsmoMSC, established via OsmoSTP.
67 2 neels
68 10 neels
Let's take this standard OsmoNITB configuration and split it up in OsmoBSC and OsmoMSC parts:
69 10 neels
70 10 neels
*OsmoNITB config*:
71 10 neels
<pre>
72 11 neels
# ---------- to OsmoBSC:
73 10 neels
e1_input
74 10 neels
 e1_line 0 driver ipa
75 10 neels
 ipa bind 10.42.42.2
76 11 neels
# ---------- to both OsmoBSC and OsmoMSC:
77 10 neels
network
78 10 neels
 network country code 901
79 10 neels
 mobile network code 70
80 18 neels
 short name my-nitb
81 18 neels
 long name my-nitb
82 1 neels
 location updating reject cause 13
83 10 neels
 encryption a5 0
84 18 neels
 # ---------- to OsmoMSC only:
85 18 neels
 auth policy closed
86 18 neels
 # ---------- to OsmoBSC only:
87 10 neels
 neci 1
88 10 neels
 rrlp mode none
89 10 neels
 mm info 1
90 10 neels
 handover 0
91 10 neels
 handover window rxlev averaging 10
92 10 neels
 handover window rxqual averaging 1
93 10 neels
 handover window rxlev neighbor averaging 10
94 10 neels
 handover power budget interval 6
95 10 neels
 handover power budget hysteresis 3
96 10 neels
 handover maximum distance 9999
97 10 neels
 bts 0
98 10 neels
  type sysmobts
99 10 neels
  band GSM-1800
100 10 neels
  cell_identity 0
101 10 neels
  location_area_code 23
102 10 neels
  training_sequence_code 7
103 10 neels
  base_station_id_code 63
104 10 neels
  ms max power 33
105 10 neels
  cell reselection hysteresis 4
106 10 neels
  rxlev access min 0
107 10 neels
  channel allocator ascending
108 10 neels
  rach tx integer 9
109 10 neels
  rach max transmission 7
110 10 neels
  ip.access unit_id 1 0
111 10 neels
  oml ip.access stream_id 255 line 0
112 10 neels
  gprs mode none
113 10 neels
  trx 0
114 10 neels
   rf_locked 0
115 10 neels
   arfcn 868
116 10 neels
   nominal power 23
117 10 neels
   max_power_red 0
118 10 neels
   rsl e1 tei 0
119 10 neels
   timeslot 0
120 10 neels
    phys_chan_config CCCH+SDCCH4
121 10 neels
   timeslot 1
122 10 neels
    phys_chan_config SDCCH8
123 10 neels
   timeslot 2
124 10 neels
    phys_chan_config TCH/F
125 10 neels
   timeslot 3
126 10 neels
    phys_chan_config TCH/F
127 10 neels
   timeslot 4
128 10 neels
    phys_chan_config TCH/F
129 10 neels
   timeslot 5
130 10 neels
    phys_chan_config TCH/F
131 10 neels
   timeslot 6
132 10 neels
    phys_chan_config TCH/F
133 10 neels
   timeslot 7
134 10 neels
    phys_chan_config TCH/F
135 11 neels
# ---------- to OsmoMSC:
136 10 neels
smpp
137 10 neels
 local-tcp-ip 10.42.42.2 2775
138 10 neels
 system-id test-nitb
139 10 neels
 policy closed
140 1 neels
</pre>
141 1 neels
142 11 neels
h2. OsmoBSC config
143 11 neels
144 11 neels
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.
145 11 neels
146 11 neels
You also need to add an 'msc' section to tell OsmoBSC where to reach the MSC.
147 11 neels
148 11 neels
*additions to OsmoBSC's config*:
149 11 neels
<pre>
150 11 neels
cs7 instance 0
151 11 neels
 point-code 0.0.2
152 11 neels
 sccp-address msc_remote
153 11 neels
  point-code 0.0.1
154 1 neels
msc
155 1 neels
 msc-addr msc_remote
156 1 neels
</pre>
157 1 neels
158 18 neels
You need to drop these sections from OsmoBSC:
159 18 neels
160 18 neels
* 'auth policy'
161 18 neels
* 'authorized-regexp'
162 18 neels
* 'authentication'
163 18 neels
164 11 neels
This should give you an OsmoBSC config file like:
165 11 neels
166 10 neels
*OsmoBSC config*:
167 10 neels
<pre>
168 10 neels
e1_input
169 1 neels
 e1_line 0 driver ipa
170 10 neels
 ipa bind 10.42.42.5
171 10 neels
cs7 instance 1
172 11 neels
 point-code 0.0.2
173 11 neels
 sccp-address msc_remote
174 1 neels
  point-code 0.0.1
175 1 neels
msc
176 10 neels
 ! 'msc_remote' is an address book entry defined above under 'cs7'
177 10 neels
 msc-addr msc_remote
178 10 neels
network
179 10 neels
 network country code 901
180 10 neels
 mobile network code 70
181 18 neels
 short name my-bsc
182 18 neels
 long name my-bsc
183 10 neels
 location updating reject cause 13
184 10 neels
 encryption a5 0
185 10 neels
 neci 1
186 10 neels
 rrlp mode none
187 10 neels
 mm info 1
188 10 neels
 handover 0
189 10 neels
 handover window rxlev averaging 10
190 10 neels
 handover window rxqual averaging 1
191 10 neels
 handover window rxlev neighbor averaging 10
192 10 neels
 handover power budget interval 6
193 10 neels
 handover power budget hysteresis 3
194 10 neels
 handover maximum distance 9999
195 10 neels
 bts 0
196 10 neels
  type sysmobts
197 10 neels
  band GSM-1800
198 10 neels
  cell_identity 0
199 10 neels
  location_area_code 23
200 10 neels
  training_sequence_code 7
201 10 neels
  base_station_id_code 63
202 10 neels
  ms max power 33
203 10 neels
  cell reselection hysteresis 4
204 10 neels
  rxlev access min 0
205 10 neels
  channel allocator ascending
206 10 neels
  rach tx integer 9
207 10 neels
  rach max transmission 7
208 10 neels
  ip.access unit_id 1 0
209 10 neels
  oml ip.access stream_id 255 line 0
210 10 neels
  gprs mode none
211 10 neels
  trx 0
212 10 neels
   rf_locked 0
213 10 neels
   arfcn 868
214 10 neels
   nominal power 23
215 10 neels
   max_power_red 0
216 10 neels
   rsl e1 tei 0
217 10 neels
   timeslot 0
218 10 neels
    phys_chan_config CCCH+SDCCH4
219 10 neels
   timeslot 1
220 10 neels
    phys_chan_config SDCCH8
221 10 neels
   timeslot 2
222 10 neels
    phys_chan_config TCH/F
223 10 neels
   timeslot 3
224 1 neels
    phys_chan_config TCH/F
225 10 neels
   timeslot 4
226 10 neels
    phys_chan_config TCH/F
227 1 neels
   timeslot 5
228 1 neels
    phys_chan_config TCH/F
229 1 neels
   timeslot 6
230 1 neels
    phys_chan_config TCH/F
231 1 neels
   timeslot 7
232 1 neels
    phys_chan_config TCH/F
233 11 neels
</pre>
234 11 neels
235 11 neels
h2. OsmoMSC config
236 11 neels
237 11 neels
To the MSC bits copied from OsmoNITB, you may want to add:
238 11 neels
239 11 neels
* a 'cs7 instance' section to configure the SCCP point codes and connection to the OsmoSTP. Note that if omitted, default values apply.
240 11 neels
* an 'hlr' section if your OsmoHLR is not running on localhost.
241 11 neels
* an 'msc' section to indicate where to reach the MGW, if it is not on localhost.
242 11 neels
243 11 neels
<pre>
244 1 neels
cs7 instance 0
245 1 neels
 point-code 0.0.1
246 11 neels
hlr
247 11 neels
 remote-ip 10.42.42.2
248 11 neels
msc
249 11 neels
 mgcpgw remote-ip 10.42.42.3
250 10 neels
</pre>
251 11 neels
252 18 neels
You will now use an external HLR to manage the subscriber database, hence change to 'auth policy remote'.
253 18 neels
254 11 neels
This should give you an OsmoMSC config file like:
255 10 neels
256 12 neels
*OsmoMSC config*:
257 1 neels
258 1 neels
<pre>
259 1 neels
cs7 instance 0
260 12 neels
 point-code 0.0.1
261 12 neels
msc
262 12 neels
 mgcpgw remote-ip 10.42.42.3
263 12 neels
hlr
264 12 neels
 remote-ip 10.42.42.2
265 10 neels
network
266 10 neels
 network country code 901
267 10 neels
 mobile network code 70
268 18 neels
 short name my-msc
269 18 neels
 long name my-msc
270 18 neels
 auth policy remote
271 10 neels
 location updating reject cause 13
272 10 neels
 encryption a5 0
273 10 neels
 authentication optional
274 10 neels
smpp
275 10 neels
 local-tcp-ip 10.42.42.4 2775
276 10 neels
 system-id test-msc
277 2 neels
 policy closed
278 2 neels
</pre>
279 2 neels
280 1 neels
h1. Service Files
281 1 neels
282 1 neels
TODO
Add picture from clipboard (Maximum size: 48.8 MB)