External SIP Gate (esg)

Description

SIP access point to the cluster for external devices: telephony providers, gateways, and upstream and peer PBXs located in an external number plan not managed by the system. All work is based on SIP provider accounts. CallerId and CalledId transformation rules (provider_callerid) are used to interconnect the internal number plan with peer and upstream PBXs and providers.

Processes requests in user-agent mode. One leg is always an external subscriber; the other leg is always an internal server with the b2bua role.
The media gateway is used when the call is associated with a provider account that has the "media" option enabled.

Is a border role for the SIP interface.
Protects the cluster from unwanted external requests using border filters based on static rules and dynamic lists of temporarily banned addresses.
Can use the bgmg role to interconnect different networks. The media gateway through the bgmg role is used automatically when multiple network interfaces are detected and when proxying a request from one subnet to another.
For this mode to work correctly, one or more bgmg role instances with non-overlapping port settings must be present on the server with the esg role.

Made redundant and scaled in Active-Active mode.
Each provider account is bound to a specific esg role instance running on one of the sites where the domain is served.

Read more about working with telephony providers.

Table 1. System characteristics

Code

esg

Operation mode

Service

Redundancy mode

Active-Active

Site types

Any

Layer

Business logic

Placement

Border

State preservation and recovery on restart

No

Application

era_sip

Limitations

  • REFER and INVITE+Replaces requests are always processed mirrored, that is, within the direction from which the request was received.

  • Is a border role and uses a TLS certificate for HTTPS and WSS connections.

Parameters

Table 2. Parameters
Name Type Default Description

name

str

required

Name. May consist of Latin letters and digits and must start with a letter.

roletype

str

required

Role type. Possible values: "esg".

ext

json

empty

Additional role options. Contains a JSON object or list.

enabled

bool

empty

Role activity flag. When set to false, the role does not participate in validation and is not started.

limit_of_cores

int

empty

Limit on the number of CPU logical cores used. Default: 0 - unlimited.

logging_default_level

int

empty

Default logging level set specifically for the role instance (microservice type). More

allow_divergence

bool

false

Flag allowing parameter differences in roles of the same group. Default: false - not allowed.

roleid

int

required

Role identifier.
Unique across the entire system, regardless of site or server. Cannot be changed.
An integer from 1 to 9999.

separate

bool

required

Flag indicating whether the role is allocated to a separate node.

udp

int

required

Local UDP port for SIP. The same port also handles TCP.
For example: 5080.
Raises a UDP listener on the wildcard interface '0.0.0.0' or on the interfaces specified by the 'sip_ifaces' parameter.

tcp

int

required

Local TCP port for SIP. If a value different from UDP is specified, it is opened additionally.
For example: 5080.
Raises a TCP listener on the wildcard interface '0.0.0.0' or on the interfaces specified by the 'sip_ifaces' parameter.

tls

int

empty

Local port for TLS connections. Not opened by default.
For example: 5081.
Raises a TLS listener on the wildcard interface '0.0.0.0' or on the interfaces specified by the 'sip_ifaces' parameter.

sip_internal_port

int

empty

Local port for SIP interaction with other system microservices (UDP/TCP).
For example: 6180.
Used for internal interaction with other system microservices over SIP.
Applied when a list of specific port listener interfaces ('sip_ifaces') is set for the microservice.
Listens only on the local interface of the node.
Must not be used by other microservices running on the same server.

sip_ifaces

array<str>

[]

List of server interfaces on which port listeners are raised.
Specified by server interface aliases.
If no interface is specified, the configured ports listen on all interfaces (0.0.0.0).

For sg, esg, and redirect roles running on the same server, the same values can be specified as external ports (udp, tcp, tls, wss) if their listen interface lists do not overlap.

The original interface of the current node is always added to the listen interface list (except when a virtual address exists in the same subnet). The listener is raised on the 'sip_internal_port', which must not be used by other microservices on the same server.

If any specified network interface is not up when the server starts, the listener does not start. After it appears, the microservice node must be restarted to start the listener.

virtual_ifaces

array<str>

[]

List of monitored virtual interfaces (Virtual IP).
Specified by server interface aliases marked with the 'virtual' flag.
If none is specified, the service starts normally on static addresses according to the sip_ifaces setting.

If some virtual interfaces are specified in the list, the SIP gateway instance monitors their appearance before starting the target service.
The absence of at least one virtual address from the specified list among the server’s available interfaces causes the service to be unloaded and wait for all addresses to appear.
Virtual interface availability is checked every 2 seconds.

The specified virtual interface is always used by the SIP gateway for its primary purpose.

Virtual addresses may have static equivalents. For example, static address 192.168.0.101 and virtual 192.168.0.100.
In this case, the service behavior differs depending on which aliases are specified in the sip_ifaces list:

  • If only the virtual address is present in the list, it is used as the primary address, and outgoing interaction uses the virtual address (bind, Via, Record-Route).

  • If both static and virtual addresses are present in the list, both listen for incoming requests, and the most appropriate address for interaction with external devices is determined by the routing table. Presumably, all outgoing interaction will be bound to the static address.

  • If only the static address is present in the list, the virtual one is also added automatically, and their use is similar.

  • If the list is empty, the service serves all interfaces (0.0.0.0), and their use is similar.

This leads to the conclusion: if there are no virtual addresses in the internal cluster subnet, or the primary static addresses in the subnet are used alongside the virtual SIP gateway, then conversation recovery will necessarily require replacement (INVITE+Replaces). In other cases, seamless recovery options are possible. This applies only to calls without bgmg on multi-server systems where all other microservices remain operational.

The target use of a virtual interface assumes the following combination of settings:

  • creating a virtual address for the internal cluster subnet;

  • creating a virtual address for the external subnet;

  • specifying both virtual interfaces in the sip_ifaces list;

  • the absence in the sip_ifaces list of static addresses from the same subnets;

  • having another server in the cluster for which the same addresses are similarly configured as virtual;

  • having another SG microservice instance bound to that server for which the same interfaces are specified as virtual.

log_cdr

bool

true

Switch for logging events to the cdr log.

log_closure

bool

true

Switch for logging Call-ID closures of different legs/dialogs to build sequence diagrams. When this log is enabled, the retention time of links in node memory (sip_stat_timeout_closure) can be reduced to save memory: volume estimate.

log_media

bool

true

Switch for logging media functions to the media log.

log_mgct

bool

true

Switch for logging the MGC controller interaction protocol to the mgct log.

log_sip

bool

true

Switch for logging the dialog state machine trace to the sip log.

log_trn

bool

true

Switch for logging SIP traffic to the trn log.

use_srtp

bool

false

By default, when initiating calls to addresses connected over TLS, an SDP offer for unencrypted media (RTP) is sent. This parameter can enable an SDP offer with an encrypted media stream for TLS addresses.
Applied only to calls using the border media gateway (media=1).

use_srtp_setup_timeout

bool

true

Switch for monitoring TLS connection establishment.
Applied only to accounts using the border media gateway, and for the external leg the media session is established over a secure protocol.
The timer is started for any SRTP leg when both local and remote SDP have been passed to the border media gateway.
The timeout is set by the media gateway parameter srtpsetuptimeoutms, default 3000 ms.

Changing the default settings may be required, for example, if the remote side does not initialize the media connection upon receiving a preliminary 183 response with SDP.
The enabled option terminates the connection and ends the dialog after 3 seconds, preventing dialogs where subscribers cannot hear each other.
The disabled option allows the dialog to continue even though the softphone subscriber will not hear early media.
A similar result can be achieved by significantly increasing the timeout in border media gateway settings.

certdir

str

empty

Alias of the server directory for storing certificates ('server.crt' and 'server.key' files).
If the path is not specified, certificates are searched in the "/usr/lib/era/era_sip/priv/ssl" directory

keypass

str

empty

Password for decrypting the certificate private key file. Secret: ciphertext when read; the plaintext value is not returned via API and is decrypted by the service when used; a plaintext value can be supplied on input (Encryption and keys).

payloads_audio_offer

array<str>

["PCMA/8000", "PCMU/8000", "telephone-event/8000"]

List of audio codec names used to initiate a call (leg call).
Applied only when using media call servicing through bgmg.

The value is a list of audio codec names in "Name/Freq" format.
The following codecs are supported (case-insensitive):

  • telephone-event/8000,

  • PCMU/8000,

  • PCMA/8000,

  • GSM/8000,

  • G722/8000,

  • G729/8000,

  • CN/8000,

  • speex/8000,

  • speex/16000,

  • speex/32000,

  • G726-16/8000,

  • G726-24/8000,

  • G726-32/8000,

  • G726-40/8000,

  • iLBC/8000,

  • opus/48000/2.

Codecs are offered in list order. The base PCMU/8000, PCMA/8000, and telephone-event/8000, if not listed, are added after the listed ones. The - prefix excludes a codec from those added (-PCMU/8000; - — all unlisted base codecs); the -- prefix additionally excludes it from the SDP of the incoming call passed to the other leg (-- — all unlisted incoming codecs; the offer is built in list order). CN/8000 and telephone-event/8000 are placed at the end. For example, ["G722/8000", "PCMA/8000", "-PCMU/8000"] — G722, PCMA, telephone-event; ["PCMA/8000", "-*"] — only PCMA. See Codecs and media negotiation.

The parameter is overridden by a non-empty value of the provider.opts.payloads_audio option for calls whose leg is the corresponding provider account with media mode enabled.

payloads_video_offer

array<str>

empty

List of video codec names used to initiate a call (leg call).
Applied only when using media call servicing through bgmg.

The value is a list of video codec names in "Name/Freq" format.
The following codecs are supported (case-insensitive):

  • H263/90000,

  • H263-1998/90000,

  • H264/90000,

  • VP8/90000,

  • VP9/90000.

use_video_transcoding

bool

false

Video transcoding switch.
Applied when using bgmg.

  • false – all video codecs from the SDP of the INVITE request received from the initiator are forwarded unchanged in the SDP of INVITE requests to the called devices. In this case the system applies neither its codec knowledge nor transcoding; even if a codec is unknown to the system, direct forwarding remains possible.

  • true – all video codecs are brought into line with the video codecs known to the system; the system offers the called side all codecs it knows (filtered by payloads_video_offer), and if the codecs selected by the devices do not match, the video stream is transcoded.

max_udp_size

int

1500

Maximum UDP packet size sent by the system, in bytes.
Minimum value: 1500.
If a sent packet exceeds the configured size, it is automatically sent over TCP.
If a sent packet exceeds size 1500 but is within the configured value, the packet is automatically split into frames and reassembled at the lower network layer.
Not all devices support this mode. At the same time, not all devices keep TCP open.

b2bmedia

bool

true

Switch for using the media gateway by the b2b role for calls initiated by the current esg role instance.

extaddrs

array<str>

empty

List of IP addresses of the current server.
Used in one of the provider account lookup algorithms when receiving INVITE requests from outside, allowing one of the listed addresses to be specified as the domain in the "To" header.
Usually this field is not needed because the required value can be specified in provider account settings.
However, to optimize and avoid specifying the same values in many provider accounts, they can be specified in the esg role option.

stunserver

array<str>

empty

List of external STUN servers for determining the server’s external IP address when operating behind NAT.
Used in one of the provider account lookup algorithms when receiving INVITE requests from outside, allowing the external NAT address to be specified as the domain in the "To" header.
The value format is a list of URIs like 'sip:<DomainOrAddress>:<Port>'

sip_alg

array<object>

empty

White address substitution.
If the system is installed behind NAT relative to subscriber devices, the sip-alg mode on NAT must be used.
Sip-alg substitutes addresses in packets sent outside and received from outside.
The SIP-ALG function can be activated on border roles. This parameter sets the set of local cluster addresses to be substituted with white external addresses.

Format:
[{"gray":"IpAddr", "white":"IpAddr"}, ...]

The list must contain the addresses of all servers where media gateways are located, as well as the local interfaces of the current machine from which routing to all external addresses is performed.
All packets sent to addresses not belonging to the cluster are subject to gray-to-white substitution.
All packets received from addresses not belonging to the cluster are subject to white-to-gray substitution.
If other devices and systems in the local network loop but not belonging to the cluster must connect to the system, a second role instance with sip-alg disabled (this parameter absent or empty) must be used.

sip_mod_codes

array<str>

empty

Group codes of the full-text SIP message modification rules applied by this instance (sipmodrules).

fwd_headers

array<object>

empty

Header forwarding.
ESG services calls in B2BUA (back-to-back user agent) mode. A separate leg with a unique Call-ID is created for each participant.
When forming an outgoing INVITE request, ESG by default does not add custom headers from the incoming INVITE request.
To ensure that certain custom headers from the incoming INVITE request are added to the outgoing INVITE request, provide a list of their names.

Format:
["X-Header-1", "header-2", ...]

Empty by default.

anti_spam_enabled

bool

true

Forced spam filter switch for the microservice instance.
The limit density is configured by border filter rules and the master domain parameter mps_limit_defaults → sip.

By default, the spam filter is not blocked but is inactive because master domain settings do not set the limit density.

tls_ciphers

array<str>

empty

Additional TLS cipher suites (OpenSSL names, e.g. ECDHE-RSA-AES256-GCM-SHA384) prepended to the default cipher list. The value "*" enables all supported ciphers.

wss

int

empty

Local WebSocketSecure port for SIP (1 - 65535). Not opened by default.

Configuration example

Configuration management is performed in an application available to master domain administrators. The application hides the full configuration content, but it is still available through the API.

The configuration contains a section describing all instances of all roles. Parameters are defined for each specific role instance.

Node example
{
  "name": "esg12",
  "roletype": "esg",

  "roleid": 11260,
  "separate": true,
  "tcp": 5080,
  "udp": 5080,
  "tls": 5081,

  "log_cdr": true,
  "log_trn": true,
  "log_sip": true,
  "log_media": true,
  "log_mgct": true,

  "certdir": "/var/lib/era/certificates",
  "keypass": "eb9c4458016d3f1e378d02004c4f4f50",
  "max_udp_size": 10000,
  "stunserver": ["sip:stun.sipnet.ru:5060", "sip:demo.era.ru:5060"],

  "sip_alg": [
    {"gray":"172.16.0.14","white":"62.84.126.3"},
    {"gray":"172.16.0.15","white":"62.84.126.6"}
  ],

  "fwd_headers": [
    "X-Header-1",
    "X-Header-2"
  ]
}

See also