diff options
author | Pau Espin Pedrol <pespin@sysmocom.de> | 2022-10-20 16:16:48 +0200 |
---|---|---|
committer | Pau Espin Pedrol <pespin@sysmocom.de> | 2022-10-20 16:16:51 +0200 |
commit | fa3260fcf94825d7205dac527f0fd695f1a90412 (patch) | |
tree | 3423898db3948bcf1a720e2c7b9b0465551b1853 | |
parent | 2e38ec231eac342ef775fcdc1327022391779d23 (diff) |
doc: Use mgwpool.adoc from osmo-gsm-manuals.git
The adoc file has been moved to osmo-gsm-manuals.git so that it can be
included by other apps supporting MGW pooling from libosmo-mgcp-client,
such as osmo-msc and osmo-hnbgw.
Related: SYS#5987
Depends: osmo-gsm-manuals.git Change-Id Ieda0d4bfe6fc90da6e19c791d8ec2da89427ba3b
Change-Id: Icaee61905fbefe4632b562603fce393b70a114b1
-rw-r--r-- | doc/manuals/chapters/mgwpool.adoc | 239 | ||||
-rw-r--r-- | doc/manuals/osmobsc-usermanual.adoc | 2 |
2 files changed, 1 insertions, 240 deletions
diff --git a/doc/manuals/chapters/mgwpool.adoc b/doc/manuals/chapters/mgwpool.adoc deleted file mode 100644 index c42915968..000000000 --- a/doc/manuals/chapters/mgwpool.adoc +++ /dev/null @@ -1,239 +0,0 @@ -[[mgw_pooling]] -== MGW Pooling - -{program-name} is able to use a pool of media gateway (MGW) instances. -The aim of MGW pooling is to evenly distribute the RTP voice stream load across -multiple MGW instances. This can help to scale out over multiple VMs or physical -machines. Until osmo-mgw includes multithreading support, it may also be used to -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. - -MGW pooling is recommended for larger RAN or CN installations. For small networks -and lab installations the classic method with one MGW per BSC offers sufficient -performance. - -=== MGW pool VTY configuration - -In {program-name} the MGW is controlled via an MGCP-Client. The VTY commands to -configure the MGCP-Client are part of the several 'mgw' nodes, one per -MGCP-Client to set up. - -To setup an MGW pool, the user must first install multiple OsmoMGW instances, so -that they won’t interfere with each other. This can be done using different -local host IP addresses or different ports. When OsmoMGW is installed from -packages, the systemd configuration may also require adjustment. - -By default, MGCP-Client will use whatever source IP address is resolved by the -kernel routing subsystem, and will also ask the kernel to pick a free UDP port. - -Example configuration with two MGCP-Client instances in a pool: ----- - mgw 0 - description media-gw-0 <2> - remote-ip 127.0.0.1 - remote-port 2432 - local-ip 127.0.0.1 - local-port 2431 - endpoint-domain mgw0 <1> - mgw 1 - description media-gw-1 <2> - remote-ip 127.0.0.1 - remote-port 2430 - local-ip 127.0.0.1 - local-port 2429 - endpoint-domain mgw1 <1> ----- - -<1> When working with multiple MGW / MGCP-Client instances, the domain name for -each MGW should be different. Otherwise it won't be possible to distinguish the -endpoint names in the log. It should also be noted that the domain name must -match the configuration of the related OsmoMGW instance. - -<2> It is also possible to assign a descriptive name to each MGW instance. The -MGCP client specific log lines will then use this name as logging context. If -no description is set, the domain name will be used. - -=== MGW pool management - -The MNGW pool is fully runtime-manageable. The only limitation -is that an MGCP-Client can not be restarted or removed as long as it is serving -calls (see also: <<mgw_pooling_blocking>>). - -==== MGW pool status - -The VTY implements a 'show mgw-pool' command that lists the currently configured -MGW pool members, their status and call utilization. The following snippet shows -an output example run on OsmoBSC, but it should be also available on other -applications supporting the MGW pooling VTY featues: - ----- -OsmoBSC> show mgw-pool -% MGW-Pool: -% MGW 0:media-gw-0 -% mgcp-client: connected -% service: unblocked -% ongoing calls: 1 -% MGW 1:media-gw-1 -% mgcp-client: connected -% service: unblocked -% ongoing calls: 0 ----- - -==== Adding an MGW / MGCP-Client to the MGW pool - -To add a new MGCP-Client to the pool, the 'mgw' node is used. Like with the -'bts' or the 'msc' node a reference number is used that usually starts at 0. -However it is still possible to assign any number from 0-255. The enumeration -also may contain gaps. The following snippet shows an output example run on -OsmoBSC, but it should be also available on other applications supporting the -MGW pooling VTY featues: - ----- -OsmoBSC> enable -OsmoBSC# configure terminal -OsmoBSC(config)# network -OsmoBSC(config-net)# mgw 2 -OsmoBSC(config-mgw)# ? - 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 - remote-port remote port to reach the MGW at - endpoint-domain Set the domain name to send in MGCP messages, e.g. the part 'foo' in 'rtpbridge/*@foo'. - reset-endpoint Add an endpoint name that should be reset (DLCX) on connect to the reset-endpoint list,e.g. 'rtpbridge/*' ----- - -The newly added MGW will immediately appear in the mgw-pool list but it won't -be used until its configuration finished by reconnecting it. - ----- -% MGW-Pool: -% MGW 0:media-gw-0 -% mgcp-client: connected -% service: unblocked -% ongoing calls: 2 -% MGW 1:media-gw-1 -% mgcp-client: connected -% service: unblocked -% ongoing calls: 3 -% MGW 2:mgw <1> -% mgcp-client: disconnected -% service: unblocked -% ongoing calls: 0 ----- - -<1> In this example a description is not set yet, so the domain name ("mgw") -is displayed. - -==== Reconnecting an MGW / MGCP-Client - -It may become necessary to reconnect an MGCP-Client. This is the case when the -VTY configuration was changed at runtime. In order to make the changes effective -the MGW configuration must be reloaded by reconnecting the MGW connection. Also -newly created MGW instances require a reconnect once their configuration is -done. - -To reconnect an MGCP-Client use the 'reconnect' VTY command: ----- -OsmoBSC# mgw 2 reconnect ----- - -The mgcp-client status should immediately change to 'connected'. The MGW is now -ready to be used for new calls. - ----- -OsmoBSC# show mgw-pool -% MGW-Pool: -% MGW 0:media-gw-0 -% mgcp-client: connected -% service: unblocked -% ongoing calls: 2 -% MGW 1:media-gw-1 -% mgcp-client: connected -% service: unblocked -% ongoing calls: 3 -% MGW 2:mgw -% mgcp-client: connected -% 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 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. - -[[mgw_pooling_blocking]] -==== Blocking an MGW / MGCP-Client - -If it becomes apparent that an MGCP-Client must be restarted or removed from -the config (maintenance) the operator can put that MGCP-Client into a blocked -mode. A blocked MGCP-Client will still serve the ongoing calls but it will not -be picked for the assignment of new calls. - -To block an MGCP-Client use the 'block' VTY command: ----- -OsmoBSC# mgw 2 block -OsmoBSC# show mgw-pool -% MGW-Pool: -% MGW 0:media-gw-0 -% mgcp-client: connected -% service: unblocked -% ongoing calls: 11 -% MGW 1:media-gw-1 -% mgcp-client: connected -% service: unblocked -% ongoing calls: 12 -% MGW 2:mgw -% mgcp-client: connected -% service: blocked -% ongoing calls: 10 ----- - -When the number of ongoing calls has tapered off, the MGW / MGCP-Client can be -restarted or removed if necessary. - ----- -OsmoBSC# show mgw-pool -% MGW-Pool: -% MGW 0:media-gw-0 -% mgcp-client: connected -% service: unblocked -% ongoing calls: 15 -% MGW 1:media-gw-1 -% mgcp-client: connected -% service: unblocked -% ongoing calls: 14 -% MGW 2:mgw -% mgcp-client: connected -% service: blocked -% ongoing calls: 0 ----- - -If the blockade should be reverted, the 'unblock' VTY command can be used in -the same way to remove the blockade. (Reconnecting will not remove the -blockade.) - -==== Removing an MGW / MGCP-Client - -An MGCP-Client is removed from the pool using the 'no mgw' command from the -configure terminal. The MGCP-Client instance will automatically be terminated -and the related resources are freed. The only requirement is that there are no -ongoing calls on the selected instance. - ----- -OsmoBSC# configure terminal -OsmoBSC(config)# network -OsmoBSC(config-net)# no mgw 2 ----- diff --git a/doc/manuals/osmobsc-usermanual.adoc b/doc/manuals/osmobsc-usermanual.adoc index f83552584..2e77e1b5f 100644 --- a/doc/manuals/osmobsc-usermanual.adoc +++ b/doc/manuals/osmobsc-usermanual.adoc @@ -36,7 +36,7 @@ include::{srcdir}/chapters/smscb.adoc[] include::{srcdir}/chapters/mscpool.adoc[] -include::{srcdir}/chapters/mgwpool.adoc[] +include::./common/chapters/mgwpool.adoc[] include::{srcdir}/chapters/smlc.adoc[] |