Project

General

Profile

Osmocom Network In The Box » History » Version 150

neels, 10/23/2019 08:48 PM

1 1 neels
h1. Osmocom Network In The Box
2 126 fixeria
3
{{>toc}}
4 1 neels
5 22 neels
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.
6 21 neels
7 146 neels
*If this documentation is inaccurate or has you stumped, let's improve it!*
8
Contact us:
9
10
* #osmocom on FreeNode IRC
11
* the openbsc@ [[Mailing Lists|mailing list]]
12
13 68 neels
h1. OsmoNITB R.I.P., long live the Network In The Box
14 1 neels
15 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.
16 1 neels
17 4 neels
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.
18 1 neels
19 2 neels
To migrate from OsmoNITB to the new separate programs, see the [[OsmoNITB Migration Guide]].
20
21 68 neels
h1. Part of this Complete Network
22 2 neels
23 32 neels
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.
24 2 neels
25 32 neels
Here is a table of the components you need:
26 1 neels
27 32 neels
|\4. *Required for*  |/3. *Program* |/3. *Description* |
28
|\2. *2G*  |\2. *3G* |
29
| *CS* | *PS* | *CS* | *PS* |
30 92 neels
| ✔ | ✔ | ✔ | ✔ | [[Osmocom Network In The Box#OsmoHLR|OsmoHLR]] | Home Location Register, stores subscriber IMSI, phone number and auth tokens. |
31 99 neels
| ✔ | (1) | ✔ (3) | (1) | [[Osmocom Network In The Box#OsmoMSC|OsmoMSC]] | Mobile Switching Center, handles signalling, i.e. attach/detach of subscribers, call establishment, messaging (SMS and USSD). |
32 92 neels
| ✔ |   | ✔ |   | [[Osmocom Network In The Box#OsmoMGW|OsmoMGW]] | Media Gateway, is instructed by the MSC and/or the BSC to direct RTP streams for active voice calls. |
33
| ✔ | ✔ | ✔ | ✔ | [[Osmocom Network In The Box#OsmoSTP|OsmoSTP]] | Signal Transfer Point, routes SCCP messages between MSC, BSC, HNBGW and for 3G also the SGSN. |
34
| ✔ | (1) |   |   | [[Osmocom Network In The Box#OsmoBSC|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". |
35
|   |   | ✔ | ✔ | [[Osmocom Network In The Box#OsmoHNBGW|OsmoHNBGW]] | 3G HomeNodeB Gateway, receives the Iuh protocol from a 3G femto cell and forwards to MSC and SGSN by SCCP/M3UA via OsmoSTP. |
36
|   | ✔ (2) |   | ✔ (2) | [[Osmocom Network In The Box#OsmoGGSN|OsmoGGSN]] | Gateway GPRS Support Node, "opens" GTP tunnels received from SGSNs to internet uplink. |
37 99 neels
|   | ✔ |   | ✔ (3) | [[Osmocom Network In The Box#OsmoSGSN|OsmoSGSN]] | Serving GPRS Support Node, handles signalling, i.e. attach/detach of subscribers and PDP contexts. |
38 92 neels
| ✔ | (1) |   |   | [[Osmocom Network In The Box#OsmoBTS|OsmoBTS]] | for 2G networks, drives the TRX and ties to the BSC via Abis-interface. |
39
|   | ✔ |   |   | [[Osmocom Network In The Box#OsmoPCU|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. |
40 37 neels
|   |   | ✔ | ✔ | hNodeb | 3rd party 3G femto cell hardware to connect to OsmoHNBGW via Iuh |
41 145 neels
|   |   |   |   | [[osmo-sip-connector|OsmoSIPConnector]] | Optional: switch OsmoMSC to external MNCC and forward Call Control and RTP to a PBX of your choice. |
42 5 neels
43 99 neels
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. That is mostly due to policy by the mobile phones, theoretically they could accept a network without voice service.
44 1 neels
45 32 neels
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.
46 99 neels
47
3: If building from source, remember to build with --enable-iu. (Our binary packages are built with --enable-iu.)
48 18 neels
49 68 neels
h2. Topology
50 55 neels
51
{{graphviz_link()
52
digraph G {
53
  rankdir = LR;
54 56 neels
  
55
  MS [label="MS\n(2G phone)"]
56
  UE [label="UE\n(3G phone)"]
57 143 neels
  PBX [label="PBX\nAsterisk, FreeSwitch,\nKamailio, Yate, ..."]
58 1 neels
59 56 neels
  subgraph cluster_bts {
60
    BTS [rank="min"]
61
    PCU [rank="min"]
62
  }
63
64
  subgraph cluster_msc_mgw {
65 59 neels
    label=MGCP;style=dotted
66 56 neels
    MSC
67 57 neels
    MGW1 [label="MGW"]
68 56 neels
  }
69
70
  subgraph cluster_bsc_mgw {
71 59 neels
    label=MGCP;style=dotted
72 56 neels
    BSC
73 57 neels
    MGW2 [label="MGW"]
74 1 neels
  }
75
76 59 neels
  hNodeB [shape="box",label="hNodeB\n(3G femto cell)"]
77
78 61 neels
  MS -> BTS [label="Um"]
79 1 neels
  MS -> PCU [style="dashed"]
80 143 neels
81 56 neels
  BTS -> BSC [label="Abis/IP"]
82 1 neels
  STP [label="STP\n(SCCP/M3UA)"]
83 56 neels
  BSC -> STP -> MSC [label="A"]
84 143 neels
  MSC -> HLR [label="\nGSUP"]
85 70 neels
  SGSN -> HLR [label="GSUP",style="dashed"]
86 62 neels
  UE -> hNodeB [label="Uu"]
87 65 neels
  UE -> hNodeB [style="dashed"]
88 56 neels
  hNodeB -> HNBGW [label="Iuh"]
89 1 neels
  HNBGW -> STP -> SGSN [label="IuPS",style="dashed"]
90 104 neels
  HNBGW -> STP -> MSC [label="IuCS"]
91 61 neels
  PCU -> SGSN [label="Gb",style="dashed"]
92 58 neels
  SGSN -> GGSN [label="GTP-C",style="dashed"]
93
  SGSN -> GGSN [label="GTP-U(2G)",style="dashed"]
94
  hNodeB -> GGSN [label="GTP-U(3G)",style="dashed"]
95
  GGSN -> internet [label="tun",style="dashed"]
96 56 neels
97 1 neels
  BTS -> MGW2 -> MGW1 [label="RTP"]
98 73 neels
  MGW1 -> MGW1 [label="RTP"]
99 143 neels
  MGW2 -> MGW2 [label="RTP (LCLS)"]
100 1 neels
  hNodeB -> MGW1 [label="IuUP/RTP"]
101
102 143 neels
  MSC -> SIPConnector [label="MNCC socket"]
103
104
  SIPConnector -> PBX [label="SIP"]
105
  MGW1 -> PBX [label="RTP"]
106
107 59 neels
  A, B, C, D [style="invisible"]
108 63 neels
  A -> B [label="data (PS)",style="dashed"]
109 103 neels
  C -> D [label="voice/SMS/USSD (CS)"]
110 1 neels
111 56 neels
}
112 143 neels
113 55 neels
}}
114
115 5 neels
h1. Have to Know
116 10 neels
117
Each program features a detailed [[Osmocom Manuals|user manual]], your primary source of information to expand on the setup described here.
118 24 laforge
119 5 neels
Osmocom offers [[Binary_Packages|compiled packages for various distributions]]. If you're up to it, you may also [[Build from Source]].
120
121
Each Osmocom program typically has
122
123 1 neels
* a distinct configuration file;
124 25 neels
* a VTY telnet console for live interaction;
125 1 neels
* a CTRL interface for live interaction from 3rd party programs.
126 18 neels
127 102 neels
See [[Port Numbers]] to find out which program runs what services on which port.
128 18 neels
129 147 neels
h1. The State of 3G Voice
130
131
IuCS doesn't talk plain RTP, it talks IuUP inside the RTP payload (!). That is another header, and the AMR bits inside that are mangled and shifted around, even though the underlying codec is still AMR. Currently, we have only stub work to decode IuUP.
132
133
The bottom line is that 3G to 3G calls work simply because we are passing the IuUP through in a hackish manner. 2G <-> 3G does not work, and 3G <-> PBX does not work. Without decoding IuUP, you will not have the slightest chance to get this working.
134
135 148 neels
There is some ongoing work, see [[3G Voice]] for the latest news.
136 147 neels
137 18 neels
h1. Configuration Examples
138 5 neels
139 83 neels
Here is a tarball of the config files discussed below: attachment:nitb.tar
140
141 6 neels
h2. OsmoHLR
142
143 127 neels
[[OsmoHLR:]] is the Home Location Register: it 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. It also handles USSD services (like "*100#").
144 67 neels
145 72 neels
osmo-hlr will automatically bootstrap an empty subscriber database. See the [[Osmocom Manuals|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]].
146 6 neels
147 50 neels
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.
148 1 neels
149 127 neels
This example optionally configures two USSD services and logging.
150
151 1 neels
*osmo-hlr.cfg* (download: attachment:nitb.tar)
152
<pre>
153 127 neels
hlr
154
 ussd route prefix *#100# internal own-msisdn
155
 ussd route prefix *#101# internal own-imsi
156
157
log stderr
158
 logging filter all 1
159
 logging print extended-timestamp 1
160
 logging print category 1
161
 logging print category-hex 0
162
 logging print level 1
163
 logging print file basename last
164 128 neels
 logging level set-all debug
165 48 neels
</pre>
166
167 97 neels
Once your HLR is running, you will want to add subscribers with authentication keys to the HLR database. Please refer to the OsmoHLR [[Osmocom Manuals]], section "Managing Subscribers".
168
169 6 neels
h2. OsmoMSC
170 1 neels
171 93 neels
[[OsmoMSC:]] is the Mobile Switching Center: it handles signalling, i.e. attach/detach of subscribers, call establishment, messaging (SMS and USSD). The OsmoMSC is your central "manager" of the network.
172 66 neels
173 6 neels
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.
174 26 neels
175 6 neels
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.
176 7 neels
177 86 neels
* There is a default point code, currently 0.23.1 (in 8.8.3 point code format, see [[Point Codes]]).
178 6 neels
* OsmoMSC will by default look for OsmoSTP on localhost's M3UA port, 2905.
179 7 neels
180 51 neels
To direct RTP streams, OsmoMSC needs an OsmoMGW instance (see OsmoMGW below).
181 38 neels
182 51 neels
You only need to set up your MCC, MNC, and how to reach/use the MGW.
183 43 neels
184 108 neels
*osmo-msc.cfg* (download: attachment:nitb.tar)
185 1 neels
<pre>
186 38 neels
network
187
 network country code 901
188 53 neels
 mobile network code 70
189
msc
190 1 neels
 mgw remote-ip 192.168.0.9
191 134 neels
 # For nano3G:
192
 iu rab-assign-addr-enc x213
193 128 neels
 
194
log stderr
195
 logging filter all 1
196
 logging print extended-timestamp 1
197
 logging print category 1
198 1 neels
 logging print category-hex 0
199 134 neels
 logging print level 1
200 128 neels
 logging print file basename last
201
 logging level set-all info
202 38 neels
</pre>
203 47 neels
204 1 neels
h2. OsmoMGW
205
206 93 neels
[[OsmoMGW:]] is the Media Gateway: it 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).
207 52 neels
208 47 neels
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).
209
210
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.
211
212
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.
213
214 105 neels
You may decide to use one OsmoMGW for both BSC and MSC, if your network topology allows.
215
(There used to be the need to separate the endpoint config for BSC and MSC, but now the MGW takes care of that automatically.)
216 47 neels
217 105 neels
To increase the likelihood that your first setup will work out, below examples pick distinct MGCP ports and VTY interfaces, which allows running two MGWs on the same public IP address.
218 47 neels
219
h3. OsmoMGW for OsmoMSC
220 1 neels
221 101 neels
OsmoMGW listens for MGCP connections, by default on port 2427.
222
223 1 neels
* 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'.
224 9 neels
* 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:
225 1 neels
226 108 neels
*osmo-mgw-for-msc.cfg* (download: attachment:nitb.tar)
227 48 neels
<pre>
228 82 neels
mgcp
229 40 neels
 bind ip 192.168.0.9
230 82 neels
line vty
231 1 neels
 bind 127.0.0.1
232 129 neels
 
233
log stderr
234
 logging filter all 1
235
 logging print extended-timestamp 1
236
 logging print category 1
237
 logging print category-hex 0
238
 logging print level 1
239
 logging print file basename last
240
 logging level set-all info
241 1 neels
</pre>
242
243 47 neels
h3. OsmoMGW for OsmoBSC
244 1 neels
245 130 neels
OsmoBSC also requires an OsmoMGW instance to run alongside it. In a setup where OsmoBSC and OsmoMSC can both reach it directly, they may in fact share the same OsmoMGW instance (endpoints are allocated dynamically).
246 1 neels
247 124 neels
It is semantically more clear to run a separate OsmoMGW instance for the OsmoBSC. When running on the same machine, though, then each MGW obviously needs to use different UDP ports, for example:
248 1 neels
249 108 neels
*osmo-mgw-for-bsc.cfg* (download: attachment:nitb.tar)
250 1 neels
<pre>
251 40 neels
mgcp
252 82 neels
 bind ip 192.168.0.9
253 47 neels
 # default port is 2427 (is used for MSC's MGW)
254
 bind port 12427
255 41 neels
line vty
256 1 neels
 # default VTY interface is on 127.0.0.1 (used for MSC's MGW)
257
 bind 127.0.0.2
258 130 neels
259
log stderr
260
 logging filter all 1
261
 logging print extended-timestamp 1
262
 logging print category 1
263
 logging print category-hex 0
264
 logging print level 1
265
 logging print file basename last
266
 logging level set-all info
267
268 1 neels
</pre>
269 40 neels
270 130 neels
Note that osmo-bsc.cfg below sets the 'mgw remote-port' to the 'bind port' configured here; if the MGWs run on distinct interfaces, the default ports will do in both cases.
271 1 neels
272 9 neels
h2. OsmoSTP
273
274 131 neels
[[OsmoSTP:]] is the Signal Transfer Point; think of it like a network switch that quietly routes messages between components, for the SS7 system. You almost never need to look at its logging or configuration.
275 1 neels
276 131 neels
OsmoSTP 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.
277
278 9 neels
The basic configuration that permits dynamic routing is:
279
280 108 neels
*osmo-stp.cfg* (download: attachment:nitb.tar)
281 9 neels
<pre>
282
cs7 instance 0
283
 xua rkm routing-key-allocation dynamic-permitted
284
 listen m3ua 2905
285 1 neels
  accept-asp-connections dynamic-permitted
286 131 neels
287
log stderr
288
 logging filter all 1
289
 logging print extended-timestamp 1
290
 logging print category 1
291
 logging print category-hex 0
292
 logging print level 1
293
 logging print file basename last
294
 logging level set-all info
295 11 neels
</pre>
296 1 neels
297
h2. OsmoBSC
298 11 neels
299 93 neels
[[OsmoBSC:]] is the 2G Base Station Controller: it 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.
300 67 neels
301 87 neels
OsmoBSC needs to register with OsmoSTP, and contact the MSC by its point code. If not configured otherwise, it will use OsmoMSC's default point code to contact it, see [[Point Codes]].
302 11 neels
303 132 neels
OsmoBSC needs to contact an OsmoMGW on its MGCP port, to manage RTP streams between BTS and the MSC's MGW, as discussed above under "OsmoMGW".
304 42 neels
305 132 neels
OsmoBSC also needs complete configuration of all connected BTS -- usually the BTS side configures the phy, unit id and the BSC's remote address, and the BSC configures everything else over OML. This example shows configuration for a sysmoBTS.
306 15 neels
307
Furthermore, some network properties need to be set.
308 1 neels
309 132 neels
The 'gprs mode' determines whether packet switched access will be enabled. 'gprs mode none' switches off data services, it tells osmo-bts not to contact osmo-pcu to establish data service. Note that if you set 'gprs mode gprs' but fail to provide a working PCU, a phone may oscillate between BTS cells to try to establish GPRS service.
310 15 neels
311 83 neels
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":http://ftp.osmocom.org/docs/latest/osmobts-abis.pdf, chapter "Dynamic Channel Combinations". The following is a configuration with voice-and-data service based on Osmocom style dynamic timeslots:
312 15 neels
313 108 neels
*osmo-bsc.cfg* for voice and data service (download: attachment:nitb.tar)
314 48 neels
<pre>
315 75 neels
network
316
 network country code 901
317 1 neels
 mobile network code 70
318 75 neels
 bts 0
319 1 neels
  type sysmobts
320 75 neels
  band GSM-1800
321 1 neels
  location_area_code 23
322 132 neels
  # This is the unit id that has to match the BTS configuration
323 75 neels
  ip.access unit_id 1800 0
324 132 neels
  codec-support fr hr amr
325 75 neels
  gprs mode gprs
326 82 neels
  gprs nsvc 0 remote ip 192.168.0.9
327 75 neels
  gprs nsvc 0 remote udp port 23000
328
  gprs nsvc 0 local udp port 23000
329
  gprs nsvc 0 nsvci 1800
330
  gprs nsei 1800
331
  gprs cell bvci 1800
332
  trx 0
333
   rf_locked 0
334
   arfcn 868
335
   nominal power 23
336
   timeslot 0
337
    phys_chan_config CCCH+SDCCH4
338
   timeslot 1
339
    phys_chan_config SDCCH8
340
   timeslot 2
341
    phys_chan_config TCH/F_TCH/H_PDCH
342
   timeslot 3
343 1 neels
    phys_chan_config TCH/F_TCH/H_PDCH
344 75 neels
   timeslot 4
345
    phys_chan_config TCH/F_TCH/H_PDCH
346
   timeslot 5
347
    phys_chan_config TCH/F_TCH/H_PDCH
348
   timeslot 6
349
    phys_chan_config TCH/F_TCH/H_PDCH
350
   timeslot 7
351
    phys_chan_config PDCH
352
e1_input
353 1 neels
 e1_line 0 driver ipa
354 75 neels
msc 0
355 82 neels
 mgw remote-ip 192.168.0.9
356 1 neels
 mgw remote-port 12427
357
 allow-emergency deny
358
 codec-list hr3
359 132 neels
360
log stderr
361
 logging filter all 1
362
 logging print extended-timestamp 1
363
 logging print category 1
364
 logging print category-hex 0
365
 logging print level 1
366
 logging print file basename last
367
 logging level set-all info
368 1 neels
</pre>
369
370
h2. OsmoHNBGW
371
372 93 neels
[[OsmoHNBGW:]] is the 3G HomeNodeB Gateway, found in the osmo-iuh.git repository: it receives the Iuh protocol from a 3G femto cell, separates it into IuCS and IuPS and forwards to the MSC and SGSN.
373 1 neels
374 89 neels
OsmoHNBGW needs to connect to OsmoSTP for routing, and needs to know the MSC and SGSN point codes. If omitted, it assumes OsmoSTP on 127.0.0.1 and uses the point codes that are default in OsmoMSC and OsmoSGSN, see [[Point Codes]].
375 1 neels
376
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.
377
378 108 neels
*osmo-hnbgw.cfg* (download: attachment:nitb.tar)
379 1 neels
<pre>
380 82 neels
hnbgw
381
 iuh
382
  local-ip 192.168.0.9
383 133 neels
 
384
log stderr
385
 logging filter all 1
386
 logging print extended-timestamp 1
387
 logging print category 1
388
 logging print category-hex 0
389
 logging print level 1
390
 logging print file basename last
391
 logging level set-all info
392 1 neels
</pre>
393
394 133 neels
*NOTE:* For the nano3G, the MSC must encode X.213 style addresses in the RAB assignment, see osmo-msc.cfg, 'iu rab-assign-addr-enc x213'.
395 96 neels
396 133 neels
*NOTE:* To connect your femto cell to the HNBGW, see for example [[Configuring_the_ipaccess_nano3G]]
397 1 neels
398 98 neels
*NOTE:* The 'hnbap-allow-tmsi' option is just a workaround for the nano3G passing a TMSI as UE-Register identity, which would normally have to be an IMSI.
399 95 neels
400 1 neels
h2. OsmoGGSN
401
402 93 neels
[[OpenGGSN:|OsmoGGSN]] is the Gateway GPRS Support Node: it "opens" GTP tunnels received from SGSNs to internet uplink. To provide packet switched service, OsmoGGSN must offer GTP service to the OsmoSGSN.
403 1 neels
404 135 neels
Notably, both OsmoGGSN and OsmoSGSN must use identical GTP port numbers, which is an intrinsic requirement of the GTP protocol. Hence they must not run on the same IP address. Furthermore, for 2G networks, the SGSN must be reachable by the PCU and thus needs to be on a public interface if the BTS is a separate box; for 3G networks, the GGSN must be reachable by the hNodeB and thus needs to be on a public interface. So, to cover both, you need to have *two* public interfaces; this example uses 192.168.0.42, assumed to be an IP address available on the local ethernet interface.
405 1 neels
406 135 neels
Refer to your distribution on how to configure a second IP address.
407
408
(In an aside, this script would obtain a second address from your DHCP server:
409
410 1 neels
<pre>
411 135 neels
#!/bin/sh
412
# usage: ./second_dhclient.sh eth0
413
dev="${1:-eth0}"
414
nr="$(ip a | grep "^[0-9]*: $dev" | wc -l)"
415
name="$(echo "$dev" | sed 's/[^0-9a-fA-F]//g' | head -c 1)"
416
mac="ac:ac:1a:b0:a0:$name$nr"
417
set -e -x
418
sudo ip link add link $dev address $mac $dev.$nr type macvlan
419
sudo dhclient $dev.$nr
420
ip addr show dev $dev.$nr
421 82 neels
</pre>
422
423 135 neels
For this example to work, the DCHP server would need to assign to you the address 192.168.0.42.)
424 82 neels
425 1 neels
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.
426 13 neels
427 82 neels
It also needs access to a tun device with an address range available to subscribers' PDP contexts. 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 'apn0' device has been created ahead of time, with:
428 13 neels
429 82 neels
<pre>
430
sudo ip tuntap add dev apn0 mode tun user $USER group $USER
431
sudo ip addr add 192.168.42.0/24 dev apn0
432
sudo ip link set apn0 up
433
</pre>
434
435
IPv4 operation is enabled by default, but for future compatibility, it is good to indicate that explicitly.
436
437 76 neels
OsmoGGSN furthermore indicates DNS servers, as well as an IPv4 address range to assign to subscribers' PDP contexts.
438 13 neels
439 85 neels
Note that the APN named in this config file (here "internet") needs to be configured on your phone, see [[Osmocom Network In The Box#APN-for-Data-Service|APN for Data Service]] below. With the @default-apn@ command, any unknown APN name will use that default APN instead, but still you usually have to define _some_ APN on your phone so that it even tries to connect to the data service.
440 13 neels
441 85 neels
A profound part of GGSN configuration is the network setup of your system: you need to allow the packets to be routed between the subscribers and your internet uplink. See the [[Osmocom Manuals|OsmoGGSN User Manual]], section _Running OsmoGGSN_ / _Routing_.
442 84 neels
443 108 neels
*osmo-ggsn.cfg* (download: attachment:nitb.tar)
444 125 neels
NOTE: this configuration requires the _apn0_ tun device to be configured and up, as well as IP-forwarding and masquerading to be enabled -- please see the manual as indicated above.
445 13 neels
<pre>
446 137 neels
log stderr
447
 logging level all debug
448
 logging filter all 1
449
 logging print category 1
450 13 neels
ggsn ggsn0
451 82 neels
 gtp bind-ip 192.168.0.42
452 1 neels
 apn internet
453
  tun-device apn0
454
  type-support v4
455
  ip dns 0 192.168.0.1
456 137 neels
  ip dns 1 9.9.9.9
457 1 neels
  ip prefix dynamic 192.168.42.0/24
458
  no shutdown
459
 default-apn internet
460
 no shutdown ggsn
461 137 neels
 
462 135 neels
log stderr
463
 logging filter all 1
464
 logging print extended-timestamp 1
465
 logging print category 1
466
 logging print category-hex 0
467
 logging print level 1
468
 logging print file basename last
469
 logging level set-all info
470 14 neels
</pre>
471 67 neels
472
h2. OsmoSGSN
473 14 neels
474 93 neels
[[OsmoSGSN:]] is the Serving GPRS Support Node: it handles signalling, i.e. attach/detach of subscribers and PDP contexts for data services.
475 14 neels
476
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.
477
478
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).
479
480 136 neels
For 3G, OsmoSGSN needs to be reachable by the HNBGW for IuPS. If you're running _only_ 3G, the SGSN does not need to listen on a public IP address.
481 88 neels
482
For 3G IuPS, the SGSN must sign up at OsmoSTP with a point code that the HNBGW knows. If not configured explicitly, the respective defaults are used, see [[Point Codes]].
483 14 neels
484 136 neels
Finally, OsmoSGSN needs access to OsmoHLR to access subscriber data. Set 'auth-policy remote' to use the HLR for subscriber authorization.
485 1 neels
486 108 neels
*osmo-sgsn.cfg* (download: attachment:nitb.tar)
487 14 neels
<pre>
488 77 neels
sgsn
489 82 neels
 gtp local-ip 192.168.0.9
490
 ggsn 0 remote-ip 192.168.0.42
491 79 neels
 ggsn 0 gtp-version 1
492 14 neels
 auth-policy remote
493 1 neels
 gsup remote-ip 127.0.0.1
494
ns
495
 encapsulation udp local-ip 192.168.0.9
496
 encapsulation udp local-port 23000
497
 encapsulation framerelay-gre enabled 0
498 136 neels
  
499
log stderr
500
 logging filter all 1
501
 logging print extended-timestamp 1
502
 logging print category 1
503
 logging print category-hex 0
504
 logging print level 1
505
 logging print file basename last
506
 logging level set-all info
507 1 neels
</pre>
508
509
The @auth-policy remote@ requires that you have the SIM cards' authentication tokens in your OsmoHLR database. Instead, you can use @auth-policy accept-all@, but be aware that this will only work for 2G. 3G networks _require_ successful authentication, and @auth-policy remote@ is your _only_ option for a 3G SGSN.
510 93 neels
511
h1. OsmoBTS
512
513
[[OsmoBTS:]] operates 2G radio hardware. OsmoBTS supports various hardware platforms including sysmoBTS and USRP. Instead, you may choose BTS vendors like ip.access or Siemens, which can also directly operate with OsmoBSC without OsmoBTS being involved.
514
515
The BTS needs to know where to reach OsmoBSC's Abis interface, and its unit id needs to match one of the BTS unit ids configured at OsmoBSC.
516
517
An example configuration for a sysmoBTS is:
518
519
<pre>
520
phy 0
521
 instance 0
522
bts 0
523
 band 1800
524
 ipa unit-id 1800 0
525
 oml remote-ip 192.168.0.9
526
 trx 0
527
  phy 0 instance 0
528
</pre>
529
530
h1. OsmoPCU
531
532
[[OsmoPCU:]] operates the packet-switched part of 2G radio hardware. Timeslots used for data transmission are controlled by the PCU instead of the BTS. OsmoPCU is typically configured from the @gprs@ config items in OsmoBSC, which is communicated to the PCU via OML and OsmoBTS (via the PCU socket). An example configuration for OsmoPCU would be:
533
534
<pre>
535
pcu
536
 flow-control-interval 10
537
 cs 2
538
 alloc-algorithm dynamic
539
 alpha 0
540
 gamma 0
541
 two-phase-access
542
</pre>
543 17 neels
544
h1. Running Examples
545
546 122 laforge
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@.
547 17 neels
548 122 laforge
When installed from debian or opkg feeds, you will find the systemd service files in @/lib/systemd/system/@.
549 17 neels
550
Re/starting and stopping then works like this:
551
552
<pre>
553 1 neels
systemctl restart osmo-hlr
554
systemctl stop osmo-hlr
555
</pre>
556 36 neels
557 150 neels
For illustration, the manual command invocations for the components would look like this on a typical CNI standalone host:
558
<pre>
559
osmo-hlr -l hlr.db -c osmo-hlr.cfg
560
osmo-msc -c osmo-msc.cfg
561
osmo-mgw -c osmo-mgw-for-msc.cfg
562
osmo-mgw -c osmo-mgw-for-bsc.cfg
563
osmo-ggsn -c osmo-ggsn.cfg
564
osmo-sgsn -c osmo-sgsn.cfg
565
osmo-stp -c osmo-stp.cfg
566
osmo-bsc -c osmo-bsc.cfg
567
osmo-hnbgw -c osmo-hnbgw.cfg
568
osmo-sip-connector -c osmo-sip-connector.cfg
569
</pre>
570
571
h2. Convenience Launcher
572
573 1 neels
It can be useful to have an @osmo-all@ script to re/start or stop all components at once, edit to pick yours:
574
575
*osmo-all* script
576
<pre>
577
#!/bin/sh
578 150 neels
cmd="${1:-status}"
579 1 neels
set -ex
580 150 neels
systemctl $cmd osmo-hlr osmo-msc osmo-mgw osmo-ggsn osmo-sgsn osmo-stp osmo-bsc osmo-hnbgw osmo-sip-connector
581 48 neels
</pre>
582
583 36 neels
which allows
584 1 neels
585
<pre>
586
./osmo-all restart
587 36 neels
./osmo-all status
588
./osmo-all stop
589
</pre>
590 18 neels
591
h1. Logging Examples
592
593
Osmocom programs have a common logging mechanism, configurable by the config files as well as the telnet VTY.
594
595 82 neels
h2. System Logging
596
597 18 neels
Depending on the system's logging configuration, logs may by default be visible in /var/log/daemon.log, or by using journalctl:
598
599 1 neels
<pre>
600
journalctl -f -u osmo-hlr
601
</pre>
602
603
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.
604
605 82 neels
h2. telnet VTY logging
606
607 1 neels
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:
608
609
<pre>
610
$ telnet localhost 4254
611
OsmoMSC> logging enable 
612
OsmoMSC> logging level ?
613
  all      Global setting for all subsystems
614
  rll      A-bis Radio Link Layer (RLL)
615 18 neels
  cc       Layer3 Call Control (CC)
616
  mm       Layer3 Mobility Management (MM)
617
  [...]
618 35 neels
OsmoMSC> logging level all ?
619 19 neels
everything debug      info       notice     error      fatal      
620
OsmoMSC> logging level all debug 
621
OsmoMSC> logging filter all 1
622 1 neels
</pre>
623
624
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.
625
626 138 neels
Here is a useful 'expect' script to attach to osmo-* components by name and start logging while still having a vty prompt:
627
628 139 neels
*vty* script (download: attachment:nitb.tar)
629 138 neels
<pre>
630
#!/usr/bin/expect -f
631
set vty [lindex $argv 0]
632
set host localhost
633
switch $vty {
634
 hlr { set port 4258 }
635
 bsc { set port 4242 }
636
 mgw { set port 4243 }
637
 mgw2 {
638
        set host 127.0.0.2
639
        set port 4243
640
      }
641
 sg { set port 4245 }
642
 msc { set port 4254 }
643
 sip { set port 4256 }
644
 gg { set port 4260 }
645
 osmo-hlr { set port 4258 }
646
 osmo-bsc { set port 4242 }
647
 osmo-mgw { set port 4243 }
648
 osmo-mgw-for-bsc { set port 4243 }
649
 osmo-mgw-for-msc {
650
        set host 127.0.0.2
651
        set port 4243
652
      }
653
 osmo-sgsn { set port 4245 }
654
 osmo-msc { set port 4254 }
655
 osmo-sip-connector { set port 4256 }
656
 osmo-ggsn { set port 4260 }
657
 default { set port 4242 }
658
}
659
spawn telnet localhost $port
660
expect ">"
661
send "enable\r"
662
expect "#"
663
send "logging enable\r"
664
expect "#"
665
send "logging print category 1\r"
666
expect "#"
667
send "logging print category-hex 0\r"
668
expect "#"
669
send "logging print level 1\r"
670
expect "#"
671
send "logging print file basename last\r"
672
expect "#"
673
send "logging print extended-timestamp 1\r"
674
expect "#"
675
send "logging level set-all notice\r"
676
expect "#"
677
switch $vty {
678
 msc {
679
  send "logging level mm info\r"
680
  expect "#"
681
  send "logging level cc info\r"
682
  expect "#"
683
 }
684
}
685
send "logging filter all 1\r"
686
expect "#"
687
interact
688
</pre>
689
690 1 neels
h2. stderr logging
691
692
A common configuration you can add to any of the above configuration files to show *all* logging on stderr is:
693
694
<pre>
695
log stderr
696
 logging filter all 1
697
 logging color 1
698
 logging print category 1
699
 logging timestamp 1
700
 logging print extended-timestamp 1
701
 logging level all debug
702
</pre>
703
704
The @filter all 1@ switches on logging, read "do not discard all logging". The amount of logging seen is determined by @logging level ...@ commands, here all categories are set to level @debug@, to show absolutely all logging. You will probably want to refine that.
705 90 neels
706
h1. Point Codes
707
708
If you'd like to configure non-default point-codes, see this example for OsmoHNBGW on the general approach:
709
710
<pre>
711
cs7 instance 0
712
 # HNBGW's local point code
713
 point-code 0.23.5
714
 # Address book entries, used below
715
 sccp-address my_msc
716
  point-code 0.23.1
717
 sccp-address my_sgsn
718
  point-code 0.23.4
719
hnbgw
720
 iucs
721
  remote-addr my_msc
722
 iups
723
  remote-addr my_sgsn
724
</pre>
725 76 neels
726
h1. Troubleshooting
727
728
h2. APN for Data Service
729
730
For the data service to work, phones generally need an APN added to their
731
configuration, or they will not even attempt to establish a data connection.
732
The APN should match the name configured in osmo-ggsn.conf.
733
734
The APN configuration steps are usually similar to:
735
736
* Navigate to APN settings:
737
** 'Settings'
738
** 'Wireless & Networks'
739
** 'Mobile networks'
740
** 'Access Point Names'
741
* You should see the list of APNs (possibly empty)
742
* Press the Menu button
743
* Choose 'New APN'
744
* Enter values for 'Name' as well as 'APN'
745
* Again press the Menu button
746
* Choose 'Save'
747
* The APN should now appear in the list of APNs.
748 1 neels
* Possibly tap the bullet icon to select the APN as default.
749 117 duo_kali
750 110 duo_kali
</pre>
751 1 neels
752 140 neels
753
h1. Tips and Facts
754
755
h2. Analyzing 3G RTP streams in wireshark
756
757
IuCS actually uses UP over RTP. See 3GPP TS 25.414, and 25.415 6.6.2.
758
(an interesting insight is https://www.ietf.org/mail-archive/web/avt/current/msg05907.html )
759
760
In the wireshark preferences, go to protocol IuUP, enable it and enter the dynamic protocol
761
number that you see in the RTP frames (e.g. 96).
Add picture from clipboard (Maximum size: 48.8 MB)