annotate doc/Fake-NANP-numbers @ 273:80a248def208

doc/Fake-NANP-numbers: article written
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 27 Nov 2023 21:45:05 -0800
parents
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
273
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Running ThemWi system sw with fake NANP numbers
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 ===============================================
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 As outlined in Use-outside-USA article, there is a possibility that some people
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 may potentially be interested in running our software outside of USA - yet
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 without any intention of connecting to their own country's public telephone
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 network. Given that ThemWi system sw was written for the primary purpose of
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 making our Osmocom-based GSM network function as a full-fledged member of USA
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 PSTN and USA SMS network, with full interconnection, it is not clear to this
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 Mother why someone would be interested in our sw without such interconnection
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 as their primary goal. Porting our sw from USA PSTN to national telephone
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 networks of other countries would certainly be a laudable goal, but operation
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 without any national PSTN interconnection at all, not so much - what is the
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 point then?
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 It is possible, however, that some people may be interested in auxiliary debug
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 or test functions of ThemWi, such as single-leg GSM test calls (MT with
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 themwi-test-mtc, MO with test sink numbers) - or perhaps they may be interested
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 in our implementation of GSUP-based SMSC. It is also possible that some people
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 may wish to operate toy networks, without money-costing and politically-
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 complicated interconnection with their national PSTN, but may still be
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 interested in hobby-level peering interconnection with other hobbyist or
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 community networks.
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 To address such strange-seeming use cases, ThemWi system sw supports the option
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 of operating with fake NANP numbers instead of real ones. Real NANP numbers are
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 those which one gets (rents for a small amount of money) from a PSTN-via-SIP
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 connectivity provider such as BulkVS - but those companies typically require
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 the customer to have physical and/or legal presence in USA or Canada, in order
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 to connect to USA or Canadian PSTN, even if that connection is made over public
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 Internet. Every real NANP number geolocates to some real location in USA,
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 Canada or one of the many smaller NANP countries. Fake NANP numbers, OTOH, are
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 completely made up, and do not correspond to any real location anywhere in North
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 America - but they superficially mimic the structure of North American Numbering
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 Plan, allowing software written for NANP to be used without major changes.
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 NANP rules require every telephone number (TN) to take the form of NXX-NXX-XXXX,
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 where N is any digit in [2-9] set and X is any digit in [0-9] set. The first
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 NXX group is also called NPA or simply "area code" (NPA stands for Numbering
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 Plan Area), and the second NXX group is called the exchange; the first 6 digits
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 taken together, typically written as NPA-NXX, are also called the prefix.
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 Furthermore, neither of the two NXX groups (neither NPA nor exchange) is allowed
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 to be N11 - these codes are reserved for emergency and other special numbers.
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 ThemWi system sw requires all presenting-as-NANP numbers to follow the rules
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 listed above, including fake NANP numbers - but the diff that sets fake NANP
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 numbers apart is the middle digit of NPA code. Per official NANP rules, this
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 middle digit can never equal 9 - thus NPA codes of form N9X (290-299, 390-399,
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 ..., 990-999) specifically signify fake NANP numbers.
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 Fake NANP numbers beginning with N9X are allowed in all contexts where real NANP
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 numbers are ordinarily expected. There is only one place in the current code
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 base where they are treated specially, and that one place is the routing code
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 in themwi-sip-out. As currently implemented, themwi-sip-out will route a call
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 addressed to a number beginning with +1N9X only if there is an explicit route
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 defined for that specific 1N9X prefix, i.e., a route with a prefix length of 4
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 or more digits. If there is no such explicit route, and the only match is
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 either the main +1 route (for all of regular NANP) or the global E.164 default
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 route, the call is rejected with GSM48_CC_CAUSE_NO_ROUTE - the idea is that we
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 should never send calls to such fake NANP numbers to real PSTN-via-SIP
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 connectivity providers.
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 Configuring your number database with fake NANP
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 ===============================================
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 No matter what kind of numbers you end up using, you have to create a database
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 of locally owned numbers - this local number database is always a required item
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 for ThemWi system sw to work, as explained in more detail in Number-database
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 article. If you are going to operate with fake NANP numbers, the recommended
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 way to populate your number database is as follows:
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 prefix N9X-NXX allow-abbrev
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 suffix XXXX gsm-sub
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 suffix XXXX gsm-sub
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 ...
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 For N9X-NXX part in the prefix line, pick some prefix that follows these
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 numerical rules (80 possibilities for N9X and 800 possibilities for NXX, for a
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 total of 64000 possible fake-NANP prefixes), and each XXXX in a suffix line is
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 a 4-digit extension number you are defining for use by your local GSM
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 subscribers. You will then need to enter each MSISDN into OsmoHLR as 11-digit
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 1N9XNXXXXXX, just as if it were a real, globally-routable E.164 number in the
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 North American Numbering Plan - but having 'allow-abbrev' modifier included on
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 the prefix line will allow you to dial 4-digit extensions instead of full
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 fake-NANP numbers for internal calls.
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 The other alternative of using ITNs (see Local-short-numbers article) is also
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 possible, but not recommended: themwi-sip-in and themwi-sip-out require NANP or
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 NANP-looking numbers, not ITNs, hence a network instance that uses only ITNs
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 will have no ability to gateway to any other networks, not even hobbyist
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 non-PSTN kind.
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 Interconnection among hobbyist or community networks
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 ====================================================
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 The real Themyscira Wireless network, operating with real NANP numbers in the
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 region of San Diego county, California, USA, is open to making peering-type
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 interconnections with other hobbyist or community networks, including those
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 hobbyist/community networks whose operators choose to not connect to any PSTN
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 themselves and operate with fake E.164 numbers instead. If you do operate with
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 fake E.164 numbers instead of real ones (real E.164 numbers are those that were
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 legitimately issued to you by your country's telephone numbering plan authority
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 or its subdelegates; any others are fake), the requisite condition for peering
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 interconnection with real ThemWi is that your fake E.164 numbers are guaranteed
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 to never conflict with any real ones. This condition is absolute with no
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 exceptions - as a real mobile telephone network participating in global, fully
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 interconnected worldwide PSTN, Themyscira Wireless MUST route every real E.164
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 number to its rightful national or international destination, no exceptions
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 allowed.
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 Fake NANP numbers as described in this article satisfy the requirement of not
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 conflicting with any possible real E.164 numbers, hence if you set up your own
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 instance of ThemWi system sw using such fake NANP numbers, you will be eligible
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 for peering interconnection with Themyscira Wireless, the real ThemWi. If you
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116 wish to be able to receive calls from us, you will need to run themwi-sip-in on
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 a server with some public-facing static IP address (and be willing to accept SIP
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 calls from anywhere in the world, addressing your selected range of fake-NANP
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 numbers), and we will create a routing entry in our themwi-sip-out config,
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 routing your +1N9X prefix to your server. In the other direction, if you wish
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121 to send calls to us, simply send them to sip.sandiego2g.org - as long as the
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122 called E.164 number is one of ours, we accept calls from anywhere on the public
80a248def208 doc/Fake-NANP-numbers: article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123 Internet, not just from our official USA PSTN connectivity provider.