== Foreword 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 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 <>) 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 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 - 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 <> 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, 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.