Project

General

Profile

Osmocom Network In The Box » History » Version 143

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