Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 1 | == remsim-bankd |
| 2 | |
Harald Welte | 35f2b20 | 2019-04-01 11:01:51 +0200 | [diff] [blame] | 3 | The `remsim-bankd` (SIM Bank Daemon) manages one given SIM bank. The |
| 4 | initial implementation supports a PC/SC driver to expose any PC/SC |
| 5 | compatible card readers as SIM bank. |
| 6 | |
| 7 | `remsim-bankd` initially connects via a RSPRO control connection to |
| 8 | `remsim-server` at startup, and will in turn receive a set of initial |
| 9 | [client,slot]:[bankd,slot] mappings. These mappings determine which |
| 10 | slot on the client (corresponding to a modem) is mapped to which slot on |
| 11 | the SIM bank. Mappings can be updated by `remsim-server` at any given |
| 12 | point in time. |
| 13 | |
| 14 | `remsim-bankd` implements a RSPRO server, where it listens to connections |
| 15 | from `remsim-clients`. |
| 16 | |
| 17 | As PC/SC only offers a blocking API, there is one thread per PC/SC slot. |
| 18 | This thread will perform blocking I/O on the socket towards the client, |
| 19 | and blocking API calls on PC/SC. |
| 20 | |
| 21 | In terms of thread handling, we do: |
| 22 | |
| 23 | * accept() handling in [spare] worker threads |
| 24 | ** this means blocking I/O can be used, as each worker thread only has |
| 25 | one TCP connection |
| 26 | ** client identifies itself with client:slot |
| 27 | ** lookup mapping based on client:slot (using mutex for protection) |
| 28 | ** open the reader based on the lookup result |
| 29 | |
| 30 | The worker threads initially don't have any mapping to a specific |
| 31 | reader, and that mapping is only established at a later point after the |
| 32 | client has identified itself. The advantage is that the entire bankd |
| 33 | can live without any non-blocking I/O. |
| 34 | |
| 35 | The main thread handles the connection to `remsim-server`, where it can |
| 36 | also use non-blocking I/O. However, re-connection would be required, to |
| 37 | avoid stalling all banks/cards in the event of a connection loss to the |
| 38 | server. |
| 39 | |
| 40 | worker threads have the following states: |
| 41 | * INIT (just started) |
| 42 | * ACCEPTING (they're blocking in the accept() call on the server socket fd) |
| 43 | * CONNECTED_WAIT_ID (TCP established, but peer not yet identified itself) |
| 44 | * CONNECTED_CLIENT (TCP established, client has identified itself, no mapping) |
| 45 | * CONNECTED_CLIENT_MAPPED (TCP established, client has identified itself, mapping exists) |
| 46 | * CONNECTED_CLIENT_MAPPED_CARD (TCP established, client identified, mapping exists, card opened) |
| 47 | * CONNECTED_SERVER (TCP established, server has identified itself) |
| 48 | |
| 49 | Once the client disconnects, or any other error occurs (such as card I/O |
| 50 | errors), the worker thread either returns to INIT state (closing client |
| 51 | socket and reader), or it terminates. Termination would mean that the |
| 52 | main thread would have to do non-blocking join to detect client |
| 53 | termination and then re-spawn clients, so the "return to INIT state" |
| 54 | approach seems to make more sense. |
| 55 | |
| 56 | |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 57 | === Running |
| 58 | |
Harald Welte | 35f2b20 | 2019-04-01 11:01:51 +0200 | [diff] [blame] | 59 | `remsim-bankd` currently has the following command-line options: |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 60 | |
| 61 | ==== SYNOPSIS |
| 62 | |
Harald Welte | 2513d81 | 2019-04-01 21:03:02 +0200 | [diff] [blame^] | 63 | *remsim-bankd* [-h] [-i A.B.C.D] [-p <1-65535>] [-b <1-65535>] [-n <1-65535>] [-I A.B.C.D] [-P <1-65535> ] |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 64 | |
| 65 | ==== OPTIONS |
| 66 | |
| 67 | *-h, --help*:: |
| 68 | Print a short help message about the supported options |
Harald Welte | 3c4d006 | 2019-03-31 18:55:18 +0200 | [diff] [blame] | 69 | *-i, --server-host A.B.C.D*:: |
| 70 | Specify the remote IP address/hostname of the remsim-server to which this bankd |
Harald Welte | 0138bb4 | 2019-04-01 11:04:04 +0200 | [diff] [blame] | 71 | shall establish its RSPRO control connection |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 72 | *-p, --server-port <1-65535>*:: |
| 73 | Specify the remote TCP port number of the remsim-server to whihc this bankd |
Harald Welte | 0138bb4 | 2019-04-01 11:04:04 +0200 | [diff] [blame] | 74 | shall establish its RSPRO control connection |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 75 | *-b, --bank-id <1-65535>*:: |
| 76 | Specify the numeric bank identifier of the SIM bank this bankd instance |
| 77 | operates. Must be unique among all banks connecting to the same remsim-server. |
Harald Welte | 2513d81 | 2019-04-01 21:03:02 +0200 | [diff] [blame^] | 78 | *-n, --num-slots <1-65535>*:: |
| 79 | Specify the number of slots that this bankd handles. |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 80 | *-I, --bind-IP A.B.C.D*:: |
| 81 | Specify the local IP address to which the socket for incoming connections |
| 82 | from remsim-clients is bound to. |
| 83 | *-P, --bind-port <1-65535>*:: |
| 84 | Specify the local TCP port to whicc the socket for incoming connections |
| 85 | from remsim-clients is bound to. |
| 86 | |
| 87 | === Logging |
| 88 | |
| 89 | remsim-bankd currently logs to stdout only, and the logging verbosity |
| 90 | is not yet configurable. However, as the libosmocore logging framework |
| 91 | is used, extending this is an easy modification. |
| 92 | |
| 93 | === `bankd_pcsc_slots.csv` CSV file |
| 94 | |
| 95 | bankd expects a CSV file `bankd_pcsc_slots.csv` in the current working directory at startup. |
| 96 | |
| 97 | This CSV file specifies the mapping between the string names of the PCSC |
Harald Welte | 0138bb4 | 2019-04-01 11:04:04 +0200 | [diff] [blame] | 98 | readers and the RSPRO bandk/slot numbers. The format is as follows: |
Harald Welte | 5bae20b | 2019-04-01 09:36:42 +0200 | [diff] [blame] | 99 | |
| 100 | .Example: CSV file mapping bankd slots 0..4 to an ACS ACR33U-A1 reader slots |
| 101 | ---- |
| 102 | "1","0","ACS ACR33 ICC Reader 00 00" |
| 103 | "1","1","ACS ACR33 ICC Reader 00 01" |
| 104 | "1","2","ACS ACR33 ICC Reader 00 02" |
| 105 | "1","3","ACS ACR33 ICC Reader 00 03" |
| 106 | "1","4","ACS ACR33 ICC Reader 00 04" |
| 107 | ---- |