doc/manuals/chapters/net.adoc

[[net]]
== Configuring the Core Network

The core network parameters are configured by the config file (as in `osmo-msc
-c osmo-msc.cfg`). The config file is parsed by the VTY, which is also
available via telnet in the running `osmo-msc` instance. Be aware that even
though you may be able to change these parameters without restarting
`osmo-msc`, some may not take immediate effect, and it is safest to use the
config file to have these parameters set at startup time.

The core network parameters are found in the `config` / `network`.

A full reference to the available commands can be found in the _OsmoMSC VTY
reference manual_ <<vty-ref-osmomsc>>. This section describes only the most
commonly used settings.

Here is an overview of the config items, described in more detail below:

----
network
 network country code 262
 mobile network code 89
 mm info 1
 short name OsmoMSC
 long name OsmoMSC
 authentication required
 encryption a5 3
----

[TIP]
====
Use the telnet VTY interface to query the current configuration of a running
`osmo-msc` process:

----
$ telnet localhost 4254
OsmoMSC> enable
OsmoMSC# show running-config
----

Some parameters may be changed without restarting `osmo-msc`. To reach the
`network` node, enter:

----
OsmoMSC> enable
OsmoMSC# configure terminal
OsmoMSC(config)# network
OsmoMSC(config-net)# short name Example-Name
OsmoMSC(config-net)# exit
OsmoMSC(config)#
----

The telnet VTY features tab-completion as well as context sensitive help shown
when entering a `?` question mark.

You can always use the `list` VTY command or enter `?` on the blank prompt to
get a list of all possible commands at the current node.
====


=== MCC/MNC

The key identities of every GSM PLMN is the Mobile Country Code and the Mobile
Network Code. 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, have this in your
osmo-msc.cfg:

----
network
 network country code 262
 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, i.e. `0`. Set to `1`
to activate this feature:

----
network
 mm info 1
 short name OsmoMSC
 long name OsmoMSC
----

[NOTE]
====
Not all phones support the MM INFO procedure. If a phone is not
factory-programmed to contain the name for your MCC/MNC, it will likely only
provide a numeric display of the network name, such as _262-89_, or show 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 OsmoMSC is running.


=== Authentication

A subscriber's IMSI must be entered in the HLR database to be able to attach. A
subscriber-create-on-demand feature is also available, see the _OsmoHLR
reference manual_ <<userman-osmohlr>>.

A known IMSI in the HLR may or may not have authentication keys associated,
which profoundly affects the ability to attach and the algorithms used to
negotiate authentication, as the following sections explain for 2G and 3G.

==== Authentication on 2G

If authentication tokens (such as KI for 2G, or K and OP/OPC for UMTS) are
present in the HLR, OsmoMSC will only attach a subscriber after successful
authentication. Note that the 3G authentication keys are also used on 2G when
the MS indicates UMTS AKA capability, in which case the full UMTS style mutual
authentication may indeed take place on 2G (GERAN).

On 2G, if no authentication keys are present in the HLR for a given subscriber,
OsmoMSC will attach the subscriber _without_ authentication. Subscribers that
lack authentication keys can always be rejected with this setting:

----
network
 authentication required
----

==== Authentication on 3G

3G (UTRAN) always requires authentication (a.k.a. Integrity Protection) by
specification, and hence authentication keys must be present in the HLR for a
subscriber to be able to attach on 3G.

OsmoMSC always indicates UIA1 and UIA2 as permitted Integrity Protection
algorithms on 3G.

=== Ciphering

To enable ciphering on the radio link, authentication must take place first:
the Kc resulting from authentication is the key used for ciphering. Hence, to
be able to use ciphering, a subscriber must have authentication tokens
available in the HLR.

==== Ciphering on 2G

The MS, BTS and MSC must agree on a ciphering algorithm to use.

- The MS sends its supported ciphering algorithms via Classmark IEs during
  Location Updating.
- Typically the BSC needs to know which A5 ciphers are supported by connected
  BTSes, see the `network / encryption a5` configuration item for OsmoBSC
  <<vty-ref-osmobsc>>.
- Finally, OsmoMSC may impose that specific A5 ciphers shall not be considered.

It is the responsibility of the BSC to then pick an A5 cipher that satisfies
all requirements.

- In OsmoMSC, A5/0 means that ciphering is turned off.
+
----
network
 encryption a5 0
----

- A5/1 and A5/3 are currently supported by Osmocom.
+
----
network
 encryption a5 1 3
----

- Never use A5/2: it is an "export grade cipher" and has been deprecated for
  its low ciphering strength.

- To allow either no encryption or any of A5/1 or A5/3 based on the presence of
  authentication keys and abilities of the MS, SIM and BSC configuration, it is
  recommended to enable all ciphers in OsmoMSC. The highest available A5 cipher
  will be used; the order in which the A5 options are configured does not
  affect the choice.
+
----
network
 encryption a5 0 1 3
----

==== Ciphering on 3G

While authentication is always required on 3G, ciphering is optional.

So far OsmoMSC allows switching ciphering on 3G either on or off -- the default
behavior is to enable ciphering. (Individual choice of algorithms may be added
in the future.)

Disable 3G ciphering:

----
network
 encryption uea 0
----

Enable 3G ciphering (default):

----
network
 encryption uea 1 2
----

OsmoMSC indicates UEA1 and UEA2 as permitted encryption algorithms on 3G.