Internal SIP Gate (sg)

Description

SIP entry point to the cluster for internal devices identified by SIP user accounts.

Proxies requests in stateless mode to internal servers with b2b roles. It has an address through which phones of internal subscribers of the corresponding site are connected. Any request from the system to a user goes through the corresponding sg role instance.
It does not distinguish between request types; it passes everything through, adding itself to the "Via" headers of all requests and the "Record-Route" headers of INVITE requests.

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 sg role.

Made redundant and scaled in Active-Active mode.

On role startup, the certificate specified in the *certdir* parameter is checked. If validation fails, the role starts with an immutable certificate. The certificate can be overridden through domain settings.

Table 1. System characteristics

Code

sg

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

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

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

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 (1 - 65535). The same port also handles TCP.
For example: 5060.
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 (1 - 65535). If a value different from UDP is specified, it is opened additionally.
For example: 5060.
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 TLS port for SIP (1 - 65535). Not opened by default.
For example: 5061.
Raises a TLS listener on the wildcard interface '0.0.0.0' or on the interfaces specified by the 'sip_ifaces' parameter.

For the TLS port, client certificate validation mode can be set with the tls_mode parameter.

wss

int

empty

Local WebSocketSecure port for SIP (1 - 65535). Not opened by default.
For example: 5063.
Raises a WSS listener on the wildcard interface '0.0.0.0' or on the interfaces specified by the 'sip_ifaces' parameter.

tls_mode

int

empty

TLS port operation mode.

  • 'public' - normal mode, without client certificate verification.

  • 'debug' - debug mode; client certificates are verified, but absence or failed verification is only logged and does not affect operation.

  • 'mutual' - mode with mutual certificate verification. A client certificate is mandatory to pass verification and must pass chain validation.

  • 'strong' - mode with mutual certificate verification. In addition to mutual, an additional strict check is performed for the certificate in the 'dm/Certificates' collection. Used together with the 'Device Manager' application, which issues certificates via SCEP.

The CA certificate that signed the certificates issued to devices is used for chain validation and can be placed in the :SYNC/common/cacerts folder in PEM format.

The behavior of the wss port is not affected by this parameter; there, the mode without client certificate verification is always used.

sip_internal_port

int

empty

Local port for SIP interaction with other system microservices (UDP/TCP).
For example: 6160.
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. This does not apply to virtual addresses.

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_closure

bool

true

Switch for logging callid of dialogs that passed through sg (without links between them) to the callid log. It is used to find the sg trn log when assembling trn and building a diagram after link retention in node memory expires. The line is written once per INVITE dialog: for the initial INVITE, or if the dialog is unknown to sg (for example, a replacement instance) for the first request within the dialog, except ACK and PRACK.

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.

certdir

str

empty

Alias of the server directory for storing certificates ('server.crt' and 'server.key' files).
If a certificate chain to a certification authority (CA) must be specified, it must be placed at the end of the certificate file.
If the path is not specified, certificates are searched in the "/usr/lib/era/era_sip/priv/ssl" directory.

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

  • the server is accessed by a domain name that does not correspond to the platform domain tree, and the certificate is not specified in master domain settings;

  • no certificate is specified in the settings of the access domain and its parent domains up to the master domain;

  • automatic certificate issuance is not used.

keypass

str

empty

Password for decrypting the certificate private key file specified in the 'certdir' field. 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).

b2bmedia

bool

true

Switch for using the media gateway by the b2b microservice for calls forwarded by the current sg role instance.
A value of false turns the system into a signaling handler, and media streams are closed directly between subscribers (provided bgmg is not used).

bgmedia

str

"off"

Switch for using the border media gateway by the current outbound-proxy server.
Any bgmg instance running on the same server is used as the border media gateway.

A border media gateway may be needed (on the internal facade) if the outbound-proxy server is located in several subnets and there is a subnet from which subscribers connect and which is unreachable from other system servers running mg microservices.

Possible values:

  • "off" or false (legacy) - border media gateway is forcibly disabled.

  • "force" - border media gateway is forcibly enabled (must be in the configuration).

  • "auto" or true (legacy) - the decision to use the border media gateway is made automatically when the conditions below are met.

In automatic mode, the border media gateway is used on the internal facade (outbound-proxy) if at least one condition is met:

  • The system is deployed on two or more servers and proxying is performed between two different subnets (the subscriber device and the SIP server are in different subnets);

  • The incoming call arrives at the main interface of the server that is marked in SIP-ALG settings as a gray address;

and is not used in other cases.

In default configurations, media traffic is handled only by the mg media gateway under the control of the b2b microservice, and the border media gateway on the internal facade is not used.

The border media gateway is added to the media traffic servicing chain; it does not replace the main media gateway.

payloads_audio_offer

array<str>

"G729/8000"

List of audio codec names used to initiate a call (leg call).
Applied only to the SDP of the response to OPTIONS.
The order and value format are the same as for the payloads_audio_offer parameter of the b2b role. See Codecs and media negotiation.

payloads_video_offer

array<str>

empty

List of video codec names used to initiate a call (leg call).
Applied only to the SDP of the response to OPTIONS.

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.

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.

use_srtp_setup_timeout

bool

true

Switch for monitoring TLS connection establishment.
Applied only to calls 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 softphone 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 media gateway settings.

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.

reregister

bool

false

Switch for sending NOTIFY requests to re-register a UA when the sg role instance serving the device fails.
true – when a sudden unavailability of an sg role instance is detected, other role instances send a NOTIFY request with special content intended to trigger a restart of the registration operation on the device.

Useful when:

  • the configuration has several sg instances;

  • the devices used support specifying several Outbound-proxy addresses;

  • the devices used support NOTIFY with event=reload-account;

  • the devices used process a NOTIFY request arriving from an alternative server.

One active SG instance with the reregister option enabled monitors all other instances of the current site.
When a loss is detected, it waits 15 seconds for the instance to restart.
If no restart occurs, all domains are searched for registrations associated with the lost sg instance.
A NOTIFY request with event=reload-account is sent to all discovered registered devices.

If not all domains are available at the time of the registration search (for example, during server shutdown there is a simultaneous takeover of DB, mdc, reg), the operation is postponed for up to 2 minutes waiting for services to come up.

deservice_response

bool

true

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

deservice_followers

array<int>

true

List of roleid of other SG instances replacing the current instance during decommissioning.
Applied only when the 'deservice_response' mode is used.
If the list is empty, the set of all SG instances of the current site is used.
Practically, the follower should be the instance configured as an alternative outbound proxy in phone parameters and autoprovision templates.

deservice_sipcode

int

503

Response code sent to subscribers in response to an incoming request while the node is in decommissioning mode.
Possible values 400 - 699.

translit

bool

false

Switch for automatic transliteration of DisplayName in requests forwarded from the system to connected devices.

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

substitute_domains

array<object>

empty

Substitution of domains instead of IP addresses in the To and From headers of SIP packets.
Used with phones that cannot substitute symbolic domain names.
When the mode is enabled, the SG microservice substitutes packets when forwarding in both directions as follows:
* Packets received from devices that contain the server IP address as the domain name in the To and From headers have the IP address in those headers replaced with the mapped domain.
* Packets sent to devices that contain one of the domains specified in the option in the To and From headers have the domain in those headers replaced with the mapped IP address.

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

ws_ping_interval

int

25

Interval for checking SIP connections over WebSocket (ws/wss), in seconds.
The server sends a WebSocket ping to the device. If neither data nor a WebSocket ping or pong arrives from the device for two intervals, the connection is closed and registrations made through it are removed: calls to a device that lost connectivity without breaking the connection (sleep, network change) are rejected immediately instead of waiting for a response.
0 — check disabled. Values below 10 are treated as 10.
Applies to new connections after the role is restarted.

log_cdr

bool

true

Switch for logging events to the cdr log.

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.

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

  "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.incoplax.com"
    }
  ]
}

See also