doc/manuals/chapters/remsim-bankd.adoc

[[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"
----