aboutsummaryrefslogtreecommitdiffstats
path: root/OsmoHLR/chapters
diff options
context:
space:
mode:
Diffstat (limited to 'OsmoHLR/chapters')
-rw-r--r--OsmoHLR/chapters/control.adoc106
-rw-r--r--OsmoHLR/chapters/overview.adoc69
-rw-r--r--OsmoHLR/chapters/running.adoc80
-rw-r--r--OsmoHLR/chapters/subscribers.adoc69
-rw-r--r--OsmoHLR/chapters/ussd.adoc78
5 files changed, 0 insertions, 402 deletions
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 <<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.
-
-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
-
-----
-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[]
-----
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 <<logging>> 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 <<logging>>
- for more information.
-*-T, --timestamp*::
- Enable time-stamping of log messages to stderr. This has mostly
- been deprecated by VTY based logging configuration, see
- <<logging>> 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
- <<logging>> 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 <<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
-|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 "..."_.