Telephony providers

General

Providers are service companies providing access to external networks. Internet, PSTN, etc. To get PSTN access, a telecommunication service contract with one of these companies is required. Providers deliver connectivity over various channels and protocols, for example E1 streams, analog lines, SIP, H.323. The platform works only with the SIP protocol. If the provider can provide a SIP connection point, the platform connects directly to the provider. If not, intermediate nodes — gateways — are needed. For example from E1 to SIP.

Connection modes

For SIP connection the provider provides: the IP address or DNS name of the connection point, the connection port (default 5060). Then, depending on the connection method, the provider may provide either credentials — login, password, and optionally a number — or the client address and subnet together with a dedicated connection. In the first case the client registers from an arbitrary address; in the second case point-to-point — the client knows the server point, and the server knows the client point. A point is a combination of IP address and port.

The registration mode, even with the simplest configuration, assumes redundancy of the esg facade node — if the responsible one fails, another takes over the function of servicing the provider connection.

More complex connection schemes are possible, involving simultaneous servicing of the account on several facade nodes at once, including connection to different provider edge-proxy servers.

Examples

Example credentials may look like this:

Example credentials for a registered connection:
SIP server: sipnet.ru
Account: 71234567890
Password: 3y82lS5
Example credentials for a point-to-point connection:
Network allocated: 172.27.103.88/29 (172.27.103.89 - default gateway, 172.27.103.90 - client equipment)

Server IP address: 44.55.66.77
Port: 5060 UDP
Voice will come from 44.55.66.88
Both above IP addresses must be routed through the default gateway

Codec: g711a 20ms
Fax: transparent
DTMF: rfc2833

Number range:
9991234567 - 9991234569 (3 numbers, 50 sessions)

The "From" must contain a 10-digit number from the allocated range.

Dialing from the client is expected to be subscriber-style, i.e., local numbers - 7-digit,
zone and long-distance - with "8", international communication is closed.

Sometimes, as in the second case, preliminary server network configuration may be required, adding a vlan interface and the issued address. Considering that in this case the media gateway may be on any other server — all servers where the first media processing point may be located. And if this is impossible, a local bgmg media gateway must be configured on the esg server and work in media mode.

External PBX

Any external PBX connecting the platform "from below", i.e., as its subscriber, can act as a provider. In this case configuration is similar, and the connection options described above also apply. That is, an external PBX can be connected via registration (on the PBX), in point-to-point mode (mutual address configuration is performed). But if the PBX must register with the platform, then the platform acts as a "provider" and connection is performed differently — by connecting as a subscriber.

Configuring the provider account.

We assume the rest of the domain is already configured and users can call each other.

In the domain the provider account must be configured: the link has a description of all properties. Configuration can be performed:

  • From the domain administrator workstation (Routing - Providers). In card mode, or in advanced mode via JSON (to access specific fields).

  • Via REST API (/rest/v1/uc/providers).

In minimal mode the following must be configured:

  • Username (username) — account name,

  • Password (pwd) — password,

  • Domain (domain) — SIP server or REGISTRAR,

  • Registration (reg) — choose registration or point-to-point mode.

  • Local domain (localdomain) — the domain name to substitute into the FROM header of outgoing requests.

  • Number of trunks — the allocated number of licenses for simultaneous sessions. Optionally:

  • Outbound proxy address (proxyaddr) — if it differs from the domain;

  • Outbound proxy port (proxyport) — if the connection point port differs from 5060; Check:

  • Protocol (transport) — if it differs from UDP;

  • Ping mode (pingmode), ping server address (pingsrv), ping interval, sec (pingtimeout) — if connection is made through NAT with temporary port binding.

We will consider the remaining fields below as we proceed.

If connection is made in point-to-point mode, the provider may specify an explicit port for the client connection point. This port must be configured in the master domain configuration for the ESG role instance to which account servicing should be bound. By default in configurations created in the configuration wizard, port 5080 is assigned to esg. If different connections require many different ports, this can be solved either by multiplying esg instances or by using an intermediate gateway in the project that solves this task.

Binding to microservices

Accounts are serviced by the esg microservice. If there is one such microservice, the account is serviced on it. If there are several, one random available and active one is selected. When configuring point-to-point mode, where esg microservice instances are spread across different servers and the client address issued by the provider relates to only one of them, the provider account may need to be explicitly bound to an esg microservice instance. This is done in the "esg role RoleID value (serveridxs)" field. See esg for more. Identifiers are assigned to microservices in the configuration.

All provider accounts across all domains are by default serviced on the same esg microservice instances. If necessary, accounts can be separated across different instances, but then these instances must be multiplied in the configuration (in the master domain), assigning them different names and ports, and also explicit bindings to instances must be specified in domain accounts (the "esg role RoleID value (serveridxs)" field). Usually this is not required.

Redundancy is possible only if the configuration has several esg microservice instances and the account is not limited to using only one of them. By default each account at any moment is serviced by some one esg instance (provider.opts.instance_count = 1). The responsible one is assigned as the instance most priority in the serveridxs list, or in the domain.settings.ext.default_provider_serveridxs list, not decommissioned and in quorum. When the responsible server with the servicing instance fails, failover to the next priority instance occurs within seconds. When a more priority one recovers, takeover back occurs within seconds.

With deeper configuration the account can be serviced on several esg instances simultaneously.

Viewing registration state

Account and registration state is available:

  • In the domain administrator workstation. (Monitoring - Providers). Only state viewing is available here. But this mode uses an API request whose response body also contains the provider SIP response.

monitoring 01
  • Via HTTP API: /api/monitor/v1/esg/active?regs=true. Here the status of the last response to the registration request is present, as well as the body of this response and the number of active sessions.

Example result:
{
  "resultcode": 0,
  "resultmsg": "OK",
  "data": {
    "sites": [
      {
        "site": "main_site",
        "servers": [
          {
            "srvidx": 1005,
            "node": "esg1@192.168.0.112",
            "addr": "192.168.0.112",
            "online": true,
            "regs": [
              {
                "code": "pbx2",
                "d": "test.incoplax.com",
                "user": "provider",
                "domain": "test.incoplax.com",
                "port": 5060,
                "proto": "udp",
                "addrs": [
                  "test.incoplax.com",
                  "192.168.0.112"
                ],
                "regstate": "registered",
                "pingstate": "disabled",
                "last_response": [
                  "SIP/2.0 200 OK",
                  "Via: SIP/2.0/UDP 192.168.0.112:5080;rport=5080;received=192.168.0.112;branch=z9hG4bK4DVwMd-2bcZ6H",
                  "From: <sip:provider@test.incoplax.com>;tag=3ZxqYI",
                  "To: <sip:provider@test.incoplax.com>;tag=rB2-0GE-3PP1",
                  "Call-ID: Z76iX6vyAeqyWKi9hEp5DHUJ3le",
                  "CSeq: 309187570 REGISTER",
                  "Max-Forwards: 70",
                  "Content-Length: 0",
                  "Contact: <sip:provider@192.168.0.112:5080>;expires=3600",
                  "Supported: path",
                  "Allow: REGISTER,INVITE,ACK,CANCEL,BYE,REFER,NOTIFY,OPTIONS,INFO,SUBSCRIBE,MESSAGE,UPDATE",
                  "Date: Wed, 05 Apr 2023 14:02:41 GMT",
                  "Path: <sip:r_Q4YyzUe@192.168.0.112:5060;transport=tcp;lr>"
                ],
                "onlinetrunkcount": 0
              }
            ]
          }
        ]
      }
    ]
  }
}
  • In the log journal: the server with the esg microservice responsible for servicing the account. The node log folder, sip/trn_*.log.

09:10:33.045	<0.682.0> 	Send to udp 192.168.0.112:5060 (ok)
	REGISTER sip:test.incoplax.com SIP/2.0
	Via: SIP/2.0/UDP 192.168.0.112:5080;rport;branch=z9hG4bK4RfHQ7-aePz3y
	From: <sip:provider@test.incoplax.com>;tag=3ZxqYI
	To: <sip:provider@test.incoplax.com>
	Call-ID: Z76iX6vyAeqyWKi9hEp5DHUJ3le
	CSeq: 309187561 REGISTER
	Max-Forwards: 70
	Content-Length: 0
	Route: <sip:192.168.0.112;lr>
	Contact: <sip:provider@192.168.0.112:5080>
	Supported: path
	Expires: 3600
	User-Agent: Incoplax 1.9.0
	Allow: INVITE,ACK,CANCEL,BYE,REFER,NOTIFY,OPTIONS,INFO,MESSAGE

09:10:33.049	<0.685.0> 	Recv from udp 192.168.0.112:5060
	SIP/2.0 401 Unauthorized
	Via: SIP/2.0/UDP 192.168.0.112:5080;rport=5080;received=192.168.0.112;branch=z9hG4bK4RfHQ7-aePz3y
	From: <sip:provider@test.incoplax.com>;tag=3ZxqYI
	To: <sip:provider@test.incoplax.com>;tag=rB2-0GE-WH5X
	Call-ID: Z76iX6vyAeqyWKi9hEp5DHUJ3le
	CSeq: 309187561 REGISTER
	Max-Forwards: 70
	Content-Length: 0
	Www-Authenticate: Digest realm="b2b_1006__test.incoplax.com", nonce="KXapTShGqTzV5d0QAu7ddHRls9s", algorithm=MD5, qop="auth", opaque="1WVpoo"

09:10:33.060	<0.685.0> 	Send to udp 192.168.0.112:5060 (ok)
	REGISTER sip:test.incoplax.com SIP/2.0
	Via: SIP/2.0/UDP 192.168.0.112:5080;rport;branch=z9hG4bK2w1opp-10Y8e1
	From: <sip:provider@test.incoplax.com>;tag=3ZxqYI
	To: <sip:provider@test.incoplax.com>
	Call-ID: Z76iX6vyAeqyWKi9hEp5DHUJ3le
	CSeq: 309187562 REGISTER
	Max-Forwards: 70
	Content-Length: 0
	Route: <sip:192.168.0.112;lr>
	Contact: <sip:provider@192.168.0.112:5080>
	Supported: path
	Expires: 3600
	Authorization: Digest username="provider", realm="b2b_1006__test.incoplax.com", nonce="KXapTShGqTzV5d0QAu7ddHRls9s", uri="sip:test.incoplax.com", response="e1a569e736485e2eed64af1990cf4727", algorithm=MD5, qop=auth, cnonce="auBMkM6dgdpbzM8neoqG1dxmndx", nc=00000001, opaque="1WVpoo"
	User-Agent: Incoplax 1.9.0
	Allow: INVITE,ACK,CANCEL,BYE,REFER,NOTIFY,OPTIONS,INFO,MESSAGE

09:10:33.072	<0.685.0> 	Recv from udp 192.168.0.112:5060
	SIP/2.0 200 OK
	Via: SIP/2.0/UDP 192.168.0.112:5080;rport=5080;received=192.168.0.112;branch=z9hG4bK2w1opp-10Y8e1
	From: <sip:provider@test.incoplax.com>;tag=3ZxqYI
	To: <sip:provider@test.incoplax.com>;tag=rB2-0GE-QA9Q
	Call-ID: Z76iX6vyAeqyWKi9hEp5DHUJ3le
	CSeq: 309187562 REGISTER
	Max-Forwards: 70
	Content-Length: 0
	Contact: <sip:provider@192.168.0.112:5080>;expires=3600
	Supported: path
	Allow: REGISTER,INVITE,ACK,CANCEL,BYE,REFER,NOTIFY,OPTIONS,INFO,SUBSCRIBE,MESSAGE,UPDATE
	Date: Wed, 05 Apr 2023 06:10:33 GMT
	Path: <sip:r_Q19NAi5@192.168.0.112:5060;transport=tcp;lr>

The packet with registration sent to the provider address and the provider response, as well as all other interactions — pings, invites, etc. — are available in their original form throughout account activity in the log journal.

Attack protection

If the server has an external address on the internet, it is under threat. If arbitrary external addresses can connect to the ESR microservice SIP port, it is an open attack surface. Attacks are carried out by brute-forcing accounts from external systems (sniffers). They send INVITE requests substituting various values and authorization data. If the system starts responding, the sniffer activates and begins intensive credential brute-forcing to break into the number plan.

Attack protection is provided by the border filter. Permission checks are performed based on border filter rules for SIP requests incoming from outside. Filter rule configuration can be performed:

  • From the master domain administrator workstation (Routing - Filter). In card mode, or in advanced mode via JSON (to access specific fields).

  • Via REST API (/rest/v1/master/borderrules).

borderrules 01

Rules can create black/white lists (the list type is determined by the least priority rule without a filter: for a white list with deny, for a black list with allow).

In closed networks the border filter need not be configured, or black lists can be configured.

In open networks a white list should be configured, i.e., allow requests only from specific addresses, and the last priority rule should deny all other requests. The deny mode should be set to 'drop' so that the server does not even react to the incoming request and does not provoke external sniffers to continue credential guessing.

If a rule has only the filter in the "address" field filled, such a request does not pass parsing and is processed directly on the socket. This is much more efficient than other modes.

borderrules 02

Thus the most performance-efficient configuration method is a white list with allow rules for IP addresses and drop mode for all others.

In all other filter configuration cases the SIP request passes parsing, and only after that other filters are checked and the action specified in the rule is applied.

Incoming call

When an incoming call (INVITE) arrives at the esg microservice port, it performs permission checking (discussed above) and account binding.

Account search is performed among all provider accounts (in all domains) currently serviced by the esg instance.

Example INVITE request:
13:26:57.450	<0.1128.0> 	Recv from udp 44.55.66.77:5087
	INVITE sip:00635@172.27.103.90:5080;transport=UDP;user=phone SIP/2.0
	Via: SIP/2.0/UDP 44.55.66.77:5060;maddr=89.232.125.56;branch=z9hG4bK-14c4dd7e-210137c8-fc50302
	From: <sip:8430000000@44.55.66.77:5060;user=phone>;tag=5026-14c4dd7e-1087cebd-14c4dd7e
	To: <sip:1234567890@172.27.103.90:5080;user=phone>
	Call-ID: 40bb12f838738e5913c414c4dd7e210137c8da2fa8102e98aa28-0048-5988
	CSeq: 1 INVITE
	User-agent: SBC/9.0
	Max-Forwards: 63
	Allow: ACK,BYE,CANCEL,INVITE,OPTIONS,INFO,SUBSCRIBE,REFER,NOTIFY,PRACK
	Contact: <sip:44.55.66.77:5060;transport=UDP>
	Supported: 100rel
	Content-Type: application/sdp
	Content-Length: 204

	v=0
	o=X 1357911604 1357911604 IN IP4 44.55.66.88
	s=-
	p=+1 6135555555
	c=IN IP4 44.55.66.88
	t=0 0
	m=audio 48970 RTP/AVP 8 13 101
	a=rtpmap:101 telephone-event/8000
	a=fmtp:101 0-15
	a=ptime:20

Binding algorithm

Suitable account search is performed in several stages.

Stage 1

When an INVITE request arrives, active accounts are iterated and conditions checked. Two fields from the request are compared with two fields from the account. The search function takes two fields, which are sequentially substituted from different headers in 6 stages until the first detection:

1. Search among registered accounts:

1.1. username and domain are taken from the To header. In the example these are "1234567890" and "172.27.103.90".

1.2. username is taken from the To header, and domain from the From header. In the example these are "1234567890" and "44.55.66.77".

1.3. username is taken from Request-Uri, and domain from the From header. In the example these are "00635" and "44.55.66.77".

1.4. username and domain are taken from the Contact header. In the example these are "" and "44.55.66.77".

2. Search among accounts without registration (point-to-point):

2.1. username and domain are taken from the Contact header. In the example these are "" and "44.55.66.77".

2.2. username is taken empty (""), domain from the Contact field. In the example these are "" and "44.55.66.77".

2.3. username is taken from the To field, domain from the From field. In the example these are "1234567890" and "44.55.66.77".

The search function itself compares the passed values:

  • username — matching the account value in the 'username' field or one of the values in the list from the 'opts.extusernames' field.

  • domain — matching the value: either one of the resolved addresses (corresponding to the account domain field or the proxyaddr field), or one of the external addresses of the server where the current esg runs, or one external NAT address. The extaddrs field specifies external addresses, and the address format can be explicit, via masks (for example '44.55.6?.*'), and via regular expressions (for example '/reg/^44[.]55[.]6\\d[.]\\d+$').

If the account is not found by the considered algorithm, the server responds '404 Not Found' and places "EB2B.OutIn. Unknown account in contact" or "EB2B.OutIn. Account not found" in the Reason header. (With the master domain block_response_malware option enabled, no response is sent).

Stage 2

For the suitable account an optional filter function is executed against an object composed of the incoming INVITE request parameters and the provider account object:

{
  "ruri": {
    "user": "1234567890",
    "domain": "172.27.103.90"
  },
  "from": {
    "user": "8430000000",
    "domain": "44.55.66.77"
  },
  "to": {
    "user": "1234567890",
    "domain": "172.27.103.90"
  },
  "contact": {
    "user": "",
    "domain": "44.55.66.77",
    "port": 5060
  },
  "proto": "udp",
  "remote": {
    "addr": "44.55.66.77",
    "port": 5060
  },
  "local": {
    "addr": "172.27.103.90",
    "port": 5080
  },
  "account": {
    "id": "89b132ba-0192-523a-d0e7-7cd30a921f58",
    "code": "provider1",
    "enabled": 1,
    "domain": "provider1.com",
    "username": "",
    "pwd": "",
    "login": "",
    "reg": 0,
    "expires": 3600,
    "transport": "tls",
    "proxyaddr": "",
    "proxyport": 5087,
    "alternative_proxies": "",
    "localdomain": "172.27.103.90",
    "extaddrs": "",
    "certificate_pem": ":SYNC_DOMAIN_DATA/files/certificates/provider1.pem",
    "lic": { "siptrunks": 100 },
    "trunksout": -1,
    "reinvite": 1,
    "media": 1,
    "translit": 0,
    "pingmode": "options",
    "pingsrv": "",
    "pingtimeout": 10,
    "serveridxs": [ 10052 ],
    "refer_mode": "terminate",
    "opts": {
      "title": "provider1",
      "comment": "",
      "extusernames": [],
      "invite_filter": [
        "equals",
        ["property","remote","port"],
        ["property","account","proxyport"]
      ],
      "sip_restore_mode": "replace",
      "deservice_response": true,
      "deservice_sipcode": 503,
      "instance_count": 1,
      "use_billing": false,
      "use_diversion": false
    },
    "ext": {
      "ct": "2024-10-03T11:53:59.271Z",
      "lwt": "2025-01-15T07:38:50.036Z"
    },
  }
}

The filter allows selecting one specific account from several suitable ones by finer parameters. For example, comparing the sender port with the port specified in the account.

If the specific account suitable under the current stage 1 conditions does not pass the filter, the search continues at stage 1.

If no account matches after applying the filter, the server responds '404 Not Found' and places "EB2B.OutIn. Unknown account in contact" or "EB2B.OutIn. Account not found" in the Reason header. (With the master domain block_response_malware option enabled, no response is sent).

By default the filter is not used.

The first suitable account is captured (within the esg/port instance servicing it). This record is placed in a cache by the combination of invite key fields and sender address to improve performance. Cache retention time — 10 minutes; the cache is reset on every change in the composition and characteristics of serviced accounts.

Stage 3.

The server checks the found account for the validity of the sender address. It compares it with the list of resolved IP addresses ('domain' and/or 'proxyaddr'), as well as with the list of 'alternative_proxies' and 'extaddrs' addresses. The latter value can specify, comma-separated, addresses explicitly, via masks (for example '44.55.6?.*', '192.168.0.0/24'), ranges ('/dia/192.168.0.105+4) and via regular expressions (for example '/reg/^44[.]55[.]6\\d[.]\\d+$').

If the account fails the check, the server responds '403 Forbidden' and places "EB2B.OutIn. Unknown remote transport address" in the Reason header. (With the master domain block_response_malware option enabled, no response is sent).

Configuration approach

In most cases there is no need to deal with provider connection specifics; it is enough to create an account and calls start passing.

In complex cases, when incoming calls do not pass and the system returns the specified message, logs should be consulted, the incoming request found and analyzed. Based on the considered algorithm, the cause of non-standard behavior should be identified. As a result, the account should be supplemented with settings. For example,

  • sometimes values of username that regularly appear in the request and do not directly correspond to the account should be added to the 'opts.extusernames' field;

  • sometimes values of domain that regularly appear in the request and do not directly correspond to the account should be added to the 'extaddrs' field. These may be specific addresses and masks, including regular expressions.

  • sometimes external addresses of the platform server that the provider specifies in the To header domain field, as well as gray addresses from SIP-ALG settings, should be added to the 'extaddrs' parameter of the ESG microservice in the configuration.

  • for accounts without registration whose incoming requests arrive with arbitrary usernames from broad ranges, it makes sense to specify an empty value in the username field, thereby enabling processing of any username. And if the contact address field or sender peer address also changes over a broad range, specify addresses as masks in extaddrs.

If the account is found, the addresses matched to it are compared with the INVITE packet sender address (domain, proxy server address, domain name resolution results, address masks specified in the account). On success the call is passed for servicing — a second leg is created toward the b2b microservice.

General technique for complex configuration:

  • analyze several INVITE packets from different provider calls;

  • extract the To, From, Contact headers, and within their values separate username and domain — 6 fields are obtained;

  • identify among them fields with constant values clearly indicating the provider account (rather than a subscriber or another provider account), and fields with variable values;

  • match the constant values with the verification algorithm given above.

If a registered provider specifies in the INVITE To header domain field the external IP address of the server with ESG, and unambiguous provider account matching is performed by username in the To header of incoming INVITE requests, then this address should be added to the 'extaddrs' list of ESG microservice parameters in the configuration (except when this is the only server address determined via a STUN request).

It is important to remember that when using the built-in SIP-ALG, white addresses will be substituted with gray ones, and account settings must account for this. In the previous case the gray address must be added to the 'extaddrs' list of ESG microservice parameters.

Multiple instances

By default one account is serviced on one esg instance.

When there are several instances, the account moves to another instance when the responsible one is lost. A registered account sends a REGISTER packet reporting the new contact address. An unregistered account assumes the external system must be preconfigured for possible contact address movement.

In special cases it may make sense to maintain account activity simultaneously on several esg instances (opts.instance_count). Such a configuration assumes each external call will arrive at only one of the contact addresses. This is more applicable to unregistered accounts (peer-to-peer), when the provider-side SBC can iterate contact addresses on no-answer or errors. But for registered accounts too, the '+sip.instance' and 'reg-id' options are added to the contact address according to RFC-5626.

Outgoing call

To make an outgoing call through a provider account, in the routing rules of the same domain it should be directed to the external contour and the provider account code specified.

Routing is performed by the b2b microservice. Before sending the call to the corresponding esg account, its availability and the account availability are checked. If its state is inactive, or the established limit for simultaneous sessions is exceeded, routing moves to the next priority rule.

If there are several rules with the same priority, their traversal order is random each time. This can be used to distribute outgoing calls across two or more accounts.

Since the outgoing call arrives at esg from inside, from the b2b microservice, the second leg is sent outside to the provider.

Routing configuration.

The esg microservice separates two number plans — the internal number plan and the external number plan (PSTN or external PBX). There is probably a difference between these number plans. For example, outside there are 10-digit numbers and inside 4-digit.

When calling across this boundary numbers mostly require modification.

Normalization rules (number substitution on esg).

Normalization rules can be bound to specific accounts (by identifier) or to a group (via masks for the code field), including binding a rule to all accounts by filling 'providercode' = "*".

The task of normalization rules: bring the incoming call initiator to the internal number plan, and the outgoing call initiator to the external number plan. That is, the INVITE call parameters arriving at ESG differ from the INVITE call parameters sent further. The normalization process lies between them. In particular, without explicit normalization rules, calls are redirected with the following changes:

  • incoming provider calls: From username — unchanged, To username — becomes empty, From domain and To domain — the system domain is substituted where the provider account matched to the call was created.

  • outgoing system calls: From username — unchanged, To username — unchanged, From domain and To domain — the provider domain specified in the account.

A common operation is creating a normalization rule for the outgoing direction of a registered account and substituting the account name as 'from username'. Without this, calls pass with the number determined during routing in the internal number plan. A special case is the application of representation rules that pre-substituted the external number for the subscriber based on complex configured logic.

Thus, normalization rules are configured separately for the incoming and outgoing directions.

Normalization rules can be tested in the administrator workstation (Routing - Testing - Substitution).

Route for incoming.

Arriving at b2b, the INVITE request has already passed normalization and is bound to the internal number plan. A call arriving from a provider can be routed in any way, like other calls. Provider calls are usually routed:

  • to voice services (IVR);

  • to CC queues;

  • to group numbers;

  • to personal internal numbers if the number is allocated as personal, or answering questions is part of the account owner’s tasks.

Obviously they can be sent to other domains, redirected outside via other providers, or refused service.

Permission to dial extension numbers (in IVR) and send them to various services without verification and additional filters should be avoided.

Route for outgoing.

To send a call to a provider, configure a rule with the 'external' action and specify the provider code. The behavior algorithm was discussed earlier in the "Outgoing call" section.

Log journals.

Log journals concerning work with telephony provider accounts are kept by esg microservices. The 'log_trn' parameter must be enabled in the configuration for the corresponding esg instance. For extended logging, set TRACE or DEBUG logging mode in the node management section (master domain administrator workstation - System - Nodes).

Log journals are in the directory specified at installation. By default this is '/opt/ERA_INSTANCE_NAME/log' on the host and '/var/log/era' in the container. The full path to the esg log directory may look like: '/opt/ERA_INSTANCE_NAME/log/esg1@SERVER_ADDR/sip'

In the 'trn_*.log' log journal all packets (for all providers) can be found. In 'erl_*.log' detailed traces of the registration process can be found.

Activity for all providers is placed in the log journals. In debug mode it may be convenient to create a separate microservice instance with low priority (high 'roleid' parameter value in the configuration) and bind the account under investigation to it (by setting the RoleId value in the serveridxs account field).

Registration

For registered providers, to track registration process correctness, REGISTER requests can be searched, for example:

Example of successful registration:
09:10:33.060	<0.685.0> 	Send to udp 192.168.0.112:5060 (ok)
	REGISTER sip:test.incoplax.com SIP/2.0
	Via: SIP/2.0/UDP 192.168.0.112:5080;rport;branch=z9hG4bK2w1opp-10Y8e1
	From: <sip:provider@test.incoplax.com>;tag=3ZxqYI
	To: <sip:provider@test.incoplax.com>
	Call-ID: Z76iX6vyAeqyWKi9hEp5DHUJ3le
	CSeq: 309187562 REGISTER
	Max-Forwards: 70
	Content-Length: 0
	Route: <sip:192.168.0.112;lr>
	Contact: <sip:provider@192.168.0.112:5080>
	Supported: path
	Expires: 3600
	Authorization: Digest username="provider", realm="b2b_1006__test.incoplax.com", nonce="KXapTShGqTzV5d0QAu7ddHRls9s", uri="sip:test.incoplax.com", response="e1a569e736485e2eed64af1990cf4727", algorithm=MD5, qop=auth, cnonce="auBMkM6dgdpbzM8neoqG1dxmndx", nc=00000001, opaque="1WVpoo"
	User-Agent: Incoplax 1.9.0
	Allow: INVITE,ACK,CANCEL,BYE,REFER,NOTIFY,OPTIONS,INFO,MESSAGE

09:10:33.072	<0.685.0> 	Recv from udp 192.168.0.112:5060
	SIP/2.0 200 OK
	Via: SIP/2.0/UDP 192.168.0.112:5080;rport=5080;received=192.168.0.112;branch=z9hG4bK2w1opp-10Y8e1
	From: <sip:provider@test.incoplax.com>;tag=3ZxqYI
	To: <sip:provider@test.incoplax.com>;tag=rB2-0GE-QA9Q
	Call-ID: Z76iX6vyAeqyWKi9hEp5DHUJ3le
	CSeq: 309187562 REGISTER
	Max-Forwards: 70
	Content-Length: 0
	Contact: <sip:provider@192.168.0.112:5080>;expires=3600
	Supported: path
	Allow: REGISTER,INVITE,ACK,CANCEL,BYE,REFER,NOTIFY,OPTIONS,INFO,SUBSCRIBE,MESSAGE,UPDATE
	Date: Wed, 05 Apr 2023 06:10:33 GMT
	Path: <sip:r_Q19NAi5@192.168.0.112:5060;transport=tcp;lr>

Examples of failed registration:

  • sending several REGISTER requests in a row with growing pause between them and no response to them.

  • the word BANNED in the Recv line (for example: 15:00:11.042 <0.692.0> Recv from udp 192.168.0.112:5060 BANNED) — means the border filter is enabled but the sender address is not in the allow list. If the address corresponds to the one the server sent REGISTER to before, this is the cause.

Calls

A call is initiated by an INVITE request. To analyze what happens with INVITE packets: find the packet in the log journal, find other session packets by Call-Id, find the response. In case of platform refusal, the Reason header revealing refusal details can be found in the response.

If an external call does not pass and no INVITE is found, the following options are possible:

  • The word BANNED is found — check provider addresses for inclusion in border filters.

  • Account without registration, esg port differs from the port the provider sends requests to. For example the provider sends to 5060, while the platform esg default port is 5080.

  • Packet tracing can be used; in this case tracing goes below the platform in the operating system and can show packets actually arriving at the server. The real port can also be found there. Utilities tcpdump, tshark can be used.

Example traffic trace with address 44.55.66.77:
mkdir pcaps
sudo chmod 777 pcaps
sudo tshark -i eno1 -f "host 44.55.66.77" -w pcaps/trace.pcap
ps ax | grep tshark
sudo chmod 775 pcaps/trace.pcap
rsync -avrh --progress pcaps/trace.pcap ...
sudo rm -r pcaps
Example tcpdump trace:
tcpdump -i any -nn -w temp.pcap

In any case of call passing complications, SIP traffic must be analyzed. These are trn logs on all microservices servicing SIP: esg, b2b, sg, ivr, conf, prompt.

Diagram

If the call reached b2b and a dialog was created, it can be found in the domain administrator workstation (Monitoring - Calls).

calls 01

And by selecting it with the cursor — execute the "Diagram" action. As a result, if trn logs are enabled on the microservices the call passed through, a sequence diagram with access to all packets related to the call is built on the screen.

diagram 01
diagram 02

esg logic

esg logic corresponds to b2bua mode (back-to-back useragent). That is, each incoming call forms a dialog and a second leg. Esg always generates a new Call-Id for the second leg.

esg never relays REFER to the other leg but processes it locally, creating a new fork toward the same side from whose leg the REFER request came. This guarantees the call is directed to the correct number plan. Correct means matching the number for call transfer. This also means the platform without additional modification cannot be configured to redirect a call without internal processing.

Each provider account can work either in reinvite pass-through mode, or in local media processing mode, or both, but at least one mode.

Reinvite pass-through mode means each session change is relayed through esg to the opposite leg without SDP change.

Local media processing mode ('media'=true). Then it terminates all re-INVITE requests within the dialog, processing them locally by media configuration. For this the bgmg media gateway is used, located on the same server as the esg instance. This mode can be useful if connection to the provider requires guaranteeing media data is sent from the same address as signaling SIP traffic, or, for example, the number of addresses in the provider dedicated vlan subnet is narrowly limited and cannot be expanded for all platform cluster servers. When using local media processing mode, signaling traffic can be terminated on the leg (reinvite=false) or relayed to the opposite leg with SDP change (reinvite=true).

By default reinvite=true and media=false are used, suitable for the vast majority of installations.

Which codecs esg offers and accepts in each mode — in the article Codecs and media negotiation.

Registration on itself (testing)

It is allowed for the provider to be registered on the platform itself as a subscriber device. This allows limited functionality testing. To bring up a call in this case, call the internal number under whose account the provider is registered. This can be another domain or the same one.

This mode is used in particular when organizing load testing.

Since esg completely replaces CallId when sending a call to another leg, there is no problem with parasitic looping.

Network interfaces and ports

esg instances, like other microservices responsible for SIP signaling, bring up listeners on all interfaces (0.0.0.0). Ports are specified in the configuration for each individual microservice instance, but the specified ports relate to all interfaces of the corresponding server. This means the platform without additional modification cannot be finely configured to listen on specific ports on specific interfaces.

In template configurations the esg role is assigned ports 5080, 5081. On these ports listeners are brought up on all interfaces of the server where the corresponding esg instance runs, and UDP signaling packets are sent from them.

There are cases where a specific provider requires port 5060 from the client. In this regard port 5060 should be configured for esg. Then ports for sg instances may also need to be changed. The only exception may be when esg and sg instances run on different servers. In decreasing order of convenience the following options are recommended:

  1. Change the provider requirements by allowing the client to use local port 5080.

  2. Separate esg and sg instances onto different servers with sufficient quantity, and use 5060 for both types.

  3. Change ports — 506X for esg, 508X for sg. Requires reconfiguring all internal devices previously configured to connect to the server on port 5060.

Using bgmg

The indication for using bgmg is only one of the situations in a multi-server platform deployment:

  • the subnet the provider belongs to is not routed from part of the deployed platform cluster servers (more precisely: from part of the servers where mg runs);

  • the provider requires matching client addresses for signaling and media traffic.

For such providers media=true and reinvite=false must be enabled. And to support this mode, pairs of bgmg instances must be added to the configuration on the same servers where esg runs (which, according to account settings and placement, can service them)

Working behind NAT

Telephony providers in the vast majority of cases work with devices connected from behind NAT. These devices are diverse and NAT settings are diverse, so to reduce problem situations, sound is usually sent to the address and port from which sound arrives at the port announced by the provider in SDP. This behavior allows ignoring problems with two-way sound.

If one-way audibility is observed in such a configuration, direct port mapping on NAT should be configured. This may be required if:

  • Configuration is with an external PBX or provider that does not support or is not configured to send RTP packets to the reverse sender address of incoming RTP.

  • It is necessary to be able to route an incoming call directly to an external number behind the same account.

The platform itself always redirects packets to the reverse sender address of incoming traffic. This algorithm shows its statistical superiority.

SIP-ALG

A special NAT case when the server is externally accessible by a white address absent from local interfaces.

In this case, and possibly some others, address substitution in packets is required — local (gray) to external (white) in outgoing packets, and external (white) to local (gray) in incoming packets. For this SIP-ALG can be configured on the network router, or if impossible, this option can be configured in the esg instance settings.

Every packet passing through an instance configured this way will be modified. Addresses are substituted according to packet direction. For incoming packets modification is performed right after the SBC filter, before routing and number normalization. For outgoing packets modification is performed after routing and normalization, right before sending to the network.

SIP-ALG configuration assumes unconditional 1-to-1 substitution of local (gray) address to external (white) address. There can be several such pairs. For example:

  "sip_alg": [
    {"gray":"172.16.0.14","white":"62.85.127.4"},
    {"gray":"172.16.0.15","white":"62.85.127.5"}
  ]

Provider connection over TLS

TLS connection is performed in both directions — from platform to provider and from provider to platform. The procedure for configuring a registered account and an unregistered account differs.

The remote side must connect to the port with certificate validation. This is especially critical for unregistered connections and for clients validating a trusted chain. As a rule equipment connects without SNI directly to the IP address — it is either registered initially (unregistered connection) or is the contact address from the registration request (registered connection).

For TLS connections (and even for each TLS connection) a separate ESG instance can be created in the configuration on a unique port with a certificate configured for this instance (certdir parameter). By default, without certdir and SNI in TLS Client Hello, a self-signed certificate is issued (which has problems passing chain authenticity validation on the client side).

Thus the system has an ESG instance for which the current certificate is set by configuration. The trusted chain of this certificate can be passed to the remote side on request.

When configuring a provider account, it must be bound to the above-mentioned ESG instance if there are several (srvidxs parameter). The connection must be serviced by the instance using by default the certificate (certdir) whose trusted chain was passed to the provider for TLS connection configuration.

In turn, if a trusted chain of the provider certificate is received, it should be placed in a PEM file and the macro path to it specified in the provider account certificate_pem parameter. For example, having uploaded the certificate to the /rest/v1/fs/targets/files/certificates/some.pem endpoint, the path can be specified as ':SYNC_DOMAIN_DATA/files/certificates/some.pem'.

For the platform to successfully validate the trusted certificate chain, it is important that the domain (or proxy address) specifies the name for which the certificate was issued. It can be found in the Server Hello message from the provider in the TLS connection dump.
If chain validation difficulties arise, the 'certificate_pem' field can be left empty. Then in platform versions 1.8.* trusted chain validation will not be performed.

The connection progress at the configuration stage can be monitored using ESG log journals and TSHARK traces taken on the server with ESG filtered by the remote side IP address.

When configuring an unregistered account, attention should also be paid to the 'localdomain' field value. The domain name or address by which provider connection is possible should be explicitly placed there. When connecting through NAT, corresponding settings must be made.

For TLS connection to use an encrypted media traffic channel (SRTP), the following is required:

  • enable the 'use_srtp' option in the configuration of the corresponding ESG.

  • ensure the configuration has bgmg microservices on the same server as ESG.

  • enable the 'media' option in the provider account — use the border media gateway.

If different connections must use different ports, own local certificates, SRTP modes, they should be bound to different ESG instances.

Redundancy

Simplest redundancy cases

The simplest redundancy method is available for registered accounts. If the configuration has several esg instances, if all are available and active, if no restrictions on their use are set, the account can be serviced on any of them, and the contact address is updated on registration.

The system monitors esg instance activity and promptly transfers servicing responsibility to available instances.

In this case redundancy of external connection points is provided by specifying one or more alternative outbound proxy servers. When registering with the main proxy server, on failure the next from the alternative proxies list is used.

On success, regular availability checking of the selected proxy server by ping can be used. Regular re-registration also provides an additional rarer availability check. On failure the responsible instance marks the account temporarily unavailable and initiates a reconnection process. Outgoing calls through an account marked temporarily unavailable are impossible, and during routing the next suitable routing rule is searched. Based on this, several different provider accounts can be used to ensure the ability to make calls.

Virtual IP addresses

Unregistered accounts assume P2P (peer-to-peer) connection; in each of the paired systems a connection point to the opposite system is configured.

virtualipesg

If the remote system is functional enough to make a call to another address when the main one is unavailable, the simplest redundancy case also applies. Responsibility for servicing the account is automatically transferred from the unavailable esg instance to the available one. If a request arrives at an instance that currently does not service the account, it either responds with failure or stays silent (when failed response suppression mode is set).

In other cases a virtual IP address is available for configuration. It is the virtual IP address that is reported to the external system. The platform makes active only the esg instance on whose server the used virtual IP address is detected. On the inactive instance the SIP signaling servicing service is unloaded and ports are not listened on.

Virtual IP address tracking and reassignment can be organized by external tools (for example keepalived) or by the platform’s own tools (virtualip_automation).

Parallel servicing

simultaneous

The platform can support several services simultaneously servicing the account. This is configured by the provider.opts.instance_count option.

This means readiness to accept a call arriving at any of the servicing ESG instances, as well as making an outgoing call through one of them that confirms its activity and connection availability.

Each esg instance servicing the account in parallel can connect to separate edge/outbound proxy servers. This allows having different paths and reserving external connection points.

For registered accounts each parallel instance forms a contact address with +sip.instance and reg-id parameters according to RFC-5626. This allows the external system to treat several registrations as standby, making a call to the contact address of only one of them.

To connect different esg instances to different edge-proxy servers, the opts.edge_proxies list must be specified in the account. Then the main proxy server will be used only for instances for which there are not enough values in the edge_proxies list. The edge_proxies lists are distributed across esg instances allowed to service the account (serveridxs) in strict priority order. If the priority esg instance is unavailable, its corresponding edge_proxies list is not used by other instances.