FreeCalypso > hg > themwi-smsc

annotate doc/Arch-design @ 0:9e364c18e0e8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
beginning of architectural design spec
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 20 Dec 2023 03:50:06 +0000
parents
children c4f8a32af088
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Themyscira Wireless SMSC implementation
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 Architectural design specification
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 1. Purpose and scope of the software
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 The purpose of the present software project is to facilitate store-and-forward
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 SMS exchange among the following parties:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 * Locally owned mobile telephone numbers (LOMTNs) that belong to Themyscira
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 Wireless, with Short Message Service accessed either via the local GSM network
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 (Osmocom-based) or via direct command line access to the SMSC;
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 * The outside world: the total set of all SMS-capable E.164 telephone numbers
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 in the world, with whom our users must be able to freely exchange SMS just
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 like users of any other cellular phone carrier in USA;
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 * USA-specific 5-digit and 6-digit short codes: these services aren't accessible
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 from anywhere in the world, only from USA (each country has its own services
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 of this type), but because we are located in USA, we must provide the same
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 access to public services as any other cellular phone carrier;
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 * Any downstream parties who enter into an interconnection agreement with ThemWi
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 for the purpose of sharing our SMS uplink to the outside world.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 1.1. NANP specifics
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 The design of our SMSC makes the following assumptions that are specific to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 North American Numbering Plan:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 * All LOMTNs and all downstream peer MTNs are expected to be NANP numbers;
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 any/all SMS source or destination numbers in country codes other than +1 are
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 treated as belonging in the Outside World, accessible only via the SMPP
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 "uplink" connection to our upstream SMS connectivity provider.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 * The set of SMS destination numbers that can be sent to the upstream includes
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 not only non-NANP and not-locally-known NANP E.164 numbers, but also any/all
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 SMS short codes in USA-specific NXXXX or NXXXXX format.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 * In the case of Mobile-Originated SMS from the local GSM network, if the
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 user-entered destination number is not explicitly international (TON=1) and
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 does not fit the format of a USA SMS short code, other USA-customary dialing
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 formats are supported, as in 10-digit NPANXXXXXX or 11-digit 1NPANXXXXXX
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 without '+' prefix.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 themwi-nanp software package is a strict dependency for themwi-smsc: themwi-nanp
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 utilities must be used to manage the database of locally owned NANP numbers,
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 and the present software uses themwi-nanp libraries to access that database.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 1.2. Hierarchical arrangement of upstream and downstream peers
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 The telecom landscape in USA is such that anyone can obtain 10-digit telephone
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 numbers (TNs) very easily and very cheaply, but making them SMS-capable (able
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 to function as Mobile Telephone Numbers or MTNs) is much more difficult.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 Suitably equipped providers such as Bandwidth.com are generally unwilling to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 provide service directly to small customers, and we (Themyscira Wireless team)
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 were able to find only one company (Sopranica Telecom) who buys P2P SMS
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 interconnection service from Bandwidth and was willing to resell to us.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 Suppose that many different ultra-small parties wish to set up their own indie
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 GSM networks in different parts of USA. Each of these tiny fiefdoms can serve
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 as its own administration and get its own TNs from a provider such as BulkVS.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 How would all of these tiny fiefdoms then add SMS capability? The feedback we
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 got from Sopranica is that asking them to set up a sub-account on their
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 Bandwidth service for each microfiefdom would be too much work - hence San Diego
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 2G Association (the primary instance of Themyscira Wireless) will need to serve
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 as a third-level reseller, getting Bandwidth SMS interconnection service from
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 Sopranica and then further subletting it to other microfiefdoms.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 Vertical hierarchy support in ThemWi-SMSC is designed to support the just-
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 described use case. Each SMSC instance has a set of locally owned mobile TNs
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 (LOMTNs, owned by the local fiefdom operating this SMSC instance), a single
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 upstream SMPP link pointing up the hierarchy tree (toward the Outside World)
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 and any number of downstream SMPP links to downstream peers. The total set of
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 phone numbers known to each SMSC instance is its own local set (themwi-nanp
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 database of locally owned TNs) plus the set of numbers assigned to downstream
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 peers - all other E.164 numbers everywhere in the world (plus all non-E.164 USA
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 SMS short codes) belong in the Outside World and are sent to the "uplink"
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 connection. Messages are then routed as follows:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 * Any SM originating from a local GSM subscriber can go to another GSM
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 subscriber, to a known downstream peer or to the Outside World.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 * Any SM that are injected directly into the SMSC from local shell access are
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 treated the same way as Mobile-Originated SMS from local GSM users - hence
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 this mechanism can be used to send SMS to the local GSM network or to the
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 Outside World.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 * Any SM coming from the uplink connection can be addressing a local GSM
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 subscriber or a downstream peer - but either way it must be a number known
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 to this SMSC, otherwise something is badly misconfigured somewhere.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 * Any SM coming from a downlink connection can go to a local GSM subscriber, to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 a different downstream peer or to the Outside World.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 1.2.1. Direction of SMPP connections
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 Despite the name "Short Message Peer to Peer", SMPP is an asymmetric client-
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 server protocol, not symmetric peer-to-peer. Our primary, above-all-else
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 requirement when it comes to SMPP is to connect to the "big daddy" SMSC of
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 Bandwidth.com, the one that allows us to receive SMS from and send SMS to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 anywhere in the Outside World. BW requires that we connect to their SMSC server
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 in the role of an SMPP client and bind as a bidirectional transceiver - both
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 message directions then flow over this single long-lived TCP connection from our
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 client to their server.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 This externally imposed requirement dictates the entire architectural design of
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 ThemWi-SMSC with respect to SMPP. Each instance of ThemWi-SMSC can have a
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 single upstream peer to whom we connect in the role of an SMPP client, and it
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 can optionally act as an SMPP server accepting TCP connections from downstream
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 peers. The master instance of ThemWi-SMSC at smsc.sandiego2g.org will point
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 its "upstream" link at Bandwidth.com SMPP server, using credentials given to us
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 by Sopranica, whereas other small fiefdoms who wish to join our service resale
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 tree will point the "upstream" link of their ThemWi-SMSC instances to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 smsc.sandiego2g.org, and we (SD2G) will assign them authentication credentials
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 and manage their downstream number pools.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 1.3. Possible use outside of originally intended North American use case
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 If your situation and/or interests do not match the very specific use case for
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 which the present software is designed (if you are located outside of North
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121 America, and/or you have no interest in attaining SMS interconnection with the
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122 national mobile telephony environment of whichever country you call home), you
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123 can still play with the present implementation of GSM-oriented SMSC: the uplink
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124 connection to the Outside World can be omitted, and if you don't have real TNs
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 (telephone numbers) in North American Numbering Plan (either because you are
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126 outside of North America or because you are in NA but not interested in official
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127 phone network interconnection), you can operate ThemWi-SMSC (plus the attached
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128 Osmocom GSM network) with fake NANP numbers instead.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 To be clear, this support for modes of usage outside of the primary design goals
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131 of ThemWi-SMSC is intended only to facilitate "play" and evaluation (getting a
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132 feel for what may be the first SMSC implementation connecting to Osmocom CNI
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133 via GSUP), not for serious long-term usage. If your actual desired use case is
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134 an isolated GSM network with a totally ad hoc or "free" numbering plan (the
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135 default which one gets with a "vanilla" installation of Osmocom CNI), or a GSM
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136 network that is interconnected with the national mobile telephony environment
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137 of some country other than USA, you need a different SMSC design that is
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138 tailored for your numbering plan (free-form or non-USA national) that will be
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
139 different from NANP, and for local telecom environment quirks that will almost
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
140 certainly be different from those in USA.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
142 If you like the general idea and overall design of ThemWi-SMSC, but require an
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143 adaptation to a different numbering plan or a different telecom environment
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144 (isolated or a national interconnect in some other country), you should be able
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145 to take the present code base and modify just the numbering plan aspects,
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146 producing a derivative-work SMSC for your different needs.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
148 2. ThemWi-SMSC software architecture
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
149
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
150 2.1. Modularity of components
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
151
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
152 A complete deployment of ThemWi-SMSC, as in our own use case at Themyscira
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
153 Wireless, includes a local GSM network (Osmocom-based) and a connection to the
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154 hierarchical SMPP tree that eventually leads to the Outside World SMS
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155 connectivity provider at the top. However, our software implementation will be
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 modular, divided into separate software components for:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
157
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
158 * The internal core of the SMSC (one daemon process and some command line
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
159 utilities);
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161 * A pair of daemon processes devoted to the task of connecting the SMSC to the
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162 local Osmocom-based GSM network, to be omitted if you don't have one;
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
163
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
164 * A dedicated daemon process serving the SMPP link to the upstream peer, to be
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
165 omitted if you have no upstream link;
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
166
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
167 * Another dedicated sw component serving downstream peer SMPP connections, one
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
168 process instance per downstream peer, or none if you have no such peers.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
169
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170 This modularity allows the software to be used and (hopefully) appreciated
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171 outside of its primary intended use case. At one extreme, someone could have
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
172 an isolated Osmocom GSM network, modify it slightly to use MSISDNs that look
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173 like (fake) NANP numbers, hook up ThemWi-SMSC and use this SMSC as a replacement
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
174 for the Osmocom-default one, paving the way for factoring the SMSC function out
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175 of OsmoMSC. At the other extreme, if someone is located in USA and wishes to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
176 interconnect to the world of SMS through the chain of 3 resellers (Bandwidth
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177 followed by Sopranica followed by San Diego 2G Association), they can run an
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
178 instance of ThemWi-SMSC without any GSM network at all. (You will still need
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
179 Osmocom libraries, but no Osmocom processes and no hardware.) In such a
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
180 deployment, all incoming SMS to your number(s) will be written into the
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
181 persistent store which you can read, and you can send outgoing SMS with a
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
182 command line utility.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
183
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
184 2.2. Persistent message store
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
185
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
186 Every SM that passes through ThemWi-SMSC gets written into an append-only
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
187 persistent message store (PMS). Because this store is append-only, no messages
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
188 are ever deleted - however, each message in PMS can be in one of two states:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
189 active or historical. An active SM is one for which the SMSC still needs to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
190 make delivery attempts, either attempts at GSM MT delivery or attempts at
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
191 delivery to the appropriate upstream or downstream SMPP peer. A historical SM
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
192 is one for which no further action will be taken by any component of our SMSC.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
193 An SM can enter "historical" state in several ways:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
194
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
195 * For some LOMTNs the act of writing incoming messages into PMS constitutes
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
196 final delivery in itself, and no other delivery actions are needed. In this
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
197 case a newly entered SM is directly written into PMS in the "historical"
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
198 state, without ever going through "active".
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
199
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200 * For messages that need to be delivered to a GSM MS or to an SMPP peer, once
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
201 that delivery has been made successfully, the message transitions from active
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
202 to historical.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
203
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
204 * In the case of failed deliveries (permament error, or expiration time reached
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
205 after repeated temporary failures), the failed message also transitions from
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
206 active to historical.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
207
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
208 The persistent message store is a simple binary file (/var/sms/pms.bin)
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
209 consisting of directly abutted 'struct sm_record' records. Each message record
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
210 is exactly 256 bytes (see struct definition - we were able to fit everything we
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
211 needed under the 256 byte mark, and then padded the struct to perfect round
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
212 size), and this perfect power-of-2 record size makes it very easy to perform
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
213 operations such as binary search via mmap or stripping initial megabytes of
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
214 historical records - see subsequent sections for more detailed description.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
215
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
216 PMS is append-only as already stated, but already-written records do not become
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
217 fully immutable until they become historical. For as long as a given SM is in
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
218 the active state, themwi-smsc-core daemon can and will update that record in
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
219 pms.bin:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
220
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
221 * For messages addressed to local GSM subscribers, dest_imsi will be filled
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
222 when the MSISDN-to-IMSI lookup operation on the destination number succeeds;
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
223
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
224 * Upon discharge (successful delivery, permanent error or validity period
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
225 expiration after temporary failures), themwi-smsc-core will transition the
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
226 sm_record into historical state by filling disposition and time_disch struct
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
227 members;
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
228
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
229 * Additional info may be written into dest_extra_info upon discharge, depending
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
230 on the destination type and thus the mode of final delivery.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
231
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
232 Once an sm_record transitions into historical state, it is then immutable for
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
233 archival purposes; archives of historical messages can be kept for years or even
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
234 decades, depending on local administration policy.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
235
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
236 2.2.1. Historical megabyte count
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
237
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
238 Given the simple binary structure of the main PMS file, each megabyte (2**20
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
239 bytes) holds exactly 4096 messages. It is envisioned that as a busy SMSC runs
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
240 for a long time, a significant number of historical messages will accumulate,
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
241 and the content of PMS may become many megabytes of historical messages followed
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
242 by some active SMs at the end. When themwi-smsc-core daemon restarts, it has
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
243 to read the entire PMS in order to collect all still-active SMs. Having to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
244 read through many megabytes of historical SMs to get to active ones at the end
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
245 becomes unacceptable at large archive sizes, hence a mechanism is needed for
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
246 marking where the historical-only portion ends and the possibly-active portion
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
247 begins.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
248
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
249 There will be an auxiliary file named historical-mb, containing a single ASCII
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
250 line giving the number of historical megabytes in pms.bin. If this file reads
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
251 1, the first 4096 SM records are historical, if the auxiliary file reads 2, the
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
252 first 8192 SM records are historical, and so forth. This auxiliary file will be
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
253 used as follows:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
254
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
255 * Upon startup, themwi-smsc-core will read this historical-mb file and skip that
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
256 many initial megabytes of pms.bin;
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
257
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
258 * At run time, themwi-smsc-core will track the index of the oldest still-active
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
259 SM in PMS. Whenever this index crosses a megabyte boundary, historical-mb
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
260 will be updated.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
261
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
262 2.2.2. Offline storage
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
263
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
264 Even with the historical-mb mechanism of the previous section, the fact remains
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
265 that disk space on live servers is not infinite. If the archive of historical
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
266 messages grows so big that it needs to be removed from the SMSC server to free
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
267 up disk space, one can carry out the following procedure:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
268
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
269 * Temporarily stop themwi-smsc-core daemon at the level of runit or systemctl
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
270 or whatever you are using - this operation will bring down the entire SMSC,
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
271 so do it during a scheduled maintenance window;
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
272
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
273 * Use dd to split pms.bin into historical and active portions:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
274
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
275 dd if=pms.bin of=pms-hist.bin bs=1048576 count=N
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
276 dd if=pms.bin of=pms-new.bin bs=1048576 skip=N
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
277
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
278 * Move pms-hist.bin to offline storage;
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
279
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
280 * Replace the long file with the shortened one:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
281
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
282 mv pms-new.bin pms.bin
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
283 echo 0 > historical-mb
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
284
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
285 * Re-enable themwi-smsc-core and restart all other SMSC daemons.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
286
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
287 2.2.3. themwi-smsc-dump reading tool
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
288
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
289 The program named themwi-smsc-dump will be a standalone command line utility
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
290 (fully static in its operation, not talking to any daemons or services) for
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
291 reading and parsing (decoding) pms.bin. It will open pms.bin with O_RDONLY, do
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
292 a read-only mmap on it, and then access this PMS as a memory-mapped file.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
293 Several different modes of operation will be provided:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
294
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
295 * It will be possible to dump and decode the entire PMS, as needed during early
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
296 debugging.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
297
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
298 * It will be possible to specify a starting date/time at which the dump should
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
299 begin. As records are added in strict forward chronological order, it is
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
300 possible to find a record nearest (by time_entry timestamp) to a given time
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
301 point by binary search, very efficient on a memory-mapped file.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
302
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
303 * Once the dump has a starting point (beginning of the file or a time point
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
304 found by binary search), the tool can be told to dump till the end, display
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
305 some count of messages, or run until a certain ending date/time is crossed.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
306
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
307 * The tool can dump all message records in the selected range, or only those
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
308 matching specific filters such as a particular source or destination type, or
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
309 a specific phone number.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
310
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
311 The complexity described above is needed for the following reasons:
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
312
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
313 * One radical idea is to grant limited access (by way of a very strict wrapper)
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
314 to themwi-smsc-dump to unprivileged users of the network served by the SMSC,
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
315 i.e., to end users. The idea is that each individual user should be able to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
316 give their ssh public key to the administrator of the community network, and
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
317 then ssh into a special restricted service on the SMSC that does not grant
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
318 any system shell access, but allows them to access services under their own
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
319 phone number. Such an empowered end user should be able to submit SMS from
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
320 their own phone number using the power of a full-size computer (as opposed to
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
321 very painful text entry on the numeric keypad of a traditional GSM phone),
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
322 and to see a full log of all messages received by or sent from their own
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
323 phone number.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
324
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
325 * By the nature of her job, the administrator of the SMSC (and of the community
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
326 GSM network to which this SMSC belongs) necessarily has access to every
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
327 message that passes through the system, all metadata and actual content.
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
328 While this access is technically necessary, an administrator who is worthy of
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
329 her trusted position must not abuse this trust, and must do everything
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
330 possible to avoid looking at users' private message content when it is not
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
331 necessary to do so for technical troubleshooting reasons. Toward this
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
332 objective, themwi-smsc-dump must make it easy to look at only technically
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
333 necessary information, without throwing unnecessary private info into the
9e364c18e0e8 beginning of architectural design spec
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
334 operator's eyeballs.