Project

General

Profile

OsmoNITB Migration Guide » History » Version 15

neels, 11/08/2017 02:14 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 15 neels
h1. Components
12 15 neels
13 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:
14 15 neels
15 15 neels
<pre>apt-get install osmo-bsc osmo-stp osmo-bsc-mgcp osmo-mgw osmo-hlr</pre>
16 15 neels
17 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.*
18 15 neels
19 15 neels
Refer to [[Osmocom Network In The Box]] for more details.
20 15 neels
21 2 neels
h1. Subscriber Database
22 2 neels
23 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.
24 4 neels
25 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:
26 5 neels
27 1 neels
<pre>
28 14 lynxis
osmo-hlr-db-tool --database /var/lib/osmocom/hlr.db import-nitb-db /var/lib/osmocom/hlr.sqlite3
29 4 neels
</pre>
30 4 neels
31 8 neels
If no @--database@ is passed, @./hlr.db@ is assumed.
32 1 neels
If the target @hlr.db@ does not exist yet, it is created.
33 8 neels
If no @--import-nitb-db@ is passed, a @hlr.db@ without any subscriber data is created.
34 8 neels
35 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.
36 8 neels
37 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.
38 4 neels
39 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.
40 5 neels
41 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.
42 2 neels
43 2 neels
h1. Configuration Files
44 2 neels
45 6 neels
Most of the current OsmoNITB config options still exist, but are now moved to OsmoMSC or OsmoBSC. Few are required in both.
46 6 neels
47 9 neels
New configuration is available to set up:
48 9 neels
* the GSUP connection from OsmoMSC to the OsmoHLR, and
49 9 neels
* the SCCP connection for the A-interface between OsmoBSC and OsmoMSC, established via OsmoSTP.
50 2 neels
51 10 neels
Let's take this standard OsmoNITB configuration and split it up in OsmoBSC and OsmoMSC parts:
52 10 neels
53 10 neels
*OsmoNITB config*:
54 10 neels
<pre>
55 11 neels
# ---------- to OsmoBSC:
56 10 neels
e1_input
57 10 neels
 e1_line 0 driver ipa
58 10 neels
 ipa bind 10.42.42.2
59 11 neels
# ---------- to both OsmoBSC and OsmoMSC:
60 10 neels
network
61 10 neels
 network country code 901
62 10 neels
 mobile network code 70
63 10 neels
 short name osmo-gsm-tester-nitb
64 10 neels
 long name osmo-gsm-tester-nitb
65 10 neels
 auth policy closed
66 10 neels
 location updating reject cause 13
67 10 neels
 encryption a5 0
68 11 neels
 # ---------- to OsmoBSC:
69 10 neels
 neci 1
70 10 neels
 rrlp mode none
71 10 neels
 mm info 1
72 10 neels
 handover 0
73 10 neels
 handover window rxlev averaging 10
74 10 neels
 handover window rxqual averaging 1
75 10 neels
 handover window rxlev neighbor averaging 10
76 10 neels
 handover power budget interval 6
77 10 neels
 handover power budget hysteresis 3
78 10 neels
 handover maximum distance 9999
79 10 neels
 bts 0
80 10 neels
  type sysmobts
81 10 neels
  band GSM-1800
82 10 neels
  cell_identity 0
83 10 neels
  location_area_code 23
84 10 neels
  training_sequence_code 7
85 10 neels
  base_station_id_code 63
86 10 neels
  ms max power 33
87 10 neels
  cell reselection hysteresis 4
88 10 neels
  rxlev access min 0
89 10 neels
  channel allocator ascending
90 10 neels
  rach tx integer 9
91 10 neels
  rach max transmission 7
92 10 neels
  ip.access unit_id 1 0
93 10 neels
  oml ip.access stream_id 255 line 0
94 10 neels
  gprs mode none
95 10 neels
  trx 0
96 10 neels
   rf_locked 0
97 10 neels
   arfcn 868
98 10 neels
   nominal power 23
99 10 neels
   max_power_red 0
100 10 neels
   rsl e1 tei 0
101 10 neels
   timeslot 0
102 10 neels
    phys_chan_config CCCH+SDCCH4
103 10 neels
   timeslot 1
104 10 neels
    phys_chan_config SDCCH8
105 10 neels
   timeslot 2
106 10 neels
    phys_chan_config TCH/F
107 10 neels
   timeslot 3
108 10 neels
    phys_chan_config TCH/F
109 10 neels
   timeslot 4
110 10 neels
    phys_chan_config TCH/F
111 10 neels
   timeslot 5
112 10 neels
    phys_chan_config TCH/F
113 10 neels
   timeslot 6
114 10 neels
    phys_chan_config TCH/F
115 10 neels
   timeslot 7
116 10 neels
    phys_chan_config TCH/F
117 11 neels
# ---------- to OsmoMSC:
118 10 neels
smpp
119 10 neels
 local-tcp-ip 10.42.42.2 2775
120 10 neels
 system-id test-nitb
121 10 neels
 policy closed
122 1 neels
</pre>
123 1 neels
124 11 neels
h2. OsmoBSC config
125 11 neels
126 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.
127 11 neels
128 11 neels
You also need to add an 'msc' section to tell OsmoBSC where to reach the MSC.
129 11 neels
130 11 neels
*additions to OsmoBSC's config*:
131 11 neels
<pre>
132 11 neels
cs7 instance 0
133 11 neels
 point-code 0.0.2
134 11 neels
 sccp-address msc_remote
135 11 neels
  point-code 0.0.1
136 11 neels
msc
137 11 neels
 msc-addr msc_remote
138 11 neels
</pre>
139 11 neels
140 11 neels
This should give you an OsmoBSC config file like:
141 11 neels
142 10 neels
*OsmoBSC config*:
143 10 neels
<pre>
144 10 neels
e1_input
145 1 neels
 e1_line 0 driver ipa
146 1 neels
 ipa bind 10.42.42.5
147 1 neels
cs7 instance 1
148 10 neels
 point-code 0.0.2
149 10 neels
 sccp-address msc_remote
150 10 neels
  point-code 0.0.1
151 11 neels
msc
152 11 neels
 ! 'msc_remote' is an address book entry defined above under 'cs7'
153 11 neels
 msc-addr msc_remote
154 10 neels
network
155 10 neels
 network country code 901
156 10 neels
 mobile network code 70
157 10 neels
 short name osmo-gsm-tester-msc
158 10 neels
 long name osmo-gsm-tester-msc
159 10 neels
 auth policy closed
160 10 neels
 location updating reject cause 13
161 10 neels
 encryption a5 0
162 10 neels
 authentication optional
163 10 neels
 neci 1
164 10 neels
 rrlp mode none
165 10 neels
 mm info 1
166 10 neels
 handover 0
167 10 neels
 handover window rxlev averaging 10
168 10 neels
 handover window rxqual averaging 1
169 10 neels
 handover window rxlev neighbor averaging 10
170 10 neels
 handover power budget interval 6
171 10 neels
 handover power budget hysteresis 3
172 10 neels
 handover maximum distance 9999
173 10 neels
 bts 0
174 10 neels
  type sysmobts
175 10 neels
  band GSM-1800
176 10 neels
  cell_identity 0
177 10 neels
  location_area_code 23
178 10 neels
  training_sequence_code 7
179 10 neels
  base_station_id_code 63
180 10 neels
  ms max power 33
181 10 neels
  cell reselection hysteresis 4
182 10 neels
  rxlev access min 0
183 10 neels
  channel allocator ascending
184 10 neels
  rach tx integer 9
185 10 neels
  rach max transmission 7
186 10 neels
  ip.access unit_id 1 0
187 10 neels
  oml ip.access stream_id 255 line 0
188 10 neels
  gprs mode none
189 10 neels
  trx 0
190 10 neels
   rf_locked 0
191 10 neels
   arfcn 868
192 10 neels
   nominal power 23
193 10 neels
   max_power_red 0
194 10 neels
   rsl e1 tei 0
195 10 neels
   timeslot 0
196 10 neels
    phys_chan_config CCCH+SDCCH4
197 10 neels
   timeslot 1
198 10 neels
    phys_chan_config SDCCH8
199 10 neels
   timeslot 2
200 10 neels
    phys_chan_config TCH/F
201 10 neels
   timeslot 3
202 1 neels
    phys_chan_config TCH/F
203 10 neels
   timeslot 4
204 10 neels
    phys_chan_config TCH/F
205 1 neels
   timeslot 5
206 1 neels
    phys_chan_config TCH/F
207 1 neels
   timeslot 6
208 1 neels
    phys_chan_config TCH/F
209 1 neels
   timeslot 7
210 1 neels
    phys_chan_config TCH/F
211 11 neels
</pre>
212 11 neels
213 11 neels
h2. OsmoMSC config
214 11 neels
215 11 neels
To the MSC bits copied from OsmoNITB, you may want to add:
216 11 neels
217 11 neels
* a 'cs7 instance' section to configure the SCCP point codes and connection to the OsmoSTP. Note that if omitted, default values apply.
218 11 neels
* an 'hlr' section if your OsmoHLR is not running on localhost.
219 11 neels
* an 'msc' section to indicate where to reach the MGW, if it is not on localhost.
220 11 neels
221 11 neels
<pre>
222 11 neels
cs7 instance 0
223 11 neels
 point-code 0.0.1
224 11 neels
hlr
225 11 neels
 remote-ip 10.42.42.2
226 10 neels
msc
227 11 neels
 mgcpgw remote-ip 10.42.42.3
228 10 neels
</pre>
229 10 neels
230 11 neels
This should give you an OsmoMSC config file like:
231 11 neels
232 10 neels
*OsmoMSC config*:
233 11 neels
234 10 neels
<pre>
235 12 neels
cs7 instance 0
236 12 neels
 point-code 0.0.1
237 12 neels
msc
238 12 neels
 mgcpgw remote-ip 10.42.42.3
239 12 neels
hlr
240 12 neels
 remote-ip 10.42.42.2
241 10 neels
network
242 10 neels
 network country code 901
243 10 neels
 mobile network code 70
244 10 neels
 short name osmo-gsm-tester-msc
245 10 neels
 long name osmo-gsm-tester-msc
246 10 neels
 auth policy closed
247 10 neels
 location updating reject cause 13
248 10 neels
 encryption a5 0
249 10 neels
 authentication optional
250 10 neels
smpp
251 10 neels
 local-tcp-ip 10.42.42.4 2775
252 10 neels
 system-id test-msc
253 2 neels
 policy closed
254 2 neels
</pre>
255 2 neels
256 1 neels
h1. Service Files
257 1 neels
258 1 neels
TODO