External SIP Gate (esg)

Description

Access point to the cluster via SIP for external devices - telephony providers, gateways and upstream and peer-to-peer PBXs that are in an external number plan not managed by the system. All work is based on the accounts of SIP providers. For docking the internal number plan with peer-to-peer and upstream PBXs and providers, the CallerId conversion rules and CalledId (provider_callerid).

Processes requests in the user-agent. One arm is always the external subscriber, the other arm is always the internal server with the role of b2bua.
Media Gateway applies when a call is associated with a provider account that has the option enabled "media".

Is a boundary role for the interface SIP.
Protects the cluster from unwanted external requests using boundary filters based on static rules and dynamic lists of temporarily banned addresses.
Can use the bgmg role to address the issue of docking different networks. Media gateway via the bgmg role is applied automatically when multiple network interfaces are detected and when proxying a request from one subnet to another.
For the mode to function properly, the server with the esg role must have one or more instances of the bgmg role with non-overlapping port settings.

Reserved and scaled in mode Active-Active.
Each provider account is assigned to a specific instance of the esg role running at one of the sites where the domain is served.

Read more about working with telephony providers.

Table 1. System Characteristics

Code

esg

Mode of operation

Service

Backup mode

Active-Active

Types of sites

Any

Layer

Business logic

Placement

Frontier

Saving and restoring state on reboot

No

appendix

era_sip

Limitations

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

  • Is an edge role, uses a TLS certificate for HTTPS and WSS connections.

Parameters

Description of columns in the table

Table 2. Parameters
Name Type Default Description

name

str

required

Name. May consist of Latin letters and numbers, must begin with a letter.

roletype

str

required

Role Type. Possible values: "esg".

iface

str

required

The alias of the server network interface on which the roles will interact internally with each other.

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.

roleid

int

required

Role ID.
Unique for the entire system, regardless of the site or server. Cannot be changed.
Integer from 1 to 9999.

separate

bool

required

An indication that the role has been allocated to a separate node.

udp

int

required

Local UDP port for SIP. The same port handles both TCP.
For example: 5080.
Raises a UDP listener on group interface '0.0.0.0.0', or the interfaces specified by the parameter 'sip_ifaces'.

tcp

int

required

Local TCP port for SIP. If a value other than UDP is specified, it will be raised additionally.
For example: 5080.
Raises a TCP listener on group interface '0.0.0.0.0', or the interfaces specified by the parameter 'sip_ifaces'.

tls

int

empty

Local port for tls connections. Does not open by default.
For example: 5081.
Raises a TLS listener on group interface '0.0.0.0.0', or the interfaces specified by the parameter 'sip_ifaces'.

sip_internal_port

int

empty

Local port for SIP interaction with other system microservices (UDP/TCP).
For example: 6180.
Used for internal communication with other microservices of the system via protocol SIP.
Applies if a list of specific port listener interfaces is defined for the microservice ('sip_ifaces').
Raised only on the local interface of the node.
Should not be used by other microservices executing on the same server.

sip_ifaces

array<str>

[]

A list of server interfaces on which port listeners are raised.
Interface aliases are specified servers.
If no interface is specified, the specified ports are listened to on all interfaces (0.0.0.0).

For sg, esg, redirect roles executed on the same server, the same values can be specified as external ports (udp,tcp,tls,wss) if their list of listened interfaces do not overlap.

The original interface of the current node with port 'sip_internal_port' is always added to the list of listened interfaces, which should not be used by other microservices on the same server.

If any of the specified network interfaces is not up at the moment of server startup, the listener is not started. After its appearance, the microservice node must be restarted to start the listener.

log_cdr

bool

true

Switch for logging events to log cdr.

log_media

bool

true

Media function logging switch media.

log_mgct

bool

true

Switch for logging the communication protocol with the MGC controller to the logger mgct.

log_sip

bool

true

Switch for logging dialog state machine trace to logs sip.

log_trn

bool

true

SIP traffic logging switch to log trn.

use_srtp

bool

false

By default, SDP-offer for unencrypted media stream (rtp) is sent to TLS-connected addresses when initiating calls. You can use the parameter to enable SDP-offer initiation with encrypted media stream for TLS addresses.
Applies only to calls using border mediagate (media=1).

certdir

str

empty

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

keypass

str

empty

Password for decrypting the certificate’s secret key file.

payloads_audio_offer

array<str>

`["PCMA/8000", "PCMU/8000"

"telephone-event/8000"]`

List of audio codec names used for call initiation (shoulder call).
Applies only when using the media call service mode via bgmg.

As value - a list containing names of audio codecs in format "Name/Freq".
The following codecs are supported (case-sensitive):

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

The three basic formats, PCMA/8000, PCMU/8000 and telephone-event/8000 are automatically added to initiated calls at any field value.

payloads_video_offer

array<str>

empty

List of video codec names used to initiate a call (shoulder call).
Applies only when using the media call service mode via bgmg.

As a value - a list containing video codec names in the following format "Name/Freq".
The following codecs are supported (case-sensitive):

  • 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 INVITE request received from the initiator are translated unchanged into SDP INVITE requests to the called devices. In this case, the system does not apply either its knowledge of codecs or transcoding, and the codec is unknown to the system, direct transfer is nevertheless still possible.

  • true – all video codecs are listed according to the video codecs known to the system, the system offers all known codecs to the called party (with a filter from payloads_video_offer), and if the codecs selected by the devices do not match, transcoding is performed on the video stream.

max_udp_size

int

1500

Maximum udp packet size sent by the system, in bytes.
Minimum value: 1500.
If the packet to be sent exceeds the set size, it is automatically sent through the TCP.
If the packet size exceeds 1500 but up to the value set in the field, the packet is automatically split into frames and reassembled when received 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 to apply media gateway role b2b for calls initiated by the current role instance esg.

extaddrs

array<str>

empty

A list of IP addresses of the current server.
Used in one of the search algorithms provider account when receiving INVITE requests from outside, allowing one of the listed addresses to be specified as the domain in the "To" header.
Usually there is no need to use this field, as it is possible to specify the necessary value in the provider account settings.
However, in order to optimize and remove the need to specify the same values in a large number of provider accounts, they can be specified in the role option esg.

stunserver

array<str>

empty

List of external STUN-servers to determine the external IP-address of the server when working for the NAT.
Used in one of the search algorithms provider account when receiving INVITE requests from outside, allowing an external address to be specified as the domain in the "To" header NAT.
The format of the value is a list of URIs of the form 'sip:<DomainOrAddress>:<Port>'

sip_alg

array<object>

empty

White Address Substitution.
In case the system is installed behind NAT with respect to subscriber devices, the sip-alg mode must be used on the NAT.
Sip-alg performs address spoofing in packets sent outward and received outward.
The SIP-ALG function can be activated on border roles. This parameter sets the set of local cluster addresses that are to be swapped with white external addresses.

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

The list should include the addresses of all servers where the media gate is located, as well as the local interfaces of the current machine from which all external addresses are routed.
All packets sent to non-cluster addresses are subject to gray-to-white address spoofing.
White to gray address spoofing is subject to all packets received from addresses not belonging to the cluster.
If it is necessary to connect to the system other devices and systems that are in the local network loop but do not belong to the cluster, you must use a second instance of the role with sip-alg disabled (this parameter is absent or its value is empty).

fwd_headers

array<object>

empty

Headline Trolling.
ESG serves calls in B2BUA (back to back user agent) mode. For each participant a separate arm is created with unique Call-ID.
When forming an outgoing INVITE request, the ESG by default does not add custom headers from the incoming INVITE request.
To ensure that certain custom headers from an incoming INVITE request are added to the outgoing INVITE request, a list of their names must be provided.

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

The default is blank.

Configuration example

The configuration is managed in an application available to master domain administrators. The application hides the full content of the configuration, but it is nevertheless accessible via the API.

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

Example node
{
  "name": "esg12",
  "roletype": "esg",
  "iface": "eth0",

  "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

  • Personalization
  • Increase font size
  • Decrease font size