Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 1 | [[hlr-ctrl]] |
| 2 | == Control interface |
| 3 | |
| 4 | The actual protocol is described in <<common-control-if>>, the variables common |
| 5 | to all programs using it are described in <<ctrl_common_vars>>. This section |
| 6 | describes the CTRL interface variables specific to OsmoHLR. |
| 7 | |
Pau Espin Pedrol | 3863816 | 2022-06-20 20:11:03 +0200 | [diff] [blame] | 8 | Subscribers can be created and deleted using the following SET commands: |
| 9 | |
| 10 | .Subscriber management commands available on OsmoHLR's Control interface |
| 11 | [options="header",width="100%",cols="35%,65%"] |
| 12 | |=== |
| 13 | |Command|Comment |
| 14 | |subscriber.create '123456'|Create a new subscriber with IMSI "123456" to the database. Returns database ID of the subscriber being created. |
| 15 | |subscriber.delete '123456'|Delete subscriber with IMSI "123456" from database. Returns database ID of the subscriber being deleted. |
| 16 | |=== |
| 17 | |
Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 18 | All subscriber variables are available by different selectors, which are freely |
| 19 | interchangeable: |
| 20 | |
| 21 | .Subscriber selectors available on OsmoHLR's Control interface |
| 22 | [options="header",width="100%",cols="35%,65%"] |
| 23 | |=== |
| 24 | |Selector|Comment |
| 25 | |subscriber.*by-imsi-*'123456'.*|Subscriber selector by IMSI, replace "123456" with the actual IMSI |
| 26 | |subscriber.*by-msisdn-*'123456'.*|Subscriber selector by MSISDN |
| 27 | |subscriber.*by-id-*'123456'.*|Subscriber selector by database ID |
| 28 | |=== |
| 29 | |
| 30 | Each of the above selectors feature all of these control variables: |
| 31 | |
| 32 | .Subscriber variables available on OsmoHLR's Control interface |
| 33 | [options="header",width="100%",cols="35%,8%,8%,8%,41%"] |
| 34 | |=== |
| 35 | |Name|Access|Trap|Value|Comment |
| 36 | |subscriber.by-\*.*info*|R|No||List (short) subscriber information |
| 37 | |subscriber.by-\*.*info-aud*|R|No||List subscriber authentication tokens |
| 38 | |subscriber.by-\*.*info-all*|R|No||List both 'info' and 'info-aud' in one |
| 39 | |subscriber.by-\*.*cs-enabled*|RW|No|'1' or '0'|Enable/disable circuit-switched access |
| 40 | |subscriber.by-\*.*ps-enabled*|RW|No|'1' or '0'|Enable/disable packet-switched access |
Pau Espin Pedrol | 3863816 | 2022-06-20 20:11:03 +0200 | [diff] [blame] | 41 | |subscriber.by-\*.*msisdn*|RW|No|valid MSISDN string|Get/Set assigned MSISDN |
| 42 | |subscriber.by-\*.*aud2g*|RW|No|'algo[,KI]'|Get/Set 2g Authentication Data |
| 43 | |subscriber.by-\*.*aud2g*|RW|No|'algo[,KI,("op"|"opc"),OP_C[,ind_bitlen]]'|Get/Set 3g Authentication Data |
Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 44 | |=== |
| 45 | |
| 46 | === subscriber.by-*.info, info-aud, info-all |
| 47 | |
| 48 | Query the HLR database and return current subscriber record, in multiple lines |
| 49 | of the format |
| 50 | |
| 51 | ---- |
| 52 | name<tab>value |
| 53 | ---- |
| 54 | |
Neels Hofmeyr | 7e2d3c7 | 2017-10-24 15:47:12 +0200 | [diff] [blame] | 55 | To keep the reply as short as possible, some values are omitted if they are |
| 56 | empty. These are the returned values and their presence |
Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 57 | modalities; for their meaning, see <<subscriber-params>>: |
| 58 | |
| 59 | .Returned values by OsmoHLR's 'info', 'info-all' and 'info-aud' commands |
| 60 | [options="header",width="100%",cols="15%,15%,30%,40%"] |
| 61 | |=== |
| 62 | |Returned by 'info-all' and|Name|Format|Presence |
| 63 | |'info'|id|-9223372036854775808 .. 9223372036854775807 (usually not negative)|always |
| 64 | |'info'|imsi|6 to 15 decimal digits|always |
| 65 | |'info'|msisdn|1 to 15 decimal digits|when non-empty |
Neels Hofmeyr | 7e2d3c7 | 2017-10-24 15:47:12 +0200 | [diff] [blame] | 66 | |'info'|nam_cs|'1' if CS is enabled, or '0'|always |
| 67 | |'info'|nam_ps|'1' if PS is enabled, or '0'|always |
Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 68 | |'info'|vlr_number|up to 15 decimal digits|when non-empty |
| 69 | |'info'|sgsn_number|up to 15 decimal digits|when non-empty |
| 70 | |'info'|sgsn_address||when non-empty |
Neels Hofmeyr | 7e2d3c7 | 2017-10-24 15:47:12 +0200 | [diff] [blame] | 71 | |'info'|ms_purged_cs|'1' if CS is purged, or '0'|always |
| 72 | |'info'|ms_purged_ps|'1' if PS is purged, or '0'|always |
| 73 | |'info'|periodic_lu_timer|0..4294967295|always |
| 74 | |'info'|periodic_rau_tau_timer|0..4294967295|always |
| 75 | |'info'|lmsi|8 hex digits|always |
Neels Hofmeyr | 25dd785 | 2017-09-25 16:37:34 +0200 | [diff] [blame] | 76 | |'info-aud'|aud2g.algo|one of 'comp128v1', 'comp128v2', 'comp128v3' or 'xor'|when valid 2G auth data is set |
| 77 | |'info-aud'|aud2g.ki|32 hexadecimal digits|when valid 2G auth data is set |
| 78 | |'info-aud'|aud3g.algo|so far always 'milenage'|when valid 3G auth data is set |
| 79 | |'info-aud'|aud3g.k|32 hexadecimal digits|when valid 3G auth data is set |
| 80 | |'info-aud'|aud3g.op|32 hexadecimal digits|when valid 3G auth data is set, *not* when OPC is set |
| 81 | |'info-aud'|aud3g.opc|32 hexadecimal digits|when valid 3G auth data is set, *not* when OP is set |
| 82 | |'info-aud'|aud3g.ind_bitlen|0..28|when valid 3G auth data is set |
| 83 | |'info-aud'|aud3g.sqn|0 .. 18446744073709551615|when valid 3G auth data is set |
| 84 | |=== |
| 85 | |
| 86 | This is an example Control Interface transcript that illustrates the various |
| 87 | 'info' commands: |
| 88 | |
| 89 | ---- |
| 90 | include::../example_subscriber_info.ctrl[] |
| 91 | ---- |
| 92 | |
| 93 | === subscriber.by-*.ps-enabled, cs-enabled |
| 94 | |
| 95 | Disable or enable packet-/circuit-switched access for the given IMSI; |
| 96 | |
| 97 | * 'ps-enabled' switches access to GPRS or UMTS data services, |
| 98 | * 'cs-enabled' switches access to voice services. |
| 99 | |
| 100 | When disabled, the next time this subscriber attempts to do a Location Updating |
| 101 | GSUP operation for the given domain (i.e. from the SGSN for 'ps-enabled', from |
| 102 | the MSC/VLR for 'cs-enabled'), it will be rejected by OsmoHLR. Currently |
| 103 | connected GSUP clients will be notified via GSUP when a subscriber is being |
| 104 | disabled, so that the subscriber can be dropped in case it is currently |
| 105 | attached. |
| 106 | |
| 107 | The current 'ps-enabled'/'cs-enabled' status can be queried by 'GET' commands, |
| 108 | and also by looking at 'nam_ps' and 'nam_cs' in a 'subscriber.by-*.info' |
| 109 | response. |
| 110 | |
| 111 | A value of "1" indicates that the given domain is enabled, which is the |
| 112 | default; a value of "0" disables access. |
| 113 | |
| 114 | This is an example transcript that illustrates 'ps-enabled' and 'cs-enabled' |
| 115 | commands: |
| 116 | |
| 117 | ---- |
| 118 | include::../example_subscriber_cs_ps_enabled.ctrl[] |
| 119 | ---- |
Pau Espin Pedrol | 3863816 | 2022-06-20 20:11:03 +0200 | [diff] [blame] | 120 | |
| 121 | === subscriber.by-*.msisdn |
| 122 | |
| 123 | Get or set the MSISDN currently assigned to a subscriber. |
| 124 | |
| 125 | |
| 126 | This is an example transcript that illustrates use of this command: |
| 127 | |
| 128 | ---- |
| 129 | include::../example_subscriber_msisdn.ctrl[] |
| 130 | ---- |
| 131 | |
| 132 | === subscriber.by-*.aud2g |
| 133 | |
| 134 | Get or set the 2G Authentication data of a subscriber. |
| 135 | |
| 136 | The information is stored/retrieved as a comma separated list of fields: |
| 137 | |
| 138 | ---- |
| 139 | algo[,KI] |
| 140 | ---- |
| 141 | |
| 142 | Where:: |
| 143 | * *KI* is the KI as a hexadecimal string. |
| 144 | * *algo* is one of the following algorithms: _none, xor, comp128v1, comp128v2, |
| 145 | comp128v3_. |
| 146 | |
| 147 | All values are case insensitive. |
| 148 | |
| 149 | This is an example transcript that illustrates use of this command: |
| 150 | |
| 151 | ---- |
| 152 | include::../example_subscriber_aud2g.ctrl[] |
| 153 | ---- |
| 154 | |
| 155 | === subscriber.by-*.aud3g |
| 156 | |
| 157 | Get or set the 3G Authentication data of a subscriber. |
| 158 | |
| 159 | The information is stored/retrieved as a comma separated list of fields: |
| 160 | |
| 161 | ---- |
| 162 | algo[,KI,("op"|"opc"),OP_C[,ind_bitlen]] |
| 163 | ---- |
| 164 | |
| 165 | Where: |
| 166 | * *KI* is the KI as a hexadecimal string. |
| 167 | * *algo* is one of the following algorithms: _none, xor, milenage_. |
| 168 | * "op" or "opc" indicates whether next field is an OP or OPC value. |
| 169 | * *OP_C* contains an OP or OPC values as hexadecimal string, based on what the |
| 170 | previous field specifies. |
| 171 | * *ind_bitlen* is set to 5 by default if not provided. |
| 172 | |
| 173 | All values are case insensitive. |
| 174 | |
| 175 | This is an example transcript that illustrates use of this command: |
| 176 | |
| 177 | ---- |
| 178 | include::../example_subscriber_aud3g.ctrl[] |
| 179 | ---- |