FreeCalypso > hg > themwi-system-sw

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

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