LTE IMS Server

version 2024-04-26*

This document is based on the latest test release.
Features may not be present in your current installed software. You may check their availability in change history or in your release documentation.
If you require an up to date release, ask for it in a ticket.

Table of Contents

1 Introduction

LTEIMS is an IMS standalone simple server. It has a built-in P-CSCF, I-CSCF, S-CSCF, HSS. It also allows SMS handling including SMS over SG by connecting to the Amarisoft MME.

2 Features

• Implements P-CSCF with built-in I-CSCF, S-CSCF and HSS.
• Support of SIP protocol.
• Support of MD5, AKAv1 and AKAv2 authentication.
• Support of ISIM cards using the XOR, Milenage or TUAK authentication algorithm.
• Support of IPsec (ESP/transport).
• Support of voice, video calls: MO and MT.
• Support of voice echo test.
• Support of hold.
• Support of SMS (GSM 3.40) using SIP MESSAGE and SMS over SG.
• Support of IPv4 and IPv6.
• Support of precondition and dedicated bearer using Rx interface or N5 interface.
• Support of emergency call.
• Configurable user database.
• External authentication using Cx interface.
• Command line monitor.
• Remote API using WebSocket.

3 Requirements

3.1 Hardware requirements

• LTEIMS can run on the same PC as the Amarisoft eNodeB if a simple and compact solution is needed. Otherwise, any reasonnably recent PC with at least one Gigabit Ethernet port is acceptable.
• A VoLTE compatible UE is necessary (See VoLTE Call, note that it may depends on UE).
• A test USIM with ISIM application should be plugged into the UE. IMSI and secret key must be known. A standard USIM may also work but it depends on the UE implementation.

3.2 Known compatible UE

The Amarisoft IMS server has been tested with the following UE models:

• Samsung S5
• LG MS870

3.3 Software requirements

• A 64 bit Linux distribution. Fedora 39 is the officially supported distribution.
  The following distributions are known as compatible:
  • Fedora 22 to 39
  • Cent OS 7
  • Ubuntu 14 to 22

  Your system requires at least GLIBC 2.17.

4 Installation

The network access thru the Gigabit Ethernet port must be correctly configured.

LTEIMS can be run directly from the directory when it was unpacked. No need for explicit installation.

4.1 Fedora setup

If you want to use SMS over SG with the Amarisoft MME or precondition with QoS, you need support of SCTP protocol for which the necessary packages are not usually installed. In order to install them, do as root user:

• Fedora

  dnf install lksctp-tools kernel-modules-extra
  

• Ubuntu

  sudo apt-get install lksctp-tools linux-image-extra-3.13.0-24-generic
  

  Note that linux-image-extra package name may differ depending on your kernel version.

To verify that SCTP kernel module is running, do as root user:

checksctp

If it reports that the protocol is not supported,

• check if you have a /etc/modprobe.d/sctp-blacklist.conf file
• edit it to comment the ’blacklist sctp’ line

Then reboot the PC in case the Linux kernel was upgraded too.

4.2 License key installation

LTEIMS needs a LTEMME license key to run. Please refer to the ltemme documentation.

4.3 Initial testing

• Edit the file config/ims.cfg to set the address of the SIP interface. Normally it is the address of the Ethernet interface that will receive SIP packets.
  You can keep the current config if you use it with the Amarisoft MME and its config/mme-ims.cfg config file.
• Start the program as root with:

  ./lteims config/ims.cfg
  

  [The root access is only needed if you want IPsec support.]

• The command line interface is used to monitor the operation of LTEIMS and to change the logging options.
  Use help to get the list of commands and quit to stop the program.
• Use users to list the user database and registering state.

4.4 Samsung S5 configuration

Your UE must run at least Android 5.0 (Even if Android 5.0 is installed, try to update software (several times) as a sub-release is necessary).
If not, please update it.

To check your UE is configured for VoLTE, please go to Settings/More networks/Mobile networks of your handset and check VoLTE Call is checked:

We assume you are using the system with Amarisoft MME and config/mme-ims.cfg config file.
As there are two PDN defined, you must add them to the UE.

• Go to Settings/More networks/Mobile networks
• Turn on Data roaming
• Check VoLTE Call (If not present, it means your device is not up to date or does not support VoLTE).
• Go to Network operators, search for networks and select Amarisoft network.
• Go back to Mobile network.
• Add the first APN with the following parameters:
  • Name = Internet
  • APN = internet
  • APN type = default
• Save it and select it.
• Add second APN with following parameters:
  • Name = IMS
  • APN = ims
  • APN type = ims
• Save it and do not select it (This APN may not be displayed).
• Reboot your phone

5 Configuration reference

5.1 Configuration file syntax

The main configuration file uses a syntax very similar to the Javascript Object Notation (JSON) with few extensions.

1. Supported types:
   • - Numbers (64 bit floating point). Notation: 13.4
   • - Complex numbers. Notation: 1.2+3*I
   • - Strings. Notation: "string"
   • - Booleans. Notation: true or false.
   • - Objects. Notation: { field1: value1, field2: value2, .... }
   • - Arrays. Notation: [ value1, value2, .... ]
2. The basic operations +, -, * and / are supported with numbers and complex numbers. + also concatenates strings. The operators !, ||, &&, ==, !=, <, <=, >=, > are supported too.
3. The numbers 0 and 1 are accepted as synonyms for the boolean values false and true.
4. {} at top level are optional.
5. " for property names are optional, unless the name starts with a number.
6. Properties can be duplicated.
   Merge will be done by recursively overriding values considering reading direction.

   {
       value: "foo",
       value: "bar",
       sub: {
           value: "foo"
       },
       sub: {
           value: "bar"
       }
   }
   

   Will be equivalent to:

   {
       value: "bar",
       sub: {
           value: "bar"
       }
   }
   

7. Files can be included using include keyword (must not be quoted) followed by a string (without :) representing the file to include (path is relative to current file) and terminating by a comma.
   Arrays can’t be included.
   Merge will be done as for duplicate properties.
   If file1.cfg is:

       value: "foo",
       include "file2.cfg",
       foo: "foo"
   

   And file2.cfg is:

       value: "bar",
       foo: "bar"
   

   Final config will be:

   {
       value: "bar",
       foo: "foo"
   }
   

8. A C like preprocessor is supported. The following preprocessor commands are available:

   #define var expr

   Define a new variable with value expr. expr must be a valid JSON expression. Note that unlike the standard C preprocessor, expr is evaluated by the preprocessor.

   #undef var

   Undefine the variable var.

   #include expr

   Include the file whose filename is the evaluation of the string expression expr.

   #if expr

   Consider the following text if expr is true.

   #else

   Alternative of #if block.

   #elif

   Composition of #else and #if.

   #endif

   End of #if block.

   #ifdef var

   Shortcut for #if defined(var)

   #ifndef var

   Shortcut for #if !defined(var)

   In the JSON source, every occurrence of a defined preprocessor variable is replaced by its value.

9. Backquote strings: JSON expression can be inserted in backquote delimited strings with the ${expr} syntax. Example: `abc${1+2}d` is evaluated as the string "abc3d". Preprocessor variables can be used inside the expression. Backquote strings may span several lines.

5.2 Properties

log_filenamelog_filename

String. Set the log filename. If no leading /, it is relative to the configuration file path. See Log file format.

log_optionslog_options

String. Set the logging options as a comma separated list of assignments.

• layer.level=verbosity. For each layer, the log verbosity can be set to none, error, info or debug. In debug level, the content of the transmitted data is logged.
• layer.max_size=n. When dumping data content, at most n bytes are shown in hexa. For ASN.1, NAS or Diameter content, show the full content of the message if n > 0.
• layer.payload=[0|1]. Dump ASN.1, NAS, SGsAP or Diameter payload in hexadecimal.
• layer.key=[0|1]. Dump security keys (NAS and RRC layers).
• layer.crypto=[0|1]. Dump plain and ciphered data (NAS and PCDP layers).
• layer.verbose=[0|1]. If layer is ipsec, dump all packets filtering informations.
• time=[sec|short|full]. Display the time as seconds, time only or full date and time (default = time only).
• time.us=[0|1]. Dump time with microseconds precision.
• file=cut. Close current file log and open a new one.
• file.rotate=now. Rename current log with timestamp and open new one.
• file.rotate=size. Rename current log every time it reaches size bytes open new one. Size is an integer and can be followed by K, M or G.
• file.path=path. When log rotation is enabled, move current log to this path instead of initial log path.
• append=[0|1]. (default=0). If 0, truncate the log file when opening it. Otherwise, append to it.

Available layers are: ims, sip, media, rx, cx, n5

log_synclog_sync

Optional boolean (default = false). If true, logs will be synchronously dumped to file.
Warning, this may lead to performances decrease.

sip_addrsip_addr

Array. Each item is an object representing a SIP server socket defined as follow:

addrsip_addr.addr

String. Set the IP address (and an optional port) on which IMS server will listen for SIP packets. The default port is 5060.

bind_addrsip_addr.bind_addr

Optional string. Defines network interface on which IMS will listen.
If not specified, the addr parameter is used.

port_minsip_addr.port_min

Optional integer (Default is 10000). Defines lower bound of UDP media socket.

port_maxsip_addr.port_max

Optional integer (Default is 20000). Defines upper bound of UDP media socket.

NB:

• SIP socket object can be represented by a simple string. Thus, it will represent addr parameter and all other parameters will use default value.
• For legacy, sip_addr can be a single SIP socket (Object or String) instead of an Array.

sctp_addrsctp_addr

String. Set the IP address (and an optional port) for MME connection.
This is only necessary for SMS over SG feature.

cx_server_addrcx_server_addr

String. Set the IP address (and optional port) of Cx SCTP connection to the HSS. The default port is 3868.

cx_bind_addrcx_bind_addr

Optional string. IP address and optional port on which the Cx SCTP connection is bound. If not set, sctp_addr is used.

cx_origin_realmcx_origin_realm

Optional string. Defines the string sent in the Origin-Realm AVP for Cx messages. Default is set to amarisoft.com.

cx_origin_hostcx_origin_host

Optional string. Defines the string sent in the Origin-Host AVP for Cx messages. Default is set to ims.amarisoft.com.

cx_watchdog_durationcx_watchdog_duration

Optional integer (range 0 to 36000000, default = 0). Tw watchdog timer in milliseconds to send the Diameter Device Watchdog Request message. The value 0 deactives the watchdog.

rx_server_addrrx_server_addr

Optional string. Set the IP address (and optional port) of Rx SCTP connection to the MME. The default port is 3868. If not set, cx_server_addr is used.

rx_bind_addrrx_bind_addr

Optional string. IP address and optional port on which the Rx SCTP connection is bound. If not set, cx_bind_addr is used.

rx_origin_realmrx_origin_realm

Optional string. Defines the string sent in the Origin-Realm AVP for Rx messages. Default is set to amarisoft.com.

rx_origin_hostrx_origin_host

Optional string. Defines the string sent in the Origin-Host AVP for Rx messages. Default is set to ims.amarisoft.com.

rx_watchdog_durationrx_watchdog_duration

Optional integer (range 0 to 36000000, default = 0). Tw watchdog timer in milliseconds to send the Diameter Device Watchdog Request message. The value 0 deactives the watchdog.

use_n5use_n5

Optional boolean (default = false). If set, the N5 interface is used instead of the Rx interface.

n5n5

Optional object used to configure the N5 interface with the PCF.

api_rootn5.api_root

String. apiRoot as defined in 3GPP TS 29.501: <scheme>://<host>:<port>, where <scheme> is "http" or "https".

transaction_timeoutn5.transaction_timeout

Optional integer (range 1 to 15000, default = 4000). Defines the timeout in milliseconds for a transaction with the PCF.

bind_addrn5.bind_addr

Optional string. IP address and optional port on which the N5 TCP connection is bound. If not set, cx_bind_addr is used.

domaindomain

String. Global SIP domain used for IMPU and authentication. May be overriden at user level.
This parameter is not used to recover IMPU.

tcp_thresholdtcp_threshold

Optional integer (default = 1300). Set packet threshold in bytes to use TCP instead of UDP.

tcp_keepalivetcp_keepalive

Optional integer (default = 900). Time in seconds before sending keepalive on TCP connections. 0 means disabling keepalive.

tcp_keepcounttcp_keepcount

Optional integer (default = 2). Number of TCP keepalive failure before releasing socket.

session_expiressession_expires

Optional object. Defines session timer configuration.
Parameters are the following:

durationsession_expires.duration

Optional integer (default = 1800). Session duration in seconds.

minsession_expires.min

Optional interger (default = 90). Minimum allowed session expires.

refreshersession_expires.refresher

Optional string (default = uac). Defines session refresher when it is up to the IMS to take this decision.

methodsession_expires.method

Optional string (default = update). Defines SIP method to use for session refresh when IMS is the refresher.

forcesession_expires.force

Optional boolean (default = true). If set to true, forces the refresher in IMS request with the refresher value.

For legacy purpose, session_expires can be an integer. If so, only duration is set and other parameters are kept to their default value.

100rel100rel

Optional Boolean (default = true). Enable/disable 100rel support.

preconditionprecondition

Optional string (default = on). Values can be "on", "off" or "silent".
On: IMS will handled QoS according to the standard.
Off: no precondition and no dedicated bearer establishment.
Silent: dedicated bearers will be established regardless the SIP and SDP content.
Note that a Rx connection is necessary to allow dedicated bearer establishment.

p_called_party_idp_called_party_id

Optional boolean (default is false). Enable P-Called-Party-ID header for INVITE and MESSAGE requests.

ipsecipsec

Optional boolean (default is true). Enable/disable support of ipsec.

ipsec_aalg_listipsec_aalg_list

Array of strings. Each string represent IPsec authentication algorithm supported by IMS.
"null" may be used to indicate no authentication.

ipsec_ealg_listipsec_ealg_list

Array of strings. Each string represent IPsec encryption algorithm supported by IMS. "null" may be used to indicate no encryption.

ipsec_mtuipsec_mtu

Optional integer (range 68 to 65535, default = 1400). MTU for IPsec network interface.

dialog_timeoutdialog_timeout

Optional integer (default = 30). Time in seconds of call session. Stop call if no activity has been detected during this time.

auth_on_register_onlyauth_on_register_only

Optional boolean (default = true). If true, don’t try to authenticate other request than register (unless expires is set to 0).

trunktrunk

Optional object. If set, IMS will accept incoming calls from a SIP trunk and will forward unknown calls to SIP trunk (https://tech-academy.amarisoft.com/how_to_run_volte_call_using_a_sip_trunk.wiki).
SIP trunk must accept non authenticated requests. Parameters are the following:

addrtrunk.addr

String. IP address of the SIP trunk.

nametrunk.name

String. SIP trunk account user name.

domaintrunk.domain

Optional string (default = same as addr). If set, use this for SIP uri domain.

tcp_thresholdtrunk.tcp_threshold

Optional integer (default = 0). If > 0, will override global tcp_threshold parameter.

com_addrcom_addr

Optional string. Address of the WebSocket server remote API. See Remote API.
If set, the WebSocket server for remote API will be enabled and bound to this address.
Default port is 9003.
Setting IP address to [::] will make remote API reachable through all network interfaces.

com_namecom_name

Optional string. Sets server name. IMS by default

com_ssl_certificatecom_ssl_certificate

Optional string. If set, forces SSL for WebSockets. Defines CA certificate filename.

com_ssl_keycom_ssl_key

Optional string. Mandatory if com_ssl_certificate is set. Defines CA private key filename.

com_ssl_peer_verifycom_ssl_peer_verify

Optional boolean (default is false). If true, server will check client certificate.

com_ssl_cacom_ssl_ca

Optional string. Set CA certificate. In case of peer verification with self signed certificate, you should use the client certificate.

com_logs_lockcom_logs_lock

Optional boolean (default is false). If true, logs configuration can’t be changed via config_set remote API.

com_authcom_auth

Optional object. If set, remote API access will require authentication.
Authentication mechanism is describe in Remote API Startup section.

passfilecom_auth.passfile

Optional string. Defines filename where password is stored (plaintext).
If not set, password must be set

passwordcom_auth.password

Optional string. Defines password.
If not set, passfile must be set.

unsecurecom_auth.unsecure

Optional boolean (default false). If set, allow password to be sent plaintext.
NB: you should set it to true if you access it from a Web Browser (Ex: Amarisoft GUI) without SSL (https) as your Web Browser may prevent secure access to work.

com_log_countcom_log_count

Optional number (Default = 8192). Defines number of logs to keep in memory before dropping them.
Must be between 4096 and 2097152).

sim_eventssim_events

Array of object. Each element gives an event configuration to execute for this UE.
Event configuration is exactly the same as for Remote API messages except that message field must be event.

sim_events_loop_countsim_events_loop_count

If set, will define loop_count for each event of sim_events, See loop_count.

sim_events_loop_delaysim_events_loop_delay

If set, will define loop_delay for each event of sim_events, See loop_delay.

license_serverlicense_server

Configuration of the Amarisoft license server to use.
Object with following properties:

server_addrlicense_server.server_addr

String. IP address of the license server.

namelicense_server.name

Optional string. Text to be displayed inside server monitor or remote API.

taglicense_server.tag

Optional string. If set, server will only allow license with same tag.

Example:

license_server: {
    server_addr: "192.168.0.20",
    name: "My license"
}

sms_expiressms_expires

Integer (default = 86400). Delay in seconds before SMS is removed from database. If a MO SMS contains the TP-Validity-Period field, it will be used instead of sms_expires.

sms_hook_onlysms_hook_only

Optional boolean (default = false). If set, when SMS is received and at least one WebSocket client has registered to sms event, don’t process SMS internally (Only CP/RP layer will be handled).

binding_expiresbinding_expires

Integer (default = 3600, max = 864000). Default duration in seconds for registration.

subscribe_expiressubscribe_expires

Integer (default = 0, max = 864000). Subscription expiration. If set to 0, use value sent by UE.

user_agentuser_agent

Optional string (default = Amarisoft-IMS-2024-04-26). SIP user agent.

force_user_agentforce_user_agent

Boolean (default = true). If true, IMS user-agent will always be used, else remote peer’s one will be used.

pathpath

Optional string (default = sip:ims.mnc001.mcc001.3gppnetwork.org). SIP path. If registration supports path, defines content of the Path header in registration response. If set to an empty string, Path header won’t be set.

timer_t1timer_t1

Optional number (default = 2). SIP T1 timer duration in seconds.

timer_t2timer_t2

Optional number (default = 16). SIP T2 timer duration in seconds.

timer_t4timer_t4

Optional number (default = 17). SIP T4 timer duration in seconds.

custom_headerscustom_headers

Array of object. Each object represents a custom header to add to requests and/or responses, defined as follows:

namecustom_headers.name

Header name

valuecustom_headers.value

Header value

codescustom_headers.codes

Number or array of numbers of the SIP responses on which to apply custom headers.
0 can be used for all codes.

methodscustom_headers.methods

String or array of strings of the SIP method on which to apply custom headers.
* can be used for all methods.
If codes is set, the custom headers will be applied to the responses of the associated request.

replacecustom_headers.replace

Optional boolean (default = false). If set, allow only one occurence of the header.

sms_centre_addresssms_centre_address

Optional object used to configure the SMS centre address. Contains the following parameters:

type_of_numbersms_centre_address.type_of_number

Optional enumeration "unknown", "international", "national" (default = "unknown"). SMS centre address type of number.

numbering_plansms_centre_address.numbering_plan

Optional enumeration "unknown", "national", "private" (default = "unknown"). SMS centre address numbering plan identification.

numbersms_centre_address.number

String. Contains optional ’+’ at first position followed by a maximum of 20 digits. SMS centre address number.

sms_retry_delaysms_retry_delay

Integer. Time in s to retry SMS sending.

100rel100rel

Optional boolean (default = true). Enable/disable support of provisional response

echoecho

IMPU (See impu). If set, this defines the phone number(s) for echo service.

mt_call_sdp_filemt_call_sdp_file

String. File to use as SDP when using MT call.

sms_message_filtersms_message_filter

Optional object. Allows to define the IMS behavior for a list of SMS related messages.
Each property name represents a SMS message type. The ones currently supported are cp_data, cp_ack, rp_data and rp_ack.
Each property value is an enum: treat (message is processed), ignore (message is ignored) or reject (message is rejected).
By default all procedures are treated.

Example:

sms_message_filter: {
    cp_data: "treat",
    rp_ack: "reject"
}

sms_forced_cp_causesms_forced_cp_cause

Optional integer (range 0 to 255). Allows to override the CP error cause selected by the IMS with the one configured. Set to 0 to deactivate the override.

sms_forced_rp_causesms_forced_rp_cause

Optional integer (range 0 to 255). Allows to override the RP error cause selected by the IMS with the one configured. Set to 0 to deactivate the override.

mms_server_bind_addrmms_server_bind_addr

Defines network interface on which MMS server will listen. It is used to configure the MMSC in the UE. MMS proxy is not supported and shall not be configured in the UE.

Example:

mms_server_bind_addr: "192.168.3.1:1111"
MMSC: http://192.168.3.1:1111

mms_expiresmms_expires

Optional integer (default = 86400). Delay in seconds before MMS is removed from database.

5.2.1 User database options

ue_dbue_db

Array of objects. Configure the user database. Each element is an entry for one user. Note that this part can be shared between Amarisoft MME and IMS. The following properties are available:

imsiue_db.imsi

Optional string. Set the IMSI.
Shall be present if nai is absent.

naiue_db.nai

Optional string. Network specific identifier-based SUPI.
Shall be present if imsi is absent.

multi_simue_db.multi_sim

Optional boolean (default = false). If true, allow several UEs to have the same IMSI (useful when using several identifical test SIM cards in different UEs at the same time). They are distinguished with their IMEI. Note: it is only allowed with the XOR authentication algorithm.

impiue_db.impi

String. Defines user IMPI. Must be fully filled with hostname if necessary.
If you don’t know your IMPI, please look at IMS logs inside REGISTER request. The IMPI must match the username argument inside Authorization header.

impuue_db.impu

Array of strings or array of objects.
Each string represent an IMPU and can be a sip URI or a telephone number.
Note that sip URI must not include hostname.
If IMPU does not start by a scheme, it is assumed to be a sip URI.
Ex:

• sip:user
• user
• tel:+33123456789

If impu is an object, it has following members:

impuue_db.impu.impu

IMPU as defined above.

imeiue_db.impu.imei

IMEI associated to this IMPU. Allows to filter calls and SMS for a specific UE.
Only relevant if multi_sim is set to true.

anonymousue_db.impu.anonymous

Optional boolean (default is false). If true, allow Anonymous connection (Emergency call) and mask impu in SIP headers.

authenticationue_db.impu.authentication

Optional boolean (default is true). If false, disable authentication.

ring_onlyue_db.impu.ring_only

Optional boolean (default is false). If true, IMS will go up to ringing state but not further.

preconditionue_db.impu.precondition

Optional string. Values can be "on", "off" or "silent".
On mode: IMS will try to guess precondition from supported header, SDP content and/or VoLTE compatibility of client.
Off mode: no precondition and no dedicated bearer establishment.
Silent mode: dedicated bearers will be established whatever the SIP and SDP content.

100relue_db.impu.100rel

Optional boolean (default = true). Enable/disable 100rel support for this IMPU.

preferredue_db.impu.preferred

Optional boolean (default: false). If set, this impu will be used for preferred identity and for INVITE request URI.

assertedue_db.impu.asserted

Optional boolean (default: false). If set, this impu will be used for asserted identity.

associatedue_db.impu.associated

Optional boolean (default: true). If set to false, this impu will not be used for associated URI.

display_nameue_db.impu.display_name

Optional string. If set, SIP headers will use this field for display name.

domainue_db.impu.domain

Optional string. Used to override user or global config.

p_called_party_idue_db.impu.p_called_party_id

Optional string. If set, forces P-Called-Party-ID header for INVITE and MESSAGE requests, no matter if p_called_party_id global parameter is set or not.

answer_delayue_db.impu.answer_delay

Optional number. If set, when doing a echo call on this IMPU, OK response to INVITE request will be delayed by answer_delay in seconds.

sms_delayue_db.impu.sms_delay

Optional number. If set, IMS will wait sms_delay seconds before sending SMS to this IMPU.

media_delayue_db.impu.media_delay

Optional number. Delay sending of media packet in seconds.

remote_controlue_db.impu.remote_control

Optional boolean. If set to true on a echo impu, the sending of final of INVITE request will be controled by dialog_set remote API with answer action (The delay to send answer is defined by dialog_timeout parameter.
A remote API invite event will be sent with dialog session_id.

sdp_fileue_db.impu.sdp_file

Optional string. When used in echo mode, use the SDP file to force the media sent in server SDP response.

session_expiresue_db.impu.session_expires

Optional object. If set, will override global session timer parameters for that impu, See session_expires.
If IMS is the server (MO call and echo call), caller configuration will be used, else (MT call) callee’s one will be used.

callflow_modifierue_db.impu.callflow_modifier

Optional object or array of objects. This allows to modify IMS behavior and messages.
Each object will define a modification in the SIP callflow.
The modifier will be applied with following rules:

• On MO dialogs, callee modifiers will be used.
• On MT dialogs, caller modifiers will be used.

Each object is defined this way:

methodue_db.impu.callflow_modifier.method

Optional string. Defines on which step to apply modifier (if not set, applies on any of the following). Modifier applies on reception or sending of message depending on dir parameter
If set to INVITE.OK, modifier applies on final answer of INVITE request.
If set to INVITE.TRYING, modifier applies on 100 SIP responses. If set to INVITE.RINGING, modifier applies on 180 SIP responses. If set to INVITE.SESSION_PROGRESS, modifier applies on 183 SIP responses. If set to INVITE, SUBSCRIBE, REGISTER, UPDATE, CANCEL, PRACK, MESSAGE, modifier applies on received or sent requests.
If set to REGISTER.SOS, modifier applies on reception of emergency REGISTER.
If set to REINVITE, modifier applies on received or sent INVITE requests during an established dialog.

codeue_db.impu.callflow_modifier.code

Optional number (between 100 and 699). If set, modifier will generate a SIP response with this code and modifier will apply on this message.
If code is not set, no response wil be generated.

stopue_db.impu.callflow_modifier.stop

Optional boolean (default = true). If set to true and modifier applies within a dialog, dialog will be stopped. In that case, normal callflow will be stopped.

dirue_db.impu.callflow_modifier.dir

Optional string (default = both). Can be tx to apply modifier on sent messages, rx to apply modifier on received messages or both for both type of messages.

transparentue_db.impu.callflow_modifier.transparent

Optional boolean (default = false). If true, modifier will be applied without stopping the normal call flow.

contentue_db.impu.callflow_modifier.content

Optional string. Response body will be filled with content file on generated message.

content_typeue_db.impu.callflow_modifier.content_type

Optional string. Mandatory if content is set, will define response content type.

access_networkue_db.impu.callflow_modifier.access_network

Optional string (default = false). List of RAT separated by comma. If set the callflow will only be affected if P-Access-Network-Info matches the selected RAT. Can be lte (3GPP-E-UTRA), nr (3GPP-NR), or n3gpp (IEEE).

custom_headersue_db.impu.callflow_modifier.custom_headers

Optional Array of object. Apply specific headers on the generated response as defined in custom_headers, except that code and methods parameters are useless.

impuue_db.impu.callflow_modifier.impu

Optional string. Is set, modifier will be applied only if counterpart of the dialog matches this IMPU:

• On MO dialogs, caller IMPU.
• On MT dialogs, callee IMPU.

imeiue_db.impu.callflow_modifier.imei

Optional string. Is set, modifier will be applied only if counterpart (Cf impu) has same IMEI provided during registration.

ttlue_db.impu.callflow_modifier.ttl

Optional integer (> 0). If set, callflow modifier will be removed after having being triggered ttl times.

codeue_db.impu.code

Deprecated. See callflow_modifier

methodue_db.impu.method

Deprecated. See callflow_modifier

contentue_db.impu.content

Deprecated. See callflow_modifier

content_typeue_db.impu.content_type

Deprecated. See callflow_modifier

transparentue_db.impu.transparent

Deprecated. See callflow_modifier

res_lenue_db.res_len

Optional integer (default = 8). Defines length of response in bytes during authentication. For TUAK authentication algorithm, the value must be 4, 8 or 16 bytes long.

authent_typeue_db.authent_type

Optional string (default = AKAv1). Defines minimum authentication level.
If client does no specify authentication algo, server will use this value.
Else, server will allow authentication only if client provided algo is at least the one specified by this parameter.
Values are (from lowest security to highest):

noneue_db.authent_type.none

Disable authentication.

MD5ue_db.authent_type.MD5

MD5 digest authentication.

AKAv1ue_db.authent_type.AKAv1

AKAv1 authentication.

AKAv2ue_db.authent_type.AKAv2

AKAv2 authentication.

authent_qopue_db.authent_qop

Optional string (default = none). Defines authentication qop parameter and can be:

noneue_db.authent_qop.none

Don’t set qop.

authue_db.authent_qop.auth

Use auth qop directive.

pwdue_db.pwd

Optional string. Password set for MD5 authentication. If set and authent_type is not set, authent_type is set to MD5.

mt_call_sdp_fileue_db.mt_call_sdp_file

Optional string. File to use as SDP when using MT call. Overrides global parameter.

domainue_db.domain

Optional string. If set, overrides global config.

auth_on_register_onlyue_db.auth_on_register_only

Optional boolean. If set, overrides global config.

force_sms_over_sgue_db.force_sms_over_sg

Optional boolean. If set, forces use of SMS over SG.

ue_db_filenameue_db_filename

Optional string. If present, store the current IMS state in a persistent file. The IMS state contains in particular the registration info and pending SMS.

6 Remote API

You can access LTEIMS via a remote API.
Protocol used is WebSocket as defined in RFC 6455 (https://tools.ietf.org/html/rfc6455).

Note that Origin header is mandatory for the server to accept connections.
This behavior is determined by the use of nopoll library.
Any value will be accepted.

6.1 Messages

Messages exchanged between client and LTEIMS server are in strict JSON format.

Each message is represented by an object. Multiple message can be sent to server using an array of message objects.

Time and delay values are floating number in seconds.

There are 3 types of messages:

• Request

  Message sent by client.
  Common definition:

  messagerequest.message

  String. Represent type of message. This parameter is mandatory and depending on its value, other parameters will apply.
  

  message_idrequest.message_id

  Optional any type. If set, response sent by the server to this message will have same message_id. This is used to identify response as WebSocket does not provide such a concept.

  start_timerequest.start_time

  Optional float. Represent the delay before executing the message.
  If not set, the message is executed when received.
  

  absolute_timerequest.absolute_time

  Optional boolean (default = false). If set, start_time is interpreted as absolute.
  You can get current clock of system using time member of any response.

  standalonerequest.standalone

  Optional boolean (default = false). If set, message will survive WebSocket disconnection, else, if socket is disconnected before end of processing, the message will be cancelled.

  loop_countrequest.loop_count

  Optional integer (default = 0, max = 1000000). If set, message will be repeated loop_count time(s) after loop_delay (From message beginning of event).
  Response will have a loop_index to indicate iteration number.

  loop_delayrequest.loop_delay

  Optional number (min = 0.1, max = 86400). Delay in seconds to repeat message from its start_time. Mandatory when loop_count is set > 0.

• Response

  Message sent by server after any request message as been processed.
  Common definition:

  messageresponse.message

  String. Same as request.

  message_idresponse.message_id

  Optional any type. Same as in request.

  timeresponse.time

  Number representing time in seconds since start of the process.
  Usefull to send command with absolute time.

  utcresponse.utc

  Number representing UTC seconds.

• Events

  Message sent by server on its own initiative.
  Common definition:

  messageevent.message

  String. Event name.

  timeevent.time

  Number representing time in seconds.
  Usefull to send command with absolute time.

6.2 Startup

When WebSocket connections is setup, LTEIMS will send a first message with name set to com_name and type set to IMS.

If authentication is not set, message will be ready:

{
    "message": "ready",
    "type": "IMS",
    "name": <com_name>
}

If authentication is set, message will be authenticate :

{
    "message": "authenticate",
    "type": "IMS",
    "name": <com_name>,
    "challenge": <random challenge>
}

To authenticate, the client must answer with a authenticate message and a res parameter where:

res = HMAC-SHA256( "<type>:<password>:<name>", "<challenge>" )

res is a string and HMAC-SHA256 refers to the standard algorithm (https://en.wikipedia.org/wiki/HMAC)

If the authentication succeeds, the response will have a ready field set to true.

{
    "message": "authenticate",
    "message_id": <message id>,
    "ready": true
}

If authentication fails, the response will have an error field and will provide a new challenge.

{
    "message": "authenticate",
    "message_id": <message id>,
    "error": <error message>,
    "type": "IMS",
    "name: <name>,
    "challenge": <new random challenge>
}

If any other message is sent before authentication succeeds, the error "Authentication not done" will be sent as a response.

6.3 Errors

If a message produces an error, response will have an error string field representing the error.

6.4 Sample nodejs program

You will find in this documentation a sample program: ws.js.
It is located in doc subdirectory.
This is a nodejs program that allow to send message to LTEIMS.
It requires nodejs to be installed:

dnf install nodejs npm
npm install nodejs-websocket

Use relevant package manager instead of NPM depending on your Linux distribution.

Then simply start it with server name and message you want to send:

./ws.js 127.0.0.1:9003 '{"message": "config_get"}'

6.5 Common messages

config_get

Retrieve current config.

Response definition:

typeconfig_get.type

Always "IMS"

nameconfig_get.name

String representing server name.

logsconfig_get.logs

Object representing log configuration.
With following elements:

layersconfig_get.logs.layers

Object. Each member of the object represent a log layer configuration:

layer name

Object. The member name represent log layer name and parameters are:

levelconfig_get.logs.layers.root.level

See log_options

max_sizeconfig_get.logs.layers.root.max_size

See log_options

keyconfig_get.logs.layers.root.key

See log_options

cryptoconfig_get.logs.layers.root.crypto

See log_options

payloadconfig_get.logs.layers.root.payload

See log_options

verboseconfig_get.logs.layers.root.verbose

Optional boolean. See log_options

countconfig_get.logs.count

Number. Number of bufferizer logs.

rotateconfig_get.logs.rotate

Optional number. Max log file size before rotation.

pathconfig_get.logs.path

Optional string. Log rotation path.

bcchconfig_get.logs.bcch

Boolean. True if BCCH dump is enabled (eNB only).

mibconfig_get.logs.mib

Boolean. True if MIB dump is enabled (eNB only).

lockedconfig_get.locked

Optional boolean. If true, logs configuration can’t be changed with config_set API.

custom_headersconfig_get.custom_headers

Array. Current custom headers configuration See custom_headers.

config_set

Change current config.
Each member is optional.
Message definition:

logsconfig_set.logs

Optional object. Represent logs configuration. Same structure as config_get (See config_get logs member).
All elements are optional.
Layer name can be set to all to set same configuration for all layers.
If set and logs are locked, response will have logs property set to locked.

preconditionconfig_set.precondition

See precondition

session_expiresconfig_set.session_expires

See session_expires

sms_retry_delayconfig_set.sms_retry_delay

See sms_retry_delay

sms_expiresconfig_set.sms_expires

See sms_expires

sms_hook_onlyconfig_set.sms_hook_only

See sms_hook_only

binding_expiresconfig_set.binding_expires

See binding_expires

subscribe_expiresconfig_set.subscribe_expires

See subscribe_expires

auth_on_register_onlyconfig_set.auth_on_register_only

See auth_on_register_only

dialog_timeoutconfig_set.dialog_timeout

See dialog_timeout

p_called_party_idconfig_set.p_called_party_id

See p_called_party_id

sms_message_filterconfig_set.sms_message_filter

See sms_message_filter

sms_forced_cp_causeconfig_set.sms_forced_cp_cause

See sms_forced_cp_cause

sms_forced_rp_causeconfig_set.sms_forced_rp_cause

See sms_forced_rp_cause

mms_expiresconfig_set.mms_expires

See mms_expires

custom_headersconfig_set.custom_headers

Optional array. If set, will replace custom_headers as defined in config file (See custom_headers) or previous call to config_set.

100relconfig_set.100rel

See 100rel

tcp_thresholdconfig_set.tcp_threshold

See tcp_threshold

tcp_keepaliveconfig_set.tcp_keepalive

See tcp_keepalive

tcp_keepcountconfig_set.tcp_keepcount

See tcp_keepcount

log_get

Get logs.
Message definition:

minlog_get.min

Optional number (default = 1). Minimum amount of logs to retrieve.
Response won’t be sent until this limit is reached (Unless timeout occurs).

maxlog_get.max

Optional number (default = 4096). Maximum logs sent in a response.

timeoutlog_get.timeout

Optional number (default = 1). If at least 1 log is available and no more logs have been generated for this time, response will be sent.

allow_emptylog_get.allow_empty

Optional boolean (default = false). If set, response will be sent after timeout, event if no logs are available.

rntilog_get.rnti

Optional number. If set, send only logs matching rnti.

ue_idlog_get.ue_id

Optional number. If set, send only logs with matching ue_id.

layerslog_get.layers

Optional Object. Each member name represents a log layer and values must be string representing maximum level. See log_options.
If layers is not set, all layers level will be set to debug, else it will be set to none.
Note also the logs is also limited by general log level. See log_options.

shortlog_get.short

Optional boolean (default = false). If set, only first line of logs will be dumped.

headerslog_get.headers

Optional boolean. If set, send log file headers.

start_timestamplog_get.start_timestamp

Optional number. Is set, filter logs older than this value in milliseconds.

end_timestamplog_get.end_timestamp

Optional number. Is set, filter logs more recent than this value in milliseconds.

max_sizelog_get.max_size

Optional number (default = 1048576, i.e. 1MB). Maximum size in bytes of the generated JSON message. If the response exceeds this size, the sending of logs will be forced independently from other parameters.

Response definition:

logslog_get.logs

Array. List of logs. Each item is a an object with following members:

datalog_get.logs.data

Array. Each item is a string representing a line of log.

timestamplog_get.logs.timestamp

Number. Milliseconds since January 1st 1970.

layerlog_get.logs.layer

String. Log layer.

levellog_get.logs.level

String. Log level: error, warn, info or debug.

dirlog_get.logs.dir

Optional string. Log direction: UL, DL, FROM or TO.

ue_idlog_get.logs.ue_id

Optional number. UE_ID.

celllog_get.logs.cell

Optional number (only for PHY layer logs). Cell ID.

rntilog_get.logs.rnti

Optional number (only for PHY layer logs). RNTI.

framelog_get.logs.frame

Optional number (only for PHY layer logs). Frame number (Subframe is decimal part).

channellog_get.logs.channel

Optional string (only for PHY layer logs). Channel name.

srclog_get.logs.src

String. Server name.

idxlog_get.logs.idx

Integer. Log index.

headerslog_get.logs.headers

Optional array. Array of strings.

discontinuitylog_get.discontinuity

Optional number. If set, this means some logs have been discarded due to log buffer overflow.

Note that only one request can be sent by client.
If a request is sent before previous one has returned, previous one will be sent without matchine min/max/timeout conditions.

log_set

Add log.
Message definition:

loglog_set.log

Optional string. Log message to add. If set, layer and level are mandatory.

layerlog_set.layer

String. Layer name. Only mandatory if log is set.

levellog_set.level

String. Log level: error, warn, info or debug. Only mandatory if log is set.

dirlog_set.dir

Optional string. Log direction: UL, DL, FROM or TO.

ue_idlog_set.ue_id

Optional number. UE_ID.

flushlog_set.flush

Optional boolean (default = false). If set, flushes fog file.

rotatelog_set.rotate

Optional boolean (default = false). If set, forces log file rotation.

cutlog_set.cut

Optional boolean (default = false). If set, forces log file reset.

log_reset

Resets logs buffer.

quit

Terminates lteims.

help

Provides list of available messages in messages array of strings and events to register in events array of strings.

stats

Report statistics for LTEIMS.
Every time this message is received by server, statistics are reset.
Warning, calling this message from multiple connections simultaneously will modify the statistics sampling time.

Response definition:

cpustats.cpu

Object. Each member name defines a type and its value cpu load in % of one core.

instance_idstats.instance_id

Number. Constant over process lifetime. Changes on process restart.

countersstats.counters

Object. List of counters, with following sub members:

messagesstats.counters.messages

Object. Each member name is the message name and its value is its occurence.
To get list of message, type cevent help msg in LTEIMS monitor.

errorsstats.counters.errors

Object. Each member name is the error name and its value is its occurence.
To get list of message, type cevent help error in LTEIMS monitor.

register

Register client to message generated by server. Message definition:

registerregister.register

String or array of string. List of message to register to.
Can be users_update, sms

unregisterregister.unregister

String or array of string. List of message to unregister.
Can be users_update, sms

ipsec

Report ipsec SAs.

Response definition:

SAsipsec.SAs

Array. List of object representing a security association witth following definition:

typeipsec.SAs.type

String. IP version, can be IPv4 or IPv6.

diripsec.SAs.dir

String. Direction, can be in or out.

spiipsec.SAs.spi

Number. SPI.

ue_idipsec.SAs.ue_id

Number. Associated ue_id.

modeipsec.SAs.mode

String. ESP type, can be tunnel or transport

srcipsec.SAs.src

String. Source IP address.

dstipsec.SAs.dst

String. Destination IP address.

tun_srcipsec.SAs.tun_src

Optional string. Tunnel source IP address.

tun_dstipsec.SAs.tun_dst

Optional string. Tunnel destination IP address.

src_prefixipsec.SAs.src_prefix

Number. Source network prefix.

dst_prefixipsec.SAs.dst_prefix

Number. Destination network prefix.

authent_keyipsec.SAs.authent_key

String. Authentication key in hexadecimal form (Empty string authentication is disabled).

cipher_keyipsec.SAs.cipher_key

String. Ciphering key in hexadecimal form (Empty string ciphering is disabled).

6.6 LTE messages

users_get

Get users state.
Message definition:

registered_only.

Optional boolean (default = false). If set, only registered user will be dumped.

Response definition:

usersusers_get.users

Array of object. Each item represents a user with following parameters:

impiusers_get.users.impi

String. IMPI of user (IP Multimedia Private identity).

force_sms_over_sgusers_get.users.force_sms_over_sg

Optional boolean. Current SMS over SG forcing state.

bindingsusers_get.users.bindings

Array of object. One for each contact binding:

uriusers_get.users.bindings.uri

String. Contact URI.

impuusers_get.users.bindings.impu

Array of strings. List of associated IMPUs.

q

Number. Contact priority.

videousers_get.users.bindings.video

Optional boolean. Video support.

smsusers_get.users.bindings.sms

Optional boolean. SMS pending.

imeiusers_get.users.bindings.imei

Optional string. IMEI.

expiresusers_get.users.bindings.expires

Integer. Number of seconds before binding expiration.

dialogsusers_get.users.dialogs

Array of object. One for each current dialog:

remoteusers_get.users.dialogs.remote

String. IMPI of remote user.

smsusers_get.users.sms

Integer. Number of pending SMS.

users_add

Add users.
Message definition:

users.

Array of object. Same as info in configuration file: See ue_db.

user_set

Configure user.
Message definition:

impiuser_set.impi

String. IMPI of user to configure.

force_sms_over_sguser_set.force_sms_over_sg

Optional boolean. Set/unset forcing of SMS over SG.

impu_set

Configure impu.
Message definition:

impuimpu_set.impu

String. IMPU to configure.

*

Same parameters as impu configuration object. See impu configuration.

impu_add

Add impu.
Message definition:

impuimpu_add.impu

String or object. IMPU to add See impu configuration.

impiimpu_add.impi

String. User for which to add IMPU. Can be set to echo to add it to the echo list.

impu_del

Remove impu.
Message definition:

impuimpu_del.impu

String or object. IMPU to add See impu configuration.

impiimpu_del.impi

String. User for which to remove IMPU. Can be set to echo to remove it from the echo list.

sms

Send SMS.
Message definition:

impisms.impi

Optional string. IMPI of user (IP Multimedia Private identity).

impusms.impu

Optional string. If IMPI is not set, try to get user from IMPU (IP Multimedia Public identity).

textsms.text

String. SMS text to send.

sendersms.sender

Optional string. Sets SMS sender.

validitysms.validity

Optional integer (Default = 86400). Validity period in seconds.

binarysms.binary

Optional string. If set (and text is not set), must be a base64 string representing binary data of the TP-User-Data.

binary_hexsms.binary_hex

Optional string. If set (and text is not set), must be an hexadecimal string representing binary data of the TP-User-Data.

tp_udlsms.tp_udl

Optional integer. Used when binary is set. If present, it sets the TP-User-Data-Length field. If not present, the TP-User-Data-Length field is set to the number of octets of the binary field.

tp_udhi_presentsms.tp_udhi_present

Optional boolean (default is false). When binary is set, indicates if TP-User-Data start with a user-data header or not.

pidsms.pid

Optional integer (default is 0). Defines protocol identifier.

dcssms.dcs

Optional integer (default is 4). Defines data coding scheme. If the text parameter was provided, it’s up to the user to ensure that the dcs value is coherent with the encoding automatically selected (7 bit default GSM alphabet or UCS2).

sms_flush

Flush pending SMS.
Message definition:

impisms_flush.impi

String. IMPI of user (IP Multimedia Private identity).

mms

Send MMS.
Message definition:

filenamemms.filename

String. File name to send. Extensions jpg, jpeg, png, gif and txt are supported.

frommms.from

String. Sender phone number.

tomms.to

String. Receiver phone number.

sosmms.sos

Optional boolean (default = false). If set, will only try to reach emergency registered UEs.

mt_call

Initiate a mobile terminating call.
Message definition:

impimt_call.impi

String. IMPI (IP Multimedia Private identity) of user to call.

impumt_call.impu

String. IMPU (IP Multimedia Public identity) of user to call.

contactmt_call.contact

String. Contact SIP uri of user to call.

sip_filemt_call.sip_file

Optional string. Define file to use as sdp. Will override mt_call_sdp_file parameter.

callermt_call.caller

Optional string. Use it to force caller IMPU. If IMPU is in user database, the P-Asserted-Identity header will be added.

sosmt_call.sos

Optional boolean (default = false). If set, will only try to reach emergency registered UEs.

durationmt_call.duration

Optional number. If set, call duration in seconds (The server will close the dialog).

Response definition:

session_idmt_call.session_id

String. If call has started, provides its session ID.

dialog_get

Get list of current pending dialogs.
Dialog will persist 30s after being stopped. Message definition:

session_iddialog_get.session_id

Optional string. If set, filter on session ID.

Response definition:

dialogsdialog_get.dialogs

Array of object representing dialogs as follow:

session_iddialog_get.dialogs.session_id

String. Dialog session ID.

statedialog_get.dialogs.state

String. Dialog state, can be init, ringing, start, hold or stop.

typedialog_get.dialogs.type

String. Dialog type, can be server, echo or mt call

todialog_get.dialogs.to

Callee IMPU.

fromdialog_get.dialogs.from

Caller IMPU.

mt_dialogdialog_get.dialogs.mt_dialog

Optional string. In case of server dialog, session id of associated MT dialog.

mo_dialogdialog_get.dialogs.mo_dialog

Optional string. In case of client dialog, session id of associated MO dialog.

datedialog_get.dialogs.date

Integer. Dialog creation time in seconds since 1st January 1970.

durationdialog_get.dialogs.duration

Number. Number of seconds since dialog has started.

event_listdialog_get.dialogs.event_list

Array of object representing events that has occurred during dialog lifetime.
Each element have the following definition:

typedialog_get.dialogs.event_list.type

String. Event type, can be state, when a state change occurs, send and recv when receiving or sending message.

timestampdialog_get.dialogs.event_list.timestamp

Number. Event time in seconds since dialog creation.

statedialog_get.dialogs.event_list.state

String. Dialog state when event has occurred as defined above.

mediasdialog_get.dialogs.medias

Array of object representing media state.
Each media is an object having following definition:

typedialog_get.dialogs.medias.type

String. Media type, can be audio or video.

qosdialog_get.dialogs.medias.qos

String. QoS state, can be:

• disabled: QoS not enabled, IETF mode used.
• required: QoS required but not yet initiated.
• pending: QoS dedicated bearer establishment in progress.
• erab_set: QoS done.

dirdialog_get.dialogs.medias.dir

String. Media current direction, can be sendrecv, sendonly, recvonly or inactive.

rtp_addrdialog_get.dialogs.medias.rtp_addr

String. RTP packets destination address.

rtp_recv_countdialog_get.dialogs.medias.rtp_recv_count

Integer. Number of RTP packets received.

rtp_send_countdialog_get.dialogs.medias.rtp_send_count

Integer. Number of RTP packets sent.

rtcp_addrdialog_get.dialogs.medias.rtcp_addr

String. RTCP packets destination address.

rtcp_recv_countdialog_get.dialogs.medias.rtcp_recv_count

Integer. Number of RTCP packets received.

rtcp_send_countdialog_get.dialogs.medias.rtcp_send_count

Integer. Number of RTCP packets sent.

dialog_set

Perform action on dialog Message definition:

session_iddialog_set.session_id

String. Session ID of dialog to stop.

actiondialog_set.action

String. Action to perform.

Action	Description
stop	Forces termination of the dialog.
answer	Triggers INVITE final answer of an echo called configured with remote_control option.
reinvite	Forces sending of INVITE if the dialog is tarted.
hold	Hold or unhold MT or ECHO dialog.
downgrade	Downgrades call by removing one media.
media	Modify media behavior.

codedialog_set.code

Optional integer. If action is answer, forces SIP code.
It action is stop, set protocol cause of SIP reason header.

reasondialog_set.reason

Optional string. If action is stop, set reason text of SIP reason header.

reason_protocoldialog_set.reason_protocol

Optional string. If action is stop, set protocol of SIP reason header.

sdp_filedialog_set.sdp_file

Optional string. Applicable on MT call dialogs only. Forces a new SDP to be sent.

mediadialog_set.media

Optional string. If action is downgrade, defines media to remove (Can be audio or video).

rtpdialog_set.rtp

Optional boolean (default = false). If action is media, set it to false to block rtp packet streaming or true to re-enable it.

rtcpdialog_set.rtcp

Optional boolean (default = false). If action is media, set it to false to block rtcp packet streaming or true to re-enable it.

unregister

Force a network deregistration of a binding.  Message definition:

uriunregister.uri

String. Binding URI (Address of Record)

6.7 LTE events

Following events are sent by IMS if they have been registered on WebSocket.

sms

Generated by SMS reception:

sendersms.sender

String. SMS originator.

destinationsms.destination

String. SMS destination.

textsms.text

String. SMS text.

binarysms.binary

String. If text is not set, base64 encoded string of SMS data.

dcssms.dcs

Integer. Data coding scheme.

datesms.date

Integer. SMS sending date in seconds since January 1st 1970.

users_update

Event generated when a change occurs on a user (Registration, call, sms...).

users_updateusers_update.users_update

Array of object. Each item represents a user (See users_get).

dialog

Generated when a dialog’s state has changed.

dialogdialog.dialog

Object. Same as dialog_get

6.8 Examples

1. Config
   1. Client sends

      {
          "message": "config_get",
          "message_id": "foo"
      }
      

   2. Server replies

      {
          "message_id": "foo",
          "message": "config_get",
          "name": "UE",
          "logs": {
              "phy": {
                  "level": "error",
                  "max_size": 0
              },
              ...
              "rrc": {
                  "level": "debug",
                  "max_size": 1
              }
          }
      }
      

2. Error
   1. Client sends

      {
          "message": "bar",
          "message_id": "foo"
      }
      

   2. Server replies

      {
          "message_id": "foo",
          "message": "bar",
          "error": "Unknown message: bar"
      }
      

7 Command line monitor reference

The following commands are available:

help

Display the help. Use help command to have a more detailed help about a command.

log [log_options]

Display the current log state. If log_options are given, change the log options. The syntax is the same as the log_options configuration property.

mme

Lists MME connections

sms impi or impu text

Send a SMS to the user identified by impi or impu if impi has not been found.

sms_flush impi

Flush pending SMS.

mms filename from to

Send a MMS to the user identified by to. Extensions jpg, jpeg, png, gif and txt are supported. For any other extension value, the content type is interpreted as octet stream.

mt_call callee [-d duration] [sip_file] [caller]

Initiate a mobile terminating call.
callee can be IMPI, IMPU or contact URI.
sip_file Define file to use as sdp. Will override mt_call_sdp_file parameter.
caller can be used to force caller IMPU. If IMPU is in user database, the P-Asserted-Identity header will be added.
duration duration of the call in seconds before server closes it.

dialog

Lists all dialogs.

dialog_set dialog-index action

Perform action on dialog.
Can be stop, hold or reinvite (Cf dialog_set).

quit

Stop the program and exit.

8 Log file format

8.1 IMS, SIP

When a message is dumped, the format is:

time layer dir id message

time

Time using the selected format.

layer

Indicate the layer.

dir

FROM or TO or - (No direction associated).

id

For IMS, represents a unique ID associated with a UE binding.
For SIP, represents a unique ID associated to a SIP dialog.

message

Log message.

8.2 CX, RX

When a message is dumped, the format is:

time layer dir addr message

time

Time using the selected format.

layer

Indicate the layer.

dir

FROM or TO or - (No direction associated).

addr

Source IP address for incoming messages.
Destination IP address for outgoing messages.

message

Log message.

8.3 MEDIA

When a message is dumped, the format is:

time layer id dir protocol/media message

time

Time using the selected format.

layer

Indicate the layer.

dir

FROM or TO or - (No direction associated).

id

SIP associated dialog id.

protocol

Can be either RTP or RTCP.

media

Media type: audio, video or text.

message

Log message.

9 Change history

9.1 Version 2024-04-26

• OpenSSL library is upgraded to 1.1.1w

9.2 Version 2024-03-15

• added ttl parameter to callflow_modifier object
• added reason_protocol parameter to dialog_set.stop remote API
• added sms_delay parameter to impu configuration
• added SIP trunk documentation
• added support of ’+’ in sms_centre_address
• added ipsec_mtu parameter
• updated SIP code list

9.3 Version 2023-12-15

• session timer support added
• added loop_count and loop_delay to remote API messages
• added sim_events, sim_events_loop_count and sim_events_loop_delay
• added com_ssl_ca parameter for SSL verification
• added dialog remote API event
• added session_expires parameter to impu object
• added duration, min, refresher, method and force to session_expires object

9.4 Version 2023-09-08

• added media action to dialog_set remote API to allow blocking or not rtp and/or rtcp streams
• sms_centre_address parameter is added
• ipsec remote API added
• tcp_threshold can now be changed during runtime with config_set remote API
• sms_flush remote API added

9.5 Version 2023-06-10

• N5 interface support is added
• added impu_add and impu_del remote API
• added echo monitor command
• added auth qop parameter
• com_logs_lock parameter added to disable logs configuration change via remote API

9.6 Version 2023-03-17

• com_addr parameter now uses [::] address instead of 0.0.0.0 in the delivered configuration file to allow IPv6 connection
• added media_delay to callflow modifier
• auth_on_register_only default value is changed to true instead of false
• added REGISTER.SOS callflow modifier
• added INVITE.RINGING callflow modifier
• added INVITE.SESSION_PROGRESS callflow modifier
• added REINVITE callflow modifier
• added code -2 to callflow modifier
• added code and reason parameters for dialog_set/action stop remote API
• added downgrade action and media parameter to dialog_set remote API

9.7 Version 2022-12-16

• added custom_headers for callflow_modifier
• added path parameter for registration
• added dialog_set remote API and monitor command. Replaces dialog_stop, reinvite and dialog_answer APIs
• added hold action on dialog_set remote API and monitor command
• added imei and impu filters on callflow_modifier
• added sdp_file to dialog_set/reinvite remote API
• added utc parameter to remote API response messages

9.8 Version 2022-09-16

• "ipsec debug" monitor is now deprecated. Set ipsec.verbose to 1 in log configuration
• callflow_modifier is added to impu definition and allows multiple modifiers
• allowed callflow_modifier based on P-Access-Network-Info header
• tcp_keepalive default value changed to 15 minutes
• tcp_keepcount parameter is added
• custom_headers parameter is added to config_get and config_set remote API
• date parameter is added to sms remote API event

9.9 Version 2022-06-17

• OpenSSL library is upgraded to 1.1.1n
• code parameter in impu objet now accepts the value -1 to ignore an incoming SIP message
• tcp_keepalive is added to control keepalive on TCP sockets
• allowed dual emergency/non emergency registration
• sos option is added to mt_call and sms remote APIs
• start_timestamp and end_timestamp are added to log_get API

9.10 Version 2022-03-18

• IMEI is now taken into account to improve calls between UEs using the same IMSI
• binding_expires parameter maximum value is increased from 3600 to 864000

9.11 Version 2021-12-17

• a new sdp_file parameter is added to force the SDP used in echo mode
• a new answer_delay parameter is added to IMPU configuration to delay final answer to INVITE request
• a new INVITE.OK option has been added to method parameter of IMPU configuration to apply code on final answer to INVITE request.
• a new remote_control option has been added to IMPU configuration. It can be handled via a new invite remote API event and a new dialog_answer remote API.
• a new transparent option has been added to IMPU configuration to avoid affecting normal callflow.
• a new impu_set remote API is added to dynamically update impu configurations.
• REGISTER handling has been added to impu method parameter.
• INVITE.TRYING handling has been added to impu method parameter.
• license monitor command is added

9.12 Version 2021-09-17

• the minimum GLIBC version is now 2.17
• logs can be displayed with microseconds precision
• precondition global parameter syntax is updated. Legacy boolean values are still available but we recommend to use on and off instead
• force_user_agent parameter is added to avoid overriding the UE user-agent string when forwarding SIP packets between UEs
• prefered parameter is renamed to preferred. Legacy name is still supported
• the logging format is further described

10 License

lteims is copyright (C) 2012-2024 Amarisoft. Its redistribution without authorization is prohibited.

lteims is available without any express or implied warranty. In no event will Amarisoft be held liable for any damages arising from the use of this software.

For more information on licensing, please refer to license terms.

Abbreviations

APN

Access Point Name

IMPU

IP Multimedia Public Identity

IMPI

IP Multimedia Private Identity