manual: Include QoS chapter and add osmo-mgw specific example

Change-Id: I46f632f52a86a50242689a0132a7a7cb2a8feb12
Depends: osmo-gsm-manuals.git Id344c29eda2a9b3e36376302b425e9db1f6c0f28

TODO-RELEASE

@@ -24,3 +24,4 @@
 # If any interfaces have been removed or changed since the last public release, a=0.
 #
 #library		what		description / commit summary line
+update dependency to libosmocore > 1.5.1 for our use of osmo_sock_set_dscp()

contrib/osmo-mgw.spec.in

@@ -120,7 +120,7 @@ make %{?_smp_mflags} check || (find . -name testsuite.log -exec cat {} +)
 %config(noreplace) %{_sysconfdir}/osmocom/osmo-mgw.cfg
 
 %files -n libosmo-mgcp-client8
-%{_libdir}/libosmo-mgcp-client.so.6*
+%{_libdir}/libosmo-mgcp-client.so.8*
 
 %files -n libosmo-mgcp-client-devel
 %{_libdir}/libosmo-mgcp-client.so

debian/changelog

@@ -1,3 +1,9 @@
+osmo-mgw (1.8.1) unstable; urgency=medium
+
+  * attempt to fix RPM spec file after recent soversion bump
+
+ -- Harald Welte <laforge@osmocom.org>  Wed, 24 Feb 2021 10:56:17 +0100
+
 osmo-mgw (1.8.0) unstable; urgency=medium
 
   [ Harald Welte ]

doc/examples/osmo-mgw/osmo-mgw-abis_e1.cfg

@@ -9,7 +9,7 @@ mgcp
   rtp port-range 4002 16000
   rtp bind-ip 127.0.0.1
   rtp ip-probing
-  rtp ip-tos 184
+  rtp ip-dscp 46
   bind port 2427
   sdp audio payload number 98
   sdp audio payload name GSM

doc/examples/osmo-mgw/osmo-mgw.cfg

@@ -6,7 +6,7 @@ mgcp
   rtp port-range 4002 16000
   rtp bind-ip 127.0.0.1
   rtp ip-probing
-  rtp ip-tos 184
+  rtp ip-dscp 46
   bind port 2427
   sdp audio payload number 98
   sdp audio payload name GSM

doc/manuals/chapters/configuration.adoc

@@ -101,7 +101,7 @@ mgcp
  rtp net-range 6000 6011
  rtp net-bind-ip 192.168.100.130
  rtp ip-probing
- rtp ip-tos 184
+ rtp ip-dscp 46
  no rtp keep-alive
  bind port 2428
  number endpoints 30

doc/manuals/chapters/overview.adoc

@@ -52,7 +52,7 @@ digraph G {
 }
 ----
 
-[[fig-bsc]]
+[[fig-bsc-e1]]
 .Integration of legacy E1 BTS in AoIP network
 [graphviz]
 ----

doc/manuals/chapters/qos-example.adoc

@@ -0,0 +1,42 @@
+==== Full example of QoS for osmo-mgw
+
+In the below example we will show the full set of configuration required
+for both DSCP and PCP differentiation of RTP traffic by osmo-mgw.
+
+What we want to achieve in this example is the following configuration:
+
+.DSCP and PCP assignments for osmo-mgw Abis downlink traffic in this example
+[options="header",width="30%",cols="2,1,1"]
+|===
+|Traffic      |DSCP|PCP
+|RTP    |  46|  6
+|===
+
+. configure the osmo-mgw program to set the DSCP value
+. configure an egrees QoS map to map from priority to PCP
+
+.Example Step 1: add related VTY configuration to `osmo-mgw.cfg`
+----
+...
+mgcp
+ rtp ip-dscp 46
+ rtp socket-priority 6
+...
+----
+
+.Example Step 2: egress QoS map to map from socket priority to PCP values
+----
+$ sudo ip link set dev eth0.9<1> type vlan egress-qos-map 0:0 5:5 6:6 7:7 <2>
+----
+<1> make sure to specify your specific VLAN interface name here instead of `eth0.9`.
+<2> create a egress QoS map that maps the priority value 1:1 to the PCP. We also include the
+    mapping 5:5 and 7:7 from the osmo-bsc example (see <<userman-osmobsc>>) here.
+
+NOTE:: The settings of the `ip` command are volatile and only active until
+the next reboot (or the network device or VLAN is removed).  Please refer to
+the documentation of your specific Linux distribution in order to find out how
+to make such settings persistent by means of an `ifup` hook whenever the interface
+comes up.  For CentOS/RHEL 8 this can e.g. be achieved by means of an `/sbin/ifup-local
+script` (when using `network-scripts` and not NetworkManager).  For Debian or Ubuntu,
+this typically involves adding `up` lines to `/etc/network/interfaces` or a `/etc/network/if-up.d`
+script.

doc/manuals/osmomgw-usermanual.adoc

@@ -24,6 +24,8 @@ include::{srcdir}/chapters/mgcp_extensions.adoc[]
 
 include::./common/chapters/osmux/osmux.adoc[]
 
+include::./common/chapters/qos-dscp-pcp.adoc[]
+
 //include::{srcdir}/chapters/counters.adoc[]
 
 include::./common/chapters/vty_cpu_sched.adoc[]

include/osmocom/mgcp/mgcp.h

@@ -143,6 +143,7 @@ struct mgcp_config {
 
 	struct mgcp_port_range net_ports;
 	int endp_dscp;
+	int endp_priority;
 
 	int force_ptime;
 
@@ -208,5 +209,6 @@ int mgcp_send_reset_ep(struct mgcp_endpoint *endp);
 int mgcp_send_reset_all(struct mgcp_config *cfg);
 
 
-int mgcp_create_bind(const char *source_addr, struct osmo_fd *fd, int port);
+int mgcp_create_bind(const char *source_addr, struct osmo_fd *fd, int port, uint8_t dscp,
+		     uint8_t prio);
 int mgcp_udp_send(int fd, struct osmo_sockaddr *addr, int port, char *buf, int len);

include/osmocom/mgcp/mgcp_network.h

@@ -148,7 +148,6 @@ void mgcp_patch_and_count(struct mgcp_endpoint *endp,
 			  struct mgcp_rtp_end *rtp_end,
 			  struct osmo_sockaddr *addr, struct msgb *msg);
 void mgcp_get_local_addr(char *addr, struct mgcp_conn_rtp *conn);
-int mgcp_set_ip_tos(int fd, int tos);
 
 /* payload processing default functions */
 int mgcp_rtp_processing_default(struct mgcp_endpoint *endp, struct mgcp_rtp_end *dst_end,

src/libosmo-mgcp/mgcp_network.c

@@ -1514,31 +1514,21 @@ static int rx_rtp(struct msgb *msg)
 	return conn->endp->type->dispatch_rtp_cb(msg);
 }
 
-/*! set IP Type of Service parameter.
- *  \param[in] fd associated file descriptor.
- *  \param[in] tos dscp value.
- *  \returns 0 on success, -1 on ERROR. */
-int mgcp_set_ip_tos(int fd, int tos)
-{
-	int ret;
-	ret = setsockopt(fd, IPPROTO_IP, IP_TOS, &tos, sizeof(tos));
-
-	if (ret < 0)
-		return -1;
-	return 0;
-}
-
 /*! bind RTP port to osmo_fd.
  *  \param[in] source_addr source (local) address to bind on.
  *  \param[in] fd associated file descriptor.
  *  \param[in] port to bind on.
+ *  \param[in] dscp IP DSCP value to use.
+ *  \param[in] prio socket priority to use.
  *  \returns 0 on success, -1 on ERROR. */
-int mgcp_create_bind(const char *source_addr, struct osmo_fd *fd, int port)
+int mgcp_create_bind(const char *source_addr, struct osmo_fd *fd, int port, uint8_t dscp,
+		     uint8_t prio)
 {
 	int rc;
 
 	rc = osmo_sock_init2(AF_UNSPEC, SOCK_DGRAM, IPPROTO_UDP, source_addr, port,
-			     NULL, 0, OSMO_SOCK_F_BIND);
+			     NULL, 0, OSMO_SOCK_F_BIND | OSMO_SOCK_F_DSCP(dscp) |
+			     OSMO_SOCK_F_PRIO(prio));
 	if (rc < 0) {
 		LOGP(DRTP, LOGL_ERROR, "failed to bind UDP port (%s:%i).\n",
 		     source_addr, port);
@@ -1557,26 +1547,22 @@ static int bind_rtp(struct mgcp_config *cfg, const char *source_addr,
 	/* NOTE: The port that is used for RTCP is the RTP port incremented by one
 	 * (e.g. RTP-Port = 16000 ==> RTCP-Port = 16001) */
 
-	if (mgcp_create_bind(source_addr, &rtp_end->rtp,
-			     rtp_end->local_port) != 0) {
+	if (mgcp_create_bind(source_addr, &rtp_end->rtp, rtp_end->local_port,
+			     cfg->endp_dscp, cfg->endp_priority) != 0) {
 		LOGPENDP(endp, DRTP, LOGL_ERROR,
 			 "failed to create RTP port: %s:%d\n",
 			 source_addr, rtp_end->local_port);
 		goto cleanup0;
 	}
 
-	if (mgcp_create_bind(source_addr, &rtp_end->rtcp,
-			     rtp_end->local_port + 1) != 0) {
+	if (mgcp_create_bind(source_addr, &rtp_end->rtcp, rtp_end->local_port + 1,
+			     cfg->endp_dscp, cfg->endp_priority) != 0) {
 		LOGPENDP(endp, DRTP, LOGL_ERROR,
 			 "failed to create RTCP port: %s:%d\n",
 			 source_addr, rtp_end->local_port + 1);
 		goto cleanup1;
 	}
 
-	/* Set Type of Service (DSCP-Value) as configured via VTY */
-	mgcp_set_ip_tos(rtp_end->rtp.fd, cfg->endp_dscp);
-	mgcp_set_ip_tos(rtp_end->rtcp.fd, cfg->endp_dscp);
-
 	if (osmo_fd_register(&rtp_end->rtp) != 0) {
 		LOGPENDP(endp, DRTP, LOGL_ERROR,
 			 "failed to register RTP port %d\n",

src/libosmo-mgcp/mgcp_osmux.c

@@ -418,13 +418,13 @@ int osmux_init(int role, struct mgcp_config *cfg)
 
 	osmo_fd_setup(&osmux_fd, -1, OSMO_FD_READ, osmux_read_fd_cb, cfg, 0);
 
-	ret = mgcp_create_bind(cfg->osmux_addr, &osmux_fd, cfg->osmux_port);
+	ret = mgcp_create_bind(cfg->osmux_addr, &osmux_fd, cfg->osmux_port,
+				cfg->endp_dscp, cfg->endp_priority);
 	if (ret < 0) {
 		LOGP(DLMGCP, LOGL_ERROR, "cannot bind OSMUX socket to %s:%u\n",
 		     cfg->osmux_addr, cfg->osmux_port);
 		return ret;
 	}
-	mgcp_set_ip_tos(osmux_fd.fd, cfg->endp_dscp);
 
 	ret = osmo_fd_register(&osmux_fd);
 	if (ret < 0) {

src/libosmo-mgcp/mgcp_vty.c

@@ -83,6 +83,8 @@ static int config_write_mgcp(struct vty *vty)
 	else
 		vty_out(vty, " no rtp ip-probing%s", VTY_NEWLINE);
 	vty_out(vty, " rtp ip-dscp %d%s", g_cfg->endp_dscp, VTY_NEWLINE);
+	if (g_cfg->endp_priority)
+		vty_out(vty, " rtp socket-priority %d%s", g_cfg->endp_priority, VTY_NEWLINE);
 	if (trunk->keepalive_interval == MGCP_KEEPALIVE_ONCE)
 		vty_out(vty, " rtp keep-alive once%s", VTY_NEWLINE);
 	else if (trunk->keepalive_interval)
@@ -579,19 +581,27 @@ DEFUN_USRATTR(cfg_mgcp_rtp_no_net_bind_ip_probing,
 DEFUN_USRATTR(cfg_mgcp_rtp_ip_dscp,
 	      cfg_mgcp_rtp_ip_dscp_cmd,
 	      X(MGW_CMD_ATTR_NEWCONN),
-	      "rtp ip-dscp <0-255>",
+	      "rtp ip-dscp <0-63>",
 	      RTP_STR
-	      "Apply IP_TOS to the audio stream (including Osmux)\n" "The DSCP value\n")
+	      "Use specified DSCP for the audio stream (including Osmux)\n" "The DSCP value\n")
 {
 	int dscp = atoi(argv[0]);
 	g_cfg->endp_dscp = dscp;
 	return CMD_SUCCESS;
 }
 
-ALIAS_DEPRECATED(cfg_mgcp_rtp_ip_dscp, cfg_mgcp_rtp_ip_tos_cmd,
-		 "rtp ip-tos <0-255>",
-		 RTP_STR
-		 "Apply IP_TOS to the audio stream\n" "The DSCP value\n")
+DEFUN_USRATTR(cfg_mgcp_rtp_priority,
+	      cfg_mgcp_rtp_priority_cmd,
+	      X(MGW_CMD_ATTR_NEWCONN),
+	      "rtp socket-priority <0-255>",
+	      RTP_STR
+	      "socket priority (values > 6 require CAP_NET_ADMIN)\n" "socket priority value\n")
+{
+	int prio = atoi(argv[0]);
+	g_cfg->endp_priority = prio;
+	return CMD_SUCCESS;
+}
+
 #define FORCE_PTIME_STR "Force a fixed ptime for packets sent"
 DEFUN_USRATTR(cfg_mgcp_rtp_force_ptime,
 	      cfg_mgcp_rtp_force_ptime_cmd,
@@ -1622,7 +1632,7 @@ int mgcp_vty_init(void)
 	install_element(MGCP_NODE, &cfg_mgcp_rtp_net_bind_ip_probing_cmd);
 	install_element(MGCP_NODE, &cfg_mgcp_rtp_no_net_bind_ip_probing_cmd);
 	install_element(MGCP_NODE, &cfg_mgcp_rtp_ip_dscp_cmd);
-	install_element(MGCP_NODE, &cfg_mgcp_rtp_ip_tos_cmd);
+	install_element(MGCP_NODE, &cfg_mgcp_rtp_priority_cmd);
 	install_element(MGCP_NODE, &cfg_mgcp_rtp_force_ptime_cmd);
 	install_element(MGCP_NODE, &cfg_mgcp_no_rtp_force_ptime_cmd);
 	install_element(MGCP_NODE, &cfg_mgcp_rtp_keepalive_cmd);