[M] Change in osmo-gsm-manuals[master]: mgwpool: Document keepalive feature

pespin has submitted this change. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/33310 ) Change subject: mgwpool: Document keepalive feature ...................................................................... mgwpool: Document keepalive feature Related: SYS#6481 Change-Id: I2cb4e2098b71b386278eb6026271a6d786a34c2a --- M common/chapters/mgwpool.adoc 1 file changed, 77 insertions(+), 22 deletions(-) Approvals: Jenkins Builder: Verified fixeria: Looks good to me, but someone else must approve laforge: Looks good to me, approved diff --git a/common/chapters/mgwpool.adoc b/common/chapters/mgwpool.adoc index c4cf28a..afb0d2b 100644 --- a/common/chapters/mgwpool.adoc +++ b/common/chapters/mgwpool.adoc @@ -8,7 +8,7 @@ scale-out to multiple cores on a single host. The load distribution is managed in such a way that when a new call is placed, -the pool will automatically assign the call to the MGW with the lowest load. +the pool will automatically assign the call to the available MGW with the lowest load. MGW pooling is recommended for larger RAN or CN installations. For small networks and lab installations the classic method with one MGW per {program-name} offers @@ -72,11 +72,11 @@ OsmoBSC> show mgw-pool % MGW-Pool: % MGW 0:media-gw-0 -% mgcp-client: connected +% MGCP link: connected,UP % service: unblocked % ongoing calls: 1 % MGW 1:media-gw-1 -% mgcp-client: connected +% MGCP link: connected,UP % service: unblocked % ongoing calls: 0 ---- @@ -96,6 +96,7 @@ OsmoBSC(config)# network OsmoBSC(config-net)# mgw 2 OsmoBSC(config-mgw)# ? + keepalive Monitor if the MGCP link against MGW is still usable local-ip local bind to connect to MGW from local-port local port to connect to MGW from remote-ip remote IP address to reach the MGW at @@ -110,15 +111,15 @@ ---- % MGW-Pool: % MGW 0:media-gw-0 -% mgcp-client: connected +% MGCP link: connected,UP % service: unblocked % ongoing calls: 2 % MGW 1:media-gw-1 -% mgcp-client: connected +% MGCP link: connected,UP % service: unblocked % ongoing calls: 3 % MGW 2:mgw <1> -% mgcp-client: disconnected +% MGCP link: disconnected,DOWN % service: unblocked % ongoing calls: 0 ---- @@ -146,33 +147,77 @@ OsmoBSC# show mgw-pool % MGW-Pool: % MGW 0:media-gw-0 -% mgcp-client: connected +% MGCP link: connected,UP % service: unblocked % ongoing calls: 2 % MGW 1:media-gw-1 -% mgcp-client: connected +% MGCP link: connected,UP % service: unblocked % ongoing calls: 3 % MGW 2:mgw -% mgcp-client: connected +% MGCP link: connected,UP % service: unblocked % ongoing calls: 0 ---- It should be noted that MGCP a protocol is used via UDP, the connect only -happens locally to forward the UDP datagrams properly. Also (unless a reset -endpoint is configured like in the example config above) there will be no -immediate interaction with the MGW. However, the log should at least confirm -the connect worked and the MGCP client has been created successfully. +happens locally to forward the UDP datagrams properly (state printed in +`mgcp-client: (dis)connected` above). Also (unless a reset endpoint is +configured like in the example config above) there will be no immediate +interaction with the MGW. However, the log should at least confirm the connect +worked and the MGCP client has been created successfully. ---- Mon Aug 2 17:15:00 2021 DLMGCP mgcp_client.c:788 MGCP client: using endpoint domain '@mgw' Mon Aug 2 17:15:00 2021 DLMGCP mgcp_client.c:908 MGCP GW connection: r=127.0.0.1:2427<->l=127.0.0.1:2727 ---- -It is strongly advised to check the activity on the related MGW and to follow -the log in order to see that the communication between {program-name} and the MGW is -working correctly. +For that reason, it is strongly advised to enable the `keepalive` feature in +{program-name} to schedule periodical MGCP queries against the MGW, in order to +make sure it is reachable (the state `MGCP link: UP|DOWN` printed above). See +section <<mgw_pooling_keepalive>> below for more information. + +[[mgw_pooling_keepalive]] +==== Monitor MGCP link (keepalive) / MGCP-Client + +The `keepalive` feature in {program-name} allows scheduling periodical queries +on the MGCP layer in order to make sure it is reachable and hence obtain +information on the state of the MGCP link. This is in turn used by the MGW Pool +when picking an MGW from the pool: MGWs whose link is considered to be DOWN are +skipped. + +The feature consists of: +- A `keepalive request-interval` which will trigger a transmission of an MGCP +AuditEndpoint command targeting endpoint with name `keepalive request-endpoint`. +This interval is updated every time any message is transmitted in the MGCP link, +meaning the MGCP AuditEndpoint message is only triggered if no message has been +transmitted since `keepalive request-interval` seconds ago. +- A `keepalive timeout` which upon triggering (because no message was received +over that amount of time) will then consider the MGW to be non-reachable (link +DOWN). + +The `keepalive` parameters are to be preferrably configured so that +`"keepalive request-interval" * 2 < "keepalive timeout"`. + +Example VTY configuration of `keepalive` feature in {program-name}: +---- + mgw 0 + ... + keepalive request-interval 20 <1> + keepalive request-endpoint null <2> + keepalive timeout 50 <3> +---- + +<1> Transmit an MGCP AuditEndpoint message to the MGW if no message has been +sent to it over last 20 seconds +<2> The MGCP AuditEndpoint targets the `null` endpoint. This is a special +endpoint available at OsmoMGW for those purposes, but any available endpoint can +be configured and used instead. +<3> Consider the MGCP link to be DOWN if no message is received from the MGW +over the last 50 seconds + +NOTE: The `keepalive` feature is disabled by default, and must be explicitly +configured in order to enable it. [[mgw_pooling_blocking]] ==== Blocking an MGW / MGCP-Client @@ -188,15 +233,15 @@ OsmoBSC# show mgw-pool % MGW-Pool: % MGW 0:media-gw-0 -% mgcp-client: connected +% MGCP link: connected,UP % service: unblocked % ongoing calls: 11 % MGW 1:media-gw-1 -% mgcp-client: connected +% MGCP link: connected,UP % service: unblocked % ongoing calls: 12 % MGW 2:mgw -% mgcp-client: connected +% MGCP link: connected,UP % service: blocked % ongoing calls: 10 ---- @@ -208,15 +253,15 @@ OsmoBSC# show mgw-pool % MGW-Pool: % MGW 0:media-gw-0 -% mgcp-client: connected +% MGCP link: connected,UP % service: unblocked % ongoing calls: 15 % MGW 1:media-gw-1 -% mgcp-client: connected +% MGCP link: connected,UP % service: unblocked % ongoing calls: 14 % MGW 2:mgw -% mgcp-client: connected +% MGCP link: connected,UP % service: blocked % ongoing calls: 0 ---- -- To view, visit https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/33310 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: I2cb4e2098b71b386278eb6026271a6d786a34c2a Gerrit-Change-Number: 33310 Gerrit-PatchSet: 5 Gerrit-Owner: pespin &lt;pespin(a)sysmocom.de&gt; Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: dexter &lt;pmaier(a)sysmocom.de&gt; Gerrit-Reviewer: fixeria &lt;vyanitskiy(a)sysmocom.de&gt; Gerrit-Reviewer: laforge &lt;laforge(a)osmocom.org&gt; Gerrit-Reviewer: osmith &lt;osmith(a)sysmocom.de&gt; Gerrit-Reviewer: pespin &lt;pespin(a)sysmocom.de&gt; Gerrit-MessageType: merged