From b79fde2dc13ee0e4edbc0c52cee463255989752d Mon Sep 17 00:00:00 2001 From: Daniel Willmann Date: Thu, 23 Aug 2018 15:35:22 +0200 Subject: [PATCH 2/7] Add VTY reference for osmo-sip-connector Ticket: OS#1684 Change-Id: I1045c20dd7234d425836ba93fa292a35ccddc7fd --- doc/manuals/Makefile | 6 + .../osmosipconnector-vty-reference.xml | 38 + doc/manuals/vty/sipconn_vty_additions.xml | 2 + doc/manuals/vty/sipconn_vty_reference.xml | 1040 +++++++++++++++++ 4 files changed, 1086 insertions(+) create mode 100644 doc/manuals/Makefile create mode 100644 doc/manuals/osmosipconnector-vty-reference.xml create mode 100644 doc/manuals/vty/sipconn_vty_additions.xml create mode 100644 doc/manuals/vty/sipconn_vty_reference.xml diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile new file mode 100644 index 0000000..5a47759 --- /dev/null +++ b/doc/manuals/Makefile @@ -0,0 +1,6 @@ +TOPDIR = .. + +VTY_REFERENCE = osmosipconnector-vty-reference.xml +include $(TOPDIR)/build/Makefile.vty-reference.inc + +include $(TOPDIR)/build/Makefile.common.inc diff --git a/doc/manuals/osmosipconnector-vty-reference.xml b/doc/manuals/osmosipconnector-vty-reference.xml new file mode 100644 index 0000000..fe22a99 --- /dev/null +++ b/doc/manuals/osmosipconnector-vty-reference.xml @@ -0,0 +1,38 @@ + + + + +]> + + + + + + v1 + 21st August 2018 + dw + Initial + + + + OsmoSIPConnector VTY Reference + + + 2018 + + + + This work is copyright by sysmocom - s.f.m.c. GmbH. All rights reserved. + + + + + + &chapter-vty; + + diff --git a/doc/manuals/vty/sipconn_vty_additions.xml b/doc/manuals/vty/sipconn_vty_additions.xml new file mode 100644 index 0000000..a4c675e --- /dev/null +++ b/doc/manuals/vty/sipconn_vty_additions.xml @@ -0,0 +1,2 @@ + + diff --git a/doc/manuals/vty/sipconn_vty_reference.xml b/doc/manuals/vty/sipconn_vty_reference.xml new file mode 100644 index 0000000..35aad6b --- /dev/null +++ b/doc/manuals/vty/sipconn_vty_reference.xml @@ -0,0 +1,1040 @@ + + + Common Commands + These commands are available on all VTY nodes. They are listed here only once, to unclutter the VTY reference. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + view + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + enable + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-log + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-stats + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-line + + + + + + + + + + + + + + + + + + + + config-sip + + + + + + + + + + + + + + + + + + + + + + + + config-mncc + + + + + + + + + config-app + + + + + + + + + + + + + From a3a28acaa1759419cb6fee26909d65c733899aed Mon Sep 17 00:00:00 2001 From: Daniel Willmann Date: Thu, 23 Aug 2018 17:21:13 +0200 Subject: [PATCH 3/7] Add manual for OsmoSIPConnector Ticket: OS#1684 Change-Id: I70d3014deb459e0b91a9a92c60710b994153538e --- doc/manuals/Makefile | 4 ++ doc/manuals/chapters/configuration.adoc | 49 ++++++++++++++++ doc/manuals/chapters/overview.adoc | 48 +++++++++++++++ doc/manuals/chapters/running.adoc | 58 +++++++++++++++++++ .../osmosipconnector-usermanual-docinfo.xml | 46 +++++++++++++++ doc/manuals/osmosipconnector-usermanual.adoc | 28 +++++++++ 6 files changed, 233 insertions(+) create mode 100644 doc/manuals/chapters/configuration.adoc create mode 100644 doc/manuals/chapters/overview.adoc create mode 100644 doc/manuals/chapters/running.adoc create mode 100644 doc/manuals/osmosipconnector-usermanual-docinfo.xml create mode 100644 doc/manuals/osmosipconnector-usermanual.adoc 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 @@ + + + 1 + August 04th, 2018 + DW + + Initial version + + + + + + + Daniel + Willmann + dwillmann@sysmocom.de + DW + + sysmocom + sysmocom - s.f.m.c. GmbH + + + + + + 2018 + sysmocom - s.f.m.c. GmbH + + + + + 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". + + + The Asciidoc source code of this manual can be found at + + http://git.osmocom.org/osmo-gsm-manuals/ + + + 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 + + +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[] + From 2e331aed4ecb405e273563ad2f7e66c2ba4493e8 Mon Sep 17 00:00:00 2001 From: Vadim Yanitskiy Date: Thu, 30 Aug 2018 01:35:44 +0700 Subject: [PATCH 4/7] OsmoSIPConnector: fix: avoid OsmoMGW/OsmoSIPcon confusion Change-Id: If20700d94775e91f174a1a07e00820ef0a91cd2f --- doc/manuals/chapters/configuration.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc index 0a9a51f..24ac3a5 100644 --- a/doc/manuals/chapters/configuration.adoc +++ b/doc/manuals/chapters/configuration.adoc @@ -16,8 +16,8 @@ line `osmo-msc -M /tmp/msc_mncc`. .Example: MNCC configuration ---- -OsmoMGW(config)# mncc -OsmoMGW(config-mncc)# socket-path /tmp/msc_mncc +OsmoSIPcon(config)# mncc +OsmoSIPcon(config-mncc)# socket-path /tmp/msc_mncc ---- === Configuring SIP @@ -27,9 +27,9 @@ 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> +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 @@ -39,8 +39,8 @@ MO- and as called (destination) address for MT-calls. .Example: Use IMSI instead of MSISDN ---- -OsmoMGW(config)# app -OsmoMGW(config-app)# use-imsi <1> +OsmoSIPcon(config)# app +OsmoSIPcon(config-app)# use-imsi <1> ---- <1> Use the IMSI for MO calling and MT called address From a001c591b36f882ae3b63020a57ce22f129cf4c0 Mon Sep 17 00:00:00 2001 From: Daniel Willmann Date: Thu, 23 Aug 2018 17:48:02 +0200 Subject: [PATCH 5/7] osmo-sip-connector: Explicitly note OsmoMSC config with external MNCC Change-Id: Ia186ea48b1012e65dc6446c839fdb548d44b6a6c --- doc/manuals/chapters/configuration.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc index 24ac3a5..5cd57fa 100644 --- a/doc/manuals/chapters/configuration.adoc +++ b/doc/manuals/chapters/configuration.adoc @@ -11,6 +11,10 @@ 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`. From 3130f0776a1a0082292eb2007702be7550e03525 Mon Sep 17 00:00:00 2001 From: Philipp Maier Date: Mon, 1 Oct 2018 12:56:23 +0200 Subject: [PATCH 6/7] running: Add note about DTMF support osmo-sip-connector does not yet support full DTMF support. The current implementation only supports DTMF tones to be send from MNCC to SIP, but not in the opposite direction. Change-Id: I578e50b0a42d88b05cf6da80443b71494b5eb26f Related: OS#2777 --- doc/manuals/chapters/running.adoc | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc index 5e0d583..85ccddc 100644 --- a/doc/manuals/chapters/running.adoc +++ b/doc/manuals/chapters/running.adoc @@ -56,3 +56,29 @@ 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. \ No newline at end of file From 1b26e8e61e5bff10f1ff80a541709f406ffc3649 Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Mon, 5 Nov 2018 03:19:46 +0100 Subject: [PATCH 7/7] sip-connector: update vty reference Change-Id: I79b91847337b6022f8f750533301b3bf0eb086df --- doc/manuals/vty/sipconn_vty_reference.xml | 120 +++++++++++++++++++--- 1 file changed, 106 insertions(+), 14 deletions(-) diff --git a/doc/manuals/vty/sipconn_vty_reference.xml b/doc/manuals/vty/sipconn_vty_reference.xml index 35aad6b..dee42e6 100644 --- a/doc/manuals/vty/sipconn_vty_reference.xml +++ b/doc/manuals/vty/sipconn_vty_reference.xml @@ -188,7 +188,7 @@ - + @@ -196,6 +196,7 @@ + @@ -205,11 +206,10 @@ - + - @@ -232,7 +232,6 @@ - @@ -240,6 +239,38 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -308,8 +339,7 @@ - - + @@ -451,7 +481,7 @@ - + @@ -459,6 +489,7 @@ + @@ -468,11 +499,10 @@ - + - @@ -495,7 +525,6 @@ - @@ -503,6 +532,38 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -855,7 +916,7 @@ - + @@ -863,13 +924,13 @@ + - + - @@ -892,7 +953,6 @@ - @@ -900,6 +960,38 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-stats