paulmataruso/osmo-mgw
1
0
Fork 0
mirror of https://gitea.osmocom.org/cellular-infrastructure/osmo-mgw.git synced 2025-11-03 21:43:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge history from osmo-gsm-manuals.git

Browse Source 
Change-Id: Ibbc4f41f7672159d8596ceb84b60e5c849b98074
This commit is contained in:
Neels Hofmeyr
2018-11-27 18:07:16 +01:00
parent 8ab3fbbaf2 c0a2196f91
commit ca6a8495e1
12 changed files with 2043 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
doc/manuals/Makefile Normal file
View File

@@ -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

57
doc/manuals/chapters/configuration.adoc Normal file
View File

@@ -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

4
doc/manuals/chapters/counters.adoc Normal file
View File

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

14
doc/manuals/chapters/counters_generated.adoc Normal file
View File

@@ -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

68
doc/manuals/chapters/mgcp_extensions.adoc Normal file
View File

@@ -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
----

100
doc/manuals/chapters/overview.adoc Normal file
View File

@@ -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

25
doc/manuals/chapters/running.adoc Normal file
View File

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

47
doc/manuals/osmomgw-usermanual-docinfo.xml Normal file
View File

@@ -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>

33
doc/manuals/osmomgw-usermanual.adoc Normal file
View File

@@ -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[]

38
doc/manuals/osmomgw-vty-reference.xml Normal file
View File

@@ -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>

2
doc/manuals/vty/mgw_vty_additions.xml Normal file
View File

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

1645
doc/manuals/vty/mgw_vty_reference.xml Normal file
View File

File diff suppressed because it is too large Load Diff