Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 1 | == Managing Subscribers |
| 2 | |
| 3 | Subscribers are kept in a local SQLite database file and can be managed via VTY |
| 4 | and CTRL interfaces. |
| 5 | |
Neels Hofmeyr | 0c331ab | 2018-07-02 15:12:33 +0200 | [diff] [blame] | 6 | This section provides some examples; also refer to the OsmoHLR VTY reference |
Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 7 | manual <<vty-ref-osmohlr>> as well as the Control interface described in |
| 8 | <<hlr-ctrl>>. |
| 9 | |
| 10 | === Example: Add/Update/Delete Subscriber via VTY |
| 11 | |
Neels Hofmeyr | 0c331ab | 2018-07-02 15:12:33 +0200 | [diff] [blame] | 12 | The following telnet VTY session adds a subscriber complete with GSM (2G) and |
| 13 | UMTS (3G and 2G) authentication tokens, and finally removes the subscriber |
| 14 | again; it assumes that osmo-hlr is running and listening for telnet VTY |
| 15 | connections on localhost: |
Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 16 | |
| 17 | ---- |
| 18 | $ telnet localhost 4258 |
| 19 | include::../example_subscriber_add_update_delete.vty[] |
| 20 | ---- |
| 21 | |
| 22 | [[subscriber-params]] |
| 23 | === Subscriber Parameters |
| 24 | |
| 25 | The following parameters are managed for each subscriber of the HLR, modelled |
| 26 | roughly after 3GPP TS 23.008, version 13.3.0; note that not all of these |
Neels Hofmeyr | 0c331ab | 2018-07-02 15:12:33 +0200 | [diff] [blame] | 27 | parameters are necessarily in active use. |
| 28 | |
| 29 | The `aud3g` table also applies to 2G networks: it provides UMTS AKA tokens for |
| 30 | Milenage authentication, which is available both on 3G and 2G networks. On 2G, |
| 31 | when both MS and network are R99 capable (like OsmoMSC and OsmoSGSN are), the |
| 32 | full UMTS AKA with Milenage keys from `aud_3g`, using AUTN and extended RES |
| 33 | tokens, is available. With pre-R99 MS or network configurations, the GSM AKA |
| 34 | compatible variant of Milenage, still using the Milenage keys from `aud_3g` but |
| 35 | transceiving only RAND and SRES, may be applicable. (See 3GPP TS 33.102, chapter |
| 36 | 6.8.1, Authentication and key agreement of UMTS subscribers.) |
Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 37 | |
| 38 | .OsmoHLR's subscriber parameters |
| 39 | [options="header",width="100%",cols="20%,20%,60%"] |
| 40 | |=== |
| 41 | |Name|Example|Description |
| 42 | |imsi|901700000014701|identity of the SIM/USIM, 3GPP TS 23.008 chapter 2.1.1.1 |
| 43 | |msisdn|2342123|number to dial to reach this subscriber (multiple MSISDNs can be stored per subscriber), 3GPP TS 23.008 chapter 2.1.2 |
| 44 | |imeisv|4234234234234275|identity of the mobile device and software version, 3GPP TS 23.008 chapter 2.2.3 |
Neels Hofmeyr | 0c331ab | 2018-07-02 15:12:33 +0200 | [diff] [blame] | 45 | |aud2g.algo|comp128v3|Authentication algorithm ID for GSM AKA, corresponds to enum osmo_auth_algo |
Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 46 | |aud2g.ki||Subscriber's secret key (128bit) |
Neels Hofmeyr | 0c331ab | 2018-07-02 15:12:33 +0200 | [diff] [blame] | 47 | |aud3g.algo|milenage|Authentication algorithm ID for UMTS AKA (applies to both 3G and 2G networks), corresponds to enum osmo_auth_algo |
Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 48 | |aud3g.k|(32 hexadecimal digits)|Subscriber's secret key (128bit) |
| 49 | |aud3g.op|(32 hexadecimal digits)|Operator's secret key (128bit) |
| 50 | |aud3g.opc|(32 hexadecimal digits)|Secret key derived from OP and K (128bit), alternative to using OP which does not disclose OP to subscribers |
| 51 | |aud3g.sqn|123|Sequence number of last used key (64bit unsigned) |
| 52 | |aud3g.ind_bitlen|5|Nr of index bits at lower SQN end |
| 53 | |apn|| |
| 54 | |vlr_number||3GPP TS 23.008 chapter 2.4.5 |
Neels Hofmeyr | a8045da | 2019-10-31 01:19:44 +0100 | [diff] [blame] | 55 | |msc_number||3GPP TS 23.008 chapter 2.4.6 |
Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 56 | |sgsn_number||3GPP TS 23.008 chapter 2.4.8.1 |
| 57 | |sgsn_address||3GPP TS 23.008 chapter 2.13.10 |
| 58 | |ggsn_number||3GPP TS 23.008 chapter 2.4.8.2 |
| 59 | |gmlc_number||3GPP TS 23.008 chapter 2.4.9.2 |
| 60 | |smsc_number||3GPP TS 23.008 chapter 2.4.23 |
| 61 | |periodic_lu_tmr||3GPP TS 23.008 chapter 2.4.24 |
| 62 | |periodic_rau_tau_tmr||3GPP TS 23.008 chapter 2.13.115 |
| 63 | |nam_cs|1|Enable/disable voice access (3GPP TS 23.008 chapter 2.1.1.2: network access mode) |
| 64 | |nam_ps|0|Enable/disable data access (3GPP TS 23.008 chapter 2.1.1.2: network access mode) |
| 65 | |lmsi||3GPP TS 23.008 chapter 2.1.8 |
| 66 | |ms_purged_cs|0|3GPP TS 23.008 chapter 2.7.5 |
| 67 | |ms_purged_ps|1|3GPP TS 23.008 chapter 2.7.6 |
| 68 | |=== |
| 69 | |
Oliver Smith | c415723 | 2019-03-06 20:23:01 +0100 | [diff] [blame] | 70 | === Configuring the Subscribers Create on Demand Feature |
| 71 | |
| 72 | Usually a HLR will only allow mobile equipment (ME) on the network, if the HLR |
| 73 | has a subscriber entry with the ME's IMSI. But OsmoHLR can also be configured to |
| 74 | automatically create new entries for new IMSIs, with the |
Oliver Smith | b64cb27 | 2019-07-15 09:17:08 +0200 | [diff] [blame] | 75 | `subscriber-create-on-demand` VTY option. The obvious use case is creating the |
Oliver Smith | c415723 | 2019-03-06 20:23:01 +0100 | [diff] [blame] | 76 | new subscriber entry and then allowing the ME to use both the CS |
| 77 | (Circuit Switched) and PS (Packet Switched) NAM (Network Access Mode). |
| 78 | |
Oliver Smith | b64cb27 | 2019-07-15 09:17:08 +0200 | [diff] [blame] | 79 | .osmo-hlr.cfg |
| 80 | ---- |
| 81 | hlr |
| 82 | subscriber-create-on-demand 5 cs+ps |
| 83 | ---- |
| 84 | |
Oliver Smith | c415723 | 2019-03-06 20:23:01 +0100 | [diff] [blame] | 85 | On the other hand, operators might only want to give network access to IMSIs, of |
| 86 | which they know the owner. In order to do that, one can set the default NAM to |
Oliver Smith | b64cb27 | 2019-07-15 09:17:08 +0200 | [diff] [blame] | 87 | `none` and manually approve new subscribers by changing the NAM (e.g. over the |
| 88 | VTY, see the example below). |
Oliver Smith | c415723 | 2019-03-06 20:23:01 +0100 | [diff] [blame] | 89 | |
| 90 | Oftentimes it is hard to know, which IMSI belongs to which ME, but the IMEI is |
| 91 | readily available. If you configure your MSC to send IMEI checking requests to |
| 92 | the HLR, before sending location update requests, the subscribers created on |
| 93 | demand can also have the IMEI stored in the HLR database. With OsmoMSC, this |
Oliver Smith | b64cb27 | 2019-07-15 09:17:08 +0200 | [diff] [blame] | 94 | is done by writing `check-imei-rqd early` in the `msc` section of osmo-msc.cfg. |
Oliver Smith | c415723 | 2019-03-06 20:23:01 +0100 | [diff] [blame] | 95 | Then enable storing the IMEI when receiving check IMEI requests with |
Oliver Smith | b64cb27 | 2019-07-15 09:17:08 +0200 | [diff] [blame] | 96 | `store-imei` in the OsmoHLR configuration. |
| 97 | |
| 98 | .osmo-msc.cfg |
| 99 | ---- |
| 100 | msc |
| 101 | check-imei-rqd early |
| 102 | ---- |
| 103 | |
| 104 | .osmo-hlr.cfg |
| 105 | ---- |
| 106 | hlr |
| 107 | subscriber-create-on-demand 5 none |
| 108 | store-imei |
| 109 | ---- |
| 110 | |
| 111 | .Example: Enabling CS and PS NAM via VTY for a known IMEI |
| 112 | ---- |
| 113 | OsmoHLR> enable |
| 114 | OsmoHLR# subscriber imei 35761300444848 show |
| 115 | ID: 1 |
| 116 | IMSI: 123456789023000 |
| 117 | MSISDN: 58192 <1> |
| 118 | IMEI: 35761300444848 |
| 119 | CS disabled <2> |
| 120 | PS disabled <2> |
| 121 | OsmoHLR# subscriber imei 35761300444848 update network-access-mode cs+ps |
| 122 | OsmoHLR# subscriber imei 35761300444848 show |
| 123 | ID: 1 |
| 124 | IMSI: 123456789023000 |
| 125 | MSISDN: 58192 |
| 126 | IMEI: 35761300444848 |
| 127 | ---- |
| 128 | <1> Randomly generated 5 digit MSISDN |
| 129 | <2> Disabled CS and PS NAM prevent the subscriber from accessing the network |
Neels Hofmeyr | 80cb6c9 | 2020-06-29 17:10:03 +0200 | [diff] [blame] | 130 | |
| 131 | |
| 132 | === Import Subscriber Data |
| 133 | |
| 134 | ==== Scripted Import |
| 135 | |
| 136 | WARNING: It is not generally a good idea to depend on the HLR database's internal table structure, but in the lack of an |
| 137 | automated import procedure, this example is provided as an ad-hoc method to aid automated subscriber import. This is not |
| 138 | guaranteed to remain valid. |
| 139 | |
| 140 | NOTE: We may add CSV and other import methods to the `osmo-hlr-db-tool`, but so far that is not implemented. Contact the |
| 141 | community if you are interested in such a feature being implemented. |
| 142 | |
| 143 | NOTE: `sqlite3` is available from your distribution packages or `sqlite.org`. |
| 144 | |
| 145 | Currently, probably the easiest way to automatically import subscribers to OsmoHLR is to write out a text file with SQL |
| 146 | commands per subscriber, and feed that to `sqlite3`, as described below. |
| 147 | |
| 148 | A difficulty is to always choose subscriber IDs that are not yet in use. For an initial import, the subscriber ID may be |
| 149 | incremented per subscriber record. If adding more subscribers to an existing database, it is necessary to choose |
| 150 | subscriber IDs that are not yet in use. Get the highest ID in use with: |
| 151 | |
| 152 | ---- |
| 153 | sqlite3 hlr.db 'select max(id) from subscriber' |
| 154 | ---- |
| 155 | |
| 156 | A full SQL example of adding a single subscriber with id 23, IMSI 001010123456789, MSISDN 1234, Ki for COMP128v1, and K |
| 157 | and OPC for Milenage: |
| 158 | |
| 159 | ---- |
| 160 | INSERT subscriber (id, imsi, msisdn) VALUES (23, '001010123456789', '1234'); |
| 161 | |
| 162 | INSERT INTO auc_2g (subscriber_id, algo_id_2g, ki) |
| 163 | VALUES(23, 1, '0123456789abcdef0123456789abcdef'); |
| 164 | |
| 165 | INSERT INTO auc_3g (subscriber_id, algo_id_3g, k, op, opc) |
| 166 | VALUES(23, 5, '0123456789abcdef0123456789abcdef',NULL,'0123456789abcdef0123456789abcdef'); |
| 167 | ---- |
| 168 | |
| 169 | Table entries to `auc_2g` and/or `auc_3g` may be omitted if no such key material is required. |
| 170 | |
| 171 | UMTS Milenage auth (on both 2G and 3G RAN) is configured by the `auc_3g` table. `algo_id_3g` must currently always be 5 |
| 172 | (MILENAGE). |
| 173 | |
| 174 | The algorithm IDs for `algo_id_2g` and `algo_id_3g` are: |
| 175 | |
| 176 | .Algorithm IDs in OsmoHLR's database |
| 177 | [options="header",width="50%",cols="40%,60%"] |
| 178 | |=== |
| 179 | |`algo_id_2g` / `algo_id_3g` | Authentication Algorithm |
| 180 | | 1 | COMP128v1 |
| 181 | | 2 | COMP128v2 |
| 182 | | 3 | COMP128v3 |
| 183 | | 4 | XOR |
| 184 | | 5 | MILENAGE |
| 185 | |=== |
| 186 | |
| 187 | Create an empty HLR database with |
| 188 | |
| 189 | ---- |
| 190 | osmo-hlr-db-tool -l hlr.db create |
| 191 | ---- |
| 192 | |
| 193 | Repeat above SQL commands per subscriber, incrementing the subscriber ID for each block, then feed the SQL commands for |
| 194 | the subscribers to be imported to the `sqlite3` command line tool: |
| 195 | |
| 196 | ---- |
| 197 | sqlite3 hlr.db < subscribers.sql |
| 198 | ---- |
| 199 | |
| 200 | [[db_import_nitb]] |
| 201 | ==== Import OsmoNITB database |
| 202 | |
| 203 | To upgrade from old OsmoNITB to OsmoHLR, use `osmo-hlr-db-tool`: |
| 204 | |
| 205 | ---- |
| 206 | osmo-hlr-db-tool -l hlr.db import-nitb-db nitb.db |
| 207 | ---- |
| 208 | |
| 209 | Be aware that the import is lossy, only the IMSI, MSISDN, nam_cs/ps and 2G auth data are set. |