Add initial osmo-remsim usermanual
Change-Id: I1d9231b24b1481afcbb5758662b7d99bd59e7fdbchanges/97/13497/1
parent
b6b7bd1dff
commit
3c4d006146
|
|
@ -1,6 +1,6 @@
|
|||
AUTOMAKE_OPTIONS = foreign dist-bzip2
|
||||
|
||||
SUBDIRS = src include
|
||||
SUBDIRS = src include doc
|
||||
|
||||
EXTRA_DIST = asn1 .version README.md
|
||||
|
||||
|
|
|
|||
44
configure.ac
44
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
|
||||
|
|
|
|||
|
|
@ -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*::
|
||||
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
|
||||
|
||||
*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