Digital cellular networks based on the GSM specification were designed
in the late 1980ies and first 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, first created by government bodies within CEPT,
then handed over to ETSI, and now in the hands of 3GPP. Nevertheless,
for the first 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 specifications, 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 and Free / Open Source software
`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.
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
* 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, fixes 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.
* 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.
This version of the manual is endorsed by Harald Welte as the official
version of the manual.
While the GFDL license (see <<licenses-gfdl>>) permits anyone to create
and distribute modified versions of this manual, such modified
versions must remove the above endorsement.
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.
=== 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 benefitting 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 qualified bug reports, work-arounds
* sharing any modifications to the software you may have made, whether
bug fixes 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.
=== Osmocom and sysmocom
Some of the founders of the Osmocom project have established sysmocom as
a company to provide products and services related to Osmocom.
sysmocom and its staff have by far contributed 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
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.
We have prepared this manual in the hope that it will guide you through the
process of installing, configuring and debugging your deployment of
cellular network infrastructure elements using Osmocom software. If
you do find errors, typos and/or omissions, or have any suggestions
on missing topics, please do take the extra time and let us know.
=== Legal disclaimers
==== Spectrum License
As GSM operates in licensed spectrum, please always double-check that
you have all required licenses and that you do not transmit on any ARFCN
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!
==== 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 is a legal instrument to ensure that this software
and any modifications, 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 file 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
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.
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 definitive or complete list
of the trademarks used.
'Osmocom(R)' and 'OpenBSC(R)' are registered trademarks of Holger
Freyther and Harald Welte.
'sysmocom(R)' and 'sysmoBTS(R)' are registered trademarks of
'sysmocom - systems for mobile communications GmbH'.
'ip.access(R)' and 'nanoBTS(R)' are registered trademarks of
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.
==== Documentation License
Please see <<licenses-gfdl>> for further information.
=== Required Skills
Please note that even while the capital expenses of running mobile
networks has decreased significantly due to Osmocom software and
associated hardware like sysmoBTS, GSM networks are still primarily
operated by large GSM operators.
Neither the GSM specification nor the GSM equipment was ever designed
for networks to be installed and configured 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,
GSM protocols, correctly installing, configuring 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 fields, from radio planning through
site installation to core network configuration/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
* understanding of TCP/IP networks and network administration, including
tcpdump, tshark, wireshark protocol analyzers.
* ability to work with text based configuration files and command-line
based interfaces such as the VTY of the Osmocom network elements
=== Getting assistance
If you do have a support package / contract with sysmocom (or want to
get one), please contact firstname.lastname@example.org with any issues you
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.