OsmoNITB HLR: expand on how to create subscribers

1 files changed, 105 insertions, 18 deletions

diff --git a/doc/manuals/chapters/hlr.adoc b/doc/manuals/chapters/hlr.adoc
index d630969aa..8f2840a6e 100644
--- a/doc/manuals/chapters/hlr.adoc
+++ b/doc/manuals/chapters/hlr.adoc
@@ -15,7 +15,6 @@ BAOC.
 At this time, the only supported database back end for the OsmoNITB
 internal HLR/AUC is the file-based SQL database SQLite3.
 
-
 === Authorization Policy
 
 Authorization determines how subscribers can access your network.  This
@@ -123,33 +122,121 @@ OpenBSC> show subscriber extension 2342
 
 A subscriber can be added to the network in different ways:
 
-* direct insert into SQL database by external program
-* semi-automatic from the VTY
+. authorizing an auto-generated subscriber
+. manually creating a subscriber using VTY commands
+. manually creating subscriber by insert into SQL database by external program
+
+==== Authorizing an auto-generated subscriber
+
+If the `subscriber-create-on-demand` configuration option is set in the `nitb`
+VTY config node, then OsmoNITB will automatically create a subscriber record
+for every IMSI that ever tries to perform a LOCATION UPDATE with the network.
+However, those subscriber records are marked as "not authorized", i.e.  they
+will not be able to use your network.
+
+You can latter on _authorize_ any such a subscriber using the `subscriber IMSI
+...  authorized 1` command at the VTY enable node.
+
+.Example: Authorizing an auto-generated subscriber
+----
+OpenBSC> enable
+OpenBSC# configure terminal
+OpenBSC(config)# nitb
+OpenBSC(config-nitb)# subscriber-create-on-demand <1>
+OpenBSC(config-nitb)# end
+OpenBSC# <2>
+OpenBSC# subscriber imsi 262420123456789 authorized 1 <3>
+----
+<1> We first ensure that `subscriber-create-on-demand` is active
+<2> At this time we ensure that the MS with IMSI 262420123456789 performs a
+    location update to our network, e.g. by powering up the associated phone
+    followed by manual operator selection
+<3> Here we authorize that ISMI
 
-In most applications, the subscribers will be pre-provisioned by direct
-insertion into the SQL database.  This can be done by a custom program,
-the SQL schema is visible from the `.schema` command on the sqlite3
-command-line program, and there are several scripts included in the
-OpenBSC source code, written in both Python as well as Perl language.
+The above method implies that you know the IMSI stored on the SIM card of the
+subscriber that you want to to authorize. Unfortunately there is no easy/standard
+way to obtain the IMSI on most phones.  If the phone has an AT-command
+interface, you may try `AT+CIMI`.  You can also read the IMSI off the SIM using
+a PC-attached smart card reader.
 
-In case you are obtaining pre-provisioned SIM cards from sysmocom: They
-will ship with a HLR SQL database containing the subscriber records.
+NOTE: Contrary to classic GSM networks and for historic reasons, this behavior
+is the default behavior of OsmoNITB.  For production networks with a closed
+subscriber base, it is strongly recommended to use the `no
+subscriber-create-on-demand` option at the `nitb` VTY config node.
 
-If you prefer to program the SIM cards yourself, you can use the pySim
+==== Manually creating a subscriber from the VTY
+
+You can manually add a subscriber to the HLR by VTY commands.  To do so, yo
+will need to know at the minimum the IMSI of the subscriber.
+
+.Example: Create a new subscriber for IMSI 262429876543210
+----
+OpenBSC# subscriber create imsi 262429876543210
+    ID: 3, Authorized: 0 <1>
+    Extension: 22150 <2>
+    LAC: 0/0x0 <3>
+    IMSI: 262429876543210
+    Expiration Time: Thu, 01 Jan 1970 01:00:00 +0100
+    Paging: not paging Requests: 0
+    Use count: 1
+OpenBSC# subscriber imsi 262429876543210 authorized 1 <4>
+OpenBSC# subscriber imsi 262429876543210 extension 23234242 <5>
+OpenBSC# subscriber imsi 262429876543210 name Sub Scriber <6>
+OpenBSC# show subscriber imsi 262429876543210 <7>
+    ID: 3, Authorized: 1
+    Name: 'Sub Scriber'
+    Extension: 23234242
+    LAC: 0/0x0
+    IMSI: 262429876543210
+    Expiration Time: Thu, 01 Jan 1970 01:00:00 +0100
+    Paging: not paging Requests: 0
+    Use count: 1
+----
+<1> as you can see, a newly-created subscriber is not automatically authorized.
+    We will change this in the next step.
+<2> the NITB has automatically allocated a random 5-digit extension (MSISDN)
+<3> Location Area Code 0 means that this subscriber is currently not registered on the network
+<4> Authorize the subscriber
+<5> Change the extension (MSISDN) to 23234242 (optional)
+<6> Give the subscriber a human-readable name (optional)
+<7> Review the content of your new subscriber record
+
+NOTE: If you are running a network with A5 encryption enabled, you must also
+configure the secret key (Ki) of the SIM card in the HLR.
+
+You can change further properties on your just-created subscriber as explained
+in <<hlr-subscr-properties>>.
+
+==== Creating subscribers in the SQL database
+
+In most applications, the network operator issues his own SIM cards, and
+the subscriber records corresponding to each SIM will be pre-provisioned by
+direct insertion into the SQL database.  This is performed long before the
+SIM cards are issued towards the actual end-users.
+
+This can be done by a custom program, the SQL schema is visible from the
+`.schema` command on the sqlite3 command-line program, and there are several
+scripts included in the OpenBSC source code, written in both Python as well as
+Perl language.
+
+In case you are obtaining a starter kit with pre-provisioned SIM cards from
+sysmocom: They will ship with a HLR SQL database containing the subscriber
+records.
+
+==== Provisioning SIM cards
+
+In most applications, the operator obtains pre-provisioned SIM cards from a SIM
+card supplier.
+
+If you prefer to provision the SIM cards yourself, you can use the pySim
 tool available from http://cgit.osmocom.org/cgit/pysim/.  It has the
 ability to append the newly-provisioned SIM cards to an existing HLR
 database, please check its `--write-hlr` command line argument.
 
 
-NOTE: OsmoNITB will automatically add new subscriber records for every
-IMSI that ever tries to perform a LOCATION UPDATE with the network.
-However, those subscriber records are marked as "not authorized", i.e.
-they will not be able to use your network.
-
-
+[[hlr-subscr-properties]]
 === Changing subscriber properties
 
-
 Once a subscriber exists in the HLR, his properties can be set
 interactively from the VTY.  Modifying subscriber properties requires
 the VTY to be in the privileged (`enable`) mode.