Merge history from osmo-gsm-manuals.git

Change-Id: Ibbc4f41f7672159d8596ceb84b60e5c849b98074

doc/manuals/Makefile

@@ -0,0 +1,10 @@
+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
+
+include $(TOPDIR)/build/Makefile.common.inc

doc/manuals/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
+
+

doc/manuals/chapters/counters.adoc

@@ -0,0 +1,4 @@
+[[counters]]
+== Counters
+
+include::./counters_generated.adoc[]

doc/manuals/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

doc/manuals/chapters/mgcp_extensions.adoc

@@ -0,0 +1,68 @@
+== MGCP Extensions
+
+The MGCP protocol is extendable. The following non-standard extensions are
+understood by OsmoMGW.
+
+=== `X-Osmo-IGN`
+
+`X-Osmo-IGN` indicates to OsmoMGW that specific items of an endpoint should be
+ignored, so that it is lenient on mismatching values that would normally
+indicate collisions or configuration errors.
+
+==== `X-Osmo-IGN` Format
+
+The value part of X-Osmo-IGN must be one or more items separated by one or more
+spaces. Each item consists of one or more non-whitespace characters.
+
+.Example: `X-Osmo-IGN` format with three ficticious items "X", "abc" and "123".
+----
+X-Osmo-IGN: X abc 123
+----
+
+`X-Osmo-IGN` must be issued in the MGCP section (typically as its last item),
+before the SDP section starts.
+
+==== Supported `X-Osmo-IGN` Items
+
+Currently, the following `X-Osmo-IGN` items are supported:
+
+* `C`: ignore CallID mismatches, i.e. differing "C" values between connections
+  on the same endpoint.
+
+.Note:
+`X-Osmo-IGN` does not support ignoring mismatches on the domain part of
+an endpoint name, e.g. ignoring a mismatch on "example.com" in
+`rtpbridge/123abc@example.com`. Instead, you may globally configure OsmoMGW
+with `mgcp` / `domain *` to permit all domain parts.
+
+===== `X-Osmo-IGN: C`
+
+By default, OsmoMGW verifies that all CallIDs ("C" values) match for all
+connections on any one given endpoint. To ignore CallID mismatches, pass a `C`
+in the `X-Osmo-IGN` header, for the first or the second `CRCX` on an endpoint.
+When the `X-Osmo-IGN: C` is sent for any one `CRCX` on an endpoint, CallID
+mismatches will be ignored for that and all subsequent messages for that
+endpoint. Hence this header only needs to be included once per endpoint, in any
+`CRCX` message that precedes or coincides with a CallID mismatch.
+
+This is particularly useful for a BSC that is connected to an A/SCCPlite MSC,
+where the BSC and MSC each are expected to configure their respective own
+connection on a shared endpoint. For A/SCCPlite, it is impossible for the BSC
+to know the CallID that the MSC will use, so CallID mismatches are inevitable.
+See also OsmoBSC, which will by default pass the `X-Osmo-IGN: C` header for
+endpoints associated with an A/SCCPlite MSC.
+
+.Example: `CRCX` message that instructs OsmoMGW to ignore CallID mismatches
+----
+CRCX 2 rtpbridge/123abc@mgw MGCP 1.0
+M: recvonly
+C: 2
+L: p:20
+X-Osmo-IGN: C
+
+v=0
+c=IN IP4 123.12.12.123
+m=audio 5904 RTP/AVP 97
+a=rtpmap:97 GSM-EFR/8000
+a=ptime:40
+----

doc/manuals/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

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

doc/manuals/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>
+

doc/manuals/osmomgw-usermanual.adoc

@@ -0,0 +1,33 @@
+: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/mgcp_extensions.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[]
+
+

doc/manuals/osmomgw-vty-reference.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ex:ts=2:sw=42sts=2:et
+  -*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
+-->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML 5.0//EN"
+"http://docbook.org/xml/5.0/dtd/docbook.dtd" [
+<!ENTITY chapter-vty      SYSTEM      "../common/chapters/vty.xml" >
+<!ENTITY sections-vty     SYSTEM      "generated/docbook_vty.xml"  >
+]>
+
+<book>
+  <info>
+    <revhistory>
+        <revision>
+            <revnumber>v1</revnumber>
+            <date>12th December 2017</date>
+            <authorinitials>pm</authorinitials>
+            <revremark>Initial</revremark>
+        </revision>
+    </revhistory>
+
+    <title>OsmoMGW VTY Reference</title>
+
+    <copyright>
+      <year>2017</year>
+    </copyright>
+
+    <legalnotice>
+      <para>This work is copyright by <orgname>sysmocom - s.f.m.c. GmbH</orgname>. All rights reserved.
+      </para>
+    </legalnotice>
+  </info>
+
+  <!-- Main chapters-->
+  &chapter-vty;
+</book>
+

doc/manuals/vty/mgw_vty_additions.xml

@@ -0,0 +1,2 @@
+<vtydoc xmlns='urn:osmocom:xml:libosmocore:vty:doc:1.0'>
+</vtydoc>