From 7898364664a4423b0e40fe556caddeb70708eec8 Mon Sep 17 00:00:00 2001 From: Oliver Smith Date: Wed, 28 Nov 2018 10:45:40 +0100 Subject: remove OsmoHLR files (now avail in osmo-hlr.git) Files were added in osmo-hlr.git Change-Id I52b7b06fddd77c6dc272004f434e9e7651f6b349 Depends: osmo-hlr.git Change-Id I52b7b06fddd77c6dc272004f434e9e7651f6b349 Related: OS#3385 Change-Id: Ice3f24888deed8affec40d5d91d71d5e1f3827c8 --- OsmoHLR/chapters/control.adoc | 106 -------------------------------------- OsmoHLR/chapters/overview.adoc | 69 ------------------------- OsmoHLR/chapters/running.adoc | 80 ---------------------------- OsmoHLR/chapters/subscribers.adoc | 69 ------------------------- OsmoHLR/chapters/ussd.adoc | 78 ---------------------------- 5 files changed, 402 deletions(-) delete mode 100644 OsmoHLR/chapters/control.adoc delete mode 100644 OsmoHLR/chapters/overview.adoc delete mode 100644 OsmoHLR/chapters/running.adoc delete mode 100644 OsmoHLR/chapters/subscribers.adoc delete mode 100644 OsmoHLR/chapters/ussd.adoc (limited to 'OsmoHLR/chapters') diff --git a/OsmoHLR/chapters/control.adoc b/OsmoHLR/chapters/control.adoc deleted file mode 100644 index 50fd314..0000000 --- a/OsmoHLR/chapters/control.adoc +++ /dev/null @@ -1,106 +0,0 @@ -[[hlr-ctrl]] -== Control interface - -The actual protocol is described in <>, the variables common -to all programs using it are described in <>. This section -describes the CTRL interface variables specific to OsmoHLR. - -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-*.info, info-aud, info-all - -Query the HLR database and return current subscriber record, in multiple lines -of the format - ----- -namevalue ----- - -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 <>: - -.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[] ----- diff --git a/OsmoHLR/chapters/overview.adoc b/OsmoHLR/chapters/overview.adoc deleted file mode 100644 index 45802ca..0000000 --- a/OsmoHLR/chapters/overview.adoc +++ /dev/null @@ -1,69 +0,0 @@ -[[overview]] -== Overview - -This manual should help you getting started with OsmoHLR. It will cover -aspects of configuring and running the OsmoHLR. - -[[intro_overview]] -=== About OsmoHLR - -OsmoHLR is Osmocom's minimal implementation of a Home Location Register (HLR) -for 2G and 3G GSM and UMTS mobile core networks. Its interfaces are: - -- GSUP, serving towards OsmoMSC and OsmoSGSN; -- A local SQLite database; -- The Osmocom typical telnet VTY and CTRL interfaces. - -Originally, the OpenBSC project's OsmoNITB all-in-one implementation had an -integrated HLR, managing subscribers and SMS in the same local database. Along -with the separate OsmoMSC and its new VLR component, OsmoHLR was implemented -from scratch to alleviate various shortcomings of the internal HLR: - -- The separate HLR allows using centralized subscriber management for both - circuit-switched and packet-switched domains (i.e. one OsmoHLR for both - OsmoMSC and OsmoSGSN). - -- VLR and HLR brought full UMTS AKA (Authentication and Key Agreement) support, - i.e. Milenage authentication in both the full 3G variant as well as the - backwards compatible 2G variant. - -- In contrast to the OsmoNITB, the specific way the new OsmoMSC's VLR accesses - OsmoHLR brings fully asynchronous subscriber database access. - -Find the OsmoHLR issue tracker and wiki online at - -- https://osmocom.org/projects/osmo-hlr -- https://osmocom.org/projects/osmo-hlr/wiki - - -[[fig-gsm]] -.Typical GSM network architecture used with OsmoHLR -[graphviz] ----- -digraph G { - rankdir=LR; - subgraph cluster_hlr { - label = "OsmoHLR"; - GSUP [label="GSUP server"] - DB [label="SQLite DB"] - GSUP->DB - DB->CTRL [dir="back"] - DB->VTY [dir="back"] - } - - Admin [label="Admin and\nMaintenance"] - SW [label="3rd party software\nintegration"] - VTY->Admin [dir="back"] - CTRL->SW [dir="back"] - - MSC [label="MSC/VLR"] - MSC->GSUP [label="GSUP"] - SGSN->GSUP [label="GSUP"] - - BSC->MSC - HNBGW->MSC - HNBGW->SGSN - PCU->SGSN -} ----- - diff --git a/OsmoHLR/chapters/running.adoc b/OsmoHLR/chapters/running.adoc deleted file mode 100644 index 5f24746..0000000 --- a/OsmoHLR/chapters/running.adoc +++ /dev/null @@ -1,80 +0,0 @@ -== Running OsmoHLR - -The OsmoHLR executable (`osmo-hlr`) offers the following command-line -arguments: - -=== SYNOPSIS - -*osmo-hlr* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL'] [-l 'DATABASE'] - -=== OPTIONS - -*-h, --help*:: - Print a short help message about the supported options -*-V, --version*:: - Print the compile-time version number of the OsmoBTS program -*-d, --debug 'DBGMASK','DBGLEVELS'*:: - Set the log subsystems and levels for logging to stderr. This - has mostly been superseded by VTY-based logging configuration, - see <> for further information. -*-D, --daemonize*:: - Fork the process as a daemon into background. -*-c, --config-file 'CONFIGFILE'*:: - Specify the file and path name of the configuration file to be - used. If none is specified, use `osmo-hlr.cfg` in the current - working directory. -*-s, --disable-color*:: - Disable colors for logging to stderr. This has mostly been - deprecated by VTY based logging configuration, see <> - for more information. -*-T, --timestamp*:: - Enable time-stamping of log messages to stderr. This has mostly - been deprecated by VTY based logging configuration, see - <> for more information. -*-e, --log-level 'LOGLEVEL'*:: - Set the global log level for logging to stderr. This has mostly - been deprecated by VTY based logging configuration, see - <> for more information. -*-l, --database 'DATABASE'*:: - Specify the file name of the SQLite3 database to use as HLR/AUC - storage - -=== Bootstrap the Database - -If no database exists yet, OsmoHLR will automatically create and bootstrap a -database file with empty tables. If no `-l` command-line option is provided, -this database file will be created in the current working directory. - -Alternatively, you may use the `osmo-hlr-db-tool`, which is installed along -with `osmo-hlr`, to bootstrap an empty database, or to migrate subscriber data -from an old 'OsmoNITB' database. See `osmo-hlr-db-tool --help`. - -=== Multiple instances - -Running multiple instances of `osmo-hlr` on the same computer is possible if -all interfaces (VTY, CTRL) are separated using the appropriate configuration -options. The IP based interfaces are binding to local host by default. In order -to separate the processes, the user has to bind those services to specific but -different IP addresses and/or ports. - -The VTY and the Control interface can be bound to IP addresses from the loopback -address range, for example: - ----- -line vty - bind 127.0.0.2 -ctrl - bind 127.0.0.2 ----- - -The GSUP interface can be bound to a specific IP address by the following -configuration options: - ----- -hlr - gsup - bind ip 10.23.42.1 ----- - -NOTE: At the time of writing, OsmoHLR lacks a config option to change the GSUP -port, which is by default TCP port 4222. diff --git a/OsmoHLR/chapters/subscribers.adoc b/OsmoHLR/chapters/subscribers.adoc deleted file mode 100644 index bb57d24..0000000 --- a/OsmoHLR/chapters/subscribers.adoc +++ /dev/null @@ -1,69 +0,0 @@ -== 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 <> as well as the Control interface described in -<>. - -=== 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 -|hlr_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 -|=== - diff --git a/OsmoHLR/chapters/ussd.adoc b/OsmoHLR/chapters/ussd.adoc deleted file mode 100644 index be463ac..0000000 --- a/OsmoHLR/chapters/ussd.adoc +++ /dev/null @@ -1,78 +0,0 @@ -[[ussd]] -== Unstructured Supplementary Services Data (USSD) - -The _Unstructured Supplementary Services Data (USSD)_ is one service within -2G/3G networks next to other services such as circuit-switched voice, packet-switched -data and SMS (Short Message Service). - -It is on an abstract level quite similar to SMS in that USSD can be used to send -textual messages. However, there are the following differences: - -* USSD is between the MS (phone) and an USSD application on the network, while - SMS is primarily between two subscribers identified by their MSISDN -* USSD is faster, as it doesn't suffer from the complicated three-layer CP/RP/TP - protocol stack of SMS with it's acknowledgement of the acknowledged acknowledgement. -* USSD is session-oriented, i.e. a dialogue/session between subscriber and application - can persist for the transfer of more than one message. The dedicated radio channel - on the RAN remains established throughout that dialogue. - -=== USSD in Osmocom - -Until August 2018, OsmoMSC contained some minimalistic internal USSD -handling with no -ability to attach/extend it with external USSD applications. - -From August 2018 onwards, OsmoMSC doesn't contain any internal USSD -handlers/applications anymore. Instead, all USSD is transported to/from -OsmoHLR via the GSUP protocol. - -OsmoHLR contains some intenal USSD handlers and can route USSD messages -to any number of external USSD entities (EUSEs). The EUSE also use GSUP -to communicate USSD from/to OsmoHLR. - -Each EUSE is identified by its name. The name consists of a single-word -string preceding a currently fixed ("-00-00-00-00-00-00") suffix. -There is no authentication between EUSE and OsmoHLR: Any client program -able to connect to the GSUP port of OsmoHLR can register as any EUSE -(name). - -NOTE:: We plan to remove the requirement for this suffix as soon as we -are done resolving all more important issues. - -=== USSD Configuration - -USSD configuration in OsmoHLR happens within the `hlr` VTY node. - -`euse foobar-00-00-00-00-00-00` defines an EUSE with the given name `foobar` - -`ussd route prefix *123 external foobar-00-00-00-00-00-00` installs a -prefix route to the named EUSE. All USSD short codes starting with *123 will be -routed to the named EUSE. - -`ussd route prefix *#100# internal own-msisdn` installs a prefix route -to the named internal USSD handler. There above command will restore -the old behavior, in which *#100# will return a text message containing -the subscribers own phone number. There is one other handler called -`own-imsi` which will return the IMSI instead of the MSISDN. - -`ussd default-route external foobar-00-00-00-00-00-00` installs a -default route to the named EUSE. This means that all USSD codes for -which no more specific route exists will be routed to the named EUSE. - -=== Example EUSE program - -We have provided an example EUSE developed in C language using existing -Osmocom libraries for GSUP protocol handling and USSD encoding/decoding. -It will register as `foobar` EUSE to OsmoHLR on localhost. You can run -it on a different machine by specifying e.g. `osmo-euse-demo 1.2.3.4 5678` -to make it connect to OsmoHLR on IP address 1.2.3.4 and GSUP/TCP port -5678. - -The idea is that you can use this as a template to develop your own USSD -applications, or any gateways to other protocols or interfaces. - -You can find it in `osmo-hlr/src/osmo-euse-demo.c` or online by -following the link to http://git.osmocom.org/osmo-hlr/tree/src/osmo-euse-demo.c - -This demonstration program will echo back any USSD message sent/routed -to it, quoted like _You sent "..."_. -- cgit v1.2.3