Add initial osmo-remsim usermanual

Change-Id: I1d9231b24b1481afcbb5758662b7d99bd59e7fdb

10 files changed, 396 insertions, 3 deletions

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 <<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[]