# HG changeset patch # User Mychaela Falconia # Date 1703490091 0 # Node ID 6da76097c86ef0738095f66c4cc2755eac9075b8 initial import from old themwi-system-sw repository diff -r 000000000000 -r 6da76097c86e Fake-NANP-numbers --- /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. diff -r 000000000000 -r 6da76097c86e Local-short-numbers --- /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. diff -r 000000000000 -r 6da76097c86e NANP-specifics --- /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. diff -r 000000000000 -r 6da76097c86e Number-database --- /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. diff -r 000000000000 -r 6da76097c86e Use-outside-USA --- /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.