[[cs7_config]]
== Configure SCCP/M3UA

All CNI programs using SCCP/M3UA act as M3UA ASP role and SCTP client,
expecting to connect to a Signalling Gateway (STP/SG) implementing the M3UA
SG role as SCTP server. The STP/SG then routes M3UA messages between its
ASPs, typically by point-codes.

For an introduction about SCCP/M3UA/SS7/SIGTRAN technology, please see
the chapter _Signaling Networks: SS7 and SIGTRAN_ in the OsmoSTP user
manual.

In an all-Osmocom CNI, the typical simple/minimal usage is:

- OsmoSTP acts as the STP/SG (server role) and routes between the ASP,
- All other Osmocom CNI programs act as SCTP client and provide ASP
  implementations.

For example, in an all-Osmocom minimal setup,

- OsmoMSC contacts an OsmoSTP and subscribes its point-code 0.23.1;
- then OsmoBSC also contacts the same OsmoSTP, subscribes with its own
  point-code 1.23.3.
- Using these established links, OsmoBSC initiates an A-interface link by
  directing a BSSAP RESET message to the MSC's point-code 0.23.1,
- and the RESET ACK response from the MSC is routed back to the BSC's
  point-code 1.23.3.

The details of SCCP/M3UA are configured in the 'cs7' section of the VTY
configuration.

Osmocom programs automatically configure missing SCCP/M3UA configuration, by
assuming sane defaults for small/minimal all-Osmocom installations, which may
not be what you want in larger networks integrating with non-Osmocom core
network elements.

If no explicit `routing-key` is set, it may be determined at runtime by
negotiation with OsmoSTP -- see OsmoSTP manual chapter "Osmocom M3UA Routing
Key Management Extensions", regarding config option `accept-asp-connections
dynamic-permitted`.

The complete active configuration of an Osmocom program can be obtained by the
VTY command `show cs7 config` (the usual `show running-config` omits
automatically configured items). Here is an example of OsmoMSC's default
configuration:

----
OsmoMSC> show cs7 config
cs7 instance 0
 point-code 0.23.1
 asp asp-clnt-OsmoMSC-A-Iu 2905 0 m3ua
  remote-ip 127.0.0.1
  role asp
  sctp-role client
 as as-clnt-OsmoMSC-A-Iu m3ua
  asp asp-clnt-OsmoMSC-A-Iu
  routing-key 2 0.23.1
----

At the time of writing, SCCP/M3UA links involving Osmocom program are:

- A-interface: OsmoBSC to OsmoMSC
- IuCS-interface: OsmoHNBGW to OsmoMSC
- IuPS-interface: OsmoHNBGW to OsmoSGSN
- Lb-interface: OsmoSMLC to OsmoBSC

On the SCTP/IP level, those connections are actually all established from
the respective program (BSC, MSC, HNBGW, SGSN, SMLC) to OsmoSTP.  Hence,
if you look at the traffic in a protocol analyzer like wireshark, at IP
level, you will see each of those programs establishing an SCTP
association from a random local IP to the well-known SCTP port for M3UA
(2905) at the OsmoSTP.

Those star-connections for M3UA/SCTP then are the transport network for
higher level protocols like SCCP.  OsmoSTP then acts as central router
for SCCP-level message exchange between all the connected programs.

=== Connect to STP Instance

Establishing an SCCP/M3UA link towards a remote STP instance can be configured
as:

----
cs7 instance 0
 asp my-asp 2905 0 m3ua
  # IP address of the remote STP:
  remote-ip 10.23.24.1
  # optional: local bind to a specific IP
  local-ip 10.9.8.7
  role asp
  sctp-role client
----

Be aware that such an `asp` needs to be linked to an `as`, see <<as_and_asp>>.

By default, an STP instance is assumed to listen on the default M3UA port
(2905) on the local host. That means in general `127.0.0.1` will be used as
default remote SCTP address, and `::1` will be added to the SCTP association if
IPv6 support is available on the system.

NOTE: OsmoSTP listens by default on `::` if IPv6 is enabled on the system,
and on `0.0.0.0` otherwise. Address `::` actually superseeds `0.0.0.0`, meaning
it will listen on all IPv4 and IPv6 addresses available on the system.

CAUTION: Some applications overwrite the default target remote address to
be `localhost`. If IPv6 support is available on the system, `localhost` will
usually resolve to `::1`, otherwise it will usually resolve to `127.0.0.1`.

=== Local Point-Code

Each CNI program on an SCCP/M3UA link typically has a local point-code,
configurable by:

----
cs7 instance 0
 point-code 7.65.4
----

If an explicit routing context is configured, this point-code is repeated in
the `routing-key` configuration:

----
cs7 instance 0
 point-code 0.23.1
 as my-as m3ua
  routing-key 2 0.23.1
----

See also <<point_code_format>>.

=== Remote Point-Code

Programs establishing communication across SCCP links need a remote SCCP
address, typically by point-code, to contact.

For example,

- OsmoBSC needs to know the MSC's point-code, to be able to establish the A-interface.
- OsmoHNBGW needs to know the MSC's point-code, to be able to establish the IuCS-interface.
- OsmoHNBGW needs to know the SGSN's point-code, to be able to establish the IuPS-interface.

To maintain remote SCCP addresses, each `cs7` instance maintains an SCCP address book:

----
cs7 instance 0
 sccp-address remote-pc-example
  point-code 1.23.1
----

This address book entry on its own has no effect. It is typically referenced by
specific configuration items depending on the individual programs.

Examples:

- An OsmoBSC configures the MSC's remote SCCP address:

----
cs7 instance 0
 sccp-address my-remote-msc
  point-code 1.23.1
msc 0
 msc-addr my-remote-msc
----

- An HNBGW configures both the remote MSC's and SGSN's SCCP addresses:

----
cs7 instance 0
 sccp-address my-msc
  point-code 0.23.1
 sccp-address my-sgsn
  point-code 0.23.2
hnbgw
 iucs
  remote-addr my-msc
 iups
  remote-addr my-sgsn
----

Besides a point-code, an SCCP address can have several routing indicators:

- PC: routing by point-code is the default for Osmocom.
- GT: routing by Global Title is configurable by `routing-indicator GT`.
- IP: routing by IP address is configurable by `routing-indicator IP`.

In OsmoSTP, only routing by point-code is currently implemented.

[[point_code_format]]
=== Point-Code Format

Point-codes can be represented in various formats. For details, see OsmoSTP
manual, chapter "Point Codes".

By default, Osmocom uses a point-code representation of 3.8.3, i.e. first digit
of 3 bit, second digit of 8 bit, and third digit of 3 bit.

----
cs7 instance 0
 point-code format 3 8 3
 point-code 0.23.1
----

Often, point-codes are also represented as a single decimal number:

----
cs7 instance 0
 point-code format 24
 point-code 185
----

It is also possible to use a dash as delimiter.

----
cs7 instance 0
 point-code delimiter dash
 point-code 0-23-1
----


[[as_and_asp]]
=== AS and ASP

Each CNI program needs at least one Application Server `as` and one Application
Server Process `asp` configured on its `cs7` to be able to communicate on
SCCP/M3UA. An `asp` needs to be part of at least one `as`. For details, see the
OsmoSTP manual, chapters "Application Server" and "Application Server Process".

In Osmocom's `cs7`, any amount of `as` and `asp` can be configured by name, and
an `as` references the `asp` entries belonging to it by their names.

In a simple/minimal Osmocom setup, an Osmocom CNI program would have exactly
one `as` with one `asp`.

For example:

----
cs7 instance 0
 asp my-asp 2905 0 m3ua
  # where to reach the STP:
  remote-ip 127.0.0.1
  role asp
  sctp-role client
 as my-as m3ua
  asp my-asp
----

In Osmocom CNI programs, it is possible to omit the `as` and/or `asp` entries,
which the program will then attempt to configure automatically.

When configuring both `as` and `asp` manually, make sure to link them by name.
For example, the following configuration will *fail*, because `as` and `asp`
are not linked:

----
cs7 instance 0
 asp my-asp 2905 0 m3ua
  remote-ip 127.0.0.1
  role asp
  sctp-role client
 as my-as m3ua
  routing-key 2 0.23.1
----

To *fix* above config, link the `asp` to an `as` by adding `asp my-asp`:

----
cs7 instance 0
 asp my-asp 2905 0 m3ua
  remote-ip 127.0.0.1
  role asp
  sctp-role client
 as my-as m3ua
  asp my-asp
  routing-key 2 0.23.1
----

=== Subsystem Number (SSN)

Osmocom CNI programs typically route SCCP/M3UA messages by PC+SSN: each ASP,
having a given SCCP address, receives messages for one or more specific
subsystems, identified by a Subsystem Number (SSN).

For example, the A-interface between BSC and MSC uses SSN = BSSAP (254). In
Osmocom programs, SSNs do not need to be configured; they implicitly, naturally
relate to the interfaces that a program implements.

For example, OsmoBSC takes the configured remote MSC's SCCP address and adds
the SSN = BSSAP to it in order to contact the MSC's A-interface. To receive
A-interface messages from the MSC, OsmoBSC subscribes a local user for this SSN
on the ASP.

=== Routing Context / Routing Key

In SCCP/M3UA, messages can be routed by various Routing Indicators (PC+SSN, PC,
GT, ...). Osmocom CNI programs typically use PC+SSN as Routing Indicator.

On the SG (for example OsmoSTP), each ASP's distinct Routing Indicator needs to
be indexed by a distinct Routing Context (a simple index number scoped per SG),
to forward M3UA to the correct peer.

The Osmocom SG implementation employs Routing Key Management (RKM, see OsmoSTP
manual) to automatically determine a distinct Routing Context index for each
connected ASP. Routing Contexts can also be configured manually -- some
non-Osmocom SG implementations require this.

Each Routing Context is associated with a Routing Indicator and address; this
association is called a Routing Key.

For example, to configure an OsmoBSC with a local point-code of 1.23.3 to
receive M3UA with Routing Context of 2 and RI=PC:

----
cs7 instance 0
 point-code 1.23.3
 as my-as m3ua
  routing-key 2 1.23.3
----

Osmocom programs so far implement Routing Keys by Destination Point Code (DPC),
plus optional Subsystem Number (SSN) and/or Service Indicator (SI):

----
routing-key RCONTEXT DPC
routing-key RCONTEXT DPC si (aal2|bicc|b-isup|h248|isup|sat-isup|sccp|tup)
routing-key RCONTEXT DPC ssn SSN
routing-key RCONTEXT DPC si (aal2|bicc|b-isup|h248|isup|sat-isup|sccp|tup) ssn SSN
----

==== M3UA without Routing Context IE / Routing Context '0'

As per the M3UA specification, the use of the routing context IE is
optional as long as there is only one AS within an ASP.  As soon as
there are multiple different AS within one ASP, the routing context IE
is mandatory, as it is the only clue to differentiate which of the ASs a
given message belongs to.

In the Osmocom M3UA implementation, it is generally assumed that a
routing context IE is always used, for the sake of clarity.

However, the routing context ID of '0' has the special meaning of _do
not encode a routing context IE on transmit_.

So if you configure an application like OsmoBSC to use routing context
0, then no routing context IE will be included in outbound M3UA
messages.

This special interpretation of '0' within the Osmocom M3UA
implementation however means that we can not represent M3UA with a
routing context IE that actually contains '0' as a numeric identifier.

So you only have the following options:
* Using M3UA with routing context (1..N)
* Using M3UA without routing context (0)

==== Example: Static Routing

Osmocom SS7 supports dynamic routing key registration via M3UA Routing Key Management (RKM), allowing minimal SS7
configuration. If all of your components support dynamic RKM, you should probably use it: see
`accept-asp-connections dynamic-permitted` in osmo-stp.cfg.

This chapter explains how to configure osmo-stp if dynamic RKM is not an option.

In this example, let's connect osmo-bsc via osmo-stp to osmo-msc using only static SS7 routing.

----
 BSC        <--RK-1-->  STP         <--RK-3--> MSC
 IP 1.1.1.1             IP 2.2.2.2             IP 3.3.3.3
 M3UA 2905              M3UA 2905              M3UA 2905
 PC 1.1.1                                      PC 3.3.3
----

Every one static route fanning out from STP gets assigned a distinct Routing Key -- a simple integer number. Above, the
BSC's link has RK 1, the MSC's link has RK 3.

For static routing, the M3UA port numbers must be fixed, i.e. there must be no `0` for a client's local port as in
`asp foo 2905 0 m3ua`. Instead, you may use `asp foo 2905 2905 m3ua`.

The BSC needs to configure:

- its own point-code -- has to match the PC configured for the BSC in osmo-stp.cfg
- the routing key -- has to match the RK assigned to BSC's PC in osmo-stp.cfg
- the MSC's point-code -- has to match the PC in osmo-stp.cfg and osmo-msc.cfg
- local and remote IP:ports for M3UA -- have to match the IP:ports in osmo-stp.cfg

The MSC needs to configure:

- its own point-code -- has to match the PC configured for the MSC in osmo-stp.cfg
- the routing key -- has to match the RK assigned to MSC's PC in osmo-stp.cfg
- local and remote IP:ports for M3UA -- have to match the IP:ports in osmo-stp.cfg

The STP needs to configure:

- all point-codes -- they have to match the PCs in osmo-bsc.cfg and osmo-msc.cfg
- all routing keys -- they have to match the RKs used in osmo-bsc.cfg and osmo-msc.cfg
- local and remote IP:ports for M3UA -- have to match the IP:ports in osmo-bsc.cfg and osmo-msc.cfg

.osmo-bsc.cfg
----
cs7 instance 0
 point-code 1.1.1

 asp mybsc-0 2905 2905 m3ua
  remote-ip 2.2.2.2
  local-ip 1.1.1.1
  sctp-role client
 as mybsc0 m3ua
  asp mybsc0-0
  routing-key 1 1.1.1

 sccp-address mymsc
  routing-indicator PC
  point-code 3.3.3

msc 0
 msc-addr mymsc
----

.osmo-stp.cfg
----
cs7 instance 0
 xua rkm routing-key-allocation static-only
 listen m3ua 2905
  accept-asp-connections pre-configured
  local-ip 2.2.2.2

 # asp <name> <remote-port> <local-port|0> m3ua
 asp mybsc-0 2905 2905 m3ua
  remote-ip 1.1.1.1
  local-ip 2.2.2.2
 as mybsc m3ua
  asp bsc-0
  routing-key 1 1.1.1

 asp mymsc-0 2905 2905 m3ua
  remote-ip 3.3.3.3
  local-ip 2.2.2.2
 as mymsc m3ua
  asp mymsc-0
  routing-key 3 3.3.3

 route-table system
  update route 1.1.1 7.255.7 linkset mybsc
  update route 3.3.3 7.255.7 linkset mymsc
----

.osmo-msc.cfg
----
cs7 instance 0
 point-code 3.3.3

 asp mymsc-0 2905 2905 m3ua
  remote-ip 2.2.2.2
  local-ip 3.3.3.3
  sctp-role client
 as mymsc0 m3ua
  asp mymsc0-0
  routing-key 3 3.3.3
----

For comparison, the same setup with dynamic routing key management is a lot shorter, especially at osmo-stp.cfg, and
there is no need to manually configure point-codes and routing keys between STP and \{BSC,MSC}:

.osmo-bsc.cfg
----
cs7 instance 0
 point-code 1.1.1

 asp mybsc-0 2905 0 m3ua
  remote-ip 2.2.2.2
  local-ip 1.1.1.1
  sctp-role client
 as mybsc0 m3ua
  asp mybsc0-0

 sccp-address mymsc
  routing-indicator PC
  point-code 3.3.3

msc 0
 msc-addr mymsc
----

.osmo-stp.cfg
----
cs7 instance 0
 xua rkm routing-key-allocation dynamic-permitted
 listen m3ua 2905
  accept-asp-connections dynamic-permitted
  local-ip 2.2.2.2
----

.osmo-msc.cfg
----
cs7 instance 0
 point-code 3.3.3

 asp mymsc-0 2905 0 m3ua
  remote-ip 2.2.2.2
  local-ip 3.3.3.3
  sctp-role client
 as mymsc0 m3ua
  asp mymsc0-0
----
