Change in osmo-gsm-manuals[master]: Add initial OsmoMGW manual

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/.

daniel gerrit-no-reply at lists.osmocom.org
Tue Jul 31 16:53:19 UTC 2018 

daniel has uploaded this change for review. ( 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, 287 insertions(+), 0 deletions(-)



  git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/79/10279/1

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..4ac79f2
--- /dev/null
+++ b/OsmoMGW/chapters/overview.adoc
@@ -0,0 +1,105 @@
+[[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
+
+Although there is basic support for transcoding, please note that this feature
+is not currently being used in production/testing setups and may not work or
+work only partially.
+
+Support for transcoding needs to be enabled at compile-time which regular
+packages do not do.
+
+=== 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..c0178e2
--- /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: newchange
Gerrit-Change-Id: I1b4ff96309d280c6a63105a6e06a82ec2e7b6908
Gerrit-Change-Number: 10279
Gerrit-PatchSet: 1
Gerrit-Owner: daniel <dwillmann at sysmocom.de>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20180731/35674be6/attachment.htm>

More information about the gerrit-log mailing list