2019/20/21 updated version of 'running osmocom gsm'

1 files changed, 418 insertions, 0 deletions

diff --git a/2021/running_osmo_gsm-2021/running-osmo-gsm.adoc b/2021/running_osmo_gsm-2021/running-osmo-gsm.adoc
new file mode 100644
index 0000000..a884d5b
--- /dev/null
+++ b/2021/running_osmo_gsm-2021/running-osmo-gsm.adoc
@@ -0,0 +1,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