Project

General

Profile

OsmoNITB Migration Guide » History » Version 24

laforge, 03/05/2018 11:24 AM

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