Cellular Network Infrastructure

h1. Osmocom Network In The Box

{{>toc}}

This is a brief guide to the most basic and minimal setup of an Osmocom 2G and/or 3G network for voice and data services. It is a good starting point for newcomers to familiarize with the software, and to expand upon by the [[Osmocom Manuals]] and other wiki pages.

*If this documentation is inaccurate or has you stumped, let's improve it!*

Contact us:

* #osmocom on libera.chat IRC

* the openbsc@ [[Mailing Lists|mailing list]]

h1. OsmoNITB R.I.P., long live the Network In The Box

Historically, Osmocom offered the [[OsmoNITB:]] "Network-In-The-Box" as an actual single program. It was a useful simplification at the time, but in 2017, Osmocom have decided to split OsmoNITB into programs more closely resembling traditional network architecture. It is recommended to use the new separate components instead of the OsmoNITB, since active development focus has moved there.

It is still very much possible to run a complete Osmocom core network in one "box". For example, a sysmoBTS can run the entire core network on the same hardware that drives the TRX, making it a complete network in actually one single box. At the same time, having separate components also allows scaling to large deployments, with properly distributed load and a central subscriber database.

To migrate from OsmoNITB to the new separate programs, see the [[OsmoNITB Migration Guide]].

h1. Part of this Complete Network

Assuming that you have your radio hardware ready (a BTS, a femto cell or an SDR driven by osmo-trx), the core network consists of separate programs providing voice/SMS/USSD ("circuit-switched" or CS) and data ("packet-switched" or PS) services.

Here is a table of the components you need:

|\4. *Required for*  |/3. *Program* |/3. *Description* |

|\2. *2G*  |\2. *3G* |

| *CS* | *PS* | *CS* | *PS* |

| ✔ | ✔ | ✔ | ✔ | [[Osmocom Network In The Box#OsmoHLR|OsmoHLR]] | Home Location Register, stores subscriber IMSI, phone number and auth tokens. |

| ✔ | (1) | ✔ (3) | (1) | [[Osmocom Network In The Box#OsmoMSC|OsmoMSC]] | Mobile Switching Center, handles signalling, i.e. attach/detach of subscribers, call establishment, messaging (SMS and USSD). |

| ✔ |   | ✔ |   | [[Osmocom Network In The Box#OsmoMGW|OsmoMGW]] | Media Gateway, is instructed by the MSC and/or the BSC to direct RTP streams for active voice calls. |

| ✔ | ✔ | ✔ | ✔ | [[Osmocom Network In The Box#OsmoSTP|OsmoSTP]] | Signal Transfer Point, routes SCCP messages between MSC, BSC, HNBGW and for 3G also the SGSN. |

| ✔ | (1) |   |   | [[Osmocom Network In The Box#OsmoBSC|OsmoBSC]] | 2G Base Station Controller, manages logical channels and other lower level aspects for one or more 2G BTS; it is technically part of the BSS and not the "core network". |

|   |   | ✔ | ✔ | [[Osmocom Network In The Box#OsmoHNBGW|OsmoHNBGW]] | 3G HomeNodeB Gateway, receives the Iuh protocol from a 3G femto cell and forwards to MSC and SGSN by SCCP/M3UA via OsmoSTP. |

|   | ✔ (2) |   | ✔ (2) | [[Osmocom Network In The Box#OsmoGGSN|OsmoGGSN]] | Gateway GPRS Support Node, "opens" GTP tunnels received from SGSNs to internet uplink. |

|   | ✔ |   | ✔ (3) | [[Osmocom Network In The Box#OsmoSGSN|OsmoSGSN]] | Serving GPRS Support Node, handles signalling, i.e. attach/detach of subscribers and PDP contexts. |

| ✔ | (1) |   |   | [[Osmocom Network In The Box#OsmoBTS|OsmoBTS]] | for 2G networks, drives the TRX and ties to the BSC via Abis-interface. |

|   | ✔ |   |   | [[Osmocom Network In The Box#OsmoPCU|OsmoPCU]] | for 2G networks, a component closely tied to the BTS, drives the TRX for PS timeslots and ties to the SGSN via Gb-interface. |

|   |   | ✔ | ✔ | hNodeb | 3rd party 3G femto cell hardware to connect to OsmoHNBGW via Iuh |

|   |   |   |   | [[osmo-sip-connector|OsmoSIPConnector]] | Optional: switch OsmoMSC to external MNCC and forward Call Control and RTP to a PBX of your choice. |

1: PS is always an _addition_ to CS: even though these components do not handle PS requests, you need to have these to be able to setup and register with a network, which is a prerequisite for data services. That is mostly due to policy by the mobile phones, theoretically they could accept a network without voice service.

2: For the GGSN to successfully route packets to an internet uplink, it needs a tun device set up and usually IP masquerading/forwarding enabled. Please refer to the OsmoGGSN manual for more details.

3: If building from source, remember to build with --enable-iu. (Our binary packages are built with --enable-iu.)

h2. Topology

{{graphviz_link()

digraph G {

  rankdir = LR;

  MS [label="MS\n(2G phone)"]

  UE [label="UE\n(3G phone)"]

  PBX [label="PBX\nAsterisk, FreeSwitch,\nKamailio, Yate, ..."]

  subgraph cluster_bts {

    BTS [rank="min"]

    PCU [rank="min"]

  }

  subgraph cluster_msc_mgw {

    style=dotted

    MSC

    MGW1 [label="MGW"]

    MSC -> MGW1 [label="MGCP",constraint=false]

  }

  subgraph cluster_bsc_mgw {

    style=dotted

    BSC

    MGW2 [label="MGW"]

    BSC -> MGW2 [label="MGCP",constraint=false]

  }

  subgraph cluster_hnbgw_mgw_upf {

    style=dotted

    MGW3 [label="MGW"]

    UPF

    HNBGW

    HNBGW -> MGW3 [label="MGCP",constraint=false]

    HNBGW -> UPF [label="PFCP",constraint=false]

  }

  hNodeB [shape="box",label="hNodeB\n(3G femto cell)"]

  MS -> BTS [label="Um",style="bold"]

  MS -> PCU [style="dashed,bold"]

  BTS -> BSC [label="Abis/IP",style=bold]

  STP [label="STP\n(SCCP/M3UA)"]

  BSC -> STP -> MSC [label="A",style=bold]

  MSC -> HLR [label="\nGSUP",style=bold]

  SGSN -> HLR [label="GSUP",style="dashed,bold"]

  UE -> hNodeB [label="Uu",style=bold]

  UE -> hNodeB [style="dashed,bold"]

  hNodeB -> HNBGW [label="Iuh",style="bold"]

  STP2 [label="STP\n(SCCP/M3UA)"]

  HNBGW -> STP2 -> SGSN [label="IuPS",style="dashed,bold"]

  HNBGW -> STP2 -> MSC [label="IuCS",style="bold"]

  PCU -> SGSN [label="Gb",style="dashed,bold"]

  SGSN -> GGSN [label="GTP-C",style="dashed,bold"]

  SGSN -> GGSN [label="GTP-U(2G)",style="dashed"]

  hNodeB -> UPF -> GGSN [label="GTP-U(3G)",style="dashed"]

  GGSN -> internet [label="tun",style="dashed"]

  BTS -> MGW2 -> MGW1 [label="RTP"]

  MGW1 -> MGW1 [label="RTP"]

  MGW2 -> MGW2 [label="RTP (LCLS)"]

  hNodeB -> MGW3 [label="IuUP/RTP",constraint=false]

  MGW3 -> MGW1 [label="IuUP/RTP"]

  MSC -> SIPConnector [label="MNCC socket",style=bold]

  SIPConnector -> PBX [label="SIP",style=bold]

  MGW1 -> PBX [label="RTP"]

  A, B, C, D [style="invisible"]

  A -> B [label="data (PS)",style="dashed"]

  C -> D [label="voice/SMS/USSD (CS)"]

}

}}

h1. Have to Know

Each program features a detailed [[Osmocom Manuals|user manual]], your primary source of information to expand on the setup described here.

Osmocom offers [[Binary_Packages|compiled packages for various distributions]]. If you're up to it, you may also [[Build from Source]].

Each Osmocom program typically has

* a distinct configuration file;

* a VTY telnet console for live interaction;

* a CTRL interface for live interaction from 3rd party programs.

See [[Port Numbers]] to find out which program runs what services on which port.

h2. Realtime scheduling hierarchy

The time-critical components use realtime scheduling policy (round-robin by default) - see https://man7.org/linux/man-pages/man7/sched.7.html

The priority hierarchy of those components looks as follows (higher priority on top):

{{graphviz_link()

digraph G {

rankdir = LR;

 subgraph cluster_legend {

    style=dotted

  A, B, C, D [style="invisible"]

 A -> B [label="normal",style="dashed,bold"]

 C -> D [label="realtime",style=bold]

  }

}

}}

{{graphviz_link()

digraph G {

  TRX [label="OsmoTRX"]

  BTS [label="OsmoBTS"]

  MGW [label="OsmoMGW"]

  PCU [label="OsmoPCU"]

  XXX [label="The rest of the system"]

  TRX -> BTS [style=bold]

  BTS -> MGW [style=bold]

  BTS -> PCU [style=bold]

  MGW -> XXX [style="dashed,bold"]

  PCU -> XXX [style="dashed,bold"]

}

}}

h1. The State of 3G Voice

IuCS doesn't talk plain RTP, it talks IuUP inside the RTP payload (!). That is another header, and the AMR bits inside that are mangled and shifted around, even though the underlying codec is still AMR. Currently, we have only stub work to decode IuUP.

The bottom line is that 3G to 3G calls work simply because we are passing the IuUP through in a hackish manner. 2G <-> 3G does not work, and 3G <-> PBX does not work. Without decoding IuUP, you will not have the slightest chance to get this working.

There is some ongoing work, see [[3G Voice]] for the latest news.

h1. Configuration Examples

Here is a tarball of the config files discussed below: attachment:nitb.tar

h2. OsmoHLR

[[OsmoHLR:]] is the Home Location Register: it stores subscriber IMSI, phone number and auth tokens. This is where you configure who is allowed on your network and who has which phone number. It also handles USSD services (like "*100#").

osmo-hlr will automatically bootstrap an empty subscriber database. See the [[Osmocom Manuals|manual]] on how to add one or more subscribers -- if you don't know your IMSI, it can be useful to attempt a connection and watch the OsmoHLR log for a rejected IMSI. To migrate subscribers from an older OsmoNITB database, see the [[OsmoNITB migration guide]].

While you do need one, your configuration file may actually remain empty. This will serve GSUP on localhost (127.0.0.1), sufficient for a Network In The Box with MSC and SGSN on the same machine as the HLR.

This example optionally configures two USSD services and logging.

*osmo-hlr.cfg* (download: attachment:nitb.tar)

<pre>

hlr

 ussd route prefix *#100# internal own-msisdn

 ussd route prefix *#101# internal own-imsi

log stderr

 logging filter all 1

 logging print extended-timestamp 1

 logging print category 1

 logging print category-hex 0

 logging print level 1

 logging print file basename last

 logging level set-all debug

</pre>

Once your HLR is running, you will want to add subscribers with authentication keys to the HLR database. Please refer to the OsmoHLR [[Osmocom Manuals]], section "Managing Subscribers".

h2. OsmoMSC

[[OsmoMSC:]] is the Mobile Switching Center: it handles signalling, i.e. attach/detach of subscribers, call establishment, messaging (SMS and USSD). The OsmoMSC is your central "manager" of the network.

The VLR component of OsmoMSC needs to connect to the OsmoHLR's GSUP server to know which subscribers are authorized. By default, it will connect to OsmoHLR on localhost, no explicit config needed.

To be reachable by OsmoBSC and OsmoHNBGW, OsmoMSC needs an SCCP point code, and it needs to connect to OsmoSTP to make itself known to SCCP routing.

* There is a default point code, currently 0.23.1 (in 8.8.3 point code format, see [[Point Codes]]).

* OsmoMSC will by default look for OsmoSTP on localhost's M3UA port, 2905.

To direct RTP streams, OsmoMSC needs an OsmoMGW instance (see OsmoMGW below).

You only need to set up your MCC, MNC, and how to reach/use the MGW.

*osmo-msc.cfg* (download: attachment:nitb.tar)

<pre>

network

 network country code 901

 mobile network code 70

msc

 mgw remote-ip 192.168.0.9

 # For nano3G:

 iu rab-assign-addr-enc x213

log stderr

 logging filter all 1

 logging print extended-timestamp 1

 logging print category 1

 logging print category-hex 0

 logging print level 1

 logging print file basename last

 logging level set-all info

</pre>

h2. OsmoMGW

[[OsmoMGW:]] is the Media Gateway: it is instructed by the MSC and/or the BSC to direct RTP streams for active voice calls. The Media Gateway receives instructions in the form of MGCP messages from OsmoMSC/OsmoBSC. It forwards RTP streams directly between BTS, femto cells and remote endpoints, e.g. other MGW instances, and its job is to transcode between codecs (future).

You need an OsmoMGW to serve OsmoMSC's MGCP requests, and an OsmoMGW to serve OsmoBSC's MGCP requests. In fact, these two can be served by one single OsmoMGW instance. If you would like to keep two separate OsmoMGW instances, you need to take care that they don't attempt to bind to identical ports on the same IP address (for MGCP, but also for VTY and CTRL interfaces).

Consider that you have a 2G network with an external BTS (say a sysmoBTS), which means that you need your OsmoBSC's MGW instance to be reachable on a public interface. So far the MSC's MGW can be on a local loopback interface, it only needs to be reachable by the BSC's MGW and by the MSC.

If you also have a 3G femto cell, then the MSC's MGW instance also needs to be on a public interface. At this point you either need two public interface addresses, or you need to put one of the MGWs on a different MGCP port.

You may decide to use one OsmoMGW for both BSC and MSC, if your network topology allows.

(There used to be the need to separate the endpoint config for BSC and MSC, but now the MGW takes care of that automatically.)

To increase the likelihood that your first setup will work out, below examples pick distinct MGCP ports and VTY interfaces, which allows running two MGWs on the same public IP address.

h3. OsmoMGW for OsmoMSC

OsmoMGW listens for MGCP connections, by default on port 2427.

* In a setup that truly runs in one box (e.g. sysmoBTS or osmo-trx with co-located core network), this may be localhost (127.0.0.1), which is the default, and your config file may omit the 'bind ip'.

* With a separate BTS and/or RNC (e.g. 3G femto cell or nanoBTS), make sure to configure an IP address that is reachable by the hNodeB and BTS:

*osmo-mgw-for-msc.cfg* (download: attachment:nitb.tar)

<pre>

mgcp

 bind ip 192.168.0.9

line vty

 bind 127.0.0.1

log stderr

 logging filter all 1

 logging print extended-timestamp 1

 logging print category 1

 logging print category-hex 0

 logging print level 1

 logging print file basename last

 logging level set-all info

</pre>

h3. OsmoMGW for OsmoBSC

OsmoBSC also requires an OsmoMGW instance to run alongside it. In a setup where OsmoBSC and OsmoMSC can both reach it directly, they may in fact share the same OsmoMGW instance (endpoints are allocated dynamically).

It is semantically more clear to run a separate OsmoMGW instance for the OsmoBSC. When running on the same machine, though, then each MGW obviously needs to use different UDP ports, for example:

*osmo-mgw-for-bsc.cfg* (download: attachment:nitb.tar)

<pre>

mgcp

 bind ip 192.168.0.9

 # default port is 2427 (is used for MSC's MGW)

 bind port 12427

line vty

 # default VTY interface is on 127.0.0.1 (used for MSC's MGW)

 bind 127.0.0.2

log stderr

 logging filter all 1

 logging print extended-timestamp 1

 logging print category 1

 logging print category-hex 0

 logging print level 1

 logging print file basename last

 logging level set-all info

</pre>

Note that osmo-bsc.cfg below sets the 'mgw remote-port' to the 'bind port' configured here; if the MGWs run on distinct interfaces, the default ports will do in both cases.

h3. OsmoMGW for OsmoHNBGW

Since 2022, OsmoHNBGW also supports an MGW instance as a local hop for 3G related IuUP/RTP.

*osmo-mgw-for-hnbgw.cfg* (download: attachment:nitb.tar)

<pre>

mgcp

 bind ip 192.168.0.9

 bind port 22427

line vty

 bind 127.0.0.3

log stderr

 logging filter all 1

 logging print extended-timestamp 1

 logging print category 1

 logging print category-hex 0

 logging print level 1

 logging print file basename last

 logging level set-all info

</pre>

Note that osmo-hnbgw.cfg below sets the 'mgw remote-port' to the 'bind port' configured here; if the MGWs run on distinct interfaces, the default ports will do in both cases.

h2. OsmoSTP

[[OsmoSTP:]] is the Signal Transfer Point; think of it like a network switch that quietly routes messages between components, for the SS7 system. You almost never need to look at its logging or configuration.

OsmoSTP acts as a server for routing SCCP messages. OsmoMSC, OsmoBSC, OsmoHNBGW and OsmoSGSN contact OsmoSTP and announce their own point code, after which they may instruct OsmoSTP to route SCCP messages to each other by these point codes.

The basic configuration that permits dynamic routing is:

*osmo-stp.cfg* (download: attachment:nitb.tar)

<pre>

cs7 instance 0

 xua rkm routing-key-allocation dynamic-permitted

 listen m3ua 2905

  accept-asp-connections dynamic-permitted

log stderr

 logging filter all 1

 logging print extended-timestamp 1

 logging print category 1

 logging print category-hex 0

 logging print level 1

 logging print file basename last

 logging level set-all info

</pre>

h2. OsmoBSC

[[OsmoBSC:]] is the 2G Base Station Controller: it manages logical channels and other lower level aspects for one or more 2G BTS. The BSC tells the MSC what the phones would like to do, and in turn the MSC tells the BSC to establish channels, page phones, and take care of the lower level BTS maintenance.

OsmoBSC needs to register with OsmoSTP, and contact the MSC by its point code. If not configured otherwise, it will use OsmoMSC's default point code to contact it, see [[Point Codes]].

OsmoBSC needs to contact an OsmoMGW on its MGCP port, to manage RTP streams between BTS and the MSC's MGW, as discussed above under "OsmoMGW".

OsmoBSC also needs complete configuration of all connected BTS -- usually the BTS side configures the phy, unit id and the BSC's remote address, and the BSC configures everything else over OML. This example shows configuration for a sysmoBTS.

Furthermore, some network properties need to be set.

The 'gprs mode' determines whether packet switched access will be enabled. 'gprs mode none' switches off data services, it tells osmo-bts not to contact osmo-pcu to establish data service. Note that if you set 'gprs mode gprs' but fail to provide a working PCU, a phone may oscillate between BTS cells to try to establish GPRS service.

To allow data service, set a 'gprs mode gprs' or 'gprs mode egprs', and configure PDCH timeslots. Traditionally, a fixed amount of TCH timeslots for voice and PDCH timeslots for data service are configured. OsmoBTS also supports two types of dynamic timeslots, as described in the "Abis manual":http://ftp.osmocom.org/docs/latest/osmobts-abis.pdf, chapter "Dynamic Channel Combinations". The following is a configuration with voice-and-data service based on Osmocom style dynamic timeslots:

*osmo-bsc.cfg* for voice and data service (download: attachment:nitb.tar)

<pre>

network

 network country code 901

 mobile network code 70

 bts 0

  type sysmobts

  band GSM-1800

  location_area_code 23

  # This is the unit id that has to match the BTS configuration

  ip.access unit_id 1800 0

  codec-support fr hr amr

  gprs mode gprs

  gprs nsvc 0 remote ip 192.168.0.9

  gprs nsvc 0 remote udp port 23000

  gprs nsvc 0 local udp port 23000

  gprs nsvc 0 nsvci 1800

  gprs nsei 1800

  gprs cell bvci 1800

  trx 0

   rf_locked 0

   arfcn 868

   nominal power 23

   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

e1_input

 e1_line 0 driver ipa

msc 0

 mgw remote-ip 192.168.0.9

 mgw remote-port 12427

 allow-emergency deny

 codec-list hr3

log stderr

 logging filter all 1

 logging print extended-timestamp 1

 logging print category 1

 logging print category-hex 0

 logging print level 1

 logging print file basename last

 logging level set-all info

</pre>

h2. OsmoHNBGW

[[OsmoHNBGW:]] is the 3G HomeNodeB Gateway, found in the osmo-iuh.git repository: it receives the Iuh protocol from a 3G femto cell, separates it into IuCS and IuPS and forwards to the MSC and SGSN.

OsmoHNBGW needs to connect to OsmoSTP for routing, and needs to know the MSC and SGSN point codes. If omitted, it assumes OsmoSTP on 127.0.0.1 and uses the point codes that are default in OsmoMSC and OsmoSGSN, see [[Point Codes]].

It must also be reachable by the hNodeB, hence its Iuh must typically run on a public IP, not a loopback address like 127.0.0.1.

*osmo-hnbgw.cfg* (download: attachment:nitb.tar)

<pre>

hnbgw

 iuh

  local-ip 192.168.0.9

 mgcp

  mgw remote-ip 192.168.0.9

  mgw remote-port 22427

 pfcp

  remote-addr 192.168.0.9

log stderr

 logging filter all 1

 logging print extended-timestamp 1

 logging print category 1

 logging print category-hex 0

 logging print level 1

 logging print file basename last

 logging level set-all info

</pre>

*NOTE:* For the nano3G, the MSC must encode X.213 style addresses in the RAB assignment, see osmo-msc.cfg, 'iu rab-assign-addr-enc x213'.

*NOTE:* To connect your femto cell to the HNBGW, see for example [[Configuring_the_ipaccess_nano3G]]

*NOTE:* The 'hnbap-allow-tmsi' option is just a workaround for the nano3G passing a TMSI as UE-Register identity, which would normally have to be an IMSI.

*NOTE:* Using a UPF as a GTP hop is optional

h2. OsmoUPF

[[OsmoUPF:]] provides a local hop for the GTP user plane of 3G PS: it receives PFCP instructions from OsmoHNBGW, and maps GTP tunnels from the hNodeB (Access) side to the GGSN (Core) side.

OsmoUPF requires to be run on Linux. OsmoUPF uses Linux kernel features to handle the GTP user plane in kernel space: the GTP module for encapsulation/decapsulation from/to "the internet", and netfilter (nftables) to forward GTP tunnels between two interfaces. The netfilter features in use require at least a Linux 5.17 kernel.

To be able to use the kernel featrues, the osmo-upf program needs to have cap_net_admin permissions, as given by the following command -- when installed from packages, this should already be taken care of:

<pre>

sudo setcap cap_net_admin+pe /usr/bin/osmo-upf

</pre>

The UPF paired with OsmoHNBGW will always do tunnel mapping, and never does encapsulation/decapsulation, which means that it does not require a GTP device.

*osmo-upf.cfg* (download: attachment:nitb.tar)

<pre>

pfcp

 local-addr 192.168.0.9

nft

 # netfilter requires no specifc configuration

gtp

 # if encaps/decaps of GTP to "the internet" is required, uncomment the following line:

 #dev create apn0

log stderr

 logging filter all 1

 logging print extended-timestamp 1

 logging print category 1

 logging print category-hex 0

 logging print level 1

 logging print file basename last

 logging level set-all info

</pre>

h2. OsmoGGSN

[[OpenGGSN:|OsmoGGSN]] is the Gateway GPRS Support Node: it "opens" GTP tunnels received from SGSNs to internet uplink. To provide packet switched service, OsmoGGSN must offer GTP service to the OsmoSGSN.

Notably, both OsmoGGSN and OsmoSGSN must use identical GTP port numbers, which is an intrinsic requirement of the GTP protocol. Hence they must not run on the same IP address. Furthermore, for 2G networks, the SGSN must be reachable by the PCU and thus needs to be on a public interface if the BTS is a separate box; for 3G networks, the GGSN must be reachable by the hNodeB and thus needs to be on a public interface. So, to cover both, you need to have *two* public interfaces; this example uses 192.168.0.42, assumed to be an IP address available on the local ethernet interface.

Refer to your distribution on how to configure a second IP address.

(In an aside, this script would obtain a second address from your DHCP server:

<pre>

#!/bin/sh

# usage: ./second_dhclient.sh eth0

dev="${1:-eth0}"

nr="$(ip a | grep "^[0-9]*: $dev" | wc -l)"

name="$(echo "$dev" | sed 's/[^0-9a-fA-F]//g' | head -c 1)"

mac="ac:ac:1a:b0:a0:$name$nr"

set -e -x

sudo ip link add link $dev address $mac $dev.$nr type macvlan

sudo dhclient $dev.$nr

ip addr show dev $dev.$nr

</pre>

For this example to work, the DCHP server would need to assign to you the address 192.168.0.42.)

OsmoGGSN maintains a gsn_restart counter, to be able to reliably communicate to the SGSN that it has restarted. This is kept in the 'state-dir', by default in /tmp.

It also needs access to a tun device with an address range available to subscribers' PDP contexts. This may be configured ahead of time, so that OsmoGGSN does not need root privileges. If run with 'sudo', OsmoGGSN may also create its own tun device. In below example, the 'apn0' device has been created ahead of time, with:

<pre>

sudo ip tuntap add dev apn0 mode tun user $USER group $USER

sudo ip addr add 192.168.42.0/24 dev apn0

sudo ip link set apn0 up

</pre>

IPv4 operation is enabled by default, but for future compatibility, it is good to indicate that explicitly.

OsmoGGSN furthermore indicates DNS servers, as well as an IPv4 address range to assign to subscribers' PDP contexts.

Note that the APN named in this config file (here "internet") needs to be configured on your phone, see [[Osmocom Network In The Box#APN-for-Data-Service|APN for Data Service]] below. With the @default-apn@ command, any unknown APN name will use that default APN instead, but still you usually have to define _some_ APN on your phone so that it even tries to connect to the data service.

A profound part of GGSN configuration is the network setup of your system: you need to allow the packets to be routed between the subscribers and your internet uplink. See the [[Osmocom Manuals|OsmoGGSN User Manual]], section _Running OsmoGGSN_ / _Routing_.

*osmo-ggsn.cfg* (download: attachment:nitb.tar)

NOTE: this configuration requires the _apn0_ tun device to be configured and up, as well as IP-forwarding and masquerading to be enabled -- please see the manual as indicated above.

<pre>

log stderr

 logging level all debug

 logging filter all 1

 logging print category 1

ggsn ggsn0

 gtp bind-ip 192.168.0.42

 apn internet

  tun-device apn0

  type-support v4

  ip dns 0 192.168.0.1

  ip dns 1 9.9.9.9

  ip prefix dynamic 192.168.42.0/24

  no shutdown

 default-apn internet

 no shutdown ggsn

log stderr

 logging filter all 1

 logging print extended-timestamp 1

 logging print category 1

 logging print category-hex 0

 logging print level 1

 logging print file basename last

 logging level set-all info

</pre>

h2. OsmoSGSN

[[OsmoSGSN:]] is the Serving GPRS Support Node: it handles signalling, i.e. attach/detach of subscribers and PDP contexts for data services.

OsmoSGSN needs to reach the GGSN to establish GTP tunnels for subscribers. It must have a separate GTP IP address from OsmoGGSN, as mentioned before.

For 2G, OsmoSGSN needs to be reachable by the PCU, and needs a public IP for the Gb interface if it is not running directly on the BTS hardware (e.g. on sysmoBTS or when using osmo-trx). For 2G operation, SGSN and GGSN may both use a local IP address for GTP, as long as they differ (e.g. 127.0.0.1 and 127.0.0.2).

For 3G, OsmoSGSN needs to be reachable by the HNBGW for IuPS. If you're running _only_ 3G, the SGSN does not need to listen on a public IP address.

For 3G IuPS, the SGSN must sign up at OsmoSTP with a point code that the HNBGW knows. If not configured explicitly, the respective defaults are used, see [[Point Codes]].

Finally, OsmoSGSN needs access to OsmoHLR to access subscriber data. Set 'auth-policy remote' to use the HLR for subscriber authorization.

*osmo-sgsn.cfg* (download: attachment:nitb.tar)

<pre>

sgsn

 gtp local-ip 192.168.0.9

 ggsn 0 remote-ip 192.168.0.42

 ggsn 0 gtp-version 1

 auth-policy remote

 gsup remote-ip 127.0.0.1

ns

 encapsulation udp local-ip 192.168.0.9

 encapsulation udp local-port 23000

 encapsulation framerelay-gre enabled 0

log stderr

 logging filter all 1

 logging print extended-timestamp 1

 logging print category 1

 logging print category-hex 0

 logging print level 1

 logging print file basename last

 logging level set-all info

</pre>

The @auth-policy remote@ requires that you have the SIM cards' authentication tokens in your OsmoHLR database. Instead, you can use @auth-policy accept-all@, but be aware that this will only work for 2G. 3G networks _require_ successful authentication, and @auth-policy remote@ is your _only_ option for a 3G SGSN.

h1. OsmoBTS

[[OsmoBTS:]] operates 2G radio hardware. OsmoBTS supports various hardware platforms including sysmoBTS and USRP. Instead, you may choose BTS vendors like ip.access or Siemens, which can also directly operate with OsmoBSC without OsmoBTS being involved.

Depending on the used hardware, you may need to launch matching BTS implementations, for example:

| SDR based BTS like USRP, B210, umTRX (see [[OsmoTRX:OsmoTRX#RF-Hardware-support|OsmoTRX hardware]]) | run osmo-trx and osmo-bts-trx on the machine hosting the SDR device |

| sysmoBTS device (https://www.sysmocom.de/products/bts/) | run osmo-bts-sysmo and osmo-pcu on the sysmoBTS box itself |

| other Osmocom based BTS, see [[OsmoBTS:Wiki#Backends-Hardware-support|OsmoBTS]] | run the matching osmo-bts-* variant |

| third party BTS, like ip.access nanoBTS | typically run in their own box, and you do not launch Osmocom software on them, but configure them to connect to your BSC |

| 3G femto cell, like ip.access nano3G | this is not even a BTS but an hNodeB ("BTS" is a 2G term) -- you configure a 3G femto cell to connect to OsmoHNBGW |

The BTS needs to know where to reach OsmoBSC's Abis interface, and its unit id needs to match one of the BTS unit ids configured at OsmoBSC.

An example configuration for a sysmoBTS is:

<pre>

phy 0

 instance 0

bts 0

 band 1800

 ipa unit-id 1800 0

 oml remote-ip 192.168.0.9

 trx 0

  phy 0 instance 0

</pre>

h1. OsmoPCU

[[OsmoPCU:]] operates the packet-switched part of 2G radio hardware. Timeslots used for data transmission are controlled by the PCU instead of the BTS. OsmoPCU is typically configured from the @gprs@ config items in OsmoBSC, which is communicated to the PCU via OML and OsmoBTS (via the PCU socket). An example configuration for OsmoPCU would be:

<pre>

pcu

 flow-control-interval 10

 cs 2

 alloc-algorithm dynamic

 alpha 0

 gamma 0

 two-phase-access

</pre>

h1. Running Examples

Each Osmocom program comes with a systemd service file. It is recommended to place config files in @/etc/osmocom/@ and launch the individual components using @systemd@.

When installed from debian or opkg feeds, you will find the systemd service files in @/lib/systemd/system/@.

Re/starting and stopping then works like this:

<pre>

systemctl restart osmo-hlr

systemctl stop osmo-hlr

</pre>

For illustration, the manual command invocations for the components would look like this on a typical CNI standalone host:

<pre>

osmo-hlr -l hlr.db -c osmo-hlr.cfg

osmo-msc -c osmo-msc.cfg

osmo-mgw -c osmo-mgw-for-msc.cfg

osmo-mgw -c osmo-mgw-for-bsc.cfg

osmo-ggsn -c osmo-ggsn.cfg

osmo-sgsn -c osmo-sgsn.cfg

osmo-stp -c osmo-stp.cfg

osmo-bsc -c osmo-bsc.cfg

osmo-hnbgw -c osmo-hnbgw.cfg

osmo-sip-connector -c osmo-sip-connector.cfg

</pre>

h2. Convenience Launcher

It can be useful to have an @osmo-all@ script to re/start or stop all components at once, edit to pick yours:

*osmo-all* script

<pre>

#!/bin/sh

cmd="${1:-status}"

set -ex

systemctl $cmd osmo-hlr osmo-msc osmo-mgw osmo-ggsn osmo-sgsn osmo-stp osmo-bsc osmo-hnbgw osmo-sip-connector

</pre>

which allows

<pre>

./osmo-all restart

./osmo-all status

./osmo-all stop

</pre>

h1. Logging Examples

Osmocom programs have a common logging mechanism, configurable by the config files as well as the telnet VTY.

h2. System Logging

Depending on the system's logging configuration, logs may by default be visible in /var/log/daemon.log, or by using journalctl:

<pre>

journalctl -f -u osmo-hlr

</pre>

When journalctl is used, it may be necessary to enable it first, e.g. by setting "Storage=volatile" in /etc/systemd/journald.conf followed by a 'systemctl restart systemd-journald'; you may also need to 'systemctl unmask systemd-journald.service systemd-jounald.socket'. Logging will only start appearing for components that were restarted after these changes.

h2. telnet VTY logging

A sure way to see the logs is to connect to the program's telnet VTY and enable logging on the VTY session -- this way you do not modify the application's default logging, but create a separate logging target for your telnet VTY session:

<pre>

$ telnet localhost 4254

OsmoMSC> logging enable 

OsmoMSC> logging level ?

  all      Global setting for all subsystems

  rll      A-bis Radio Link Layer (RLL)

  cc       Layer3 Call Control (CC)

  mm       Layer3 Mobility Management (MM)

  [...]

OsmoMSC> logging level all ?

everything debug      info       notice     error      fatal      

OsmoMSC> logging level all debug 

OsmoMSC> logging filter all 1

</pre>

You will see logging output on your telnet console immediately. Note that the VTY prompt is still listening, so you may at any time issue 'logging filter all 0' to switch off logging, and be able to type commands without being cluttered by ongoing log output.

Here is a useful 'expect' script to attach to osmo-* components by name and start logging while still having a vty prompt:

*vty* script (download: attachment:nitb.tar)

<pre>

#!/usr/bin/expect -f

set vty [lindex $argv 0]

set host localhost

switch $vty {

 hlr { set port 4258 }

 bsc { set port 4242 }

 mgw { set port 4243 }

 mgw2 {

        set host 127.0.0.2

        set port 4243

      }

 sg { set port 4245 }

 msc { set port 4254 }

 sip { set port 4256 }

 gg { set port 4260 }

 osmo-hlr { set port 4258 }

 osmo-bsc { set port 4242 }

 osmo-mgw { set port 4243 }

 osmo-mgw-for-bsc { set port 4243 }

 osmo-mgw-for-msc {

        set host 127.0.0.2

        set port 4243

      }

 osmo-sgsn { set port 4245 }

 osmo-msc { set port 4254 }

 osmo-sip-connector { set port 4256 }

 osmo-ggsn { set port 4260 }

 default { set port 4242 }

}

spawn telnet localhost $port

expect ">"

send "enable\r"

expect "#"

send "logging enable\r"

expect "#"

send "logging print category 1\r"

expect "#"

send "logging print category-hex 0\r"

expect "#"

send "logging print level 1\r"

expect "#"

send "logging print file basename last\r"

expect "#"

send "logging print extended-timestamp 1\r"

expect "#"

send "logging level set-all notice\r"

expect "#"

switch $vty {

 msc {

  send "logging level mm info\r"

  expect "#"

  send "logging level cc info\r"

  expect "#"

 }

}

send "logging filter all 1\r"

expect "#"

interact

</pre>

h2. stderr logging

A common configuration you can add to any of the above configuration files to show *all* logging on stderr is:

<pre>

log stderr

 logging filter all 1

 logging color 1

 logging print category 1

 logging timestamp 1

 logging print extended-timestamp 1

 logging level all debug

</pre>

The @filter all 1@ switches on logging, read "do not discard all logging". The amount of logging seen is determined by @logging level ...@ commands, here all categories are set to level @debug@, to show absolutely all logging. You will probably want to refine that.

h1. Point Codes

If you'd like to configure non-default point-codes, see this example for OsmoHNBGW on the general approach:

<pre>

cs7 instance 0

 # HNBGW's local point code

 point-code 0.23.5

 # Address book entries, used below

 sccp-address my_msc

  point-code 0.23.1

 sccp-address my_sgsn

  point-code 0.23.4

hnbgw

 iucs

  remote-addr my_msc

 iups

  remote-addr my_sgsn

</pre>

h1. Troubleshooting

h2. APN for Data Service

For the data service to work, phones generally need an APN added to their

configuration, or they will not even attempt to establish a data connection.

The APN should match the name configured in osmo-ggsn.conf.

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'

* 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.

</pre>

h1. Tips and Facts

h2. Analyzing 3G 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).