This is merely a historical archive of years 2008-2021, before the migration to mailman3.
A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.
osmith gerrit-no-reply at lists.osmocom.orgosmith has uploaded this change for review. ( https://gerrit.osmocom.org/12068 Change subject: Add manual for OsmoSIPConnector ...................................................................... Add manual for OsmoSIPConnector Ticket: OS#1684 Change-Id: I70d3014deb459e0b91a9a92c60710b994153538e --- M doc/manuals/Makefile A doc/manuals/chapters/configuration.adoc A doc/manuals/chapters/overview.adoc A doc/manuals/chapters/running.adoc A doc/manuals/osmosipconnector-usermanual-docinfo.xml A doc/manuals/osmosipconnector-usermanual.adoc 6 files changed, 233 insertions(+), 0 deletions(-) git pull ssh://gerrit.osmocom.org:29418/osmo-sip-connector refs/changes/68/12068/1 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 @@ +<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 at 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> 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 <dwillmann at 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[] + -- To view, visit https://gerrit.osmocom.org/12068 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-sip-connector Gerrit-Branch: master Gerrit-MessageType: newchange Gerrit-Change-Id: I70d3014deb459e0b91a9a92c60710b994153538e Gerrit-Change-Number: 12068 Gerrit-PatchSet: 1 Gerrit-Owner: osmith <osmith at sysmocom.de> Gerrit-Reviewer: daniel <dwillmann at sysmocom.de> -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20181203/ab3ba5a9/attachment.htm>