From 3c4d0061463a31df621981e55e193067d81c343a Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Sun, 31 Mar 2019 18:55:18 +0200 Subject: [PATCH] Add initial osmo-remsim usermanual Change-Id: I1d9231b24b1481afcbb5758662b7d99bd59e7fdb --- Makefile.am | 2 +- configure.ac | 44 +++++++++ doc/Makefile.am | 3 + doc/manuals/Makefile.am | 12 +++ doc/manuals/chapters/overview.adoc | 86 ++++++++++++++++ doc/manuals/chapters/remsim-bankd.adoc | 4 +- doc/manuals/chapters/remsim-server.adoc | 78 +++++++++++++++ doc/manuals/chapters/rspro.adoc | 98 +++++++++++++++++++ .../osmo-remsim-usermanual-docinfo.xml | 41 ++++++++ doc/manuals/osmo-remsim-usermanual.adoc | 31 ++++++ 10 files changed, 396 insertions(+), 3 deletions(-) create mode 100644 doc/Makefile.am create mode 100644 doc/manuals/Makefile.am create mode 100644 doc/manuals/chapters/overview.adoc create mode 100644 doc/manuals/chapters/remsim-server.adoc create mode 100644 doc/manuals/chapters/rspro.adoc create mode 100644 doc/manuals/osmo-remsim-usermanual-docinfo.xml create mode 100644 doc/manuals/osmo-remsim-usermanual.adoc diff --git a/Makefile.am b/Makefile.am index 9832b58..ec76bff 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,6 +1,6 @@ AUTOMAKE_OPTIONS = foreign dist-bzip2 -SUBDIRS = src include +SUBDIRS = src include doc EXTRA_DIST = asn1 .version README.md diff --git a/configure.ac b/configure.ac index 7a07f6b..7281196 100644 --- a/configure.ac +++ b/configure.ac @@ -79,6 +79,48 @@ then CPPFLAGS="$CPPFLAGS $WERROR_FLAGS" 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" CPPFLAGS="$CPPFLAGS -Wall" @@ -87,6 +129,8 @@ AC_MSG_RESULT([CPPFLAGS="$CPPFLAGS"]) AC_OUTPUT( Makefile + doc/Makefile + doc/manuals/Makefile src/Makefile src/rspro/Makefile src/server/Makefile diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..adfdcf7 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,3 @@ +SUBDIRS = \ + manuals \ + $(NULL) diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am new file mode 100644 index 0000000..36ca4f2 --- /dev/null +++ b/doc/manuals/Makefile.am @@ -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 diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc new file mode 100644 index 0000000..0a303b1 --- /dev/null +++ b/doc/manuals/chapters/overview.adoc @@ -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. + + diff --git a/doc/manuals/chapters/remsim-bankd.adoc b/doc/manuals/chapters/remsim-bankd.adoc index a3e708d..11a8811 100644 --- a/doc/manuals/chapters/remsim-bankd.adoc +++ b/doc/manuals/chapters/remsim-bankd.adoc @@ -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 <> control connection *-p, --server-port <1-65535>*:: Specify the remote TCP port number of the remsim-server to whihc this bankd diff --git a/doc/manuals/chapters/remsim-server.adoc b/doc/manuals/chapters/remsim-server.adoc new file mode 100644 index 0000000..fcb7283 --- /dev/null +++ b/doc/manuals/chapters/remsim-server.adoc @@ -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. diff --git a/doc/manuals/chapters/rspro.adoc b/doc/manuals/chapters/rspro.adoc new file mode 100644 index 0000000..1ce511e --- /dev/null +++ b/doc/manuals/chapters/rspro.adoc @@ -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. diff --git a/doc/manuals/osmo-remsim-usermanual-docinfo.xml b/doc/manuals/osmo-remsim-usermanual-docinfo.xml new file mode 100644 index 0000000..a1ceb6d --- /dev/null +++ b/doc/manuals/osmo-remsim-usermanual-docinfo.xml @@ -0,0 +1,41 @@ + + + 1 + March 2019 + HW + + Initial version. + + + + + + + Harald + Welte + hwelte@sysmocom.de + HW + + sysmocom + sysmocom - s.f.m.c. GmbH + Managing Director + + + + + + 2019 + sysmocom - s.f.m.c. GmbH + + + + + 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". + + diff --git a/doc/manuals/osmo-remsim-usermanual.adoc b/doc/manuals/osmo-remsim-usermanual.adoc new file mode 100644 index 0000000..88e3dad --- /dev/null +++ b/doc/manuals/osmo-remsim-usermanual.adoc @@ -0,0 +1,31 @@ +:gfdl-enabled: + +osmo-remsim User Manual +======================= +Harald Welte + +//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[]