aboutsummaryrefslogtreecommitdiffstats
path: root/common/chapters/preface.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'common/chapters/preface.adoc')
-rw-r--r--common/chapters/preface.adoc274
1 files changed, 274 insertions, 0 deletions
diff --git a/common/chapters/preface.adoc b/common/chapters/preface.adoc
new file mode 100644
index 0000000..1893d1f
--- /dev/null
+++ b/common/chapters/preface.adoc
@@ -0,0 +1,274 @@
+== 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 into
+what is today known as 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 quick also commercial interest,
+contribution and adoption. This added 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.
+
+It has been a most exciting ride during the last seven years. I
+wouldn't want to miss it under any circumstances.
+
+-- Harald Welte, Osmocom.org and OpenBSC founder, January 2016.
+
+
+== 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, Alexander Huemer
+
+May the source be with you!
+
+-- Harald Welte, Osmocom.org and OpenBSC founder, January 2016.
+
+
+== 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.
+
+
+=== 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 are the by far the largest developers and
+contributors 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 requires participation in the FOSS projects any commercial
+relationship with sysmocom as a company.
+
+
+=== Corrections
+
+We have prepared this manual in the hope 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, mistakes 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.
+
+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 respecitve
+owners. All rights not expressly granted herein are reserved.
+
+For your convenience we have listed below some of the registrered
+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)' is registered trasdemarks 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.
+
+
+==== Documentation License
+
+Please see <<licenses-gfdl>> for further information.
+
+
+== Introduction
+
+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 through 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 us at support@sysmocom.de with any issues you
+may have.
+
+If you don't have a support package / contract, please be advised that
+sysmocom can only provide very basic assistance. However, in any case,
+you can try to use the resources put together by the Osmocom community
+at http://openbsc.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.