177 lines
7.5 KiB
Plaintext
177 lines
7.5 KiB
Plaintext
[[remsim-bankd]]
|
|
== osmo-remsim-bankd
|
|
|
|
The `osmo-remsim-bankd` (SIM Bank Daemon) manages one given SIM bank.
|
|
The initial implementation supports a PC/SC driver to expose any PC/SC
|
|
compatible card readers as SIM bank.
|
|
|
|
`osmo-remsim-bankd` initially connects via a RSPRO control connection to
|
|
`osmo-remsim-server` at startup, and will in turn receive a set of
|
|
initial [client,slot]:[bankd,slot] mappings. These mappings determine
|
|
which slot on the client (corresponding to a modem) is mapped to which
|
|
slot on the SIM bank. Mappings can be updated by `osmo-remsim-server`
|
|
at any given point in time.
|
|
|
|
`osmo-remsim-bankd` implements a RSPRO server, where it listens to
|
|
connections from `osmo-remsim-clients`.
|
|
|
|
As PC/SC only offers a blocking API, there is one thread per PC/SC slot.
|
|
This thread will perform blocking I/O on the socket towards the client,
|
|
and blocking API calls on PC/SC.
|
|
|
|
In terms of thread handling, we do:
|
|
|
|
* accept() handling in [spare] worker threads
|
|
** this means blocking I/O can be used, as each worker thread only has
|
|
one TCP connection
|
|
** client identifies itself with client:slot
|
|
** lookup mapping based on client:slot (using mutex for protection)
|
|
** open the reader based on the lookup result
|
|
|
|
The worker threads initially don't have any mapping to a specific
|
|
reader, and that mapping is only established at a later point after the
|
|
client has identified itself. The advantage is that the entire bankd
|
|
can live without any non-blocking I/O.
|
|
|
|
The main thread handles the connection to `osmo-remsim-server`, where it
|
|
can also use non-blocking I/O. However, re-connection would be
|
|
required, to avoid stalling all banks/cards in the event of a connection
|
|
loss to the server.
|
|
|
|
worker threads have the following states:
|
|
* INIT (just started)
|
|
* ACCEPTING (they're blocking in the accept() call on the server socket fd)
|
|
* CONNECTED_WAIT_ID (TCP established, but peer not yet identified itself)
|
|
* CONNECTED_CLIENT (TCP established, client has identified itself, no mapping)
|
|
* CONNECTED_CLIENT_MAPPED (TCP established, client has identified itself, mapping exists)
|
|
* CONNECTED_CLIENT_MAPPED_CARD (TCP established, client identified, mapping exists, card opened)
|
|
* CONNECTED_SERVER (TCP established, server has identified itself)
|
|
|
|
Once the client disconnects, or any other error occurs (such as card I/O
|
|
errors), the worker thread either returns to INIT state (closing client
|
|
socket and reader), or it terminates. Termination would mean that the
|
|
main thread would have to do non-blocking join to detect client
|
|
termination and then re-spawn clients, so the "return to INIT state"
|
|
approach seems to make more sense.
|
|
|
|
|
|
=== Running
|
|
|
|
`osmo-remsim-bankd` currently has the following command-line options:
|
|
|
|
==== SYNOPSIS
|
|
|
|
*osmo-remsim-bankd* [-h] [-V] [-d LOGOPT] -i A.B.C.D [-p <1-65535>] [-b <1-1023>] [-n <1-1023>] [-I A.B.C.D] [-P <1-65535> ]
|
|
|
|
==== OPTIONS
|
|
|
|
*-h, --help*::
|
|
Print a short help message about the supported options
|
|
*-V, --version*::
|
|
Print the software version number
|
|
*-d, --debug LOGOPT*::
|
|
Configure the logging verbosity, see <<remsim_logging>>.
|
|
*-i, --server-host A.B.C.D*::
|
|
Specify the remote IP address/hostname of the `osmo-remsim-server` to
|
|
which this bankd shall establish its RSPRO control connection. Do not specify a loopback
|
|
address or localhost, as this would in most cases result in a broken configuration where
|
|
a [usually remote] remsim-client attempts to reach the bankd via loopback, which doesn't work.
|
|
*-p, --server-port <1-65535>*::
|
|
Specify the remote TCP port number of the `osmo-remsim-server` to which
|
|
this bankd shall establish its RSPRO control connection
|
|
*-b, --bank-id <1-1023>*::
|
|
Specify the numeric bank identifier of the SIM bank this bankd
|
|
instance operates. Must be unique among all banks connecting to the
|
|
same `osmo-remsim-server`.
|
|
*-n, --num-slots <1-1023>*::
|
|
Specify the number of slots that this bankd handles.
|
|
*-I, --bind-IP A.B.C.D*::
|
|
Specify the local IP address to which the socket for incoming connections
|
|
from `osmo-remsim-clients` is bound to.
|
|
*-P, --bind-port <1-65535>*::
|
|
Specify the local TCP port to which the socket for incoming connections
|
|
from `osmo-remsim-client`s is bound to.
|
|
*-s, --permit-shared-pcsc*::
|
|
Specify whether the PC/SC readers should be accessed in SCARD_SHARE_SHARED
|
|
mode, instead of the default (SCARD_SHARE_EXCLUSIVE). Shared mode would
|
|
permit multiple application programs to access a single reader/slot/card
|
|
concurrently. This is potentially dangerous as the two programs operate
|
|
without knowledge of each other, and either of them might modify the card
|
|
state (such as the currently selected file, validated PIN, etc.) in a
|
|
way not expected by the other application.
|
|
|
|
|
|
==== Examples
|
|
.remsim-server is on 10.2.3.4, cardreader has 5 slots:
|
|
----
|
|
osmo-remsim-bankd -i 10.2.3.4 -n 5
|
|
----
|
|
.remsim-server is on 10.2.3.4, cardreader has 4 slots, local ip is 10.5.4.3
|
|
----
|
|
osmo-remsim-bankd -i 10.2.3.4 -n 4 -I 10.5.4.3
|
|
----
|
|
|
|
=== Logging
|
|
|
|
`osmo-remsim-bankd` currently logs to stdout only, and the logging
|
|
verbosity is not yet configurable. However, as the libosmocore logging
|
|
framework is used, extending this is an easy modification.
|
|
|
|
=== `bankd_pcsc_slots.csv` CSV file
|
|
|
|
bankd expects a CSV file `bankd_pcsc_slots.csv` in the current working directory at startup.
|
|
|
|
This CSV file specifies the mapping between the string names of the PCSC
|
|
readers and the RSPRO bandk/slot numbers. The format is as follows:
|
|
|
|
* first column: bankd number
|
|
* second column: slot number within bankd
|
|
* third column: extended POSIX regular expression matching the slot
|
|
|
|
.Example: CSV file mapping bankd slots 0..4 to an ACS ACR33U-A1 reader slots
|
|
----
|
|
"1","0","ACS ACR33 ICC Reader 00 00"
|
|
"1","1","ACS ACR33 ICC Reader 00 01"
|
|
"1","2","ACS ACR33 ICC Reader 00 02"
|
|
"1","3","ACS ACR33 ICC Reader 00 03"
|
|
"1","4","ACS ACR33 ICC Reader 00 04"
|
|
----
|
|
|
|
You can obtain the exact string to use as PC/SC reader name from the output of the
|
|
`pcsc_scan` utility (part of pcsc-lite package). The tool will produce output like:
|
|
|
|
.Example: Output of `pcsc_scan` utility on a system with a single reader installed
|
|
----
|
|
Scanning present readers...
|
|
0: Alcor Micro AU9560 00 00
|
|
----
|
|
|
|
In this example, there's only a single PC/SC reader available, and it has a string of
|
|
"Alcor Micro AU9560 00 00" which needs to be used in the CSV file.
|
|
|
|
NOTE:: If the reader name contains any special characters, they might need to be escaped according
|
|
to the extended POSIX regular expression syntax. See `man 7 regex` for a reference.
|
|
|
|
.Example: CSV file mapping bankd slots 0..7 to a sysmoOCTSIM:
|
|
----
|
|
"1","0","sysmocom sysmoOCTSIM \[CCID\] \(ab19180f3335355320202034463a15ff\) [0-9]{2} 00"
|
|
"1","1","sysmocom sysmoOCTSIM \[CCID\] \(ab19180f3335355320202034463a15ff\) [0-9]{2} 01"
|
|
"1","2","sysmocom sysmoOCTSIM \[CCID\] \(ab19180f3335355320202034463a15ff\) [0-9]{2} 02"
|
|
"1","3","sysmocom sysmoOCTSIM \[CCID\] \(ab19180f3335355320202034463a15ff\) [0-9]{2} 03"
|
|
"1","4","sysmocom sysmoOCTSIM \[CCID\] \(ab19180f3335355320202034463a15ff\) [0-9]{2} 04"
|
|
"1","5","sysmocom sysmoOCTSIM \[CCID\] \(ab19180f3335355320202034463a15ff\) [0-9]{2} 05"
|
|
"1","6","sysmocom sysmoOCTSIM \[CCID\] \(ab19180f3335355320202034463a15ff\) [0-9]{2} 06"
|
|
"1","7","sysmocom sysmoOCTSIM \[CCID\] \(ab19180f3335355320202034463a15ff\) [0-9]{2} 07"
|
|
----
|
|
|
|
In the above example, the +\[CCID\]+ and the +\(serialnumber\)+ both had to be escaped.
|
|
|
|
The +[0-9]\{2\}+ construct exists to perform wildcard matching, no matter which particular two-digit number
|
|
pcscd decides to use.
|
|
|
|
.Example: CSV file mapping bankd slot 0 to a OMNIKEY 3x21 Smart Card Reader:
|
|
----
|
|
"1","0","HID Global OMNIKEY 3x21 Smart Card Reader \[OMNIKEY 3x21 Smart Card Reader\] 00 00"
|
|
----
|
|
|