- Getting Started with 3G
- Build Core Network Programs
- Configure Core Network
- Femto Config
- Subscriber Configuration
- APN for Data Service
- Further Links
- Tips and Facts
Getting Started with 3G¶
This reflects the state of Osmocom 3G development on 2017-05-14
If you have your 3G femto cell1, this is how to get started:
The physical setup is:
_____________ _____________ | | | | | femto |<--Ethernet-->| Laptop/PC | |___________| |___________|
On the protocol layer, the femto cell is the hNodeB and talks to various core
network elements over the ethernet cable, typically all located on your
computer, and talks to the phone (UE) over the air:
+--------+ ,-->| Osmo | / | MGCPGW | | | |<--MGCP | +--------+ \ / | +------------+<--RTP +--------+ `->+----------+ UE <-->| hNodeB | | Osmo | | OsmoMSC | +------+ UE <-->| |<--Iuh---->| HNB-GW |<--IuCS-->| | | Osmo | | | | | | (VLR)|<-GSUP->| HLR | | | | | +----------+ GSUP->+------+ +------------+<--GTP-U | | / \ | | +------+<---' +------+ | | |<--IuPS-->| Osmo |<--GTP-C--->| Open | | +--------+ | SGSN | GTP-U--->| GGSN | | +------+ / +------+ \_______________________________/
Build Core Network Programs¶
To get your 3G core network up and running, you need to manually build specific
branches from various Osmocom projects.
The 3G-config-example.tar contains a script to clone and build -- refer to the README.txt
enclosed in the tar.
In detail, this is what needs to be built:
- libosmocore: master
- libosmo-abis: master
- libosmo-netif: master
- libosmo-sccp: old_sua (tag)
- libsmpp34: master
- libasn1c: master
- osmo-iuh: old_sua (tag)
- openggsn: master
- openbsc: vlr_3G
- osmo-hlr: master
(In the unlikely case the asn.1 definitions changed, you also need asn1c, branch aper-prefix-onto-upstream)
The git command to get onto a branch other than 'master' is:
git checkout the_branch_name
See Build from Source on build instructions
(remember to pass --enable-iu for openbsc's ./configure step).
Configure Core Network¶
Once the CN stack is built, set up the configuration and launch the core
network components. Find further below example configuration files and a run
script that may help to get you started. Here are 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-msc and osmo-sgsn default to 127.0.0.1 and
127.0.0.2, respectively, i.e. it's easiest to run osmo-msc and osmo-sgsn on
the same machine as the osmo-hnbgw. These will listen on the proper port
(14001) without further configuration.
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-msc process. The
osmo-msc.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 use, the SGSN may not bind on the same IP address as the GGSN!
Typically this requires to add another IP address to your ethernet interface.
On linux this is achieved, for example, by:
sudo ip addr add 10.9.1.13/32 dev eth0
The above adds the address 10.9.1.13 to eth0, which works e.g. when your
machine is in a 10.9.1.0/24 net and the address 10.9.1.13 is not yet taken by
Also, IP forwarding and masquerading must be enabled for your GGSN to be able
to connect to your mobile phones to the internet uplink. On linux, that can be
done for eth0 by:
sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward" sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
You may need a different interface, possibly a wildcard like 'eth*'.
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
export LD_LIBRARY_PATH=/usr/local/lib. With sudo that would be
sudo, and you may need to add "SETENV" to
LD_LIBRARY_PATH=/usr/local/lib ggsn ...
your sudoers config -- see the sudo documentation.
Once you have configured the IP addresses, start up your core network: launch
osmo-msc, osmo-bsc_mgcp, osmo-sgsn, ggsn and osmo-hnbgw. You should see log
messages indicating established IuCS and IuPS links (HNBGW, MSC and SGSN).
Core Network Configuration Example¶
Here is a specific 3G core network configuration example, including a highly
specialized launcher script that configures the network (on a linux system) and
runs all the programs needed for a 3G core network -- but be aware:
- Make sure all IP addresses in the config files match your actual ones.
- The ggsn.conf 'listen' address is the additional interface (ala 'ip addr
add' above) and needs to match whichever address you picked there.
- Make sure the MCC and MNC match the ones configured in the femto cell.
- The current mgcp.cfg allows any base station to take up a call's RTP stream.
To limit to your specific femto cell address, set it as 'bts ip' in the mgcp.cfg.
- See also the README.txt enclosed in the tar.
- It assumes the Osmocom libs and programs to be installed in /usr/local/*.
- It launches each component in a separate X terminal.
- It uses rxvt-unicode, you may want to change the
urxvtcall to your favorite xterm instead.
- Make sure the ethernet interface makes sense.
- Make sure the IP address makes sense.
- Run it in a directory where it will find the various configuration files.
- The GGSN needs to run with root privileges to be able to create a tun device for data services. The startup will ask you for your password because it is launched by sudo. See also "Tips" below to make this non-interactive.
- Once you hit Enter in the original terminal where you started, all the other
terminals will be torn down in one fell swoop (hopefully).
Now that you've taken notice of the points above, here are the config and
With your CN up and running, configure the hNodeB to contact osmo-hnbgw via
Iuh. Also make sure the PLMN ID matches the MCC and MNC in the osmo-msc.cfg --
otherwise the hNodeB may reject all attach requests.
Depending on your femto cell, the steps to configure it will be radically
For your phone loaded with your USIM to be able to subscribe to your network, the IMSI needs to be authorized to enter and the authentication keys need to be added to the HLR.
Configure your femto cell to authorize your IMSIs, refer to your specific model's configuration documentation.
Once off, the HLR database needs to be created using the file
sqlite3 hlr.db < osmo-hlr/sql/hlr.sql
This hlr.db needs to be found by the osmo-hlr binary -- either place it in the current working directory when launching osmo-hlr, or use the
osmo-hlr -l my/hlr.db commandline option to pass a specific path.
$ sqlite3 hlr.db sqlite> insert into subscriber (imsi, msisdn) values ('901700000099999', '999'); sqlite> select id, imsi from subscriber; 2342|901700000099999 sqlite> insert into auc_3g (subscriber_id, algo_id_3g, k, opc) values (2342, 5, '0102030405060708090a0b0c0d0e0f00', 'f0e0d0c0b0a090807060504030201000');
The numbers (except '5') are freely chosen and will all differ for you:
- 901700000099999: IMSI of your USIM.
- 999: MSISDN, i.e. the subscriber's telephone number. Your choice.
- 2342: the automatically created subscriber id, probably 1 for you.
- 5: use Milenage. see enum osmo_auth_algo in libosmocore's crypt/auth.h
- '0102030405060708090a0b0c0d0e0f00': KI, you got it with your USIM
- 'f0e0d0c0b0a090807060504030201000': OPC, you got it with your USIM
APN for Data Service¶
For the 3G data service to work, 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:
- '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.
The "3G Voice Works" blog post from 2016 has some explanations:
My phone doesn't register / the MSC sees no messages¶
Make sure that you start the OsmoHNBGW only after the MSC and SGSN have started up and are ready.
Best stop all programs, then first launch in this order:
- osmo-hlr, osmo-bsc_mgcp
- osmo-msc, osmo-sgsn -- give it time to listen for IuCS/IuPS
My phone is rejected¶
- is your hNodeB cell configured for open access or to allow this IMSI?
- do the MCC+MNC configured in the hNodeB match osmo-msc.cfg's "network country code" and "mobile network code"?
- did you enter the subscriber in the HLR database?
- does the subscriber have an auc_3g entry?
- if you got an OPC value for your USIM, is this key entered in the OPC column (vs. the OP column which would not work then)? Or vice versa, did you put the OP key in the OPC column?
- make sure only one of OP or OPC are entered.
I have no phone number¶
If dialling '*#100#' returns a message lacking a phone number ("Your extension is "), then add an MSISDN in the hlr.db's subscriber table.
Voice calls don't go through¶
Does the MGCP gateway (aka osmo-bsc_mgcp) have your hNodeB's IP address configured as "mgcp" / "bts ip"?
Phone is registered, but is usually not receiving any SMS / voice calls¶
In open access mode, it seems the nano3G sometimes fails to page a phone -- it looks like it didn't store the subscriber's IMSI. Try to register the phone that should receive a call to a different network (being rejected suffices, just to get the TMSI out of the phone's state) and then re-register to the hNodeB.
Data service is not working¶
Try to go to flight mode and back online...
Tips and Facts¶
Analyzing RTP streams in wireshark¶
IuCS actually uses UP over RTP. See 3GPP TS 25.414, and 25.415 6.6.2.
(an interesting insight is https://www.ietf.org/mail-archive/web/avt/current/msg05907.html )
In the wireshark preferences, go to protocol IuUP, enable it and enter the dynamic protocol
number that you see in the RTP frames (e.g. 96).
Launch GGSN with root priviliges¶
The GGSN needs to run with root privileges. This means you need to type your password when starting it for sudo to work. But sudo also allows you to put rules in place to make this password-less:
echo "$USER ALL= NOPASSWD:SETENV: /usr/local/bin/ggsn *" > ~/ggsn_sudoers chmod go-w ~/ggsn_sudoers sudo chown root: ~/ggsn_sudoers sudo mv ~/ggsn_sudoers /etc/sudoers.d/
This places a NOPASSWD rule in /etc/sudoers.d which should allow you to start the GGSN without issuing a password when invoked via sudo.
If you experience problems you may ask for assistance on our