Virtual Um

In July 2017, the Osmocom project has inroduced a Virtual Um interface (i.e. virtual radio layer) between OsmoBTS and OsmocomBB. This allows us to run a complete GSM network with 1-N BTSs and 1-M MSs without any actual radio hardware, which is of course excellent for all kinds of testing scenarios.

The Virtual Um layer is based on sending L2 frames (blocks) encapsulated via GSMTAP UDP multicast packets. There are two separate multicast groups, one for uplink and one for downlink. The multicast nature simulates the shared medium and enables any simulated phone to receive the signal from multiple BTSs via the downlink multicast group.

In OsmoBTS, this is implemented via the new osmo-bts-virtual BTS model.

In OsmocomBB, this is realized by adding virtphy virtual L1, which speask the same L1CTL protocol that is used between the real OsmcoomBB Layer1 and the Layer2/3 programs such as Mobile and the like.

This page describes how to set up the Virtual Um layer. It assumes that you are famliar with classic operation of OsmocomBB and OsmoBTS and OsmoNITB with a real radio layer. In case of doubt, look at the genric documentation and tutorials for real RF hardware.

The big picture

Using OsmoNITB

Using OsmoBSC, OsmoMSC, OsmoHLR

The BTS side

Setting up OsmoBTS in its osmo-bts-virtual flavor isn't really much different from setting it up with real hardware. The amount of required configuration at the BTS configuration file is (as always) very minimal, as in the GSM network architecture provides almost all relevant configuration to the BTS from the BSC.

An example configuratin file is provided as part of the osmo-bts source code: doc/examples/virtual/osmobts-virtual.cfg (

The only parameters that you must ensure to match your local configuration are:

bts 0
 band DCS1800
 ipa unit-id 6969 0
 oml remote-ip

  • band must match the frequency band of your simulated radio layer
  • ipa unit-id must match what you have configured on the BSC (OsmoBSC or OsmoNITB)
  • oml remote-ip must point to the IP address to which your BSC is listening

You can subsequently start osmo-bts-virtual using the following commands:

$ ./osmo-bts-virtual -c osmo-bts.cfg

whre of course osmo-bts.cfg is the file name (in current directory or with path) of your configuration file, starting from the provided example.

You should get output like this:

 / \ OsmoBTS
<000f> main.c:117 Unimplemneted bts_model_phy_instance_set_defaults
<0017> control_if.c:788 CTRL at 4238
<0006> bts_model.c:175 Unimplemneted bts_model_ctrl_cmds_install
<0010> telnet_interface.c:102 telnet at 4241
<0012> input/ipaccess.c:884 enabling ipaccess BTS mode, OML connecting to
<000d> abis.c:207 Input Signal 4 received
<0006> phy_link.c:58 PHY link state change shutdown -> connecting
<0006> scheduler.c:216 Init scheduler for trx=0
<0007> scheduler_virtbts.c:637 starting VBTS scheduler
<0006> phy_link.c:58 PHY link state change connecting -> connected
<0006> phy_link.c:68 trx_set_avail(1)
<0012> input/ipa.c:129 connection done.
<0012> input/ipaccess.c:705 received ID get
<000d> abis.c:101 OML Signalling link up

followed by the usual OML initialization sequence according to TS 12.21 and finally the RSL initialization:

<0000> rsl.c:299  Rx RSL BCCH INFO (SI1, 23 bytes)
<0000> rsl.c:299  Rx RSL BCCH INFO (SI2, 23 bytes)
<0000> rsl.c:299  Rx RSL BCCH INFO (SI3, 23 bytes)
<0000> bts.c:374 Updated AGCH max queue length to 25
<0000> rsl.c:299  Rx RSL BCCH INFO (SI4, 23 bytes)
<0000> rsl.c:506  Rx RSL SACCH FILLING (SI5, 19 bytes)
<0000> rsl.c:506  Rx RSL SACCH FILLING (SI6, 13 bytes)

If the BTS process exits immediately, it is likely you have an error in your configuration file syntax, or your BSC does not know any BTS with the unit-id that you have specified in the config file.

At this point your virtual BTS should be happily transmitting virtual radio frames. How can you verify that? Check in wireshark if you see it emitting UDP multicast packets to port 4729. Those packets should be properly displayed/decoded by the wireshark GSMTAP dissector, and you should see e.g. the repeated transmission of the SYSTEM INFORMATION messages on BCCH.

If you cannot see related packets, it might be that your network stack (routing, packet filter) is configured in a way that multiast is disabled/filtered. On a typical workstation permitting all outbound IP traffic in the firewall and having a default route to eth0, the multicast traffic should appear on that interface. Please see attached file osmo_bts_virtual_gsmtap.pcapng for an example of how the traffic should look like.

The MS side

On the MS side, you will need to compile the classic OsmocomBB host-side programs, particularly layer23/mobile and also the new virtphy program


virtphy is a small program that does not much more than to
  • bind a local UDP socket to port 4729
  • subscribe to the downlink IP multicast group to receive downlink messages from the BTS
  • provide the /tmp/osmcom_l2 unix domain socket to whcih L1CTL-using programs such as mobile can connect. This socket is traditionally provided by the osmocon demultiplexer program, which is only used in context with physical phones.

You don't need to configure anything, simply run the program

$ ./virtphy


The Mobile program did not need any modifications and hence does not know whether it is talking to a real L1/PHY or to the virtphy program. So there's nothing Virtual Um specific regarding its configuration, just configure it as usual.

One notable requirement is that you use the built-in software SIM card emulation, though, as virtphy doesn't implement the handling of any virtual or physical SIM Card.

You can then start the program like this:

$ ./mobile -c mobile.cfg

Once the mobile program is running, it will instruct virtphy to perform a network scan (which basically just listens for some multicast frames and reports for which ARFCN we have seen CCCH/BCCH frames) and perform operator selection and subsequently the first Location Update (LU).

A protocol trace of the location update as captured on the Virtual UM layer can be found attached as gsmtap_virtphy_lu.pcapng.

screenshot of wireshark trace of LU

osmo_bts_virtual_gsmtap.pcapng - GSMTAP downlink BCCH/CCCH from osmo-bts-virtual (10.6 KB) laforge, 07/19/2017 03:28 PM

gsmtap_virtphy_lu.pcapng - GSMTAP packets between MS and BTS during LU (464 Bytes) laforge, 07/19/2017 03:38 PM

wireshark_gsmtap_virtphy_lu.png - screenshot of wireshark trace of LU (154 KB) laforge, 07/19/2017 03:46 PM

mobile.cfg - example config file for mobile (1021 Bytes) laforge, 07/19/2017 03:49 PM