mirror of
https://gitea.osmocom.org/cellular-infrastructure/osmo-hlr.git
synced 2025-11-02 13:13:29 +00:00
80cb6c93b9
It seems a bad idea to cement the internal SQL structure in the user manual, but since we currently lack a safe and portable import mechanism (like CSV import in osmo-hlr-db-tool), this is currently valuable info to users. Change-Id: I3246e6d5364215a71c33b5aca876deab7b6cfd70
210 lines
7.9 KiB
Plaintext
210 lines
7.9 KiB
Plaintext
== Managing Subscribers
|
|
|
|
Subscribers are kept in a local SQLite database file and can be managed via VTY
|
|
and CTRL interfaces.
|
|
|
|
This section provides some examples; also refer to the OsmoHLR VTY reference
|
|
manual <<vty-ref-osmohlr>> as well as the Control interface described in
|
|
<<hlr-ctrl>>.
|
|
|
|
=== Example: Add/Update/Delete Subscriber via VTY
|
|
|
|
The following telnet VTY session adds a subscriber complete with GSM (2G) and
|
|
UMTS (3G and 2G) authentication tokens, and finally removes the subscriber
|
|
again; it assumes that osmo-hlr is running and listening for telnet VTY
|
|
connections on localhost:
|
|
|
|
----
|
|
$ telnet localhost 4258
|
|
include::../example_subscriber_add_update_delete.vty[]
|
|
----
|
|
|
|
[[subscriber-params]]
|
|
=== Subscriber Parameters
|
|
|
|
The following parameters are managed for each subscriber of the HLR, modelled
|
|
roughly after 3GPP TS 23.008, version 13.3.0; note that not all of these
|
|
parameters are necessarily in active use.
|
|
|
|
The `aud3g` table also applies to 2G networks: it provides UMTS AKA tokens for
|
|
Milenage authentication, which is available both on 3G and 2G networks. On 2G,
|
|
when both MS and network are R99 capable (like OsmoMSC and OsmoSGSN are), the
|
|
full UMTS AKA with Milenage keys from `aud_3g`, using AUTN and extended RES
|
|
tokens, is available. With pre-R99 MS or network configurations, the GSM AKA
|
|
compatible variant of Milenage, still using the Milenage keys from `aud_3g` but
|
|
transceiving only RAND and SRES, may be applicable. (See 3GPP TS 33.102, chapter
|
|
6.8.1, Authentication and key agreement of UMTS subscribers.)
|
|
|
|
.OsmoHLR's subscriber parameters
|
|
[options="header",width="100%",cols="20%,20%,60%"]
|
|
|===
|
|
|Name|Example|Description
|
|
|imsi|901700000014701|identity of the SIM/USIM, 3GPP TS 23.008 chapter 2.1.1.1
|
|
|msisdn|2342123|number to dial to reach this subscriber (multiple MSISDNs can be stored per subscriber), 3GPP TS 23.008 chapter 2.1.2
|
|
|imeisv|4234234234234275|identity of the mobile device and software version, 3GPP TS 23.008 chapter 2.2.3
|
|
|aud2g.algo|comp128v3|Authentication algorithm ID for GSM AKA, corresponds to enum osmo_auth_algo
|
|
|aud2g.ki||Subscriber's secret key (128bit)
|
|
|aud3g.algo|milenage|Authentication algorithm ID for UMTS AKA (applies to both 3G and 2G networks), corresponds to enum osmo_auth_algo
|
|
|aud3g.k|(32 hexadecimal digits)|Subscriber's secret key (128bit)
|
|
|aud3g.op|(32 hexadecimal digits)|Operator's secret key (128bit)
|
|
|aud3g.opc|(32 hexadecimal digits)|Secret key derived from OP and K (128bit), alternative to using OP which does not disclose OP to subscribers
|
|
|aud3g.sqn|123|Sequence number of last used key (64bit unsigned)
|
|
|aud3g.ind_bitlen|5|Nr of index bits at lower SQN end
|
|
|apn||
|
|
|vlr_number||3GPP TS 23.008 chapter 2.4.5
|
|
|msc_number||3GPP TS 23.008 chapter 2.4.6
|
|
|sgsn_number||3GPP TS 23.008 chapter 2.4.8.1
|
|
|sgsn_address||3GPP TS 23.008 chapter 2.13.10
|
|
|ggsn_number||3GPP TS 23.008 chapter 2.4.8.2
|
|
|gmlc_number||3GPP TS 23.008 chapter 2.4.9.2
|
|
|smsc_number||3GPP TS 23.008 chapter 2.4.23
|
|
|periodic_lu_tmr||3GPP TS 23.008 chapter 2.4.24
|
|
|periodic_rau_tau_tmr||3GPP TS 23.008 chapter 2.13.115
|
|
|nam_cs|1|Enable/disable voice access (3GPP TS 23.008 chapter 2.1.1.2: network access mode)
|
|
|nam_ps|0|Enable/disable data access (3GPP TS 23.008 chapter 2.1.1.2: network access mode)
|
|
|lmsi||3GPP TS 23.008 chapter 2.1.8
|
|
|ms_purged_cs|0|3GPP TS 23.008 chapter 2.7.5
|
|
|ms_purged_ps|1|3GPP TS 23.008 chapter 2.7.6
|
|
|===
|
|
|
|
=== Configuring the Subscribers Create on Demand Feature
|
|
|
|
Usually a HLR will only allow mobile equipment (ME) on the network, if the HLR
|
|
has a subscriber entry with the ME's IMSI. But OsmoHLR can also be configured to
|
|
automatically create new entries for new IMSIs, with the
|
|
`subscriber-create-on-demand` VTY option. The obvious use case is creating the
|
|
new subscriber entry and then allowing the ME to use both the CS
|
|
(Circuit Switched) and PS (Packet Switched) NAM (Network Access Mode).
|
|
|
|
.osmo-hlr.cfg
|
|
----
|
|
hlr
|
|
subscriber-create-on-demand 5 cs+ps
|
|
----
|
|
|
|
On the other hand, operators might only want to give network access to IMSIs, of
|
|
which they know the owner. In order to do that, one can set the default NAM to
|
|
`none` and manually approve new subscribers by changing the NAM (e.g. over the
|
|
VTY, see the example below).
|
|
|
|
Oftentimes it is hard to know, which IMSI belongs to which ME, but the IMEI is
|
|
readily available. If you configure your MSC to send IMEI checking requests to
|
|
the HLR, before sending location update requests, the subscribers created on
|
|
demand can also have the IMEI stored in the HLR database. With OsmoMSC, this
|
|
is done by writing `check-imei-rqd early` in the `msc` section of osmo-msc.cfg.
|
|
Then enable storing the IMEI when receiving check IMEI requests with
|
|
`store-imei` in the OsmoHLR configuration.
|
|
|
|
.osmo-msc.cfg
|
|
----
|
|
msc
|
|
check-imei-rqd early
|
|
----
|
|
|
|
.osmo-hlr.cfg
|
|
----
|
|
hlr
|
|
subscriber-create-on-demand 5 none
|
|
store-imei
|
|
----
|
|
|
|
.Example: Enabling CS and PS NAM via VTY for a known IMEI
|
|
----
|
|
OsmoHLR> enable
|
|
OsmoHLR# subscriber imei 35761300444848 show
|
|
ID: 1
|
|
IMSI: 123456789023000
|
|
MSISDN: 58192 <1>
|
|
IMEI: 35761300444848
|
|
CS disabled <2>
|
|
PS disabled <2>
|
|
OsmoHLR# subscriber imei 35761300444848 update network-access-mode cs+ps
|
|
OsmoHLR# subscriber imei 35761300444848 show
|
|
ID: 1
|
|
IMSI: 123456789023000
|
|
MSISDN: 58192
|
|
IMEI: 35761300444848
|
|
----
|
|
<1> Randomly generated 5 digit MSISDN
|
|
<2> Disabled CS and PS NAM prevent the subscriber from accessing the network
|
|
|
|
|
|
=== Import Subscriber Data
|
|
|
|
==== Scripted Import
|
|
|
|
WARNING: It is not generally a good idea to depend on the HLR database's internal table structure, but in the lack of an
|
|
automated import procedure, this example is provided as an ad-hoc method to aid automated subscriber import. This is not
|
|
guaranteed to remain valid.
|
|
|
|
NOTE: We may add CSV and other import methods to the `osmo-hlr-db-tool`, but so far that is not implemented. Contact the
|
|
community if you are interested in such a feature being implemented.
|
|
|
|
NOTE: `sqlite3` is available from your distribution packages or `sqlite.org`.
|
|
|
|
Currently, probably the easiest way to automatically import subscribers to OsmoHLR is to write out a text file with SQL
|
|
commands per subscriber, and feed that to `sqlite3`, as described below.
|
|
|
|
A difficulty is to always choose subscriber IDs that are not yet in use. For an initial import, the subscriber ID may be
|
|
incremented per subscriber record. If adding more subscribers to an existing database, it is necessary to choose
|
|
subscriber IDs that are not yet in use. Get the highest ID in use with:
|
|
|
|
----
|
|
sqlite3 hlr.db 'select max(id) from subscriber'
|
|
----
|
|
|
|
A full SQL example of adding a single subscriber with id 23, IMSI 001010123456789, MSISDN 1234, Ki for COMP128v1, and K
|
|
and OPC for Milenage:
|
|
|
|
----
|
|
INSERT subscriber (id, imsi, msisdn) VALUES (23, '001010123456789', '1234');
|
|
|
|
INSERT INTO auc_2g (subscriber_id, algo_id_2g, ki)
|
|
VALUES(23, 1, '0123456789abcdef0123456789abcdef');
|
|
|
|
INSERT INTO auc_3g (subscriber_id, algo_id_3g, k, op, opc)
|
|
VALUES(23, 5, '0123456789abcdef0123456789abcdef',NULL,'0123456789abcdef0123456789abcdef');
|
|
----
|
|
|
|
Table entries to `auc_2g` and/or `auc_3g` may be omitted if no such key material is required.
|
|
|
|
UMTS Milenage auth (on both 2G and 3G RAN) is configured by the `auc_3g` table. `algo_id_3g` must currently always be 5
|
|
(MILENAGE).
|
|
|
|
The algorithm IDs for `algo_id_2g` and `algo_id_3g` are:
|
|
|
|
.Algorithm IDs in OsmoHLR's database
|
|
[options="header",width="50%",cols="40%,60%"]
|
|
|===
|
|
|`algo_id_2g` / `algo_id_3g` | Authentication Algorithm
|
|
| 1 | COMP128v1
|
|
| 2 | COMP128v2
|
|
| 3 | COMP128v3
|
|
| 4 | XOR
|
|
| 5 | MILENAGE
|
|
|===
|
|
|
|
Create an empty HLR database with
|
|
|
|
----
|
|
osmo-hlr-db-tool -l hlr.db create
|
|
----
|
|
|
|
Repeat above SQL commands per subscriber, incrementing the subscriber ID for each block, then feed the SQL commands for
|
|
the subscribers to be imported to the `sqlite3` command line tool:
|
|
|
|
----
|
|
sqlite3 hlr.db < subscribers.sql
|
|
----
|
|
|
|
[[db_import_nitb]]
|
|
==== Import OsmoNITB database
|
|
|
|
To upgrade from old OsmoNITB to OsmoHLR, use `osmo-hlr-db-tool`:
|
|
|
|
----
|
|
osmo-hlr-db-tool -l hlr.db import-nitb-db nitb.db
|
|
----
|
|
|
|
Be aware that the import is lossy, only the IMSI, MSISDN, nam_cs/ps and 2G auth data are set.
|