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.