FreeCalypso > hg > themwi-docs

comparison Number-database @ 0:6da76097c86e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial import from old themwi-system-sw repository
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 25 Dec 2023 07:41:31 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:6da76097c86e
1 Database of locally owned numbers
2 =================================
3
4 The database of locally owned phone numbers is a ThemWi-invented ad hoc data
5 structure that is absolutely required for ThemWi system sw to work. The human-
6 edited ASCII source form of this database resides in /var/gsm/number-db2 and
7 its compiled binary form resides in /var/gsm/number-db2.bin, compiled with
8 themwi-update-numdb2 utility. (The "db2" in file and utility names refers to
9 database version 2, which is the current version.) This database contains two
10 types of entries:
11
12 1) Locally owned 10-digit NANP numbers;
13 2) Internally defined 4-digit short numbers.
14
15 NANP number ownership information
16 =================================
17
18 ThemWi system sw is written with the assumption that the local instance operator
19 obtains (rents) real NANP phone numbers from a provider such as BulkVS and
20 assigns these numbers to individual GSM subscribers in OsmoHLR. However, in
21 order for ThemWi system sw to work correctly, there is one more step needed:
22 each locally owned number (i.e., each NANP number you rent from BulkVS or
23 whoever your upstream is) needs to be entered into ThemWi local number database.
24
25 The step of obtaining (a batch of) NANP phone numbers from your SIP trunk
26 provider and the step of assigning individual numbers to specific GSM
27 subscribers (by way of OsmoHLR subscriber database) are almost always separated
28 in time: as an operator, you will typically obtain a batch of TNs (telephone
29 numbers) in one go, and from the perspective of your upstream, all of these TNs
30 route to your server. How you then assign them to GSM subscribers (make them
31 into MSISDNs associated with IMSIs) is your own business, and you can change
32 these associations any time you like, without affecting your interconnection
33 with your PSTN upstream.
34
35 ThemWi local number database needs to list all TNs (10-digit NANP numbers) that
36 are currently owned by your local fiefdom, irrespective of whether or not they
37 are assigned to a GSM subscriber. If a given TN belongs to your local fiefdom
38 in the sense that the global worldwide PSTN will direct any incoming calls to
39 this TN to your server, but you haven't assigned it to a GSM subscriber yet,
40 ThemWi system sw still needs to know that this number is locally owned: call
41 attempts to that TN should never be sent to the outbound gateway, in particular.
42
43 Owned NANP number entry syntax
44 ------------------------------
45
46 By way of example, suppose that a set of telephone numbers in the range
47 310-555-01XX is yours - how do you enter them into /var/gsm/number-db2? You
48 have a choice of two syntax forms:
49
50 1) If you have many numbers in the same NPA-NXX prefix (as in the present
51 example), you can enter them using this syntax:
52
53 prefix 310-555 [allow-abbrev]
54
55 suffix 0101
56 suffix 0102
57 suffix 0103
58 ...
59
60 In this form, all owned TNs under the same prefix are clearly grouped together,
61 and you have the option of allowing abbreviations - if you wish to allow
62 abbreviated 4-digit dialing, add 'allow-abbrev' keyword to the prefix line.
63 When abbreviations are enabled, each suffix line not only creates an entry in
64 the owned-NANP portion of the local number database, but also adds an entry to
65 the list of defined 4-digit short dialing numbers, mapping to the corresponding
66 full number - see Local-short-numbers article.
67
68 2) If you have individual 10-digit NANP numbers that don't form a neat group
69 under a single NPA-NXX prefix, you can enter them using this alternative
70 syntax for single numbers:
71
72 full10 310-123-5678
73 full10 216-555-0166
74 full10 949-011-1234
75 ...
76
77 (The example uses invalid NANP numbers, whereas in actual usage you have to
78 enter real valid ones - but the syntax is the same.) With this number entry
79 method, there is no possibility of allow-abbrev: no 4-digit short dialing number
80 is created, and the owned NANP number in question can only be dialed in full
81 10-digit form.
82
83 The given syntax examples for prefix and full10 lines use hyphens. These
84 hyphens are optional and can be placed anywhere in the number - but we recommend
85 following the standard notation for NANP numbers.
86
87 NANP number usage information
88 =============================
89
90 The entry formats given above provide only number ownership information: they
91 tell ThemWi system sw which NANP numbers belong in the local fiefdom (all listed
92 numbers) and which ones don't (the remaining space of all other possible NANP
93 numbers outside listed ones). However, this number ownership information does
94 not include any usage or assignment information, and this additional info needs
95 to be provided via number attributes.
96
97 If number ownership information is entered exactly as shown in the examples
98 above, without any additional attributes, ThemWi system sw will treat each of
99 its owned numbers as being unassigned: any call attempts to that number, from
100 the inside or from the outside, will return "unassigned number" error to the
101 caller in the form of GSM CC cause value or SIP error code. When locally owned
102 numbers are assigned to GSM subscribers, a 'gsm-sub' attribute needs to be added
103 to each thus-assigned number; following the already given examples, the new
104 syntax becomes:
105
106 prefix 310-555 [allow-abbrev]
107
108 suffix 0101 gsm-sub
109 suffix 0102 gsm-sub
110 suffix 0103 gsm-sub
111
112 full10 310-123-5678 gsm-sub
113 full10 216-555-0166 gsm-sub
114 full10 949-011-1234 gsm-sub
115 ...
116
117 Note the absence of indication as to which GSM subscriber each number is
118 assigned to: when ThemWi system sw sees that the called number is assigned to
119 gsm-sub usage, it sends the call to OsmoMSC, which will then look for a
120 connected subscriber whose MSISDN equals the called party number. The mapping
121 from phone numbers to specific subscribers as in IMSIs thus happens by way of
122 OsmoHLR subscriber database, just like in "bare" Osmocom CNI setups without
123 ThemWi system sw.
124
125 Alias numbers
126 -------------
127
128 ThemWi system sw supports the notion of alias or redirecting numbers. Suppose
129 you have a single GSM subscriber who needs to be reachable at more than one NANP
130 number - for example, someone who got a native ThemWi number (from BulkVS etc)
131 at one point in time, but then ported their number from some national carrier
132 (of evil 2G-killing kind) to BulkVS/ThemWi - how to make the same GSM subscriber
133 reachable via both numbers? Each GSM subscriber has a primary MSISDN (phone
134 number) that is configured in OsmoHLR: this number is returned by *#100# query,
135 and appears as the "from" number on all outgoing calls. Any additional numbers
136 that should route to the same subscriber need to be handled via ThemWi alias
137 number facility, i.e., handled at ThemWi system sw level rather than at OsmoCNI
138 level.
139
140 The syntax for entering alias numbers is as follows (using example fake numbers
141 from above):
142
143 prefix 310-555 [allow-abbrev]
144 suffix 0123 map-to 216-555-0166
145
146 or
147
148 full10 310-555-0123 map-to 216-555-0166
149
150 In this example the "native" number of the GSM subscriber is 216-555-0166, but
151 alias number 310-555-0123 is configured to route to the same subscriber. In the
152 case of full10 number lines, the map-to target number must always be entered in
153 full 10-digit notation just like the alias number; in the case of prefix and
154 suffix lines, the map-to target number can be either a full 10-digit number or
155 a 4-digit number in the same prefix.
156
157 Irrespective of entry notation used, every map-to target number must be a
158 locally owned NANP number (cannot be an outside number) of gsm-sub usage type,
159 i.e., some local GSM subscriber's primary number.
160
161 Additional number flags for SMS and E911
162 ========================================
163
164 The following additional flags can be set on each locally owned NANP number's
165 suffix or full10 line:
166
167 e911 This flag indicates that the number in question is provisioned for E911
168 at the level of BulkVS or whoever is the upstream provider from whom
169 the number is rented. Having a number provisioned for E911 (which costs
170 additional money every month) means that emergency 911 calls can be sent
171 to that PSTN-via-SIP provider with this number as source or "from",
172 without paying a hefty fine for an unprovisioned E911 call.
173
174 sms This flag indicates that the number in question is provisioned for
175 outside SMS connectivity, meaning that it is possible to send SMS to
176 the outside world with this number as source or "from".
177
178 Local short number entries
179 ==========================
180
181 In addition to entries that list locally owned NANP numbers, there are other
182 types of entry in the master number database source file that list ITNs
183 (internal test numbers) and test sinks. These entries are described in
184 Local-short-numbers article.
185
186 Compiled binary format and updates
187 ==================================
188
189 The human-edited ASCII source form of the just-described number database,
190 located in /var/gsm/number-db2 master file, is read only by themwi-update-numdb2
191 utility and no other programs. This utility reads the ASCII source form of the
192 number database, parses it with some basic validation, and compiles it into a
193 binary format that is designed for fast lookups and read by long-running ThemWi
194 processes. The compiled binary form of the number database resides in
195 /var/gsm/number-db2.bin, and the latter file is always updated via an atomic
196 rename mechanism: themwi-update-numdb2 first writes out a temporary file named
197 number-db2.newbin, then renames it to number-db2.bin, making the new version
198 live.
199
200 Long-running ThemWi server processes perform stat(2) checks on this file as part
201 of call setup or SMS admission processing, and if they notice that the binary
202 database file has changed, they read the new version.