# HG changeset patch # User Mychaela Falconia # Date 1701150305 28800 # Node ID 80a248def2082a1ef01c6e379608182e5d166aa2 # Parent c78b8d6ce885a38fb86170ac53bb2a6afe8aca6e doc/Fake-NANP-numbers: article written diff -r c78b8d6ce885 -r 80a248def208 doc/Fake-NANP-numbers --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Fake-NANP-numbers Mon Nov 27 21:45:05 2023 -0800 @@ -0,0 +1,123 @@ +Running ThemWi system sw with fake NANP numbers +=============================================== + +As outlined in Use-outside-USA article, there is a possibility that some people +may potentially be interested in running our software outside of USA - yet +without any intention of connecting to their own country's public telephone +network. Given that ThemWi system sw was written for the primary purpose of +making our Osmocom-based GSM network function as a full-fledged member of USA +PSTN and USA SMS network, with full interconnection, it is not clear to this +Mother why someone would be interested in our sw without such interconnection +as their primary goal. Porting our sw from USA PSTN to national telephone +networks of other countries would certainly be a laudable goal, but operation +without any national PSTN interconnection at all, not so much - what is the +point then? + +It is possible, however, that some people may be interested in auxiliary debug +or test functions of ThemWi, such as single-leg GSM test calls (MT with +themwi-test-mtc, MO with test sink numbers) - or perhaps they may be interested +in our implementation of GSUP-based SMSC. It is also possible that some people +may wish to operate toy networks, without money-costing and politically- +complicated interconnection with their national PSTN, but may still be +interested in hobby-level peering interconnection with other hobbyist or +community networks. + +To address such strange-seeming use cases, ThemWi system sw supports the option +of operating with fake NANP numbers instead of real ones. Real NANP numbers are +those which one gets (rents for a small amount of money) from a PSTN-via-SIP +connectivity provider such as BulkVS - but those companies typically require +the customer to have physical and/or legal presence in USA or Canada, in order +to connect to USA or Canadian PSTN, even if that connection is made over public +Internet. Every real NANP number geolocates to some real location in USA, +Canada or one of the many smaller NANP countries. Fake NANP numbers, OTOH, are +completely made up, and do not correspond to any real location anywhere in North +America - but they superficially mimic the structure of North American Numbering +Plan, allowing software written for NANP to be used without major changes. + +NANP rules require every telephone number (TN) to take the form of NXX-NXX-XXXX, +where N is any digit in [2-9] set and X is any digit in [0-9] set. The first +NXX group is also called NPA or simply "area code" (NPA stands for Numbering +Plan Area), and the second NXX group is called the exchange; the first 6 digits +taken together, typically written as NPA-NXX, are also called the prefix. +Furthermore, neither of the two NXX groups (neither NPA nor exchange) is allowed +to be N11 - these codes are reserved for emergency and other special numbers. + +ThemWi system sw requires all presenting-as-NANP numbers to follow the rules +listed above, including fake NANP numbers - but the diff that sets fake NANP +numbers apart is the middle digit of NPA code. Per official NANP rules, this +middle digit can never equal 9 - thus NPA codes of form N9X (290-299, 390-399, +..., 990-999) specifically signify fake NANP numbers. + +Fake NANP numbers beginning with N9X are allowed in all contexts where real NANP +numbers are ordinarily expected. There is only one place in the current code +base where they are treated specially, and that one place is the routing code +in themwi-sip-out. As currently implemented, themwi-sip-out will route a call +addressed to a number beginning with +1N9X only if there is an explicit route +defined for that specific 1N9X prefix, i.e., a route with a prefix length of 4 +or more digits. If there is no such explicit route, and the only match is +either the main +1 route (for all of regular NANP) or the global E.164 default +route, the call is rejected with GSM48_CC_CAUSE_NO_ROUTE - the idea is that we +should never send calls to such fake NANP numbers to real PSTN-via-SIP +connectivity providers. + +Configuring your number database with fake NANP +=============================================== + +No matter what kind of numbers you end up using, you have to create a database +of locally owned numbers - this local number database is always a required item +for ThemWi system sw to work, as explained in more detail in Number-database +article. If you are going to operate with fake NANP numbers, the recommended +way to populate your number database is as follows: + +prefix N9X-NXX allow-abbrev + +suffix XXXX gsm-sub +suffix XXXX gsm-sub +... + +For N9X-NXX part in the prefix line, pick some prefix that follows these +numerical rules (80 possibilities for N9X and 800 possibilities for NXX, for a +total of 64000 possible fake-NANP prefixes), and each XXXX in a suffix line is +a 4-digit extension number you are defining for use by your local GSM +subscribers. You will then need to enter each MSISDN into OsmoHLR as 11-digit +1N9XNXXXXXX, just as if it were a real, globally-routable E.164 number in the +North American Numbering Plan - but having 'allow-abbrev' modifier included on +the prefix line will allow you to dial 4-digit extensions instead of full +fake-NANP numbers for internal calls. + +The other alternative of using ITNs (see Local-short-numbers article) is also +possible, but not recommended: themwi-sip-in and themwi-sip-out require NANP or +NANP-looking numbers, not ITNs, hence a network instance that uses only ITNs +will have no ability to gateway to any other networks, not even hobbyist +non-PSTN kind. + +Interconnection among hobbyist or community networks +==================================================== + +The real Themyscira Wireless network, operating with real NANP numbers in the +region of San Diego county, California, USA, is open to making peering-type +interconnections with other hobbyist or community networks, including those +hobbyist/community networks whose operators choose to not connect to any PSTN +themselves and operate with fake E.164 numbers instead. If you do operate with +fake E.164 numbers instead of real ones (real E.164 numbers are those that were +legitimately issued to you by your country's telephone numbering plan authority +or its subdelegates; any others are fake), the requisite condition for peering +interconnection with real ThemWi is that your fake E.164 numbers are guaranteed +to never conflict with any real ones. This condition is absolute with no +exceptions - as a real mobile telephone network participating in global, fully +interconnected worldwide PSTN, Themyscira Wireless MUST route every real E.164 +number to its rightful national or international destination, no exceptions +allowed. + +Fake NANP numbers as described in this article satisfy the requirement of not +conflicting with any possible real E.164 numbers, hence if you set up your own +instance of ThemWi system sw using such fake NANP numbers, you will be eligible +for peering interconnection with Themyscira Wireless, the real ThemWi. If you +wish to be able to receive calls from us, you will need to run themwi-sip-in on +a server with some public-facing static IP address (and be willing to accept SIP +calls from anywhere in the world, addressing your selected range of fake-NANP +numbers), and we will create a routing entry in our themwi-sip-out config, +routing your +1N9X prefix to your server. In the other direction, if you wish +to send calls to us, simply send them to sip.sandiego2g.org - as long as the +called E.164 number is one of ours, we accept calls from anywhere on the public +Internet, not just from our official USA PSTN connectivity provider.