FreeCalypso > hg > themwi-system-sw

annotate doc/Number-database @ 272:c78b8d6ce885

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