Add manual for OsmoSIPConnector

Ticket: OS#1684
Change-Id: I70d3014deb459e0b91a9a92c60710b994153538e

6 files changed, 233 insertions, 0 deletions

diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile
index 5a47759..cd3bb89 100644
--- a/doc/manuals/Makefile
+++ b/doc/manuals/Makefile
@@ -1,5 +1,9 @@
 TOPDIR = ..
 
+ASCIIDOC = osmosipconnector-usermanual.adoc
+ASCIIDOC_DEPS = chapters/*.adoc
+include $(TOPDIR)/build/Makefile.asciidoc.inc
+
 VTY_REFERENCE = osmosipconnector-vty-reference.xml
 include $(TOPDIR)/build/Makefile.vty-reference.inc
 
diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc
new file mode 100644
index 0000000..0a9a51f
--- /dev/null
+++ b/doc/manuals/chapters/configuration.adoc
@@ -0,0 +1,49 @@
+== Configuring OsmoSIPConnector
+
+The configuration of OsmoSIPConnector consists mainly of two parts:
+configuring the MNCC interface towards the MSC and configuring the SIP
+interface towards the PBX.
+
+=== Configuring MNCC
+
+Configuring the MNCC interface is very simple. It has to be pointed to
+the same path that OsmoMSC is also using. This means that OsmoMSC and
+OsmoSIPConnector need to be running on the same machine or have a shared
+directory that supports UNIX domain sockets.
+
+The example config below assumes that OsmoMSC was started with the command
+line `osmo-msc -M /tmp/msc_mncc`.
+
+.Example: MNCC configuration
+----
+OsmoMGW(config)# mncc
+OsmoMGW(config-mncc)# socket-path /tmp/msc_mncc
+----
+
+=== Configuring SIP
+
+This section covers the SIP configuration. Source and destination IP and port
+can be set for the connection to the PBX.
+
+.Example: SIP configuration
+----
+OsmoMGW(config)# sip 
+OsmoMGW(config-sip)# local 10.0.0.1 5060 <1>
+OsmoMGW(config-sip)# remote 10.0.0.2 5060 <2>
+----
+<1> The local IP/port to use
+<2> The remote SIP IP/port that the PBX uses
+
+There is also an option to use the IMSI as calling (source) address for
+MO- and as called (destination) address for MT-calls.
+
+.Example: Use IMSI instead of MSISDN
+----
+OsmoMGW(config)# app
+OsmoMGW(config-app)# use-imsi <1>
+----
+<1> Use the IMSI for MO calling and MT called address
+
+Since OsmoSIPConnector is just a shim between OsmoMSC and a proper SIP server
+this is the extent of the configuration. Setting up a dialplan and other
+SIP-related configuration should be done in the actual SIP server.
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
new file mode 100644
index 0000000..24fe8b9
--- /dev/null
+++ b/doc/manuals/chapters/overview.adoc
@@ -0,0 +1,48 @@
+[[overview]]
+== Overview
+
+This manual should help you getting started with OsmoSIPConnector. It will
+cover aspects of configuring and running OsmoSIPConnector.
+
+[[intro_overview]]
+=== About OsmoSIPConnector
+
+OsmoSIPConnector translates between Mobile Network Call Control (MNCC)
+used in the GSM newtwork and Voice over IP SIP call control messages so that
+speech calls can traverse through the mobile network to SIP and vice versa. It
+has the following interfaces:
+
+- MNCC UNIX domain socket towards `osmo-msc`
+- SIP towards the PBX
+- The Osmocom typical telnet VTY interface.
+
+Find the OsmoSIPConnector issue tracker and wiki online at
+
+- https://osmocom.org/projects/osmo-sip-connector
+- https://osmocom.org/projects/osmo-sip-connector/wiki
+
+
+[[fig-gsm]]
+.Typical GSM network architecture used with OsmoSIPConnector
+[graphviz]
+----
+digraph G{
+  rankdir = LR;
+  "osmo-sip-connector" [color="red"];
+  OsmoMGWB [label="OsmoMGW\n(BSC)"];
+  OsmoMGWM [label="OsmoMGW\n(MSC)"];
+  MS -> BTS [label = "Um"];
+  BTS -> OsmoBSC [label = "Abis"];
+  OsmoBSC -> OsmoMSC [label = "AoIP" ];
+  OsmoMSC -> "osmo-sip-connector" [label = "MNCC"];
+  "osmo-sip-connector" -> "PBX" [label = "SIP"];
+  BTS -> OsmoMGWB [label = "RTP"];
+  OsmoMGWB -> OsmoMGWM [label = "RTP"];
+  OsmoMGWM -> "PBX" [label = "RTP"];
+  OsmoBSC -> OsmoMGWB [label = "MGCP" ];
+  OsmoMSC -> OsmoMGWM [label = "MGCP" ];
+  { rank = same; OsmoBSC; OsmoMGWB; }
+  { rank = same; OsmoMSC; OsmoMGWM; }
+}
+----
+
diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
new file mode 100644
index 0000000..5e0d583
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -0,0 +1,58 @@
+== Running OsmoSIPConnectoer
+
+The OsmoSIPConnector executable (`osmo-sip-connector`) offers the following
+command-line arguments:
+
+=== SYNOPSIS
+
+*osmo-sip-connector* [-h] [-c 'CONFIGFILE']
+
+=== OPTIONS
+
+*-h, --help*::
+	Print a short help message about the supported options
+*-c, --config-file 'CONFIGFILE'*::
+	Specify the file and path name of the configuration file to be
+	used. If none is specified, use `osmo-sip-connector.cfg` in the
+	current working directory.
+
+=== Colocation with OsmoMSC
+
+Since the MNCC interface used to communicate between OsmoMSC and
+OsmoSIPConnector is a UNIX domain socket both processes must run on the same
+machine or have a shared directory that supports sharing UNIX domain sockets.
+
+=== Multiple instances
+
+Running multiple instances of `osmo-sip-connector` on the same computer is
+possible if all interfaces (VTY, CTRL) are separated using the appropriate
+configuration options. The IP based interfaces are binding to local host by
+default. In order to separate the processes, the user has to bind those
+services to specific but different IP addresses and/or ports.
+
+The VTY and the Control interface can be bound to IP addresses from the
+loopback address range, for example:
+
+----
+line vty
+ bind 127.0.0.2
+ctrl
+ bind 127.0.0.2
+----
+
+For the SIP client a different IP/port combination also needs to be used, for
+example:
+
+----
+sip
+ local 0.0.0.0 5061
+----
+
+The socket path for the MNCC interface also needs to change, which can be done
+with the following configuration snippet:
+
+----
+mncc
+ socket-path /tmp/msc2_mncc
+----
+
diff --git a/doc/manuals/osmosipconnector-usermanual-docinfo.xml b/doc/manuals/osmosipconnector-usermanual-docinfo.xml
new file mode 100644
index 0000000..937e054
--- /dev/null
+++ b/doc/manuals/osmosipconnector-usermanual-docinfo.xml
@@ -0,0 +1,46 @@
+<revhistory>
+  <revision>
+    <revnumber>1</revnumber>
+    <date>August 04th, 2018</date>
+    <authorinitials>DW</authorinitials>
+    <revremark>
+      Initial version
+    </revremark>
+  </revision>
+</revhistory>
+
+<authorgroup>
+  <author>
+    <firstname>Daniel</firstname>
+    <surname>Willmann</surname>
+    <email>dwillmann@sysmocom.de</email>
+    <authorinitials>DW</authorinitials>
+    <affiliation>
+      <shortaffil>sysmocom</shortaffil>
+      <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+    </affiliation>
+  </author>
+</authorgroup>
+
+<copyright>
+  <year>2018</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>
+  <para>
+	The Asciidoc source code of this manual can be found at
+	<ulink url="http://git.osmocom.org/osmo-gsm-manuals/">
+		http://git.osmocom.org/osmo-gsm-manuals/
+	</ulink>
+  </para>
+</legalnotice>
diff --git a/doc/manuals/osmosipconnector-usermanual.adoc b/doc/manuals/osmosipconnector-usermanual.adoc
new file mode 100644
index 0000000..72f6c1f
--- /dev/null
+++ b/doc/manuals/osmosipconnector-usermanual.adoc
@@ -0,0 +1,28 @@
+:gfdl-enabled:
+:program-name: OsmoSIPConnector
+
+OsmoSIPConnector User Manual
+============================
+Daniel Willmann <dwillmann@sysmocom.de>
+
+
+include::../common/chapters/preface.adoc[]
+
+include::chapters/overview.adoc[]
+
+include::chapters/running.adoc[]
+
+include::../common/chapters/vty.adoc[]
+
+include::../common/chapters/logging.adoc[]
+
+include::chapters/configuration.adoc[]
+
+include::../common/chapters/port_numbers.adoc[]
+
+include::../common/chapters/bibliography.adoc[]
+
+include::../common/chapters/glossary.adoc[]
+
+include::../common/chapters/gfdl.adoc[]
+