diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile new file mode 100644 index 000000000..b092e66ab --- /dev/null +++ b/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 diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc new file mode 100644 index 000000000..c398f25c8 --- /dev/null +++ b/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 + + diff --git a/doc/manuals/chapters/counters.adoc b/doc/manuals/chapters/counters.adoc new file mode 100644 index 000000000..7fbb10c6f --- /dev/null +++ b/doc/manuals/chapters/counters.adoc @@ -0,0 +1,4 @@ +[[counters]] +== Counters + +include::./counters_generated.adoc[] diff --git a/doc/manuals/chapters/counters_generated.adoc b/doc/manuals/chapters/counters_generated.adoc new file mode 100644 index 000000000..20a4dec8b --- /dev/null +++ b/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 diff --git a/doc/manuals/chapters/mgcp_extensions.adoc b/doc/manuals/chapters/mgcp_extensions.adoc new file mode 100644 index 000000000..86ff6433c --- /dev/null +++ b/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 +---- diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc new file mode 100644 index 000000000..6a8f3e38f --- /dev/null +++ b/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 diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc new file mode 100644 index 000000000..8565ea54d --- /dev/null +++ b/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 <> + for more information. diff --git a/doc/manuals/osmomgw-usermanual-docinfo.xml b/doc/manuals/osmomgw-usermanual-docinfo.xml new file mode 100644 index 000000000..d801c9b0a --- /dev/null +++ b/doc/manuals/osmomgw-usermanual-docinfo.xml @@ -0,0 +1,47 @@ + + + 1 + July 24th, 2018 + DW + + Initial version + + + + + + + Daniel + Willmann + dwillmann@sysmocom.de + DW + + sysmocom + sysmocom - s.f.m.c. GmbH + + + + + + 2018 + sysmocom - s.f.m.c. GmbH + + + + + 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". + + + The Asciidoc source code of this manual can be found at + + http://git.osmocom.org/osmo-gsm-manuals/ + + + + diff --git a/doc/manuals/osmomgw-usermanual.adoc b/doc/manuals/osmomgw-usermanual.adoc new file mode 100644 index 000000000..603002398 --- /dev/null +++ b/doc/manuals/osmomgw-usermanual.adoc @@ -0,0 +1,33 @@ +:gfdl-enabled: +:program-name: OsmoMGW + +OsmoMGW User Manual +==================== +Daniel Willmann + + +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[] + + diff --git a/doc/manuals/osmomgw-vty-reference.xml b/doc/manuals/osmomgw-vty-reference.xml new file mode 100644 index 000000000..2d915451d --- /dev/null +++ b/doc/manuals/osmomgw-vty-reference.xml @@ -0,0 +1,38 @@ + + + + +]> + + + + + + v1 + 12th December 2017 + pm + Initial + + + + OsmoMGW VTY Reference + + + 2017 + + + + This work is copyright by sysmocom - s.f.m.c. GmbH. All rights reserved. + + + + + + &chapter-vty; + + diff --git a/doc/manuals/vty/mgw_vty_additions.xml b/doc/manuals/vty/mgw_vty_additions.xml new file mode 100644 index 000000000..a4c675e8a --- /dev/null +++ b/doc/manuals/vty/mgw_vty_additions.xml @@ -0,0 +1,2 @@ + + diff --git a/doc/manuals/vty/mgw_vty_reference.xml b/doc/manuals/vty/mgw_vty_reference.xml new file mode 100644 index 000000000..834db040b --- /dev/null +++ b/doc/manuals/vty/mgw_vty_reference.xml @@ -0,0 +1,1645 @@ + + + Common Commands + These commands are available on all VTY nodes. They are listed here only once, to unclutter the VTY reference. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + view + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + enable + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-log + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-stats + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-line + + + + + + + + + + + + + + + + + + + + config-mgcp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-mgcp-trunk + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +