- WARNING
-
osmo-nitb is obsolete since 2017. It is not actively maintained, and it lack several man-years of development effort that went into the so-called post-NITB stack consisting of separate OsmoBSC, OsmoMSC, OsmoMGW and OsmoHLR. You should not use this software except for archaeological purpose. You will be on your own. Do not contact the developers about any issues you may experience while running unsuported, obsolete software!
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
-
NLnet Foundation, for providing funding for a number of individual work items within the Osmocom universe, such as LTE support in OsmoCBC or GPRS/EGPRS support for Ericsson RBS6000.
-
WaveMobile Ltd, for many years of sponsoring.
May the source be with you!
— Harald Welte, Osmocom.org and OpenBSC founder, January 2016.
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.
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® 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.
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
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 https://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.
If you would like to obtain professional/commercial support on Osmocom CNI, you can always reach out to sales@sysmocom.de to discuss your support needs. Purchasing support from sysmocom helps to cover the ongoing maintenance of the Osmocom CNI software stack.
Overview
This manual should help you getting started with OsmoNITB. It will cover aspects of configuring and running the OsmoNITB.
- WARNING
-
osmo-nitb is obsolete since 2017. It is not actively maintained, and it lack several man-years of development effort that went into the so-called post-NITB stack consisting of separate OsmoBSC, OsmoMSC, OsmoMGW and OsmoHLR. You should not use this software except for archaeological purpose. You will be on your own. Do not contact the developers about any issues you may experience while running unsuported, obsolete software!
About OsmoNITB
OsmoNITB is one particular version of the OpenBSC software suite. Unlike classic, distributed, hierarchical GSM networks, OsmoNITB implements all parts of a GSM Network (BSC, MSC, VLR, HLR, AUC, SMSC) in the box, i.e. in one element.
The difference between classic GSM network architecture and the OsmoNITB based GSM network architecture is illustrated in [fig-gsm-classic] and [fig-gsm-nitb].
Software Components
OsmoNITB contains a variety of different software components, which we’ll quickly describe in this section.
A-bis Implementation
OsmoNITB implements the ETSI/3GPP specified A-bis interface, including 3GPP TS 48.056 [3gpp-ts-48-056] (LAPD), 3GPP TS 48.058 [3gpp-ts-48-058] (RSL) and 3GPP TS 52.021 [3gpp-ts-52-021] (OML). In addition, it supports a variety of vendor-specific extensions and dialects in order to communicate with BTSs from Siemens, Nokia, Ericsson, ip.access and sysmocom.
For more information, see [bts] and [bts-examples].
BSC Implementation
The BSC implementation covers the classic functionality of a GSM Base Station Controller, i.e.
-
configuring and bringing up BTSs with their TRXs and TSs
-
implementing the A-bis interface / protocols for signalling and actual voice data (TRAU frames).
-
processing measurement results from the mobile stations in dedicated mode, performing hand-over decision and execution.
-
Terminating the 3GPP TS 24.008 [3gpp-ts-24-008] RR (Radio Resource) sub-layer from the MS.
For more information, see [net], [bts] and [bts-examples].
HLR/AUC
A minimalistic implementation of the subscriber database (HLR) and subscriber secret key storage (AUC).
For more information, see [hlr].
SMSC
A minimal store-and-forward server for SMS, supporting both MO and MT SMS service, as well as multi-part messages.
The built-in SMSC also supports an external SMSC interface. For more information, see [smpp].
MSC
The MSC component of OsmoNITB implements the mobility management (MM) functions of the TS 04.08, as well as the optional security related procedures for cryptographic authentication and encryption.
Furthermore, it can handle TS 04.08 Call Control (CC), either by use of an internal MNCC handler, or by use of an external MNCC agent. For more information see [mncc].
TRAU mapper / E1 sub-channel muxer
Unlike classic GSM networks, OsmoNITB does not perform any transcoding. Rather, a compatible codec is selected for both legs of a call, and codec frames are passed through transparently. In order to achieve this with E1 based BTS, OsmoNITB contains a E1 sub-channel de- and re-multiplexer as well as a TRAU mapper that can map uplink to downlink frames and vice versa.
RTP proxy
BTS models implementing A-bis over IP don’t use classic TRAU frames but typically transport the voice codec frames as RTP/UDP/IP protocol. OsmoNITB can either instruct the BTSs to send those voice streams directly to each other (BTS to BTS without any intermediary), or it can run an internal RTP proxy for passing frames from one BTS to another.
Running OsmoNITB
The OsmoNITB executable (osmo-nitb
) offers the following command-line
arguments:
SYNOPSIS
osmo-nitb [-h|-V] [-d DBGMASK] [-D] [-c CONFIGFILE] [-s] [-T] [-e LOGLEVEL] [-l DATABASE] [-a] [-P] [-m] [-C] [-r RFCTL]
OPTIONS
- -h, --help
-
Print a short help message about the supported options
- -V, --version
-
Print the compile-time version number of the program
- -d, --debug DBGMASK,DBGLEVELS
-
Set the log subsystems and levels for logging to stderr. This has mostly been superseded by VTY-based logging configuration, see [logging] for further information.
- -D, --daemonize
-
Fork the process as a daemon into background.
- -c, --config-file CONFIGFILE
-
Specify the file and path name of the configuration file to be used. If none is specified, use
openbsc.cfg
in the current working directory. - -s, --disable-color
-
Disable colors for logging to stderr. This has mostly been deprecated by VTY based logging configuration, see [logging] for more information.
- -T, --timestamp
-
Enable time-stamping of log messages to stderr. This has mostly been deprecated by VTY based logging configuration, see [logging] for more information.
- -e, --log-level LOGLEVEL
-
Set the global log level for logging to stderr. This has mostly been deprecated by VTY based logging configuration, see [logging] for more information.
- -l, --database DATABASE
-
Specify the file name of the SQLite3 database to use as HLR/AUC storage
- -a, --authorize-everyone
-
Authorize every subscriber to the network. This corresponds to the
auth-policy open
VTY configuration option.
- WARNING
-
This is dangerous as you may disrupt services to subscribers that are not part of your network! Don’t use unless you absolutely know what you’re doing!
- -P, --rtp-proxy
-
Enable the RTP proxy code inside OsmoNITB. This will force all voice RTP data to pass through OsmoNITB, rather than going directly from BTS to MGW, or BTS to BTS.
- -M, --mncc-sock-path
-
Enable the MNCC socket for an external MNCC handler. See [mncc] for further information.
- -m, --mncc-sock
-
Same as option -M (deprecated).
- -C, --no-dbcounter
-
Disable the regular periodic synchronization of statistics counters to the database.
- -r, --rf-ctl RFCTL
-
Offer a Unix domain socket for RF control at the path/filename RFCTL in the file system.
Multiple instances
Running multiple instances of osmo-nitb
is possible if all interfaces (VTY,
OML) are separated using the appropriate configuration 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 specific but different
IP addresses.
The VTY and the control interface can be bound to IP addresses from the loopback address range.
line vty
bind 127.0.0.2
ctrl
bind 127.0.0.2
The OML interface also needs to be separated by binding it to different IP addresses. Usually it is not possible to use addresses from the loopback address range here since the OML interface needs to be reachable by an external BTS. If only one ethernet interface is available, sub-devices with different IP addresses can be created.
e1_input
ipa bind 10.9.1.101
Note
|
Depending on the application, it is necessary to have different ARFCN, MCC, MNC and network name settings. It might also be necessary to point to different database and config files using command line options (see option -l and -c). |
Note
|
If an external MNCC handler is used, the user has to assign a different socket path to reach osmo-nitb instance using commandline option -M. If option -M is left out, the internal MNCC handler is used and no further configuration is required |
Control interface
The actual protocol is described in [common-control-if], the variables common to all programs using it are described in [ctrl_common_vars]. The variables shared with OsmoBSC are described in corresponding section of OsmoBSC documentation.Here we describe variables specific to OsmoNITB.
Name | Access | Trap | Value | Comment |
---|---|---|---|---|
subscriber-modify-v1 |
WO |
No |
"<imsi>,<msisdn>,<alg>,<ki>" |
See [sub1] for details. |
subscriber-delete-v1 |
WO |
No |
"<imsi>" |
See [subdel] for details. |
subscriber-list-active-v1 |
RO |
No |
Return list of active subscribers. |
subscriber-modify-v1
Modify (or add if missing) subscriber entry with the give IMSI, MSISDN, Ki and algorithm (valid values are "none", "xor" and "comp128v1"). The subscriber is automatically marked as authorized.
subscriber-delete-v1
Delete the subscriber with the given IMSI. Returns "Removed active subscriber" or "Removed" depending on the subscriber’s use status.
The following variables are only available over control interface of osmo-bsc_nat program.
Name | Access | Trap | Value | Comment |
---|---|---|---|---|
net.0.bsc.N.* |
RW |
Yes |
Arbitrary variable |
Forward given command to BSC N control interface. |
net.0.bsc_cfg.N.access-list-name |
RW |
No |
"<name>" |
Set/Get ACL for a given BSC N. |
net.0.bsc_cfg.N.no-access-list-name |
WO |
No |
Ignored |
Remove ACL for a given BSC N. |
net.0.add.allow.access-list.A |
WO |
No |
"<regexp>" |
See [nacl] for details. |
net.0.save-configuration |
WO |
No |
Ignored |
Save current running config into file. |
net.0.bsc.N.notification-rejection-v1 |
NA |
Yes |
"imsi=<imis>" |
See [narej] for details. |
allow.access-list
Add given regular expression for matching IMSI(s) to allowed access list A.
notification-rejection-v1
This TRAP event notifies all connected clients about IMSI which was rejected by BSC N.
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 configuration parameters, but also to view run-time state and statistics,
-
review the currently active (running) configuration,
-
perform interactive changes to the configuration (for those items that do not require a program restart),
-
store the current running configuration to the config file,
-
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 specific 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 finding commands and the possible argument values.
Configuration file 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 config file 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
config with changes you may have made, you may use the write file command to
overwrite your config file with the current configuration, after which you
should be able to restart the program with all changes taking effect. |
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:
Pattern | Example | Explanation |
---|---|---|
|
|
An IPv4 address |
|
|
An IPv4 address and mask |
|
|
An IPv6 address |
|
|
An IPv6 address and mask |
|
|
A single string without any spaces, tabs |
|
|
A line of text |
|
|
A choice between a list of available options |
|
|
A number from a range |
Accessing the telnet VTY
The VTY of a given Osmocom program is implemented as a telnet server, listening to a specific TCP port.
Please see [port-numbers] to check for the default TCP port number of the VTY interface of the specific 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 filter of your operating system to restrict access to the Osmocom VTY ports further. |
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 configuration. 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 signified by a # character at the end of your prompt.
You can change back from the ENABLE node to the VIEW node by using thedisable
command. - CONFIG
-
The CONFIG node is entered by the
configure terminal
command from the ENABLE node. The config node is used to change the run-time configuration parameters of the system. The prompt will indicate that you are in the config node by a(config)#
prompt suffix.
You can always leave the CONFIG node or any of its children by using theend
command.
This node is also automatically entered at the time the configuration file is read. All configuration file lines are processed as if they were entered from the VTY CONFIG node at start-up. - Other
-
Depending on the specific 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.
Interactive help
The VTY features an interactive help system, designed to help you to efficiently 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. |
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 first word of
all possible commands available at this node:
?
at start of OsmoMSC promptOsmoMSC> <1>
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:
?
after a partial commandOsmoMSC> show <1>
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
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 theshow
command, the?
itself will not be printed.
You may pick the bsc
object and type ?
again:
?
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".
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.
<tab>
pressed after typing only s
as commandOsmoMSC> s<1>
show sms subscriber
-
Type
<tab>
here.
At this point, you may choose show
, and then press <tab>
again:
<tab>
pressed after typing show
commandOsmoMSC> show <1>
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.
The list
command
The list
command will give you a full list of all commands and their
arguments available at the current node:
list
at start of OsmoMSC VIEW node promptOsmoMSC> 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|sgs|lglobal|llapd|linp|lmux|lmi|lmib|lsms|lctrl|lgtp|lstats|lgsup|loap|lss7|lsccp|lsua|lm3ua|lmgcp|ljibuf|lrspro) (debug|info|notice|error|fatal)
logging level set-all (debug|info|notice|error|fatal)
logging level force-all (debug|info|notice|error|fatal)
no logging level force-all
show logging vty
show alarms
show talloc-context (application|all) (full|brief|DEPTH)
show talloc-context (application|all) (full|brief|DEPTH) tree ADDRESS
show talloc-context (application|all) (full|brief|DEPTH) filter REGEXP
show stats
show stats level (global|peer|subscriber)
show asciidoc counters
show rate-counters
show fsm NAME
show fsm all
show fsm-instances NAME
show fsm-instances all
show sgs-connections
show subscriber (msisdn|extension|imsi|tmsi|id) ID
show subscriber cache
show bsc
show connection
show transaction
sms send pending
sms delete expired
subscriber create imsi ID
subscriber (msisdn|extension|imsi|tmsi|id) ID sms sender (msisdn|extension|imsi|tmsi|id) SENDER_ID send .LINE
subscriber (msisdn|extension|imsi|tmsi|id) ID silent-sms sender (msisdn|extension|imsi|tmsi|id) SENDER_ID send .LINE
subscriber (msisdn|extension|imsi|tmsi|id) ID silent-call start (any|tch/f|tch/any|sdcch)
subscriber (msisdn|extension|imsi|tmsi|id) ID silent-call stop
subscriber (msisdn|extension|imsi|tmsi|id) ID ussd-notify (0|1|2) .TEXT
subscriber (msisdn|extension|imsi|tmsi|id) ID ms-test close-loop (a|b|c|d|e|f|i)
subscriber (msisdn|extension|imsi|tmsi|id) ID ms-test open-loop
subscriber (msisdn|extension|imsi|tmsi|id) ID paging
show statistics
show sms-queue
logging filter imsi IMSI
show smpp esme
Tip
|
Remember, the list of available commands will change significantly depending on the Osmocom program you are accessing, its software version and the current node you’re at. Compare the above example of the OsmoMSC VIEW node with the list of the OsmoMSC NETWORK config node: |
list
at start of OsmoMSC NETWORK config node promptOsmoMSC(config-net)# list
help
list
write terminal
write file
write memory
write
show running-config
exit
end
network country code <1-999>
mobile network code <0-999>
short name NAME
long name NAME
encryption a5 <0-3> [<0-3>] [<0-3>] [<0-3>]
authentication (optional|required)
rrlp mode (none|ms-based|ms-preferred|ass-preferred)
mm info (0|1)
timezone <-19-19> (0|15|30|45)
timezone <-19-19> (0|15|30|45) <0-2>
no timezone
periodic location update <6-1530>
no periodic location update
The attribute system
The VTY allows to edit the configuration at runtime. For many VTY commands the configuration change is immediately valid but for some commands a change becomes valid on a certain event only. In some cases it is even necessary to restart the whole process.
To give the user an overview, which configuration change applies when, the VTY
implemets a system of attribute flags, which can be displayed using the show
command with the parameter vty-attributes
show vty-attributes
at the VTY promptOsmoBSC> show vty-attributes
Global attributes:
^ This command is hidden (check expert mode)
! This command applies immediately
@ This command applies on VTY node exit
Library specific attributes:
A This command applies on ASP restart
I This command applies on IPA link establishment
L This command applies on E1 line update
Application specific attributes:
o This command applies on A-bis OML link (re)establishment
r This command applies on A-bis RSL link (re)establishment
l This command applies for newly created lchans
The attributes are symbolized through a single ASCII letter (flag) and do exist in three levels. This is more or less due to the technical aspects of the VTY implementation. For the user, the level of an attribute has only informative purpose.
The global attributes, which can be found under the same attribute letter in every osmocom application, exist on the top level. The Library specific attributes below are used in various osmocom libraries. Like with the global attributes the attribute flag letter stays the same throughout every osmocom application here as well. On the third level one can find the application specific attributes. Those are unique to each osmocom application and the attribute letters may have different meanings in different osmocom applications. To make the user more aware of this, lowercase letters were used as attribute flags.
The list
command with the parameter with-flags
displays a list of available
commands on the current VTY node, along with attribute columns on the left side.
Those columns contain the attribute flag letters to indicate to the user how the
command behaves in terms of how and when the configuration change takes effect.
list with-flags
at the VTY promptOsmoBSC(config-net-bts)# list with-flags
. ... help
. ... list [with-flags]
. ... show vty-attributes
. ... show vty-attributes (application|library|global)
. ... write terminal
. ... write file [PATH]
. ... write memory
. ... write
. ... show running-config <1>
. ... exit
. ... end
. o.. type (unknown|bs11|nanobts|rbs2000|nokia_site|sysmobts) <2>
. ... description .TEXT
. ... no description
. o.. band BAND
. .r. cell_identity <0-65535> <3>
. .r. dtx uplink [force]
. .r. dtx downlink
. .r. no dtx uplink
. .r. no dtx downlink
. .r. location_area_code <0-65535>
. o.. base_station_id_code <0-63>
. o.. ipa unit-id <0-65534> <0-255>
. o.. ipa rsl-ip A.B.C.D
. o.. nokia_site skip-reset (0|1)
! ... nokia_site no-local-rel-conf (0|1) <4>
! ... nokia_site bts-reset-timer <15-100> <4>
-
This command has no attributes assigned.
-
This command applies on A-bis OML link (re)establishment.
-
This command applies on A-bis RSL link (re)establishment.
-
This command applies immediately.
There are multiple columns because a single command may be associated with multiple attributes at the same time. To improve readability each flag letter gets a dedicated column. Empty spaces in the column are marked with a dot (".")
In some cases the listing will contain commands that are associated with no flags at all. Those commands either play an exceptional role (interactive commands outside "configure terminal", vty node navigation commands, commands to show / write the config file) or will require a full restart of the overall process to take effect.
The expert mode
Some VTY commands are considered relatively dangerous if used in production operation, so the general approach is to hide them. This means that they don’t show up anywhere but the source code, but can still be executed. On the one hand, this approach reduces the risk of an accidental invocation and potential service degradation; on the other, it complicates intentional use of the hidden commands.
The VTY features so-called expert mode, that makes the hidden commands appear in
the interactive help, as well as in the XML VTY reference, just like normal ones. This
mode can be activated from the VIEW node by invoking the enable
command with the
parameter expert-mode
. It remains active for the individual VTY session, and gets
disabled automatically when the user switches back to the VIEW node or terminates
the session.
A special attribute in the output of the list with-flags
command indicates whether
a given command is hidden in normal mode, or is a regular command:
list with-flags
commandOsmoBSC> enable expert-mode <1>
OsmoBSC# list with-flags
...
^ bts <0-255> (activate-all-lchan|deactivate-all-lchan) <2>
^ bts <0-255> trx <0-255> (activate-all-lchan|deactivate-all-lchan) <2>
. bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> mdcx A.B.C.D <0-65535> <3>
^ bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> (borken|unused) <2>
. bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> handover <0-255> <3>
. bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> assignment <3>
. bts <0-255> smscb-command (normal|schedule|default) <1-4> HEXSTRING <3>
...
-
This command enables the expert mode.
-
This is a hidden command (only shown in the expert mode).
-
This is a regular command that is always shown regardless of the mode.
libosmocore Logging System
In any reasonably complex software it is important to understand how to enable and configure logging in order to get a better insight into what is happening, and to be able to follow the course of action. We therefore ask the reader to bear with us while we explain how the logging subsystem works and how it is configured.
Most Osmocom Software (like osmo-bts
, osmo-bsc
, osmo-nitb
,
osmo-sgsn
and many others) uses the same common logging system.
This chapter describes the architecture and configuration of this common logging system.
The logging system is composed of
-
log targets (where to log),
-
log categories (who is creating the log line),
-
log levels (controlling the verbosity of logging), and
-
log filters (filtering or suppressing certain messages).
All logging is done in human-readable ASCII-text. The logging system is configured by means of VTY commands that can either be entered interactively, or read from a configuration file at process start time.
Log categories
Each sub-system of the program in question typically logs its messages as a
different category, allowing fine-grained control over which log
messages you will or will not see. For example, in OsmoBSC, there are
categories for the protocol layers rsl
, rr
, mm
,
cc
and many others. To get a list of categories interactively
on the vty, type: logging level ?
Log levels
For each of the log categories (see [log_categories]), you can set an independent log level, controlling the level of verbosity. Log levels include:
- fatal
-
Fatal messages, causing abort and/or re-start of a process. This shouldn’t happen.
- error
-
An actual error has occurred, its cause should be further investigated by the administrator.
- notice
-
A noticeable event has occurred, which is not considered to be an error.
- info
-
Some information about normal/regular system activity is provided.
- debug
-
Verbose information about internal processing of the system, used for debugging purpose. This will log the most.
The log levels are inclusive, e.g. if you select info, then this really means that all events with a level of at least info will be logged, i.e. including events of notice, error and fatal.
So for example, in OsmoBSC, to set the log level of the Mobility
Management category to info, you can use the following command:
log level mm info
.
There is also a special command to set all categories as a one-off to a desired
log level. For example, to silence all messages but those logged as notice and
above issue the command: log level set-all notice
Afterwards you can adjust specific categories as usual.
A similar command is log level force-all <level>
which causes all categories
to behave as if set to log level <level> until the command is reverted with
no log level force-all
after which the individually-configured log levels will
again take effect. The difference between set-all
and force-all
is that
set-all
actually changes the individual category settings while force-all
is a (temporary) override of those settings and does not change them.
Log printing options
The logging system has various options to change the information displayed in the log message.
- log color 1
-
With this option each log message will log with the color of its category. The color is hard-coded and can not be changed. As with other options a 0 disables this functionality.
- log timestamp 1
-
Includes the current time in the log message. When logging to syslog this option should not be needed, but may come in handy when debugging an issue while logging to file.
- log print extended-timestamp 1
-
In order to debug time-critical issues this option will print a timestamp with millisecond granularity.
- log print category 1
-
Prefix each log message with the category name.
- log print category-hex 1
-
Prefix each log message with the category number in hex (<000b>).
- log print level 1
-
Prefix each log message with the name of the log level.
- log print file 1
-
Prefix each log message with the source file and line number. Append the keyword
last
to append the file information instead of prefixing it.
Log filters
The default behavior is to filter out everything, i.e. not to log anything. The reason is quite simple: On a busy production setup, logging all events for a given subsystem may very quickly be flooding your console before you have a chance to set a more restrictive filter.
To request no filtering, i.e. see all messages, you may use:
log filter all 1
In addition to generic filtering, applications can implement special log filters using the same framework to filter on particular context.
For example in OsmoBSC, to only see messages relating to a particular
subscriber identified by his IMSI, you may use:
log filter imsi 262020123456789
Log targets
Each of the log targets represent certain destination for log messages.
It can be configured independently by selecting levels (see [log_levels]) for categories
(see [log_categories]) as well as filtering (see [log_filters]) and
other options like logging timestamp
for example.
Logging to the VTY
Logging messages to the interactive command-line interface (VTY) is most useful for occasional investigation by the system administrator.
Logging to the VTY is disabled by default, and needs to be enabled explicitly for each such session. This means that multiple concurrent VTY sessions each have their own logging configuration. Once you close a VTY session, the log target will be destroyed and your log settings be lost. If you re-connect to the VTY, you have to again activate and configure logging, if you wish.
To create a logging target bound to a VTY, you have to use the following
command: logging enable
This doesn’t really activate the
generation of any output messages yet, it merely creates and attaches a
log target to the VTY session. The newly-created target still doesn’t
have any filter installed, i.e. all log messages will be suppressed
by default
Next, you can configure the log levels for desired categories in your VTY session. See [log_categories] for more details on categories and [log_levels] for the log level details.
For example, to set the log level of the Call Control category to debug, you
can use:
log level cc debug
Finally, after having configured the levels, you still need to set the filter as it’s described in [log_filters].
Tip
|
If many messages are being logged to a VTY session, it may be hard to impossible to still use the same session for any commands. We therefore recommend to open a second VTY session in parallel, and use one only for logging, while the other is used for interacting with the system. Another option would be to use different log target. |
To review the current vty logging configuration, you
can use:
show logging vty
Logging to the ring buffer
To avoid having separate VTY session just for logging output while still having immediate access to them,
one can use alarms
target. It lets you store the log messages inside the ring buffer of a given size which
is available with show alarms
command.
It’s configured as follows:
OsmoBSC> enable
OsmoBSC# configure terminal
OsmoBSC(config)# log alarms 98
OsmoBSC(config-log)#
In the example above 98 is the desired size of the ring buffer (number of messages). Once it’s filled, the incoming log messages will push out the oldest messages available in the buffer.
Logging via gsmtap
GSMTAP is normally a pseudo-header format that enables the IP-transport of GSM (or other telecom) protocols that are not normally transported over IP. For example, the most common situation is to enable GSMTAP in OsmoBTS or OsmoPCU to provide GSM-Um air interface capture files over IP, so they can be analyzed in wireshark.
GSMTAP logging is now a method how Osmocom software can also encapsulate its own log output in GSMTAP frames. We’re not trying to re-invent rsyslog here, but this is very handy When debugging complex issues. It enables the reader of the pcap file containing GSMTAP logging together with other protocol traces to reconstruct exact chain of events. A single pcap file can then contain both the log output of any number of Osmocom programs in the same timeline of the messages on various interfaces in and out of said Osmocom programs.
It’s configured as follows:
OsmoBSC> enable
OsmoBSC# configure terminal
OsmoBSC(config)# log gsmtap 192.168.2.3
OsmoBSC(config-log)#
The hostname/ip argument is optional: if omitted the default 127.0.0.1 will be used. The log strings inside GSMTAP are already
supported by Wireshark. Capturing for port 4729
on appropriate interface will reveal log messages including source file
name and line number as well as application. This makes it easy to consolidate logs from several different network components
alongside the air frames. You can also use Wireshark to quickly filter logs for a given subsystem, severity, file name etc.
![./common/images/wireshark-gsmtap-log.png](./common/images/wireshark-gsmtap-log.png)
Note: the logs are also duplicated to stderr when GSMTAP logging is configured because stderr is the default log target which is initialized automatically. To descrease stderr logging to absolute minimum, you can configure it as follows:
OsmoBSC> enable
OsmoBSC# configure terminal
OsmoBSC(config)# log stderr
OsmoBSC(config-log)# logging level force-all fatal
Note
|
Every time you generate GSMTAP messages and send it to a unicast (non-broadcast/multicast) IP address,
please make sure that the destination IP address actually has a socket open on the specified port, or drops
the packets in its packet filter. If unicast GSMTAP messages arrive at a closed destination UDP port, the
operating system will likely generate ICMP port unreachable messages. Those ICMP messages in turn will, when
arriving at the source (the host on which you run the Osmocom software sending GSMTAP), suppress generation
of further GSMTAP messages for some time, resulting in incomplete files. In case of doubt, either send GSMTAP
to multicast IP addresses, or run something like nc -l -u -p 4729 > /dev/null on the destination host to
open the socket at the GSMTAP port and discard anything arriving at it. |
Logging to a file
As opposed to Logging to the VTY, logging to files is persistent and stored in the configuration file. As such, it is configured in sub-nodes below the configuration node. There can be any number of log files active, each of them having different settings regarding levels / subsystems.
To configure a new log file, enter the following sequence of commands:
OsmoBSC> enable
OsmoBSC# configure terminal
OsmoBSC(config)# log file /path/to/my/file
OsmoBSC(config-log)#
This leaves you at the config-log prompt, from where you can set the
detailed configuration for this log file. The available commands at
this point are identical to configuring logging on the VTY, they include
logging filter
, logging level
as well as logging color
and logging timestamp
.
Tip
|
Don’t forget to use the copy running-config startup-config (or
its short-hand write file ) command to make your logging configuration
persistent across application re-start. |
Note
|
libosmocore provides file close-and-reopen support by SIGHUP, as used by popular log file rotating solutions such as https://github.com/logrotate/logrotate found in most GNU/Linux distributions. |
Logging to syslog
syslog is a standard for computer data logging maintained by the IETF. Unix-like operating systems like GNU/Linux provide several syslog compatible log daemons that receive log messages generated by application programs.
libosmocore based applications can log messages to syslog by using the syslog log target. You can configure syslog logging by issuing the following commands on the VTY:
OsmoBSC> enable
OsmoBSC# configure terminal
OsmoBSC(config)# log syslog daemon
OsmoBSC(config-log)#
This leaves you at the config-log prompt, from where you can set the
detailed configuration for this log file. The available commands at
this point are identical to configuring logging on the VTY, they include
logging filter
, logging level
as well as logging color
and logging timestamp
.
Note
|
Syslog daemons will normally automatically prefix every message
with a time-stamp, so you should disable the libosmocore time-stamping
by issuing the logging timestamp 0 command. |
Logging to systemd-journal
systemd has been adopted by the majority of modern GNU/Linux distributions. Along with various daemons and utilities it provides systemd-journald [1] - a daemon responsible for event logging (syslog replacement). libosmocore based applications can log messages directly to systemd-journald.
The key difference from other logging targets is that systemd based logging allows to offload rendering of the meta information, such as location (file name, line number), subsystem, and logging level, to systemd-journald. Furthermore, systemd allows to attach arbitrary meta fields to the logging messages [2], which can be used for advanced log filtering.
[1] https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html [2] https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html
It was decided to introduce libsystemd as an optional dependency, so it needs to be enabled explicitly at configure/build time:
$ ./configure --enable-systemd-logging
Note
|
Recent libosmocore packages provided by Osmocom for Debian and CentOS are compiled with libsystemd (https://gerrit.osmocom.org/c/libosmocore/+/22651). |
You can configure systemd based logging in two ways:
systemd-journal
target with offloaded renderinglog systemd-journal raw <1>
logging filter all 1
logging level set-all notice
-
raw
logging handler, rendering offloaded to systemd.
In this example, logging messages will be passed to systemd without any meta
information (time, location, level, category) in the text itself, so all
the printing parameters like logging print file
will be ignored. Instead,
the meta information is passed separately as fields which can be retrieved
from the journal and rendered in any preferred way.
# Show Osmocom specific fields
$ journalctl --fields | grep OSMO
# Filter messages by logging subsystem at run-time
$ journalctl OSMO_SUBSYS=DMSC -f
# Render specific fields only
$ journalctl --output=verbose \
--output-fields=SYSLOG_IDENTIFIER,OSMO_SUBSYS,CODE_FILE,CODE_LINE,MESSAGE
See man 7 systemd.journal-fields
for a list of default fields, and
man 1 journalctl
for general information and available formatters.
systemd-journal
target with libosmocore based renderinglog systemd-journal <1>
logging filter all 1
logging print file basename
logging print category-hex 0
logging print category 1
logging print level 1
logging timestamp 0 <2>
logging color 1 <3>
logging level set-all notice
-
Generic logging handler, rendering is done by libosmocore.
-
Disable timestamping, systemd will timestamp every message anyway.
-
Colored messages can be rendered with
journalctl --output=cat
.
In this example, logging messages will be pre-processed by libosmocore before
being passed to systemd. No additional fields will be attached, except the
logging level (PRIORITY
). This mode is similar to syslog and stderr.
Logging to stderr
If you’re not running the respective application as a daemon in the background, you can also use the stderr log target in order to log to the standard error file descriptor of the process.
In order to configure logging to stderr, you can use the following commands:
OsmoBSC> enable
OsmoBSC# configure terminal
OsmoBSC(config)# log stderr
OsmoBSC(config-log)#
Osmocom Counters
The following gives an overview of all the types of counters available:
Osmo Counters (deprecated)
Osmo counters are the oldest type of counters added to Osmocom projects. They are not grouped.
-
Printed as part of VTY show stats
-
Increment, Decrement
-
Accessible through the control interface: counter.<counter_name>
Rate Counters
Rate counters count rates of events.
-
Printed as part of VTY show stats
-
Intervals: per second, minute, hour, day or absolute value
-
Increment only
-
Accessible through the control interface
-
Rate counters are grouped and different instances per group can exist
The control interface command to get a counter (group) is:
rate_ctr.per_{sec,min,hour,day,abs}.<group_name>.<idx>.[counter_name]
It is possible to get all counters in a group by omitting the counter name
Stat Item
Stat items are a grouped replacement for osmo counters.
-
Printed as part of VTY show stats
-
Replacement for osmo counters
-
Not yet available through the control interface
-
Grouped and indexed like rate counters
-
Items have a unit
-
Keeps a list of the last values measured, so could return an average, min, max, std. deviation. So far this is not implemented in any of the reporting options.
Statistic Levels
There are three levels on which a statistic can be aggregated in Osmocom projects: globally, per-peer and per-subscriber.
Global
These are global statistics.
Peer
These statistics relate to a peer the program connects to such as the NSVC in an SGSN.
This level also includes reporting global statistics.
Subscriber
These statistics are related to an individual mobile subscriber. An example would be bytes transferred in an SGSN PDP context.
This level also includes global and peer-based statistics.
Stats Reporter
The stats reporter periodically collects osmo counter, rate counter and stat item values and sends them to a backend. Currently implemented are outputting to the configured log targets and a statsd connector.
Configuring a stats reporter
Periodically printing the statistics to the log can be done in the following way:
OsmoBSC> enable
OsmoBSC# configure terminal
OsmoBSC(config)# stats interval 60 <1>
OsmoBSC(config)# stats reporter log <2>
OsmoBSC(config-stats)# level global <3>
OsmoBSC(config-stats)# enable <4>
-
The interval determines how often the statistics are reported.
-
Write the statistic information to any configured log target.
-
Report only
global
statistics (can beglobal
,peer
, orsubscriber
). -
Enable the reporter,
disable
will disable it again.
The counter values can also be sent to any aggregation/visualization tool that understands the statsd format, for example a statsd server with graphite or prometheus using the statsd_exporter together with grafana.
The statsd format is specified in https://github.com/b/statsd_spec
OsmoBSC> enable
OsmoBSC# configure terminal
OsmoBSC(config)# stats interval 10
OsmoBSC(config)# stats reporter statsd <1>
OsmoBSC(config-stats)# prefix BSC1 <2>
OsmoBSC(config-stats)# level subscriber <3>
OsmoBSC(config-stats)# remote-ip 1.2.3.4 <4>
OsmoBSC(config-stats)# remote-port 8125 <5>
OsmoBSC(config-stats)# enable
-
Configure the statsd reporter.
-
Prefix the reported statistics. This is useful to distinguish statistics from multiple instances of the same service.
-
Report only
global
statistics or includepeer
orsubscriber
statistics as well. -
IP address of the statsd server.
-
UDP port of the statsd server. Statsd by default listens to port 8125.
You can use Netdata (https://learn.netdata.cloud/) as a statsd server which does not require special configuration to show rate counters. By default all the rate counters will be exposed to the StatsD plugin (listening on 127.0.0.1:8125) and displayed on the Netdata dashboard available via: http://localhost:19999 The list of available charts which includes all the rate counters reported via statsD is available through: http://localhost:19999/api/v1/charts
Socket stats
libosmocore provides features to monitor the status of TCP connections. This can be a helpful source of information when the links between network components are unreliable (e.g. satellite link between BTS and BSC).
Note
|
This feature is only available for certain types of TCP connections. At the moment only RSL/OML connections between OsmoBSC and the connected BTSs can be monitored. |
Configuration
The gathering of the TCP connection statistics is done via syscalls. This has to be taken into account for the configuration. Since syscalls are rather expensive and time consuming the overall performance of the application may suffer when many TCP connections are present. This may be the case for BSCs with a large number of BTSs connected to it.
The statistics are gathered in batches per interval. A batch size of 5 would mean that only 5 TCP connections per interval are evaluated and the next 5 connections in the next interval and so on.
It is recommended to choose a large reporting interval and a reasonable small batch size to distribute the syscall load as even as possible.
OsmoBSC> enable
OsmoBSC# configure terminal
stats-tcp interval 10 <1>
stats-tcp batch-size 5 <2>
-
Set the gathering interval (sec.)
-
Set how many TCP sockets statistics to gather per interval.
Generated stats items
Name | Description |
---|---|
tcp:unacked |
unacknowledged packets. |
tcp:lost |
unacknowledged packets. |
tcp:retrans |
lost packets. |
tcp:rtt |
retransmitted packets. |
tcp:rcv_rtt |
roundtrip-time (receive). |
tcp:notsent_bytes |
bytes not yet sent. |
tcp:rwnd_limited |
time (usec) limited by receive window. |
tcp:sndbuf_limited |
Time (usec) limited by send buffer. |
tcp:reord_seen |
reordering events seen. |
The item group index is the file descriptor number. The item group name consists of a static prefix (e.g. "ipa-rsl"), followed by the IP addresses and ports of both peers.
stats tcp (15)('ipa-rsl,r=10.9.1.143:38455<->l=10.9.1.162:3003'):
unacknowledged packets: 0
lost packets: 0
retransmitted packets: 0
roundtrip-time: 583
roundtrip-time (receive): 0
bytes not yet sent: 0
time (usec) limited by receive window: 0
Time (usec) limited by send buffer: 0
reordering events seen: 0
Implemented Counters
These counters and their description based on OpenBSC 1.3.0 (OpenBSC).
Rate Counters
Name | Reference | Description |
---|---|---|
hdlc:abort |
HDLC abort |
|
hdlc:bad_fcs |
HLDC Bad FCS |
|
hdlc:overrun |
HDLC Overrun |
|
alarm |
Alarm |
|
removed |
Line removed |
Name | Reference | Description |
---|---|---|
chreq:total |
Received channel requests. |
|
chreq:no_channel |
Sent to MS no channel available. |
|
handover:attempted |
Received handover attempts. |
|
handover:no_channel |
Sent no channel available responses. |
|
handover:timeout |
Count the amount of timeouts of timer T3103. |
|
handover:completed |
Received handover completed. |
|
handover:failed |
Receive HO FAIL messages. |
|
paging:attempted |
Paging attempts for a MS. |
|
paging:detached |
Counts the amount of paging attempts which couldn’t sent out any paging request because no responsible bts found. |
|
paging:completed |
Paging successful completed. |
|
paging:expired |
Paging Request expired because of timeout T3113. |
|
chan:rf_fail |
Received a RF failure indication from BTS. |
|
chan:rll_err |
Received a RLL failure with T200 cause from BTS. |
|
bts:oml_fail |
Received a TEI down on a OML link. |
|
bts:rsl_fail |
Received a TEI down on a OML link. |
|
bts:codec_amr_f |
Count the usage of AMR/F codec by channel mode requested. |
|
bts:codec_amr_h |
Count the usage of AMR/H codec by channel mode requested. |
|
bts:codec_efr |
Count the usage of EFR codec by channel mode requested. |
|
bts:codec_fr |
Count the usage of FR codec by channel mode requested. |
|
bts:codec_hr |
Count the usage of HR codec by channel mode requested. |
Name | Reference | Description |
---|---|---|
loc_update_type:attach |
Received location update imsi attach requests. |
|
loc_update_type:normal |
Received location update normal requests. |
|
loc_update_type:periodic |
Received location update periodic requests. |
|
loc_update_type:detach |
Received location update detach indication. |
|
loc_update_resp:failed |
Rejected location updates. |
|
loc_update_resp:completed |
Successful location updates. |
|
sms:submitted |
Received a RPDU from a MS (MO). |
|
sms:no_receiver |
Counts SMS which couldn’t routed because no receiver found. |
|
sms:delivered |
Global SMS Deliver attempts. |
|
sms:rp_err_mem |
CAUSE_MT_MEM_EXCEEDED errors of MS responses on a sms deliver attempt. |
|
sms:rp_err_other |
Other error of MS responses on a sms delive attempt. |
|
sms:deliver_unknown_error |
Unknown error occured during sms delivery. |
|
call:mo_setup |
Received setup requests from a MS to init a MO call. |
|
call:mo_connect_ack |
Received a connect ack from MS of a MO call. Call is now succesful connected up. |
|
call:mt_setup |
Sent setup requests to the MS (MT). |
|
call:mt_connect |
Sent a connect to the MS (MT). |
|
call:active |
Count total amount of calls that ever reached active state. |
|
call:complete |
Count total amount of calls which got terminated by disconnect req or ind after reaching active state. |
|
call:incomplete |
Count total amount of call which got terminated by any other reason after reaching active state. |
Osmo Stat Items
base transceiver station .bts - base transceiver station
Name | Reference | Description | Unit |
---|---|---|---|
chanloadavg |
Channel load average. |
% |
|
T3122 |
T3122 IMMEDIATE ASSIGNMENT REJECT wait indicator. |
s |
Osmo Counters
Name | Reference | Description |
---|---|---|
msc.active_calls |
OsmoNITB Core Network Subsystem
The OsmoNITB Core Network is a minimalistic implementation of the classic MSC/VLR/HLR/AUC/SMSC components. None of the standardized core network protocols (such as SCCP/TCAP/MAP) are used, interfaces between VLR and HLR are simple function calls inside the same software package.
OsmoNITB can thus provide autonomous voice and SMS services to its coverage area, but it cannot provide roaming interfaces to classic GSM operators. To support this configuration, it is suggested to use the OsmoBSC variant of OpenBSC and interface it with a conventional MSC using A-over-IP protocol.
If you have classic GSM network/operator background, many of the concepts used in OsmoNITB will appear foreign to you, as they are very unlike the conventional GSM networks that you have worked with.
Configuring the Core Network
Like everything else, the core network related parameters are configured
using the VTY. The respective parameters are underneath the
network
config node.
You can get to that node by issuing the following commands:
OpenBSC> enable
OpenBSC# configure terminal
OpenBSC(config)# network
OpenBSC(config-net)#
A full reference to them can be found in the OsmoNITB VTY reference manual [vty-ref-osmonitb]. This section will only introduce the most commonly used settings in detail.
Tip
|
You can always use the |
Configuring the MCC/MNC
The key identities of every GSM PLMN is the MCC and MNC. They are identical over the entire network. In most cases, the MCC/MNC will be allocated to the operator by the respective local regulatory authority. For example, to set the MCC/MNC of 262-89, you may enter:
OpenBSC(config-net)# network country code 262
OpenBSC(config-net)# mobile network code 89
Configuring MM INFO
The MM INFO procedure can be used after a successful LOCATION UPDATE in order to transmit the human-readable network name as well as local time zone information to the MS.
By default, MM INFO is not active. You can activate it, and set its configuration using the VTY. An example is provided below.
OpenBSC(config-net)# mm info 1
OpenBSC(config-net)# short name OpenBSC
OpenBSC(config-net)# long name OpenBSC
Note
|
Not all phone support the MM INFO procedure. Unless they already are factory-programmed to contain the name for your MCC/MNC, then they will likely only provide a numeric display of the network name, such as 262-89 or with the country code transformed into a letter, such as D 89. |
The time information transmitted is determined by the local system time
of the operating system on which OsmoNITB is running. As BTSs attached
to one OsmoNITB can reside in different time zones, it is possible to
use the timezone
command at each BTS node to set different time
zone offsets in hours and quarter hours.
Setting the NECI bit
NECI (New Establishment Cause Indication) is an optional change of the definition for establishment cause in the RACH burst. Among other things, in a network with NECI, a MS can explicitly indicate its TCH/H capability while asking for a dedicated radio channel.
It is strongly recommended to use NECI. You can do so by issuing the following command: .Enabling NECI
OpenBSC(config-net)# neci 1
Configuring Handover
As opposed to cell re-selection in idle mode, handover refers to the explicit transfer of a MS dedicated channel from one radio channel to another. This typically happens due to a MS moving from one cell to another while in an active call.
OsmoNITB has a number of hand-over related parameters by which the hand-over algorithm can be tuned. Logically, those settings are settings of the BSC component, but for historic reasons, they are also configured under the network VTY node.
OpenBSC(config-net)# handover 1
OpenBSC(config-net)# handover window rxlev averaging 10
OpenBSC(config-net)# handover window rxqual averaging 1
OpenBSC(config-net)# handover window rxlev neighbor averaging 10
OpenBSC(config-net)# handover power budget interval 6
OpenBSC(config-net)# handover power budget hysteresis 3
OpenBSC(config-net)# handover maximum distance 9999
Note
|
If you are receiving the following error message:
then you should do as indicated and make sure to start your |
BSC level configuration
The BSC component is shared between OsmoBSC and OsmoNITB. This chapter describes some of the configuration options related to this shared BSC component.
Hand-over
Hand-over in GSM
Hand-over is the process of changing a MS with a currently active dedicated channel from one BTS to another BTS. As opposed to idle mode, where the MS autonomously performs cell re-selection, in dedicated mode this happens under network control.
In order to determine when to perform hand-over, and to which cells, the network requests the MS to perform measurements on a list of neighbor cell channels, which the MS then reports back to the network in the form of GSM RR Measurement Result messages. Those messages contain the downlink measurements as determined by the MS.
Furthermore, the BTS also performs measurements on the uplink, and communicates those by means of RSL to the BSC.
The hand-over decision is made by an algorithm that processes those measurement results and determines when to perform the hand-over.
Configuration of hand-over in OsmoBSC/OsmoNITB
OsmoBSC (like the internal BSC component of OsmoNITB) only support so-called intra-BSC hand-over, where the hand-over is performed between two BTSs within the same BSC.
Hand-over is enabled and configured by the use of a set of handover
commands. Using those, you can tune the key parameters of the hand-over
algorithm and adapt it to your specific environment.
handover 1 <1>
handover window rxlev averaging 10 <2>
handover window rxqual averaging 1 <3>
handover window rxlev neighbor averaging 10 <4>
handover power budget interval 6 <5>
handover power budget hysteresis 3 <6>
handover maximum distance 9999 <7>
-
Enable hand-over
-
Set the RxLev averaging window for the serving cell to 10 measurements
-
Set the RxQual averaging window for the serving cell to 1 measurement (no window)
-
Set the RxLev averaging for neighbor cells to 10 measurements
-
Check for the conditions of a power budget hand-over every 6 SACCH frames
-
A neighbor cell must be at least 3 dB stronger than the serving cell to be considered a candidate for hand-over
-
Perform a maximum distance hand-over if TA is larger 9999 (i.e. never)
Timer Configuration
The GSM specification specifies a variety of timers both on the network as well as on the mobile station side.
Those timers can be configured using the timer tXXXX
command.
node |
timer |
default |
description |
network |
t3101 |
10 |
Timeout for Immediate Assignment (sec) |
network |
t3103 |
? |
Timeout for Handover (sec) |
network |
t3105 |
40 |
Repetition of Physical Information (sec) |
network |
t3107 |
? |
? |
network |
t3109 |
? |
RSL SACCH deactivation timeout (sec) |
network |
t3111 |
? |
RSL timeout to wait before releasing the RF channel (sec) |
network |
t3113 |
60 |
Time to try paging for a subscriber (sec) |
network |
t3115 |
? |
? |
network |
t3117 |
? |
? |
network |
t3119 |
? |
? |
network |
t3122 |
10 |
Waiting time after Immediate Assignment Reject |
network |
t3141 |
? |
? |
Discontinuous Transmission (DTX)
GSM provides a full-duplex voice call service. However, in any civilized communication between human beings, only one of the participants is speaking at any given point in time. This means that most of the time, one of the two directions of the radio link is transmitting so-called silence frames.
During such periods of quiescence in one of the two directions, it is possible to suppress transmission of most of the radio bursts, as there is no voice signal to transport. GSM calls this feature Discontinuous Transmission. It exists separately for uplink (DTXu) and downlink (DTXd).
Downlink DTX is only permitted on non-primary transceivers (!= TRX0), as TRX0 must always transmit at constant output power to ensure it is detected during cell selection.
Uplink DTX is possible on any TRX, and serves primarily two uses:
possible on any TRX, and serves primarily two uses:
-
reducing the MS battery consumption by transmitting at a lower duty cycle
-
reducing the uplink interference caused in surrounding cells that re-use the same ARFCN.
DTS for both uplink and downlink is implemented in the BTS. Not all BTS models support it.
The Osmocom BSC component can instruct the BTS to enable or disable uplink and/or downlink DTX by means of A-bis OML.
Reviewing and Provisioning BTS configuration
The main functionality of the BSC component is to manage BTSs. As such, provisioning BTSs within the BSC is one of the most common tasks during BSC operation. Just like about anything else in OsmoBSC, they are configured using the VTY.
BTSs are internally numbered with integer numbers starting from "0" for the first BTS. BTS numbers have to be contiguous, so you cannot configure 0,1,2 and then 5.
Reviewing current BTS status and configuration
In order to view the status and properties of a BTS, you can issue the
show bts
command. If used without any BTS number, it will display
information about all provisioned BTS numbers.
OsmoBSC> show bts 0
BTS 0 is of nanobts type in band DCS1800, has CI 0 LAC 1, BSIC 63, TSC 7 and 1 TRX
Description: (null)
MS Max power: 15 dBm
Minimum Rx Level for Access: -110 dBm
Cell Reselection Hysteresis: 4 dBm
RACH TX-Integer: 9
RACH Max transmissions: 7
System Information present: 0x0000007e, static: 0x00000000
Unit ID: 200/0/0, OML Stream ID 0xff
NM State: Oper 'Enabled', Admin 2, Avail 'OK'
Site Mgr NM State: Oper 'Enabled', Admin 0, Avail 'OK'
Paging: 0 pending requests, 0 free slots
OML Link state: connected.
Current Channel Load:
TCH/F: 0% (0/5)
SDCCH8: 0% (0/8)
You can also review the status of the TRXs configured within the BTSs of
this BSC by using show trx
:
OsmoBSC> show trx 0 0
TRX 0 of BTS 0 is on ARFCN 871
Description: (null)
RF Nominal Power: 23 dBm, reduced by 0 dB, resulting BS power: 23 dBm
NM State: Oper 'Enabled', Admin 2, Avail 'OK'
Baseband Transceiver NM State: Oper 'Enabled', Admin 2, Avail 'OK'
ip.access stream ID: 0x00
The output can be restricted to the TRXs of one specified BTS number
(show trx 0
) or even that of a single specified TRX within a
specified BTS (show trx 0 0
).
Furthermore, information on the individual timeslots can be shown by
means of show timeslot
. The output can be restricted to the
timeslots of a single BTS (show timeslot 0
) or that of a single
TRX (show timeslot 0 0
). Finally, you can restrict the output to
a single timeslot by specifying the BTS, TRX and TS numbers (show
timeslot 0 0 4
).
OsmoBSC> show timeslot 0 0 0
BTS 0, TRX 0, Timeslot 0, phys cfg CCCH, TSC 7
NM State: Oper 'Enabled', Admin 2, Avail 'OK'
OsmoBSC> show timeslot 0 0 1
BTS 0, TRX 0, Timeslot 1, phys cfg SDCCH8, TSC 7
NM State: Oper 'Enabled', Admin 2, Avail 'OK'
Provisioning a new BTS
In order to provision BTSs, you have to enter the BTS config node of the VTY. In order to configure BTS 0, you can issue the following sequence of commands:
OsmoBSC> enable
OsmoBSC# configure terminal
OsmoBSC(config)# network
OsmoBSC(config-net)# bts 0
OsmoBSC(config-net-bts)#
At this point, you have a plethora of commands, in fact an entire hierarchy of commands to configure all aspects of the BTS, as well as each of its TRX and each timeslot within each TRX. For a full reference, please consult the telnet VTY integrated help or the respective chapter in the VTY reference.
BTS configuration depends quite a bit on the specific BTS vendor and model. The section below provides just one possible example for the case of a sysmoBTS.
Note that from the configure terminal
command onwards, the telnet VTY
commands above are identical to configuration file settings, for details see
[vty].
Starting with network
as above, your complete sysmoBTS configuration may look
like this:
network
bts 0
type sysmobts
band DCS1800
description The new BTS in Baikonur
location_area_code 2342
cell_identity 5
base_station_id_code 63
ip.access unit_id 8888 0
ms max power 40
trx 0
arfcn 871
nominal power 23
max_power_red 0
timeslot 0
phys_chan_config CCCH+SDCCH4
timeslot 1
phys_chan_config TCH/F
timeslot 2
phys_chan_config TCH/F
timeslot 3
phys_chan_config TCH/F
timeslot 4
phys_chan_config TCH/F
timeslot 5
phys_chan_config TCH/F
timeslot 6
phys_chan_config TCH/F
timeslot 7
phys_chan_config PDCH
System Information configuration
A GSM BTS periodically transmits a series of SYSTEM INFORMATION messages to mobile stations, both via the BCCH in idle mode, was well as via the SACCH in dedicated mode. There are many different types of such messages. For their detailed contents and encoding, please see 3GPP TS 24.008 [3gpp-ts-24-008].
For each of the SYSTEM INFORMATION message types, you can configure to have the BSC generate it automatically (computed), or you can specify the respective binary message as a string of hexadecimal digits.
The default configuration is to compute all (required) SYSTEM INFORMATION messages automatically.
Please see the OsmoBSC VTY Reference Manual [vty-ref-osmobsc] for further information, particularly on the following commands:
-
system-information (1|2|3|4|5|6|7|8|9|10|13|16|17|18|19|20|2bis|2ter|2quater|5bis|5ter) mode (static|computed)
-
system-information (1|2|3|4|5|6|7|8|9|10|13|16|17|18|19|20|2bis|2ter|2quater|5bis|5ter) static HEXSTRING
Neighbor List configuration
Every BTS sends a list of ARFCNs of neighbor cells . within its SYSTEM INFORMATION 2 (and 2bis/2ter) messages on the BCCH . within its SYSTEM INFORMATION 5 messages on SACCH in dedicated mode
For every BTS config node in the VTY, you can specify the behavior of
the neighbor list using the neighbor list mode
VTY command:
- automatic
-
Automatically generate a list of neighbor cells using all other BTSs configured in the VTY
- manual
-
Manually specify the neighbor list by means of
neighbor-list (add|del) arfcn <0-1023>
commands, having identical neighbor lists on BCCH (SI2) and SACCH (SI5) - manual-si5
-
Manually specify the neighbor list by means of
neighbor-list (add|del) arfcn <0-1023>
for BCCH (SI2) and a separate neighbor list by means ofsi5 neighbor-list (add|del) arfcn <0-1023>
for SACCH (SI5).
Configuring GPRS PCU parameters of a BTS
In the case of BTS models using Abis/IP (IPA), the GPRS PCU is located inside the BTS. The BTS then establishes a Gb connection to the SGSN.
All the BTS-internal PCU configuration is performed via A-bis OML by means of configuring the CELL, NSVC (NS Virtual Connection and NSE (NS Entity).
There is one CELL node and one NSE node, but there are two NSVC nodes. At the time of this writing, only the NSVC 0 is supported by OsmoBTS, while both NSVC are supported by the ip.access nanoBTS.
The respective VTY configuration parameters are described below. They all exist beneath each BTS VTY config node.
But let’s first start with a small example
OsmoBSC(config-net-bts)# gprs mode gprs
OsmoBSC(config-net-bts)# gprs routing area 1
OsmoBSC(config-net-bts)# gprs cell bvci 1234
OsmoBSC(config-net-bts)# gprs nsei 1234
OsmoBSC(config-net-bts)# gprs nsvc 0 nsvci 1234
OsmoBSC(config-net-bts)# gprs nsvc 0 local udp port 23000
OsmoBSC(config-net-bts)# gprs nsvc 0 remote udp port 23000
OsmoBSC(config-net-bts)# gprs nsvc 0 remote ip 192.168.100.239
More explanation about the PCU config parameters
gprs mode (none|gprs|egprs)
This command determines if GPRS (or EGPRS) services are to be enabled in this cell at all.
gprs cell bvci <2-65535>
Configures the BSSGP Virtual Circuit Identifier. It must be unique between all BGSGP connections to one SGSN.
Note
|
It is up to the system administrator to ensure all PCUs are allocated an unique bvci. OsmoBSC will not ensure this policy. |
gprs nsei <0-65535>
Configures the NS Entity Identifier. It must be unique between all NS connections to one SGSN.
Note
|
It is up to the system administrator to ensure all PCUs are allocated an unique bvci. OsmoBSC will not ensure this policy. |
gprs nsvc <0-1> nsvci <0-65535>
Configures the NS Virtual Connection Identifier. It must be unique between all NS virtual connections to one SGSN.
Note
|
It is up to the system administrator to ensure all PCUs are allocated an unique nsvci. OsmoBSC will not ensure this policy. |
gprs nsvc <0-1> local udp port <0-65535>
Configures the local (PCU side) UDP port for the NS-over-UDP link.
gprs nsvc <0-1> remote udp port <0-65535>
Configures the remote (SGSN side) UDP port for the NS-over-UDP link.
gprs nsvc <0-1> remote ip A.B.C.D
Configures the remote (SGSN side) UDP port for the NS-over-UDP link.
gprs ns timer (tns-block|tns-block-retries|tns-reset|tns-reset-retries|tns-test|tns-alive|tns-alive-retries)
<0-255>
Configures the various GPRS NS related timers. Please check the GPRS NS specification for the detailed meaning of those timers.
Dynamic Timeslot Configuration (TCH / PDCH)
A dynamic timeslot is in principle a voice timeslot (TCH) that is used to serve GPRS data (PDCH) when no voice call is active on it. This enhances GPRS bandwidth while no voice calls are active, which is dynamically scaled down as voice calls need to be served. This is a tremendous improvement in service over statically assigning a fixed number of timeslots for voice and data.
The causality is as follows: to establish a voice call, the MSC requests a logical channel of a given TCH kind from the BSC. The BSC assigns such a channel from a BTS' TRX’s timeslot of its choice. The knowledge that a given timeslot is dynamic exists only on the BSC level. When the MSC asks for a logical channel, the BSC may switch off PDCH on a dynamic timeslot and then assign a logical TCH channel on it. Hence, though compatibility with the BTS needs to be ensured, any MSC is compatible with dynamic timeslots by definition.
OsmoBSC support two kinds of dynamic timeslot handling, configured
via the network
/ bts
/ trx
/ timeslot
/ phys_chan_config
configuration. Not all BTS models support dynamic channels.
|
|
|
ip.access nanoBTS |
- |
supported |
Ericsson RBS |
supported |
- |
sysmoBTS using osmo-bts-sysmo |
supported |
supported |
various SDR platforms using osmo-bts-trx |
supported |
supported |
Nutaq Litecell 1.5 using osmo-bts-litecell15 |
supported |
supported |
Octasic OctBTS using osmo-bts-octphy |
supported |
supported |
The OsmoBTS Abis Protocol Specification [osmobts-abis-spec] describes the non-standard RSL messages used for these timeslot kinds.
Note
|
Same as for dedicated PDCH timeslots, you need to enable GPRS and operate a PCU, SGSN and GGSN to provide the actual data service. |
Osmocom Style Dynamic Timeslots (TCH/F_TCH/H_PDCH)
Timeslots of the TCH/F_TCH/H_PDCH
type dynamically switch between TCH/F,
TCH/H and PDCH, depending on the channel kind requested by the MSC. The RSL
messaging for TCH/F_TCH/H_PDCH
timeslots is compatible with Ericsson RBS.
BTS models supporting this timeslot kind are shown in [dyn_ts_compat].
ip.access Style Dynamic Timeslots (TCH/F_PDCH)
Timeslots of the TCH/F_PDCH
type dynamically switch between TCH/F and PDCH.
The RSL messaging for TCH/F_PDCH
timeslots is compatible with ip.access
nanoBTS.
BTS models supporting this timeslot kind are shown in [dyn_ts_compat].
Avoid PDCH Exhaustion
To avoid disrupting GPRS, configure at least one timeslot as dedicated PDCH. With only dynamic timeslots, a given number of voice calls would convert all timeslots to TCH, and no PDCH timeslots would be left for GPRS service.
Dynamic Timeslot Configuration Examples
This is an extract of an osmo-bsc`
config file. A timeslot configuration with
five Osmocom style dynamic timeslots and one dedicated PDCH may look like this:
network
bts 0
trx 0
timeslot 0
phys_chan_config CCCH+SDCCH4
timeslot 1
phys_chan_config SDCCH8
timeslot 2
phys_chan_config TCH/F_TCH/H_PDCH
timeslot 3
phys_chan_config TCH/F_TCH/H_PDCH
timeslot 4
phys_chan_config TCH/F_TCH/H_PDCH
timeslot 5
phys_chan_config TCH/F_TCH/H_PDCH
timeslot 6
phys_chan_config TCH/F_TCH/H_PDCH
timeslot 7
phys_chan_config PDCH
With the ip.access nanoBTS, only TCH/F_PDCH
dynamic timeslots are supported,
and hence a nanoBTS configuration may look like this:
network
bts 0
trx 0
timeslot 0
phys_chan_config CCCH+SDCCH4
timeslot 1
phys_chan_config SDCCH8
timeslot 2
phys_chan_config TCH/F_PDCH
timeslot 3
phys_chan_config TCH/F_PDCH
timeslot 4
phys_chan_config TCH/F_PDCH
timeslot 5
phys_chan_config TCH/F_PDCH
timeslot 6
phys_chan_config TCH/F_PDCH
timeslot 7
phys_chan_config PDCH
Tuning Access to the BTS
OsmoBSC offers several configuration options to fine-tune access to the BTS. It can allow only a portion of the subscribers access to the network. This can also be used to ramp up access to the network on startup by slowly letting in more and more subscribers. This is especially useful for isolated cells with a huge number of subscribers.
Other options control the behaviour of the MS when it needs to access the random access channel before a dedicated channel is established.
If the BTS is connected to the BSC via a high-latency connection the MS should wait longer for an answer to a RACH request. If it does not the network will have to deal with an increased load due to duplicate RACH requests. However, in order to minimize the delay when a RACH request or response gets lost the MS should not wait too long before retransmitting.
Load Management
Every SIM card is member of one of the ten regular ACCs (0-9). Access to the BTS can be restricted to SIMs that are members of certain ACCs.
Since the ACCs are distributed uniformly across all SIMs allowing only ACCs 0-4 to connect to the BTS should reduce its load by 50%.
The default is to allow all ACCs to connect.
network
bts 0
rach access-control-class 1 barred <1>
rach access-control-class 9 allowed <2>
-
Disallow SIMs with access-class 1 from connecting to the BTS
-
Permit SIMs with access-class 9 to connect to the BTS.
Smaller cells with lots of subscribers can be overwhelmed with traffic after the network is turned on. This is especially true in areas with little to no reception from other networks. To manage the load OsmoBSC has an option to enable one Access Class at a time so initial access to the network is distributed across a longer time.
network
bts 0
access-control-class-ramping <1>
access-control-class-ramping-step-interval 30 <2>
access-control-class-ramping-step-size 1 <3>
-
Turn on access-control-class ramping
-
Enable more ACCs every 30 seconds
-
At each step enable one more ACC
RACH Parameter Configuration
The following parameters allow control over how the MS can access the random access channel (RACH). It is possible to set a minimum receive level under which the MS will not even attempt to access the network.
The RACH is a shared channel which means multiple MS can choose to send a request at the same time. To minimize the risk of a collision each MS will choose a random number of RACH slots to wait before trying to send a RACH request.
On very busy networks the range this number is chosen from should be high to avoid collisions, but a lower range reduces the overall delay when trying to establish a channel.
The option rach tx integer N
controls the range from which this number X
is chosen. It is 0 <= X < max(8,N)
.
After sending a RACH request the MS will wait a random amount of slots before
retransmitting its RACH request. The range it will wait is also determined by
the option rach tx integer N
, but calculating it is not so straightforward.
It is defined as S <= X < S+N
where S
is determined from a table.
In particular S
is lowest when N
is one of 3, 8, 14 or 50 and highest when
N
is 7, 12 or 32.
For more information see 3GPP TA 44.018 [3gpp-ts-44-018] Ch. 3.3.1.1.2 and Table 3.3.1.1.2.1 in particular.
The amount of times the MS attempts to retransmit RACH requests can also be changed. A higher number means more load on the RACH while a lower number can cause channel establishment to fail due to collisions or bad reception.
network
bts 0
rxlev access min 20 <1>
rach tx integer 50<2>
rach max transmission <3>
-
Allow access to the network if the MS receives the BCCH of the cell at -90dBm or better (20dB above -110dBm).
-
This number affects how long the MS waits before (re-)transmitting RACH requests.
-
How often to retransmit the RACH request.
OsmoNITB example configuration files
The openbsc/doc/examples/osmo-nitb
directory in the OpenBSC source
tree contains a collection of example configuration files, sorted by BTS
type.
This chapter is illustrating some excerpts from those examples
Example configuration for OsmoNITB with one dual-TRX BS-11
e1_input
e1_line 0 driver misdn
network
network country code 1
mobile network code 1
short name OpenBSC
long name OpenBSC
timer t3101 10
timer t3113 60
bts 0
type bs11 <1>
band GSM900
cell_identity 1
location_area_code 1
training_sequence_code 7
base_station_id_code 63
oml e1 line 0 timeslot 1 sub-slot full <2>
oml e1 tei 25 <3>
trx 0
arfcn 121
max_power_red 0
rsl e1 line 0 timeslot 1 sub-slot full <4>
rsl e1 tei 1 <5>
timeslot 0
phys_chan_config CCCH+SDCCH4
e1 line 0 timeslot 1 sub-slot full
timeslot 1
phys_chan_config TCH/F
e1 line 0 timeslot 2 sub-slot 1 <6>
timeslot 2
phys_chan_config TCH/F
e1 line 0 timeslot 2 sub-slot 2
timeslot 3
phys_chan_config TCH/F
e1 line 0 timeslot 2 sub-slot 3
timeslot 4
phys_chan_config TCH/F
e1 line 0 timeslot 3 sub-slot 0
timeslot 5
phys_chan_config TCH/F
e1 line 0 timeslot 3 sub-slot 1
timeslot 6
phys_chan_config TCH/F
e1 line 0 timeslot 3 sub-slot 2
timeslot 7
phys_chan_config TCH/F
e1 line 0 timeslot 3 sub-slot 3
trx 1
arfcn 123
max_power_red 0
rsl e1 line 0 timeslot 1 sub-slot full <4>
rsl e1 tei 2 <5>
timeslot 0
phys_chan_config TCH/F
e1 line 0 timeslot 4 sub-slot 0 <6>
timeslot 1
phys_chan_config TCH/F
e1 line 0 timeslot 4 sub-slot 1
timeslot 2
phys_chan_config TCH/F
e1 line 0 timeslot 4 sub-slot 2
timeslot 3
phys_chan_config TCH/F
e1 line 0 timeslot 4 sub-slot 3
timeslot 4
phys_chan_config TCH/F
e1 line 0 timeslot 5 sub-slot 0
timeslot 5
phys_chan_config TCH/F
e1 line 0 timeslot 5 sub-slot 1
timeslot 6
phys_chan_config TCH/F
e1 line 0 timeslot 5 sub-slot 2
timeslot 7
phys_chan_config TCH/F
e1 line 0 timeslot 5 sub-slot 3
-
The BTS type must be set to bs11
-
The OML E1 timeslot needs to be identical with what was on the BTS side using LMT.
-
The OML TEI value needs to be identical with what was configured on the BTS side using LMT.
-
The RSL E1 timeslot can be identical for all TRX.
-
The RSL TEI values must be different if multiple TRX share one E1 signalling timeslot.
-
The TCH all need to be allocated one 16k sub-slot on the E1
Example configuration for OsmoNITB with one single-TRX nanoBTS
e1_input
e1_line 0 driver ipa <1>
network
network country code 1
mobile network code 1
short name OpenBSC
long name OpenBSC
auth policy closed
location updating reject cause 13
encryption a5 0
neci 1
rrlp mode none
mm info 1
handover 0
bts 0
type nanobts <2>
band DCS1800 <3>
cell_identity 0
location_area_code 1
training_sequence_code 7
base_station_id_code 63
ms max power 15
cell reselection hysteresis 4
rxlev access min 0
channel allocator ascending
rach tx integer 9
rach max transmission 7
ip.access unit_id 1801 0 <4>
oml ip.access stream_id 255 line 0
gprs mode none
trx 0
rf_locked 0
arfcn 871 <5>
nominal power 23
max_power_red 20 <6>
rsl e1 tei 0
timeslot 0
phys_chan_config CCCH+SDCCH4
timeslot 1
phys_chan_config SDCCH8
timeslot 2
phys_chan_config TCH/F
timeslot 3
phys_chan_config TCH/F
timeslot 4
phys_chan_config TCH/F
timeslot 5
phys_chan_config TCH/F
timeslot 6
phys_chan_config TCH/F
timeslot 7
phys_chan_config TCH/F
-
You have to configure one virtual E1 line with the IPA driver in order to use Abis/IP. One e1_line is sufficient for any number of A-bis/IP BTSs, there is no limit like in physical E1 lines.
-
The BTS type must be set using
type nanobts
-
The GSM band must be set according to the BTS hardware.
-
The IPA Unit ID parameter must be set to what has been configured on the BTS side using the BTS Manager or
ipaccess-config
. -
The ARFCN of the BTS.
-
All known nanoBTS units have a nominal transmit power of 23 dBm. If a
max_power_red
of 20 (dB) is configured, the resulting output power at the BTS Tx port is 23 - 20 = 3 dBm.
Note
|
The |
Example configuration for OsmoNITB with multi-TRX nanoBTS
e1_input
e1_line 0 driver ipa
network
network country code 1
mobile network code 1
short name OpenBSC
long name OpenBSC
auth policy closed
location updating reject cause 13
encryption a5 0
neci 1
rrlp mode none
mm info 0
handover 0
bts 0
type nanobts
band DCS1800
cell_identity 0
location_area_code 1
training_sequence_code 7
base_station_id_code 63
ms max power 15
cell reselection hysteresis 4
rxlev access min 0
channel allocator ascending
rach tx integer 9
rach max transmission 7
ip.access unit_id 1800 0 <1>
oml ip.access stream_id 255 line 0
gprs mode none
trx 0
rf_locked 0
arfcn 871
nominal power 23
max_power_red 0
rsl e1 tei 0
timeslot 0
phys_chan_config CCCH+SDCCH4
timeslot 1
phys_chan_config SDCCH8
timeslot 2
phys_chan_config TCH/F
timeslot 3
phys_chan_config TCH/F
timeslot 4
phys_chan_config TCH/F
timeslot 5
phys_chan_config TCH/F
timeslot 6
phys_chan_config TCH/F
timeslot 7
phys_chan_config TCH/F
trx 1
rf_locked 0
arfcn 873
nominal power 23
max_power_red 0
rsl e1 tei 0
timeslot 0
phys_chan_config SDCCH8
timeslot 1
phys_chan_config TCH/F
timeslot 2
phys_chan_config TCH/F
timeslot 3
phys_chan_config TCH/F
timeslot 4
phys_chan_config TCH/F
timeslot 5
phys_chan_config TCH/F
timeslot 6
phys_chan_config TCH/F
timeslot 7
phys_chan_config TCH/F
-
In this example, the IPA Unit ID is specified as
1800 0
. Thus, the first nanoBTS unit (trx 0
) needs to be configured to 1800/0/0 and the second nanoBTS unit (trx 1
) needs to be configured to 1800/0/1. You can configure the BTS unit IDs using theipaccess-config
utility included in OpenBSC.
Note
|
For building a multi-TRX setup, you also need to connect the TIB cables between the two nanoBTS units, as well as the coaxial/RF AUX cabling. |
OsmoNITB HLR subsystem
As OsmoNITB is a fully autonomous system, it also includes a minimal/simplistic HLR and AUC. Compared to real GSM networks, it does not implement any of the external interfaces of a real HLR, such as the MAP/TCAP/SCCP protocol. It can only be used inside the OsmoNITB.
While functionally maintaining the subscriber database and authentication keys, it offers a much reduced feature set. For example, it is not possible to configure bearer service permission lists, or BAOC.
At this time, the only supported database back end for the OsmoNITB internal HLR/AUC is the file-based SQL database SQLite3.
Authorization Policy
Authorization determines how subscribers can access your network. This is unrelated to authentication, which verifies the authenticity of SIM cards that register with the network.
OsmoNITB supports three different authorization policies:
- closed
-
This mode requires subscribers to have a record with their IMSI in the HLR, and it requires that their status is set to
authorized 1
This reflects the most typical operation of GSM networks, where subscribers have to obtain a SIM card issued by the operator. At the time the SIM gets issued, it is provisioned in the HLR to enable the subscriber to use the services of the network. - accept-all
-
This policy accepts any and all subscribers that every try to register to the network. Non-existent subscribers are automatically and dynamically created in the HLR, and they immediately have full access to the network. Any IMSI can register, no matter what SIM card they are using in their phones.
This mode is mostly useful for lab testing or for demonstrating the lack of mutual authentication and the resulting security problems in the GSM system.
Note
|
As you do not know the Ki of dynamically created subscribers with SIM cards of unknown origin, you cannot use cryptographic authentication and/or encryption! |
Caution
|
Never run a network in accept-all mode, unless you know exactly what you are doing. You are very likely causing service interruption to mobile phones in the coverage area of your BTSs, which is punishable under criminal law in most countries! |
- token
-
This method was created for special-purpose configurations at certain events. It tries to combine the benefits of automatic enrollment with foreign IMSI while trying to prevent causing disruption to phones that register to the network by accident.
This policy is currently not actively supported.
The currently active policy can be selected using the
auth policy (closed|accept-all|token)
at the network
configuration
node of the VTY.
Location Update Reject Cause
When a Location Update Request is to be rejected by the network (e.g. due to an unknown or unauthorized subscriber), the Location Update Reject message will contain a Reject Cause.
You can configure the numeric value of that cause by means of the
location updating reject cause <2-111>
command at the network node.
Querying information about a subscriber
Information about a specific subscriber can be obtained from the HLR by
issuing show subscriber
command.
For example, to display information about a subscriber with the IMSI 602022080345046, you can use the following command:
OpenBSC> show subscriber imsi 602022080345046
ID: 1, Authorized: 1 <1>
Name: 'Frank'
Extension: 2342 <2>
LAC: 1/0x1 <3>
IMSI: 602022080345046
TMSI: 4DB8B4D8
Pending: 0
Use count: 1
-
Whether or not the subscriber is authorized for access
-
OsmoNITB is often treated like a PBX, this is why phone numbers are called extensions
-
The Location Area Code (LAC) indicates where in the network the subscriber has last performed a LOCATION UPDATE. Detached subscribers indicate a LAC of 0.
Subscribers don’t have to be identified/referenced by their IMSI, but they can also be identified by their extension (phone number), their TMSI as well as their internal database ID. Example alternatives showing the same subscriber record are:
OpenBSC> show subscriber id 1
or
OpenBSC> show subscriber extension 2342
Enrolling a subscriber
A subscriber can be added to the network in different ways:
-
authorizing an auto-generated subscriber
-
manually creating a subscriber using VTY commands
-
manually creating subscriber by insert into SQL database by external program
Authorizing an auto-generated subscriber
If the subscriber-create-on-demand
configuration option is set in the nitb
VTY config node, then OsmoNITB will automatically create a subscriber record
for every IMSI that ever tries to perform a LOCATION UPDATE with the network.
However, those subscriber records are marked as "not authorized", i.e. they
will not be able to use your network.
You can latter on authorize any such a subscriber using the subscriber IMSI
... authorized 1
command at the VTY enable node.
OpenBSC> enable
OpenBSC# configure terminal
OpenBSC(config)# nitb
OpenBSC(config-nitb)# subscriber-create-on-demand <1>
OpenBSC(config-nitb)# end
OpenBSC# <2>
OpenBSC# subscriber imsi 262420123456789 authorized 1 <3>
-
We first ensure that
subscriber-create-on-demand
is active -
At this time we ensure that the MS with IMSI 262420123456789 performs a location update to our network, e.g. by powering up the associated phone followed by manual operator selection
-
Here we authorize that ISMI
The above method implies that you know the IMSI stored on the SIM card of the
subscriber that you want to to authorize. Unfortunately there is no easy/standard
way to obtain the IMSI on most phones. If the phone has an AT-command
interface, you may try AT+CIMI
. You can also read the IMSI off the SIM using
a PC-attached smart card reader.
Note
|
Contrary to classic GSM networks and for historic reasons, this behavior
is the default behavior of OsmoNITB. For production networks with a closed
subscriber base, it is strongly recommended to use the no
subscriber-create-on-demand option at the nitb VTY config node. |
Manually creating a subscriber from the VTY
You can manually add a subscriber to the HLR by VTY commands. To do so, yo will need to know at the minimum the IMSI of the subscriber.
OpenBSC# subscriber create imsi 262429876543210
ID: 3, Authorized: 0 <1>
Extension: 22150 <2>
LAC: 0/0x0 <3>
IMSI: 262429876543210
Expiration Time: Thu, 01 Jan 1970 01:00:00 +0100
Paging: not paging Requests: 0
Use count: 1
OpenBSC# subscriber imsi 262429876543210 authorized 1 <4>
OpenBSC# subscriber imsi 262429876543210 extension 23234242 <5>
OpenBSC# subscriber imsi 262429876543210 name Sub Scriber <6>
OpenBSC# show subscriber imsi 262429876543210 <7>
ID: 3, Authorized: 1
Name: 'Sub Scriber'
Extension: 23234242
LAC: 0/0x0
IMSI: 262429876543210
Expiration Time: Thu, 01 Jan 1970 01:00:00 +0100
Paging: not paging Requests: 0
Use count: 1
-
as you can see, a newly-created subscriber is not automatically authorized. We will change this in the next step.
-
the NITB has automatically allocated a random 5-digit extension (MSISDN)
-
Location Area Code 0 means that this subscriber is currently not registered on the network
-
Authorize the subscriber
-
Change the extension (MSISDN) to 23234242 (optional)
-
Give the subscriber a human-readable name (optional)
-
Review the content of your new subscriber record
Note
|
If you are running a network with A5 encryption enabled, you must also configure the secret key (Ki) of the SIM card in the HLR. |
You can change further properties on your just-created subscriber as explained in [hlr-subscr-properties].
Creating subscribers in the SQL database
In most applications, the network operator issues his own SIM cards, and the subscriber records corresponding to each SIM will be pre-provisioned by direct insertion into the SQL database. This is performed long before the SIM cards are issued towards the actual end-users.
This can be done by a custom program, the SQL schema is visible from the
.schema
command on the sqlite3 command-line program, and there are several
scripts included in the OpenBSC source code, written in both Python as well as
Perl language.
In case you are obtaining a starter kit with pre-provisioned SIM cards from sysmocom: They will ship with a HLR SQL database containing the subscriber records.
Provisioning SIM cards
In most applications, the operator obtains pre-provisioned SIM cards from a SIM card supplier.
If you prefer to provision the SIM cards yourself, you can use the pySim
tool available from http://cgit.osmocom.org/cgit/pysim/. It has the
ability to append the newly-provisioned SIM cards to an existing HLR
database, please check its --write-hlr
command line argument.
Changing subscriber properties
Once a subscriber exists in the HLR, his properties can be set
interactively from the VTY. Modifying subscriber properties requires
the VTY to be in the privileged (enable
) mode.
All commands are single-line commands and always start with identifying the subscriber on which the operation shall be performed. Such identification can be performed by
-
IMSI
-
TMSI
-
extension number
-
ID (internal identifier)
Changing the subscriber phone number
You can set the phone number of the subscriber with IMSI 602022080345046 to 12345 by issuing the following VTY command from the enable node:
OpenBSC# subscriber imsi 602022080345046 extension 12345
Changing the subscriber name
The subscriber name is an internal property of OsmoNITB. The name will never be transmitted over the air interface or used by the GSM protocol. The sole purpose of the name is to make log output more intuitive, as human readers of log files tend to remember names easier than IMSIs or phone numbers.
In order to set the name of subscriber with extension number 12345 to
"Frank", you can issue the following command on the VTY enable node:
subscriber extension 12345 name Frank
The name may contain spaces and special characters. You can verify the
modified subscriber record by issuing the show subscriber extension
12345
command.
Changing the authorization status
As the HLR automatically adds records for all subscribers it sees, those that are actually permitted to use the network have to be authorized by setting the authorized property of the subscriber.
You can set the authorized property by issuing the following VTY command from the enable node:
OpenBSC# subscriber extension 12345 authorized 1
Similarly, you can remove the authorized status from a subscriber by issuing the following command:
OpenBSC# subscriber extension 12345 authorized 0
Changing the GSM authentication algorithm and Ki
In order to perform cryptographic authentication of the subscriber, his Ki needs to be known to the HLR/AUC. Furthermore, the authentication algorithm implemented on the SIM card (A3/A8) must match that of the algorithm configured in the HLR.
Currently, OsmoNITB supports the following authentication algorithms:
- none
-
No authentication is performed
- xor
-
Authentication is performed using the XOR algorithm (for test/debugging purpose)
- comp128v1
-
Authentication is performed according to the COMP128v1 algorithm
Warning
|
None of the supported authentication algorithms are cryptographically very strong. Development is proceeding to include support for stronger algorithms like GSM-MILENAGE. Please contact sysmocom if you require strong authentication support. |
In order to configure a subscriber for COMP128v1 and to set his Ki, you can use the following VTY command from the enable node:
OpenBSC# subscriber extension 2342 a3a8 comp128v1 000102030405060708090a0b0c0d0e0f
Short Message Peer to Peer (SMPP)
The Short Message Peer to Peer (SMPP) Protocol [smpp-34] has been used for the communication with SMSCs. Osmocom implements version 3.4 of the protocol. Using this interface one can send MT-SMS to an attached subscriber or receive unrouted MO-SMS.
SMPP is served by the Osmocom MSC layer (both in the old OsmoNITB as well as the new OsmoMSC.
SMPP describes a situation where multiple ESMEs (External SMS Entities) interact with a SMSC (SMS Service Center) via the SMPP protocol. Each entity is identified by its System Id. The System ID is a character string which is configured by the system administrator.
OsmoNITB implements the SMSC side of SMPP and subsequently acts as a TCP server accepting incoming connections from ESME client programs.
Each ESME identifies itself to the SMSC with its system-id and an optional shared password.
Global SMPP configuration
There is a smpp
vty node at the top level of the OsmoNITB
configuration. Under this node, the global SMPP configuration is
performed.
Use the local-tcp-ip
command to define the TCP IP and port at which the
OsmoNITB internal SMSC should listen for incoming SMPP connections. The
default behaviour is to listen on all IPs (0.0.0.0), and the default port
assigned to SMPP is 2775.
Use the system-id
command to define the System ID of the SMSC.
Use the policy
parameter to define whether only explicitly configured
ESMEs are permitted to access the SMSC (closed
), or whether any
ESME should be accepted (accept-all
).
Use the smpp-first
command to define if SMPP routes have higher
precedence than MSISDNs contained in the HLR (smpp-first
), or if
only MSISDNs found not in the HLR should be considered for routing to
SMPP (no smpp-first
).
ESME configuration
Under the smpp
vty node, you can add any number of esme
nodes, one
for each ESME that you wish to configure.
Use the esme NAME
command (where NAME corresponds to the system-id of
the ESME to be configured) under the SMPP vty node to enter the
configuration node for this given ESME.
Use the password
command to specify the password (if any) for the
ESME.
Use the default-route
command to indicate that any MO-SMS without a
more specific route should be routed to this ESME.
Use the deliver-src-imsi
command to indicate that the SMPP DELIVER
messages for MO SMS and the SMPP ALERT should state the IMSI (rather
than the MSISDN) as source address.
Use the osmocom-extensions
command to request that Osmocom specific
extension TLVs shall be included in the SMPP PDUs. Those extensions
include the ARFCN of the cell, the L1 transmit power of the MS, the
timing advance, the uplink and dwnlink RxLev and RxQual, as well as the
IMEI of the terminal at the time of generating the SMPP DELIVER PDU.
Use the dcs-transparent
command to transparently pass the DCS value
from the SMS Layer3 protocols to SMPP, instead of converting them to the
SMPP-specific values.
Use the route prefix
command to specify a route towards this ESME.
Using routes, you specify which destination MSISDNs should be routed
towards your ESME.
Example configuration snippet
The following example configuration snippet shows a single ESME galactica with a prefix-route of all national numbers stating with 2342:
smpp
local-tcp-port 2775
policy closed
no smpp-first
esme galactica
password SoSayWeAll
deliver-src-imsi
osmocom-extensions
route prefix national isdn 2342
Osmocom SMPP protocol extensions
Osmocom has implemented some extensions to the SMPP v3.4 protocol.
These extensions can be enabled using the osmocom-extensions
VTY
command at esme
level.
The TLV definitions can be found in the
<osmocom/gsm/protocol/smpp34_osmocom.h>
header file provided by
libosmocore.
RF channel measuremets
When the Osmocom SMPP extensions are enabled, we add the following TLVs to each SMPP DELIVER PDU:
TLV | IEI | Length (Octets) | Purpose |
---|---|---|---|
TLVID_osmo_arfcn |
0x2300 |
2 |
GSM ARFCN of the radio interface |
TLVID_osmo_ta |
0x2301 |
1 |
Timing Advance on the radio interface |
TLVID_osmo_ms_l1_txpwr |
0x2307 |
1 |
Transmit Power of the MS in uplink direction |
TLVID_osmo_rxlev_ul |
0x2302 |
2 |
Uplink receive level as measured by BTS in dBm (int16_t) |
TLVID_osmo_rxqual_ul |
0x2303 |
1 |
Uplink RxQual value as measured by BTS |
TLVID_osmo_rxlev_dl |
0x2304 |
2 |
Downlink receive level as measured by MS in dBm (int16_t) |
TLVID_osmo_rxqual_dl |
0x2305 |
1 |
Downlink RxQual value as measured by MS |
All of the above values reflect the last measurement report as received vi A-bis RSL from the BTS. It is thus a snapshot value (of the average within one 480ms SACCH period), and not an average over all the SACCH periods during which the channel was open or the SMS was received. Not all measurement reports contain all the values. So you might not get an TLVID_osmo_rxlev_dl IE, as that particular uplink frame might habe benn lost for the given snapshot we report.
Equipment IMEI
If we know the IMEI of the subscribers phone, we add the following TLV to each SMPP DELIVER PDU:
TLV | IEI | Length | Purpose |
---|---|---|---|
TLVID_osmo_imei |
0x2306 |
variable |
IMEI of the subscribers phone (ME) |
MNCC for External Call Control
The 3GPP GSM specifications define an interface point (service access point) inside the MSC between the call-control part and the rest of the system. This service access point is called the MNCC-SAP. It is described in 3GPP TS 24.007 [3gpp-ts-24-007] Chapter 7.1.
However, like for all internal interfaces, 3GPP does not give any specific encoding for the primitives passed at this SAP.
The MNCC protocol has been created by the Osmocom community
and allows to control the call handling and audio processing by an
external application. The interface is currently exposed using Unix
Domain Sockets. The protocol is defined in the mncc.h
header file.
It is exposed by the Osmocom MSC layer (both in the old OsmoNITB as well as the new OsmoMSC.
OsmoNITB can run in two different modes:
-
with internal MNCC handler
-
with external MNCC handler
Internal MNCC handler
When the internal MNCC handler is enabled, OsmoNITB will switch voice calls between GSM subscribers internally and automatically based on the the subscribers extension number. No external software is required.
Note
|
Internal MNCC is the default behavior. |
Internal MNCC Configuration
The internal MNCC handler offers some configuration parameters under the
mncc-int
VTY configuration node.
default-codec tch-f (fr|efr|amr)
Using this command, you can configure the default voice codec to be used by voice calls on TCH/F channels.
default-codec tch-h (hr|amr)
Using this command, you can configure the default voice codec to be used by voice calls on TCH/H channels.
External MNCC handler
When the external MNCC handler is enabled, OsmoNITB will not perform any internal call switching, but delegate all call-control handling towards the external MNCC program connected via the MNCC socket.
If you intend to operate OsmoNITB with external MNCC handler, you have to disable the internal MNCC handler and specify the MNCC socket path in the configuration file.
At the time of this writing, there are only two known open source applications implementing the MNCC interface compatible with the Osmocom MNCC socket:
-
historically
lcr
, the Linux Call Router (support for modern MNCC protocol versions may be missing) -
osmo-sip-connector
, the more up-to-date integration of external call routing by translating MNCC into a SIP trunk towards an external SIP PBX / switch.
DTMF considerations
In mobile networks, the signaling of DTMF tones is implemented differently, depending on the signaling direction. A mobile originated DTMF tone is signaled using START/STOP DTMF messages which are hauled through various protocols upwards into the core network.
Contrary to that, a mobile terminated DTMF tone is not transferred as an out of band message. Instead, in-band signaling is used, which means a tone is injected early inside a PBX or MGW.
When using OsmoNITB with its built in MNCC functionality a mobile originated DTMF message will not be translated into an in-band tone. Therefore, sending DTMF will not work when internal MNCC is used.
For external MNCC, the network integrator must make sure that the back-end components are configured properly in order to handle the two different signaling schemes depending on the signaling direction.
Note
|
osmo-sip-connector will translate MNCC DTMF signaling into sip-info messages. DTMF signaling in the opposite direction is not possible. osmo-sip-connector will reject sip-info messages that attempt to signal a DTMF tone. |
MNCC protocol description
The protocol follows the primitives specified in 3GPP TS 04.07 Chapter 7.1.
The encoding of the primitives is provided in the mncc.h
header file in
OsmoNITB’s source tree, which uses some common definitions from
osmocom/gsm/mncc.h
(part of libosmocore.git).
However, Osmocom’s MNCC specifies a number of additional primitives beyond those listed in the 3GPP specification.
The different calls in the network are distinguished by their callref (call reference), which is a unique unsigned 32bit integer.
MNCC_HOLD_IND
Direction: OsmoNITB → Handler
A CC HOLD message was received from the MS.
MNCC_HOLD_CNF
Direction: Handler → OsmoNITB
Acknowledge a previously-received CC HOLD message, causes the transmission of a CC HOLD ACK message to the MS.
MNCC_HOLD_REJ
Direction: Handler → OsmoNITB
Reject a previously-received CC HOLD message, causes the transmission of a CC HOLD REJ message to the MS.
MNCC_RETRIEVE_IND
Direction: OsmoNITB → Handler
A CC RETRIEVE message was received from the MS.
MNCC_RETRIEVE_CNF
Direction: Handler → OsmoNITB
Acknowledge a previously-received CC RETRIEVE message, causes the transmission of a CC RETRIEVE ACK message to the MS.
MNCC_RETRIEVE_REJ
Direction: Handler → OsmoNITB
Reject a previously-received CC RETRIEVE message, causes the transmission of a CC RETRIEVE REJ message to the MS.
MNCC_USERINFO_REQ
Direction: OsmoNITB → Handler
Causes a CC USER INFO message to be sent to the MS.
MNCC_USERINFO_IND
Direction: OsmoNITB → Handler
Indicates that a CC USER-USER message has been received from the MS.
MNCC_BRIDGE
Direction: Handler → OsmoNITB
Requests that the TCH (voice) channels of two calls shall be inter-connected. This is the old-fashioned way of using MNCC, historically required for circuit-switched BTSs whose TRAU frames are received via an E1 interface card, and works only when the TCH channel types match.
Note
|
Internal MNCC uses MNCC_BRIDGE to connect calls directly between connected BTSs or RNCs, in effect disallowing calls between mismatching TCH types and forcing all BTSs to be configured with exactly one TCH type and codec. This is a limitation that will probably remain for the old OsmoNITB. For the new OsmoMSC, the MNCC_BRIDGE command will instruct the separate OsmoMGW to bridge calls, which will be able to handle transcoding between different TCH as well as 3G (IuUP) payloads (but note: not yet implemented at the time of writing this). Hence an external MNCC may decide to bridge calls directly between BTSs or RNCs that both are internal to the OsmoMSC, for optimization reasons. |
MNCC_FRAME_RECV
Direction: Handler → OsmoNITB
Enable the forwarding of TCH voice frames via the MNCC interface in OsmoNITB→Handler direction for the specified call.
MNCC_FRAME_DROP
Direction: Handler → OsmoNITB
Disable the forwarding of TCH voice frames via the MNCC interface in OsmoNITB→Handler direction for the specified call.
MNCC_LCHAN_MODIFY
Direction: Handler → OsmoNITB
Modify the current dedicated radio channel from signalling to voice, or if it is a signalling-only channel (SDCCH), assign a TCH to the MS.
MNCC_RTP_CREATE
Direction: Handler → OsmoNITB
Create a RTP socket for this call at the BTS/TRAU that serves this BTS.
MNCC_RTP_CONNECT
Direction: Handler → OsmoNITB
Connect the RTP socket of this call to the given remote IP address and port.
MNCC_RTP_FREE
Direction: Handler → OsmoNITB
Release a RTP connection for one given call.
GSM_TCHF_FRAME
Direction: both
Transfer the payload of a GSM Full-Rate (FR) voice frame between the OsmoNITB and an external MNCC handler.
GSM_TCHF_FRAME_EFR
Direction: both
Transfer the payload of a GSM Enhanced Full-Rate (EFR) voice frame between the OsmoNITB and an external MNCC handler.
GSM_TCHH_FRAME
Direction: both
Transfer the payload of a GSM Half-Rate (HR) voice frame between the OsmoNITB and an external MNCC handler.
GSM_TCH_FRAE_AMR
Direction: both
Transfer the payload of a GSM Adaptive-Multi-Rate (AMR) voice frame between the OsmoNITB and an external MNCC handler.
GSM_BAD_FRAME
Direction: OsmoNITB → Handler
Indicate that no valid voice frame, but a bad frame was received over the radio link from the MS.
MNCC_START_DTMF_IND
Direction: OsmoNITB → Handler
Indicate the beginning of a DTMF tone playback.
MNCC_START_DTMF_RSP
Direction: Handler → OsmoNITB
Acknowledge that the DTMF tone playback has been started.
MNCC_START_DTMF_REJ
Direction: both
Indicate that starting a DTMF tone playback was not possible.
MNCC_STOP_DTMF_IND
Direction: OsmoNITB → Handler
Indicate the ending of a DTMF tone playback.
MNCC_STOP_DTMF_RSP
Direction: Handler → OsmoNITB
Acknowledge that the DTMF tone playback has been stopped.
Osmocom Control Interface
The VTY interface as described in [vty] is aimed at human interaction with the respective Osmocom program.
Other programs should not use the VTY interface to interact with the Osmocom software, as parsing the textual representation is cumbersome, inefficient, and will break every time the formatting is changed by the Osmocom developers.
Instead, the Control Interface was introduced as a programmatic interface that can be used to interact with the respective program.
Control Interface Protocol
The control interface protocol is a mixture of binary framing with text based payload.
The protocol for the control interface is wrapped inside the IPA multiplex header with the stream identifier set to IPAC_PROTO_OSMO (0xEE).
Inside the IPA header is a single byte of extension header with protocol ID 0x00 which indicates the control interface.
After the concatenation of the two above headers, the plain-text payload message starts. The format of that plain text is illustrated for each operation in the respective message sequence chart in the chapters below.
The fields specified below follow the following meaning:
- <id>
-
A numeric identifier, uniquely identifying this particular operation. Value
0
is not allowed unless it’s a TRAP message. It will be echoed back in any response to a particular request. - <var>
-
The name of the variable / field affected by the GET / SET / TRAP operation. Which variables/fields are available is dependent on the specific application under control.
- <val>
-
The value of the variable / field
- <reason>
-
A text formatted, human-readable reason why the operation resulted in an error.
GET operation
The GET operation is performed by an external application to get a certain value from inside the Osmocom application.
SET operation
The SET operation is performed by an external application to set a value inside the Osmocom application.
TRAP operation
The program can at any time issue a trap. The term is used in the spirit of SNMP.
Common variables
There are several variables which are common to all the programs using control interface. They are described in the following table.
Name | Access | Value | Comment |
---|---|---|---|
counter.* |
RO |
Get counter value. |
|
rate_ctr.* |
RO |
Get list of rate counter groups. |
|
rate_ctr.IN.GN.GI.name |
RO |
Get value for interval IN of rate counter name which belong to group named GN with index GI. |
Those read-only variables allow to get value of arbitrary counter using its name.
For example "rate_ctr.per_hour.bsc.0.handover:timeout
" is the number of handover timeouts per hour.
Of course for that to work the program in question have to register corresponding counter names and groups using libosmocore functions.
In the example above, "bsc
" is the rate counter group name and "0
" is its index. It is possible to
obtain all the rate counters in a given group by requesting "rate_ctr.per_sec.bsc.*
" variable.
The list of available groups can be obtained by requesting "rate_ctr.*
" variable.
The rate counter group name have to be prefixed with interval specification which can be any of "per_sec", "per_min", "per_hour", "per_day" or "abs" for absolute value.
The old-style counters available via "counter.*
" variables are superseded by "rate_ctr.abs
"
so its use is discouraged.
There might still be some applications not yet converted to rate_ctr.
Control Interface python examples
In the osmo-python-tests
repository, there is an example python script
called scripts/osmo_ctrl.py
which implements the Osmocom
control interface protocol.
You can use this tool either stand-alone to perform control interface operations against an Osmocom program, or you can use it as a reference for developing your own python software talking to the control interface.
Another implementation is in scripts/osmo_rate_ctr2csv.py
which will retrieve performance counters
for a given Osmocom program and output it in csv format. This can be used to periodically (using systemd timer
for example) retrieve data to build KPI and evaluate how it changes over time.
Internally it uses "rate_ctr.*
" variable described in [ctrl_common_vars] to get the list of counter groups
and than request all the counters in each group. Applications interested in individual metrics can request it
directly using rate_ctr2csv.py
as an example.
Getting rate counters
rate_ctr2csv.py
to get rate counters from OsmoBSC$ ./scripts/osmo_rate_ctr2csv.py --header
Connecting to localhost:4249...
Getting rate counter groups info...
"group","counter","absolute","second","minute","hour","day"
"e1inp.0","hdlc:abort","0","0","0","0","0"
"e1inp.0","hdlc:bad_fcs","0","0","0","0","0"
"e1inp.0","hdlc:overrun","0","0","0","0","0"
"e1inp.0","alarm","0","0","0","0","0"
"e1inp.0","removed","0","0","0","0","0"
"bsc.0","chreq:total","0","0","0","0","0"
"bsc.0","chreq:no_channel","0","0","0","0","0"
...
"msc.0","call:active","0","0","0","0","0"
"msc.0","call:complete","0","0","0","0","0"
"msc.0","call:incomplete","0","0","0","0","0"
Completed: 44 counters from 3 groups received.
Setting a value
osmo_ctrl.py
to set the short network name of OsmoBSC$ ./osmo_ctrl.py -d localhost -s short-name 32C3
Got message: SET_REPLY 1 short-name 32C3
Getting a value
osmo_ctrl.py
to get the mnc of OsmoBSC$ ./osmo_ctrl.py -d localhost -g mnc
Got message: GET_REPLY 1 mnc 262
Listening for traps
You can use osmo_ctrl.py
to listen for traps the following way:
osmo_ctrl.py
to listen for traps:$ ./osmo_ctrl.py -d localhost -m
<1>
-
the command will not return and wait for any TRAP messages to arrive
Cell Broadcast
Normally, all user plane data in GSM/GPRS networks are sent in point-to-point channels from the network to the user. Those are called dedicated radio channels which exist between the network and one given phone/subscriber at a time.
Cell Broadcast is an exception to that rule. It permits user data (so-called SMS-CB data) to be broadcast by the network in a way that can be received by all phones in the coverage area of the given BTS simultaneously.
More high-level information can be found at https://en.wikipedia.org/wiki/Cell_Broadcast and the related specification is [3gpp-ts-23-041].
Use Cases
Cell Broadcast was used for various different use cases primarily in the 1990s and early 2000s, including
-
advertisement of the GPS position of the cell tower you’re currently camping on
-
advertisement of the calling codes of your current "home zone", i.e. a "lower cost short distance" call zone travelling with you as you roam around.
More recently, SMS-CB is seeing some uptake by various disaster warning systems, such as
-
CMAS (Commercial Mobile Alert System), later renamed to WEA (Wireless Emergency Alerts) in the US.
-
EU-Alert in the European union
-
Messer Ishi (Rocket Alert) in Israel
-
ETWS (Earthquake and Tsunami Warning System) in Japan
-
KPAS (Korean Public Alert System)
Osmocom Cell Broadcast support
-
OsmoBTS implements the
SMS BROADCAST COMMAND
Message in A-bis RSL according to Section 8.5.8 of 3GPP TS 48.058 -
low-level testing/debugging features
-
OsmoNITB and OsmoBSC implement a VTY command
bts <0-255> smscb-command <1-4> HEXSTRING
to send a given hex-formatted cell broadcast message to a specified BTS. This can be used for low-level debugging
-
-
proper 3GPP-specified CBS/PWS elements and protocols
-
OsmoBSC supports routing and distribution of CBS and warning messages
-
OsmoBSC implements the BSC-CBC interface using the CBSP protocol
-
OsmoCBC implements the central function of a Cell Broadcast Centre, receiving cell broadcast and warning messages from external entities via a REST based HTTP interface, and distributing it throughout the cellular network.
-
OsmoCBC implements the BSC-CBC interface using the CBSP protocol (for 2G/GSM RAN)
-
OsmoCBC implements the MME-CBC interface using the SBcAP protocol (for 4G/LTE RAN)
-
Message Structure
-
Each message has a maximum of 15 pages
-
Each page is 82 bytes of data, resulting in 93 characters in GSM 7-bit default alphabet
-
Messages are broadcast on logical channels (more like an address)
-
Subscribers can activate/deactivate selective addresses
Abis/IP Interface
A-bis Operation & Maintenance Link
The GSM Operation & Maintenance Link (OML) is specified in 3GPP TS 12.21 and is used between a GSM Base-Transceiver-Station (BTS) and a GSM Base-Station-Controller (BSC). The default TCP port for OML is 3002. The connection will be opened from the BTS to the BSC.
Abis OML is only specified over E1 interfaces. The Abis/IP implementation of OsmoBTS and OsmoBSC extend and/or deviate from the TS 12.21 specification in several ways. Please see the OsmoBTS Abis Protocol Specification [osmobts-abis-spec] for more information.
A-bis Radio Signalling Link
The GSM Radio Signalling Link (RSL) is specified in 3GPP TS 08.58 and is used between a GSM Base-Transceiver-Station and a GSM Base-Station-Controller (BSC). The default TCP port for RSL is 3003. The connection will be opened from the BTS to BSC after it has been instructed by the BSC.
Abis RSL is only specified over E1 interfaces. The Abis/IP implementation of OsmoBTS and OsmoBSC extend and/or deviate from the TS 08.58 specification in several ways. Please see the OsmoBTS Abis Protocol Specification [osmobts-abis-spec] for more information.
Locate Abis/IP based BTS
We can use a tool called abisip-find to be able to find BTS which is connected in the network. This tool is located in the OsmoBSC project repository under: ./src/ipaccess
abisip-find
abisip-find is a small command line tool which is used to search and find BTS devices in your network (e.g. sysmoBTS, nanoBTS).
It uses broadcast packets of the UDP variant of the Abis-IP protocol on port 3006, and thus will find any BTS that can be reached by the all-network broadcast address 255.255.255.255
When program is started it will print one line for each BTS it can find.
$ ./abisip-find
abisip-find (C) 2009 by Harald Welte
This is FREE SOFTWARE with ABSOLUTELY NO WARRANTY
you might need to specify the outgoing
network interface, e.g. ``abisip-find eth0``
Trying to find ip.access BTS by broadcast UDP...
MAC_Address='24:62:78:01:02:03' IP_Address='192.168.0.171' Serial_Number='123'
Unit_ID='sysmoBTS 1002'
MAC_Address='24:62:78:04:05:06' IP_Address='192.168.0.182' Serial_Number='456'
Unit_ID='sysmoBTS 1002'
MAC Address='00:01:02:03:04:05' IP Address='192.168.100.123' Unit ID='65535/0/0'
Location_1='' Location 2='BTS_NBT131G' Equipment Version='165a029_55'
Software Version='168a302_v142b13d0' Unit Name='nbts-00-02-95-00-4E-B3'
Serial Number='00123456'
^C
You may have to start the program as a root:
$ sudo ./abisip-find eth0
Deploying a new nanoBTS
A tool called ipaccess-config can be used to configure a new ip.access nanoBTS.
ipaccess-config
This program is very helpful tool which is used to configure Unit ID and Primary OML IP. You can find this tool in the OsmoBSC repository under: ./src/ipaccess
nanoBTS
$ ./ipaccess-config -u 1801/0/0<1> 10.9.1.195<2> -o 10.9.1.154<3>
ipaccess-config (C) 2009-2010 by Harald Welte and others
This is FREE SOFTWARE with ABSOLUTELY NO WARRANTY
Trying to connect to ip.access BTS ...
abis_nm.c:316 OC=SITE-MANAGER(00) INST=(ff,ff,ff) STATE CHG:
OP_STATE=Disabled AVAIL=Not installed(07)
abis_nm.c:316 OC=BTS(01) INST=(00,ff,ff) STATE CHG:
OP_STATE=Disabled AVAIL=Not installed(07) ADM=Locked
abis_nm.c:316 OC=BASEBAND-TRANSCEIVER(04) INST=(00,00,ff) STATE CHG:
OP_STATE=Disabled AVAIL=Not installed(07) ADM=Locked
OML link established using TRX 0
setting Unit ID to '1801/0/0'
setting primary OML link IP to '10.9.1.154'
abis_nm.c:316 OC=CHANNEL(03) INST=(00,00,00) STATE CHG:
OP_STATE=Disabled AVAIL=Not installed(07) ADM=Locked
...
abis_nm.c:2433 OC=BASEBAND-TRANSCEIVER(04) INST=(00,00,ff) IPACCESS(0xf0):
SET NVATTR ACK
Set the NV Attributes.
-
Unit ID
-
IP address of the NITB
-
IP address of the nanoBTS
Appendix A. Osmocom TCP/UDP Port Numbers
The Osmocom GSM system utilizes a variety of TCP/IP based protocols. The table below provides a reference as to which port numbers are used by which protocol / interface.
L4 Protocol | Port Number | Purpose | Software |
---|---|---|---|
UDP |
1984 |
Osmux |
osmo-mgw, osmo-bts |
UDP |
2427 |
MGCP GW |
osmo-bsc_mgcp, osmo-mgw |
TCP |
2775 |
SMPP (SMS interface for external programs) |
osmo-nitb |
TCP |
3002 |
A-bis/IP OML |
osmo-bts, osmo-bsc, osmo-nitb |
TCP |
3003 |
A-bis/IP RSL |
osmo-bts, osmo-bsc, osmo-nitb |
TCP |
4227 |
telnet (VTY) |
osmo-pcap-client |
TCP |
4228 |
telnet (VTY) |
osmo-pcap-server |
TCP |
4236 |
Control Interface |
osmo-trx |
TCP |
4237 |
telnet (VTY) |
osmo-trx |
TCP |
4238 |
Control Interface |
osmo-bts |
TCP |
4239 |
telnet (VTY) |
osmo-stp |
TCP |
4240 |
telnet (VTY) |
osmo-pcu |
TCP |
4241 |
telnet (VTY) |
osmo-bts |
TCP |
4242 |
telnet (VTY) |
osmo-nitb, osmo-bsc, cellmgr-ng |
TCP |
4243 |
telnet (VTY) |
osmo-bsc_mgcp, osmo-mgw |
TCP |
4244 |
telnet (VTY) |
osmo-bsc_nat |
TCP |
4245 |
telnet (VTY) |
osmo-sgsn |
TCP |
4246 |
telnet (VTY) |
osmo-gbproxy |
TCP |
4247 |
telnet (VTY) |
OsmocomBB |
TCP |
4249 |
Control Interface |
osmo-nitb, osmo-bsc |
TCP |
4250 |
Control Interface |
osmo-bsc_nat |
TCP |
4251 |
Control Interface |
osmo-sgsn |
TCP |
4252 |
telnet (VTY) |
sysmobts-mgr |
TCP |
4253 |
telnet (VTY) |
osmo-gtphub |
TCP |
4254 |
telnet (VTY) |
osmo-msc |
TCP |
4255 |
Control Interface |
osmo-msc |
TCP |
4256 |
telnet (VTY) |
osmo-sip-connector |
TCP |
4257 |
Control Interface |
osmo-ggsn, ggsn (OpenGGSN) |
TCP |
4258 |
telnet (VTY) |
osmo-hlr |
TCP |
4259 |
Control Interface |
osmo-hlr |
TCP |
4260 |
telnet (VTY) |
osmo-ggsn |
TCP |
4261 |
telnet (VTY) |
osmo-hnbgw |
TCP |
4262 |
Control Interface |
osmo-hnbgw |
TCP |
4263 |
Control Interface |
osmo-gbproxy |
TCP |
4264 |
telnet (VTY) |
osmo-cbc |
TCP |
4265 |
Control Interface |
osmo-cbc |
TCP |
4266 |
D-GSM MS Lookup: mDNS serve |
osmo-hlr |
TCP |
4267 |
Control Interface |
osmo-mgw |
TCP |
4268 |
telnet (VTY) |
osmo-uecups |
SCTP |
4268 |
UECUPS |
osmo-uecups |
TCP |
4269 |
telnet (VTY) |
osmo-e1d |
TCP |
4270 |
telnet (VTY) |
osmo-isdntap |
TCP |
4271 |
telnet (VTY) |
osmo-smlc |
TCP |
4272 |
Control Interface |
osmo-smlc |
TCP |
4273 |
telnet (VTY) |
osmo-hnodeb |
TCP |
4274 |
Control Interface |
osmo-hnodeb |
TCP |
4275 |
telnet (VTY) |
osmo-upf |
TCP |
4276 |
Control Interface |
osmo-upf |
TCP |
4277 |
telnet (VTY) |
osmo-pfcp-tool |
TCP |
4278 |
Control Interface |
osmo-pfcp-tool |
UDP |
4729 |
GSMTAP |
Almost every osmocom project |
TCP |
5000 |
A/IP |
osmo-bsc, osmo-bsc_nat |
UDP |
23000 |
GPRS-NS over IP default port |
osmo-pcu, osmo-sgsn, osmo-gbproxy |
TCP |
48049 |
BSC-CBC (CBSP) default port |
osmo-bsc, osmo-cbc |
Appendix A. Bibliography / References
-
[osmobts-abis-spec] Neels Hofmeyr & Harald Welte. OsmoBTS Abis Protocol Specification. https://ftp.osmocom.org/docs/latest/osmobts-abis.pdf
-
[userman-osmobsc] Osmocom Project: OsmoBSC User Manual. https://ftp.osmocom.org/docs/latest/osmobsc-usermanual.pdf
-
[vty-ref-osmobsc] Osmocom Project: OsmoBSC VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmobsc-vty-reference.pdf
-
[userman-osmobts] Osmocom Project: OsmoBTS User Manual. https://ftp.osmocom.org/docs/latest/osmobts-usermanual.pdf
-
[vty-ref-osmobts] Osmocom Project: OsmoBTS VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmobts-trx-vty-reference.pdf https://ftp.osmocom.org/docs/latest/osmobts-sysmo-vty-reference.pdf https://ftp.osmocom.org/docs/latest/osmobts-lc15-vty-reference.pdf https://ftp.osmocom.org/docs/latest/osmobts-oc2g-vty-reference.pdf https://ftp.osmocom.org/docs/latest/osmobts-octphy-vty-reference.pdf https://ftp.osmocom.org/docs/latest/osmobts-virtual-vty-reference.pdf
-
[userman-osmocbc] Osmocom Project: OsmoCBC User Manual. https://ftp.osmocom.org/docs/latest/osmocbc-usermanual.pdf
-
[vty-ref-osmocbc] Osmocom Project: OsmoCBC VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmocbc-vty-reference.pdf
-
[userman-osmogbproxy] Osmocom Project: OsmoGBProxy User Manual. https://ftp.osmocom.org/docs/latest/osmogbproxy-usermanual.pdf
-
[vty-ref-osmogbproxy] Osmocom Project: OsmoGBPRoxy VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmogbproxy-vty-reference.pdf
-
[userman-osmoggsn] Osmocom Project: OpenGGSN User Manual. https://ftp.osmocom.org/docs/latest/osmoggsn-usermanual.pdf
-
[vty-ref-osmoggsn] Osmocom Project: OsmoGGSN VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmoggsn-vty-reference.pdf
-
[userman-osmohlr] Osmocom Project: OsmoHLR User Manual. https://ftp.osmocom.org/docs/latest/osmohlr-usermanual.pdf
-
[vty-ref-osmohlr] Osmocom Project: OsmoHLR VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmohlr-vty-reference.pdf
-
[userman-osmohnbgw] Osmocom Project: OsmoHNBGW User Manual. https://ftp.osmocom.org/docs/latest/osmohnbgw-usermanual.pdf
-
[vty-ref-osmohnbgw] Osmocom Project: OsmoHNBGW VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmohnbgw-vty-reference.pdf
-
[userman-osmomgw] Osmocom Project: OsmoMGW User Manual. https://ftp.osmocom.org/docs/latest/osmomgw-usermanual.pdf
-
[vty-ref-osmomgw] Osmocom Project: OsmoMGW VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmomgw-vty-reference.pdf
-
[userman-osmomsc] Osmocom Project: OsmoMSC User Manual. https://ftp.osmocom.org/docs/latest/osmomsc-usermanual.pdf
-
[vty-ref-osmomsc] Osmocom Project: OsmoMSC VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmomsc-vty-reference.pdf
-
[userman-osmonitb] Osmocom Project: OsmoNITB User Manual. https://ftp.osmocom.org/docs/latest/osmonitb-usermanual.pdf
-
[vty-ref-osmonitb] Osmocom Project: OsmoNITB VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmonitb-vty-reference.pdf
-
[userman-osmopcu] Osmocom Project: OsmoPCU User Manual. https://ftp.osmocom.org/docs/latest/osmopcu-usermanual.pdf
-
[vty-ref-osmopcu] Osmocom Project: OsmoPCU VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmopcu-vty-reference.pdf
-
[userman-osmosgsn] Osmocom Project: OsmoSGSN User Manual. https://ftp.osmocom.org/docs/latest/osmosgsn-usermanual.pdf
-
[vty-ref-osmosgsn] Osmocom Project: OsmoSGSN VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmosgsn-vty-reference.pdf
-
[userman-osmosipconnector] Osmocom Project: OsmoSIPconnector User Manual. https://ftp.osmocom.org/docs/latest/osmosipconnector-usermanual.pdf
-
[vty-ref-osmosipconnector] Osmocom Project: OsmoSIPconnector VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmosipconnector-vty-reference.pdf
-
[userman-osmosmlc] Osmocom Project: OsmoSMLC User Manual. https://ftp.osmocom.org/docs/latest/osmosmlc-usermanual.pdf
-
[vty-ref-osmosmlc] Osmocom Project: OsmoSMLC VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmosmlc-vty-reference.pdf
-
[userman-osmostp] Osmocom Project: OsmoSTP User Manual. https://ftp.osmocom.org/docs/latest/osmostp-usermanual.pdf
-
[vty-ref-osmostp] Osmocom Project: OsmoSTP VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmostp-vty-reference.pdf
-
[userman-osmotrx] Osmocom Project: OsmoTRX User Manual. https://ftp.osmocom.org/docs/latest/osmotrx-usermanual.pdf
-
[vty-ref-osmotrx] Osmocom Project: OsmoTRX VTY Reference Manual. https://ftp.osmocom.org/docs/latest/osmotrx-uhd-vty-reference.pdf https://ftp.osmocom.org/docs/latest/osmotrx-lms-vty-reference.pdf https://ftp.osmocom.org/docs/latest/osmotrx-ipc-vty-reference.pdf https://ftp.osmocom.org/docs/latest/osmotrx-usrp1-vty-reference.pdf
-
[3gpp-ts-23-041] 3GPP TS 23.041: Technical realization of Cell Broadcast Service (CBS)
-
[3gpp-ts-23-048] 3GPP TS 23.048: Security mechanisms for the (U)SIM application toolkit; Stage 2 https://www.3gpp.org/DynaReport/23048.htm
-
[3gpp-ts-23-236] 3GPP TS 23.236: Intra-domain connection of Radio Access Network (RAN) nodes to multiple Core Network (CN) nodes https://www.3gpp.org/DynaReport/23236.htm
-
[3gpp-ts-24-007] 3GPP TS 24.007: Mobile radio interface signalling layer 3; General Aspects https://www.3gpp.org/DynaReport/24007.htm
-
[3gpp-ts-24-008] 3GPP TS 24.008: Mobile radio interface Layer 3 specification; Core network protocols; Stage 3. https://www.3gpp.org/dynareport/24008.htm
-
[3gpp-ts-31-101] 3GPP TS 31.101: UICC-terminal interface; Physical and logical characteristics https://www.3gpp.org/DynaReport/31101.htm
-
[3gpp-ts-31-102] 3GPP TS 31.102: Characteristics of the Universal Subscriber Identity Module (USIM) application https://www.3gpp.org/DynaReport/31102.htm
-
[3gpp-ts-31-103] 3GPP TS 31.103: Characteristics of the IMS Subscriber Identity Module (ISIM) application https://www.3gpp.org/DynaReport/31103.htm
-
[3gpp-ts-31-111] 3GPP TS 31.111: Universal Subscriber Identity Module (USIM) Application Toolkit (USAT) https://www.3gpp.org/DynaReport/31111.htm
-
[3gpp-ts-31-115] 3GPP TS 31.115: Secured packet structure for (Universal) Subscriber Identity Module (U)SIM Toolkit applications https://www.3gpp.org/DynaReport/31115.htm
-
[3gpp-ts-31-116] 3GPP TS 31.116: Remote APDU Structure for (U)SIM Toolkit applications https://www.3gpp.org/DynaReport/31116.htm
-
[3gpp-ts-35-205] 3GPP TS 35.205: 3G Security; Specification of the MILENAGE algorithm set: General
-
[3gpp-ts-35-206] 3GPP TS 35.206: 3G Security; Specification of the MILENAGE algorithm set: Algorithm specification https://www.3gpp.org/DynaReport/35206.htm
-
[3gpp-ts-44-006] 3GPP TS 44.006: Mobile Station - Base Station System (MS - BSS) interface; Data Link (DL) layer specification https://www.3gpp.org/DynaReport/44006.htm
-
[3gpp-ts-44-018] 3GPP TS 44.018: Mobile radio interface layer 3 specification; Radio Resource Control (RRC) protocol https://www.3gpp.org/DynaReport/44018.htm
-
[3gpp-ts-44-064] 3GPP TS 44.064: Mobile Station - Serving GPRS Support Node (MS-SGSN); Logical Link Control (LLC) Layer Specification https://www.3gpp.org/DynaReport/44064.htm
-
[3gpp-ts-45-002] 3GPP TS 45.002: Digital cellular telecommunications system (Phase 2+) (GSM); GSM/EDGE Multiplexing and multiple access on the radio path https://www.3gpp.org/DynaReport/45002.htm
-
[3gpp-ts-48-008] 3GPP TS 48.008: Mobile Switching Centre - Base Station system (MSC-BSS) interface; Layer 3 specification https://www.3gpp.org/DynaReport/48008.htm
-
[3gpp-ts-48-016] 3GPP TS 48.016: General Packet Radio Service (GPRS); Base Station System (BSS) - Serving GPRS Support Node (SGSN) interface; Network service https://www.3gpp.org/DynaReport/48016.htm
-
[3gpp-ts-48-018] 3GPP TS 48.018: General Packet Radio Service (GPRS); Base Station System (BSS) - Serving GPRS Support Node (SGSN); BSS GPRS protocol (BSSGP) https://www.3gpp.org/DynaReport/48018.htm
-
[3gpp-ts-48-049] 3GPP TS 48.049: Digital cellular communications system; Base Station Controller - Cell Broadcast Centre (BSC-CBC) interface specification; Cell Broadcast Service Protocol (CBSP) https://www.3gpp.org/DynaReport/48049.htm
-
[3gpp-ts-48-056] 3GPP TS 48.056: Base Station Controller - Base Transceiver Station (BSC - BTS) interface; Layer 2 specification https://www.3gpp.org/DynaReport/48056.htm
-
[3gpp-ts-48-058] 3GPP TS 48.058: Base Station Controller - Base Transceiver Station (BSC - BTS) Interface; Layer 3 specification https://www.3gpp.org/DynaReport/48058.htm
-
[3gpp-ts-51-011] 3GPP TS 51.011: Specification of the Subscriber Identity Module - Mobile Equipment (SIM-ME) interface
-
[3gpp-ts-51-014] 3GPP TS 51.014: Specification of the SIM Application Toolkit for the Subscriber Identity Module - Mobile Equipment (SIM - ME) interface https://www.3gpp.org/DynaReport/51014.htm
-
[3gpp-ts-52-021] 3GPP TS 52.021: Network Management (NM) procedures and messages on the A-bis interface https://www.3gpp.org/DynaReport/52021.htm
-
[etsi-tr102216] ETSI TR 102 216: Smart cards https://www.etsi.org/deliver/etsi_tr/102200_102299/102216/03.00.00_60/tr_102216v030000p.pdf
-
[etsi-ts102221] ETSI TS 102 221: Smart Cards; UICC-Terminal interface; Physical and logical characteristics https://www.etsi.org/deliver/etsi_ts/102200_102299/102221/13.01.00_60/ts_102221v130100p.pdf
-
[etsi-ts101220] ETSI TS 101 220: Smart Cards; ETSI numbering system for telecommunication application providers https://www.etsi.org/deliver/etsi_ts/101200_101299/101220/12.00.00_60/ts_101220v120000p.pdf
-
[ieee-802.1q] IEEE 802.1Q: Bridges and Bridged Networks https://ieeexplore.ieee.org/document/6991462
-
[ietf-rfc768] IETF RFC 768: User Datagram Protocol https://tools.ietf.org/html/rfc768
-
[ietf-rfc791] IETF RFC 791: Internet Protocol https://tools.ietf.org/html/rfc791
-
[ietf-rfc793] IETF RFC 793: Transmission Control Protocol https://tools.ietf.org/html/rfc793
-
[ietf-rfc1035] IETF RFC 1035: Domain Names - Implementation and Specification https://tools.ietf.org/html/rfc1035
-
[ietf-rfc1350] IETF RFC 1350: Trivial File Transfer Protool https://tools.ietf.org/html/rfc1350
-
[ietf-rfc2131] IETF RFC 2131: Dynamic Host Configuration Protocol https://tools.ietf.org/html/rfc2131
-
[ietf-rfc2474] IETF RFC 2474: Definition of the Differentiated Services Field (DS Field) in the IPv44 and IPv6 Headers https://tools.ietf.org/html/rfc2474
-
[ietf-rfc2719] IETF RFC 2719: Signal Transport over IP https://tools.ietf.org/html/rfc2719
-
[ietf-rfc3331] IETF RFC 3331: Message Transfer Part 2 User Adaptation Layer https://tools.ietf.org/html/rfc3331
-
[ietf-rfc3550] IETF RFC 3550: RTP: A Transport protocol for Real-Time Applications https://tools.ietf.org/html/rfc3550
-
[ietf-rfc3596] IETF RFC 3596: DNS Extensions to Support IP Version 6 https://tools.ietf.org/html/rfc3596
-
[ietf-rfc3868] IETF RFC 3868: SCCP User Adaptation Layer https://tools.ietf.org/html/rfc3868
-
[ietf-rfc4165] IETF RFC 4165: Message Transfer Part 2 Peer-to-Peeer Adaptation Layer https://tools.ietf.org/html/rfc4165
-
[ietf-rfc4251] IETF RFC 4251: The Secure Shell (SSH) Protocol Architecture https://tools.ietf.org/html/rfc4251
-
[ietf-rfc4666] IETF RFC 4666: Message Transfer Part 3 User Adaptation Layer https://tools.ietf.org/html/rfc4666
-
[ietf-rfc5771] IETF RFC 5771: IANA Guidelines for IPv4 Multicast Address Assignments https://tools.ietf.org/html/rfc5771
-
[itu-t-q701] ITU-T Q.701: Functional Description of the Message Transfer Part (MTP) https://www.itu.int/rec/T-REC-Q.701/en/
-
[itu-t-q711] ITU-T Q.711: Functional Description of the Signalling Connection Control Part https://www.itu.int/rec/T-REC-Q.711/en/
-
[itu-t-q713] ITU-T Q.713: Signalling connection control part formats and codes https://www.itu.int/rec/T-REC-Q.713/en/
-
[itu-t-q714] ITU-T Q.714: Signalling connection control part procedures https://www.itu.int/rec/T-REC-Q.714/en/
-
[itu-t-q921] ITU-T Q.921: ISDN user-network interface - Data link layer specification https://www.itu.int/rec/T-REC-Q.921/en
-
[smpp-34] SMPP Develoepers Forum. Short Message Peer-to-Peer Protocol Specification v3.4 https://docs.nimta.com/SMPP_v3_4_Issue1_2.pdf
-
[gnu-agplv3] Free Software Foundation. GNU Affero General Public License. https://www.gnu.org/licenses/agpl-3.0.en.html
-
[freeswitch_pbx] FreeSWITCH SIP PBX https://freeswitch.org
Glossary
- 2FF
-
2nd Generation Form Factor; the so-called plug-in SIM form factor
- 3FF
-
3rd Generation Form Factor; the so-called microSIM form factor
- 3GPP
-
3rd Generation Partnership Project
- 4FF
-
4th Generation Form Factor; the so-called nanoSIM form factor
- A Interface
-
Interface between BTS and BSC, traditionally over E1 (3GPP TS 48.008 [3gpp-ts-48-008])
- A3/A8
-
Algorithm 3 and 8; Authentication and key generation algorithm in GSM and GPRS, typically COMP128v1/v2/v3 or MILENAGE are typically used
- A5
-
Algorithm 5; Air-interface encryption of GSM; currently only A5/0 (no encryption), A5/1 and A5/3 are in use
- Abis Interface
-
Interface between BTS and BSC, traditionally over E1 (3GPP TS 48.058 [3gpp-ts-48-058] and 3GPP TS 52.021 [3gpp-ts-52-021])
- ACC
-
Access Control Class; every BTS broadcasts a bit-mask of permitted ACC, and only subscribers with a SIM of matching ACC are permitted to use that BTS
- AGCH
-
Access Grant Channel on Um interface; used to assign a dedicated channel in response to RACH request
- AGPL
-
GNU Affero General Public License, a copyleft-style Free Software License
- AQPSK
-
Adaptive QPSK, a modulation scheme used by VAMOS channels on Downlink
- ARFCN
-
Absolute Radio Frequency Channel Number; specifies a tuple of uplink and downlink frequencies
- AUC
-
Authentication Center; central database of authentication key material for each subscriber
- BCCH
-
Broadcast Control Channel on Um interface; used to broadcast information about Cell and its neighbors
- BCC
-
Base Station Color Code; short identifier of BTS, lower part of BSIC
- BTS
-
Base Transceiver Station
- BSC
-
Base Station Controller
- BSIC
-
Base Station Identity Code; 16bit identifier of BTS within location area
- BSSGP
-
Base Station Subsystem Gateway Protocol (3GPP TS 48.018 [3gpp-ts-48-018])
- BVCI
-
BSSGP Virtual Circuit Identifier
- CBC
-
Cell Broadcast Centre; central entity of Cell Broadcast service
- CBCH
-
Cell Broadcast Channel; used to transmit Cell Broadcast SMS (SMS-CB)
- CBS
-
Cell Broadcast Service
- CBSP
-
Cell Broadcast Service Protocol (3GPP TS 48.049 [3gpp-ts-48-049])
- CC
-
Call Control; Part of the GSM Layer 3 Protocol
- CCCH
-
Common Control Channel on Um interface; consists of RACH (uplink), BCCH, PCH, AGCH (all downlink)
- Cell
-
A cell in a cellular network, served by a BTS
- CEPT
-
Conférence européenne des administrations des postes et des télécommunications; European Conference of Postal and Telecommunications Administrations.
- CGI
-
Cell Global Identifier comprised of MCC, MNC, LAC and BSIC
- CSFB
-
Circiut-Switched Fall Back; Mechanism for switching from LTE/EUTRAN to UTRAN/GERAN when circuit-switched services such as voice telephony are required.
- dB
-
deci-Bel; relative logarithmic unit
- dBm
-
deci-Bel (milliwatt); unit of measurement for signal strength of radio signals
- DHCP
-
Dynamic Host Configuration Protocol (IETF RFC 2131 [ietf-rfc2131])
- downlink
-
Direction of messages / signals from the network core towards the mobile phone
- DSCP
-
Differentiated Services Code Point (IETF RFC 2474 [ietf-rfc2474])
- DSP
-
Digital Signal Processor
- dvnixload
-
Tool to program UBL and the Bootloader on a sysmoBTS
- EDGE
-
Enhanced Data rates for GPRS Evolution; Higher-speed improvement of GPRS; introduces 8PSK
- EGPRS
-
Enhanced GPRS; the part of EDGE relating to GPRS services
- EIR
-
Equipment Identity Register; core network element that stores and manages IMEI numbers
- ESME
-
External SMS Entity; an external application interfacing with a SMSC over SMPP
- ETSI
-
European Telecommunications Standardization Institute
- FPGA
-
Field Programmable Gate Array; programmable digital logic hardware
- Gb
-
Interface between PCU and SGSN in GPRS/EDGE network; uses NS, BSSGP, LLC
- GERAN
-
GPRS/EDGE Radio Access Network
- GFDL
-
GNU Free Documentation License; a copyleft-style Documentation License
- GGSN
-
GPRS Gateway Support Node; gateway between GPRS and external (IP) network
- GMSK
-
Gaussian Minimum Shift Keying; modulation used for GSM and GPRS
- GPL
-
GNU General Public License, a copyleft-style Free Software License
- Gp
-
Gp interface between SGSN and GGSN; uses GTP protocol
- GPRS
-
General Packet Radio Service; the packet switched 2G technology
- GPS
-
Global Positioning System; provides a highly accurate clock reference besides the global position
- GSM
-
Global System for Mobile Communications. ETSI/3GPP Standard of a 2G digital cellular network
- GSMTAP
-
GSM tap; pseudo standard for encapsulating GSM protocol layers over UDP/IP for analysis
- GSUP
-
Generic Subscriber Update Protocol. Osmocom-specific alternative to TCAP/MAP
- GT
-
Global Title; an address in SCCP
- GTP
-
GPRS Tunnel Protocol; used between SGSN and GGSN
- HLR
-
Home Location Register; central subscriber database of a GSM network
- HNB-GW
-
Home NodeB Gateway. Entity between femtocells (Home NodeB) and CN in 3G/UMTS.
- HPLMN
-
Home PLMN; the network that has issued the subscriber SIM and has his record in HLR
- IE
-
Information Element
- IMEI
-
International Mobile Equipment Identity; unique 14-digit decimal number to globally identify a mobile device, optionally with a 15th checksum digit
- IMEISV
-
IMEI software version; unique 14-digit decimal number to globally identify a mobile device (same as IMEI) plus two software version digits (total digits: 16)
- IMSI
-
International Mobile Subscriber Identity; 15-digit unique identifier for the subscriber/SIM; starts with MCC/MNC of issuing operator
- IP
-
Internet Protocol (IETF RFC 791 [ietf-rfc791])
- IPA
-
ip.access GSM over IP protocol; used to multiplex a single TCP connection
- Iu
-
Interface in 3G/UMTS between RAN and CN
- IuCS
-
Iu interface for circuit-switched domain. Used in 3G/UMTS between RAN and MSC
- IuPS
-
Iu interface for packet-switched domain. Used in 3G/UMTS between RAN and SGSN
- LAC
-
Location Area Code; 16bit identifier of Location Area within network
- LAPD
-
Link Access Protocol, D-Channel (ITU-T Q.921 [itu-t-q921])
- LAPDm
-
Link Access Protocol Mobile (3GPP TS 44.006 [3gpp-ts-44-006])
- LLC
-
Logical Link Control; GPRS protocol between MS and SGSN (3GPP TS 44.064 [3gpp-ts-44-064])
- Location Area
-
Location Area; a geographic area containing multiple BTS
- LU
-
Location Updating; can be of type IMSI-Attach or Periodic. Procedure that indicates a subscriber’s physical presence in a given radio cell.
- M2PA
-
MTP2 Peer-to-Peer Adaptation; a SIGTRAN Variant (RFC 4165 [ietf-rfc4165])
- M2UA
-
MTP2 User Adaptation; a SIGTRAN Variant (RFC 3331 [ietf-rfc3331])
- M3UA
-
MTP3 User Adaptation; a SIGTRAN Variant (RFC 4666 [ietf-rfc4666])
- MCC
-
Mobile Country Code; unique identifier of a country, e.g. 262 for Germany
- MFF
-
Machine-to-Machine Form Factor; a SIM chip package that is soldered permanently onto M2M device circuit boards.
- MGW
-
Media Gateway
- MM
-
Mobility Management; part of the GSM Layer 3 Protocol
- MNC
-
Mobile Network Code; identifies network within a country; assigned by national regulator
- MNCC
-
Mobile Network Call Control; Unix domain socket based Interface between MSC and external call control entity like osmo-sip-connector
- MNO
-
Mobile Network Operator; operator with physical radio network under his MCC/MNC
- MO
-
Mobile Originated. Direction from Mobile (MS/UE) to Network
- MS
-
Mobile Station; a mobile phone / GSM Modem
- MSC
-
Mobile Switching Center; network element in the circuit-switched core network
- MSC pool
-
A number of redundant MSCs serving the same core network, which a BSC / RNC distributes load across; see also the "MSC Pooling" chapter in OsmoBSC’s user manual [userman-osmobsc] and 3GPP TS 23.236 [3gpp-ts-23-236]
- MSISDN
-
Mobile Subscriber ISDN Number; telephone number of the subscriber
- MT
-
Mobile Terminated. Direction from Network to Mobile (MS/UE)
- MTP
-
Message Transfer Part; SS7 signaling protocol (ITU-T Q.701 [itu-t-q701])
- MVNO
-
Mobile Virtual Network Operator; Operator without physical radio network
- NCC
-
Network Color Code; assigned by national regulator
- NITB
-
Network In The Box; combines functionality traditionally provided by BSC, MSC, VLR, HLR, SMSC functions; see OsmoNITB
- NRI
-
Network Resource Indicator, typically 10 bits of a TMSI indicating which MSC of an MSC pool attached the subscriber; see also the "MSC Pooling" chapter in OsmoBSC’s user manual [userman-osmobsc] and 3GPP TS 23.236 [3gpp-ts-23-236]
- NSEI
-
NS Entity Identifier
- NVCI
-
NS Virtual Circuit Identifier
- NWL
-
Network Listen; ability of some BTS to receive downlink from other BTSs
- NS
-
Network Service; protocol on Gb interface (3GPP TS 48.016 [3gpp-ts-48-016])
- OCXO
-
Oven Controlled Crystal Oscillator; very high precision oscillator, superior to a VCTCXO
- OML
-
Operation & Maintenance Link (ETSI/3GPP TS 52.021 [3gpp-ts-52-021])
- OpenBSC
-
Open Source implementation of GSM network elements, specifically OsmoBSC, OsmoNITB, OsmoSGSN
- OpenGGSN
-
Open Source implementation of a GPRS Packet Control Unit
- OpenVPN
-
Open-Source Virtual Private Network; software employed to establish encrypted private networks over untrusted public networks
- Osmocom
-
Open Source MObile COMmunications; collaborative community for implementing communications protocols and systems, including GSM, GPRS, TETRA, DECT, GMR and others
- OsmoBSC
-
Open Source implementation of a GSM Base Station Controller
- OsmoNITB
-
Open Source implementation of a GSM Network In The Box, combines functionality traditionally provided by BSC, MSC, VLR, HLR, AUC, SMSC
- OsmoSGSN
-
Open Source implementation of a Serving GPRS Support Node
- OsmoPCU
-
Open Source implementation of a GPRS Packet Control Unit
- OTA
-
Over-The-Air; Capability of operators to remotely reconfigure/reprogram ISM/USIM cards
- PC
-
Point Code; an address in MTP
- PCH
-
Paging Channel on downlink Um interface; used by network to page an MS
- PCP
-
Priority Code Point (IEEE 802.1Q [ieee-802.11])
- PCU
-
Packet Control Unit; used to manage Layer 2 of the GPRS radio interface
- PDCH
-
Packet Data Channel on Um interface; used for GPRS/EDGE signalling + user data
- PIN
-
Personal Identification Number; a number by which the user authenticates to a SIM/USIM or other smart card
- PLMN
-
Public Land Mobile Network; specification language for a single GSM network
- PUK
-
PIN Unblocking Code; used to unblock a blocked PIN (after too many wrong PIN attempts)
- RAC
-
Routing Area Code; 16bit identifier for a Routing Area within a Location Area
- RACH
-
Random Access Channel on uplink Um interface; used by MS to request establishment of a dedicated channel
- RAM
-
Remote Application Management; Ability to remotely manage (install, remove) Java Applications on SIM/USIM Card
- RF
-
Radio Frequency
- RFM
-
Remote File Management; Ability to remotely manage (write, read) files on a SIM/USIM card
- Roaming
-
Procedure in which a subscriber of one network is using the radio network of another network, often in different countries; in some countries national roaming exists
- Routing Area
-
Routing Area; GPRS specific sub-division of Location Area
- RR
-
Radio Resources; Part of the GSM Layer 3 Protocol
- RSL
-
Radio Signalling Link (3GPP TS 48.058 [3gpp-ts-48-058])
- RTP
-
Real-Time Transport Protocol (IETF RFC 3550 [ietf-rfc3550]); Used to transport audio/video streams over UDP/IP
- SACCH
-
Slow Associate Control Channel on Um interface; bundled to a TCH or SDCCH, used for signalling in parallel to active dedicated channel
- SCCP
-
Signaling Connection Control Part; SS7 signaling protocol (ITU-T Q.711 [itu-t-q711])
- SDCCH
-
Slow Dedicated Control Channel on Um interface; used for signalling and SMS transport in GSM
- SDK
-
Software Development Kit
- SGs
-
Interface between MSC (GSM/UMTS) and MME (LTE/EPC) to facilitate CSFB and SMS.
- SGSN
-
Serving GPRS Support Node; Core network element for packet-switched services in GSM and UMTS.
- SIGTRAN
-
Signaling Transport over IP (IETF RFC 2719 [ietf-rfc2719])
- SIM
-
Subscriber Identity Module; small chip card storing subscriber identity
- Site
-
A site is a location where one or more BTSs are installed, typically three BTSs for three sectors
- SMPP
-
Short Message Peer-to-Peer; TCP based protocol to interface external entities with an SMSC
- SMSC
-
Short Message Service Center; store-and-forward relay for short messages
- SS7
-
Signaling System No. 7; Classic digital telephony signaling system
- SS
-
Supplementary Services; query and set various service parameters between subscriber and core network (e.g. USSD, 3rd-party calls, hold/retrieve, advice-of-charge, call deflection)
- SSH
-
Secure Shell; IETF RFC 4250 [ietf-rfc4251] to 4254
- SSN
-
Sub-System Number; identifies a given SCCP Service such as MSC, HLR
- STP
-
Signaling Transfer Point; A Router in SS7 Networks
- SUA
-
SCCP User Adaptation; a SIGTRAN Variant (RFC 3868 [ietf-rfc3868])
- syslog
-
System logging service of UNIX-like operating systems
- System Information
-
A set of downlink messages on the BCCH and SACCH of the Um interface describing properties of the cell and network
- TCH
-
Traffic Channel; used for circuit-switched user traffic (mostly voice) in GSM
- TCP
-
Transmission Control Protocol; (IETF RFC 793 [ietf-rfc793])
- TFTP
-
Trivial File Transfer Protocol; (IETF RFC 1350 [ietf-rfc1350])
- TOS
-
Type Of Service; bit-field in IPv4 header, now re-used as DSCP (IETF RFC 791 [ietf-rfc791])
- TRX
-
Transceiver; element of a BTS serving a single carrier
- TS
-
Technical Specification
- u-Boot
-
Boot loader used in various embedded systems
- UBI
-
An MTD wear leveling system to deal with NAND flash in Linux
- UBL
-
Initial bootloader loaded by the TI Davinci SoC
- UDP
-
User Datagram Protocol (IETF RFC 768 [ietf-rfc768])
- UICC
-
Universal Integrated Chip Card; A smart card according to ETSI TR 102 216 [etsi-tr102216]
- Um interface
-
U mobile; Radio interface between MS and BTS
- uplink
-
Direction of messages: Signals from the mobile phone towards the network
- USIM
-
Universal Subscriber Identity Module; application running on a UICC to provide subscriber identity for UMTS and GSM networks
- USSD
-
Unstructured Supplementary Service Data; textual dialog between subscriber and core network, e.g. *100 → Your extension is 1234
- VAMOS
-
Voice services over Adaptive Multi-user channels on One Slot; an optional extension for GSM specified in Release 9 of 3GPP GERAN specifications (3GPP TS 48.018 [3gpp-ts-48-018]) allowing two independent UEs to transmit and receive simultaneously on traffic channels
- VCTCXO
-
Voltage Controlled, Temperature Compensated Crystal Oscillator; a precision oscillator, superior to a classic crystal oscillator, but inferior to an OCXO
- VLAN
-
Virtual LAN in the context of Ethernet (IEEE 802.1Q [ieee-802.1q])
- VLR
-
Visitor Location Register; volatile storage of attached subscribers in the MSC
- VPLMN
-
Visited PLMN; the network in which the subscriber is currently registered; may differ from HPLMN when on roaming
- VTY
-
Virtual TeletYpe; a textual command-line interface for configuration and introspection, e.g. the OsmoBSC configuration file as well as its telnet link on port 4242
Appendix A. GNU Free Documentation License
Version 1.3, 3 November 2008
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. http://fsf.org/
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
PREAMBLE
The purpose of this License is to make a manual, textbook, or other functional and useful document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a [secondary-section] may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain [secondary-section] whose titles are designated, as being those of [invariant-sections], in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero [invariant-sections]. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise [transparent] file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not [transparent]. An image format is not [transparent] if used for any substantial amount of text. A copy that is not [transparent] is called “Opaque”.
Examples of suitable formats for [transparent] copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, [title-page] means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section [licenses-gfdl-section-4].
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires [cover-texts], you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-[cover-texts] on the front cover, and Back-[cover-texts] on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable [transparent] copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete [transparent] copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this [transparent] copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
MODIFICATIONS
You may copy and distribute a [modified-version] of the Document under the conditions of sections 2 and 3 above, provided that you release the [modified-version] under precisely this License, with the [modified-version] filling the role of the Document, thus licensing distribution and modification of the [modified-version] to whoever possesses a copy of it. In addition, you must do these things in the [modified-version]:
-
Use in the [title-page] (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
-
List on the [title-page], as authors, one or more persons or entities responsible for authorship of the modifications in the [modified-version], together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
-
State on the [title-page] the name of the publisher of the [modified-version], as the publisher.
-
Preserve all the copyright notices of the Document.
-
Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
-
Include, immediately after the copyright notices, a license notice giving the public permission to use the [modified-version] under the terms of this License, in the form shown in the Addendum below.
-
Preserve in that license notice the full lists of [invariant-sections] and required [cover-texts] given in the Document’s license notice.
-
Include an unaltered copy of this License.
-
Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the [modified-version] as given on the [title-page]. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its [title-page], then add an item describing the [modified-version] as stated in the previous sentence.
-
Preserve the network location, if any, given in the Document for public access to a [transparent] copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
-
For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
-
Preserve all the [invariant-sections] of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
-
Delete any section Entitled “Endorsements”. Such a section may not be included in the [modified-version].
-
Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any [invariant-sections].
-
Preserve any Warranty Disclaimers.
If the [modified-version] includes new front-matter sections or appendices that qualify as [secondary-section] and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of [invariant-sections] in the [modified-version]'s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your [modified-version] by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of [cover-texts] in the [modified-version]. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any [modified-version].
COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the [invariant-sections] of all of the original documents, unmodified, and list them all as [invariant-sections] of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical [invariant-sections] may be replaced with a single copy. If there are multiple [invariant-sections] with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of [invariant-sections] in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements”.
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s [cover-texts] may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing [invariant-sections] with translations requires special permission from their copyright holders, but you may include translations of some or all [invariant-sections] in addition to the original versions of these [invariant-sections]. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
RELICENSING
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (c) YEAR YOUR NAME.
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''.
If you have [invariant-sections], Front-[cover-texts] and Back-[cover-texts], replace the “with…Texts.” line with this:
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have [invariant-sections] without [cover-texts], or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.