aboutsummaryrefslogtreecommitdiffstats
path: root/common/chapters/cs7-config.adoc
blob: 648e289b7ade7a412973dbb9f54686c2e53c1bcb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
[[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
  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
- Lb-interface: OsmoBSC to OsmoSMLC
- 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

By default, an STP instance is assumed to listen on the default M3UA port
(2905) on the local host (127.0.0.1).

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
----

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

=== 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.
- OsmoBSC needs to know the SMLC's point-code, to be able to establish the Lb-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 OsmoBSC configures the SMLC's remote SCCP address:

----
cs7 instance 0
 sccp-address my-remote-smlc
  point-code 0.42.6
smlc
 smlc-addr my-remote-smlc
----

- 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
  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
 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
 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
----

[[sccp-multiple-cs7]]
=== Multiple cs7 Instances

It is possible to connect to several STPs from an Osmocom CNI program. Which
`cs7 instance` to use is usually indicated by choosing an SCCP address
configured at the desired instance.

For example, an OsmoBSC can run A- and Lb-interface via distinct STP
connections, by configuring two separate `cs7 instance` sections with different
STP addresses. Which instance to use is chosen by assigning an SCCP address from
the desired instance:

----
cs7 instance 0
 asp my-asp 2905 0 m3ua
  remote-ip 10.23.24.1

cs7 instance 1
 # default remote-ip for STP is 127.0.0.1
 sccp-address smlc-on-local-stp
  point-code 0.23.6

msc 0

smlc
 smlc-addr smlc-on-local-stp
 enable
----

The above example points `cs7 instance 0` to a remote STP for the A-interface.
`msc 0` has no explicit `msc-addr` set, so it uses the first `cs7 instance 0`
and its default point-code for the A-interface.

The second `cs7 instance 1` points at a locally running STP at 127.0.0.1. `cs7
instance 1` contains an addressbook entry named `smlc-on-local-stp`. By
assigning this address to the `smlc-addr`, the Lb interface will run on `cs7
instance 1` via the local STP.

The remaining AS, ASP and point-codes are automatically configured. A fully
written out version of above example is:

----
cs7 instance 0
 # the default point-code for a BSC is 0.23.3
 point-code 0.23.3
 asp my-asp 2905 0 m3ua
  remote-ip 10.23.24.1
  sctp-role client
 as as-clnt-A-0-m3ua m3ua
  asp my-asp
 # the default point-code for an MSC is 0.23.1
 sccp-address msc0
  point-code 0.23.1
 sccp-address bsc-on-A
  point-code 0.23.3

cs7 instance 1
 point-code 0.23.3
 asp asp-clnt-Lb-1-m3ua 2905 0 m3ua
  remote-ip localhost
  sctp-role client
 as as-clnt-Lb-1-m3ua m3ua
  asp asp-clnt-Lb-1-m3ua
 sccp-address smlc-on-local-stp
  point-code 0.23.6
 sccp-address bsc-on-Lb
  point-code 0.23.3

msc 0
 msc-addr msc0
 # when bsc-addr is omitted, the chosen cs7 instance's point-code is used
 bsc-addr bsc-on-A

smlc
 # when smlc-addr is omitted, cs7 instace 0 would be used with the SMLC's
 # default point-code
 smlc-addr smlc-on-local-stp
 # when bsc-addr is omitted, the chosen cs7 instance's point-code is used
 bsc-addr bsc-on-Lb
 enable
----