Osmocom 3G - Getting Started » History » Version 3

« Previous - Version 3/4 (diff) - Next » - Current version
neels, 10/14/2016 11:41 AM

Osmocom 3G - Getting Started

Detailed steps for getting started with the Osmocom 3G core network software,
dependencies, installation and configuration.


For the Osmocom 3G CN to be useful, you need a 3G cell. OsmoHNBGW interfaces
with hNodeB aka femto cells via Iuh, and OsmoCSCN and OsmoSGSN interface to
IuCS and IuPS, respectively, which OsmoHNBGW forwards to them.

For details on obtaining suitable 3G hardware, you can ask at
or on our mailing list.


In order to build the osmocom stack, you need various libraries, most of which
are available as installable packages in the major linux distributions like
Debian, Ubuntu etc.

Each ./configure step below will complain in case of a missing dependency,
and mostly installing a package named like "lib<name>-dev" or very similar will
fix the problem.

The less obvious dependencies from the configure error messages are
libdbd-sqlite3 and libssl-dev (Debian names).

Debian/Ubuntu example:

apt-cache search $name
sudo apt-get install lib${name}-dev

Download 3G Sources

Some of the 3G work is still on non-master branches. These steps clone the
latest 3G code:

git clone git://
git clone git://
git clone git:// -b sysmocom/sctp
git clone git:// -b aper-prefix-onto-upstream
git clone git://
git clone git:// -b sysmocom/iu
git clone git://
git clone git://
git clone git://
git clone git:// -b sysmocom/iu


Installation Target

In case you are not familiar with autoconf/automake installations:

Usually, the default installation target will be in /usr/local/. To be able
to install to it, you can use sudo to install (sudo make install) or you can
make /usr/local/ writable by your user (sudo chown -R $USER: /usr/local).

You can also install to a different location by passing the
--prefix=/path/to/target option, in which case you need to make sure that
PKG_CONFIG_PATH is set while building and LD_LIBRARY_PATH is set while running
the built binaries as well as the make check steps. For example:

cd libosmocore
autoreconf -fi
./configure --prefix=/my/target
make install
export PKG_CONFIG_PATH=/my/target/lib/pkgconfig
export LD_LIBRARY_PATH=/my/target/lib other libs... binaries...

Faster Build

To make use of multiple CPU cores during build, pass the -j option to make:

make -j 8 check

Sometimes such a parallel build exhibits problems that go away when running
make again without a -j option. We do try to make all our projects safe for
parallel building.


Above source trees need to be built and installed in the order they appear

For most of the installed source trees, the standard steps are:

autoreconf -fi
make check
make install

The exception is openbsc, which

  • needs to be built in the openbsc subdirectory and
  • needs further ./configure options.

Here are the full steps to build:

# be verbose, abort on error:
set -x -e

for project in \
    libosmocore libosmo-abis libosmo-netif asn1c libasn1c libosmo-sccp \
    openggsn libsmpp34 osmo-iuh
    cd $project
    autoreconf -fi
    make -j8 || make
    #make check  # optional
    make install

    cd ..

cd openbsc/openbsc
autoreconf -fi
./configure --enable-smpp --enable-osmo-bsc --enable-nat --enable-iu
make -j8
make check  # optional
make install

Run an Osmocom 3G Core Network

                             ,-->| MGCPGW |<--RTP--...
                            /    |        |
                            |    |        |<--MGCP
                            |    +--------+       \
                            /                     |
        +------------+<--RTP     +--------+       `->+----------+
 UE <-->| hNodeB     |           | HNB-GW |          | OsmoCSCN |
 UE <-->|            |<--Iuh---->|        |<--IuCS-->|          |
        |            |     ...-->|        |    ...-->|          |
        |            |           |        |          +----------+
        +------------+<--GTP-U   |        |
                              \  |        |          +------+           +------+
                              |  |        |<--IuPS-->| SGSN |<--GTP-C-->| GGSN |
                              |  +--------+    ...-->|      |   GTP-U-->|      |
                              |                      +------+  /        +------+

The CN comprises of

  • OsmoHNBGW to forward Iuh,
  • OsmoCSCN for voice signalling,
  • OsmoMGCPGW to direct RTP streams,
  • OsmoSGSN and
  • OpenGGSN for data connectivity.

In short, Iuh is the combined voice (IuCS, Iu circuit switched) and data (IuPS,
Iu packet switched) signalling, which the HNB-GW splits to OsmoCSCN (circuit
switched core network) and OsmoSGSN. When a phone (UE, user equipment) starts a
call, OsmoCSCN takes care of all the signalling, from authentication to RAB
assignment, and instructs the MGCPGW to forward the RTP streams from the
hNodeB, in our case, back to the same hNodeB and to the other UE. In the field,
the MGCPGW would instead forward to a remote media gateway.

Configuration Files

Each of the programs has a configuration file, which need to be adjusted to
your local network topology. Here is an example configuration -- the IP
addresses used are described in the enclosed README.txt.

Some details explained:

Tell the osmo-hnbgw which local IP address to use to listen for Iuh
connections. This needs to be on an interface reachable by the hNodeB. The
IuCS and IuPS links towards the osmo-cscn and osmo-sgsn are at the time of
writing still hardcoded1 as and, respectively, i.e.
osmo-cscn and osmo-sgsn should run on the same machine as the osmo-hnbgw. These
will listen on the proper port without further configuration (still hardcoded).

Also tell the MGCPGW (osmo-bsc_mgcp) which local IP address to bind to, which
has to be reachable both by the hNodeB as well as the osmo-cscn process. The
osmo-cscn.cfg is then told where to reach the MGCPGW.

A notable detail for 3G data is that the GGSN has to be reachable by the hNodeB.
Since the GTP standard defines fixed port numbers which both SGSN and GGSN have
to to use, the SGSN may not bind on the same IP address as the GGSN.

Once you have configured the IP addresses, start up your core network: launch
osmo-cscn, osmo-bsc_mgcp, osmo-sgsn, ggsn and osmo-hnbgw. You should see log
messages indicating established IuCS and IuPS links (HNBGW, CSCN and SGSN).

Here are example command lines for each of the programs:

osmo-hnbgw -c osmo-hnbgw.cfg
osmo-cscn -c osmo-cscn.cfg
osmo-sgsn -c osmo-sgsn.cfg
sudo ggsn -f -c ggsn.conf --statedir=$PWD
osmo-bsc_mgcp -c mgcp.cfg

The GGSN needs permissions to create a tun device, which sudo will allow.
It may be safer though to allow your user to create tunnels instead of running
the GGSN as root.

If programs complain about missing library .so files, you will probably need
to export LD_LIBRARY_PATH=/usr/local/lib. With sudo that would be sudo
LD_LIBRARY_PATH=/usr/local/lib ggsn ...
, and you may need to add "SETENV" to
your sudoers config -- see the sudo documentation.

1 but see

Configure the 3G Cell

With your CN up and running, configure the hNodeB to contact osmo-hnbgw. Also
make sure the PLMN ID and LAC are configured correctly, to match the MCC and
MNC in the osmo-cscn.cfg -- otherwise the hNodeB may reject all attach requests.

It may also be necessary to configure your 3G hardware to authorize access by
your SIM card's IMSI.

Provision SIM Cards

At the time of writing, full milenage 3G authentication is not yet integrated
in Osmocom. Our HLR needs to be able to store 3G crypto tokens and
corresponding code needs to be added to OsmoCSCN and OsmoSGSN.

So far, we use SIM cards that are capable of subscribing to 3G networks but
still use 2G crypto tokens, which is in fact legal according to the 3G spec.
This means that the part where the core network authenticates to the phone
(intrinsic to milenage crypto) is skipped, and only the phone authenticates to
the core network as in 2G.

Also, we use a hardcoded security key to allow us to work with 3G until we have
a fully capable HLR ready. The Ki is simply 000102030405060708090a0b0c0d0e0f,
and using pysim and a smartcard reader, this is how to provision a SIM
card with this Ki:

First find out your SIM card's IMSI and ICCID:

./ -p 0

and now use this to program the SIM:

./ -p 0 -k 000102030405060708090a0b0c0d0e0f -i $iccid -s $imsi -t auto

Of course replace $iccid and $imsi, and instead of -t auto you may need
to pick a specific type instead. The pcsc_scan program may help to determine
the type.

If you are in need of SIM cards that can be used with Osmocom 3G, ask

Authorize Subscribers

As usual, you need to register SIM cards' IMSIs in the CN's HLR database.
Probably most convenient is to use the telnet VTY for this. osmo-cscn offers
a telnet VTY, the address and port are logged during program startup.

telnet localhost 4254
OsmoCSCN> enable
OsmoCSCN# subscriber create imsi 987654321098765
    ID: 9, Authorized: 0
    Extension: 48280
    LAC: 0/0x0
    IMSI: 987654321098765
    Expiration Time: Thu, 01 Jan 1970 01:00:00 +0100
    Paging: not paging Requests: 0
    Use count: 1
OsmoCSCN# subscriber imsi 987654321098765 authorized 1
OsmoCSCN# show subscriber imsi 987654321098765
    ID: 9, Authorized: 1
    Extension: 48280
    LAC: 0/0x0
    IMSI: 987654321098765
    Expiration Time: Thu, 01 Jan 1970 01:00:00 +0100
    Paging: not paging Requests: 0
    Use count: 1
OsmoCSCN# exit
Connection closed by foreign host.

APN for Data Service

For the 3G data service to use, phones generally need an APN added to their
configuration, or they will not even attempt to establish a data connection.
For the Osmocom 3G CN, any arbitrary APN name will do.

The APN configuration steps are usually similar to:

  • Navigate to APN settings:
    • 'Settings'
    • 'Wireless & Networks'
    • 'Mobile networks'
    • 'Access Point Names'
  • You should see the list of APNs (possibly empty)
  • Press the Menu button
  • Choose 'New APN'
  • Enter values for 'Name' as well as 'APN'
    • For both, any nonempty value is sufficient, e.g. "test".
  • Again press the Menu button
  • Choose 'Save'
  • The APN should now appear in the list of APNs.
  • Possibly tap the bullet icon to select the APN as default.


If you experience problems you may ask for assistance on our
mailing list.