<p>laforge <strong>submitted</strong> this change.</p><p><a href="https://gerrit.osmocom.org/c/osmo-bsc/+/18779">View Change</a></p><div style="white-space:pre-wrap">Approvals:
Jenkins Builder: Verified
laforge: Looks good to me, but someone else must approve
neels: Looks good to me, approved
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">mscpool: add user manual chapter<br><br>Change-Id: Ia60afc8a91189c9de0d8e8065781ed463bf18d7e<br>---<br>A doc/manuals/chapters/mscpool.adoc<br>M doc/manuals/osmobsc-usermanual.adoc<br>2 files changed, 215 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/doc/manuals/chapters/mscpool.adoc b/doc/manuals/chapters/mscpool.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..923a088</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/mscpool.adoc</span><br><span>@@ -0,0 +1,213 @@</span><br><span style="color: hsl(120, 100%, 40%);">+== MSC Pooling</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+MSC pooling is described in 3GPP TS 23.236 <<3gpp-ts-23-236>>, and is supported</span><br><span style="color: hsl(120, 100%, 40%);">+by OsmoBSC since mid 2020.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The aim of MSC pooling is to distribute load from a BSC across multiple MSCs,</span><br><span style="color: hsl(120, 100%, 40%);">+which are equivalent and redundant infrastructure for the same core network.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The main mechanism for MSC pooling is the TMSI identity, which an MSC hands out</span><br><span style="color: hsl(120, 100%, 40%);">+to its attached subscribers. Typically 10 bits of the TMSI are designated as a</span><br><span style="color: hsl(120, 100%, 40%);">+Network Resource Identifier (NRI) that identifies the originating MSC, and</span><br><span style="color: hsl(120, 100%, 40%);">+allows OsmoBSC to direct a subscriber back to the same MSC instance that</span><br><span style="color: hsl(120, 100%, 40%);">+previously negotiated the IMSI Attach procedure. Typically, the full NRI value</span><br><span style="color: hsl(120, 100%, 40%);">+range available is divided into N even ranges, where each MSC is assigned one</span><br><span style="color: hsl(120, 100%, 40%);">+NRI range.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Subscribers attaching without a TMSI identity, or those with unknown NRI value,</span><br><span style="color: hsl(120, 100%, 40%);">+are evenly distributed across MSC instances. OsmoBSC uses a round-robin</span><br><span style="color: hsl(120, 100%, 40%);">+approach to distribute load across all connected MSCs.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+A Paging Response from a subscriber is always returned back to whichever MSC</span><br><span style="color: hsl(120, 100%, 40%);">+initiated the Paging, regardless of the Mobile Identity used.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Finally, a NULL-NRI is a special NRI value that indicates that the MSC wishes</span><br><span style="color: hsl(120, 100%, 40%);">+to offload this subscriber to a different MSC. A NULL-NRI is an arbitrary NRI</span><br><span style="color: hsl(120, 100%, 40%);">+value that is chosen distinctly for each PLMN served by a BSC, so that a</span><br><span style="color: hsl(120, 100%, 40%);">+subscriber can be reassigned within that PLMN. Upon (periodic) Location</span><br><span style="color: hsl(120, 100%, 40%);">+Updating, an offloading MSC hands out a NULL-NRI value in the assigned TMSI,</span><br><span style="color: hsl(120, 100%, 40%);">+along with a non-broadcast LAI. The subscriber will notice the LAI mismatch,</span><br><span style="color: hsl(120, 100%, 40%);">+and immediately re-attempt the attach using the TMSI containing the NULL-NRI.</span><br><span style="color: hsl(120, 100%, 40%);">+The BSC recognises the NULL-NRI and redirects the subscriber to one of the</span><br><span style="color: hsl(120, 100%, 40%);">+other MSCs. A prerequisite for this to work well is that the particular MSC is</span><br><span style="color: hsl(120, 100%, 40%);">+previously marked as not accepting new subscribers, in the BSC's configuration.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The mechanisms described above make up the NAS node selection function</span><br><span style="color: hsl(120, 100%, 40%);">+implemented in the BSC.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+3GPP TS 23.236 also defines that an offloading MSC hands subscriber information</span><br><span style="color: hsl(120, 100%, 40%);">+to the newly assigned MSC, which takes place outside the scope of the BSC.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Configuring MSC Pooling</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The NRI ranges assigned to each MSC must match in the BSC and the MSC</span><br><span style="color: hsl(120, 100%, 40%);">+configuration. If MSC and BSC had inconsistent NRI value ranges configured,</span><br><span style="color: hsl(120, 100%, 40%);">+attached subscribers would be redirected MSC instances that did not perform the</span><br><span style="color: hsl(120, 100%, 40%);">+attach, possibly rendering the core network unusable.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Connecting Multiple MSCs</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The `cs7 instance` configuration defines the SCCP addresses to reach the MSCs</span><br><span style="color: hsl(120, 100%, 40%);">+at. In addition, each MSC is configured by its own `msc` section in the</span><br><span style="color: hsl(120, 100%, 40%);">+configuration. An example osmo-bsc.cfg serving three MSCs:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+cs7 instance 0</span><br><span style="color: hsl(120, 100%, 40%);">+ # SCCP address book entries for the three MSCs</span><br><span style="color: hsl(120, 100%, 40%);">+ sccp-address my-msc-0</span><br><span style="color: hsl(120, 100%, 40%);">+ point-code 0.23.0</span><br><span style="color: hsl(120, 100%, 40%);">+ sccp-address my-msc-1</span><br><span style="color: hsl(120, 100%, 40%);">+ point-code 0.23.1</span><br><span style="color: hsl(120, 100%, 40%);">+ sccp-address my-msc-2</span><br><span style="color: hsl(120, 100%, 40%);">+ point-code 0.23.2</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+# assign each MSC configuration its remote SCCP address</span><br><span style="color: hsl(120, 100%, 40%);">+msc 0</span><br><span style="color: hsl(120, 100%, 40%);">+ msc-addr my-msc-0</span><br><span style="color: hsl(120, 100%, 40%);">+msc 1</span><br><span style="color: hsl(120, 100%, 40%);">+ msc-addr my-msc-1</span><br><span style="color: hsl(120, 100%, 40%);">+msc 2</span><br><span style="color: hsl(120, 100%, 40%);">+ msc-addr my-msc-2</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+# configure NRI value ranges</span><br><span style="color: hsl(120, 100%, 40%);">+network</span><br><span style="color: hsl(120, 100%, 40%);">+ nri bitlen 10</span><br><span style="color: hsl(120, 100%, 40%);">+ nri null add 0</span><br><span style="color: hsl(120, 100%, 40%);">+msc 0</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 1 341</span><br><span style="color: hsl(120, 100%, 40%);">+msc 1</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 342 682</span><br><span style="color: hsl(120, 100%, 40%);">+msc 2</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 683 1023</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== NRI Value Bit Length</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In OsmoBSC, the NRI value's bit length is freely configurable from 1 to 15</span><br><span style="color: hsl(120, 100%, 40%);">+bits. 3GPP TS 23.236 suggests a typical bit length of 10, which is OsmoBSC's</span><br><span style="color: hsl(120, 100%, 40%);">+default. The NRI bit length must be identical across the entire MSC pool.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Change the NRI value bit length in OsmoBSC's VTY configuration like this:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+network</span><br><span style="color: hsl(120, 100%, 40%);">+ nri bitlen 10</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In the TMSI bits, regardless of the NRI bit length, the NRI value always starts</span><br><span style="color: hsl(120, 100%, 40%);">+just after the most significant octet of a TMSI (most significant bit at TMSI's</span><br><span style="color: hsl(120, 100%, 40%);">+bit 23).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== NULL-NRI</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Since OsmoBSC supports serving only one PLMN, NULL-NRI are configured globally.</span><br><span style="color: hsl(120, 100%, 40%);">+Even though 3GPP TS 23.236 indicates that there is a single NULL-NRI per PLMN,</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoBSC allows configuring multiple NULL-NRI values.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+network</span><br><span style="color: hsl(120, 100%, 40%);">+ nri null add 0</span><br><span style="color: hsl(120, 100%, 40%);">+ nri null add 423</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Assigning NRI Ranges to MSCs</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Each MSC configured in OsmoBSC must be assigned a distinct NRI value range.</span><br><span style="color: hsl(120, 100%, 40%);">+Overlapping NRI value ranges will cause failure to serve subscribers.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+NRI values are typically configured in ranges, here dividing a 10bit range</span><br><span style="color: hsl(120, 100%, 40%);">+(0..1023) into three equal ranges, while leaving 0 available to be configured</span><br><span style="color: hsl(120, 100%, 40%);">+as NULL-NRI:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+msc 0</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 1 341</span><br><span style="color: hsl(120, 100%, 40%);">+msc 1</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 342 684</span><br><span style="color: hsl(120, 100%, 40%);">+msc 2</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 685 1023</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+NRI can also be assigned in single values:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+msc 0</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 23</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Ranges can be constructed arbitrarily by a sequence of `add` and `del`</span><br><span style="color: hsl(120, 100%, 40%);">+configurations, here a contrived example:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+msc 0</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 0 342</span><br><span style="color: hsl(120, 100%, 40%);">+ nri del 23</span><br><span style="color: hsl(120, 100%, 40%);">+ nri del 42 235</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 1000 1023</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+To view the current NRI config in a running OsmoBSC instance, use the</span><br><span style="color: hsl(120, 100%, 40%);">+`show nri` command, here showing the result of the contrived example:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoBSC(config-msc)# show nri</span><br><span style="color: hsl(120, 100%, 40%);">+msc 0</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 0 22</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 24 41</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 236 342</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 1000 1023</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On the VIEW and ENABLE VTY nodes, `show nri` shows all MSCs:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoBSC> show nri</span><br><span style="color: hsl(120, 100%, 40%);">+msc 0</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 1 341</span><br><span style="color: hsl(120, 100%, 40%);">+msc 1</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 342 684</span><br><span style="color: hsl(120, 100%, 40%);">+msc 2</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 685 1023</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+When configuring overlapping NRI value ranges across MSCs, the telnet VTY warns</span><br><span style="color: hsl(120, 100%, 40%);">+about it, and starting OsmoBSC with such a configuration will fail:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+msc 0</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 1 511</span><br><span style="color: hsl(120, 100%, 40%);">+msc 1</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 512 1023</span><br><span style="color: hsl(120, 100%, 40%);">+msc 2</span><br><span style="color: hsl(120, 100%, 40%);">+ nri add 500 555</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This results in:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+$ osmo-bsc</span><br><span style="color: hsl(120, 100%, 40%);">+DMSC ERROR msc 2: NRI range [500..555] overlaps between msc 2 and msc 0. For overlaps, msc 0 has higher priority than msc 2</span><br><span style="color: hsl(120, 100%, 40%);">+DMSC ERROR msc 2: NRI range [500..555] overlaps between msc 2 and msc 1. For overlaps, msc 1 has higher priority than msc 2</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== MSC Offloading</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+To effectively offload a particular MSC, it must be marked as no longer taking</span><br><span style="color: hsl(120, 100%, 40%);">+new subscribers in OsmoBSC. This can be achieved in the telnet VTY by:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+msc 0</span><br><span style="color: hsl(120, 100%, 40%);">+ no allow-attach</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This MSC will, as long as it is connected, continue to serve subscribers</span><br><span style="color: hsl(120, 100%, 40%);">+already attached to it: those that yield an NRI matching this MSC, and those</span><br><span style="color: hsl(120, 100%, 40%);">+that are being paged by this MSC. But OsmoBSC will no longer direct new</span><br><span style="color: hsl(120, 100%, 40%);">+subscribers to this MSC.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+To re-enable an MSC for attaching new subscribers:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+msc 0</span><br><span style="color: hsl(120, 100%, 40%);">+ allow-attach</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span>diff --git a/doc/manuals/osmobsc-usermanual.adoc b/doc/manuals/osmobsc-usermanual.adoc</span><br><span>index c518c96..862c8f9 100644</span><br><span>--- a/doc/manuals/osmobsc-usermanual.adoc</span><br><span>+++ b/doc/manuals/osmobsc-usermanual.adoc</span><br><span>@@ -28,6 +28,8 @@</span><br><span> </span><br><span> include::{srcdir}/chapters/smscb.adoc[]</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/mscpool.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> include::./common/chapters/counters-overview.adoc[]</span><br><span> </span><br><span> include::{srcdir}/chapters/counters.adoc[]</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-bsc/+/18779">change 18779</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-bsc/+/18779"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: osmo-bsc </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: Ia60afc8a91189c9de0d8e8065781ed463bf18d7e </div>
<div style="display:none"> Gerrit-Change-Number: 18779 </div>
<div style="display:none"> Gerrit-PatchSet: 7 </div>
<div style="display:none"> Gerrit-Owner: neels <nhofmeyr@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: Jenkins Builder </div>
<div style="display:none"> Gerrit-Reviewer: daniel <dwillmann@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: dexter <pmaier@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-Reviewer: neels <nhofmeyr@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: pespin <pespin@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>