--- /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.