Change in ...osmo-gsm-manuals[master]: common: Introduce Osmux documentation

laforge gerrit-no-reply at lists.osmocom.org
Mon Jul 22 19:48:46 UTC 2019


laforge has submitted this change and it was merged. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/14839 )

Change subject: common: Introduce Osmux documentation
......................................................................

common: Introduce Osmux documentation

Change-Id: I182d94c63f7d74ef882b77be59a95b1b7d8a4e5e
---
A common/chapters/osmux/mgcp_extension_osmux.adoc
A common/chapters/osmux/mo_call_osmux_aoip.msc
A common/chapters/osmux/mo_call_osmux_sccplite.msc
A common/chapters/osmux/mo_call_osmux_sccplite_nat.msc
A common/chapters/osmux/network_osmux_aoip.dot
A common/chapters/osmux/network_osmux_sccplite.dot
A common/chapters/osmux/network_osmux_sccplite_nat.dot
A common/chapters/osmux/osmux.adoc
8 files changed, 550 insertions(+), 0 deletions(-)

Approvals:
  Jenkins Builder: Verified
  laforge: Looks good to me, approved



diff --git a/common/chapters/osmux/mgcp_extension_osmux.adoc b/common/chapters/osmux/mgcp_extension_osmux.adoc
new file mode 100644
index 0000000..c12e9ef
--- /dev/null
+++ b/common/chapters/osmux/mgcp_extension_osmux.adoc
@@ -0,0 +1,115 @@
+[[mgcp-extension-osmux]]
+=== Osmux and MGCP
+
+`X-Osmux` indicates to OsmoMGW that a given connection of an `rtpbridge`
+endpoint has to be configured in order to handle Osmux frames instead of RTP
+messages on the data plane.
+
+==== `X-Osmux` Format
+
+The value part of `X-Osmux` must be one integer in range [0..255], or
+alternatively only on request messages, an asterisk (*) if the value is not yet
+known.
+
+`X-Osmux` must be issued in the MGCP header section (typically as its last
+item), before the SDP section starts.
+
+`X-Osmux` can be included inside `CRCX` and `MDCX` request messages, as well as
+their respective response messages.
+
+In request messages, the value part of `X-Osmux` specifies the CID to be used by
+OsmoMGW to _send_ Osmux frames to the remote peer for that connection, also
+known as _sendCID_.
+
+In response messages, the value part of `X-Osmux` specifies the CID where
+OsmoMGW expect to _receive_ Osmux frames from the remote peer for that
+connection, also known as _recvCID_.
+
+.Example: `X-Osmux` format with a known CID 3.
+----
+X-Osmux: 3
+----
+
+.Example: `X-Osmux` format with a wildcard (not yet known) CID.
+----
+X-Osmux: *
+----
+
+==== `X-Osmux` Considerations
+
+If the MGCP client is willing to use Osmux for a given connection, it shall
+specify so during `CRCX` time, and not later. If at `CRCX` time the MGCP client
+doesn't yet know the _sendCID_, it can use an astersik (*) and provide
+_sendCID_ later within `MDCX` messages.
+
+All subsequent `MDCX` messages sent towards an Osmux connection must contain the
+original _sendCID_ sent during `CRCX`. The same way, all `MDCX` response shall
+contain the _recvCID_ sent during `CRCX`.
+
+The other required connection address parameters, such as IP address, port, and
+codecs, are negotiated through MGCP and SDP as usual, but in this case the IP
+address and port specific the Osmux socket IP address and port to use, that
+together with the Osmux CID conform the entire tuple identifying a Osmux stream.
+
+Since Osmux only supports AMR codec payloads, the SDP must specify use of AMR
+codec.
+
+.Example: `CRCX` message that instructs OsmoMGW to create an Osmux connection
+----
+CRCX 189 rtpbridge/1 at mgw MGCP 1.0
+C: 36
+M: sendrecv
+X-Osmux: 2
+
+v=0
+o=- 36 23 IN IP4 172.18.2.20
+s=-
+c=IN IP4 1.2.3.4
+t=0 0
+m=audio 2342 RTP/AVP 112
+a=fmtp:112
+a=rtpmap:112 AMR/8000/1
+a=ptime:20
+----
+
+.Example: response to `CRCX` containing the <<recvCID>>
+----
+200 189 OK
+I: 07E41584
+X-Osmux: 2
+Z: rtpbridge/1 at mgw
+
+v=0
+o=- foo 21 IN IP4 172.18.1.20
+s=-
+c=IN IP4 172.18.1.20
+t=0 0
+m=audio 11002 RTP/AVP 112
+a=rtpmap:112 AMR/8000
+a=ptime:20
+----
+
+==== `X-Osmux` Support
+
+`X-Osmux` is known to be supported by OsmoMGW on the MGCP server side, and by
+OsmoBSC as well as OsmoMSC on the MGCP client side (through libosmo-mgcp-cli).
+No other programs supporting this feature are known or envisioned at the time of
+writing this document.
+
+In OmoMGW, Osmux support is managed through VTY.
+
+.Example: Sample config file section with Osmux configuation
+----
+mgcp
+ ...
+ osmux on <1>
+ osmux bind-ip 172.18.1.20 <2>
+ osmux port 1984 <3>
+ osmux batch-factor 4 <4>
+ osmux dummy on <5>
+----
+<1> Allow clients to set allocate Osmux connections in `rtpbridge` endpoints, while still allowing RTP connections
+<2> Bind the Osmux socket to the provided IP address
+<3> Bind the Osmux socket to the provided UDP port
+<4> Batch up to 4 RTP payloads of the same stream on each Osmux frame
+<5> Periodically send Osmux dummy frames, useful to punch a hole in NATs and maintain connections opened.
diff --git a/common/chapters/osmux/mo_call_osmux_aoip.msc b/common/chapters/osmux/mo_call_osmux_aoip.msc
new file mode 100644
index 0000000..9cb2e50
--- /dev/null
+++ b/common/chapters/osmux/mo_call_osmux_aoip.msc
@@ -0,0 +1,54 @@
+# MO-call with Osmux enable on 3GPP AoIP
+msc {
+	hscale=2;
+	ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgw_bsc[label="OsmoMGW(bsc)"], m_sc[label="MSC"], mgw_msc[label="OsmoMGW(msc)"];
+
+	bsc <- m_sc 	[label="BSSMAP RESET (with extension IE: Osmux Support)"];
+	bsc -> m_sc 	[label="BSSMAP RESET ACK (with extension IE: Osmux Support)"];
+	...;
+	ms box mgw_msc	[label="We assume a SDCCH is already established"];
+	...;
+
+	ms -> bsc	[label="DTAP CM Service Request"];
+	bsc -> m_sc	[label="Complete Layer 3 Information DTAP CM Service Request"];
+
+	# Allocate MGW/MSC Osmux endpoint
+	m_sc -> mgw_msc	[label="MGCP CRCX rtpbridge/*@mgw, X-Osmux: *"];
+	mgw_msc box mgw_msc	[label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 1, recvCID 5"];
+	mgw_msc -> m_sc	[label="MGCP CRCX rtpbridge/1 at mgw OK (MGW:1984, X-Osmux: 5)"];
+
+	bsc <- m_sc 	[label="BSSAP ASSGN REQ (3GPP AoIP, extension IE: Osmux CID 5)"];
+	bts <- bsc 	[label="RSL CHAN ACT"];
+	bts -> bsc 	[label="RSL CHAN ACT ACK"];
+	ms <- bsc      [label="Assignment Command"];
+	ms -> bsc      [label="Assignment Complete"];
+	...;
+
+	# connect BTS RTP with BSC-MGW RTP
+	bts <- bsc	[label="IPA CRCX"];
+	bts box bts	[label="Bind to BTS-local RTP Port (1000)"];
+	bts -> bsc	[label="IPA CRCX ACK (BTS:1000)"];
+	bsc -> mgw_bsc	[label="MGCP CRCX rtpbridge/2 at mgw (BTS:1000)"];
+	mgw_bsc box mgw_bsc	[label="Bind to MGW-local RTP Port (2000)\nConnect to BTS:1000"];
+	bsc <- mgw_bsc	[label="MGCP CRCX rtpbridge/2 at mgw OK (MGW:2000)"];
+	bts <- bsc	[label="IPA MDCX (MGW:2000)"];
+	bts box bts	[label="Connect RTP socket to remote (MGW) RTP Port"];
+	bts -> bsc	[label="IPA MDCX ACK"];
+	...;
+
+	mgw_bsc <- bsc	[label="MGCP CRCX rtpbridge/2 at mgw (MSC:1984, X-Osmux: 5)"];
+	mgw_bsc box mgw_bsc	[label="Bind to MGW-local Osmux Port (1985)\nConnect to MSC:1984\nAllocate new recvCID 7"];
+	mgw_bsc -> bsc	[label="MGCP CRCX rtpbridge/2 at mgw OK (MGW:1985, X-Osmux: 7)"];
+	...;
+
+	bsc -> m_sc	[label="BSSAP ASSGN CMPL (3GPP AoIP MGW:1985, extension IE: Osmux CID 7)"];
+	m_sc box m_sc	[label="Connect remote Osmux to MGW addr from ASSGN CMPL"];
+	m_sc -> mgw_msc	[label="MGCP MDCX rtpbridge/1 at mgw (MGW:1985, X-Osmux: 7)"];
+	m_sc <- mgw_msc	[label="MGCP MDCX rtpbridge/1 at mgw OK (X-Osmux: 5)"];
+	...;
+
+	mgw_bsc <=> mgw_msc	[label="Osmux Audio MGW:1985 MSC:1984, CID(uplink):5, CID(downlink):7"];
+	bts <=> mgw_bsc	[label="RTP Audio BTS:1000 MGW:2000"];
+	ms <=> bts	[label="Um Audio (bidirectional)"];
+	ms <-> m_sc	[label="DTAP CC ALERTING"];
+}
diff --git a/common/chapters/osmux/mo_call_osmux_sccplite.msc b/common/chapters/osmux/mo_call_osmux_sccplite.msc
new file mode 100644
index 0000000..903da46
--- /dev/null
+++ b/common/chapters/osmux/mo_call_osmux_sccplite.msc
@@ -0,0 +1,58 @@
+# MO-call with Osmux enable on 3GPP AoIP using A/IP with IPA/SCCPlite
+msc {
+	hscale=2;
+	ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgw_bsc[label="OsmoMGW(bsc)"], m_sc[label="MSC"], mgw_msc[label="OsmoMGW(msc)"];
+
+	ms box m_sc     [label="We assume a SDCCH is already established"];
+	...;
+
+	ms -> bsc	[label="DTAP CM Service Request"];
+	bsc -> m_sc	[label="Complete Layer 3 Information DTAP CM Service Request"];
+	bsc <- m_sc	[label="Connection Confirmed"];
+
+	# Allocate MGW/MSC Osmux endpoint
+	m_sc -> mgw_msc	[label="MGCP CRCX *@mgw, X-Osmux: *"];
+	mgw_msc box mgw_msc	[label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 1, recvCID 5"];
+	mgw_msc -> m_sc	[label="MGCP CRCX rtpbridge/1 at mgw OK (MGW:1984, X-Osmux: 5)"];
+
+	bsc <- m_sc     [label="BSSAP ASSGN REQ (CIC:1)"];
+	bts <- bsc      [label="RSL CHAN ACT"];
+	bts -> bsc      [label="RSL CHAN ACT ACK"];
+	ms <- bsc      [label="Assignment Command"];
+	ms -> bsc      [label="Assignment Complete"];
+	...;
+
+	# connect BTS RTP with BSC-MGW RTP, CIC is used as MGW endpoint
+	bts <- bsc	[label="IPA CRCX"];
+	bts box bts	[label="Bind to BTS-local RTP Port (1000)"];
+	bts -> bsc	[label="IPA CRCX ACK (BTS:1000)"];
+	bsc -> mgw_bsc	[label="MGCP CRCX 1 at mgw (BTS:1000)"];
+	mgw_bsc box mgw_bsc	[label="Bind to MGW-local RTP Port (2000)\nConnect to BTS:1000"];
+	bsc <- mgw_bsc	[label="MGCP CRCX 1 at mgw OK (MGW:2000)"];
+	bts <- bsc	[label="IPA MDCX (MGW:2000)"];
+	bts box bts	[label="Connect RTP socket to remote (MGW) RTP Port"];
+	bts -> bsc	[label="IPA MDCX ACK"];
+	...;
+
+	bsc -> m_sc      [label="BSSMAP ASSGN Complete"];
+	...;
+
+	# MSC configures BSC-MGW MSC-side of the endpoint through MGCP UDP forwarding
+	mgw_bsc <- m_sc    [label="MGCP CRCX 1 at mgw (MSC:1984, X-Osmux: 5)"];
+	mgw_bsc box mgw_bsc   [label="Bind to BTS-local Osmux Port (1985)\nAllocate new recvCID 7"];
+	mgw_bsc -> m_sc    [label="MGCP CRCX 1 at mgw OK (MGW:1985, X-Osmux: 7)"];
+	mgw_bsc <- m_sc    [label="MGCP MDCX 1 at mgw (recvonly) "];
+	mgw_bsc box mgw_bsc   [label="Connect Osmux socket to remote (MSC) Osmux Port"];
+	mgw_bsc -> m_sc    [label="MGCP MDCX 1 at mgw OK"];
+	mgw_bsc <= mgw_msc    [label="Osmux Audio MGW:1985 MSC:1984, CID(downlink):7"];
+	bts <= mgw_bsc     [label="RTP Audio BTS:1000 MGW:2000"];
+	ms <= bts       [label="Um Audio (unidirectional)"];
+	ms <- m_sc      [label="DTAP CC ALERTING"];
+	...;
+	mgw_bsc <- m_sc    [label="MGCP MDCX 1 at mgw (sndrecv) "];
+	mgw_bsc box mgw_bsc   [label="Switch to bi-directional audio"];
+	mgw_bsc -> m_sc    [label="MGCP MDCX 1 at mgw OK"];
+	mgw_bsc <=> mgw_msc   [label="Osmux Audio MGW:1985 MSC:1984, CID(uplink):5, CID(downlink):7"];
+	bts <=> mgw_bsc    [label="RTP Audio BTS:1000 MGW:2000"];
+	ms <=> bts      [label="Um Audio (bidirectional)"];
+}
diff --git a/common/chapters/osmux/mo_call_osmux_sccplite_nat.msc b/common/chapters/osmux/mo_call_osmux_sccplite_nat.msc
new file mode 100644
index 0000000..2aa8105
--- /dev/null
+++ b/common/chapters/osmux/mo_call_osmux_sccplite_nat.msc
@@ -0,0 +1,77 @@
+# MO-call with Osmux enable on 3GPP AoIP using A/IP with IPA/SCCPlite with a BSC-NAT between BSC and MSC
+msc {
+	hscale=2;
+	ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgw_bsc[label="OsmoMGW(bsc)"], bscnat[label="OsmoBSCNAT"], m_sc[label="MSC"], mgw_msc[label="OsmoMGW(msc)"];
+
+	ms box m_sc     [label="We assume a SDCCH is already established"];
+	...;
+
+	ms -> bsc	[label="DTAP CM Service Request"];
+	bsc -> m_sc	[label="Complete Layer 3 Information DTAP CM Service Request"];
+	bsc <- m_sc	[label="Connection Confirmed"];
+
+	# Allocate MGW/MSC RTP endpoint
+	m_sc -> mgw_msc	[label="MGCP CRCX *@mgw"];
+	mgw_msc box mgw_msc	[label="Bind to MGW-local RTP Port (3000)\nAllocate new endpoint 1"];
+	mgw_msc -> m_sc	[label="MGCP CRCX rtpbridge/1 at mgw OK (MGW:3000)"];
+	bscnat <- m_sc     [label="BSSAP ASSGN REQ (CIC:1)"];
+
+	# NAT: MGW/MSC Osmux endpoint
+	#bscnat -> bscnat	[label="MGCP CRCX *@mgw, X-Osmux: *"];
+	mgw_msc box mgw_msc	[label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 2, recvCID 5"];
+	#mgw_msc -> m_sc	[label="MGCP CRCX rtpbridge/1 at mgw OK (MGW:1984, X-Osmux: 5)"];
+	bsc <- bscnat    [label="BSSAP ASSGN REQ (CIC:2)"];
+
+	bts <- bsc      [label="RSL CHAN ACT"];
+	bts -> bsc      [label="RSL CHAN ACT ACK"];
+	ms <- bsc      [label="Assignment Command"];
+	ms -> bsc      [label="Assignment Complete"];
+	...;
+
+	# connect BTS RTP with BSC-MGW RTP, CIC is used as MGW endpoint
+	bts <- bsc	[label="IPA CRCX"];
+	bts box bts	[label="Bind to BTS-local RTP Port (1000)"];
+	bts -> bsc	[label="IPA CRCX ACK (BTS:1000)"];
+	bsc -> mgw_bsc	[label="MGCP CRCX 1 at mgw (BTS:1000)"];
+	mgw_bsc box mgw_bsc	[label="Bind to MGW-local RTP Port (2000)\nConnect to BTS:1000"];
+	bsc <- mgw_bsc	[label="MGCP CRCX 1 at mgw OK (MGW:2000)"];
+	bts <- bsc	[label="IPA MDCX (MGW:2000)"];
+	bts box bts	[label="Connect RTP socket to remote (MGW) RTP Port"];
+	bts -> bsc	[label="IPA MDCX ACK"];
+	#bsc -> mgw_bsc	[label="MGCP MDCX 1 at mgw (optional)"];
+	#bsc <- mgw_bsc	[label="MGCP MDCX 1 at mgw OK (optional)"];
+	...;
+
+	bsc -> bscnat      [label="BSSMAP ASSGN Complete"];
+	bscnat -> m_sc     [label="BSSMAP ASSGN Complete"];
+	...;
+
+	# MSC configures BSC-MGW MSC-side of the endpoint through MGCP UDP forwarding
+	bscnat <- m_sc    [label="MGCP CRCX 1 at mgw (MSC:3000)"];
+	bscnat box bscnat [label="Allocate new endpoint 2\nAllocate new recvCID 5\nBind to local Osmux Port (1984)\nBind to local RTP port 4000"];
+	mgw_bsc <- bscnat [label="MGCP CRCX 2 at mgw (MSC:1984, X-Osmux: 5)"];
+	mgw_bsc -> bscnat    [label="MGCP CRCX 2 at mgw OK (MGW:1985, X-Osmux: 7)"];
+	bscnat -> m_sc    [label="MGCP CRCX 1 at mgw OK (MGW:4000)"];
+	bscnat <- m_sc    [label="MGCP MDCX 1 at mgw (recvonly) "];
+	mgw_bsc <- bscnat    [label="MGCP MDCX 2 at mgw (recvonly) "];
+	mgw_bsc box mgw_bsc   [label="Connect Osmux socket to remote (MSC) Osmux Port"];
+	mgw_bsc -> bscnat    [label="MGCP MDCX 2 at mgw OK"];
+	bscnat -> m_sc    [label="MGCP MDCX 1 at mgw OK"];
+
+	bscnat <= mgw_msc    [label="RTP Audio BSCNAT:4000 MGW:3000"];
+	mgw_bsc <= bscnat [label="Osmux Audio MGW:1985 BSCNAT:1984, CID(downlink):7"];
+	bts <= mgw_bsc     [label="RTP Audio BTS:1000 MGW:2000"];
+	ms <= bts       [label="Um Audio (unidirectional)"];
+	ms <- m_sc      [label="DTAP CC ALERTING"];
+	...;
+	bscnat <- m_sc    [label="MGCP MDCX 1 at mgw (sndrecv) "];
+	mgw_bsc <- bscnat    [label="MGCP MDCX 2 at mgw (sndrecv) "];
+	mgw_bsc box mgw_bsc   [label="Switch to bi-directional audio"];
+	mgw_bsc -> bscnat    [label="MGCP MDCX 2 at mgw OK"];
+	bscnat -> m_sc    [label="MGCP MDCX 1 at mgw OK"];
+
+	bscnat <=> mgw_msc    [label="RTP Audio BSCNAT:4000 MGW:3000"];
+	mgw_bsc <=> bscnat   [label="Osmux Audio MGW:1985 MSC:1984, CID(uplink):5, CID(downlink):7"];
+	bts <=> mgw_bsc    [label="RTP Audio BTS:1000 MGW:2000"];
+	ms <=> bts      [label="Um Audio (bidirectional)"];
+}
diff --git a/common/chapters/osmux/network_osmux_aoip.dot b/common/chapters/osmux/network_osmux_aoip.dot
new file mode 100644
index 0000000..7531e6a
--- /dev/null
+++ b/common/chapters/osmux/network_osmux_aoip.dot
@@ -0,0 +1,32 @@
+digraph G {
+	rankdir = LR;
+	subgraph cluster_RAN {
+		OsmoBTS1 [label="OsmoBTS"];
+		OsmoBTS2 [label="OsmoBTS"];
+		OsmoBSC;
+		OsmoMGW [label="OsmoMGW\n(for BSC)"];
+
+		OsmoBTS1 -> OsmoBSC [label="Abis/IP", dir="both"];
+		OsmoBTS2 -> OsmoBSC [label="Abis/IP", dir="both"];
+		OsmoBSC -> OsmoMGW [label="MGCP", dir="both"];
+		{ rank = same; OsmoBSC; OsmoMGW }
+
+		OsmoBTS1 -> OsmoMGW [label="RTP", dir="both"];
+		OsmoBTS2 -> OsmoMGW [label="RTP", dir="both"];
+
+		label = "RAN";
+	}
+	subgraph cluster_CN {
+		OsmoMGW1 [label="OsmoMGW\n(for MSC)"];
+		OsmoMSC [label="MSC\ne.g. OsmoMSC"];
+		Core [label="Other CN Elements"];
+		OsmoMSC -> Core [label="MAP/ISUP/SIP/GSUP", dir="both"];
+		OsmoMSC -> OsmoMGW1 [label="MGCP", dir="both"];
+		{ rank = same; OsmoMSC; OsmoMGW1 }
+		OsmoMGW -> OsmoMGW1 [label="Osmux", dir="both", color=red];
+		OsmoMGW1 -> Core [label="RTP", dir="both"];
+		label = "CN";
+	}
+
+	OsmoBSC -> OsmoMSC [label="3GPP AoIP\nvia SIGTRAN/STP", dir="both"];
+}
diff --git a/common/chapters/osmux/network_osmux_sccplite.dot b/common/chapters/osmux/network_osmux_sccplite.dot
new file mode 100644
index 0000000..678a61e
--- /dev/null
+++ b/common/chapters/osmux/network_osmux_sccplite.dot
@@ -0,0 +1,33 @@
+digraph G {
+	rankdir = LR;
+	subgraph cluster_RAN {
+		OsmoBTS1 [label="OsmoBTS"];
+		OsmoBTS2 [label="OsmoBTS"];
+		OsmoBSC;
+		OsmoMGW [label="OsmoMGW\n(for BSC)"];
+
+		OsmoBTS1 -> OsmoBSC [label="Abis/IP", dir="both"];
+		OsmoBTS2 -> OsmoBSC [label="Abis/IP", dir="both"];
+		OsmoBSC -> OsmoMGW [label="MGCP (BTS side)", dir="both"];
+		{ rank = same; OsmoBSC; OsmoMGW }
+
+		OsmoBTS1 -> OsmoMGW [label="RTP", dir="both"];
+		OsmoBTS2 -> OsmoMGW [label="RTP", dir="both"];
+
+		label = "RAN";
+	}
+	subgraph cluster_CN {
+		OsmoMGW1 [label="OsmoMGW\n(for MSC)"];
+		OsmoMSC [label="MSC\ne.g. OsmoMSC"];
+		Core [label="Other CN Elements"];
+		OsmoMSC -> Core [label="MAP/ISUP/SIP/GSUP", dir="both"];
+		OsmoMSC -> OsmoMGW1 [label="MGCP", dir="both"];
+		{ rank = same; OsmoMSC; OsmoMGW1 }
+		OsmoMGW -> OsmoMGW1 [label="Osmux", dir="both", color=red];
+		OsmoMGW1 -> Core [label="RTP", dir="both"];
+		label = "CN";
+	}
+
+	OsmoBSC -> OsmoMSC [label="3GPP AoIP\nvia IPA/SCCPlite", dir="both"];
+	OsmoMGW -> OsmoMSC [label="MGCP (CN side)\n(IPA/UDP forwarding via BSC)", dir="both"];
+}
diff --git a/common/chapters/osmux/network_osmux_sccplite_nat.dot b/common/chapters/osmux/network_osmux_sccplite_nat.dot
new file mode 100644
index 0000000..021d0ec
--- /dev/null
+++ b/common/chapters/osmux/network_osmux_sccplite_nat.dot
@@ -0,0 +1,40 @@
+digraph G {
+	rankdir = LR;
+	subgraph cluster_RAN {
+		OsmoBTS1 [label="OsmoBTS"];
+		OsmoBTS2 [label="OsmoBTS"];
+		OsmoBSC;
+		OsmoMGW [label="OsmoMGW\n(for BSC)"];
+
+		OsmoBTS1 -> OsmoBSC [label="Abis/IP", dir="both"];
+		OsmoBTS2 -> OsmoBSC [label="Abis/IP", dir="both"];
+		OsmoBSC -> OsmoMGW [label="MGCP (BTS side)", dir="both"];
+		{ rank = same; OsmoBSC; OsmoMGW }
+
+		OsmoBTS1 -> OsmoMGW [label="RTP", dir="both"];
+		OsmoBTS2 -> OsmoMGW [label="RTP", dir="both"];
+
+		label = "RAN";
+	}
+	subgraph cluster_BSCNAT {
+		OsmoBSCNAT;
+		label = "BSCNAT";
+	}
+	subgraph cluster_CN {
+		OsmoMGW1 [label="OsmoMGW\n(for MSC)"];
+		OsmoMSC [label="MSC\ne.g. OsmoMSC"];
+		Core [label="Other CN Elements"];
+		OsmoMSC -> Core [label="MAP/ISUP/SIP/GSUP", dir="both"];
+		OsmoMSC -> OsmoMGW1 [label="MGCP", dir="both"];
+		{ rank = same; OsmoMSC; OsmoMGW1 }
+		OsmoMGW -> OsmoBSCNAT [label="Osmux", dir="both", color=red];
+		OsmoMGW1 -> Core [label="RTP", dir="both"];
+		label = "CN";
+	}
+
+	OsmoBSC -> OsmoBSCNAT [label="3GPP AoIP\nvia IPA/SCCPlite", dir="both"];
+	OsmoMGW -> OsmoBSCNAT [label="MGCP (CN side)\n(IPA/UDP forwarding via BSC)", dir="both"];
+	OsmoBSCNAT -> OsmoMSC [label="3GPP AoIP\nvia IPA/SCCPlite", dir="both"];
+	OsmoBSCNAT -> OsmoMSC [label="MGCP\nvia UDP", dir="both"];
+	OsmoBSCNAT -> OsmoMGW1 [label="RTP", dir="both"];
+}
diff --git a/common/chapters/osmux/osmux.adoc b/common/chapters/osmux/osmux.adoc
new file mode 100644
index 0000000..5e53b60
--- /dev/null
+++ b/common/chapters/osmux/osmux.adoc
@@ -0,0 +1,141 @@
+== Osmux
+
+`Osmux` is a protocol aimed at multiplexing and transmitting voice and
+signalling traffic from multiple sources in order to reduce the overall
+bandwidth consumption. This feature becomes specially meaningful in case of
+satellite based GSM systems, where the transmission cost on the back-haul is
+relatively expensive. In such environment, even seemingly small protocol
+optimizations, eg. message batching and trunking, can result in significant cost
+reduction.
+
+Full reference document for the osmux protocol can be found here:
+http://ftp.osmocom.org/docs/latest/osmux-reference.pdf
+
+In Osmocom satellite based GSM networks, the satellite link is envisioned to be
+in between the BSS and the core network, that is, between the BSC and the MSC
+(or BSC-NAT). Hence, Osmocom components can make use of `Osmux` protocol to
+multiplex payload audio streams from call legs between OsmoBSC and OsmoMSC (or
+OsmoBSCNAT). The MGW attached those components need of course also be aware of
+`Osmux` existence in order to properly set up the audio data plane.
+
+=== Osmux and NAT
+
+It is quite usual for satellite based links to use NATs, which means any or both
+of the two components at each side of the satellite link (BSC and MSC/BSC-NAT)
+may end up being behind a NAT and being unable to provide the real public
+address to its peer on the other side of the satellite.
+
+As a result, upon call parameter negotiation (RTP/Osmux IP address and port),
+those parameters won't be entirely useful and some specific logic needs to be
+introduced into the network components to circumvent the NAT under those cases.
+
+For instance, if the BSC and its co-located MGW (BSC/MGW from now on) is under a
+NAT, it may end up providing its private address and port as RTP/Osmux
+parameters to the MSC/MGW through GSM protocols, but MSC will fail to send any
+message to that tuple because of the NAT or routing issues (due to IP address
+being a private address). In that scenario, MSC/MGW needs to be aware that
+there's a NAT and wait until an RTP/Osmux message arrives from the BSC/MGW host.
+It then can, from that message source IP address and port (and CID in case of
+Osmux), discover the real public IP address and port of the peer (BSC/MGW). From
+that point on, the BSC/MGW punched a hole in the NAT (its connection table is
+updated) and MSC/MGW is able to send data back to it on that connection.
+
+Moreover, NATs tend to drop connections from their connection tables after some
+inactivity time, meaning a peer may receive notice about the other end not being
+available while it actually is. This means the GSM network needs to be
+configured in a way to ensure inactivity periods are short enough that this
+cannot occur. That's the reason why OsmoMGW provides the `osmux dummy` VTY
+command to enable sending dummy packets from time to time to keep the
+connections alive.
+
+=== CID allocation
+
+Each peer (BSC/MGW and MSC/MGW) allocates its own _recvCID_, and receives from
+the peer through the used GSM protocol the peer's _recvCID_, which becomes
+the local _sendCID_ for that connection.
+
+----
+BSC/MGW(recvCID=Y,sendCID=?)<-X--MSC/MGW(recvCID=X,sendCID=?)
+BSC/MGW(recvCID=Y,sendCID=X)--Y->MSC/MGW(recvCID=X,sendCID=Y)
+----
+
+This way each peer is responsible for allocating and managing their own local
+address (CID) space. This is basically the same that happens with regular IP
+address and port in the RTP case (and those also apply when Osmux is used, but
+an extra identifier, the CID, is allocated).
+
+In an ideal scenario, without NAT, each BSC/MGW would have a public,
+differentiated and unique IP and port set tuple, And MSC/MGW should be able to
+identify messages coming from them by easily matching source IP address, port
+(and CID in Osmux case) against the parameters negotiated during call set up.
+
+In this kind of scenario, MSC/MGW could easily open and manage one Osmux socket
+per BSC (based on SDP IPaddr and port parameters), with same `<localIPaddr,
+localPort>` tuple, allowing for 256 Osmux CIDs per BSC and hence call legs per
+BSC. Each of the peers could actually have more than one Osmux socket towards
+the other peer, by using a pool of ports or IP addresses, so there's really not
+limit if required as long as there's a way to infer the initially negotiated
+`<srcIP, srcPort, dstIP, dstPort, sendCID>` tuple from the received audio
+packets.
+
+However, due to some constrains from in between NATs explained in section above,
+BSC/MGW IP address and port are not a priory known, and could change between
+different connections coming from it. As a result, it is difficult to infer the
+entire tuple, so for now MGW needs to allocate its Osmux _recvCID_ in a clever
+way, in order to be able to identify the full tuple from it.
+
+Hence, currently OsmoMGW CID allocation implementation shares CID between all
+connections, which means it can only handle up to 256 concurrent Osmux
+connections (call legs).
+
+Future work in OsmoMGW (https://osmocom.org/issues/4092[OS#4092]) plans to use a
+set of local ports for Osmux sockets instead of only 1 currently used. This way
+local ports can be matched against specific `<remoteIP, remotePort>` tuples and
+have an entire 256 Osmux CID space per `<remoteIP, remotePort>` (aka per peer).
+
+=== 3GPP AoIP network setup with Osmux
+
+[[fig-network-osmux-aoip]]
+.Sample node diagram of a 3GPP AoIP network with Osmux enabled
+[graphviz]
+----
+include::network_osmux_aoip.dot[]
+----
+
+.MO-call with Osmux enable on 3GPP AoIP
+[mscgen]
+----
+include::mo_call_osmux_aoip.msc[]
+----
+
+=== SCCPLite network setup with Osmux
+
+[[fig-network-osmux-sccplite]]
+.Sample node diagram of a 3GPP AoIP using A/IP with IPA/SCCPlite network with Osmux enabled
+[graphviz]
+----
+include::network_osmux_sccplite.dot[]
+----
+
+.MO-call with Osmux enable on 3GPP AoIP using A/IP with IPA/SCCPlite
+["mscgen"]
+----
+include::mo_call_osmux_sccplite.msc[]
+----
+
+=== SCCPLite network setup with Osmux + BSC-NAT
+
+[[fig-network-osmux-sccplite-nat]]
+.Sample node diagram of a 3GPP AoIP using A/IP with IPA/SCCPlite network and BSC-NAT with Osmux enabled
+[graphviz]
+----
+include::network_osmux_sccplite_nat.dot[]
+----
+
+.MO-call with Osmux enable on 3GPP AoIP using A/IP with IPA/SCCPlite with a BSC-NAT between BSC and MSC
+["mscgen"]
+----
+include::mo_call_osmux_sccplite_nat.msc[]
+----
+
+include::mgcp_extension_osmux.adoc[]

-- 
To view, visit https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/14839
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

Gerrit-Project: osmo-gsm-manuals
Gerrit-Branch: master
Gerrit-Change-Id: I182d94c63f7d74ef882b77be59a95b1b7d8a4e5e
Gerrit-Change-Number: 14839
Gerrit-PatchSet: 2
Gerrit-Owner: pespin <pespin at sysmocom.de>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: laforge <laforge at gnumonks.org>
Gerrit-Reviewer: osmith <osmith at sysmocom.de>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20190722/57fcf433/attachment.html>


More information about the gerrit-log mailing list