From a3a28acaa1759419cb6fee26909d65c733899aed Mon Sep 17 00:00:00 2001 From: Daniel Willmann Date: Thu, 23 Aug 2018 17:21:13 +0200 Subject: [PATCH] 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[] +