osmo-hlr/doc/manuals/chapters/control.adoc

180 lines
6.4 KiB
Plaintext

[[hlr-ctrl]]
== Control interface
The actual protocol is described in <<common-control-if>>, the variables common
to all programs using it are described in <<ctrl_common_vars>>. This section
describes the CTRL interface variables specific to OsmoHLR.
Subscribers can be created and deleted using the following SET commands:
.Subscriber management commands available on OsmoHLR's Control interface
[options="header",width="100%",cols="35%,65%"]
|===
|Command|Comment
|subscriber.create '123456'|Create a new subscriber with IMSI "123456" to the database. Returns database ID of the subscriber being created.
|subscriber.delete '123456'|Delete subscriber with IMSI "123456" from database. Returns database ID of the subscriber being deleted.
|===
All subscriber variables are available by different selectors, which are freely
interchangeable:
.Subscriber selectors available on OsmoHLR's Control interface
[options="header",width="100%",cols="35%,65%"]
|===
|Selector|Comment
|subscriber.*by-imsi-*'123456'.*|Subscriber selector by IMSI, replace "123456" with the actual IMSI
|subscriber.*by-msisdn-*'123456'.*|Subscriber selector by MSISDN
|subscriber.*by-id-*'123456'.*|Subscriber selector by database ID
|===
Each of the above selectors feature all of these control variables:
.Subscriber variables available on OsmoHLR's Control interface
[options="header",width="100%",cols="35%,8%,8%,8%,41%"]
|===
|Name|Access|Trap|Value|Comment
|subscriber.by-\*.*info*|R|No||List (short) subscriber information
|subscriber.by-\*.*info-aud*|R|No||List subscriber authentication tokens
|subscriber.by-\*.*info-all*|R|No||List both 'info' and 'info-aud' in one
|subscriber.by-\*.*cs-enabled*|RW|No|'1' or '0'|Enable/disable circuit-switched access
|subscriber.by-\*.*ps-enabled*|RW|No|'1' or '0'|Enable/disable packet-switched access
|subscriber.by-\*.*msisdn*|RW|No|valid MSISDN string|Get/Set assigned MSISDN
|subscriber.by-\*.*aud2g*|RW|No|'algo[,KI]'|Get/Set 2g Authentication Data
|subscriber.by-\*.*aud2g*|RW|No|'algo[,KI,("op"|"opc"),OP_C[,ind_bitlen]]'|Get/Set 3g Authentication Data
|===
=== subscriber.by-*.info, info-aud, info-all
Query the HLR database and return current subscriber record, in multiple lines
of the format
----
name<tab>value
----
To keep the reply as short as possible, some values are omitted if they are
empty. These are the returned values and their presence
modalities; for their meaning, see <<subscriber-params>>:
.Returned values by OsmoHLR's 'info', 'info-all' and 'info-aud' commands
[options="header",width="100%",cols="15%,15%,30%,40%"]
|===
|Returned by 'info-all' and|Name|Format|Presence
|'info'|id|-9223372036854775808 .. 9223372036854775807 (usually not negative)|always
|'info'|imsi|6 to 15 decimal digits|always
|'info'|msisdn|1 to 15 decimal digits|when non-empty
|'info'|nam_cs|'1' if CS is enabled, or '0'|always
|'info'|nam_ps|'1' if PS is enabled, or '0'|always
|'info'|vlr_number|up to 15 decimal digits|when non-empty
|'info'|sgsn_number|up to 15 decimal digits|when non-empty
|'info'|sgsn_address||when non-empty
|'info'|ms_purged_cs|'1' if CS is purged, or '0'|always
|'info'|ms_purged_ps|'1' if PS is purged, or '0'|always
|'info'|periodic_lu_timer|0..4294967295|always
|'info'|periodic_rau_tau_timer|0..4294967295|always
|'info'|lmsi|8 hex digits|always
|'info-aud'|aud2g.algo|one of 'comp128v1', 'comp128v2', 'comp128v3' or 'xor'|when valid 2G auth data is set
|'info-aud'|aud2g.ki|32 hexadecimal digits|when valid 2G auth data is set
|'info-aud'|aud3g.algo|so far always 'milenage'|when valid 3G auth data is set
|'info-aud'|aud3g.k|32 hexadecimal digits|when valid 3G auth data is set
|'info-aud'|aud3g.op|32 hexadecimal digits|when valid 3G auth data is set, *not* when OPC is set
|'info-aud'|aud3g.opc|32 hexadecimal digits|when valid 3G auth data is set, *not* when OP is set
|'info-aud'|aud3g.ind_bitlen|0..28|when valid 3G auth data is set
|'info-aud'|aud3g.sqn|0 .. 18446744073709551615|when valid 3G auth data is set
|===
This is an example Control Interface transcript that illustrates the various
'info' commands:
----
include::../example_subscriber_info.ctrl[]
----
=== subscriber.by-*.ps-enabled, cs-enabled
Disable or enable packet-/circuit-switched access for the given IMSI;
* 'ps-enabled' switches access to GPRS or UMTS data services,
* 'cs-enabled' switches access to voice services.
When disabled, the next time this subscriber attempts to do a Location Updating
GSUP operation for the given domain (i.e. from the SGSN for 'ps-enabled', from
the MSC/VLR for 'cs-enabled'), it will be rejected by OsmoHLR. Currently
connected GSUP clients will be notified via GSUP when a subscriber is being
disabled, so that the subscriber can be dropped in case it is currently
attached.
The current 'ps-enabled'/'cs-enabled' status can be queried by 'GET' commands,
and also by looking at 'nam_ps' and 'nam_cs' in a 'subscriber.by-*.info'
response.
A value of "1" indicates that the given domain is enabled, which is the
default; a value of "0" disables access.
This is an example transcript that illustrates 'ps-enabled' and 'cs-enabled'
commands:
----
include::../example_subscriber_cs_ps_enabled.ctrl[]
----
=== subscriber.by-*.msisdn
Get or set the MSISDN currently assigned to a subscriber.
This is an example transcript that illustrates use of this command:
----
include::../example_subscriber_msisdn.ctrl[]
----
=== subscriber.by-*.aud2g
Get or set the 2G Authentication data of a subscriber.
The information is stored/retrieved as a comma separated list of fields:
----
algo[,KI]
----
Where::
* *KI* is the KI as a hexadecimal string.
* *algo* is one of the following algorithms: _none, xor, comp128v1, comp128v2,
comp128v3_.
All values are case insensitive.
This is an example transcript that illustrates use of this command:
----
include::../example_subscriber_aud2g.ctrl[]
----
=== subscriber.by-*.aud3g
Get or set the 3G Authentication data of a subscriber.
The information is stored/retrieved as a comma separated list of fields:
----
algo[,KI,("op"|"opc"),OP_C[,ind_bitlen]]
----
Where:
* *KI* is the KI as a hexadecimal string.
* *algo* is one of the following algorithms: _none, xor, milenage_.
* "op" or "opc" indicates whether next field is an OP or OPC value.
* *OP_C* contains an OP or OPC values as hexadecimal string, based on what the
previous field specifies.
* *ind_bitlen* is set to 5 by default if not provided.
All values are case insensitive.
This is an example transcript that illustrates use of this command:
----
include::../example_subscriber_aud3g.ctrl[]
----