Add manual for OsmoSIPConnector

Ticket: OS#1684
Change-Id: I70d3014deb459e0b91a9a92c60710b994153538e
This commit is contained in:
Daniel Willmann 2018-08-23 17:21:13 +02:00 committed by Neels Hofmeyr
parent b79fde2dc1
commit a3a28acaa1
6 changed files with 233 additions and 0 deletions

View File

@ -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

View File

@ -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.

View File

@ -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; }
}
----

View File

@ -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
----

View File

@ -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>

View File

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