Merge history from osmo-gsm-manuals.git
Change-Id: Ia3eed1030966e0ed9f3e0bfdaa3939cfcec1f70a
This commit is contained in:
commit
161695c389
|
@ -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
|
|
@ -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.
|
|
@ -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; }
|
||||||
|
}
|
||||||
|
----
|
||||||
|
|
|
@ -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.
|
|
@ -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>
|
|
@ -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[]
|
||||||
|
|
|
@ -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>
|
||||||
|
|
|
@ -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
Loading…
Reference in New Issue