Add initial osmo-remsim usermanual
Change-Id: I1d9231b24b1481afcbb5758662b7d99bd59e7fdb
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 @@
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_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 @@
*-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
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 @@
+<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>
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 <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[]