Merge history from osmo-gsm-manuals.git

Change-Id: Ia3eed1030966e0ed9f3e0bfdaa3939cfcec1f70a
This commit is contained in:
Neels Hofmeyr 2018-11-27 18:34:40 +01:00
commit 161695c389
9 changed files with 1441 additions and 0 deletions

10
doc/manuals/Makefile Normal file
View File

@ -0,0 +1,10 @@
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
include $(TOPDIR)/build/Makefile.common.inc

View File

@ -0,0 +1,53 @@
== 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.
Note that you need to start `osmo-msc` with the `--mncc-sock` option and point
to the same file that osmo-sip-connector is configured to use. See the OsmoMSC
manual for more information.
The example config below assumes that OsmoMSC was started with the command
line `osmo-msc -M /tmp/msc_mncc`.
.Example: MNCC configuration
----
OsmoSIPcon(config)# mncc
OsmoSIPcon(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
----
OsmoSIPcon(config)# sip
OsmoSIPcon(config-sip)# local 10.0.0.1 5060 <1>
OsmoSIPcon(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
----
OsmoSIPcon(config)# app
OsmoSIPcon(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,84 @@
== 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
----
=== DTMF signaling
In VoIP based telephony networks DTMF (Dual-tone multi-frequency signaling) can
be signaled through multiple methods. Common methods are in-band, RFC2833 and
sip-info messages.
Osmo-sip-connector is using sip-info messages to signal DTMF tones. When a DTMF
tone is signaled at the MNCC socket interface, osmo-sip-connector will generate
a matching sip-info message to forward the DTMF signal to the PBX. Depending on
the PBX software reconfiguring the DTMF signaling method to sip-info may be
necessary.
While sending DTMF tones through the MNCC interface to a SIP leg, the current
implementation of osmo-sip-connector does not support sending DTMF tones in the
opposite direction. Any attempts to send DTMF tones to an MNCC leg will be
confirmed with a status 405 "Method not allowed".
The reason for this limitation is that in mobile networks, depending on the
signaling direction, the signaling of DTMF tones is implemented differently.
A mobile originated DTMF tone is signaled through out of band messages,
which arrive at osmo-sip-connector on as MNCC DTMF START/STOP messages. Those
messages can be directly translated to sip-info messages. However, in the
other direction (mobile terminated), an in-band signaling method is used. This
means that osmo-sip-connector would have to translate an incoming DTMF sip-info
message into an audio sample that then would have to be injected into the
voice stream. Currently this scheme is not implemented in osmo-sip-connector.

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

View File

@ -0,0 +1,38 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
ex:ts=2:sw=42sts=2:et
-*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML 5.0//EN"
"http://docbook.org/xml/5.0/dtd/docbook.dtd" [
<!ENTITY chapter-vty SYSTEM "../common/chapters/vty.xml" >
<!ENTITY sections-vty SYSTEM "generated/docbook_vty.xml" >
]>
<book>
<info>
<revhistory>
<revision>
<revnumber>v1</revnumber>
<date>21st August 2018</date>
<authorinitials>dw</authorinitials>
<revremark>Initial</revremark>
</revision>
</revhistory>
<title>OsmoSIPConnector VTY Reference</title>
<copyright>
<year>2018</year>
</copyright>
<legalnotice>
<para>This work is copyright by <orgname>sysmocom - s.f.m.c. GmbH</orgname>. All rights reserved.
</para>
</legalnotice>
</info>
<!-- Main chapters-->
&chapter-vty;
</book>

View File

@ -0,0 +1,2 @@
<vtydoc xmlns='urn:osmocom:xml:libosmocore:vty:doc:1.0'>
</vtydoc>

File diff suppressed because it is too large Load Diff