summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDaniel Willmann <daniel@totalueberwachung.de>2018-08-23 17:21:13 +0200
committerDaniel Willmann <daniel@totalueberwachung.de>2018-08-23 17:41:22 +0200
commitbf2a61aafad69273509ed43cee2410e5e30353f9 (patch)
tree5376647e4b75faa0fd3568681c150ab8aa644c54
parent078c7a4666030e20629c06c2e55480f289e757ee (diff)
Add manual for OsmoSIPConnector
Ticket: OS#1684 Change-Id: I70d3014deb459e0b91a9a92c60710b994153538e
-rw-r--r--OsmoSIPConnector/Makefile4
-rw-r--r--OsmoSIPConnector/chapters/configuration.adoc49
-rw-r--r--OsmoSIPConnector/chapters/overview.adoc48
-rw-r--r--OsmoSIPConnector/chapters/running.adoc58
-rw-r--r--OsmoSIPConnector/osmosipconnector-usermanual-docinfo.xml46
-rw-r--r--OsmoSIPConnector/osmosipconnector-usermanual.adoc28
6 files changed, 233 insertions, 0 deletions
diff --git a/OsmoSIPConnector/Makefile b/OsmoSIPConnector/Makefile
index 5a47759..cd3bb89 100644
--- a/OsmoSIPConnector/Makefile
+++ b/OsmoSIPConnector/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/OsmoSIPConnector/chapters/configuration.adoc b/OsmoSIPConnector/chapters/configuration.adoc
new file mode 100644
index 0000000..0a9a51f
--- /dev/null
+++ b/OsmoSIPConnector/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/OsmoSIPConnector/chapters/overview.adoc b/OsmoSIPConnector/chapters/overview.adoc
new file mode 100644
index 0000000..24fe8b9
--- /dev/null
+++ b/OsmoSIPConnector/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/OsmoSIPConnector/chapters/running.adoc b/OsmoSIPConnector/chapters/running.adoc
new file mode 100644
index 0000000..5e0d583
--- /dev/null
+++ b/OsmoSIPConnector/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/OsmoSIPConnector/osmosipconnector-usermanual-docinfo.xml b/OsmoSIPConnector/osmosipconnector-usermanual-docinfo.xml
new file mode 100644
index 0000000..937e054
--- /dev/null
+++ b/OsmoSIPConnector/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/OsmoSIPConnector/osmosipconnector-usermanual.adoc b/OsmoSIPConnector/osmosipconnector-usermanual.adoc
new file mode 100644
index 0000000..72f6c1f
--- /dev/null
+++ b/OsmoSIPConnector/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[]
+