# HG changeset patch # User Mychaela Falconia # Date 1701039082 28800 # Node ID ff1ed366c84d81bc2df3e0943ad601a768dea279 # Parent d6630a2d6e807ad39f5852971c96dd4770407eac doc/Number-database: first draft written diff -r d6630a2d6e80 -r ff1ed366c84d doc/Number-database --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Number-database Sun Nov 26 14:51:22 2023 -0800 @@ -0,0 +1,176 @@ +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. + +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".