Internal SIP Gate (sg)

Description

Cluster entry point over SIP for internal devices defined by SIP-user accounts.

Proxies requests in stateless mode to internal servers with roles b2b. Has an address through which the phones of internal subscribers of the respective site are connected. Any request from the system to the user goes through the appropriate role instance sg.
Does not distinguish between different types of requests - skips all the way through, adding itself to the "Via" headers of all requests and the "Record-Route" headers of INVITE requests.

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 sg role must have one or more instances of the bgmg role with non-overlapping port settings.

Reserved and scaled in mode Active-Active.

When the role is started, the certificate specified in the *certdir* parameter is validated. If the validation fails, the role is started with an unchanged certificate. The certificate can be overridden through the domain settings.

Table 1. System Characteristics

Code

sg

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

  • No more than 3000 SIP packets per role instance per second.

  • 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: "sg".

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 (1 - 65535). The same port also handles at the same time TCP.
For example: 5060.
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 (1 - 65535). If a value other than UDP is specified, it will be raised additionally.
For example: 5060.
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 TLS port for SIP (1 - 65535). Does not open by default.
For example: 5061.
Raises a TLS listener on group interface '0.0.0.0.0', or the interfaces specified by the parameter 'sip_ifaces'.

wss

int

empty

WebSocketSecure local port for SIP (1 - 65535). Does not open by default.
For example: 5063.
Raises the WSS 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: 6160.
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_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.

certdir

str

empty

The alias of the directory on the server for storing certificates (files 'server.crt' and 'server.key').
In case it is necessary to specify the certificate chain up to the CA (Certification Authority) it should be placed at the end of the certificate file.
If the path is not specified, the certificates are searched in the directory "/usr/lib/era/era_sip/priv/ssl"

This setting and certificate is applied only when the certificate specified in the domain settings is not applied (settings.certificate_pem):

  • the server was accessed using a domain name that does not correspond to the platform domain tree, and at the same time the certificate is not specified in the master domain settings;

  • the address domain and its parent domains up to the master domain do not have a certificate specified in the settings;

  • automatic certificate issuance is not used.

keypass

str

empty

Password for decryption of the certificate secret key file specified in the field 'certdir'.

b2bmedia

bool

true

Media gateway microservice application switch b2b for calls forwarded by the current role instance sg.

bgmedia

bool

false

Turns off the application of an edge media gateway by the current outbound-proxy server.
An arbitrary instance of bgmg executing on the same server is used as the media edge gateway.

An outbound media gateway may be needed if the outbound-proxy server is hosted on multiple subnets, and there is a subnet from which subscribers connect that is not accessible to other servers in the system where the microservices are executing mg.
Mode is not enforced on outbound-proxy under any of the following conditions:

  • the system is deployed on a single server;

  • there is only one network interface on the sg microservice server;

  • proxying is performed within one subnet (the subscriber device is in the same subnet as the SIP server b2b).

By default, media traffic is handled by a media gateway mg running a microservice b2b.

payloads_audio_offer

array<str>

"G729/8000"

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

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.

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.

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.

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.

reregister

bool

false

NOTIFY request sending mode switch to re-register the UA when the sg role instance serving the device goes down.
true – When a sudden unavailability of an sg role instance is detected, other role instances send a NOTIFY request with special content to initiate a restart of the registration operation on the device.
Applies if devices support specifying multiple Outbound-proxy addresses and handling this NOTIFY.

deservice_response

bool

true

Switch for sending unsuccessful final SIP responses to REGISTER, SUBSCRIBE, INVITE (new) requests during server out-of-service mode.
Applies only if other instances specified in the list are active and not being decommissioned 'deservice_followers'".

deservice_followers, array<int>, true, "A list of roleid other SG instances replacing the current instance during decommissioning.
Applies only when the mode is used 'deservice_response'.
If the list is empty, the set of all SGs of the current site is applied.
In a practical sense, an instance configured as an alternative outbound proxy in the phones settings and in the auto provisioning templates should be specified as a follower.

deservice_sipcode

int

503

A response code sent to subscribers in response to an incoming request while the node is in service withdrawal mode.
Possible options 400 - 699.

translit

bool

false

Turns off automatic DisplayName transliteration mode in requests forwarded away from the system to connected devices.

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

substitute_domains

array<object>

empty

"Substitution of domains instead of ip addresses in the To and From headers of SIP packets.
Used when working with phones that cannot substitute character domain names.
When the mode is activated, the SG microservice spoofs packets in round-trip forwarding as follows:
* Packets received from devices that contain the server IP address as the domain name in the To and From headers substitute the IP address in those headers for the domain mapped to it.
* Packets sent to devices that contain one of the domains specified in the To and From headers will substitute the domain in those headers for the IP address mapped to it.

Format:
[{"addr":"IpAddr", "domain":"DOMAIN"}, ...]

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": "sg1",
  "roletype": "sg",
  "iface": "eth0",

  "roleid": 11280,
  "separate": true,
  "tcp": 5060,
  "udp": 5060,
  "tls": 5061,
  "wss": 5063,

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

  "certdir": "alias://paths/default_certdir",
  "keypass": "eb9c4458016d3f1e378d02004c4f4f50",

  "max_udp_size": 10000,

  "b2bmedia": true,
  "reregister": false,
  "translit": true,

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

  "substitute_domains": [
    {
      "addr": "172.16.0.15",
      "domain": "pbx.era-platform.ru"
    }
  ]
}

See also

  • Personalization
  • Increase font size
  • Decrease font size