Add initial osmo-remsim usermanual

Change-Id: I1d9231b24b1481afcbb5758662b7d99bd59e7fdb
Harald Welte 4 years ago
parent b6b7bd1dff
commit 3c4d006146
  1. 2
  2. 44
  3. 3
  4. 12
  5. 86
  6. 4
  7. 78
  8. 98
  9. 41
  10. 31

@ -1,6 +1,6 @@
AUTOMAKE_OPTIONS = foreign dist-bzip2
SUBDIRS = src include
SUBDIRS = src include doc
EXTRA_DIST = asn1 .version

@ -79,6 +79,48 @@ then
# Generate manuals
[Generate manual PDFs [default=no]],
[osmo_ac_build_manuals=$enableval], [osmo_ac_build_manuals="no"])
AM_CONDITIONAL([BUILD_MANUALS], [test x"$osmo_ac_build_manuals" = x"yes"])
AC_ARG_VAR(OSMO_GSM_MANUALS_DIR, [path to common osmo-gsm-manuals files, overriding pkg-config and "../osmo-gsm-manuals"
if test x"$osmo_ac_build_manuals" = x"yes"
# Find OSMO_GSM_MANUALS_DIR (env, pkg-conf, fallback)
if test -n "$OSMO_GSM_MANUALS_DIR"; then
echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from env)"
OSMO_GSM_MANUALS_DIR="$($PKG_CONFIG osmo-gsm-manuals --variable=osmogsmmanualsdir 2>/dev/null)"
if test -n "$OSMO_GSM_MANUALS_DIR"; then
echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from pkg-conf)"
echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (fallback)"
if ! test -d "$OSMO_GSM_MANUALS_DIR"; then
AC_MSG_ERROR("OSMO_GSM_MANUALS_DIR does not exist! Install osmo-gsm-manuals or set OSMO_GSM_MANUALS_DIR.")
# Find and run check-depends
if ! test -x "$CHECK_DEPENDS"; then
if ! $CHECK_DEPENDS; then
AC_MSG_ERROR("missing dependencies for --enable-manuals")
# Put in Makefile with absolute path
@ -87,6 +129,8 @@ AC_MSG_RESULT([CPPFLAGS="$CPPFLAGS"])

@ -0,0 +1,3 @@
manuals \

@ -0,0 +1,12 @@
osmo-remsim-usermanual.adoc \
osmo-remsim-usermanual-docinfo.xml \
ASCIIDOC = osmo-remsim-usermanual.adoc
include $(OSMO_GSM_MANUALS_DIR)/build/
osmo-remsim-usermanual.pdf: $(srcdir)/chapters/*.adoc
include $(OSMO_GSM_MANUALS_DIR)/build/

@ -0,0 +1,86 @@
== Overview
=== About this manual
This manual should help you getting started with the osmo-remsim software.
It will cover aspects of configuration and running osmo-remsim as well as some
introduction about its internal architecture and external interfaces.
=== About osmo-remsim
osmo-remsim is a suite of software programs enabling physical/geographic
separation of a cellular phone (or modem) on the one hand side and the
SIM/USIM/ISIM card on the other side.
Using osmo-remsim, you can operate an entire fleet of modems/phones, as
well as banks of SIM cards and dynamically establish or remove the
connections between modems/phones and cards.
So in technical terms, it behaves like a proxy for the ISO 7816 smart
card interface between the MS/UE and the UICC/SIM/USIM/ISIM.
While originally designed to be used in context of cellular networks,
there is nothing cellular specific in the system. It can therefore also
be used with other systems that use contact based smart cards according
to ISO 7816. Currently only the T=0 protocol with standard
(non-extended) APDUs is supported. Both T=1 and extended APDU support
can easily be added as a pure software update, should it be required at
some future point.
=== Credits
osmo-remsim was originally developed by Harald Welte with contributions
by Kevin Redon. It builds on top of pre-existing infrastructure of
the Osmocom project, including the Osmocom SIMtrace project.
Development of osmo-remsim software was funded by GSMK and sysmocom.
=== remsim-server
The remsim-server is the central element of the osmo-remsim
architecture. All other elements connect to it. It maintains the
inventory of other network elements, as well as the list of
slot-mappings, i.e. the relationship between each given physical card
in a bank and each card emulator attached to a phone/modem.
The tasks of remsim-server include:
* accepting incoming TCP control connections from remsim-client and
remsim-bankd instances
* providing a RESTful JSON interface for external application logic to
=== remsim-client
The remsim-client software is co-located next to a cellular phone/modem.
It typically runs on an [embedded] computer next to the phone/modem.
The tasks of remsim-client include:
* interaction over USB with a device supported by the 'SIMtrace2 cardem'
firmware, which provides the physical interface to the phone/modem SIM
* establishing a TCP connection with the remsim-server, in order to
enable the server to issue control commands
* under control of remsim-server, establishing a TCP connection to a
remsim-bankd in order to connect a card physically located at the
remsim-client supports at this point only one phone/modem. If you have
multiple phones/modems at one location, you can simply run multiple
instances of remsim-client on the same system, one for each phone/modem.
=== remsim-bankd
The remsim-bankd software is co-located next to a bank of SIM cards.
The tasks of remsim-bankd include:
* interaction with the actual card reader hardware. At this point, only
PC/SC based readers are supported, with 1 to 255 slots per reader.
* establishing a TCP connection with the remsim-server, in order to
enable the server to issue control commands
* running a TCP server where TCP connections from remsim-client
instances are accepted and handled.

@ -12,8 +12,8 @@ remsim-bankd currently has the following command-line options:
*-h, --help*::
Print a short help message about the supported options
*-i, --server-ip A.B.C.D*::
Specify the remote IP address of the remsim-server to which this bankd
*-i, --server-host A.B.C.D*::
Specify the remote IP address/hostname of the remsim-server to which this bankd
shall establish its <<RSPRO>> control connection
*-p, --server-port <1-65535>*::
Specify the remote TCP port number of the remsim-server to whihc this bankd

@ -0,0 +1,78 @@
== remsim-server
=== Running
`remsim-server` currently has no command-line arguments. It will bind to
INADDR_ANY and offer the following TCP ports:
* Port 9998 for the inbound control connections from `remsim-client`
and `remsim-bankd`
* Port 9997 for the RESTful/JSON Web API (role: HTTP server)
It is intended to make these settings (IP addresses, ports) configurable
in future versions.
=== Logging
`remsim-server` 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.
=== RESTful/JSON Web API
`remsim-server` provides a RESTful/JSON WEB API for application logic
integration. The purpose of the API is to allow run-time configuration
and monitoring of the entire osmo-remsim system.
The API currently has version 1, and the URL prefix is /api/backend/v1
==== /api/backend/v1/clients
*GET* obtains a JSON list where each element represents one currently
connected `remsim-client`.
No other HTTP operation is implemented.
==== /api/backend/v1/clients/:client_id
*GET* obtains a single JSON object representing one specific currently
connected `remsim-client`.
No other HTTP operation is implemented.
==== /api/backend/v1/bankds
*GET* obtains a JSON list where each element represents one currently
connected `remsim-bankd`.
No other HTTP operation is implemented.
==== /api/backend/v1/bankds/:bank_id
*GET* obtains a single JSON object representing one specific currently
connected `remsim-bankd`.
No other HTTP operation is implemented.
==== /api/backend/v1/slotmaps
*GET* obtains a JSON list where each element represents one provisioned
slot mapping.
*POST* creates a new slot mapping as specified in the JSON syntax
contained in the HTTP body.
No other HTTP operation is implemented.
==== /api/backend/v1/slotmaps/:slotmap_id
*DELETE* deletes a slot mapping by its identifier. If the mapping is
currently in use, the related bankd is instructed to disconnect the
client from the card.
No other HTTP operation is implemented.
==== /api/backend/v1/global-reset
*POST* performs a global reset of the `remsim-server` state. This means
all mappings are removed.

@ -0,0 +1,98 @@
*RSPRO*, the *Remote SIM Protocol*, is an osmo-remsim specific,
non-standard communications protocol used between the elements of the
osmo-remsim system.
It is specified in ASN.1 syntax (see `asn1/RSPRO.asn` in the
`osmo-remsim` source code) and uses BER (Basic Encoding Rules) on the
transport level.
=== Underlying Transport Layer
RSPRO uses TCP as an underlying transport protocol. As TCP doesn't
preserve message boundaries, the IPA multiplex is used as intermediate
layer between TCP and the BER-encoded RSPRO PDU.
For more information about the IPA multiplex, see the related chapter
RSPRO uses the IPA CCM PING/PONG messages for keep-alive and detection
of dead/stale connections. The compiled-in defaults transmits one IPA
PING every 30s and waits 10s for a response from the peer before
declaring the connection as dead.
An RsproPDU consists of:
* *version* of the protocol (v2 is current)
* *tag* specified by the sender, echoed back by the receiver in
its response so the server can map responses back to a specific
* *msg* the actual RSPRO Message (union/choice)
=== RSPRO Operations
Each RSPRO Operation typically (unless specified othewise) consists of a
Request and Response pair.
==== ConnectBank
This is used by `remsim-bankd` to identify itself to `remsim-server` and
to establish a logical connection between the two elements.
==== ConnectClient
This is used by `remsim-client` to identify itself to `remsim-server`
and to establish a logical connection between the two elements.
==== CreateMapping
This is used by `remsim-server` to install a slot mapping in a
==== RemoveMapping
This is used by `remsim-server` to remove a slot mapping from a
==== ConfigClientId
This is used by `remsim-server` to dynamically configure a ClientID in a
`remsim-client`. This mode is currently not supported yet, each client
must have a locally-configured ClientID.
==== ConfigClientBank
This is used by `remsim-server` to inform a `remsim-client` about the
details (bankd ID, slot number, IP address, TCP port) of a the
`remsim-bankd` to which it shall connect.
==== ErrorInd
This is a generic error indication that can be sent by any RSRPO entity.
==== SetAtr
This is used by `remsim-bankd` to inform the `remsim-client` about the
ATR of the card, so that `remsim-client` can replicate that ATR when
answering to the reset of the SIM card interface of the phone/modem.
==== TpduModemToCard
This is used by `remsim-client` to transfer a command TPDU/APDU from the
phone/modem to the SIM card in `remsim-bankd`
==== TpduCardToModem
This is used by `remsim-bankd` to transfer a response TPDU/APDU from the
SIM card back to the phone/modem at `remsim-client`.
==== ClientSlotStatusInd
This is used by `remsim-client` to report the status of a given slot.
==== BankSlotStatusInd
This is used by `remsim-bankd` to report the status of a given slot.

@ -0,0 +1,41 @@
<date>March 2019</date>
Initial version.
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
<jobtitle>Managing Director</jobtitle>
<holder>sysmocom - s.f.m.c. GmbH</holder>
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with the Invariant Sections being just 'Foreword',
'Acknowledgements' and 'Preface', with no Front-Cover Texts,
and no Back-Cover Texts. A copy of the license is included in
the section entitled "GNU Free Documentation License".

@ -0,0 +1,31 @@
osmo-remsim User Manual
Harald Welte <>