Database of locally owned numbers
=================================

The database of locally owned phone numbers is a ThemWi-invented ad hoc data
structure that is absolutely required for ThemWi system sw to work.  The human-
edited ASCII source form of this database resides in /var/gsm/number-db2 and
its compiled binary form resides in /var/gsm/number-db2.bin, compiled with
themwi-update-numdb2 utility.  (The "db2" in file and utility names refers to
database version 2, which is the current version.)  This database contains two
types of entries:

1) Locally owned 10-digit NANP numbers;
2) Internally defined 4-digit short numbers.

NANP number ownership information
=================================

ThemWi system sw is written with the assumption that the local instance operator
obtains (rents) real NANP phone numbers from a provider such as BulkVS and
assigns these numbers to individual GSM subscribers in OsmoHLR.  However, in
order for ThemWi system sw to work correctly, there is one more step needed:
each locally owned number (i.e., each NANP number you rent from BulkVS or
whoever your upstream is) needs to be entered into ThemWi local number database.

The step of obtaining (a batch of) NANP phone numbers from your SIP trunk
provider and the step of assigning individual numbers to specific GSM
subscribers (by way of OsmoHLR subscriber database) are almost always separated
in time: as an operator, you will typically obtain a batch of TNs (telephone
numbers) in one go, and from the perspective of your upstream, all of these TNs
route to your server.  How you then assign them to GSM subscribers (make them
into MSISDNs associated with IMSIs) is your own business, and you can change
these associations any time you like, without affecting your interconnection
with your PSTN upstream.

ThemWi local number database needs to list all TNs (10-digit NANP numbers) that
are currently owned by your local fiefdom, irrespective of whether or not they
are assigned to a GSM subscriber.  If a given TN belongs to your local fiefdom
in the sense that the global worldwide PSTN will direct any incoming calls to
this TN to your server, but you haven't assigned it to a GSM subscriber yet,
ThemWi system sw still needs to know that this number is locally owned: call
attempts to that TN should never be sent to the outbound gateway, in particular.

Owned NANP number entry syntax
------------------------------

By way of example, suppose that a set of telephone numbers in the range
310-555-01XX is yours - how do you enter them into /var/gsm/number-db2?  You
have a choice of two syntax forms:

1) If you have many numbers in the same NPA-NXX prefix (as in the present
   example), you can enter them using this syntax:

prefix 310-555 [allow-abbrev]

suffix 0101
suffix 0102
suffix 0103
...

In this form, all owned TNs under the same prefix are clearly grouped together,
and you have the option of allowing abbreviations - if you wish to allow
abbreviated 4-digit dialing, add 'allow-abbrev' keyword to the prefix line.
When abbreviations are enabled, each suffix line not only creates an entry in
the owned-NANP portion of the local number database, but also adds an entry to
the list of defined 4-digit short dialing numbers, mapping to the corresponding
full number - see Local-short-numbers article.

2) If you have individual 10-digit NANP numbers that don't form a neat group
   under a single NPA-NXX prefix, you can enter them using this alternative
   syntax for single numbers:

full10 310-123-5678
full10 216-555-0166
full10 949-011-1234
...

(The example uses invalid NANP numbers, whereas in actual usage you have to
enter real valid ones - but the syntax is the same.)  With this number entry
method, there is no possibility of allow-abbrev: no 4-digit short dialing number
is created, and the owned NANP number in question can only be dialed in full
10-digit form.

The given syntax examples for prefix and full10 lines use hyphens.  These
hyphens are optional and can be placed anywhere in the number - but we recommend
following the standard notation for NANP numbers.

NANP number usage information
=============================

The entry formats given above provide only number ownership information: they
tell ThemWi system sw which NANP numbers belong in the local fiefdom (all listed
numbers) and which ones don't (the remaining space of all other possible NANP
numbers outside listed ones).  However, this number ownership information does
not include any usage or assignment information, and this additional info needs
to be provided via number attributes.

If number ownership information is entered exactly as shown in the examples
above, without any additional attributes, ThemWi system sw will treat each of
its owned numbers as being unassigned: any call attempts to that number, from
the inside or from the outside, will return "unassigned number" error to the
caller in the form of GSM CC cause value or SIP error code.  When locally owned
numbers are assigned to GSM subscribers, a 'gsm-sub' attribute needs to be added
to each thus-assigned number; following the already given examples, the new
syntax becomes:

prefix 310-555 [allow-abbrev]

suffix 0101 gsm-sub
suffix 0102 gsm-sub
suffix 0103 gsm-sub

full10 310-123-5678 gsm-sub
full10 216-555-0166 gsm-sub
full10 949-011-1234 gsm-sub
...

Note the absence of indication as to which GSM subscriber each number is
assigned to: when ThemWi system sw sees that the called number is assigned to
gsm-sub usage, it sends the call to OsmoMSC, which will then look for a
connected subscriber whose MSISDN equals the called party number.  The mapping
from phone numbers to specific subscribers as in IMSIs thus happens by way of
OsmoHLR subscriber database, just like in "bare" Osmocom CNI setups without
ThemWi system sw.

Alias numbers
-------------

ThemWi system sw supports the notion of alias or redirecting numbers.  Suppose
you have a single GSM subscriber who needs to be reachable at more than one NANP
number - for example, someone who got a native ThemWi number (from BulkVS etc)
at one point in time, but then ported their number from some national carrier
(of evil 2G-killing kind) to BulkVS/ThemWi - how to make the same GSM subscriber
reachable via both numbers?  Each GSM subscriber has a primary MSISDN (phone
number) that is configured in OsmoHLR: this number is returned by *#100# query,
and appears as the "from" number on all outgoing calls.  Any additional numbers
that should route to the same subscriber need to be handled via ThemWi alias
number facility, i.e., handled at ThemWi system sw level rather than at OsmoCNI
level.

The syntax for entering alias numbers is as follows (using example fake numbers
from above):

prefix 310-555 [allow-abbrev]
suffix 0123 map-to 216-555-0166

or

full10 310-555-0123 map-to 216-555-0166

In this example the "native" number of the GSM subscriber is 216-555-0166, but
alias number 310-555-0123 is configured to route to the same subscriber.  In the
case of full10 number lines, the map-to target number must always be entered in
full 10-digit notation just like the alias number; in the case of prefix and
suffix lines, the map-to target number can be either a full 10-digit number or
a 4-digit number in the same prefix.

Irrespective of entry notation used, every map-to target number must be a
locally owned NANP number (cannot be an outside number) of gsm-sub usage type,
i.e., some local GSM subscriber's primary number.

Additional number flags for SMS and E911
========================================

The following additional flags can be set on each locally owned NANP number's
suffix or full10 line:

e911	This flag indicates that the number in question is provisioned for E911
	at the level of BulkVS or whoever is the upstream provider from whom
	the number is rented.  Having a number provisioned for E911 (which costs
	additional money every month) means that emergency 911 calls can be sent
	to that PSTN-via-SIP provider with this number as source or "from",
	without paying a hefty fine for an unprovisioned E911 call.

sms	This flag indicates that the number in question is provisioned for
	outside SMS connectivity, meaning that it is possible to send SMS to
	the outside world with this number as source or "from".

Local short number entries
==========================

In addition to entries that list locally owned NANP numbers, there are other
types of entry in the master number database source file that list ITNs
(internal test numbers) and test sinks.  These entries are described in
Local-short-numbers article.

Compiled binary format and updates
==================================

The human-edited ASCII source form of the just-described number database,
located in /var/gsm/number-db2 master file, is read only by themwi-update-numdb2
utility and no other programs.  This utility reads the ASCII source form of the
number database, parses it with some basic validation, and compiles it into a
binary format that is designed for fast lookups and read by long-running ThemWi
processes.  The compiled binary form of the number database resides in
/var/gsm/number-db2.bin, and the latter file is always updated via an atomic
rename mechanism: themwi-update-numdb2 first writes out a temporary file named
number-db2.newbin, then renames it to number-db2.bin, making the new version
live.

Long-running ThemWi server processes perform stat(2) checks on this file as part
of call setup or SMS admission processing, and if they notice that the binary
database file has changed, they read the new version.