Sysmocom OsmoGGSN User Manual

OsmoGGSN User Manual i

sysmocom - s.f.m.c. GmbH

OsmoGGSN User Manual

DRAFT

by Harald Welte

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

The Asciidoc source code of this manual can be found at http://git.osmocom.org/osmo-gsm-manuals/

DRAFT 1.6.0-13-g1230, 2020-Aug-18

OsmoGGSN User Manual ii

HISTORY

NUMBER DATE DESCRIPTION NAME

1 August 2017 Initial version. HW

OsmoGGSN User Manual iii

Contents

1 Foreword 1

1.1 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Preface 2

2.1 FOSS lives by contribution! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2.2 Osmocom and sysmocom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2.3 Corrections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.4 Legal disclaimers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.4.1 Spectrum License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.4.2 Software License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.4.3 Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.4.4 Liability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Introduction 4

3.1 Required Skills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3.2 Getting assistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

4 Overview 4

4.1 About OsmoGGSN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

4.2 Software Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4.2.1 GTP Implementation (libgtp) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4.2.2 sgsnemu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4.2.3 osmo-ggsn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4.2.4 systemd service ﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4.2.5 init script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4.3 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4.3.1 GSM 09.60 (GTPv0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4.3.2 3GPP 29.060 (GTPv1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

5 Running OsmoGGSN 7

5.1 SYNOPSIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5.2 OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5.3 Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5.4 Multiple instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

OsmoGGSN User Manual iv

6 The Osmocom VTY Interface 8

6.1 Accessing the telnet VTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

6.2 VTY Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

6.3 Interactive help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

6.3.1 The question-mark (?) command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

6.3.2 TAB completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

6.3.3 The list command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

6.3.4 The attribute system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.3.5 The expert mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

7 libosmocore Logging System 15

7.1 Log categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

7.2 Log levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

7.3 Log printing options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

7.4 Log ﬁlters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

7.5 Log targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

7.5.1 Logging to the VTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

7.5.2 Logging to the ring buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

7.5.3 Logging via gsmtap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

7.5.4 Logging to a ﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

7.5.5 Logging to syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

7.5.6 Logging to stderr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

8 Conﬁguring OsmoGGSN 20

8.1 Conﬁguring a virtual GGSN instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

8.1.1 Creating/Editing a GGSN instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

8.1.2 Conﬁguring a GGSN instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

8.1.3 Deleting a GGSN instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

8.1.4 Taking a GGSN instance out of shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

8.1.5 Shutting a GGSN instance down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

8.2 Conﬁguring an Access Point Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

8.2.1 Creating/Editing an APN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

8.2.2 Conﬁguring an APN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

8.2.3 Deleting an APN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

8.2.4 Taking an APN out of shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

8.2.5 Shutting an APN down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

8.3 Conﬁguring for running without root privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

8.3.1 Manual TUN device creation / conﬁguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

8.3.2 systemd based TUN device creation+conﬁguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

8.3.3 Conﬁg Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

OsmoGGSN User Manual v

9 Osmocom Control Interface 26

9.1 Control Interface Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

9.1.1 GET operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

9.1.2 SET operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

9.1.3 TRAP operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

9.2 Common variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

9.3 Control Interface python examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

9.3.1 Getting rate counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

9.3.2 Setting a value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

9.3.3 Getting a value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

9.3.4 Listening for traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

10 VTY Process and Thread management 30

10.1 Scheduling Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

10.2 CPU-Afﬁnity Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

11 Glossary 32

A Osmocom TCP/UDP Port Numbers 40

B Bibliography / References 41

B.0.0.0.1 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

C GNU Free Documentation License 44

C.1 PREAMBLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

C.2 APPLICABILITY AND DEFINITIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

C.3 VERBATIM COPYING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

C.4 COPYING IN QUANTITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

C.5 MODIFICATIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

C.6 COMBINING DOCUMENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

C.7 COLLECTIONS OF DOCUMENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

C.8 AGGREGATION WITH INDEPENDENT WORKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

C.9 TRANSLATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

C.10 TERMINATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

C.11 FUTURE REVISIONS OF THIS LICENSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

C.12 RELICENSING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

C.13 ADDENDUM: How to use this License for your documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

OsmoGGSN User Manual 1 / 49

1 Foreword

Digital cellular networks based on the GSM speciﬁcation were designed in the late 1980ies and ﬁrst deployed in the early 1990ies in Europe. Over the last 25 years, hundreds of networks were established globally and billions of subscribers have joined the associated networks.

The technological foundation of GSM was based on multi-vendor interoperable standards, ﬁrst created by government bodies within CEPT, then handed over to ETSI, and now in the hands of 3GPP. Nevertheless, for the ﬁrst 17 years of GSM technology, the associated protocol stacks and network elements have only existed in proprietary black-box implementations and not as Free Software.

In 2008 Dieter Spaar and I started to experiment with inexpensive end-of-life surplus Siemens GSM BTSs. We learned about the A-bis protocol speciﬁcations, reviewed protocol traces and started to implement the BSC-side of the A-bis protocol as something originally called bs11-abis. All of this was just for fun, in order to learn more and to boldly go where no Free Software developer has gone before. The goal was to learn and to bring Free Software into a domain that despite its ubiquity, had not yet seen any Free / Open Source software implementations.

bs11-abis quickly turned into bsc-hack, then OpenBSC and its OsmoNITB variant: A minimal implementation of all the required functionality of an entire GSM network, exposing A-bis towards the BTS. The project attracted more interested developers, and surprisingly quickly also commercial interest, contribution and adoption. This allowed adding support for more BTS models.

After having implemented the network-side GSM protocol stack in 2008 and 2009, in 2010 the same group of people set out to create a telephone-side implementation of the GSM protocol stack. This established the creation of the Osmocom umbrella project, under which OpenBSC and the OsmocomBB projects were hosted.

Meanwhile, more interesting telecom standards were discovered and implemented, including TETRA professional mobile radio, DECT cordless telephony, GMR satellite telephony, some SDR hardware, a SIM card protocol tracer and many others.

Increasing commercial interest particularly in the BSS and core network components has lead the way to 3G support in Osmocom, as well as the split of the minimal OsmoNITB implementation into separate and fully featured network components: OsmoBSC, OsmoMSC, OsmoHLR, OsmoMGW and OsmoSTP (among others), which allow seamless scaling from a simple "Network In The Box" to a distributed installation for serious load.

It has been a most exciting ride during the last eight-odd years. I would not have wanted to miss it under any circumstances.

— Harald Welte, Osmocom.org and OpenBSC founder, December 2017.

1.1 Acknowledgements

My deep thanks to everyone who has contributed to Osmocom. The list of contributors is too long to mention here, but I’d like to call out the following key individuals and organizations, in no particular order:

• Dieter Spaar for being the most amazing reverse engineer I’ve met in my career

• Holger Freyther for his many code contributions and for shouldering a lot of the maintenance work, setting up Jenkins - and being crazy enough to co-start sysmocom as a company with me ;)

• Andreas Eversberg for taking care of Layer2 and Layer3 of OsmocomBB, and for his work on OsmoBTS and OsmoPCU

• Sylvain Munaut for always tackling the hardest problems, particularly when it comes closer to the physical layer

• Chaos Computer Club for providing us a chance to run real-world deployments with tens of thousands of subscribers every year

• Bernd Schneider of Netzing AG for funding early ip.access nanoBTS support

• On-Waves ehf for being one of the early adopters of OpenBSC and funding a never ending list of features, ﬁxes and general improvement of pretty much all of our GSM network element implementations

• sysmocom, for hosting and funding a lot of Osmocom development, the annual Osmocom Developer Conference and releasing this manual.

OsmoGGSN User Manual 2 / 49

• Jan Luebbe, Stefan Schmidt, Daniel Willmann, Pablo Neira, Nico Golde, Kevin Redon, Ingo Albrecht, Alexander Huemer, Alexander Chemeris, Max Suraev, Tobias Engel, Jacob Erlbeck, Ivan Kluchnikov

May the source be with you!

— Harald Welte, Osmocom.org and OpenBSC founder, January 2016.

2 Preface

First of all, we appreciate your interest in Osmocom software.

Osmocom is a Free and Open Source Software (FOSS) community that develops and maintains a variety of software (and partially also hardware) projects related to mobile communications.

Founded by people with decades of experience in community-driven FOSS projects like the Linux kernel, this community is built on a strong belief in FOSS methodology, open standards and vendor neutrality.

2.1 FOSS lives by contribution!

If you are new to FOSS, please try to understand that this development model is not primarily about “free of cost to the GSM network operator”, but it is about a collaborative, open development model. It is about sharing ideas and code, but also about sharing the effort of software development and maintenance.

If your organization is beneﬁtting from using Osmocom software, please consider ways how you can contribute back to that community. Such contributions can be many-fold, for example

• sharing your experience about using the software on the public mailing lists, helping to establish best practises in using/operating it,

• providing qualiﬁed bug reports, work-arounds

• sharing any modiﬁcations to the software you may have made, whether bug ﬁxes or new features, even experimental ones

• providing review of patches

• testing new versions of the related software, either in its current “master” branch or even more experimental feature branches

• sharing your part of the maintenance and/or development work, either by donating developer resources or by (partially) funding those people in the community who do.

We’re looking forward to receiving your contributions.

2.2 Osmocom and sysmocom

Some of the founders of the Osmocom project have established sysmocom - systems for mobile communications GmbH as a company to provide products and services related to Osmocom.

sysmocom and its staff have contributed by far the largest part of development and maintenance to the Osmocom mobile network infrastructure projects.

As part of this work, sysmocom has also created the manual you are reading.

At sysmocom, we draw a clear line between what is the Osmocom FOSS project, and what is sysmocom as a commercial entity. Under no circumstances does participation in the FOSS projects require any commercial relationship with sysmocom as a company.

OsmoGGSN User Manual 3 / 49

2.3 Corrections

We have prepared this manual in the hope that it will guide you through the process of installing, conﬁguring and debugging your deployment of cellular network infrastructure elements using Osmocom software. If you do ﬁnd errors, typos and/or omissions, or have any suggestions on missing topics, please do take the extra time and let us know.

2.4 Legal disclaimers

2.4.1 Spectrum License

As GSM and UMTS operate in licensed spectrum, please always double-check that you have all required licenses and that you do not transmit on any ARFCN or UARFCN that is not explicitly allocated to you by the applicable regulatory authority in your country.

Warning

Depending on your jurisdiction, operating a radio transmitter without a proper license may be considered a felony under criminal law!

2.4.2 Software License

The software developed by the Osmocom project and described in this manual is Free / Open Source Software (FOSS) and subject to so-called copyleft licensing.

Copyleft licensing is a legal instrument to ensure that this software and any modiﬁcations, extensions or derivative versions will always be publicly available to anyone, for any purpose, under the same terms as the original program as developed by Osmocom.

This means that you are free to use the software for whatever purpose, make copies and distribute them - just as long as you ensure to always provide/release the complete and corresponding source code.

Every Osmocom software includes a ﬁle called COPYING in its source code repository which explains the details of the license. The majority of programs is released under GNU Affero General Public License, Version 3 (AGPLv3).

If you have any questions about licensing, don’t hesitate to contact the Osmocom community. We’re more than happy to clarify if your intended use case is compliant with the software licenses.

2.4.3 Trademarks

All trademarks, service marks, trade names, trade dress, product names and logos appearing in this manual are the property of their respective owners. All rights not expressly granted herein are reserved.

For your convenience we have listed below some of the registered trademarks referenced herein. This is not a deﬁnitive or complete list of the trademarks used.

Osmocom® and OpenBSC® are registered trademarks of Holger Freyther and Harald Welte.

sysmocom® and sysmoBTS® are registered trademarks of sysmocom - systems for mobile communications GmbH.

ip.access® and nanoBTS® are registered trademarks of ip.access Ltd.

2.4.4 Liability

The software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the License text included with the software for more details.

OsmoGGSN User Manual 4 / 49

3 Introduction

3.1 Required Skills

Please note that even while the capital expenses of running mobile networks has decreased signiﬁcantly due to Osmocom software and associated hardware like sysmoBTS, GSM networks are still primarily operated by large GSM operators.

Neither the GSM speciﬁcation nor the GSM equipment was ever designed for networks to be installed and conﬁgured by anyone but professional GSM engineers, specialized in their respective area like radio planning, radio access network, back-haul or core network.

If you do not share an existing background in GSM network architecture and GSM protocols, correctly installing, conﬁguring and optimizing your GSM network will be tough, irrespective whether you use products with Osmocom software or those of traditional telecom suppliers.

GSM knowledge has many different ﬁelds, from radio planning through site installation to core network conﬁguration/administration.

The detailed skills required will depend on the type of installation and/or deployment that you are planning, as well as its associated network architecture. A small laboratory deployment for research at a university is something else than a rural network for a given village with a handful of cells, which is again entirely different from an urban network in a dense city.

Some of the useful skills we recommend are:

• general understanding about RF propagation and path loss in order to estimate coverage of your cells and do RF network planning.

• general understanding about GSM network architecture, its network elements and key transactions on the Layer 3 protocol

• general understanding about voice telephony, particularly those of ISDN heritage (Q.931 call control)

• understanding of GNU/Linux system administration and working on the shell

• understanding of TCP/IP networks and network administration, including tcpdump, tshark, wireshark protocol analyzers.

• ability to work with text based conﬁguration ﬁles and command-line based interfaces such as the VTY of the Osmocom network elements

3.2 Getting assistance

If you do have a support package / contract with sysmocom (or want to get one), please contact support@sysmocom.de with any issues you may have.

If you don’t have a support package / contract, you have the option of using the resources put together by the Osmocom community at http://projects.osmocom.org/, checking out the wiki and the mailing-list for community-based assistance. Please always remember, though: The community has no obligation to help you, and you should address your requests politely to them. The information (and software) provided at osmocom.org is put together by volunteers for free. Treat them like a friend whom you’re asking for help, not like a supplier from whom you have bought a service.

4 Overview

4.1 About OsmoGGSN

OsmoGGSN is a Free / Open Source Software implementation of the GPRS GGSN (Gateway GPRS support node) element in side the packet switched core network of 2G and 3G cellular networks.

The GGSN function is the tunnel endpoint on the core network side, from where the external (IP) packet data network

OsmoGGSN User Manual 5 / 49

4.2 Software Components

4.2.1 GTP Implementation (libgtp)

The OsmoGGSN source code includes a shared library implementation of the GTP protocol used on the GGSN-SGSN interface. This library and associated header ﬁles are installed system-wide and are available to other programs/applications.

In fact, libgtp is what the OsmoSGSN also uses for its use of GTP.

4.2.2 sgsnemu

In order to test OsmoGGSN without running a SGSN and other elements of a cellular network, there is a small command-line utility called sgsnemu which is able to simulate the customary operations of a SGSN towards the GGSN, such as a PDP Context Activation.

sgsnemu can even be used for testing against other GGSNs, as the GTP protocol is standardized across implementations.

4.2.3 osmo-ggsn

osmo-ggsn is the actual name of the OsmoGGSN executable program. It implements the GGSN functionality. All parameters are set using the conﬁguration ﬁle, by default located in ./osmo-ggsn.cfg

4.2.4 systemd service ﬁle

In contrib/osmo-ggsn.service you can ﬁnd a sample service ﬁle for OsmoGGSN which can be used with systemd.

4.2.5 init script

In contrib/osmo-ggsn.init you can ﬁnd a sample init script to be used on systems with classic init process.

4.3 Limitations

OsmoGGSN supports both GTP0 (GSM 09.60) and GTP1 (3GPP 29.060). In the following tables the support of each individual message type is detailed. The numbers before each feature indicates the relevant section in the standard.

4.3.1 GSM 09.60 (GTPv0)

Feature gtplib osmo-ggsn sgsnemu notes

7.4 Path Management Messages

7.4.1 Echo Request Supported Supported Supported

7.4.2 Echo Response Supported Supported Supported

7.4.3 Version Not Supported Supported Supported Supported

7.5 Tunnel Management Messages

7.5.1 Create PDP Context Request Supported Supported Supported

7.5.2 Create PDP Context Response Supported Supported Supported

7.5.3 Update PDP Context Request Supported Supported Not

7.5.4 Update PDP Context Response Supported Supported Not

7.5.5 Delete PDP Context Request Supported Supported Supported

7.5.6 Delete PDP Context Response Supported Supported Supported

7.5.7 Create AA PDP Context Request Unsupported Unsupported Unsupported

7.5.8 Create AA PDP Response Unsupported Unsupported Unsupported

7.5.9 Delete AA PDP Context Request Unsupported Unsupported Unsupported

7.5.10 Delete AA PDP Context Response Unsupported Unsupported Unsupported

OsmoGGSN User Manual 6 / 49

Feature gtplib osmo-ggsn sgsnemu notes

7.5.11 Error Indication Supported Supported Supported

7.5.12 PDU Notiﬁcation Request Unsupported Unsupported Unsupported

7.5.13 PDU Notiﬁcation Response Unsupported Unsupported Unsupported

7.5.14 PDU Notiﬁcation Reject Request Unsupported Unsupported Unsupported

7.5.15 PDU Notiﬁcation Reject Response Unsupported Unsupported Unsupported

7.6 Location Management Messages

7.6.1 Send Routeing Information for GPRS Request Unsupported Unsupported Not applicable

7.6.2 Send Routeing Information for GPRS Response Unsupported Unsupported Not applicable

7.6.3 Failure Report Request Unsupported Unsupported Not applicable

7.6.3 Failure Report Response Unsupported Unsupported Not applicable

7.6.5 Note MS GPRS Present Request Unsupported Unsupported Not applicable

7.6.6 Note MS GPRS Present Response Unsupported Unsupported Not applicable

7.5 Mobility Management Messages

7.5.1 Identiﬁcation Request Unsupported Not applicable Not applicable

7.5.2 Identiﬁcation Response Unsupported Not applicable Not applicable

7.5.3 SGSN Context Request Unsupported Not applicable Not applicable

7.5.4 SGSN Context Response Unsupported Not applicable Not applicable

7.5.5 SGSN Context Acknowledge Unsupported Not applicable Not applicable

4.3.2 3GPP 29.060 (GTPv1)

Feature gtplib osmo-ggsn sgsnemu notes

7.2 Path Management Messages

7.2.1 Echo Request Supported Supported Supported

7.2.2 Echo Response Supported Supported Supported

7.2.3 Version Not Supported Supported Supported Supported

7.2.4 Extension Headers Notiﬁcation Supported Supported Supported

7.3 Tunnel Management Messages

7.3.1 Create PDP Context Request Supported Supported Supported 1

7.3.2 Create PDP Context Response Supported Supported Supported

7.3.3 Update PDP Context Request Supported Supported Not applicable 1

7.3.4 Update PDP Context Response Supported Supported Not applicable

7.3.5 Delete PDP Context Request Supported Supported Supported

7.3.6 Delete PDP Context Response Supported Supported Supported

7.3.7 Error Indication Supported Supported Supported

7.3.8 PDU Notiﬁcation Request Unsupported Unsupported Unsupported

7.3.9 PDU Notiﬁcation Response Unsupported Unsupported Unsupported

7.3.10 PDU Notiﬁcation Reject Request Unsupported Unsupported Unsupported

7.3.10 PDU Notiﬁcation Reject Response Unsupported Unsupported Unsupported

7.4 Location Management Messages

7.4.1 Send Routeing Information for GPRS Request Unsupported Unsupported Not applicable

7.4.2 Send Routeing Information for GPRS Response Unsupported Unsupported Not applicable

7.4.3 Failure Report Request Unsupported Unsupported Not applicable

7.4.3 Failure Report Response Unsupported Unsupported Not applicable

7.4.5 Note MS GPRS Present Request Unsupported Unsupported Not applicable

7.4.6 Note MS GPRS Present Response Unsupported Unsupported Not applicable

7.5 Mobility Management Messages

7.5.1 Identiﬁcation Request Unsupported Not applicable Not applicable

7.5.2 Identiﬁcation Response Unsupported Not applicable Not applicable

7.5.3 SGSN Context Request Unsupported Not applicable Not applicable

7.5.4 SGSN Context Response Unsupported Not applicable Not applicable

7.5.5 SGSN Context Acknowledge Unsupported Not applicable Not applicable

7.5.6 Forward Relocation Request Unsupported Not applicable Not applicable

7.5.7 Forward Relocation Response Unsupported Not applicable Not applicable

7.5.8 Forward Relocation Complete Unsupported Not applicable Not applicable

OsmoGGSN User Manual 7 / 49

Feature gtplib osmo-ggsn sgsnemu notes

7.5.9 Relocation Cancel Request Unsupported Not applicable Not applicable

7.5.10 Relocation Cancel Response Unsupported Not applicable Not applicable

7.5.11 Forward Relocation Complete Unsupported Not applicable Not applicable

7.5.12 Forward SRNS Context Acknowledge Unsupported Not applicable Not applicable

7.5.13 Forward SRNS Context Unsupported Not applicable Not applicable

Notes

1) The "Secondary PDP Context Activation Procedure" is not supported.

5 Running OsmoGGSN

The OsmoGGSN executable (osmo-ggsn) offers the following command-line arguments:

5.1 SYNOPSIS

osmo-ggsn [-h|-V] [-D] [-c CONFIGFILE]

5.2 OPTIONS

-h, --help

Print a short help message about the supported options

-V, --version

Print the compile-time version number of the program

-D, --daemonize

Fork the process as a daemon into background.

-c, --conﬁg-ﬁle CONFIGFILE

Specify the ﬁle and path name of the conﬁguration ﬁle to be used. If none is speciﬁed, use osmo-ggsn.cfg in the current working directory.

5.3 Routing

Operating the OpenGGSN tun device naturally creates a network setup with multiple interfaces. Consider:

• Typical Linux setups prevent forwarding of packets between separate interfaces by default. To let subscribers reach the internet uplink from the tun device, it may be required to enable IP forwarding.

• Having a locally deﬁned address range assigned to the tun device requires either sensible routing for this address range, or that masquerading is enabled to allow your single uplink IP address to "proxy" for the tun.

These are decisions to be made on a network administration level.

In a trivial case where you have a single box serving GPRS to few subscribers on an arbitrary IP address range not known in the larger network, the easiest way to enable GPRS uplink would be to enable IP forwarding and masquerading.

To manually enable IPv4 forwarding and masquerading ad-hoc, you can do:

sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward" iptables -t nat -A POSTROUTING -o '*' -j MASQUERADE

(You may want to replace*with the network device name, like -o eth0)

There are various ways to enable these settings persistently, please refer to your distribution’s documentation — e.g. look for @net.ipv4.ip_forward=1@ in @/etc/sysctl.d/@, and https://wiki.debian.org/iptables for masquerading.

OsmoGGSN User Manual 8 / 49

5.4 Multiple instances

Running multiple instances of osmo-ggsn is possible if all GGSN instances are binding to different local IP addresse and all other interfaces (VTY, OML) are separated using the appropriate conﬁguration options. The IP based interfaces are binding to local host by default. In order to separate the processes, the user has to bind those services to speciﬁc but different IP addresses.

The VTY and the control interface can be bound to IP addresses from the loopback address range.

Example: Binding VTY and control interface to a speciﬁc ip-address

line vty

bind 127.0.0.2

ctrl

bind 127.0.0.2

Also make sure to place each instance’s GTP bind on a separate IP address (GTP uses a port number that is ﬁxed in the GTP speciﬁcations, so it will not be possible to pick differing ports on the same IP address), like:

ggsn ggsn0

gtp bind-ip 127.0.0.2

6 The Osmocom VTY Interface

All human interaction with Osmocom software is typically performed via an interactive command-line interface called the VTY.

Note

Integration of your programs and scripts should not be done via the telnet VTY interface, which is intended for human interaction only: the VTY responses may arbitrarily change in ways obvious to humans, while your scripts’ parsing will likely break often. For external software to interact with Osmocom programs (besides using the dedicated protocols), it is strongly recommended to use the Control interface instead of the VTY, and to actively request / implement the Control interface commands as required for your use case.

The interactive telnet VTY is used to

• explore the current status of the system, including its conﬁguration parameters, but also to view run-time state and statistics,

• review the currently active (running) conﬁguration,

• perform interactive changes to the conﬁguration (for those items that do not require a program restart),

• store the current running conﬁguration to the conﬁg ﬁle,

• enable or disable logging; to the VTY itself or to other targets.

The Virtual Tele Type (VTY) has the concept of nodes and commands. Each command has a name and arguments. The name may contain a space to group several similar commands into a speciﬁc group. The arguments can be a single word, a string, numbers, ranges or a list of options. The available commands depend on the current node. there are various keyboard shortcuts to ease ﬁnding commands and the possible argument values.

Conﬁguration ﬁle parsing during program start is actually performed the VTY’s CONFIG node, which is also available in the telnet VTY. Apart from that, the telnet VTY features various interactive commands to query and instruct a running Osmocom program. A main difference is that during conﬁg ﬁle parsing, consistent indenting of parent vs. child nodes is required, while the interactive VTY ignores indenting and relies on the exit command to return to a parent node.

Note

In the CONFIG node, it is not well documented which commands take immediate effect without requiring a program restart. To save your current conﬁg with changes you may have made, you may use the write file command to overwrite your conﬁg ﬁle with the current conﬁguration, after which you should be able to restart the program with all changes taking effect.

OsmoGGSN User Manual 9 / 49

This chapter explains most of the common nodes and commands. A more detailed list is available in various programs’ VTY reference manuals, e.g. see [vty-ref-osmomsc].

There are common patterns for the parameters, these include IPv4 addresses, number ranges, a word, a line of text and choice. The following will explain the commonly used syntactical patterns:

Table 1: VTY Parameter Patterns

Pattern Example Explanation

A.B.C.D 127.0.0.1 An IPv4 address A.B.C.D/M 192.168.1.0/24 An IPv4 address and mask X:X::X:X ::1 An IPv6 address X:X::X:X/M ::1/128 An IPv6 address and mask TEXT example01 A single string without any spaces, tabs .TEXT Some information A line of text (OptionA|OptionB|OptionC) OptionA A choice between a list of available options <0-10> 5 A number from a range

6.1 Accessing the telnet VTY

The VTY of a given Osmocom program is implemented as a telnet server, listening to a speciﬁc TCP port.

Please see Appendix A to check for the default TCP port number of the VTY interface of the speciﬁc Osmocom software you would like to connect to.

As telnet is insecure and offers neither strong authentication nor encryption, the VTY by default only binds to localhost (127.0.0.1) and will thus not be reachable by other hosts on the network.

Warning

By default, any user with access to the machine running the Osmocom software will be able to connect to the VTY. We assume that such systems are single-user systems, and anyone with local access to the system also is authorized to access the VTY. If you require stronger security, you may consider using the packet ﬁlter of your operating system to restrict access to the Osmocom VTY ports further.

6.2 VTY Nodes

The VTY by default has the following minimal nodes:

VIEW

When connecting to a telnet VTY, you will be on the VIEW node. As its name implies, it can only be used to view the system status, but it does not provide commands to alter the system state or conﬁguration. As long as you are in the non-privileged VIEW node, your prompt will end in a > character.

ENABLE

The ENABLE node is entered by the enable command, from the VIEW node. Changing into the ENABLE node will unlock all kinds of commands that allow you to alter the system state or perform any other change to it. The ENABLE node and its children are signiﬁed by a # character at the end of your prompt. You can change back from the ENABLE node to the VIEW node by using the disable command.

CONFIG

The CONFIG node is entered by the configure terminal command from the ENABLE node. The conﬁg node is used to change the run-time conﬁguration parameters of the system. The prompt will indicate that you are in the conﬁg node by a (config)# prompt sufﬁx.

OsmoGGSN User Manual 10 / 49

You can always leave the CONFIG node or any of its children by using the end command. This node is also automatically entered at the time the conﬁguration ﬁle is read. All conﬁguration ﬁle lines are processed as if they were entered from the VTY CONFIG node at start-up.

Other

Depending on the speciﬁc Osmocom program you are running, there will be few or more other nodes, typically below the CONFIG node. For example, the OsmoBSC has nodes for each BTS, and within the BTS node one for each TRX, and within the TRX node one for each Timeslot.

6.3 Interactive help

The VTY features an interactive help system, designed to help you to efﬁciently navigate is commands.

Note

The VTY is present on most Osmocom GSM/UMTS/GPRS software, thus this chapter is present in all the relevant manuals. The detailed examples below assume you are executing them on the OsmoMSC VTY. They will work in similar fashion on the other VTY interfaces, while the node structure will differ in each program.

6.3.1 The question-mark (?) command

If you type a single ? at the prompt, the VTY will display possible completions at the exact location of your currently entered command.

If you type ? at an otherwise empty command (without having entered even only a partial command), you will get a list of the ﬁrst word of all possible commands available at this node:

Example: Typing ? at start of OsmoMSC prompt

OsmoMSC>

show Show running system information list Print command list exit Exit current mode and down to previous mode help Description of the interactive help system enable Turn on privileged mode command terminal Set terminal line parameters who Display who is on vty logging Configure logging no Negate a command or set its defaults sms SMS related commands subscriber Operations on a Subscriber

Type ? here at the prompt, the ? itself will not be printed.

If you have already entered a partial command, ? will help you to review possible options of how to continue the command. Let’s say you remember that show is used to investigate the system status, but you don’t remember the exact name of the object. Hitting ? after typing show will help out:

Example: Typing ? after a partial command

OsmoMSC> show

version Displays program version online-help Online help history Display the session command history cs7 ITU-T Signaling System 7 logging Show current logging configuration alarms Show current logging configuration talloc-context Show talloc memory hierarchy

OsmoGGSN User Manual 11 / 49

stats Show statistical values asciidoc Asciidoc generation rate-counters Show all rate counters fsm Show information about finite state machines fsm-instances Show information about finite state machine instances sgs-connections Show SGs interface connections / MMEs subscriber Operations on a Subscriber bsc BSC connection Subscriber Connections transaction Transactions statistics Display network statistics sms-queue Display SMSqueue statistics smpp SMPP Interface

Type ? after the show command, the ? itself will not be printed.

You may pick the bsc object and type ? again:

Example: Typing ? after show bsc

OsmoMSC> show bsc

<cr>

By presenting <cr> as the only option, the VTY tells you that your command is complete without any remaining arguments being available, and that you should hit enter, a.k.a. "carriage return".

6.3.2 TAB completion

The VTY supports tab (tabulator) completion. Simply type any partial command and press <tab>, and it will either show you a list of possible expansions, or completes the command if there’s only one choice.

Example: Use of <tab> pressed after typing only s as command

OsmoMSC> s

show sms subscriber

Type <tab> here.

At this point, you may choose show, and then press <tab> again:

Example: Use of <tab> pressed after typing show command

OsmoMSC> show version online-help history cs7 logging alarms talloc-context stats asciidoc rate-counters fsm fsm-instances sgs-connections subscriber bsc connection transaction statistics sms-queue smpp

Type <tab> here.

6.3.3 The list command

The list command will give you a full list of all commands and their arguments available at the current node:

Example: Typing list at start of OsmoMSC VIEW node prompt

OsmoGGSN User Manual 12 / 49

OsmoMSC> list

show version show online-help list exit help enable terminal length <0-512> terminal no length who show history show cs7 instance <0-15> users show cs7 (sua|m3ua|ipa) [<0-65534>] show cs7 instance <0-15> asp show cs7 instance <0-15> as (active|all|m3ua|sua) show cs7 instance <0-15> sccp addressbook show cs7 instance <0-15> sccp users show cs7 instance <0-15> sccp ssn <0-65535> show cs7 instance <0-15> sccp connections show cs7 instance <0-15> sccp timers logging enable logging disable logging filter all (0|1) logging color (0|1) logging timestamp (0|1) logging print extended-timestamp (0|1) logging print category (0|1) logging print category-hex (0|1) logging print level (0|1) logging print file (0|1|basename) [last] logging set-log-mask MASK logging level (rll|cc|mm|rr|mncc|pag|msc|mgcp|ho|db|ref|ctrl|smpp|ranap|vlr|iucs|bssap| ←-

SENDER_ID send .LINE

+ 37 hidden pages

Sysmocom OsmoGGSN User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

1 Foreword

1.1 Acknowledgements

2 Preface

2.1 FOSS lives by contribution!

2.2 Osmocom and sysmocom

2.3 Corrections

2.4 Legal disclaimers

3 Introduction

3.1 Required Skills

3.2 Getting assistance

4 Overview

4.1 About OsmoGGSN

4.2 Software Components

sgsnemu can even be used for testing against other GGSNs, as the GTP protocol is standardized across implementations.

osmo-ggsn is the actual name of the OsmoGGSN executable program. It implements the GGSN functionality. All parameters are set using the conﬁguration ﬁle, by default located in ./osmo-ggsn.cfg

4.3 Limitations

5 Running OsmoGGSN

5.1 SYNOPSIS

5.2 OPTIONS

5.3 Routing

5.4 Multiple instances

6 The Osmocom VTY Interface

6.1 Accessing the telnet VTY

6.2 VTY Nodes

6.3 Interactive help