Configuration¶
One file, sigtran.yaml, describes the node: its point code, the SCTP
transport plane, the MTP3 route table, the SCCP/GTT tables, and the
content-routing rules. The composing siphon binary loads it at startup (you
point extensions.sigtran at it; see
Using it in a SIPhon build). Parsing validates the whole
file: dangling references, duplicate names, point codes out of range for the
variant, and unknown operation names are rejected at load, not at 3 am.
A complete annotated example (every value synthetic: test PLMN 001/01,
+1-555-01xx global titles, decimal point codes):
node:
point_code: 1000 # our PC (ITU 14-bit, decimal)
variant: itu
network_indicator: international
# SCTP transport plane. m2pa links carry their adjacent PC inline.
associations:
- { id: hlr-a, adaptation: m3ua, role: server, addrs: [10.1.0.10], port: 2905 }
- { id: hlr-b, adaptation: m3ua, role: server, addrs: [10.1.0.11], port: 2905 }
- { id: msc, adaptation: m3ua, role: server, addrs: [10.1.0.12], port: 2905 }
- { id: xit-1, adaptation: m2pa, role: client, addrs: [10.0.1.1], port: 3565, adjacent_pc: 3000 }
# M3UA Application Servers: one AS per destination, served by its ASPs (the
# m3ua associations), with a traffic mode (RFC 4666).
application_servers:
- { name: hlr, traffic_mode: loadshare, routing_context: 100, asps: [hlr-a, hlr-b] }
- { name: msc, traffic_mode: override, routing_context: 101, asps: [msc] }
# M2PA linksets (RFC 4165): links grouped toward an adjacent PC. SLS spreads
# traffic across the links, so there is no traffic mode here.
linksets:
- { name: transit, links: [{assoc: xit-1}] }
# Signalling network management (ITU-T Q.704): its timers, in milliseconds.
# Every key is optional; these two are the ones a lab changes first.
mtp3:
t18_ms: 20000 # how long a restart waits for adjacent points
t21_ms: 64000 # how long a restarting adjacent point is waited for
# MTP3 routes: dpc -> an AS or a linkset, priority (1 = primary, higher =
# alternate, equal = shared by SLS). The adjacent PC of an m2pa link (3000)
# is an implicit route.
mtp3_routes:
- { dpc: 2000, as: hlr, priority: 1 }
- { dpc: 2000, linkset: transit, priority: 2 } # alternate via M2PA transit
- { dpc: 2002, as: msc, priority: 1 }
# SCCP: local subsystems, GTT groups, GTT rules, and E.214/E.164 conversion.
sccp:
local_ssns: [6, 8] # inbound for these terminates locally
gtt_groups:
- { name: ag-hlr, mode: cost, members: [{dpc: 2000, ssn: 6, cost: 1}, {dpc: 2001, ssn: 6, cost: 2}] }
- { name: ag-home-router, mode: share, members: [{dpc: 2003, ssn: 8, weight: 1}, {dpc: 2004, ssn: 8, weight: 1}] }
gtt:
- { match: {gt_prefix: "155501", gti: 4, tt: 0, np: 1, nai: 4}, to: {group: ag-hlr} }
- { match: {gt_prefix: "1555"}, to: {dpc: 2000, ssn: 6} }
gt_conversion:
plmn_map:
- { mcc: "001", mnc: "01", e164_prefix: "15551" }
# Content routing: routes/screens on the decoded MAP layer.
content_routing:
protocol: gsm-map
address_tables:
- { name: home-subs, addrs: ["15550142", "15550143"] }
imsi_tables:
- { name: customer-a, prefixes: ["001010", "001011"] }
rules:
- name: customer-a-home
match: { operation: [update-location, send-auth-info, cancel-location], imsi_in: customer-a }
action: { route: {dpc: 2005, ssn: 6} }
- name: sri-sm-route
match: { operation: sri-sm }
action: { route: {dpc: 2000, ssn: 6} }
node¶
Our identity.
| Field | Default | Meaning |
|---|---|---|
point_code |
(required) | Our point code, decimal, resolved under variant. |
variant |
(required) | SS7 variant: itu, ansi, or china. Fixes the point-code width, so an out-of-range PC is a load error. |
network_indicator |
international |
Q.704 NI for messages we originate: international, international_spare, national, national_spare. |
Point codes are decimal integers throughout the file, the way an operator reads them off a plan.
associations¶
The SCTP transport plane: one entry per association.
| Field | Default | Meaning |
|---|---|---|
id |
(required) | Association id, referenced by AS asps and linkset links. Unique; the <group-id>@ prefix is reserved when that DNS group is enabled. |
adaptation |
(required) | m3ua (RFC 4666) or m2pa (RFC 4165). |
role |
(required) | server (we listen) or client (we connect). |
addrs |
(required) | IP literals; clients also accept DNS names and host:port (IPv6 with a port uses [address]:port). Names are resolved on every dial. Without all_addresses, the resolved list describes one multihomed SCTP peer. |
port |
(required) | SCTP port. Convention: 2905 for M3UA, 3565 for M2PA. For a server, 0 asks the kernel for a port of its own (a test, not a deployment). |
peer_addrs |
[] (server only) |
Every IP address of the peer this association accepts: all of them for a multihomed peer. See who a listening association accepts. Empty accepts whoever connects first and logs a warning at start. |
peer_port |
(none: any port) (server only) | The SCTP port of the peer. Needs peer_addrs. Not 0. |
local_addrs |
[] (client only) |
The local IP addresses the association is dialled from; more than one makes this end multihomed. Empty leaves the choice to the kernel, which then offers the peer every address of the host: a peer that accepts by source address (peer_addrs on its side) needs this set. |
local_port |
(none: any port) (client only) | The local SCTP port the association is dialled from. Without local_addrs it is bound on every address. Not 0. |
all_addresses |
false |
Client M3UA only: expand the single addrs entry into one association per resolved socket address. |
resolve_seconds |
30 |
Positive DNS refresh interval for all_addresses. |
reconnect_max_seconds |
30 |
Positive reconnect cap in seconds when dial is absent. An explicit dial block takes precedence, including its defaults. |
dial |
(client only) every default below | How the association is dialled, and dialled again: see the dial block. |
adjacent_pc |
(m2pa only) | The adjacent point code reached directly over this link. An adjacent PC is an implicit route; it needs no mtp3_routes entry. |
m2pa |
(m2pa only) every default below | Level 2 of the link: see the m2pa block. |
m3ua |
(m3ua only) every default below | The heartbeat and the acknowledgement timer of the peer: see the m3ua block. |
An m3ua association carries traffic only as an ASP of an
application server. One that is in no server can come
up and cannot become active: its ASP Active is answered with Error, "No
Configured AS for ASP" (RFC 4666 3.8.1).
Who a listening association accepts¶
For a server association addrs and port are this node's. The peer is
described by peer_addrs and, when its port is fixed, peer_port:
associations:
- { id: asp-a, adaptation: m3ua, role: server, addrs: [192.0.2.1, 198.51.100.1], port: 2905,
peer_addrs: [192.0.2.10, 198.51.100.10] }
- { id: asp-b, adaptation: m3ua, role: server, addrs: [192.0.2.1, 198.51.100.1], port: 2905,
peer_addrs: [192.0.2.20], peer_port: 2905 }
RFC 4165 4.1.2 asks for it for a signalling link ("Each MTP link corresponds to an SCTP association. To prevent duplicate associations from being established, it is RECOMMENDED that each endpoint know the IP address (or IP addresses, if multi-homing is used) and port number of both endpoints"), and the node applies the same to an M3UA and a SUA association.
- A peer is an association's when every address it presents is listed. SCTP hands over all the addresses of the peer (RFC 9260 5.1.2: the receiver of an INIT records "all the transport addresses from the received chunk"). One listed address with one that is not listed is refused: traffic would be sent to an address nobody vouched for. A peer whose SCTP socket is not bound to specific addresses offers every address of its host, so list them all or bind the peer.
- Anyone else is refused. The kernel answers an INIT by itself and
completes the handshake before the node sees the association, so the refusal
is an SCTP ABORT right after the association came up: the peer sees it come
up and be aborted. Nothing it sent is read. Each refusal is counted in
sigtran_association_refused_total{reason}and logged with the addresses (at most one line a second per listening endpoint, which says how many it left out). - Associations may share one local
addrsandportand are told apart by the address of the peer: one listener serves them all. Two associations on one endpoint whosepeer_addrshave an address in common (unless a differentpeer_porton each tells them apart), or one of which has nopeer_addrs, do not load: the error names both. Two associations whoseaddrsoverlap without being the same list on one port do not load either. - An established association is not displaced. A second association for
the same
idwaits, unread, for up to two seconds (a peer that closed its association and dials again at once is served as soon as the old one is gone) and is then aborted and counted asduplicate. A restart of the same peer from the same addresses and port never gets that far: SCTP handles it inside the association it has (RFC 9260 5.2.4). The cost of not displacing: a peer that lost its association without the node noticing, and comes back from another port, is refused until the old association has failed, which is at the next packet the node sends to it or at the SCTP heartbeat (30 seconds by default).beat_msof them3uablock shortens that; a fixed source port at the peer, withpeer_porthere, avoids it. - Being accepted makes an association no egress. Traffic goes to it when its adaptation layer says so: an ASP that is active, a link that is aligned and passed its test.
Without peer_addrs an association accepts whoever connects first to its
port, as every release before this key did, and a line at start says so in
capitals. It then needs an address and port of its own.
DNS member groups¶
With all_addresses: true, the configured ASP is a template. Every resolved
address gets a member named <id>@<address:port> (IPv6 addresses are bracketed).
Each member inherits every AS membership of the template and independently
retries connections, then completes ASP Up / ASP Active before carrying traffic.
The template itself never dials. Members expand at the template's position in
AS order and are ordered by their names, making Override choose the first active
member and Loadshare choose by SLS across the active members. Broadcast uses all
active members. Separate client gateways' Active acknowledgements do not displace
one another; server-side Override still follows RFC 4666's displacement procedure.
Resolution happens immediately and every resolve_seconds. Duplicate answers
are collapsed. A successful answer withdraws missing members: their live
associations send ASP Down, close, and leave every AS and the registry. A lookup
error or timeout retains the previous set; a successful empty answer removes all
members. Unchanged members keep their associations. DNS and connect failures are
logged and retried without preventing startup. Each lookup is bounded by
dial.connect_timeout_ms; ordinary dialing bounds lookup and connect together.
TCAP dialogue affinity across members is not provided. A TC-CONTINUE arriving on a different member from its TC-BEGIN is outside this feature's scope.
The dial block¶
A client association is dialled by a task of its own when the node starts,
again after every attempt that failed, and again after the association it had
was lost (the peer closed or aborted it, SCTP gave it up, the M3UA heartbeat
went unanswered). RFC 4666 4.3.4.6: "the signalling process SHOULD attempt to
re-establish communication if it is configured as the client for the
disconnected M3UA peer". A peer that is absent at start delays nothing and
stops nothing: the node starts, its other associations are served, and the
absent one is dialled until it is there. On an association that was dialled
again everything runs as on the first: ASP Up and ASP Active, or the
alignment and the test of the link and, for a link that had been changed over
from, the changeback (ITU-T Q.704 clause 6). The times are in milliseconds.
| Field | Default | Meaning |
|---|---|---|
connect_timeout_ms |
10000 |
How long one attempt may take before it is given up and counted as timeout. The default lets the INIT and its first two retransmissions out at the Linux initial retransmission timeout of 3 seconds (at 0, 3 and 9 seconds) and does not sit through all eight the kernel would send. Not 0. |
backoff_initial_ms |
1000 |
The wait before the next attempt after the first failure, and after an association that had been up was lost. It doubles with every further failure. The default is that of restart_ms of an M2PA link, for the same reason (ITU-T Q.704 16.8, T17: "Delay to avoid oscillation of initial alignment failure and link restart"). Not 0. |
backoff_max_ms |
30000 |
The longest wait. The default is the interval at which SCTP itself probes an idle path (RFC 9260 16, HB.interval: 30 seconds): a peer that is back is found within that, and a node with many absent peers sends one INIT per peer in that time. Not below backoff_initial_ms. |
backoff_jitter_percent |
20 |
How much of every wait is taken off at random (0 to 100), so that associations that failed together (one peer with many links, many nodes toward one peer) are not all dialled in the same instant. The sequence is seeded per association from the per-process random key of the standard library's hasher and the association id; it spreads waits and is not for anything that must be unpredictable. |
The waits start over at backoff_initial_ms once an association has held for
backoff_max_ms. One that ends sooner (a far end that accepts and aborts,
for instance because this node is not the peer it has configured) counts as
one more failure, and the waits go on growing to the cap.
A fixed local_port has a cost on Linux: the far end can still be finishing
the shutdown of the association it had with that port when the next INIT
arrives, and discards it (RFC 9260 9.2: "it SHOULD discard the INIT chunk and
retransmit the SHUTDOWN ACK chunk"). A redial right after a close then takes
one INIT retransmission, 3 seconds by default, as measured on loopback. Keep
connect_timeout_ms above that.
What the dialling does is in sigtran_association_dial_attempts_total,
sigtran_association_dial_failures_total{reason} and
sigtran_association_dial_backoff_seconds
(metrics), and in one line of the log per change: the
first attempt of a run that failed, a failure for another reason, the
association established (with how many attempts failed before), the
association ended. While attempts keep failing for the same reason there is
one line a minute, which says how many it left out.
The m3ua block¶
What RFC 4666 leaves to provisioning for one M3UA peer, on an m3ua
association. The timers are in milliseconds.
| Field | Default | Meaning |
|---|---|---|
beat_ms |
0 |
T(beat) of RFC 4666 4.3.4.6: the interval at which this node sends Heartbeat. 0 sends none, which is the default because SCTP has a heartbeat of its own; set it to notice a peer whose process hangs while its SCTP stack still answers. When nothing at all arrives from the peer for twice the interval ("If no Heartbeat Ack message (or any other M3UA message) is received from the M3UA peer within 2*T(beat), the remote M3UA peer is considered unavailable") the association is aborted: for a server association the ASP is then down and may connect again, a client association is dialled again. A Heartbeat from the peer is always acknowledged with its data unchanged, whatever is set here. |
ack_ms |
2000 |
T(ack) of RFC 4666 4.3.4.1 and 4.3.4.3 ("provisionable, with a default of 2 seconds"): on a client association, an ASP Up or ASP Active that is not acknowledged is sent again every ack_ms. Not 0. |
asp_id |
(none) | The ASP Identifier this node puts in its ASP Up on a client association (RFC 4666 3.5.1: "a unique value that is locally significant among the ASPs that support an AS"). Left out when not set. A gateway quotes it in the Notify that tells the other ASPs of a takeover or a failure. |
The m2pa block¶
Level 2 of one M2PA link (RFC 4165), on an m2pa association. The timers are
those of ITU-T Q.703 12.3; the defaults are inside the ranges it gives for a
64 kbit/s link, which RFC 4165 clause 4 has M2PA use. All of them are in
milliseconds and none may be 0.
| Field | Default | Meaning |
|---|---|---|
proving |
normal |
The proving period this end asks for at alignment: normal (Link Status Proving Normal, t4n_ms) or emergency (Proving Emergency, t4e_ms). When the peer asks for the emergency period it is used whatever is set here (Q.703 7.2). |
t1_ms |
45000 |
T1, alignment ready (Q.703: 40 to 50 s): how long to wait, after proving, for the peer to finish its own. |
t2_ms |
30000 |
T2, not aligned (5 to 150 s): how long to wait for the peer to start alignment. |
t3_ms |
1500 |
T3, aligned (1 to 2 s): how long to wait for the peer to start proving. |
t4n_ms |
8200 |
T4, the normal proving period (7.5 to 9.5 s). |
t4e_ms |
500 |
T4, the emergency proving period (400 to 600 ms). |
t6_ms |
4500 |
T6, remote congestion (3 to 6 s): how long the peer may stay busy with messages unacknowledged (RFC 4165 4.1.5). |
t7_ms |
2000 |
T7, excessive delay of acknowledgement (0.5 to 2 s): a User Data message unacknowledged for this long fails the link (RFC 4165 4.2.1). |
proving_interval_ms |
100 |
The interval between Link Status Proving messages while T4 runs (RFC 4165 4.1.3, Proving_Interval). |
restart_ms |
1000 |
The delay before alignment is started again after it failed or the link failed (ITU-T Q.704 12.2.2, timer T17, 800 to 1500 ms). |
tx_queue |
4096 |
MSUs the link holds for transmission (waiting for the link's task, or because the peer is busy or in processor outage) before further ones are discarded and counted (Q.704 3.8). |
A link starts alignment as soon as its association is up, and starts it again after every failure for as long as the association lasts.
The value sua selects SUA (RFC 3868) for connectionless SCCP-user traffic:
like m3ua it terminates SCTP and feeds the SCCP messages this node routes and
terminates onto the same path. (SUA connection-oriented service is out of scope.)
application_servers¶
M3UA Application Servers (RFC 4666). An AS is a logical destination served by
one or more ASPs; each ASP is an m3ua association, and the per-ASP
ASPSM/ASPTM state machine brings it up.
| Field | Meaning |
|---|---|
name |
AS name, referenced by mtp3_routes (as:). Shares one namespace with linkset names, so a route reference never resolves two ways. |
traffic_mode |
loadshare (SLS-keyed spread over the active ASPs), override (one active, others standby), or broadcast (every active ASP). An AS property, not per-ASP. |
routing_context |
The Routing Context identifying this AS in ASPAC/DATA. |
asps |
The member ASPs: association ids. Each must be an m3ua association. |
recovery_ms |
T(r) of RFC 4666 4.3.2 and 4.3.4.4, in milliseconds, default 2000 (the RFC has it "configurable by the network operator" and names no value). When the last active ASP of the server leaves, the server is pending for this long: it stays a route, what arrives for it is queued, and the ASP that becomes active in time gets the queue. When the timer runs out the queue is discarded and the server is inactive or down. 0 switches the pending state off. Only a server this node is the signalling gateway of (one with a server association) is ever pending. |
pending_queue |
Messages queued for the server while it is pending, default 4096. Further ones are discarded and counted. Not 0. |
required_asps |
"n" of RFC 4666 4.3.2, default 1: the number of ASPs that have to be active before the server is, and so before it is a route. Once active the server stays active until its last ASP leaves; while it has fewer than required_asps its inactive ASPs are told ("Insufficient ASP Resources Active in AS"). 1 for an override server, at most the number of asps otherwise. |
The traffic mode and the routing context are enforced. An ASP Active that
names a Traffic Mode Type other than the server's is answered with Error,
"Unsupported Traffic Mode Type"; one that names a routing context the
association is not configured in, with "Invalid Routing Context" (RFC 4666
4.3.4.3, 3.8.1). The same goes for DATA: it is routed only from an ASP that is
active in the server whose context it names, or in any server when it names
none. In an override server the ASP that asks last takes all the traffic, and
the one that had it is told ("Alternate ASP Active").
linksets¶
M2PA linksets (RFC 4165). M2PA replaces MTP2, so the classic linkset/link model applies directly: a linkset groups links toward an adjacent point code, and SLS spreads traffic across its links. There is no traffic mode here.
Each selection code has a normal link, by the position of the links in
links (ITU-T Q.704 2.3.2 a: with two links, the even codes on the first and
the odd ones on the second). While a link carries no traffic its codes go to
the links that do, and come back by changeback when it returns
(Routing model). The links of a linkset are expected
to name the same adjacent_pc: changeover orders, transfer-prohibited and
traffic restart allowed for the linkset go to the first one named, and a
linkset whose links name none gets no management messages at all.
| Field | Meaning |
|---|---|
name |
Linkset name, referenced by mtp3_routes (linkset:). |
links |
The member links, each {assoc, slc}, at most 16. Each assoc must be an m2pa association; its adjacent PC comes from the association's adjacent_pc. slc is the signalling link code, 0 to 15, unique in the linkset; it defaults to the position of the link in the list. Both ends of a link must use the same code (RFC 4165 4.1.2). |
link_test |
The signalling link test of ITU-T Q.707 2.2 on every link of the linkset: see below. |
link_test¶
After alignment a link is tested before it carries traffic, and again at an
interval while it is in service (Q.707 2.2: "The signalling link becomes
available only if the test is successful"). A test that is not acknowledged
within t1_ms, or is acknowledged with another pattern, from another point
code or for another link code, is repeated once; the second failure takes the
link out of service and alignment starts again. Q.707 leaves the action on a
failed periodic test for further study; here it is the same as at activation.
| Field | Default | Meaning |
|---|---|---|
enabled |
true |
Whether this node tests its links. A test message from the peer is answered either way. |
t1_ms |
8000 |
T1, supervision of the acknowledgement (Q.707 5.5: 4 to 12 s, and not less than t6_ms). |
t2_ms |
60000 |
T2, the interval between tests (30 to 90 s). |
pattern |
a5a5a5a5a5a5a5a5 |
The test pattern: 1 to 15 octets in hexadecimal. |
The test is addressed to the link's adjacent_pc. A link without one, or with
enabled: false, is not tested: it is available as soon as it is aligned, and
the node says so in a warning when the link starts.
mtp3_routes¶
The static route table: DPC to a destination, by priority.
| Field | Meaning |
|---|---|
dpc |
Destination point code (decimal, validated against the node variant). |
as or linkset |
The destination. Exactly one of the two; naming both, or neither, is a load error. |
priority |
1 = primary; higher numbers are alternates. The resolver picks the lowest-priority available route and fails over as availability changes. Routes of the same priority to one DPC are a combined linkset (ITU-T Q.704 2.3.2 b, 4.2.1): they share its traffic by SLS, in the order they are listed. |
Adjacent PCs on M2PA links are implicit routes and need no entry. Availability comes from live state: M3UA ASP active/inactive, M2PA link in/out of traffic, a transfer-prohibited or transfer-allowed from the adjacent point of a linkset (which marks that one route), and Pause / Resume from an application server. See Routing model & coverage.
With two routes of one priority, the lowest bit of the SLS picks the route and
the links of each linkset are picked by the next bits, as Figure 5/Q.704 has
it, so every link of both linksets carries traffic. The SLS in the label is
not rewritten. A route added at run time with ss7.routes.add(...) shares like
any other, but the width a linkset divides the codes by is fixed from this
file at start.
mtp3¶
Signalling network management of a transfer point (ITU-T Q.704), per routing domain: what the node does when a link, a route or an adjacent point changes state. Every key is optional and every timer is in milliseconds; the defaults are the values of Q.704 16.8, or a value inside the range it gives. What each procedure does is in Routing model.
| Field | Default | Meaning |
|---|---|---|
t1_ms |
800 |
T1 (500 to 1200 ms), "delay to avoid message mis-sequencing on changeover": how long the traffic of a link is withheld when the far end cannot be asked what it received (Q.704 5.6.2), and when a link is inhibited (10.2). Also the isolation that is short enough not to call for a restart (9.4.1). |
t2_ms |
1400 |
T2 (700 to 2000 ms), "waiting for changeover acknowledgement" (5.7.2). |
t3_ms |
800 |
T3 (500 to 1200 ms), "time controlled diversion-delay to avoid mis-sequencing on changeback": how long the traffic of a linkset that became available is withheld (6.4). |
t4_ms |
800 |
T4 (500 to 1200 ms), "waiting for changeback acknowledgement (first attempt)" (6.5.3). |
t5_ms |
800 |
T5 (500 to 1200 ms), the same for the second attempt, after which traffic starts on the link anyway. |
t6_ms |
800 |
T6 (500 to 1200 ms), "delay to avoid message mis-sequencing on controlled rerouting": how long the traffic of a destination is held when a transfer-allowed or -restricted moves it to another route (8.2.1). |
t8_ms |
1000 |
T8 (800 to 1200 ms), "transfer prohibited inhibition timer": after a transfer-prohibited for a destination, no further one is sent by the response method for this long (13.2.2). |
t10_ms |
45000 |
T10 (30 to 60 s), "waiting to repeat signalling route set test message" (13.5.2). |
t12_ms |
1150 |
T12 (800 to 1500 ms), "waiting for uninhibit acknowledgement" (10.3.1 e). |
t13_ms |
1150 |
T13 (800 to 1500 ms), "waiting for force uninhibit" (10.3.2 e). |
t18_ms |
20000 |
T18, the first phase of this node's MTP restart: how long it waits for the traffic restart allowed of every adjacent point before it goes on without them (9.2.2). Q.704 leaves the value to the implementation and the network; it has to be shorter than t20_ms. |
t19_ms |
68000 |
T19 (67 to 69 s): after a traffic restart allowed was sent to an adjacent point, another one from it is ignored for this long (9.5). |
t20_ms |
60000 |
T20 (59 to 61 s), the "overall MTP restart timer at the signalling point whose MTP restarts" (9.2.4). |
t21_ms |
64000 |
T21 (63 to 65 s), the "overall MTP restart timer at a signalling point adjacent to one whose MTP restarts": how long an adjacent point that became reachable again is waited for before traffic is sent to it without its traffic restart allowed (9.3.2). |
t23_ms |
240000 |
T23 (3 to 6 minutes), the "remote inhibit test timer" (10.6.2). |
tfp_for_unknown_destination |
true |
Whether a message for a point code this node has no route for at all is answered with transfer-prohibited, as it is for a destination that is configured and inaccessible (13.2.2 iii). Footnote 7 of that clause leaves it to the network operator: false avoids route set tests for destinations that do not exist. |
rerouting_buffer |
4096 |
Messages held for one destination while T6 runs, before further ones are discarded and counted. The changeover and changeback buffers of a link are bounded by that link's tx_queue. |
No timer may be 0. T7, T11, T14 to T17 and T22 of Q.704 16.8 have no key:
they belong to procedures this node does not run (the allocation of data
links, the transfer-restricted timer, inhibiting a link on its own initiative,
the route set congestion test), except T17, which is restart_ms of
the m2pa block.
A node that starts, and a peer that does not answer. A node whose first
link comes into service runs the MTP restart procedure: until every adjacent
point has sent traffic restart allowed, or t18_ms is over, it discards what
arrives on its linksets (Q.704 9.6.6). An adjacent point that was unreachable
and returns is waited for in the same way under t21_ms. Against a conformant
peer both end within milliseconds of the link test. Against one that never
sends traffic restart allowed they last the whole timer: two nodes that start
together each wait t18_ms for the other, and a peer that does not implement
the procedure costs t21_ms every time its linkset comes back. Lower the two
timers for such a peer rather than expect traffic at once.
sccp¶
local_ssns¶
The subsystem numbers this node owns. Inbound SCCP addressed to one of them
(directly, or via a GTT result of local) terminates in the dialogue engine
instead of being forwarded. Termination decorators register handlers on these
SSNs (Script API).
gtt_groups¶
Named result sets for GTT, for cost-based failover or weighted sharing:
| Field | Meaning |
|---|---|
name |
Group name, referenced by gtt and content-rule route targets. |
mode |
cost (lowest cost primary, others fail-over alternates), share (weighted round-robin) or instance (see below). |
members |
{dpc, ssn} plus cost (for cost groups), weight (for share groups) or instance (for instance groups). |
instance_bits |
instance groups only: the width of the instance field in the members' transaction ids, 1 to 16. |
An instance group is for a function that runs as several instances behind one
global title, each instance with its own point code. Every instance sets
tcap.instance_bits (the same value as the group's instance_bits) and its own
tcap.instance, which puts the index in the OTID of every dialogue it opens or
answers (tcap). The node that translates the shared title then
routes on the transaction id:
- a TC-CONTINUE, TC-END or TC-ABORT goes to the member whose
instanceits DTID carries, at whichever relay it arrives, with no state about the dialogue. If that member is unreachable the message is undeliverable (it is not handed to another instance, which does not hold the dialogue); - a TC-BEGIN has no DTID: it goes round-robin to the next reachable member;
- a message whose DTID is not one of the group's (no marker bit, a length other than four octets, an index no member has) is shared like a TC-BEGIN.
sccp:
gtt_groups:
- name: sms-function
mode: instance
instance_bits: 2
members:
- { dpc: 110, ssn: 8, instance: 0 }
- { dpc: 111, ssn: 8, instance: 1 }
- { dpc: 112, ssn: 8, instance: 2 }
gtt:
- { match: { gt_prefix: "15550110" }, to: { group: sms-function } }
When every instance has a global title of its own, a plain dpc rule per title
is enough and no group is needed.
gtt¶
The ordered translation rules. First match wins.
match: any ofgt_prefix(leading GT digits),gti,tt,np,nai. All present fields must hold.to: exactly one of{dpc, ssn}(a concrete destination),{group}(a named group), or{local: true}(terminate here).
gt_conversion¶
E.214 (mobile global title) to E.164 conversion. Roaming MAP addresses an HLR with an E.214 called party: the home network's E.164 prefix (mapped from the IMSI's MCC+MNC) plus the MSIN. The converter runs the E.214→E.164 pre-step before GTT on an inbound called party whose numbering plan marks it E.214.
plmn_map: the network numbering map,{mcc, mnc, e164_prefix}entries. An E.214 called party matched to aplmn_mapprefix is rewritten to its E.164 form, then translated by GTT.
tcap¶
The dialogue-termination engine's timers and ceiling. Node-wide; the defaults sit in the Q.774 default operation-timer neighbourhood, and a low-volume node never touches them.
tcap:
invoke_timer_ms: 15000 # default invocation timer (default)
dialogue_timer_ms: 30000 # default idle timeout of a dialogue (default)
max_dialogues: 100000 # Begin over the ceiling is refused with a P-Abort
instance_bits: 0 # width of the instance field in our OTIDs (0 = none)
instance: 0 # this instance's index in that field
| Field | Default | Meaning |
|---|---|---|
invoke_timer_ms |
15000 |
The invocation timer of an invoke that does not name its own. Its expiry is reported to the handler and means what the operation's class says (operation classes); only a class 1 expiry is counted in sigtran_invoke_timeouts_total, and only a handler (or the default for class 1) aborts the dialogue on it. |
dialogue_timer_ms |
30000 |
How long a dialogue may go without a message in either direction before it is aborted (a U-Abort to the peer, the handler told, counted in sigtran_dialogue_timeouts_total). 0 disables it. A dialogue sets its own with dlg.set_idle_timeout(...): a call-control dialogue that waits for the end of a call needs more than a request / response default. |
max_dialogues |
100000 |
Ceiling on concurrently open dialogues. A Begin over it is refused with a P-Abort, cause resource limitation. |
instance_bits |
0 |
Width in bits (at most 16) of the instance field in the transaction ids this node allocates. A 4-octet id is the marker bit, then this field, then a counter; 0 leaves the id as the marker and a 31-bit counter. |
instance |
0 |
This instance's index in the field, below 2^instance_bits. Pairs with an instance gtt_groups entry on the relay. |
content_routing¶
Routing on the decoded MAP/CAP layer. Ordered rules, first match wins; rules a script adds live are prepended, so a fresh override wins over config.
| Field | Meaning |
|---|---|
protocol |
Which application layer to decode: gsm-map (TS 29.002) or gsm-cap (TS 29.078). |
address_tables |
Named sets of GT digit strings: {name, addrs}. |
imsi_tables |
Named sets of IMSI prefixes (leading MCC+MNC[+MSIN] digits): {name, prefixes}. |
rules |
The ordered rules: {name, match, action}. |
A rule match combines (all present fields must hold, absent fields are
wildcards):
| Match field | Meaning |
|---|---|
operation |
A kebab-case operation name or a list of them. Unknown names are a load error; see the operation table. |
imsi_in |
The decoded IMSI is in this named imsi_table. |
imsi_prefix |
The decoded IMSI starts with this prefix. |
cdpa_gt_in |
The called-party GT digits are in this named address_table. |
cgpa_gt_in |
The calling-party GT digits are in this named address_table. |
The action is one of:
| Action | Meaning |
|---|---|
route |
To {dpc, ssn} or {group: ...}. |
rewrite_cdpa_gt |
Rewrite the called-party GT digits on the egress SCCP before relay (combined with route). |
screen |
true drops the message (counted per rule). |
The rules are evaluated on a TCAP Begin or Continue that decodes in full. One
that does not (a damaged transaction or dialogue portion, a component that cannot
be read, octets after the end of the message) is dropped in a domain that has
content rules, and counted in
sigtran_content_unscreened_total{reason="undecodable",action="dropped"}: a
message that cannot be inspected has not passed a rule, so damaging a message is
not a way past screen. The drop takes the same path as any other, so a sender
that asked for return on error gets its UDTS. Everything the rules do not look at
(an End, an Abort, a payload that is not TCAP) is routed as before.
A rule that tests the IMSI (imsi_in, imsi_prefix) reads it from the argument
of the operation, decoded strictly. If the argument of an operation that carries
an IMSI does not decode, the IMSI is unknown, not absent: the first such rule
whose other tests hold cannot be evaluated, and the message is dropped there
(counted as sigtran_content_rule_hits_total{rule=…,action="unevaluable"})
instead of falling through to a later rule or to GTT. The argument types are the
MAP version 3 ones. The version 1 and 2 arguments of cancel-location, purge-ms
and send-auth-info are different types and do not decode as them, so an IMSI
rule on those operations drops version 1 and 2 dialogues; leave those operations
out of IMSI rules in a domain that still carries them.
One segment of a segmented XUDT / LUDT does not hold a whole TCAP message, and the
node does not reassemble in transit: segments are not evaluated against the
rules and are routed on, counted in
sigtran_content_unscreened_total{reason="segmented",action="passed"}. Watch that
counter if a screen rule matters to you.
isup_screening¶
Optional ISUP-aware screening on the SI=5 transit path. When the block is absent
the transit path is byte-for-byte unchanged; when present, each transiting ISUP
message is decoded and evaluated against the ordered rules (first match wins). A
block drops the message and counts it under sigtran_isup_screened_total.
sccp: { local_ssns: [] }
isup_screening:
default: allow # action when no rule matches (default: allow)
rules:
- { name: block-premium, match: { message_type: iam, called_prefix: "1999" }, action: block }
| Field | Meaning |
|---|---|
default |
Action for a message no rule matches: allow (default) or block. |
rules |
Ordered {name, match, action}; first match wins. |
match.message_type |
ISUP message by its lower-case Q.763 acronym (iam, rel, acm, …). |
match.called_prefix / calling_prefix |
Leading-digit prefix of the called / calling party number. |
action |
block (drop) or allow (explicitly pass). |
All present match fields must hold (AND); absent fields are wildcards. A
message that will not decode as ISUP takes the default action.
How the pieces connect¶
sigtran.yaml
|- node -> our PC / variant / NI
|- associations -> SCTP transport plane
|- application_servers -> M3UA AS over the m3ua associations
|- linksets -> M2PA linksets over the m2pa associations
|- mtp3_routes -> DPC -> AS/linkset, by priority
|- sccp -> owned SSNs, GTT (+ groups), E.214 conversion
|- tcap -> dialogue timers + ceiling
|- content_routing -> rules on the decoded MAP/CAP view
A full config load (parse + validation) costs about 28 microseconds, so re-configuring is free. Next: the Script API your handlers use, or the Cookbook to see config and script work together.