summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDaniel Willmann <dwillmann@sysmocom.de>2018-07-31 18:53:45 +0200
committerDaniel Willmann <daniel@totalueberwachung.de>2018-08-07 18:57:53 +0200
commit0c1dad4a5bdb7528f066502b801bb6e31b190a58 (patch)
tree433de6485d5bff5213a69d637f5867e3ccb4dbac
parentfa787b2e3054c4be3af6850a32f21410d3c86230 (diff)
Add initial OsmoMGW manual
-rw-r--r--OsmoMGW/Makefile4
-rw-r--r--OsmoMGW/chapters/configuration.adoc57
-rw-r--r--OsmoMGW/chapters/counters.adoc4
-rw-r--r--OsmoMGW/chapters/counters_generated.adoc14
-rw-r--r--OsmoMGW/chapters/overview.adoc100
-rw-r--r--OsmoMGW/chapters/running.adoc25
-rw-r--r--OsmoMGW/osmomgw-usermanual-docinfo.xml47
-rw-r--r--OsmoMGW/osmomgw-usermanual.adoc31
8 files changed, 282 insertions, 0 deletions
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@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@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[]
+
+