<p>neels has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/17502">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">add common/chapters/cs7-config<br><br>This will be used by the manuals of osmo-bsc, osmo-hnbgw, osmo-msc.<br><br>Related: OS#2767<br>Change-Id: Ia2508d4c7b0fef9cdc57e7e122799a480e340bf7<br>---<br>A common/chapters/cs7-config.adoc<br>1 file changed, 226 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/02/17502/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/common/chapters/cs7-config.adoc b/common/chapters/cs7-config.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..61efad9</span><br><span>--- /dev/null</span><br><span>+++ b/common/chapters/cs7-config.adoc</span><br><span>@@ -0,0 +1,226 @@</span><br><span style="color: hsl(120, 100%, 40%);">+[[cs7_config]]</span><br><span style="color: hsl(120, 100%, 40%);">+== Configure SCCP/M3UA</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+All CNI programs using SCCP/M3UA act as client to connect to an STP instance.</span><br><span style="color: hsl(120, 100%, 40%);">+The STP then routes SCCP messages between its clients, typically by</span><br><span style="color: hsl(120, 100%, 40%);">+point-codes.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+For example,</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- OsmoMSC contacts an OsmoSTP and subscribes its point-code 0.23.1;</span><br><span style="color: hsl(120, 100%, 40%);">+- then OsmoBSC also contacts the same OsmoSTP, subscribes with its own</span><br><span style="color: hsl(120, 100%, 40%);">+  point-code 1.23.3.</span><br><span style="color: hsl(120, 100%, 40%);">+- Using these established links, OsmoBSC initiates an A-interface link by</span><br><span style="color: hsl(120, 100%, 40%);">+  directing a BSSAP RESET message to the MSC's point-code 0.23.1,</span><br><span style="color: hsl(120, 100%, 40%);">+- and the RESET ACK response from the MSC is routed back to the BSC's</span><br><span style="color: hsl(120, 100%, 40%);">+  point-code 1.23.3.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The details of SCCP/M3UA are configured in the 'cs7' section of the VTY</span><br><span style="color: hsl(120, 100%, 40%);">+configuration.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Osmocom programs automatically configure missing SCCP/M3UA configuration, by</span><br><span style="color: hsl(120, 100%, 40%);">+assuming sane defaults.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If no explicit `routing-key` is set, it may be determined at runtime by</span><br><span style="color: hsl(120, 100%, 40%);">+negotiation with OsmoSTP -- see OsmoSTP manual chapter "Osmocom M3UA Routing</span><br><span style="color: hsl(120, 100%, 40%);">+Key Management Extensions", regarding config option `accept-asp-connections</span><br><span style="color: hsl(120, 100%, 40%);">+dynamic-permitted`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The complete active configuration of an Osmocom program can be obtained by the</span><br><span style="color: hsl(120, 100%, 40%);">+VTY command `show cs7 config` (the usual `show running-config` omits</span><br><span style="color: hsl(120, 100%, 40%);">+automatically configured items). Here is an example of OsmoMSC's default</span><br><span style="color: hsl(120, 100%, 40%);">+configuration:</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%);">+OsmoMSC> show cs7 config</span><br><span style="color: hsl(120, 100%, 40%);">+cs7 instance 0</span><br><span style="color: hsl(120, 100%, 40%);">+ point-code 0.23.1</span><br><span style="color: hsl(120, 100%, 40%);">+ asp asp-clnt-OsmoMSC-A-Iu 2905 0 m3ua</span><br><span style="color: hsl(120, 100%, 40%);">+  remote-ip 127.0.0.1</span><br><span style="color: hsl(120, 100%, 40%);">+  sctp-role client</span><br><span style="color: hsl(120, 100%, 40%);">+ as as-clnt-OsmoMSC-A-Iu m3ua</span><br><span style="color: hsl(120, 100%, 40%);">+  asp asp-clnt-OsmoMSC-A-Iu</span><br><span style="color: hsl(120, 100%, 40%);">+  routing-key 2 0.23.1</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%);">+At the time of writing, SCCP/M3UA links involving Osmocom program are:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- A-interface: OsmoBSC to OsmoMSC</span><br><span style="color: hsl(120, 100%, 40%);">+- IuCS-interface: OsmoHNBGW to OsmoMSC</span><br><span style="color: hsl(120, 100%, 40%);">+- IuPS-interface: OsmoHNBGW to OsmoSGSN</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Connect to STP Instance</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+By default, an STP instance is assumed to listen on the default M3UA port</span><br><span style="color: hsl(120, 100%, 40%);">+(2905) on the local host (127.0.0.1).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Establishing an SCCP/M3UA link towards a remote STP instance can be configured</span><br><span style="color: hsl(120, 100%, 40%);">+as:</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%);">+ asp my-asp 2905 0 m3ua</span><br><span style="color: hsl(120, 100%, 40%);">+  # IP address of the remote STP:</span><br><span style="color: hsl(120, 100%, 40%);">+  remote-ip 10.23.24.1</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%);">+Be aware that such an `asp` needs to be linked to an `as`, see <<as_and_asp>>.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[point_code_format]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== Point-Code Format</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Point-codes can be represented in various formats. For details, see OsmoSTP</span><br><span style="color: hsl(120, 100%, 40%);">+manual, chapter "Point Codes".</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+By default, Osmocom uses a point-code representation of 3.8.3, i.e. first digit</span><br><span style="color: hsl(120, 100%, 40%);">+of 3 bit, second digit of 8 bit, and third digit of 3 bit.</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%);">+ point-code format 3 8 3</span><br><span style="color: hsl(120, 100%, 40%);">+ point-code 0.23.1</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%);">+Often, point-codes are also represented as a single decimal number:</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%);">+ point-code format 24</span><br><span style="color: hsl(120, 100%, 40%);">+ point-code 185</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%);">+It is also possible to use a dash as delimiter.</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%);">+ point-code delimiter dash</span><br><span style="color: hsl(120, 100%, 40%);">+ point-code 0-23-1</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%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Local Point-Code</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Each CNI program on an SCCP/M3UA link typically has a local point-code,</span><br><span style="color: hsl(120, 100%, 40%);">+configurable 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%);">+cs7 instance 0</span><br><span style="color: hsl(120, 100%, 40%);">+ point-code 7.65.4</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%);">+If an explicit routing context is configured, this point-code is repeated in</span><br><span style="color: hsl(120, 100%, 40%);">+the `routing-key` configuration:</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%);">+ point-code 0.23.1</span><br><span style="color: hsl(120, 100%, 40%);">+ as my-as m3ua</span><br><span style="color: hsl(120, 100%, 40%);">+  routing-key 2 0.23.1</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%);">+See also <<point_code_format>>.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Remote Point-Code</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Programs establishing communication across SCCP links need a remote SCCP</span><br><span style="color: hsl(120, 100%, 40%);">+address, typically by point-code, to contact.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+For example,</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- OsmoBSC needs to know the MSC's point-code, to be able to establish the A-interface.</span><br><span style="color: hsl(120, 100%, 40%);">+- OsmoHNBGW needs to know the MSC's point-code, to be able to establish the IuCS-interface.</span><br><span style="color: hsl(120, 100%, 40%);">+- OsmoHNBGW needs to know the SGSN's point-code, to be able to establish the IuPS-interface.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+To maintain remote SCCP addresses, each `cs7` instance maintains an SCCP address book:</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 my-entry</span><br><span style="color: hsl(120, 100%, 40%);">+  point-code 1.23.1</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 address book entry on its own has no effect. It is typically referenced by</span><br><span style="color: hsl(120, 100%, 40%);">+specific configuration items depending on the individual programs.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Examples:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- An OsmoBSC configures the MSC's remote SCCP address:</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 my-remote-msc</span><br><span style="color: hsl(120, 100%, 40%);">+  point-code 1.23.1</span><br><span style="color: hsl(120, 100%, 40%);">+msc 0</span><br><span style="color: hsl(120, 100%, 40%);">+ msc-addr my-remote-msc</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%);">+- An HNBGW configures both the remote MSC's and SGSN's SCCP addresses:</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 my-msc</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-sgsn</span><br><span style="color: hsl(120, 100%, 40%);">+  point-code 0.23.2</span><br><span style="color: hsl(120, 100%, 40%);">+hnbgw</span><br><span style="color: hsl(120, 100%, 40%);">+ iucs</span><br><span style="color: hsl(120, 100%, 40%);">+  remote-addr my-msc</span><br><span style="color: hsl(120, 100%, 40%);">+ iups</span><br><span style="color: hsl(120, 100%, 40%);">+  remote-addr my-sgsn</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%);">+Besides a point-code, an SCCP address can have several routing indicators:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- PC: routing by point-code is the default for Osmocom.</span><br><span style="color: hsl(120, 100%, 40%);">+- GT: routing by Global Title is configurable by `routing-indicator GT`.</span><br><span style="color: hsl(120, 100%, 40%);">+- IP: routing by IP address is configurable by `routing-indicator IP`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In OsmoSTP, only routing by point-code is currently implemented.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[as_and_asp]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== AS and ASP</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Each CNI program needs an Application Server `as` and Application Server</span><br><span style="color: hsl(120, 100%, 40%);">+Process `asp` configured on its `cs7` to be able to communicate on SCCP/M3UA.</span><br><span style="color: hsl(120, 100%, 40%);">+An `asp` is part of an `as`. For details, see the OsmoSTP manual, chapters</span><br><span style="color: hsl(120, 100%, 40%);">+"Application Server" and "Application Server Process".</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In Osmocom's `cs7`, any amount of `as` and `asp` can be configured by name, and</span><br><span style="color: hsl(120, 100%, 40%);">+an `as` references the `asp` belonging to it by their names.  In typical usage,</span><br><span style="color: hsl(120, 100%, 40%);">+an Osmocom program will have exactly one `as` with one `asp`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+For 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%);">+cs7 instance 0</span><br><span style="color: hsl(120, 100%, 40%);">+ asp my-asp 2905 0 m3ua</span><br><span style="color: hsl(120, 100%, 40%);">+  # where to reach the STP:</span><br><span style="color: hsl(120, 100%, 40%);">+  remote-ip 127.0.0.1</span><br><span style="color: hsl(120, 100%, 40%);">+  sctp-role client</span><br><span style="color: hsl(120, 100%, 40%);">+ as my-as m3ua</span><br><span style="color: hsl(120, 100%, 40%);">+  asp my-asp</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%);">+It is possible to configure only an `as` or only an `asp` explicitly -- a</span><br><span style="color: hsl(120, 100%, 40%);">+missing entity will be configured automatically. However, be aware that when</span><br><span style="color: hsl(120, 100%, 40%);">+both are configured manually, they need to be linked by name. For example, the</span><br><span style="color: hsl(120, 100%, 40%);">+following configuration will *fail*, because `as` and `asp` are not linked:</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%);">+ asp my-asp 2905 0 m3ua</span><br><span style="color: hsl(120, 100%, 40%);">+  remote-ip 127.0.0.1</span><br><span style="color: hsl(120, 100%, 40%);">+ as my-as m3ua</span><br><span style="color: hsl(120, 100%, 40%);">+  routing-key 2 0.23.1</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 *fix* above config, link the `asp` to an `as` by adding `asp my-asp`:</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%);">+ asp my-asp 2905 0 m3ua</span><br><span style="color: hsl(120, 100%, 40%);">+  remote-ip 127.0.0.1</span><br><span style="color: hsl(120, 100%, 40%);">+ as my-as m3ua</span><br><span style="color: hsl(120, 100%, 40%);">+  asp my-asp</span><br><span style="color: hsl(120, 100%, 40%);">+  routing-key 2 0.23.1</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/17502">change 17502</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-gsm-manuals/+/17502"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: osmo-gsm-manuals </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: Ia2508d4c7b0fef9cdc57e7e122799a480e340bf7 </div>
<div style="display:none"> Gerrit-Change-Number: 17502 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: neels <nhofmeyr@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>