osmo-remsim/doc/manuals/chapters/remsim-client.adoc

156 lines
7.2 KiB
Plaintext

== osmo-remsim-client-st2
The client interfaces with GSM phones / modems via dedicated "Card
Emulation" devices such as the Osmocom SIMtrace2 or sysmocom sysmoQMOD
board + firmware. This hardware implements the ISO7816-3 electrical
interface and protocol handling and passes any TPDU headers received
from the phone/modem to `osmo-remsim-client` for further processing of
the TPDUs associated to the given APDU transfer.
`osmo-remsim-client` connects via a RSPRO control connection to
`osmo-remsim-server` at startup and registers itself. It will receive
configuration data such as the `osmo-remsim-bankd` IP+Port and the
ClientId from `osmo-remsim-server`.
After receiving the configuration, `osmo-remsim-client` will establish a
RSPRO data connection to the `osmo-remsim-bankd` IP:Port.
As the USB interface for remote SIM in simtrace2.git uses one interface
per slot, we can implement the client in blocking mode, i.e. use
blocking I/O on the TCP/RSPRO side. This simplifies the code compared
to a more complex async implementation.
=== Running
osmo-remsim-client-st2 currently has the following command-line options:
==== SYNOPSIS
*osmo-remsim-client-st2* [...]
==== OPTIONS
*-h, --help*::
Print a short help message about the supported options
*-s, --server-host A.B.C.D*::
Specify the remote IP address / hostname of the `osmo-remsim-server` to
which this client shall establish its RSPRO control connection
*-p, --server-port <1-65535>*::
Specify the remote TCP port number of the `osmo-remsim-server` to which
this client shall establish its RSPRO control connection
*-c, --client-id <1-65535>*::
Specify the numeric client identifier of the SIM bank this bankd
instance operates. The tuple of client-id and client-slot must be
unique among all clients connecting to the same `osmo-remsim-server`.
*-n, --client-slot <0-65535>*::
Specify the slot number served within this client. The tuple of
client-id and client-slot must be unique among all clients connecting
to the same `osmo-remsim-server`.
*-i, --gsmtap-ip A.B.C.D*::
Specify the IP address (if any) to which APDU traces are sent in
GSMTAP format (useful for debugging; supported by wireshark).
*-k, --keep-running*::
Specify if the `osmo-remsim-client` should terminate after handling one
session, or whether it should keep running. Fast respawn (i.e. no
--keep-running) is probably the more robust option at this point.
*-V, --usb-vendor*::
Specify the USB Vendor ID of the USB device served by this client,
use e.g. 0x1d50 for SIMtrace2, sysmoQMOD and OWHW.
*-P, --usb-product*::
Specify the USB Product ID of the USB device served by this client,
use e.g. 0x4004 for sysmoQMOD.
*-C, --usb-config*::
Specify the USB Cofiguration number of the USB device served by this
client. Default will use current configuration of the device.
*-I, --usb-interface*::
Specify the USB Interface number (within active configuration) of the
USB device served by this client. Default will use FIXME.
*-S, --usb-altsetting*::
Specify the USB Alternate Setting to be used within the USB Interface
of the USB device served by this client. Default will use FIXME.
*-A, --usb-address <0-255>*::
Specify the USB Address of the USB device served by this client. This
is useful in case multiple identical USB devices are attached to the
same host. However, the address changed at every re-enumeration and
it's therefor recommended to use the USB path (see below).
*-H, --usb-path*::
Specify the USB path of the USB device served by this client. This is
usefule to disambiguate between multiple identical USB devices
attached to the same host. You don't need this if you have only one
SIM emulation device attached to your system.
*-a, --atr HEXSTRING*::
Specify the initial ATR to be communicated to the modem/phone. Can
and will later be overridden by the ATR as specified by
`osmo-remsim-bankd` once a card has been mapped to this client.
*-e, --event-script COMMAND*::
Specify the shell command to be execute when the client wants to call its
helper script
==== Examples
.remsim-server is on 10.2.3.4, sysmoQMOD on usb bus, all 4 modems:
----
osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 0 -H 2-1.1 -c 0 -n 0
osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 1 -H 2-1.1 -c 0 -n 1
osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 0 -H 2-1.4 -c 0 -n 2
osmo-remsim-client-st2 -s 10.2.3.4 -V 1d50 -P 4004 -C 1 -I 1 -H 2-1.4 -c 0 -n 3
----
=== Logging
`osmo-remsim-client` 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.
=== Helper Script
`osmo-remsim-client` can call an external shell command / script / program at specific
instances of time. This serves two purposes:
* To keep external system integration posted about the overall status of remsim-client,
such as whether or not it is connected to a server and/or bankd.
* To request the external system to perform specific actions, such as triggering the reset
of the modem - in case the hardware doesn't allow the simtrace2 firmware to do that itself.
==== Script Environment Variables
The environment passed to the helper script contains a number of variables to provide inormation
to the external script:
.Environment Variables
[options="header",cols="27%,18%,55%"]
|===
| Name | Example Value | Description
| REMSIM_CLIENT_VERSION | 0.2.2.37-5406a | Compile version of the software
| REMSIM_SERVER_ADDR | 1.2.3.4:1234 | Address and port of the remsim-server
| REMSIM_SERVER_STATE | CONNECTED | FSM state of the connection to remsim-server
| REMSIM_BANKD_ADDR | 1.2.3.4:1234 | Address and port of the remsim-bankd
| REMSIM_BANKD_STATE | CONNECTED | FSM state of the connection to remsim-bankd
| REMSIM_CLIENT_SLOT | 23:42 | Client ID and Client Slot Number
| REMSIM_BANKD_SLOT | 55:33 | Bank ID and Bank Slot Number
| REMSIM_USB_PATH | 2-1.1 | USB path of the USB device with simtrace2 cardem firmware
| REMSIM_USB_INTERFACE | 1 | Interface number of the USB device with simtrace2 cardem firmware
| REMSIM_SIM_VCC | 1 | Whether or not the modem currently applies SIM VCC (0/1)
| REMSIM_SIM_RST | 1 | Whether or not the modem currently asserts SIM RST (0=inactive, 1=active)
| REMSIM_CAUSE | request-card-insert | The cause why this script has been called
|===
==== REMSIM_CAUSE values
The REMSIM_CAUSE environment variable (as well as the first argument) passed to the helper
script indicated why the script has been called.
[options="header",cols="25%,75%"]
|===
| Name | Description
| event-modem-status | The SIM card interface status has changed (e.g. VCC/RST change)
| event-bankd-connect | A logical RSPRO connection to a bankd has been established
| event-server-connect | A logical RSPRO connection to a server has been established
| event-config-bankd | The server has instructed the client of the bankd address
| request-card-insert | The client asks the system to simulate SIM card insertion to the modem
| request-card-remove | The client asks the system to simulate SIM card removal from the modem
| request-sim-remote | The client asks the system to switch to remote SIM
| request-sim-local | The client asks the system to switch to local SIM
| request-modem-reset | The client asks the system to perform a modem reset
|===