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/.
Harald Welte gerrit-no-reply at lists.osmocom.orgHarald Welte has submitted this change and it was merged. ( https://gerrit.osmocom.org/10279 ) Change subject: Add initial OsmoMGW manual ...................................................................... Add initial OsmoMGW manual Change-Id: I1b4ff96309d280c6a63105a6e06a82ec2e7b6908 --- M OsmoMGW/Makefile A OsmoMGW/chapters/configuration.adoc A OsmoMGW/chapters/counters.adoc A OsmoMGW/chapters/counters_generated.adoc A OsmoMGW/chapters/overview.adoc A OsmoMGW/chapters/running.adoc A OsmoMGW/osmomgw-usermanual-docinfo.xml A OsmoMGW/osmomgw-usermanual.adoc 8 files changed, 282 insertions(+), 0 deletions(-) Approvals: Jenkins Builder: Verified Harald Welte: Looks good to me, approved diff --git a/OsmoMGW/Makefile b/OsmoMGW/Makefile index 46c97e4..b092e66 100644 --- a/OsmoMGW/Makefile +++ b/OsmoMGW/Makefile @@ -1,5 +1,9 @@ TOPDIR = .. +ASCIIDOC = osmomgw-usermanual.adoc +ASCIIDOC_DEPS = chapters/*.adoc +include $(TOPDIR)/build/Makefile.asciidoc.inc + VTY_REFERENCE = osmomgw-vty-reference.xml include $(TOPDIR)/build/Makefile.vty-reference.inc diff --git a/OsmoMGW/chapters/configuration.adoc b/OsmoMGW/chapters/configuration.adoc new file mode 100644 index 0000000..c398f25 --- /dev/null +++ b/OsmoMGW/chapters/configuration.adoc @@ -0,0 +1,57 @@ +== Configuring OsmoMGW + +A basic configation of OsmoMGW mainly consists of specifying the IP address +and port on which to listen to MGCP commands, but changing the port range at +which the RTP streams terminate as well as limiting operation to a single call +agent can be done as well as changing the number of endpoints. + +=== Configuring MGCP + +By default OsmoMGW listens for MGCP on port 2427 on any IP address. If a call +agent address is configured then OsmoMGW will only answer MGCP commands from +that IP port 2727, otherwise all sources are handled. A domain can be +specified + +.Example: MGCP configuration +---- +OsmoMGW(config-mgcp)# bind ip 127.0.0.1 +OsmoMGW(config-mgcp)# bind port 2427 +OsmoMGW(config-mgcp)# call-agent ip 127.0.0.1 +OsmoMGW(config-mgcp)# domain mgw-bsc +OsmoMGW(config-mgcp)# local ip 127.0.0.1 +---- + +=== Configuring the trunk + +The first trunk (trunk 0) is considered a virtual trunk in OsmoMGW. All +endpoints of type "rtpbridge" are routed here. The virtual trunk is configured +in the config-mgcp context. + +All other trunks are configured in the config-mgcp-trunk context, but the +commands used are identical. Right now trunks are considered only for ds/e1 +type endpoints which are not yet implemented. Don't use trunks other than the +"virtual" trunk 0. + +.Example: MGCP trunk configuration +---- +OsmoMGW(config-mgcp)# number endpoints 63 <1> +OsmoMGW(config-mgcp)# rtp bind-ip 10.0.0.1 <2> +OsmoMGW(config-mgcp)# rtp port-range 12000-14000 <3> +---- +<1> Maximum number of endpoints that can be allocated at once +<2> Use this IP when binding RTP endpoints +<3> Use ports in this range when binding RTP endpoints + +There are some options to tweak how RTP forwarding behaves in OsmoMGW: + +.Example: MGCP trunk rtp options +---- +OsmoMGW(config-mgcp)# rtp keep-alive 30 <1> +OsmoMGW(config-mgcp)# rtp-patch ssrc <2> +OsmoMGW(config-mgcp)# rtp-patch timestamp <3> +---- +<1> Send dummy UDP packets periodically to RTP destination +<2> Hide SSRC changes +<3> Ensure RTP timestamp is aligned with frame duration + + diff --git a/OsmoMGW/chapters/counters.adoc b/OsmoMGW/chapters/counters.adoc new file mode 100644 index 0000000..7fbb10c --- /dev/null +++ b/OsmoMGW/chapters/counters.adoc @@ -0,0 +1,4 @@ +[[counters]] +== Counters + +include::./counters_generated.adoc[] diff --git a/OsmoMGW/chapters/counters_generated.adoc b/OsmoMGW/chapters/counters_generated.adoc new file mode 100644 index 0000000..20a4dec --- /dev/null +++ b/OsmoMGW/chapters/counters_generated.adoc @@ -0,0 +1,14 @@ + +// autogenerated by show asciidoc counters +These counters and their description based on OsmoMGW 1.3.0.34-9cd52 (OsmoMGW). + +=== Rate Counters + +// generating tables for rate_ctr_group +== Osmo Stat Items + +// generating tables for osmo_stat_items +== Osmo Counters + +// generating tables for osmo_counters +// there are no ungrouped osmo_counters diff --git a/OsmoMGW/chapters/overview.adoc b/OsmoMGW/chapters/overview.adoc new file mode 100644 index 0000000..6a8f3e3 --- /dev/null +++ b/OsmoMGW/chapters/overview.adoc @@ -0,0 +1,100 @@ +[[overview]] +== Overview + +This manual should help you getting started with OsmoMGW. It will cover +aspects of configuring and running the media gateway. + +[[intro_overview]] +=== About OsmoMGW + +OsmoMGW is the Osmocom implementation of a media gateway to handle user +plane (voice) traffic in cellular networks. It can connect and optionally +transcode RTP voice streams between different network elements such as BTSs +and external entities like SIP. It is typically co-located with both OsmoBSC +and OsmoMSC and controlled by them via MGCP, the Media Gateway Control +Protocol. + +[[fig-bsc]] +.OsmoMGW used with OsmoBSC +[graphviz] +---- +digraph G { + rankdir = LR; + OsmoBTS -> OsmoBSC [label="Abis/IP"]; + OsmoBSC -> OsmoMSC [label="3GPP AoIP"]; + OsmoBSC -> OsmoMGW [label="MGCP"]; + OsmoBTS -> OsmoMGW [label="RTP",dir=both]; + OsmoMGW -> OsmoMSC [label="RTP",dir=both]; + {rank=same OsmoBSC OsmoMGW} + OsmoMGW [color=red]; +} +---- + +[[fig-msc]] +.OsmoMGW used with OsmoMSC +[graphviz] +---- +digraph G { + rankdir = LR; + BTS -> BSC [label="Abis"]; + BSC -> OsmoMSC [label="3GPP AoIP"]; + OsmoMSC -> OsmoMGW [label="MGCP"]; + BSC -> OsmoMGW [label="RTP",dir=both]; + OsmoMSC -> OsmoSIP [label="MNCC"]; + OsmoSIP -> PBX [label="SIP Trunk"]; + OsmoMGW -> PBX [label="RTP",dir=both]; + {rank=same OsmoMSC OsmoMGW} + OsmoSIP [label="osmo-sip-connector"]; + OsmoMGW [color=red]; + + hNodeB -> OsmoHNBGW [label="Iuh"]; + OsmoHNBGW -> OsmoMSC [label="IuCS"]; + hNodeB -> OsmoMGW [label="RTP",dir=both]; +} +---- + +=== Software Components + +OsmoMGW contains a variety of different software components, which we’ll +quickly describe in this section. + +==== MGCP Implementation + +OsmoMGW brings its own MGCP implementation through which OsmoMGW is +controlled. + +The commands implemented are CRCX, MDCX, DLCX and RSIP. The command AUEP is +implemented as a stub and will simply respond with OK. + +==== RTP implementation + +Support for IuUP which is used in 3G cells is quite lacking at the moment. +3G<->3G and 2G<->2G calls should work, but 3G<->2G does not. + +==== Audio transcoder + +Transcoding is currently not supported in OsmoMGW. + +=== Limitations + +Osmux is not yet supported in OsmoMGW. + +At the moment (July 2018), OsmoMGW only implements RTP proxy / RTP bridge +type endpoints, to each of which two RTP connections can be established. +We are planning to add endpoint types for: + +- classic E1/T1 timeslots (64kBps alaw/ulaw) +- classic E1/T1 16k sub-slots with TRAU frames for classic BTS support +- announcement/playout end-points +- conference endpoints + +=== Additional resources + +You can find the OsmoMGW issue tracker and wiki online at + +- https://osmocom.org/projects/osmomgw +- https://osmocom.org/projects/osmomgw/wiki + +RFC 3435 for MGCP is located at + +- https://tools.ietf.org/html/rfc3435 diff --git a/OsmoMGW/chapters/running.adoc b/OsmoMGW/chapters/running.adoc new file mode 100644 index 0000000..8565ea5 --- /dev/null +++ b/OsmoMGW/chapters/running.adoc @@ -0,0 +1,25 @@ +== Running OsmoMGW + +The OsmoMGW executable (`osmo-mgw`) offers the following command-line +arguments: + +=== SYNOPSIS + +*osmo-mgw* [-h|-V] [-D] [-c 'CONFIGFILE'] [-s] + +=== OPTIONS + +*-h, --help*:: + Print a short help message about the supported options +*-V, --version*:: + Print the compile-time version number of the OsmoBTS program +*-D, --daemonize*:: + Fork the process as a daemon into background. +*-c, --config-file 'CONFIGFILE'*:: + Specify the file and path name of the configuration file to be + used. If none is specified, use `osmo-mgw.cfg` in the current + working directory. +*-s, --disable-color*:: + Disable colors for logging to stderr. This has mostly been + deprecated by VTY based logging configuration, see <<logging>> + for more information. diff --git a/OsmoMGW/osmomgw-usermanual-docinfo.xml b/OsmoMGW/osmomgw-usermanual-docinfo.xml new file mode 100644 index 0000000..d801c9b --- /dev/null +++ b/OsmoMGW/osmomgw-usermanual-docinfo.xml @@ -0,0 +1,47 @@ +<revhistory> + <revision> + <revnumber>1</revnumber> + <date>July 24th, 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/OsmoMGW/osmomgw-usermanual.adoc b/OsmoMGW/osmomgw-usermanual.adoc new file mode 100644 index 0000000..69dc005 --- /dev/null +++ b/OsmoMGW/osmomgw-usermanual.adoc @@ -0,0 +1,31 @@ +:gfdl-enabled: +:program-name: OsmoMGW + +OsmoMGW 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::chapters/counters.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/10279 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-gsm-manuals Gerrit-Branch: master Gerrit-MessageType: merged Gerrit-Change-Id: I1b4ff96309d280c6a63105a6e06a82ec2e7b6908 Gerrit-Change-Number: 10279 Gerrit-PatchSet: 4 Gerrit-Owner: daniel <dwillmann at sysmocom.de> Gerrit-Reviewer: Harald Welte <laforge at gnumonks.org> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: daniel <dwillmann at sysmocom.de> -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20180807/4d8c4487/attachment.htm>