Skip to content

HSS Configuration⚓︎

The HSS is the part of xRouter that the roaming partners talk to. Its configuration has two halves: the transport and peer settings of the HSS itself (Diameter, MAP over SS7, SMPP), which live under hss in values.yaml, and the home-network identity the Expeto Agent provisions into it (home PLMNs, HLR and SMS centre addressing), which lives under agent.hss.nodeConfig. This page maps the decisions from the interconnect data onto both.

All values shown are placeholders: replace the PLMN, realm, addresses, global titles and point codes with the ones agreed with your partners.

Home network identity⚓︎

The Agent configures the HSS with the home PLMNs it serves and the SS7 identity it answers under. Everything under agent.hss.nodeConfig is passed to the Agent's HSS configuration unchanged.

agent:
  hss:
    nodeConfig:
      hssConfig:
        homePlmns:
          - plmn:
              mcc: "001"
              mncs: ["001"]
              realm: epc.mnc001.mcc001.3gppnetwork.org
            gts: ["882600000001", "882600000002"]   # global titles serving this PLMN
        hostUri: hss01                               # Diameter host name of this HSS
        originHost: hss01.epc.mnc001.mcc001.3gppnetwork.org
        originRealm: epc.mnc001.mcc001.3gppnetwork.org
        hlrGt: "882600000001"                        # HLR global title
        pointCode: 2010                              # HLR point code
        hlrTt: 0                                     # translation type
        hlrGti: GLOBAL_TITLE_INCLUDES_TRANSLATION_TYPE_NUMBERING_PLAN_ENCODING_SCHEME_AND_NATURE_OF_ADDRESS
        hlrEncoding: BCD_ODD
        allowRoaming: true
        smsInMme: false                              # S6a "SMS in MME" for the home PLMN
      smscConfig:
        gt: "882600000002"                           # SMS centre global title
        pointCode: 2010
Field Purpose
homePlmns[].plmn One entry per home PLMN: mcc, the list of mncs (two or three digits, as encoded on the SIMs) and the Diameter realm, normally epc.mnc<MNC>.mcc<MCC>.3gppnetwork.org with the MNC padded to three digits.
homePlmns[].gts Global titles registered for the PLMN; the first is used as the HLR global title.
hostUri, originHost, originRealm The Diameter identity this HSS presents to the partners' Diameter Routing Agents.
hlrGt, pointCode, hlrTt, hlrGti, hlrEncoding, hlrNp, hlrNoai The HLR's SS7 addressing: global title, point code and the SCCP address indicators.
allowRoaming Whether subscribers may attach from visited networks.
smsInMme Enable delivery of SMS through the MME over S6a for this home network.
smscConfig Global title and point code of the SMS centre.

Diameter⚓︎

Diameter is the S6a path from the visited networks' MMEs. The HSS listens on one or two addresses and either accepts connections from the partners' Diameter Routing Agents (DRAs) or initiates them.

hss:
  diameter:
    tcp: false                        # SCTP; set true for TCP
    host: hss01                       # Diameter host name
    realm: epc.mnc001.mcc001.3gppnetwork.org
    primaryIp: 192.0.2.10             # listen address; default 0.0.0.0
    secondaryIp: 192.0.2.11           # second address for SCTP multi-homing; omit for single-homed
    port: 3868
    capabilitiesIntersectionOnly: true
    applications:
      s6a: true
      s6b: true
      s13: true
      cxdx: true
      sh: true
      swx: false
    routingRules:
      - peerRealm: "*"
        peerHosts: [dra1.ipx.example.com, dra2.ipx.example.com]
    peers:                            # only for connections this HSS initiates
      - ip: 192.0.2.50
        port: 3868
        diameterRealm: ipx.example.com
        diameterHost: dra1.ipx.example.com
        protocol: SCTP
        hssIp: 192.0.2.10
        hssPort: 3868
Field Purpose
tcp Transport: SCTP (the IPX default) when false, TCP when true.
host, realm Diameter identity; keep them consistent with originHost and originRealm above.
primaryIp, secondaryIp, port Listen addresses and port. With Multus the addresses are the HSS pod's fixed addresses on the interconnect segment; with NodePorts leave the default.
capabilitiesIntersectionOnly Advertise only the applications both sides support in the capabilities exchange.
applications Which Diameter applications are enabled; extra keys are rendered as given.
routingRules Which peer hosts serve which realms (* for any).
peers DRAs this HSS connects to, with the local address and port to use. Omit when the partners initiate the connection.

MAP over SS7⚓︎

MAP serves 3G partners and SMS. The HSS runs an M3UA stack over SCTP towards the partners' signalling transfer points (STPs), acting as server or client per link.

hss:
  map:
    enabled: true
    sccpVersion: ITU                  # or ANSI
    hlr:
      pointCode: 2010
      globalTitle: "882600000001"
      sccp:
        - addressIndicator: "11"
          globalTitleType: GT0010
    smsc:
      pointCode: 2010
      globalTitle: "882600000002"
      sccp:
        - addressIndicator: "11"
          globalTitleType: GT0010
    servers:                          # local M3UA endpoints partners connect to
      - name: sctp1
        ip: 0.0.0.0
        port: 2905
    stps:
      - pointCodes: ["4444", "4445"]  # primary and backup point code of the STP
        networkIndicator: "2"
        routingContexts: []           # only if the STP requires them
        trafficMode: 2                # 2 = load share, 1 = override
        sccp:
          - name: stp1-sccp
            addressIndicator: "19"
            globalTitleType: GT0100
            translationType: "0"
            encodingScheme: "1"
            numberingPlan: "0"
            natureOfAddress: "0"
        ips:
          - ip: 192.0.2.60            # the STP's address
            port: 2905
            name: stp1-link1
            linkTo: sctp1             # accept from this STP on our server "sctp1"
          - ip: 192.0.2.61
            port: 2906
            hlrIp: 192.0.2.10         # connect out from this address instead
            hlrPort: 2906
    routingRules:
      - addressIndicator: "19"
        globalTitleType: GT0100
        translationType: "0"
        encodingScheme: "1"
        numberingPlan: "0"
        natureOfAddress: "0"
        globalTitlePrefixes: ["8826*"]
        routeTo:
          - pointCode: 4444
            sccp: stp1-sccp
Field Purpose
sccpVersion ITU or ANSI, as the STPs use.
hlr, smsc Point code, global title and SCCP address pattern of the HLR and the SMS centre. Keep them consistent with agent.hss.nodeConfig.
servers Local SCTP endpoints on which STPs connect to the HSS.
stps[] One entry per STP link: its point codes, network indicator, routing contexts, traffic mode, SCCP patterns and the addresses. An ips[] entry with linkTo accepts the STP's connection on the named server; one with hlrIp and hlrPort connects out to the STP.
routingRules Global title prefixes and the STPs and SCCP patterns they are routed to.

The default SCCP address indicators (11, GT0010, translation type 10, numbering plan ISDN, international nature of address) suit most ITU interconnects; the STP operator confirms the values.

SMS centre and SMPP⚓︎

The SMS centre delivers messages over MAP to the partners and accepts SMPP clients for application-originated traffic:

hss:
  smsc:
    enabled: true
    smpp:
      clients:
        - systemId: acmecorp-app
          password: <SMPP password>
    routingRules:
      - destinationAddress: "1555*"
        destinationRoute: SMPP
        sourceRoute: ANY
        systemId: acmecorp-app

The SMPP port (2775) is published with the other HSS ports; see Verify the installation.

Exposed ports⚓︎

The HSS chart publishes Diameter (3868), M3UA (2905) and SMPP (2775) as Services and, by default, as NodePorts on the same numbers, which is why the API server's node port range must include them. On a Multus deployment, attach the HSS to the interconnect segment through hss.deployments.hss.networks and give the partners the fixed address instead.

Applying changes⚓︎

The HSS reads its configuration at start-up. After changing any of the values above:

helm upgrade xrouter expeto/xrouter -n xrouter -f values.yaml \
    --set imageCredentials.username='<username>' \
    --set imageCredentials.password='<password>' \
    --set imageCredentials.email='user@example.com' \
    --set agent.connections.apiToken='<site API token>'
kubectl -n xrouter rollout status deployment/xrouter-hss

Peer state after a restart is visible in the HSS log; a partner link that does not come up is almost always an address, port or firewall mismatch on the interconnect.