summaryrefslogtreecommitdiff
path: root/2021/running_osmo_gsm-2021/running-osmo-gsm.adoc
blob: a884d5bfe9455d2edb70da855269c3e5cbb854a3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
Running a basic Osmocom GSM network
===================================
:author:	Harald Welte <laforge@gnumonks.org>
:copyright:	sysmocom - s.f.m.c. GmbH (License: CC-BY-SA)
:backend:	slidy
:max-width:	45em
//:data-uri:
//:icons:


== What this talk is about

[role="incremental"]
* Implementing GSM/GPRS network elements as FOSS
* Applied Protocol Archaeology
* Doing all of that on top of Linux (in userspace)


== Running your own Internet-style network

* use off-the-shelf hardware (x86, Ethernet card)
* use any random Linux distribution
* configure Linux kernel TCP/IP network stack
** enjoy fancy features like netfilter/iproute2/tc
* use apache/lighttpd/nginx on the server
* use Firefox/chromium/konqueor/lynx on the client
* do whatever modification/optimization on any part of the stack


== Running your own GSM network

Until 2009 the situation looked like this:

* go to Ericsson/Huawei/ZTE/Nokia/Alcatel/...
* spend lots of time convincing them that you're an eligible customer
* spend a six-digit figure for even the most basic full network
* end up with black boxes you can neither study nor improve

[role="incremental"]
- WTF?
- I've grown up with FOSS and the Internet. I know a better world.


== Why no cellular FOSS?

- both cellular (2G/3G/4G) and TCP/IP/HTTP protocol specs are publicly
  available for decades.  Can you believe it?
- Internet protocol stacks have lots of FOSS implementations
- cellular protocol stacks have no FOSS implementations for the
  first almost 20 years of their existence?
[role="incremental"]
- it's the classic conflict
 * classic circuit-switched telco vs. the BBS community
 * ITU-T/OSI/ISO vs. Arpanet and TCP/IP


== Enter Osmocom

In 2008, some people (most present in this room) started to write FOSS
for GSM

- to boldly go where no FOSS hacker has gone before
[role="incremental"]
** where protocol stacks are deep
** and acronyms are plentiful
** we went from `bs11-abis` to `bsc_hack` to 'OpenBSC'
** many other related projects were created
** finally leading to the 'Osmocom' umbrella project


== Classic GSM network architecture

image::Gsm_structures.svg[width=850]


== GSM Acronyms, Radio Access Network

MS::
	Mobile Station (your phone)
BTS::
	Base Transceiver Station, consists of 1..n TRX
TRX::
	Transceiver for one radio channel, serves 8 TS
TS::
	Timeslots in the GSM radio interface; each runs a specific combination of logical channels
BSC::
	Base Station Controller


== GSM Acronyms, Core Network

MSC::
	Mobile Switching Center; Terminates MM + CC Sub-layers

HLR::
	Home Location Register; Subscriber Database

SMSC::
	SMS Service Center


== GSM Acronyms, Layer 2 + 3

LAPDm::
	Link Access Protocol, D-Channel. Like LAPD in ISDN
RR::
	Radio Resource (establish/release dedicated channels)
MM::
	Mobility Management (registration, location, authentication)
CC::
	Call Control (voice, circuit switched data, fax)
CM::
	Connection Management


== Osmocom GSM components

image::osmocom-cni.png[width=850]


== Classic GSM network as digraph

[graphviz]
----
digraph G {
	rankdir=LR;
	MS0 [label="MS"]
	MS1 [label="MS"]
	MS2 [label="MS"]
	MS3 [label="MS"]
	BTS0 [label="BTS"]
	BTS1 [label="BTS"]
	MSC [label="MSC/VLR"]
	HLR [label="HLR/AUC"]
	MS0->BTS0 [label="Um"]
	MS1->BTS0 [label="Um"]
	MS2->BTS1 [label="Um"]
	MS3->BTS1 [label="Um"]
	BTS0->BSC [label="Abis"]
	BTS1->BSC [label="Abis"]
	BSC->MSC [label="A"]
	MSC->HLR [label="C"]
	MSC->EIR [label="F"]
	MSC->SMSC
}
----

== Osmocom GSM network

[graphviz]
----
digraph G {
	rankdir=LR;
	MS0 [label="MS"]
	MS1 [label="MS"]
	MS2 [label="MS"]
	MS3 [label="MS"]
	BTS0 [label="OsmoBTS"]
	BTS1 [label="OsmoBTS"]
	MS0->BTS0 [label="Um"]
	MS1->BTS0 [label="Um"]
	MS2->BTS1 [label="Um"]
	MS3->BTS1 [label="Um"]
	BTS0->BSC [label="Abis"]
	BTS1->BSC [label="Abis"]
	subgraph cluster_cni {
		label = "Osmocom CNI";
		BSC [label="OsmoBSC"]
		MSC [label="OsmoMSC (SMSC inside)"]
		HLR [label="OsmoHLR"]
		BSC->MSC [label="AoIP"]
		MSC->HLR [label="GSUP"]
	}
}
----

== Which BTS to use?

* Proprietary BTS of classic vendor
** Siemens BS-11 is what we started with
** Nokia, Ericsson, and others available 2nd hand
* 'OsmoBTS' software implementation, running with
** Proprietary HW + PHY (DSP): 'sysmoBTS', or
** General purpose SDR (like USRP) + 'OsmoTRX'

We assume a sysmoBTS in the following tutorial


== OsmoBTS Overview

image::osmo-bts.svg[]

* Implementation of GSM BTS
* supports variety of hardware/PHY options
** `osmo-bts-sysmo`: BTS family by sysmocom
** `osmo-bts-trx`: Used with 'OsmoTRX' + general-purpose SDR
** `osmo-bts-octphy`: Octasic OCTBTS hardware / OCTSDR-2G PHY
** `osmo-bts-litecell15`: Nutaq Litecell 1.5 hardware/PHY

See separate talk about BTS hardware options later today.

== BTS Hardware vs. BTS software

* A classic GSM BTS is hardware + software
* It has two interfaces
** Um to the radio side, towards phones
** Abis to the wired back-haul side, towards BSC
* with today's flexible architecture, this is not always true
** the hardware might just be a network-connected SDR and BTS software
runs o a different CPU/computer, _or_
** the BTS and BSC, or even the NITB may run on the same board


== Physical vs. Logical Arch (sysmoBTS)

[graphviz]
----
include::arch-sysmobts.dot[]
----

[graphviz]
----
include::arch-sysmobts-allinone.dot[]
----

== Physical vs. Logical Arch (SDR e.g. USRP B2xx)

[graphviz]
----
include::arch-usrp.dot[]
----

[graphviz]
----
include::arch-usrp-allinone.dot[]
----

== IP layer traffic

* Abis/IP signaling runs inside IPA multiplex inside TCP
** Port 3002 and 3003 betewen BTS and BSC
** Connections initiated from BTS to BSC
* Voice data is carried in RTP/UDP on dynamic ports

=> Make sure you permit the above communication in your
network/firewall config

== Configuring Osmocom software

* all _native_ Osmo* GSM infrastructure programs share common architecture, as
  defined by various libraries 'libosmo{core,gsm,vty,abis,netif,...}'
* part of this is configuration handling
** interactive configuration via command line interface (*vty*), similar
   to Cisco routers
** based on a fork of the VTY code from Zebra/Quagga, now 'libosmovty'
* you can manually edit the config file,
* or use `configure terminal` and interactively change it


== Configuring OsmoBTS

* 'OsmoBTS' in our example scenario runs on the embedded ARM/Linux system
  inside the 'sysmoBTS'
* we access the 'sysmoBTS' via serial console or ssh
* we then edit the configuration file `/etc/osmocom/osmo-bts.cfg` as
  described in the following slide


== Configuring OsmoBTS

----
bts 0
 band DCS1800 <1>
 ipa unit-id 1801 0 <2>
 oml remote-ip 192.168.100.11 <3>
----
<1> the GSM frequency band in which the BTS operates
<2> the unit-id by which this BTS identifies itself to the BSC
<3> the IP address of the BSC (to establish the OML connection towards it)

NOTE: All other configuration is downloaded by the BSC via OML. So most
BTS settings are configured in the BSC/NITB configuration file.


== Purpose of Unit ID

* Unit IDs consist of three parts:
** Site Number, BTS Number, TRX Number

[graphviz]
----
graph G {
	rankdir=LR;
	BTS0 [label="BTS\nUnit 5/0[/0]"]
	BTS1 [label="BTS\nUnit 23/0[/0]"]
	BTS2 [label="BTS\nUnit 42/0[/0]"]
        NAT
        BSC [label="BSC/NITB"]

        BTS0 -- NAT [label="10.9.23.5"]
        BTS1 -- NAT [label="10.9.23.23"]
        BTS2 -- NAT [label="10.9.23.42"]
        NAT -- BSC [label="172.16.23.42"]
}
----

* source IP of all BTSs would be identical

=> BSC identifies BTS on Unit ID, not on Source IP!


== Configuring Osmocom CNI

* 'Osmocom CNI' is the collection of all the non-BTS Osmocom projects for 3GPP network operation, of which
  the minimally required are osmo-bsc, osmo-msc and osmo-hlr.  You also will need osmo-stp for SIGTRAN and osmo-mgw for user plane.
** just your usual `git clone && autoreconf -fi && ./configure && make install`
** (in reality, the `libosmo*` dependencies are required first...)
** nightly packages for Debian 9-11, buntu 19.x/20.x/21.x available
* runs on any Linux system, like your speakers' laptop
** you can actually also run it on the ARM/Linux of the 'sysmoBTS' itself,
   having a literal 'Network In The Box' with power as only external
   dependency


== Configuring Osmocom CNI

* each program has a config file
* simple example given in `doc/examples/osmo-*.cfg` of each git repo
* each program has a user manual and a VTY command reference manual
** asciidoc is part of the source
** PDF renderings at https://downloads.osmocom.org/docs/latest/


== What a GSM phone does after power-up

* Check SIM card for last cell before switch-off
** if that cell is found again, use that
** if not, perform a network scan
*** try to find strong carriers, check if they contain BCCH
*** create a list of available cells + networks
*** if one of the networks MCC+MNC matches first digits of 'IMSI', this is
the home network, which has preference over others
* perform 'LOCATION UPDATE' (TYPE=IMSI ATTACH) procedure to network
* when network sends 'LOCATION UPDATE ACCEPT', *camp* on that cell

-> let's check if we can perform 'LOCATION UPDATE' on our own network


== Verifying our network

* look at log output of Osmocom programs
** 'OsmoBTS' will terminate if Abis cannot be set-up, expected to be re-spawned by init / systemd
* use MS to search for networks, try manual registration
* observe registration attempts `logging level mm info`

-> should show 'LOCATION UPDATE' request / reject / accept

* use the VTY to explore system state (`show *`)
* use the VTY to change subscriber parameters like extension number


== Exploring your GSM networks services

* use `*#100#` from any registered MS to obtain own number
* voice calls from mobile to mobile
* SMS from mobile to mobile
* SMS to/from external applications (via SMPP)
* voice to/from external PBX (via MNCC)
* explore the VTY interfaces of all network elements
** send SMS from the command line
** experiment with 'silent call' feature
** experiment with logging levels
* use wireshark to investigate GSM protocols


== Using the VTY

* The VTY can be used not only to configure, but also to interactively
  explore the system status (`show` commands)
* Every Osmo* program has its own telnet port
|===
|Program|Telnet Port
|OsmoBTS|4241
|OsmoBSC|4242
|OsmoMSC|4254
|OsmoHLR|4258
|===
* https://osmocom.org/projects/cellular-infrastructure/wiki/Port_Numbers
* ports are bound to 127.0.0.1 by default
** can be bound to other IPs or ANY via config file
* try tab-completion, `?` and `list` commands

== Using the VTY (continued)

* context-sensitive command line interface like Cisco and many others
* `show` commands to introspect
** try `show bts`, `show trx`, `show lchan`, `show statistics`, ...
* `enable` + `configure terminal` for configuration mode
* interactive reference, tab-completion
* `logging enable` adds log target to VTY session

== Further Reading

User Manuals::
See http://ftp.osmocom.org/docs/latest/
Wiki::
See https://osmocom.org/projects/cellular-infrastructure/wiki

== The End

* so long, and thanks for all the fish
* I hope you have questions!

[role="incremental"]
* have fun exploring mobile technologies using Osmocom
* interested in working with more acronyms? Come join the project!

* Check out https://osmocom.org/ and openbsc@lists.osmocom.org
personal git repositories of Harald Welte. Your mileage may vary