Add initial osmo-remsim usermanual
Change-Id: I1d9231b24b1481afcbb5758662b7d99bd59e7fdb
This commit is contained in:
parent
b6b7bd1dff
commit
3c4d006146
|
@ -1,6 +1,6 @@
|
||||||
AUTOMAKE_OPTIONS = foreign dist-bzip2
|
AUTOMAKE_OPTIONS = foreign dist-bzip2
|
||||||
|
|
||||||
SUBDIRS = src include
|
SUBDIRS = src include doc
|
||||||
|
|
||||||
EXTRA_DIST = asn1 .version README.md
|
EXTRA_DIST = asn1 .version README.md
|
||||||
|
|
||||||
|
|
44
configure.ac
44
configure.ac
|
@ -79,6 +79,48 @@ then
|
||||||
CPPFLAGS="$CPPFLAGS $WERROR_FLAGS"
|
CPPFLAGS="$CPPFLAGS $WERROR_FLAGS"
|
||||||
fi
|
fi
|
||||||
|
|
||||||
|
# Generate manuals
|
||||||
|
AC_ARG_ENABLE(manuals,
|
||||||
|
[AS_HELP_STRING(
|
||||||
|
[--enable-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"
|
||||||
|
fallback])
|
||||||
|
if test x"$osmo_ac_build_manuals" = x"yes"
|
||||||
|
then
|
||||||
|
# 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)"
|
||||||
|
else
|
||||||
|
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)"
|
||||||
|
else
|
||||||
|
OSMO_GSM_MANUALS_DIR="../osmo-gsm-manuals"
|
||||||
|
echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (fallback)"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
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.")
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Find and run check-depends
|
||||||
|
CHECK_DEPENDS="$OSMO_GSM_MANUALS_DIR/check-depends.sh"
|
||||||
|
if ! test -x "$CHECK_DEPENDS"; then
|
||||||
|
CHECK_DEPENDS="osmo-gsm-manuals-check-depends"
|
||||||
|
fi
|
||||||
|
if ! $CHECK_DEPENDS; then
|
||||||
|
AC_MSG_ERROR("missing dependencies for --enable-manuals")
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Put in Makefile with absolute path
|
||||||
|
OSMO_GSM_MANUALS_DIR="$(realpath "$OSMO_GSM_MANUALS_DIR")"
|
||||||
|
AC_SUBST([OSMO_GSM_MANUALS_DIR])
|
||||||
|
fi
|
||||||
|
|
||||||
CFLAGS="$CFLAGS -Wall"
|
CFLAGS="$CFLAGS -Wall"
|
||||||
CPPFLAGS="$CPPFLAGS -Wall"
|
CPPFLAGS="$CPPFLAGS -Wall"
|
||||||
|
|
||||||
|
@ -87,6 +129,8 @@ AC_MSG_RESULT([CPPFLAGS="$CPPFLAGS"])
|
||||||
|
|
||||||
AC_OUTPUT(
|
AC_OUTPUT(
|
||||||
Makefile
|
Makefile
|
||||||
|
doc/Makefile
|
||||||
|
doc/manuals/Makefile
|
||||||
src/Makefile
|
src/Makefile
|
||||||
src/rspro/Makefile
|
src/rspro/Makefile
|
||||||
src/server/Makefile
|
src/server/Makefile
|
||||||
|
|
|
@ -0,0 +1,3 @@
|
||||||
|
SUBDIRS = \
|
||||||
|
manuals \
|
||||||
|
$(NULL)
|
|
@ -0,0 +1,12 @@
|
||||||
|
EXTRA_DIST = \
|
||||||
|
osmo-remsim-usermanual.adoc \
|
||||||
|
osmo-remsim-usermanual-docinfo.xml \
|
||||||
|
chapters
|
||||||
|
|
||||||
|
if BUILD_MANUALS
|
||||||
|
ASCIIDOC = osmo-remsim-usermanual.adoc
|
||||||
|
include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
|
||||||
|
osmo-remsim-usermanual.pdf: $(srcdir)/chapters/*.adoc
|
||||||
|
|
||||||
|
include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc
|
||||||
|
endif
|
|
@ -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
|
||||||
|
interface
|
||||||
|
* 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
|
||||||
|
bankd.
|
||||||
|
|
||||||
|
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*::
|
*-h, --help*::
|
||||||
Print a short help message about the supported options
|
Print a short help message about the supported options
|
||||||
*-i, --server-ip A.B.C.D*::
|
*-i, --server-host A.B.C.D*::
|
||||||
Specify the remote IP address of the remsim-server to which this bankd
|
Specify the remote IP address/hostname of the remsim-server to which this bankd
|
||||||
shall establish its <<RSPRO>> control connection
|
shall establish its <<RSPRO>> control connection
|
||||||
*-p, --server-port <1-65535>*::
|
*-p, --server-port <1-65535>*::
|
||||||
Specify the remote TCP port number of the remsim-server to whihc this bankd
|
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
|
||||||
|
|
||||||
|
*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
|
||||||
|
in http://ftp.osmocom.org/docs/latest/osmobts-abis.pdf
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
=== RSPRO PDU
|
||||||
|
|
||||||
|
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
|
||||||
|
request
|
||||||
|
* *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
|
||||||
|
`remsim-bankd`.
|
||||||
|
|
||||||
|
==== RemoveMapping
|
||||||
|
|
||||||
|
This is used by `remsim-server` to remove a slot mapping from a
|
||||||
|
`remsim-bankd`.
|
||||||
|
|
||||||
|
==== 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 @@
|
||||||
|
<revhistory>
|
||||||
|
<revision>
|
||||||
|
<revnumber>1</revnumber>
|
||||||
|
<date>March 2019</date>
|
||||||
|
<authorinitials>HW</authorinitials>
|
||||||
|
<revremark>
|
||||||
|
Initial version.
|
||||||
|
</revremark>
|
||||||
|
</revision>
|
||||||
|
</revhistory>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Harald</firstname>
|
||||||
|
<surname>Welte</surname>
|
||||||
|
<email>hwelte@sysmocom.de</email>
|
||||||
|
<authorinitials>HW</authorinitials>
|
||||||
|
<affiliation>
|
||||||
|
<shortaffil>sysmocom</shortaffil>
|
||||||
|
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
|
||||||
|
<jobtitle>Managing Director</jobtitle>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>2019</year>
|
||||||
|
<holder>sysmocom - s.f.m.c. GmbH</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
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".
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
|
@ -0,0 +1,31 @@
|
||||||
|
:gfdl-enabled:
|
||||||
|
|
||||||
|
osmo-remsim User Manual
|
||||||
|
=======================
|
||||||
|
Harald Welte <hwelte@sysmocom.de>
|
||||||
|
|
||||||
|
//include::./common/chapters/preface.adoc[]
|
||||||
|
|
||||||
|
include::{srcdir}/chapters/overview.adoc[]
|
||||||
|
|
||||||
|
include::{srcdir}/chapters/remsim-server.adoc[]
|
||||||
|
|
||||||
|
include::{srcdir}/chapters/remsim-client.adoc[]
|
||||||
|
|
||||||
|
include::{srcdir}/chapters/remsim-bankd.adoc[]
|
||||||
|
|
||||||
|
include::{srcdir}/chapters/rspro.adoc[]
|
||||||
|
|
||||||
|
//include::./common/chapters/vty.adoc[]
|
||||||
|
|
||||||
|
//include::./common/chapters/logging.adoc[]
|
||||||
|
|
||||||
|
include::{srcdir}/chapters/architecture.adoc[]
|
||||||
|
|
||||||
|
//include::./common/chapters/port_numbers.adoc[]
|
||||||
|
|
||||||
|
include::./common/chapters/bibliography.adoc[]
|
||||||
|
|
||||||
|
include::./common/chapters/glossary.adoc[]
|
||||||
|
|
||||||
|
include::./common/chapters/gfdl.adoc[]
|
Loading…
Reference in New Issue