--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Fake-NANP-numbers	Mon Dec 25 07:41:31 2023 +0000
@@ -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.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Local-short-numbers	Mon Dec 25 07:41:31 2023 +0000
@@ -0,0 +1,118 @@
+Network-internal short dialing numbers
+======================================
+
+In addition to obviously necessary support for standard E.164 phone numbers
+(assigning real NANP numbers to local subscribers, calling any other NANP
+numbers whether they are local or not, calling international numbers outside of
+NANP), ThemWi system sw implements an additional, entirely private and network-
+internal, numbering space for 4-digit short dialing numbers.  Any time a ThemWi
+GSM subscriber dials a number that consists of only (exactly) 4 digits, that
+short number is looked up in this private ThemWi-defined numbering space.
+
+In the present implementation, three different types of numbers can exist in
+this private, network-internal short 4-digit number space, each described in
+its own section below.
+
+Abbreviated NANP numbers
+------------------------
+
+If you have a bunch of real NANP numbers from the same NPA-NXX prefix, you can
+enter them into the master database of locally owned numbers (see
+Number-database article) using this notation:
+
+prefix NPA-NXX allow-abbrev
+
+If the 'allow-abbrev' flag keyword is included, each NANP number entered under
+this prefix (each following suffix line) gets added to the short 4-digit number
+space: in addition to the standard option of dialing all 10 digits, the same
+number can be reached by dialing only the last 4 digits, considered to be the
+"station" part of the number (under a given "exchange") per NANP rules.
+
+You do need to be careful with this facility, as conflicting numbers are not
+allowed.  Enabling allow-abbrev mode makes sense under the following conditions:
+
+1) You have one preferred NPA-NXX prefix, presumably corresponding to your
+   geographic locality, and you reserve all of your native numbers (via BulkVS
+   portal or equivalent from other providers) from that one preferred prefix.
+   In this case you should set allow-abbrev on your "home" prefix, but whenever
+   you have to add non-native numbers to your network (customer port-ins etc),
+   those don't get the abbreviated dialing option, only full10.
+
+2) You may enable allow-abbrev for more than one prefix if you reserve your
+   numbers from multiple prefixes in a judicious manner, selecting 4-digit
+   suffixes that don't overlap across your two (or more) prefixes.
+
+Internal test numbers (ITNs)
+----------------------------
+
+An ITN is a 4-digit short dialing number (meaningful only inside your local GSM
+network) that is assigned to a GSM subscriber and entered as such (4 digits
+only) into OsmoHLR subscriber database.  When ITNs are used, a GSM subscriber
+who gets an ITN is *not* given a real NANP telephone number, and thus cannot
+make any calls to or receive any calls from the outside world.
+
+Our own Themyscira Wireless operation does not presently use any ITNs.  This
+facility was invented before we realized how cheap NANP numbers can be when they
+are ordered "raw" or "bare": a basic reservation of a real 10-digit NANP number
+from BulkVS *without* E911 provision and without SMS capability (regular,
+non-emergency calls only) costs only $0.06 (6 cents) per number per month.  At
+this insanely cheap price, it makes no sense to introduce ITNs, it is easier to
+give a real NANP number to every GSM subscriber including lab-use-only test
+SIMs - but the Mother does not believe in removing implemented functionality
+without extremely strong justification, hence support for ITNs remains in our
+software.
+
+To define an ITN, enter a line like this into your master database of locally
+owned numbers:
+
+itn XXXX
+
+where XXXX is the 4-digit number to be defined as an ITN.
+
+Test sink numbers
+-----------------
+
+A test sink number is a private, network-internal 4-digit number that is
+intended to serve as a destination or "sink" for test calls and test SMS.  Any
+calls dialed to a test sink number will be handled by a special process which
+only exists for that purpose (remains to be implemented), and any SMS sent to a
+test sink number will be simply written into log-structured storage without any
+further delivery to anywhere.  The purpose of test sink numbers is to exercise
+outgoing call and outgoing SMS functions of GSM MS without needing a "real"
+second party to serve as the recipient.
+
+To define a test sink number, enter a line like this into your master database
+of locally owned numbers:
+
+test-sink XXXX
+
+where XXXX is the 4-digit number to be defined as a test sink.
+
+Historical perspective
+======================
+
+In the original design of ThemWi system sw, 4-digit short dialing numbers were
+intended to be ITNs only, forming an internal-only numbering space that is
+entirely disjoint from public E.164 numbers.  Operating on the assumption that
+external NANP numbers would be expensive, the design model was that every GSM
+subscriber would have an ITN, and then additionally some subscriber lines (those
+belonging to human users, rather than lab test SIMs) would be given real
+external phone numbers in NANP.  The fixed 4-digit length for internal short
+numbers was chosen, contrary to the apparent custom in Osmocom community of
+using 5-digit numbers for such internal "extensions", because a 5-digit number
+can be a valid SMS short code in USA, and human users of Themyscira Wireless GSM
+service need to be able to access these SMS short-code public services just like
+customers of any other cell carrier in this country.
+
+Shortly after beginning to implement the initial design described above, we
+discovered how cheap real NANP numbers actually are, and got a batch of numbers
+from our choice of NPA-NXX prefix.  We were then sitting on a batch of numbers
+that had the same 6-digit prefix, but different 4-digit suffixes, and that was
+how we got the idea of abbreviated dialing numbers: instead of completely
+made-up ITNs, allow "home block" NANP numbers to be dialed (from one local GSM
+phone to another) by just the last 4 digits of the external, globally valid
+E.164 number.
+
+Test sink numbers are our latest-so-far addition to the network-internal 4-digit
+dialing number space, and we have yet to implement them beyond mere definition
+in the local number database.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/NANP-specifics	Mon Dec 25 07:41:31 2023 +0000
@@ -0,0 +1,163 @@
+North American Numbering Plan (NANP) specifics in ThemWi system sw
+==================================================================
+
+Themyscira Wireless system software, as currently written, is strongly tied to
+NANP.  More precisely, it thoroughly assumes that all local phone numbers are
+in +1 country code and follow NANP rules, and that all E.164 telephone numbers
+in country codes other than +1 are foreign - numbers which we can call and
+receive calls from, but which can never be local to us.
+
+Why does our software need to have these assumptions baked into it, why can't
+it be country-agnostic?  The present article answers this question, and this
+long answer needs to be thoroughly understood before there can be any meaningful
+discussion of how the software could possibly be adapted to other countries and
+their respective telephone numbering plans.
+
+In principle, there exists a standardized dialing format on all GSM phones that
+remains the same no matter which country you happen to be in.  If you always
+enter phone numbers (dialing, SMS manual entry, phone book entries) in full
+international format beginning with the '+' symbol (press and hold the '0'
+button before the number in most phone UIs), the phone handset firmware will
+capture the number with TON=1, NPI=1 attributes (signifying international number
+format in GSM call control and SMS protocols) and transmit it as such to the
+GSM network.  Every properly designed GSM network, upon seeing a number with
+these TON=1, NPI=1 attributes, must address the call or message to the country
+indicated by the country code at the beginning of the full E.164 number, whether
+that country is your local one or some other.  Thus if everyone were to always
+use only full E.164 numbers in full international format, network software could
+hypothetically be written in a country-agnostic way, treating full E.164 phone
+numbers as opaque strings without parsing.  However, there are two practical
+problems with such country-agnostic approach:
+
+1) Most human users of mobile phones dial local phone numbers (within their own
+   country) in a way that follows local dialing conventions, rather than in
+   international format beginning with '+' and their own country code.  For
+   example, in USA a given 10-digit NANP phone number can be dialed as just the
+   10 digits NPANXXXXXX, as 11-digit 1NPANXXXXXX, or as full international
+   +1NPANXXXXXX - and a proper cellphone network MUST accept all 3 formats as
+   equivalent.
+
+2) As explained further in this article, a network implementation must be able
+   to look at a telephone number and immediately tell if that number is locally
+   owned ("one of ours") or belongs somewhere outside of the local GSM network.
+   Practical implementation of this distinction requires a database of locally
+   owned phone numbers, and the implementation of that database in turn becomes
+   much easier when the local numbering plan is known and fixed.
+
+Supported dialing formats in ThemWi
+===================================
+
+When themwi-mncc processes a mobile-originated (MO) call from a GSM subscriber,
+it supports dialing the following classes of numbers:
+
+* NANP numbers in any of the 3 standard dialing formats;
+
+* International numbers in any country - an international number beginning
+  with +1 is enforced to be valid NANP, but E.164 numbers in all other country
+  codes are accepted as-is;
+
+* Local 4-digit numbers described in Local-short-numbers article;
+
+* Whatever special numbers are configured in themwi-sip-out, such as 511 and
+  911.
+
+Only NANP numbers and specially configured 4-digit numbers (see
+Local-short-numbers) can be local - all E.164 numbers in non-NANP country codes
+are sent to the outbound call gateway, and all other unrecognized number formats
+are likewise sent to themwi-sip-out so that the latter process can catch and map
+special numbers like 511, 911 etc.
+
+If a dialed number is recognized as NANP, themwi-mncc looks in the database of
+locally owned numbers to see if the dialed number is one of ours - and the
+outcome of this look-up determines if the call is handled locally or sent to
+the outside world via themwi-sip-out.
+
+No 7-digit dialing support
+==========================
+
+In the olden days of land lines, most localities in USA supported 7-digit
+dialing: to call Jenny, you would merely dial her local 7-digit number 867-5309,
+without needing to dial the local area code; full 10-digit numbers (or 11 digits
+with leading '1') had to be dialed only when calling someone in a different
+area code from your own.  However, this 7-digit dialing has now been disabled
+even for land lines in most localities, including the locality where ThemWi
+currently operates: per official rules, 7-digit dialing gets disabled (full
+10-digit numbers become mandatory) whenever an area code overlay is implemented,
+such as overlay of 760 and 442 area codes in our locality.
+
+In the case of mobile phones, 7-digit dialing never made much sense to begin
+with: if you dial only 7 digits, should the implicit area code be taken from
+your own number, or should it be the area code of the locality you happen to be
+traveling through at the moment?  The latter option is impossible in the case
+of localities with two or more overlaid NPA codes, and it appears that official
+rules once again call for simply disabling 7-digit dialing.
+
+Based on these considerations, ThemWi system sw was written from the outset to
+not support 7-digit dialing - it is no longer relevant in the current state of
+telecom culture in USA.  We do, however. provide optional support for
+abbreviated 4-digit local numbers - see Local-short-numbers article.
+
+Database of locally owned numbers
+=================================
+
+The telecom culture in USA features full number portability - end users can take
+their phone numbers with them anywhere, from one telecom provider to another,
+and with mobile phones and VoIP services, from one geographic locality to any
+other, making the entire country effectively "flat" for local/non-local
+distinction purposes.  Therefore, the set of phone numbers "owned" (or rented
+in reality) by a small network operator such as Themyscira Wireless does not
+constitute any kind of clean-cut digit range partition in the numbering plan -
+instead we can have a small set of locally owned numbers (say, on the order of
+5 to 20 individual numbers), and each of these locally owned numbers can fall
+anywhere in the whole nationwide 10-digit numbering plan.  So how can we tell,
+by looking at an arbitrary NANP number, whether it is "one of ours" or not?
+
+The implemented solution is an explicitly maintained database of locally owned
+phone numbers, described in detail in Number-database article.  The format of
+this database (the way numbers are entered, the way the input format is parsed,
+and the compiled binary format used for fast look-ups) is specific to NANP -
+only NANP numbers can be local in the present design.
+
+Porting to other national telephone numbering plans
+===================================================
+
+If someone wishes to port ThemWi system sw for use in other countries with
+respective local phone numbers, the following aspects will need to be changed:
+
+* Based on the structure of your country's national numbering plan, you will
+  need to come up with an appropriate local number database format for your
+  country, or if the range of numbers belonging to your GSM network forms a
+  clean-cut digit range partition, implement that scheme instead.
+
+* You will need to modify MO call handling to recognize your country code
+  (rather than +1) as the one calling for parsing and closer scrutiny of the
+  dialed number, determining if it is local or not.
+
+* Handling of non-international dialing formats (numbers dialed without '+')
+  will need to be changed to whatever is appropriate for your country's telecom
+  culture and customs.
+
+* Handle all secondary fallout (throughout the code base) from the previous
+  essential and necessary changes.
+
+Using fake NANP numbers
+=======================
+
+If someone outside of North America wishes to merely play with ThemWi system sw
+on a casual basis, without actually interconnecting to your non-USA PSTN with
+non-NANP real phone numbers, the easiest way to bring the software up is to use
+fake NANP numbers.  There are two types of guaranteed-fake (can't collide with
+real ones) phone numbers in NANP:
+
+1) NPA-555-01XX, where NPA is some real area code for some (any) actual locality
+   in USA and XX can be any two digits.  This number range is specifically set
+   aside for use in movies etc, with realistic USA settings - the area code can
+   be any real one, but 555-01XX numbers are reserved for fake use in every
+   area code.
+
+2) Fake area codes of form N9X (290-299, 390-399, ..., 990-999) are also good
+   for guaranteed-fake numbers as the middle digit of NPA is not allowed to be
+   '9' per official NANP rules.  This method allows large ranges of fake NANP
+   numbers.
+
+See Fake-NANP-numbers article for more info.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Number-database	Mon Dec 25 07:41:31 2023 +0000
@@ -0,0 +1,202 @@
+Database of locally owned numbers
+=================================
+
+The database of locally owned phone numbers is a ThemWi-invented ad hoc data
+structure that is absolutely required for ThemWi system sw to work.  The human-
+edited ASCII source form of this database resides in /var/gsm/number-db2 and
+its compiled binary form resides in /var/gsm/number-db2.bin, compiled with
+themwi-update-numdb2 utility.  (The "db2" in file and utility names refers to
+database version 2, which is the current version.)  This database contains two
+types of entries:
+
+1) Locally owned 10-digit NANP numbers;
+2) Internally defined 4-digit short numbers.
+
+NANP number ownership information
+=================================
+
+ThemWi system sw is written with the assumption that the local instance operator
+obtains (rents) real NANP phone numbers from a provider such as BulkVS and
+assigns these numbers to individual GSM subscribers in OsmoHLR.  However, in
+order for ThemWi system sw to work correctly, there is one more step needed:
+each locally owned number (i.e., each NANP number you rent from BulkVS or
+whoever your upstream is) needs to be entered into ThemWi local number database.
+
+The step of obtaining (a batch of) NANP phone numbers from your SIP trunk
+provider and the step of assigning individual numbers to specific GSM
+subscribers (by way of OsmoHLR subscriber database) are almost always separated
+in time: as an operator, you will typically obtain a batch of TNs (telephone
+numbers) in one go, and from the perspective of your upstream, all of these TNs
+route to your server.  How you then assign them to GSM subscribers (make them
+into MSISDNs associated with IMSIs) is your own business, and you can change
+these associations any time you like, without affecting your interconnection
+with your PSTN upstream.
+
+ThemWi local number database needs to list all TNs (10-digit NANP numbers) that
+are currently owned by your local fiefdom, irrespective of whether or not they
+are assigned to a GSM subscriber.  If a given TN belongs to your local fiefdom
+in the sense that the global worldwide PSTN will direct any incoming calls to
+this TN to your server, but you haven't assigned it to a GSM subscriber yet,
+ThemWi system sw still needs to know that this number is locally owned: call
+attempts to that TN should never be sent to the outbound gateway, in particular.
+
+Owned NANP number entry syntax
+------------------------------
+
+By way of example, suppose that a set of telephone numbers in the range
+310-555-01XX is yours - how do you enter them into /var/gsm/number-db2?  You
+have a choice of two syntax forms:
+
+1) If you have many numbers in the same NPA-NXX prefix (as in the present
+   example), you can enter them using this syntax:
+
+prefix 310-555 [allow-abbrev]
+
+suffix 0101
+suffix 0102
+suffix 0103
+...
+
+In this form, all owned TNs under the same prefix are clearly grouped together,
+and you have the option of allowing abbreviations - if you wish to allow
+abbreviated 4-digit dialing, add 'allow-abbrev' keyword to the prefix line.
+When abbreviations are enabled, each suffix line not only creates an entry in
+the owned-NANP portion of the local number database, but also adds an entry to
+the list of defined 4-digit short dialing numbers, mapping to the corresponding
+full number - see Local-short-numbers article.
+
+2) If you have individual 10-digit NANP numbers that don't form a neat group
+   under a single NPA-NXX prefix, you can enter them using this alternative
+   syntax for single numbers:
+
+full10 310-123-5678
+full10 216-555-0166
+full10 949-011-1234
+...
+
+(The example uses invalid NANP numbers, whereas in actual usage you have to
+enter real valid ones - but the syntax is the same.)  With this number entry
+method, there is no possibility of allow-abbrev: no 4-digit short dialing number
+is created, and the owned NANP number in question can only be dialed in full
+10-digit form.
+
+The given syntax examples for prefix and full10 lines use hyphens.  These
+hyphens are optional and can be placed anywhere in the number - but we recommend
+following the standard notation for NANP numbers.
+
+NANP number usage information
+=============================
+
+The entry formats given above provide only number ownership information: they
+tell ThemWi system sw which NANP numbers belong in the local fiefdom (all listed
+numbers) and which ones don't (the remaining space of all other possible NANP
+numbers outside listed ones).  However, this number ownership information does
+not include any usage or assignment information, and this additional info needs
+to be provided via number attributes.
+
+If number ownership information is entered exactly as shown in the examples
+above, without any additional attributes, ThemWi system sw will treat each of
+its owned numbers as being unassigned: any call attempts to that number, from
+the inside or from the outside, will return "unassigned number" error to the
+caller in the form of GSM CC cause value or SIP error code.  When locally owned
+numbers are assigned to GSM subscribers, a 'gsm-sub' attribute needs to be added
+to each thus-assigned number; following the already given examples, the new
+syntax becomes:
+
+prefix 310-555 [allow-abbrev]
+
+suffix 0101 gsm-sub
+suffix 0102 gsm-sub
+suffix 0103 gsm-sub
+
+full10 310-123-5678 gsm-sub
+full10 216-555-0166 gsm-sub
+full10 949-011-1234 gsm-sub
+...
+
+Note the absence of indication as to which GSM subscriber each number is
+assigned to: when ThemWi system sw sees that the called number is assigned to
+gsm-sub usage, it sends the call to OsmoMSC, which will then look for a
+connected subscriber whose MSISDN equals the called party number.  The mapping
+from phone numbers to specific subscribers as in IMSIs thus happens by way of
+OsmoHLR subscriber database, just like in "bare" Osmocom CNI setups without
+ThemWi system sw.
+
+Alias numbers
+-------------
+
+ThemWi system sw supports the notion of alias or redirecting numbers.  Suppose
+you have a single GSM subscriber who needs to be reachable at more than one NANP
+number - for example, someone who got a native ThemWi number (from BulkVS etc)
+at one point in time, but then ported their number from some national carrier
+(of evil 2G-killing kind) to BulkVS/ThemWi - how to make the same GSM subscriber
+reachable via both numbers?  Each GSM subscriber has a primary MSISDN (phone
+number) that is configured in OsmoHLR: this number is returned by *#100# query,
+and appears as the "from" number on all outgoing calls.  Any additional numbers
+that should route to the same subscriber need to be handled via ThemWi alias
+number facility, i.e., handled at ThemWi system sw level rather than at OsmoCNI
+level.
+
+The syntax for entering alias numbers is as follows (using example fake numbers
+from above):
+
+prefix 310-555 [allow-abbrev]
+suffix 0123 map-to 216-555-0166
+
+or
+
+full10 310-555-0123 map-to 216-555-0166
+
+In this example the "native" number of the GSM subscriber is 216-555-0166, but
+alias number 310-555-0123 is configured to route to the same subscriber.  In the
+case of full10 number lines, the map-to target number must always be entered in
+full 10-digit notation just like the alias number; in the case of prefix and
+suffix lines, the map-to target number can be either a full 10-digit number or
+a 4-digit number in the same prefix.
+
+Irrespective of entry notation used, every map-to target number must be a
+locally owned NANP number (cannot be an outside number) of gsm-sub usage type,
+i.e., some local GSM subscriber's primary number.
+
+Additional number flags for SMS and E911
+========================================
+
+The following additional flags can be set on each locally owned NANP number's
+suffix or full10 line:
+
+e911	This flag indicates that the number in question is provisioned for E911
+	at the level of BulkVS or whoever is the upstream provider from whom
+	the number is rented.  Having a number provisioned for E911 (which costs
+	additional money every month) means that emergency 911 calls can be sent
+	to that PSTN-via-SIP provider with this number as source or "from",
+	without paying a hefty fine for an unprovisioned E911 call.
+
+sms	This flag indicates that the number in question is provisioned for
+	outside SMS connectivity, meaning that it is possible to send SMS to
+	the outside world with this number as source or "from".
+
+Local short number entries
+==========================
+
+In addition to entries that list locally owned NANP numbers, there are other
+types of entry in the master number database source file that list ITNs
+(internal test numbers) and test sinks.  These entries are described in
+Local-short-numbers article.
+
+Compiled binary format and updates
+==================================
+
+The human-edited ASCII source form of the just-described number database,
+located in /var/gsm/number-db2 master file, is read only by themwi-update-numdb2
+utility and no other programs.  This utility reads the ASCII source form of the
+number database, parses it with some basic validation, and compiles it into a
+binary format that is designed for fast lookups and read by long-running ThemWi
+processes.  The compiled binary form of the number database resides in
+/var/gsm/number-db2.bin, and the latter file is always updated via an atomic
+rename mechanism: themwi-update-numdb2 first writes out a temporary file named
+number-db2.newbin, then renames it to number-db2.bin, making the new version
+live.
+
+Long-running ThemWi server processes perform stat(2) checks on this file as part
+of call setup or SMS admission processing, and if they notice that the binary
+database file has changed, they read the new version.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Use-outside-USA	Mon Dec 25 07:41:31 2023 +0000
@@ -0,0 +1,48 @@
+Themyscira Wireless system sw was written for deployment in USA, with a key goal
+of full interconnection with USA PSTN.  However, as the software grows in
+functionality and becomes more interesting, there is a growing possibility that
+someone some day may be interested in running our sw outside of USA, or outside
+of North American continent in general.  This document outlines some thoughts
+for how it might be possible to adapt the present software for use in other
+geopolitical regions.
+
+The first point that needs to be made clear is that software has no extrasensory
+psychic powers - it cannot divine where you are located in physical geography,
+and it doesn't care.  Instead the aspects which telephony software cares about
+are dialing formats and numbering plans - and in the case of Themyscira Wireless
+system sw, the "thing" to which our sw is tied is NANP, the telephone numbering
+plan of +1 country code.
+
+If anyone is contemplating the idea of running ThemWi system sw in a country
+other than USA, the first question that needs to be answered is: are you looking
+to interconnect with your country's national public telephone network similarly
+to how we (ThemWi) interconnect with USA PSTN, or are you only interested in
+running an isolated (test or toy) network without interconnection to PSTN?
+
+Interconnecting with PSTN outside of USA
+========================================
+
+Suppose that your country has SIP trunk providers who operate similarly to those
+in USA: you rent a range of numbers in your country's national telephone
+numbering plan, calls addressed to those numbers are delivered to your Internet-
+connected server via SIP, and you can likewise use SIP to dial outbound calls.
+At this point our current software will NOT work as-is - it will require
+modifications to work with the local numbering plan being some other than NANP.
+
+Please read our NANP-specifics article for the explanation of why our current
+software is tied to NANP, and in exactly what ways.  That article also gives an
+outline of what changes would need to be made to support other national
+telephone numbering plans.
+
+Running an isolated instance of Osmocom CNI + ThemWi system sw
+==============================================================
+
+If you are not interconnecting with your country's public phone network with
+real phone numbers from your country's national telephone numbering plan, then
+it doesn't matter where you are located in terms of physical geography - your
+network will be either fully isolated (self-contained) or perhaps interconnected
+with other hobbyist or community networks - but not with general PSTN.
+
+If you would like to run ThemWi system sw in such non-PSTN-connected
+configuration, the easiest way is to use fake NANP numbers - see
+Fake-NANP-numbers article for more info.