299 lines
12 KiB
Plaintext
299 lines
12 KiB
Plaintext
== Foreword
|
|
|
|
Digital cellular networks based on the GSM specification were designed
|
|
in the late 1980s and first deployed in the early 1990s 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 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.
|
|
|
|
|
|
=== 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, 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.
|
|
|
|
|
|
ifdef::gfdl-enabled[]
|
|
=== Endorsements
|
|
|
|
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.
|
|
endif::[]
|
|
|
|
== 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.
|
|
|
|
|
|
=== 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 benefiting 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, workarounds
|
|
* 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 -
|
|
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.
|
|
|
|
|
|
=== Corrections
|
|
|
|
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 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!
|
|
|
|
|
|
==== 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 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
|
|
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.
|
|
|
|
|
|
==== 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 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
|
|
'ip.access Ltd.'
|
|
|
|
|
|
==== 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.
|
|
|
|
|
|
ifdef::gfdl-enabled[]
|
|
==== Documentation License
|
|
|
|
Please see <<licenses-gfdl>> for further information.
|
|
endif::[]
|
|
|
|
|
|
== Introduction
|
|
|
|
|
|
=== 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 and
|
|
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
|
|
shell
|
|
* 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 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.
|