Appendix

Appendix A: Basic Call Flows

General Call Setup

General Call Setup
Figure 1. General Call Setup

Sipwise C5 performs the following checks when processing a call coming from a subscriber and terminated at a peer:

  • Checks if the IP address where the request came from is in the list of trusted IP addresses. If yes, this IP address is taken as the identity for authentication. Otherwise, Sipwise C5 performs the digest authentication.

  • When the subscriber is authorized to make the call, Sipwise C5 applies the Inbound Rewrite Rules for the caller and the callee assigned to the subscriber (if any). If there are no Rewrite Rules assigned to the subscriber, the ones assigned to the subscriber’s domain are applied. On this stage the platform normalises the numbers from the subscriber’s format to E.164.

  • Matches the callee (called number) with local subscribers.

    • If it finds a matching subscriber, the call is routed internally. In this case, Sipwise C5 applies the Outbound Rewrite Rules associated with the callee (if any). If there are no Rewrite Rules assigned to the callee, the ones assigned to the callee’s domain are applied.

    • If it does not find a matching subscriber, the call goes to a peer as described below.

  • Queries the LNP database to find out if the number was ported or not.For details of LNP queries refer to the Local Number Porting chapter.

    • If it was ported, Sipwise C5 applies the LNP Rewrite Rules to the called number.

  • Based on the priorities of peering groups and peering rules (see basicconfiguration:basicconfiguration.adoc#peering_group_selection for details), Sipwise C5 selects peering groups for call termination and defines their precedence.

  • Within every peering group the weight of a peering server defines its probability to receive the call for termination. Thus, the bigger the weight of a server, the higher the probability that Sipwise C5 will send the call to it.

  • Applies the Outbound Rewrite Rules for the caller and the callee assigned to a peering server when sending the call to it.

Endpoint Registration

Registration Call-Flow
Figure 2. Registration Call-Flow

The subscriber endpoint starts sending a REGISTER request, which gets challenged by a 401. After calculating the response of the authentication challenge, it sends the REGISTER again, including the authentication response. The SIP proxy looks up the credentials of the subscriber in the database,does the same calculation, and if the result matches the one from the subscriber, the registration is granted.

The SIP proxy writes the content of the Contact header (e.g. sip:me@1.2.3.4:1234;transport=UDP) into its location table (in case of NAT the content is changed by the SIP load-balancer to the IP/port from where the request was received), so it knows where to reach a subscriber in case on an inbound call to this subscriber (e.g. sip:someuser@example.org is mapped to sip:me@1.2.3.4:1234;transport=UDP and sent out to this address).

If NAT is detected, the SIP proxy sends a OPTIONS message to the registered contact every 30 seconds, in order to keep the NAT binding on the NAT device open. Otherwise, for subsequent calls to this contact, Sipwise C5 wouldn’t be able to reach the endpoint behind NAT (NAT devices usually drop a UDP binding after not receiving any traffic for ~30-60 seconds).

By default, a subscriber can register 5 contacts for an Address of Record (AoR, e.g. sip:someuser@example.org).

Basic Call

Basic Call Call-Flow
Figure 3. Basic Call Call-Flow

The calling party sends an INVITE (e.g. sip:someuser@example.org) via the SIP load-balancer to the SIP proxy. The proxy replies with an authorization challenge in the 407 response, and the calling party sends the INVITE again with authentication credentials. The SIP proxy checks if the called party is a local user. If it is, and if there is a registered contact found for this user, then (after various feature-related tasks for both the caller and the callee) the Request-URI is replaced by the URI of the registered contact (e.g. sip:me@1.2.3.4:1234;transport=UDP). If it’s not a local user but a numeric user, a proper PSTN gateway is being selected by the SIP proxy, and the Request-URI is rewritten accordingly (e.g. sip:+43123456789@2.3.4.5:5060).

Once the proxy has finished working through the call features of both parties involved and has selected the final destination for the call, and - optionally - has invoked the Media Relay for this call, the INVITE is sent to the SIP B2BUA. The B2BUA creates a new INVITE message from scratch (using a new Call-ID and a new From-Tag), copies only various and explicitly allowed SIP headers from the old message to the new one, filters out unwanted media capabilities from the SDP body (e.g. to force audio calls to use G.711 as a codec) and then sends the new message back to the SIP proxy that forwards it to the SIP load-balancer to reach to the called party.

SIP replies from the called party are passed through the elements back to the calling party (replacing various fields on the B2BUA to match the first call leg again). If a reply with an SDP body is received by the SIP proxy (e.g. a 183 or a 200), the Media Relay is invoked again to prepare the ports for the media stream.

Once the 200OK is routed from the called party to the calling party, the media stream is fully negotiated, and the endpoints can start sending traffic to each other (either end-to-end or via the Media Relay). Upon reception of the 200OK, the SIP proxy writes a start record for the accounting process. The 200OK is also acknowledged with an ACK message from the calling party to the called party, according to the SIP 3-way handshake.

Either of the parties can tear down the media session at any time by sending a BYE, which is passed through to the other party. Once the BYE reaches the SIP proxy, it instructs the Media Relay to close the media ports, and it writes a stop record for accounting purposes. Both the start- and the stop-records are picked up by the ngcp-mediator service in a regular interval and are converted into a Call Detail Record (CDR), which will be rated by the ngcp-rate-o-mat process and can be billed to the calling party.

Session Keep-Alive

The SIP B2BUA acts as refresher for the Session-Timer mechanism as defined in RFC 4028. If the endpoints indicate support for session timers during call-setup, then the SIP B2BUA will use an UPDATE or re-INVITE message if enabled per peer, domain or subscriber via Provisioning to check if the endpoints are still alive and responsive. Both endpoints can renegotiate the timer within a configurable range. All values can be tuned using the Admin Panel or the APIs using Peer-, Domain- and Subscriber-Preferences.

Keep in mind that the values being used in the signaling are always half the value being configured. So if you want to send a keep-alive every 300 seconds, you need to provision sst_expires to 600.

If one of the endpoints doesn’t respond to the keep-alive messages or answers with 481 Call/Transaction Does Not Exist, then the call is torn down on both sides. This mechanism prevents excessive over-billing of calls if one of the endpoints is not reachable anymore or "forgets" about the call. The BYE message sent by the B2BUA triggers a stop-record for accounting and also closes the media ports on the Media Relay to stop the call.

Beside the Session-Timer mechanism to prevent calls from being lost or kept open, there is a maximum call length of 21600 seconds per default defined in the B2BUA. This is a security/anti-fraud mechanism to prevent overly long calls causing excessive costs.

Voicebox Calls

Voicebox Call-Flow
Figure 4. Voicebox Call-Flow

Calls to the Voicebox (both for callers leaving a voicemail message and for voicebox owners managing it via the IVR menu) are passed directly from the SIP proxy to the App-Server without a B2BUA. The App-Server maintains its own timers, so there is no risk of over-billing or overly long calls.

In such a case where an endpoint talks via the Media Relay to a system-internal endpoint, the Media Relay bridges the media streams between the public in the system-internal network.

In case of an endpoint leaving a new message on the voicebox, the Message-Waiting-Indication (MWI) mechanism triggers the sending of a unsolicited NOTIFY message, passing the number of new messages in the body. As soon as the voicebox owner dials into his voicebox (e.g. by calling sip:voicebox@example.org from his SIP account), another NOTIFY message is sent to his devices, resetting the number of new messages.

The Sipwise C5 does not require your device to subscribe to the MWI service by sending a SUBSCRIBE (it would rather reject it). On the other hand, the endpoints need to accept unsolicited NOTIFY messages (that is, a NOTIFY without a valid subscription), otherwise the MWI service will not work with these endpoints.

Appendix B: Configuration Overview

config.yml Overview

/etc/ngcp-config/config.yml is the main configuration YAML file used by Sipwise C5. After every changes it need to run the command ngcpcfg apply "my commit message" to apply changes (followed by ngcpcfg push in the PRO version to apply changes to sp2). The following is a brief description of the main variables contained into /etc/ngcp-config/config.yml file.

apps

This section contains parameters for the additional applications that may be activated on Sipwise C5.

apps:
  malicious_call: no

  • malicious_call: If set to 'yes', the Malicious Call Identification (MCID) application will be enabled.

asterisk

The following is the asterisk section:

asterisk:
  log:
    facility: local6
  rtp:
    maxport: 20000
    minport: 10000
  sip:
    bindport: 5070
    dtmfmode: rfc2833
  voicemail:
    enable: no
    fromstring: 'Voicemail server'
    greeting:
      busy_custom_greeting: '/home/user/file_no_extension'
      busy_overwrite_default: no
      busy_overwrite_subscriber: no
      unavail_custom_greeting: '/home/user/file_no_extension'
      unavail_overwrite_default: no
      unavail_overwrite_subscriber: no
    mailbody: 'You have received a new message from ${VM_CALLERID} in voicebox ${VM_MAILBOX} on ${VM_DATE}.'
    mailsubject: '[Voicebox] New message ${VM_MSGNUM} in voicebox ${VM_MAILBOX}'
    max_msg_length: 180
    maxgreet: 60
    maxmsg: 30
    maxsilence: 0
    min_msg_length: 3
    normalize_match: '^00|\+([1-9][0-9]+)$'
    normalize_replace: '$1'
    serveremail: voicebox@sip.sipwise.com

  • log.facility: rsyslog facility for asterisk log, defined in /etc/asterisk/logger.conf.

  • rtp.maxport: RTP maximum port used by asterisk.

  • rtp.minport: RTP minimum port used by asterisk.

  • sip.bindport: SIP asterisk internal bindport.

  • voicemail.greetings.*: set the audio file path for voicemail custom unavailable/busy greetings

  • voicemail.mailbody: Mail body for incoming voicemail.

  • voicemail.mailsubject: Mail subject for incoming voicemail.

  • voicemail.max_msg_length: Sets the maximum length of a voicemail message, in seconds.

  • voicemail.maxgreet: Sets the maximum length of voicemail greetings, in seconds.

  • voicemail.maxmsg: Sets the maximum number of messages that may be kept in any voicemail folder.

  • voicemail.min_msg_length: Sets the minimum length of a voicemail message, in seconds.

  • voicemail.maxsilence: Maxsilence defines how long Asterisk will wait for a contiguous period of silence before terminating an incoming call to voice mail. The default value is 0, which means the silence detector is disabled and the wait time is infinite.

  • voicemail.serveremail: Provides the email address from which voicemail notifications should be sent.

  • voicemail.normalize_match: Regular expression to match the From number for calls to voicebox.

  • voicemail.normalize_replace: Replacement string to return, in order to match an existing voicebox.

autoprov

The following is the autoprovisioning section:

autoprov:
  hardphone:
    skip_vendor_redirect: no
  server:
    bootstrap_port: 1445
    ca_certfile: '/etc/ngcp-config/shared-files/ssl/client-auth-ca.crt'
    host: localhost
    port: 1444
    server_certfile: '/etc/ngcp-config/shared-files/ssl/myserver.crt'
    server_keyfile: '/etc/ngcp-config/shared-files/ssl/myserver.key'
    ssl_enabled: yes
  softphone:
    config_lockdown: 0
    webauth: 0

  • autoprov.skip_vendor_redirect: Skip phone vendor redirection to the vendor provisioning web site.

sems-b2b (some paramenters are only used with additional Cloud PBX module activated)

The following is the B2B section:

b2b:
  bindport: 5080
  dialog_publish_expires: 3600
  enable: yes
  highport: 19999
  lowport: 15000
  media_processor_threads: 10
  moh_codecs:
    codecs_list: PCMA,PCMU,telephone-event
    enable: no
    mode: whitelist
  permit_ext_dial_when_no_prompt_exists: no
  session_processor_threads: 10
  xmlrpcport: 8090

  • b2b.enable: Enable sems-b2b service.

backuptools

The following is the backup tools section:

backuptools:
  cdrexport_backup:
    enable: no
  etc_backup:
    enable: no
  mail:
    address: noc@company.org
    error_subject: '[ngcp-backup] Problems detected during daily backup'
    log_subject: '[ngcp-backup] Daily backup report'
    send_errors: no
    send_log: no
  mysql_backup:
    enable: no
    exclude_dbs: 'syslog sipstats information_schema'
  replicas:
    peer: yes
    mgmt: no
  rotate_days: 7
  storage_dir: '/ngcp-data/backup/ngcp_backup'
  temp_backup_dir: '/ngcp-data/backup/ngcp_backup/tmp'

  • backuptools.cdrexport_backup.enable: Enable backup of cdrexport (.csv) directory.

  • backuptools.etc_backup.enable: Enable backup of /etc/* directory.

  • backuptools.mail.address: Destination email address for backup emails.

  • backuptools.mail.error_subject: Subject for error emails.

  • backuptools.mail.log_subjetc: Subject for daily backup report.

  • backuptools.mail.send_error: Send daily backup error report.

  • backuptools.mail.send_log: Send daily backup log report.

  • backuptools.mysql_backup.enable: Enable daily mysql backup.

  • backuptools.mysql_backup.exclude_dbs: exclude mysql databases from backup.

  • backuptools.replicas.peer: Enable or disable copying the backups to the peer node, for additional safety.

  • backuptools.replicas.mgmt: Enable or disable copying the backups to the mgmt nodes, for additional safety, and so that the management nodes have consolidated backups for the entire cluster.

  • backuptools.rotate_days: Number of days backup files should be kept. All files older than specified number of days are deleted from the storage directory.

  • backuptools.storage_dir: Storage directory of backups.

  • backuptools.storage_group: Name of the group that backup files should be owned by.

  • backuptools.storage_user: Name of the user that backup files should be owned by.

  • backuptools.temp_backup_dir: Temporary storage directory of backups.

cdrexport

The following is the cdr export section:

cdrexport:
  daily_folder: yes
  export_failed: no
  export_incoming: no
  export_nodes:
    roles:
      - mgmt
    hosts:
  exportpath: '/home/jail/home/cdrexport'
  full_names: yes
  monthly_folder: yes

  • cdrexport.daily_folder: Set 'yes' if you want to create a daily folder for CDRs under the configured path.

  • cdrexport.export_failed: Export CDR for failed calls.

  • cdrexport.export_incoming: Export CDR for incoming calls.

  • cdrexport.export_nodes: Export CDRs to specific nodes based on role or hostnames.

  • cdrexport.exportpath: The path to store CDRs in .csv format.

  • cdrexport.full_names: Use full names for CDRs instead of short ones.

  • cdrexport.monthly_folder: Set 'yes' if you want to create a monthly folder (ex. 201301 for January 2013) for CDRs under configured path.

cleanuptools

The following is the cleanup tools section:

cleanuptools:
  acc_cleanup_days: 90
  archive_targetdir: '/ngcp-data/backups/cdr'
  binlog_days: 15
  cdr_archive_months: 2
  cdr_keep_months: 2
  compress: gzip
  delete_old_cdr_files:
    enable: no
    max_age_days: 30
    paths:
      -
        max_age_days: ~
        path: '/home/jail/home/*/20[0-9][0-9][0-9][0-9]/[0-9][0-9]'
        remove_empty_directories: yes
        wildcard: yes
      -
        max_age_days: ~
        path: '/home/jail/home/cdrexport/resellers/*/20[0-9][0-9][0-9][0-9]/[0-9][0-9]'
        remove_empty_directories: yes
        wildcard: yes
      -
        max_age_days: ~
        path: '/home/jail/home/cdrexport/system/20[0-9][0-9][0-9][0-9]/[0-9][0-9]'
        remove_empty_directories: yes
        wildcard: yes
  sql_batch: 10000
  trash_cleanup_days: 30

  • cleanuptools.acc_cleanup_days: CDR records in acc table in kamailio database will be deleted after this time

  • cleanuptools.binlog_days: Time after MySQL binlogs will be deleted.

  • cleanuptools.cdr_archive_months: How many months worth of records to keep in monthly CDR backup tables, instead of dumping them into archive files and dropping them from database.

  • cleanuptools.cdr_keep_months: How many months worth of records to keep in the current cdr table, instead of moving them into the monthly CDR backup tables.

  • cleanuptools.delete_old_cdr_files:

    • enable: Enable (yes) or disable (no) exported CDR cleanup.

    • max_age_days: Gives the expiration time of the exported CDR files in days. There is a general value which may be overridden by a local value provided at a specific path. The local value is valid for the particular path only.

    • paths: an array of path definitions

      • path: a path where CDR files are to be found and deleted; this may contain wildcard characters

      • wildcard: Enable (yes) or disable (no) using wildcards in the path

      • remove_empty_directories: Enable (yes) or disable (no) removing empty directories if those are found in the given path

      • max_age_days: the local expiration time value for files in the particular path

  • cleanuptools.sql_batch: How many records to process within a single SQL statement.

  • cleanuptools.trash_cleanup_days: Time after CDRs from acc_trash and acc_backup tables in kamailio database will be deleted.

For the description of cleanuptools please visit Cleanuptools Description section of the handbook.

cluster_sets

The following is the cluster sets section:

cluster_sets:
  default:
    dispatcher_id: 50
  default_set: default
  type: central

  • cluster_sets.<label>: an arbitrary label of the cluster set; in the above example we have default

  • cluster_sets.<label>.dispatcher_id: a unique, numeric value that identifies a particular cluster set

  • cluster_sets.default_set: selects the default cluster set

  • cluster_sets.type: the type of cluster set; can be central or distributed

database

The following is the database section:

database:
  bufferpoolsize: 24768M

  • database.bufferpoolsize: Innodb_buffer_pool_size value in /etc/mysql/my.cnf

faxserver

The following is the fax server section:

faxserver:
  enable: yes
  fail_attempts: '3'
  fail_retry_secs: '60'
  mail_from: 'Sipwise C5 FaxServer <voipfax@ngcp.sipwise.local>'

  • faxserver.enable: 'yes'/'no' to enable or disable ngcp-faxserver on the platform respectively.

  • faxserver.fail_attempts: Amount of attempts to send a fax after which it is marked as 'failed'.

  • faxserver.fail_retry_secs: Amount of seconds to wait between "fail_attemts".

  • faxserver.mail_from: Sets the e-mail From Header for incoming fax.

general

The following is the general section:

general:
  adminmail: adjust@example.org
  companyname: sipwise
  lang: en
  production: yes
  timezone: localtime

  • general.adminmail: Email address used by monit to send notifications to.

  • general.companyname: Label used in SNMPd configuration.

  • general.lang: Sets sounds language (e.g: 'de' for German)

  • general.production: Label to hint self-check scripts about installation mode.

  • general.timezone: Sipwise C5 Timezone

intercept

The following is the legal intercept section:

intercept:
  enable: no

  • intercept.enable: Enable ngcp-voisniff for Lawful Interception (additional Sipwise C5 module).

kamailio

The following is the kamailio section:

kamailio:
  lb:
    block_useragents:
      action: reject
      block_empty: no
      block_absent: no
      enable: no
      mode: blacklist
      ua_patterns: []
    cfgt: no
    debug:
      enable: no
      modules:
      - level: '1'
        name: core
      - level: '3'
        name: xlog
    debug_level: '1'
    debug_uri:
      enable: no
      redis_db: 27
      htable_idx_size: 4
    dns:
      dns_sctp_pref: 1
      dns_tcp_pref: 1
      dns_tls_pref: 1
      dns_try_naptr: no
      dns_udp_pref: 1
      use_dns_cache: on
    external_sbc: []
    extra_sockets: ~
    filter_content_type:
      enable: yes
      action: filter
      content_type_list:
      - content_type: application/vnd.etsi.cug+xml
        direction: all
      - content_type: application/isup
        direction: reply
      - content_type: application/xml
        direction: request
    max_forwards: '70'
    mem_log: '1'
    mem_summary: '12'
    max_inv_lifetime: '180000'
    nattest_exception_ips:
    - 1.2.3.4
    - 5.6.7.8
    nattest_exception_nets:
    - 192.168.10.0/24
    - 192.168.11.0/24
    pkg_mem: '16'
    port: '5060'
    sdp_line_filter:
      enable: no
      remove_line_startswith: []
    security:
      dos_ban_enable: yes
      dos_ban_time: '300'
      dos_reqs_density_per_unit: '50'
      dos_sampling_time_unit: '5'
      dos_whitelisted_ips: []
      dos_whitelisted_subnets: []
      failed_auth_attempts: '3'
      failed_auth_ban_enable: yes
      failed_auth_ban_time: '3600'
      topoh:
        enable: no
        mask_callid: no
        mask_ip: 127.0.0.8
      topos:
        enable: no
        redis_db: 24
    shm_mem: '64'
    skip_contact_alias_for_ua_when_tcp:
      enable: no
      user_agent_patterns: []
    start: yes
    strict_routing_safe: no
    syslog_options: yes
    tcp_children: 1
    tcp_max_connections: '2048'
    tls:
      enable: no
      port: '5061'
      sslcertfile: /etc/ngcp-config/shared-files/ssl/myserver.crt
      sslcertkeyfile: /etc/ngcp-config/shared-files/ssl/myserver.key
    udp_children: 1
  proxy:
    allow_cf_to_itself: no
    allow_info_method: no
    allow_msg_method: no
    allow_peer_relay: no
    allow_refer_method: no
    always_anonymize_from_user: no
    authenticate_bye: no
    cf_depth_limit: '10'
    cfgt: no
    check_prev_forwarder_as_upn: no
    children: 1
    decode_utu_header: no
    debug:
      enable: no
      modules:
      - level: '1'
        name: core
      - level: '3'
        name: xlog
    debug_level: '1'
    default_expires: '3600'
    default_expires_range: '30'
    dlg_timeout: '43200'
    early_rejects:
      block_admin:
        announce_code: '403'
        announce_reason: Blocked by Admin
      block_callee:
        announce_code: '403'
        announce_reason: Blocked by Callee
      block_caller:
        announce_code: '403'
        announce_reason: Blocked by Caller
      block_contract:
        announce_code: '403'
        announce_reason: Blocked by Contract
      block_in:
        announce_code: '403'
        announce_reason: Block in
      block_out:
        announce_code: '403'
        announce_reason: Blocked out
      block_override_pin_wrong:
        announce_code: '403'
        announce_reason: Incorrect Override PIN
      callee_busy:
        announce_code: '486'
        announce_reason: Busy Here
      callee_offline:
        announce_code: '480'
        announce_reason: Offline
      callee_tmp_unavailable:
        announce_code: '480'
        announce_reason: Temporarily Unavailable
      callee_tmp_unavailable_gp:
        announce_code: '480'
        announce_reason: Unavailable
      callee_tmp_unavailable_tm:
        announce_code: '408'
        announce_reason: Request Timeout
      callee_unknown:
        announce_code: '404'
        announce_reason: Not Found
      cf_loop:
        announce_code: '480'
        announce_reason: Unavailable
      emergency_invalid:
        announce_code: '404'
        announce_reason: Emergency code not available in this region
      emergency_unsupported:
        announce_code: '403'
        announce_reason: Emergency Calls Not Supported
      invalid_speeddial:
        announce_code: '484'
        announce_reason: Speed-Dial slot empty
      locked_in:
        announce_code: '403'
        announce_reason: Callee locked
      locked_out:
        announce_code: '403'
        announce_reason: Caller locked
      max_calls_in:
        announce_code: '486'
        announce_reason: Busy
      max_calls_out:
        announce_code: '403'
        announce_reason: Maximum parallel calls exceeded
      no_credit:
        announce_code: '402'
        announce_reason: Insufficient Credit
      peering_unavailable:
        announce_code: '503'
        announce_reason: PSTN Termination Currently Unavailable
      reject_vsc:
        announce_code: '403'
        announce_reason: VSC Forbidden
      relaying_denied:
        announce_code: '403'
        announce_reason: Relaying Denied
      unauth_caller_ip:
        announce_code: '403'
        announce_reason: Unauthorized IP detected
    emergency_priorization:
      enable: no
      register_fake_200: yes
      register_fake_expires: '3600'
      reject_code: '503'
      reject_reason: Temporary Unavailable
      retry_after: '3600'
    enum_suffix: e164.arpa.
    expires_range: '30'
    filter_100rel_from_supported: no
    filter_failover_response: 408|500|503
    foreign_domain_via_peer: no
    fritzbox:
      enable: no
      prefixes:
      - 0$avp(caller_ac)
      - $avp(caller_cc)$avp(caller_ac)
      - \+$avp(caller_cc)$avp(caller_ac)
      - 00$avp(caller_cc)$avp(caller_ac)
      special_numbers:
      - '112'
      - '110'
      - 118[0-9]{2}
    ignore_auth_realm: no
    ignore_subscriber_allowed_clis: no
    keep_original_to: no
    lcr_stopper_mode: 0
    latency_limit_action: '100'
    latency_limit_db: '500'
    latency_log_level: '1'
    latency_runtime_action: 1000
    lnp:
      add_reply_headers:
        enable: no
        number: P-NGCP-LNP-Number
        status: P-NGCP-LNP-Status
      api:
        add_caller_cc_to_lnp_dst: no
        invalid_lnp_routing_codes:
        - ^EE00
        - ^DD00
        keepalive_interval: '3'
        lnp_request_blacklist: []
        lnp_request_whitelist: []
        port: '8991'
        reply_error_on_lnp_failure: no
        request_timeout: '1000'
        server: localhost
        tcap_field_fci: end.components.0.invoke.parameter
        tcap_field_lnp: ConnectArg.destinationRoutingAddress.0
        tcap_field_opcode: end.components.0.invoke.opCode
      enable: no
      execute_ncos_block_out_before_lnp: no
      skip_callee_lnp_lookup_from_any_peer: no
      strictly_check_ncos: no
      type: api
    lookup_peer_destination_domain_for_pbx: no
    loop_detection:
      enable: no
      expire: '1'
      max: '5'
    max_expires: '43200'
    max_gw_lcr: '128'
    max_registrations_per_subscriber: '5'
    mem_log: '1'
    mem_summary: '12'
    min_expires: '60'
    nathelper:
      sipping_from: sip:pinger@sipwise.local
    nathelper_dbro: no
    natping_interval: '30'
    natping_processes: 1
    nonce_expire: '300'
    pbx:
      hunt_display_fallback_format: '[H %s]'
      hunt_display_fallback_indicator: $var(cloud_pbx_hg_ext)
      hunt_display_format: '[H %s]'
      hunt_display_indicator: $var(cloud_pbx_hg_displayname)
      hunt_display_maxlength: 8
      ignore_cf_when_hunting: no
    peer_probe:
      available_treshold: '1'
      enable: yes
      from_uri_domain: probe.ngcp.local
      from_uri_user: ping
      interval: '10'
      method: OPTIONS
      reply_codes: class=2;class=3;code=403;code=404;code=405
      timeout: '5'
      unavailable_treshold: '1'
    perform_peer_failover_on_tm_timeout: yes
    perform_peer_lcr: no
    pkg_mem: '32'
    port: '5062'
    presence:
      enable: yes
      max_expires: '3600'
      reginfo_domain: example.org
    proxy_lookup: no
    push:
      apns_alert: New call
      apns_sound: incoming_call.xaf
      code_18x: 180
      reason_18x: 'Ringing'
      reply_18x: 'no'
    report_mos: yes
    set_ruri_to_peer_auth_realm: no
    shm_mem: '125'
    skip_pbx_loop: no
    start: yes
    stir:
      cache_dir: /var/cache/kamailio/stir/
      cache_expire: 3600
      domains:
      - name: <domain_name>
        private_key: <path_to_a_private_key_related_to_domain>
      enable: yes
      expire: 300
      libopt: []
      shaken:
        attestation_name: verstat
        attestation_values:
          failed: TN-Validation-Failed
          no_validation: No-TN-Validation
          not_present: TN-Validation-Not-Present
          passed: TN-Validation-Passed
          passed_A: TN-Validation-Passed-A
          passed_B: TN-Validation-Passed-B
          passed_C: TN-Validation-Passed-C
      timeout: 5
    store_recentcalls: no
    syslog_options: yes
    tcp_children: 1
    tm:
      fr_inv_timer: '180000'
      fr_timer: '9000'
      max_inv_lifetime: '180000'
    treat_600_as_busy: yes
    use_enum: no
    usrloc_dbmode: '1'
    voicebox_first_caller_cli: yes
    xfer_other_party_from: no

  • kamailio.lb.block_useragents.action: one of [drop, reject] - Whether to silently drop the request from matching User-Agent or reject with a 403 message.

  • kamailio.lb.block_useragents.block_empty: Enable/disable a rejection of messages with an empty User-Agent header (header present, but no value given).

  • kamailio.lb.block_useragents.block_absent: Enable/disable a rejection of messages with an absent User-Agent header.

  • kamailio.lb.block_useragents.enable: Enable/disable the User-Agent blocking.

  • kamailio.lb.block_useragents.mode: one of [whitelist, blacklist] - Sets the mode of ua_patterns list evaluation (whitelist: block requests coming from all but listed User-Agents, blacklist: block requests from all listed User-Agents).

  • kamailio.lb.block_useragents.ua_patterns: List of User-Agent string patterns that trigger the block action.

  • kamailio.lb.cfgt: Enable/disable unit test config file execution tracing.

  • kamailio.lb.debug.enable: Enable per-module debug options.

  • kamailio.lb.debug.modules: List of modules to be traced with respective debug level.

  • kamailio.lb.debug_uri.enable: Enable/disable sending SIP messages From/To specific subscriber to an inactive proxy node in order to debug/trace calls. Only makes sense on Sipwise C5 CARRIER appliance environment.

  • kamailio.lb.debug_uri.redis_db: A number of internal Redis DB used by htable module to keep the subscribers values

  • kamailio.lb.debug_uri.htable_idx_size: number to control how many slots (buckets) to create for the hash table ( 2^size ). See kamailio htable docs for details.

  • kamailio.lb.debug_level: Default debug level for kamailio-lb.

  • kamailio.lb.dns.use_dns_cache: Enable/disable use of internal DNS cache.

  • kamailio.lb.dns.dns_udp_pref: Set preference for each protocol when doing NAPTR lookups.In order to use remote site preferences set all dns_*_pref to the same positive value (e.g. dns_udp_pref=1, dns_tcp_pref=1, dns_tls_pref=1, dns_sctp_pref=1). To completely ignore NAPTR records for a specific protocol, set the corresponding protocol preference to -1.

  • kamailio.lb.dns.dns_tcp_pref: See above.

  • kamailio.lb.dns.dns_tls_pref: See above.

  • kamailio.lb.dns.dns_sctp_pref: See above.

  • kamailio.lb.dns.dns_try_naptr: Enable NAPTR support according to RFC 3263.

  • kamailio.lb.external_sbc: SIP URI of external SBC used in the Via Route option of peering server.

  • kamailio.lb.extra_sockets: Add here extra sockets for Load Balancer.

  • kamailio.lb.max_forwards: Set the value for the Max Forwards SIP header for outgoing messages.

  • kamailio.lb.mem_log: Specifies on which log level the memory statistics will be logged.

  • kamailio.lb.mem_summary: Parameter to control printing of memory debugging information on exit or SIGUSR1 to log.

  • kamailio.lb.max_inv_lifetime: Set INVITE transaction timeout per the whole transaction if no final reply for an INVITE arrives after a provisional message was received (whole transaction ringing timeout). It has to be equals or greater than kamailio.proxy.tm.fr_inv_timer.

  • kamailio.lb.nattest_exception_ips: List of IPs that don’t need the NAT test.

  • kamailio.lb.nattest_exception_nets: List of IP networks (sub-nets) that don’t need the NAT test. The format is network/mask, see an example of the 'kamailio' section.

  • kamailio.lb.shm_mem: Shared memory used by Kamailio Load Balancer.

  • kamailio.lb.pkg_mem: PKG memory used by Kamailio Load Balancer.

  • kamailio.lb.port: Default listen port.

  • kamailio.lb.remove_isup_body_from_replies: Enable/disable stripping of ISUP part from the message body.

  • kamailio.lb.sdp_line_filter.enable: Enable/Disable filter of SDP lines in all the SIP messages.

  • kamailio.lb.sdp_line_filter.remove_line_startswith: List of the SDP lines that should be removed. Attention: it removes all SDP attribute lines beginning with the listed strings in all media streams.

  • kamailio.lb.security.dos_ban_enable: Enable/Disable DoS Ban.

  • kamailio.lb.security.dos_ban_time: Sets the ban time.

  • kamailio.lb.security.dos_reqs_density_per_unit: Sets the requests density per unit (if we receive more then * lb.dos_reqs_density_per_unit within dos_sampling_time_unit the user will be banned).

  • kamailio.lb.security.dos_sampling_time_unit: Sets the DoS unit time.

  • kamailio.lb.security.dos_whitelisted_ips: Write here the whitelisted IPs.

  • kamailio.lb.security.dos_whitelisted_subnets: Write here the whitelisted IP subnets.

  • kamailio.lb.security.failed_auth_attempts: Sets how many authentication attempts allowed before ban.

  • kamailio.lb.security.failed_auth_ban_enable: Enable/Disable authentication ban.

  • kamailio.lb.security.failed_auth_ban_time: Sets how long a user/IP has be banned.

  • kamailio.lb.topoh.enable: Enable topology masking module (see the Topology Masking Mechanism subchapter for a detailed description).

  • kamailio.lb.topoh.mask_callid: if set to yes, the SIP Call-ID header will also be encoded.

  • kamailio.lb.topoh.mask_ip: an IP address that will be used to create valid SIP URIs, after encoding the real/original header content.

  • kamailio.lb.topos.enable: Enable topology hiding module (see the Topology Hiding Mechanism subchapter for a detailed description).

  • kamailio.lb.topos.redis_db: A number of internal Redis DB used by the topology hiding module.

  • kamailio.lb.start: Enable/disable kamailio-lb service.

  • kamailio.lb.strict_routing_safe: Enable strict routing handle feature.

  • kamailio.lb.syslog_options: Enable/disable logging of SIP OPTIONS messages to kamailio-options-lb.log.

  • kamailio.lb.tcp_children: Number of TCP worker processes.

  • kamailio.lb.tcp_max_connections: Maximum number of open TCP connections.

  • kamailio.lb.tls.enable: Enable TLS socket.

  • kamailio.lb.tls.port: Set TLS listening port.

  • kamailio.lb.tls.sslcertificate: Path for the SSL certificate.

  • kamailio.lb.tls.sslcertkeyfile: Path for the SSL key file.

  • kamailio.lb.udp_children: Number of UDP worker processes.

  • kamailio.proxy.allow_cf_to_itself: Specify whether or not a Call Forward to the same subscriber (main number to an alias or viceversa) is allowed. To stop the CF loop a source number or a b-number have to be defined in the CF configuration.

  • kamailio.proxy.allow_info_method: Allow INFO method.

  • kamailio.proxy.allow_msg_method: Allow MESSAGE method.

  • kamailio.proxy.allow_peer_relay: Allow peer relay. Call coming from a peer that doesn’t match a local subscriber will try to go out again, matching the peering rules.

  • kamailio.proxy.allow_refer_method: Allow REFER method. Enable it with caution.

  • kamailio.proxy.always_anonymize_from_user: Enable anonymization of full From URI (as opposed to only From Display-name part by default), has same effect as enabling the preference anonymize_from_user for all peers.

  • kamailio.proxy.authenticate_bye: Enable BYE authentication.

  • kamailio.proxy.cf_depth_limit: CF loop detector. How many CF loops are allowed before drop the call.

  • kamailio.proxy.cfgt: Enable/disable unit test config file execution tracing.

  • kamailio.proxy.check_prev_forwarder_as_upn: Enable/disable validation of the forwarder’s number taken from the Diversion or History-Info header.

  • kamailio.proxy.children: Number of UDP worker processes.

  • kamailio.proxy.decode_utu_header: Default 'no'. If set to 'yes', the content of the User-to-User field received in 200Ok is decoded and saved in a dedicated field of the ACC records. The decoding consists in few steps: discard everything after the first occurrence of ';', remove the initial '04', hex decode the remaining part.

  • kamailio.proxy.debug.enable: Enable per-module debug options.

  • kamailio.proxy.debug.modules: List of modules to be traced with respective debug level.

  • kamailio.proxy.debug_level: Default debug level for kamailio-proxy.

  • kamailio.proxy.default_expires: Default expires value in seconds for a new registration (for REGISTER messages that contains neither Expires HFs nor expires contact parameters).

  • kamailio.proxy.default_expires_range: This parameter specifies that the expiry used for the registration should be randomly chosen in a range given by default_expires +/- default_expires_range percent. For instance, if default_expires is 1200 seconds and default_expires_range is 50, the expiry is randomly chosen between [600,1800] seconds. If set to '0', default_expires is left unmodified.

  • kamailio.proxy.dlg_timeout: Dialog timeout in seconds (by default 43200 sec - 12 hours).

  • kamailio.proxy.early_rejects: Customize here the response codes and sound prompts for various reject scenarios. See the subchapter Configuring Early Reject Sound Sets for a detailed description.

  • kamailio.proxy.emergency_prioritization.enable: Enable an emergency mode support.

  • kamailio.proxy.emergency_prioritization.register_fake_200: When enabled, generates a fake 200 response to REGISTER from non-prioritized subscriber in emergency mode.

  • kamailio.proxy.emergency_prioritization.register_fake_expires: Expires value for the fake 200 response to REGISTER.

  • kamailio.proxy.emergency_prioritization.reject_code: Reject code for the non-emergency request.

  • kamailio.proxy.emergency_prioritization.reject_reason: Reject reason for the non-emergency request.

  • kamailio.proxy.emergency_prioritization.retry_after: Retry-After value when rejecting the non-emergency request.

    In order to learn about details of emergency priorization function of NGCP please refer to advancedconfiguration:advancedconfiguration.adoc#emergency_prio_main part of the handbook.

  • kamailio.proxy.enum_suffix: Sets ENUM suffix - don’t forget '.' (dot).

  • kamailio.proxy.expires_range: Set randomization of expires for REGISTER messages (similar to default_expires_range but applies to received expires value).

  • kamailio.proxy.filter_100rel_from_supported: Enable filtering of '100rel' from Supported header, to disable PRACK.

  • kamailio.proxy.filter_failover_response: Specify the list of SIP responses that trigger a failover on the next available peering server.

  • kamailio.proxy.foreign_domain_via_peer: Enable/disable of routing of calls to foreign SIP URI via peering servers.

  • kamailio.proxy.fritzbox.enable: Enable detection for Fritzbox special numbers. Ex. Fritzbox add some prefix to emergency numbers.

  • kamailio.proxy.fritzbox.prefixes: Fritybox prefixes to check. Ex. '0$avp(caller_ac)'

  • kamailio.proxy.fritzbox.special_numbers: Specifies Fritzbox special number patterns. They will be checked with the prefixes defined. Ex. '112', so the performed check will be 'sip:0$avp(caller_ac)112@' if prefix is '0$avp(caller_ac)'

  • kamailio.proxy.ignore_auth_realm: Ignore SIP authentication realm.

  • kamailio.proxy.ignore_subscriber_allowed_clis: Set to 'yes' to ignore the subscriber’s allowed_clis preference so that the User-Provided CLI is only checked against customer’s allowed_clis preference.

  • kamailio.proxy.lcr_stopper_mode: 0, default mode first rule to match will stop the gw matching process. 1, lcr will keep matching gws even if the rule has stopper value and after ordering gws by priority it will obey the first stopper value and discard the rest.

  • kamailio.proxy.latency_limit_action: Limit of runtime in ms for config actions. If a config action executed by cfg interpreter takes longer than this value, a message is printed in the logs.

  • kamailio.proxy.latency_limit_db: Limit of runtime in ms for DB queries. If a DB operation takes longer than this value, a warning is printed in the logs.

  • kamailio.proxy.latency_log_level: Log level to print the messages related to latency. Default is 1 (INFO).

  • kamailio.proxy.latency_runtime_action: Limit of runtime in ms for SIP message processing cycle. If the SIP message processing takes longer than this value, a warning is printed in the logs.

  • kamailio.proxy.keep_original_to: Not used now.

  • kamailio.proxy.lnp.add_reply_headers.enable: Enable/disable dedicated headers to be added after LNP lookup.

  • kamailio.proxy.lnp.add_reply_headers.number: Name of the header that will contain the LNP number.

  • kamailio.proxy.lnp.add_reply_headers.status: Name of the header that will contain the LNP return code (200 if OK, 500/480/…​ if an error/timeout is occurred).

  • kamailio.proxy.lnp.api.add_caller_cc_to_lnp_dst: Enable/disable adding of caller country code to LNP routing number of the result ('no' by default, LNP result in E.164 format is assumed).

  • kamailio.proxy.lnp.api.invalid_lnp_routing_codes [only for api type]: number matching pattern for routing numbers that represent invalid call destinations; an announcement is played in that case and the call is dropped.

  • kamailio.proxy.lnp.api.keepalive_interval: Not used now.

  • kamailio.proxy.lnp.api.lnp_request_whitelist [only for api type]: list of matching patterns of called numbers for which LNP lookup must be done.

  • kamailio.proxy.lnp.api.lnp_request_blacklist [only for api type]: list of matching patterns of called numbers for which LNP lookup must not be done.

  • kamailio.proxy.lnp.api.port: Not used now.

  • kamailio.proxy.lnp.api.reply_error_on_lnp_failure: Specifies whether platform should drop the call in case of LNP API server failure or continue routing the call to the original callee without LNP.

  • kamailio.proxy.lnp.api.request_timeout [only for api type]: timeout in milliseconds while Proxy waits for the response of an LNP query from Sipwise LNP daemon.

  • kamailio.proxy.lnp.api.server: Not used now.

  • kamailio.proxy.lnp.api.tcap_field_fci: path of the FCI INFO in the received tcap message

  • kamailio.proxy.lnp.api.tcap_field_lnp: path of the LNP NUMBER in the received tcap/inap message

  • kamailio.proxy.lnp.api.tcap_field_opcode: path of the FCI OPCODE in the received tcap message

  • kamailio.proxy.lnp.enable: Enable/disable LNP (local number portability) lookup during call setup.

  • kamailio.proxy.lnp.execute_ncos_block_out_before_lnp: if set to 'yes', the NCOS and BLOCK_OUT checks will be executed before the LNP lookup. Default is 'no', therefore the check are done after the LNP evaluation and rewriting.

  • kamailio.proxy.lnp.skip_callee_lnp_lookup_from_any_peer: if set to 'yes', the destination LNP lookup is skipped (has same effect as enabling preference skip_callee_lnp_lookup_from_any_peer for all peers).

  • kamailio.proxy.lnp.strictly_check_ncos: specify whether the NCOS LNP should be evaluated even if the LNP lookup was not previously executed or if it didn’t return any occurrence. If set to yes, a whitelist NCOS will fail if the LNP lookup doesn’t return any match. The parameter has no impact on blacklist NCOS.

  • kamailio.proxy.lnp.type: method of LNP lookup; valid values are: local (local LNP database) and api (LNP lookup through external gateways). PLEASE NOTE: the api type of LNP lookup is only available for Sipwise C5 PRO / CARRIER installations.

  • kamailio.proxy.lookup_peer_destination_domain_for_pbx: one of [yes, no, peer_host_name] - Sets the content of destination_domain CDR field for calls between CloudPBX subscribers. In case of 'no' this field contains name of CloudPBX domain; 'yes': peer destination domain; 'peer_host_name': human-readable name of the peering server.

  • kamailio.proxy.loop_detection.enable: Enable the SIP loop detection based on the combination of SIP-URI, To and From header URIs.

  • kamailio.proxy.loop_detection.expire: Sampling interval in seconds for the incoming INVITE requests (by default 1 sec).

  • kamailio.proxy.loop_detection.max: Maximum allowed number of SIP requests with the same SIP-URI, To and From header URIs within sampling interval. Requests in excess of this limit will be rejected with 482 Loop Detected response.

  • kamailio.proxy.max_expires: Sets the maximum expires in seconds for registration. If set to '0', the check is disabled.

  • kamailio.proxy.max_gw_lcr: Defines the maximum number of gateways in lcr_gw table

  • kamailio.proxy.max_registrations_per_subscriber: Sets the maximum registration per subscribers.

  • kamailio.proxy.mem_log: Specifies on which log level the memory statistics will be logged.

  • kamailio.proxy.mem_summary: Parameter to control printing of memory debugging information on exit or SIGUSR1 to log.

  • kamailio.proxy.min_expires: Sets the minimum expires in seconds for registration. If set to '0', the check is disabled.

  • kamailio.proxy.nathelper.sipping_from: Set the From header in OPTIONS NAT ping.

  • kamailio.proxy.nathelper_dbro: Default is "no". This will be "yes" on CARRIER in order to activate the use of a read-only connection using LOCAL_URL

  • kamailio.proxy.natping_interval: Sets the NAT ping interval in seconds.

  • kamailio.proxy.natping_processes: Set the number of NAT ping worker processes.

  • kamailio.proxy.nonce_expire: Nonce expire time in seconds.

  • kamailio.proxy.pbx.hunt_display_fallback_format: Default is '[H %s]'. Sets the format of the hunt group indicator that is sent as initial part of the From Display Name when subscriber is called as a member of PBX hunt group if the preferred format defined by the hunt_display_format and hunt_display_indicator can not be used (as in the case of not provisioned subscriber settings). The '%s' part is replaced with the value of the hunt_display_fallback_indicator variable.

  • kamailio.proxy.pbx.hunt_display_fallback_indicator: The internal kamailio variable that sets the number or extension of the hunt group. Default is $var(cloud_pbx_hg_ext) which is populated during call routing with the extension of the hunt group.

  • kamailio.proxy.pbx.hunt_display_format: Default is '[H %s]'. Sets the format of hunt group indicator that is sent as initial part of the From Display Name when subscriber is called as a member of PBX hunt group. This is the preferred (default) indicator format with Display Name, where the '%s' part is replaced with the value of the hunt_display_indicator variable.

  • kamailio.proxy.pbx.hunt_display_indicator: The internal kamailio variable that contains the preferred identifier of the hunt group. Default is $var(cloud_pbx_hg_displayname) which is populated during call routing with the provisioned Display Name of the hunt group.

  • kamailio.proxy.pbx.hunt_display_maxlength: Default is '8'. Sets the maximum length of the variable used as the part of hunt group indicator in Display Name. The characters beyond this limit are truncated in order for hunt group indicator and calling party information to fit on display of most phones.

  • kamailio.proxy.pbx.ignore_cf_when_hunting: Default is 'no'. Whether to disregard all individual call forwards (CFU, CFB, CFT and CFNA) of PBX extensions when they are called via hunt groups. Note that call forwards configured to local services such as Voicebox or Conference are always skipped from group hunting.

  • kamailio.proxy.peer_probe.enable: Enable the peer probing, must be also checked per individual peer in the panel/API.

  • kamailio.proxy.peer_probe.interval: Peer probe interval in seconds.

  • kamailio.proxy.peer_probe.timeout: Peer probe response wait timeout in seconds.

  • kamailio.proxy.peer_probe.reply_codes: Defines the response codes that are considered successful response to the configured probe request, e.g. class=2;class=3;code=403;code=404;code=405, with class defining a code range.

  • kamailio.proxy.peer_probe.unavailable_treshold: Defines after how many failed probes a peer is considered unavailable.

  • kamailio.proxy.peer_probe.available_treshold: Defines after how many successful probes a peer is considered available.

  • kamailio.proxy.peer_probe.from_uri_user: From-userpart for the probe requests.

  • kamailio.proxy.peer_probe.from_uri_domain From-hostpart for the probe requests.

  • kamailio.proxy.peer_probe.method: [OPTIONS|INFO] - Request method for probe request.

    You can find more information about peer probing configuration in advancedconfiguration:advancedconfiguration.adoc#peer_probing_config of the handbook.

  • kamailio.proxy.perform_peer_failover_on_tm_timeout: Specifies the failover behavior when maximum ring timeout (fr_inv_timer) has been reached. In case it is set to 'yes': failover to the next peer if any; in case of 'no' stop trying other peers.

  • kamailio.proxy.perform_peer_lcr: Enable/Disable Least Cost Routing based on peering fees.

  • kamailio.proxy.pkg_mem: PKG memory used by Kamailio Proxy.

  • kamailio.proxy.shm_mem: Shared memory used by Kamailio Proxy.

  • kamailio.proxy.port: SIP listening port.

  • kamailio.proxy.presence.enable: Enable/disable presence feature

  • kamailio.proxy.presence.max_expires: Sets the maximum expires value for PUBLISH/SUBSCRIBE message. Defines expiration of the presentity record.

  • kamailio.proxy.presence.reginfo_domain: Set FQDN of Sipwise C5 domain used in callback for mobile push.

  • kamailio.proxy.push.apns_alert: Set the content of 'alert' field towards APNS.

  • kamailio.proxy.push.apns_sound: Set the content of 'sound' field towards APNS.

  • kamailio.proxy.push.code_18x: code to be sent if reply_18x is 'yes'. Default: 180.

  • kamailio.proxy.push.reason_18x: reason phrase to be sent if reply_18x is 'yes'. Default: 'Ringing'.

  • kamailio.proxy.push.reply_18x: If set to 'yes' proxy will send a 18x message using code_18x and reason_18x config values after sending the PUSH notification. So caller will hear a fake ringing while the app is wakening.

  • kamailio.proxy.report_mos: Enable MOS reporting in the log file.

  • kamailio.proxy.set_ruri_to_peer_auth_realm: Set R-URI using peer auth realm.

  • kamailio.proxy.start: Enable/disable kamailio-proxy service.

  • kamailio.proxy.stir.cache_dir: A path to the directory where to store cached public keys. This directory must be r/w for kamailio user.

  • kamailio.proxy.stir.cache_expire: An interval in seconds after which a cached public key is considered expired.

  • kamailio.proxy.stir.domains: A list of domains for which STIR is enabled, includes the 'name' - domain name (FQDN), the 'private_key' - a path to the private key.

  • kamailio.proxy.stir.enable: Enable or disable STIR/SHAKEN support in Sipwise C5.

  • kamailio.proxy.stir.libopt: Optional, set a libsecsipid option. The value has to be a list of options: name=value.

  • kamailio.proxy.stir.shaken: A sub-block of options related to a treatment of incoming calls (mostly is used to define what are the values to be used in PAI header). For now Sipwise C5 only controls with it an optional parameter 'verstat' for the PAI header.

  • kamailio.proxy.stir.timeout: An interval in seconds after which the HTTP GET operation to download the public key times out.

  • kamailio.proxy.skip_pbx_loop: Enable or disable the sems pbx loop for pbx subscribers

  • kamailio.proxy.store_recentcalls: Store recent calls to redis (used by Malicious Call Identification application and VSCs related to recent calls redial).

  • kamailio.proxy.syslog_options: Enable/disable logging of SIP OPTIONS messages to kamailio-options-proxy.log.

  • kamailio.proxy.tcp_children: Number of TCP worker processes.

  • kamailio.proxy.tm.fr_inv_timer: Set INVITE transaction timeout per branch if no final reply for an INVITE arrives after a provisional message was received (branch ringing timeout).

  • kamailio.proxy.tm.fr_timer: Set INVITE transaction timeout if the destination is not responding with provisional response message.

  • kamailio.proxy.tm.max_inv_lifetime: Set INVITE transaction timeout per the whole transaction if no final reply for an INVITE arrives after a provisional message was received (whole transaction ringing timeout). It has to be equals or greater than kamailio.proxy.tm.fr_inv_timer.

  • kamailio.proxy.treat_600_as_busy: Enable the 6xx response handling according to RFC3261. When enabled, the 6xx response should stop the serial forking. Also, CFB will be triggered or busy prompt played as in case of 486 Busy response.

  • kamailio.proxy.use_enum: Enable/Disable ENUM feature.

  • kamailio.proxy.usrloc_dbmode: Set the mode of database usage for persistent contact storage.

  • kamailio.proxy.voicebox_first_caller_cli: When enabled the previous forwarder’s CLI will be used as caller CLI in case of chained Call Forwards.

  • kamailio.proxy.xfer_other_party_from: If set to 'yes' transferred calls will have the number of the transferred party in the From header. Default is 'no', thus transferred calls have the number of the transferrer party in the From header.

ngcp-mediator

The following is the ngcp-mediator section:

mediator:
  interval: 10

  • mediator.interval: Running interval of ngcp-mediator.

modules

The following is the modules section:

modules:
  - enable: no
    name: dummy
    options: numdummies=2

  • modules: list of configs needed for load kernel modules on boot.

  • enable: Enable/disable loading of the specific module (yes/no)

  • name: kernel module name

  • options: kernel module options if needed

monitoring

The following is the monitoring section:

monitoring:
  backend: prometheus
  filesystems:
  - /
  - /ngcp-data
  - /ngcp-fallback
  - /mnt/glusterfs
  interval: 10
  prometheus_server: victoria-metrics
  retention_policy_long_duration: 12
  retention_policy_short_duration: 15
  retrospect_interval: 30
  threshold:
    cpu_idle_min: '0.1'
    disk_used_max: '0.9'
    kamailio_lb_pkgmem_min: 1048576
    kamailio_lb_shmem_min: '1048576'
    kamailio_proxy_pkgmem_min: 1048576
    kamailio_proxy_shmem_min: '1048576'
    load_long_max: '2'
    load_medium_max: '2'
    load_short_max: '3'
    mem_used_max: 0.98
    mta_queue_len_max: '15'
    mysql_replication_delay_max: 60
    sip_responsiveness_max: '15'
    sslcert_timetoexpiry: '30'
    sslcert_whitelist: []
    swap_free_min: 0.02
  timeout: 10

  • monitoring.backend: The monitoring implementation backend to use. Valid value is: 'prometheus' (default).

  • monitoring.filesystems: The filesystem mount points to monitor.

  • monitoring.interval: The number of seconds between each data gathering iteration.

  • monitoring.prometheus_server: The prometheus server implementation to use. Either 'victoria-metrics' (default) or 'prometheus'.

  • monitoring.retention_policy_long_duration: The long term retention policy for metrics in the monitoring database in months.

  • monitoring.retention_policy_short_duration: The short term retention policy for metrics in the monitoring database in days.

  • monitoring.restrospect_interval: The number of seconds to look into the past, when checking for the last value for a data point.

  • monitoring.threshold.*: These settings specify the thresholds that once crossed will make various components on the system (that is ngcp-status, ngcp-collective-check, snmpd or monit) emit alarms or warnings.

  • monitoring.threshold.cpu_idle_min: Sets the minimum value for CPU usage (0.1 means 10%).

  • monitoring.threshold.disk_used_max: Sets the maximum value for DISK usage (0.9 means 90%).

  • monitoring.threshold.kamailio_lb_pkgmem_min: Sets the minimum value for Kamailio lb package memory usage per process.

  • monitoring.threshold.kamailio_lb_shmem_min: Sets the minimum value for Kamailio lb shared memory usage.

  • monitoring.threshold.kamailio_proxy_pkgmem_min: Sets the minimum value for Kamailio proxy package memory usage per process.

  • monitoring.threshold.kamailio_proxy_shmem_min: Sets the minimum value for Kamailio proxy shared memory usage.

  • monitoring.threshold.load_long_max/load_long_max/load_short_max: Max values for load (long, short, medium term).

  • monitoring.threshold.mem_used_max: Sets the maximum value for memory usage (0.7 means 70%).

  • monitoring.threshold.mta_queue_len_max: Sets the maximum value for the MTA queue length.

  • monitoring.threshold.mysql_replication_delay_max: Sets the maximum MySQL replication delay in seconds.

  • monitoring.threshold.sip_responsiveness_max: Sets the maximum SIP responsiveness time timeout for the SIP options.

  • monitoring.threshold.sslcert_timetoexpiry: Sets the number of days before a SSL certificate expiry starts to warn.

  • monitoring.threshold.sslcert_whitelist: Sets a list of SSL certificate fingerprints to whitelist from the expiry check.

  • monitoring.threshold.swap_free_min: Sets the minimum value for free swap (0.5 means 50%).

  • monitoring.timeout: The timeout for backend queries in seconds, after which the query is considered to have failed due to lack of responsiveness.

nginx

The following is the nginx section:

nginx:
  status_port: 8081
  xcap_port: 1080

  • nginx.status_port: Status port used by nginx server

  • nginx.xcap_port: XCAP port used by nginx server

ntp

The following is the ntp server section:

ntp:
  servers:
    - 0.debian.pool.ntp.org
    - 1.debian.pool.ntp.org
    - 2.debian.pool.ntp.org
    - 3.debian.pool.ntp.org

  • ntp.servers: Define your NTP server list.

ossbss

The following is the ossbss section:

ossbss:
  apache:
    port: 2443
    proxyluport: 1080
    restapi:
      sslcertfile: '/etc/ngcp-panel/api_ssl/api_ca.crt'
      sslcertkeyfile: '/etc/ngcp-panel/api_ssl/api_ca.key'
    serveradmin: support@sipwise.com
    servername: "\"myserver\""
    ssl_enable: yes
    sslcertfile: '/etc/ngcp-config/shared-files/ssl/myserver.crt'
    sslcertkeyfile: '/etc/ngcp-config/shared-files/ssl/myserver.key'
  frontend: no
  htpasswd:
    -
      pass: '{SHA}w4zj3mxbmynIQ1jsUEjSkN2z2pk='
      user: ngcpsoap
  logging:
    apache:
      acc:
        facility: daemon
        identity: oss
        level: info
      err:
        facility: local7
        level: info
    ossbss:
      facility: local0
      identity: provisioning
      level: DEBUG
    web:
      facility: local0
      level: DEBUG
  provisioning:
    allow_ip_as_domain: 1
    allow_numeric_usernames: 0
    auto_allow_cli: 1
    carrier:
      account_distribution_function: roundrobin
      prov_distribution_function: roundrobin
    credit_warnings:
      -
        domain: example.com
        recipients:
          - nobody@example.com
        threshold: 1000
    faxpw_min_char: 0
    log_passwords: 0
    no_logline_truncate: 0
    pw_min_char: 6
    routing:
      ac_regex: '[1-9]\d{0,4}'
      cc_regex: '[1-9]\d{0,3}'
      sn_regex: '[1-9]\d+'
    tmpdir: '/tmp'

  • ossbss.frontend: Enable disable SOAP interface. Set value to 'fcgi' to enable old SOAP interface.

  • ossbss.htpasswd: Sets the username and SHA hashed password for SOAP access. You can generate the password using the following command: htpasswd -nbs myuser mypassword.

  • ossbss.provisioning.allow_ip_as_domain: Allow or not allow IP address as SIP domain (0 is not allowed).

  • ossbss.provisioning.allow_numeric_usernames: Allow or not allow numeric SIP username (0 is not allowed).

  • ossbss.provisioning.faxpw_min_char: Minimum number of characters for fax passwords.

  • ossbss.provisioning.pw_min_char: Minimum number of characters for sip passwords.

  • ossbss.provisioning.log_password: Enable logging of passwords.

  • ossbss.provisioning.routing: Regexp for allowed AC (Area Code), CC (Country Code) and SN (Subscriber Number).

pbx (only with additional Cloud PBX module activated)

The following is the PBX section:

pbx:
  enable: no

  • pbx.enable: Enable Cloud PBX module.

prosody

The following is the prosody section:

prosody:
  ctrl_port: 5582
  log_level: info

  • prosody.ctrl_port: XMPP server control port.

  • prosody.log_level: Prosody loglevel.

pushd

The following is the pushd section:

pushd:
  apns:
    enable: yes
    endpoint: api.push.apple.com
    endpoint_port: 0
    extra_instances:
    - certificate: '/etc/ngcp-config/shared-files/ssl/PushCallkitCert.pem'
      enable: yes
      key: '/etc/ngcp-config/shared-files/ssl/PushCallkitKey.pem'
      type: callkit
    http2_jwt:
      ec_key: '/etc/ngcp-config/shared-files/ssl/AuthKey_ABCDE12345.pem'
      ec_key_id: 'ABCDE12345'
      enable: yes
      issuer: 'VWXYZ67890'
      tls_certificate: ''
      tls_key: ''
      topic: 'com.example.appID'
    legacy:
      certificate: '/etc/ngcp-config/shared-files/ssl/PushChatCert.pem'
      feedback_endpoint: feedback.push.apple.com
      feedback_interval: '3600'
      key: '/etc/ngcp-config/shared-files/ssl/PushChatKey.pem'
    socket_timeout: 0
  domains:
  - apns:
      endpoint: api.push.apple.com
      extra_instances:
      - certificate: '/etc/ngcp-config/shared-files/ssl/PushCallkitCert-example.com.pem'
        enable: no
        key: '/etc/ngcp-config/shared-files/ssl/PushCallkitKey-example.com.pem''
        type: callkit
      http2_jwt:
        ec_key: '/etc/ngcp-config/shared-files/ssl/AuthKey_54321EDCBA.pem'
        ec_key_id: '54321EDCBA'
        issuer: '09876ZYXWV'
        tls_certificate: ''
        tls_key: ''
        topic: 'com.example.otherAppID'
      legacy:
        certificate: '/etc/ngcp-config/shared-files/ssl/PushChatCert-example.com.pem'
        feedback_endpoint: feedback.push.apple.com
        key: '/etc/ngcp-config/shared-files/ssl/PushChatKey-example.com.pem'
    domain: example.com
    enable: yes
    android:
      key: 'google_api_key_for_example.com_here'
  enable: yes
  android:
    enable: yes
    key: 'google_api_key_here'
    priority:
      call: high
      groupchat: normal
      invite: normal
      message: normal
  muc:
    exclude: []
    force_persistent: 'true'
    owner_on_join: 'true'
  one_device_per_subscriber: no
  port: 45060
  processes: 4
  ssl: yes
  sslcertfile: /etc/ngcp-config/shared-files/ssl/CAsigned.crt
  sslcertkeyfile: /etc/ngcp-config/shared-files/ssl/CAsigned.key
  unique_device_ids: no

  • pushd.enable: Enable/Disable the Push Notification feature.

  • pushd.apns.enable: Enable/Disable Apple push notification.

  • pushd.apns.endpoint: API endpoint hostname or address. Should be one of 'api.push.apple.com' or 'api.development.push.apple.com' for the newer HTTP2/JWT based protocol, or one of 'gateway.push.apple.com' or 'gateway.sandbox.push.apple.com' for the legacy protocol.

  • pushd.apns.endpoint_port: API endpoint port. Normally 443 or alternatively 2197 for the newer HTTP2/JWT based protocol, or 2195 for the legacy protocol.

  • pushd.apns.legacy: Contains all options specific to the legacy APNS protocol. Ignored when HTTP2/JWT is in use.

  • pushd.apns.legacy.certificate: Specify the Apple certificate for push notification https requests from Sipwise C5 to an endpoint.

  • pushd.apns.legacy.key: Specify the Apple key for push notification https requests from Sipwise C5 to an endpoint.

  • pushd.apns.legacy.feedback_endpoint: Hostname or address of the APNS feedback service. Normally one of 'feedback.push.apple.com' or 'feedback.sandbox.push.apple.com'.

  • pushd.apns.legacy.feedback_interval: How often to poll the feedback service, in seconds.

  • pushd.apns.extra_instances: If the iOS app supports Callkit push notifications, they can be enabled here and the required separate certificate and key can be specified. Ignored if HTTP2/JWT is enabled.

  • pushd.http2_jwt: Contains all options specific to the newer HTTP2/JWT based APNS API protocol.

  • pushd.http2_jwt.ec_key: Name of file that contains the elliptic-curve (EC) cryptographic key provided by Apple, in PEM format.

  • pushd.http2_jwt.ec_key_id: 10-digit identification string of the EC key in use.

  • pushd.http2_jwt.enable: Master switch for the HTTP2/JWT based protocol. Disables the legacy protocol when enabled.

  • pushd.http2_jwt.issuer: Issuer string for the JWT token. Normally the 10-digit team ID string for which the EC key was issued.

  • pushd.http2_jwt.tls_certificate: Optional client certificate to use for the TLS connection.

  • pushd.http2_jwt.tls_key: Optional private key for the client certificate to use for the TLS connection.

  • pushd.http2_jwt.topic: Topic string for the JWT token. Normally the bundle ID for the iOS app.

  • pushd.android.enable: Enable/Disable Google push notification.

  • pushd.android.key: Specify the Google key for push notification https requests from Sipwise C5 to an endpoint.

  • pushd.domains: Supports a separate set of push configurations (API keys, certificates, etc) for all subscribers of the given domain.

  • pushd.muc.exclude: list of MUC room jids excluded from sending push notifications.

  • pushd.muc.force_persistent: Enable/Disable MUC rooms to be persistent. Needed for Sipwise C5 app to work with other clients.

  • pushd.muc.owner_on_join: Enable/Disable all MUC participants to be owners of the MUC room. Needed for Sipwise C5 app to work with other clients.

  • pushd.ssl: The security protocol Sipwise C5 uses for https requests from the app in the push notification process.

  • pushd.sslcertfile: The trusted certificate file purchased from a CA

  • pushd.sslcertkeyfile: The key file that purchased from a CA

  • pushd.unique_device_ids: Allows a subscriber to register the app and have the push notification enabled on more than one mobile device.

qos

The QoS section allows configuring the ToS (Type of Service) feature:

qos:
  tos_rtp: 184
  tos_sip: 184

  • qos.tos_rtp: a ToS value for RTP traffic.

  • qos.tos_sip: a ToS value for SIP traffic.

The ToS byte includes both DSCP and ECN bits. So, specify the DSCP value multiplied by four (46x4=184) and, optionally, add the required ECN value to it (1, 2 or 3).

Set the rtpengine.control_tos parameter higher than zero to enable ToS.

ngcp-rate-o-mat

The following is the ngcp-rate-o-mat section:

rateomat:
  enable: yes
  loopinterval: 10
  splitpeakparts: 0

  • rateomat.enable: Enable/Disable ngcp-rate-o-mat

  • rateomat.loopinterval: How long we shall sleep before looking for unrated CDRs again.

  • rateomat.splitpeakparts: Whether we should split CDRs on peaktime borders.

redis

The following is the redis section:

redis:
  database_amount: 16
  port: 6379
  syslog_ident: redis

  • redis.database_amout: Set the number of databases in redis. The default database is DB 0.

  • redis.port: Accept connections on the specified port, default is 6379

  • redis.syslog_ident: Specify the syslog identity.

reminder

The following is the reminder section:

reminder:
  retries: 2
  retry_time: 60
  sip_fromdomain: voicebox.sipwise.local
  sip_fromuser: reminder
  wait_time: 30
  weekdays: '2, 3, 4, 5, 6, 7'

  • reminder.retries: How many times the reminder feature have to try to call you.

  • reminder.retry_time: Seconds between retries.

  • reminder.wait_time: Seconds to wait for an answer.

rsyslog

The following is the rsyslog section:

rsyslog:
  external_logging:
  - address: 192.168.32.1
    enable: no
    loglevel: warning
    port: '514'
    proto: udp
  ngcp_logs_max_size: 2G
  ngcp_logs_preserve_days: '93'

  • rsyslog.external_logging: List of remote syslog servers.

  • rsyslog.external_logging.address: Address of this remote syslog server.

  • rsyslog.external_logging.enable: Enable or disable this remote syslog destination.

  • rsyslog.external_logging.loglevel: Minimum log level to send to this syslog destination.

  • rsyslog.external_logging.port: Port of this remote syslog server.

  • rsyslog.external_logging.proto: Protocol (udp or tcp) for this remote syslog server.

  • rsyslog.ngcp_logs_max_size: Specify a maximum size for log files before they are rotated away.

  • rsyslog.ngcp_logs_preserve_days: Specify how many days to preserve old rotated log files in /var/log/ngcp/old path.

rtpengine

The following is the rtp proxy section:

rtpengine:
  allow_userspace_only: yes
  cdr_logging_facility: ''
  control_tos: 0
  delete_delay: 30
  dtls_passive: no
  enable: yes
  final_timeout: 0
  firewall_iptables_chain: ''
  graphite:
    interval: 600
    prefix: rtpengine.
    server: ''
  log_level: '6'
  maxport: '40000'
  minport: '30000'
  num_threads: 0
  prefer_bind_on_internal: no
  recording:
    enable: no
    mp3_bitrate: '48000'
    log_level: '6'
    nfs_host: 192.168.1.1
    nfs_remote_path: /var/recordings
    output_dir: /var/lib/rtpengine-recording
    output_format: wav
    output_mixed: yes
    output_single: yes
    resample: no
    resample_to: '16000'
    spool_dir: /var/spool/rtpengine
  rtcp_logging_facility: ''
  rtp_timeout: '60'
  rtp_timeout_onhold: '3600'

  • rtpengine.allow_userspace_only: Enable/Disable the user space failover for rtpengine ('yes' means enable). By default rtpengine works in kernel space.

  • rtpengine.cdr_logging_facility: If set, rtpengine will produce a CDR-like syslog line after each call finishes. Must be set to a valid syslog facility string (such as 'daemon' or 'local0').

  • rtpengine.control_tos: If higher than 0, the control messages port uses the configured ToS (Type of Service) bits. See the QoS section below for details.

  • rtpengine.delete_delay: After a call finishes, rtpengine will wait this many seconds before cleaning up resources. Useful for possible late branched calls.

  • rtpengine.dtls_passive: If enabled, rtpengine will always advertise itself as a passive role in DTLS setup. Useful in WebRTC scenarios if used behind NAT.

  • rtpengine.final_timeout: If set, any calls lasting longer than this many seconds will be terminated, no matter the circumstances.

  • rtpengine.firewall_iptables_chain: If set, rtpengine will create an iptables rule for each individual media port opened in this chain.

  • rtpengine.graphite.interval: Interval in seconds between sending updates to the Graphite server.

  • rtpengine.graphite.prefix: Graphite keys will be prefixed with this string. Must include a separator character (such as a trailing dot) if one should be used.

  • rtpengine.graphite.server: Graphite server to send periodic statistics updates to. Disabled if set to an empty string. Must be in format 'IP:port' or 'hostname:port'.

  • rtpengine.log_level: Verbosity of log messages. The default '6' logs everything except debug messages. Increase to 7 to log everything, or decrease to make logging more quiet.

  • rtpengine.maxport: Maximum port used by rtpengine for RTP traffic.

  • rtpengine.minport: Minimum port used by rtpengine for RTP traffic.

  • rtpengine.num_threads: Number of worker threads to use. If set to 0, the number of CPU cores will be used.

  • rtpengine.recording.enable: Enable support for call recording.

  • rtpengine.recording.mp3_bitrate: If saving audio as MP3, bitrate of the output file.

  • rtpengine.recording.log_level: Same as log_level above, but for the recording daemon.

  • rtpengine.recording.nfs_host: Mount an NFS share from this host for storage.

  • rtpengine.recording.nfs_remote_path: Remote path of the NFS share to mount.

  • rtpengine.recording.output_dir: Local mount point for the NFS share.

  • rtpengine.recording.output_format: Either 'wav' for PCM output or 'mp3'.

  • rtpengine.recording.output_mixed: Create output audio files with all contributing audio streams mixed together.

  • rtpengine.recording.output_single: Create separate audio files for each contributing audio stream.

  • rtpengine.recording.resample: Resample all audio to a fixed bitrate ('yes' or 'no').

  • rtpengine.recording.resample_to: If resampling is enabled, resample to this sample rate.

  • rtpengine.recording.spool_dir: Local directory for temporary metadata file storage.

  • rtpengine.rtcp_logging_facility: If set, rtpengine will write the contents of all received RTCP packets to syslog. Must be set to a valid syslog facility string (such as 'daemon' or 'local0').

  • rtpengine.rtp_timeout: Consider a call dead if no RTP is received for this long (60 seconds).

  • rtpengine.rtp_timeout_onhold: Maximum limit in seconds for an onhold (1h).

security

The following is the security section. Usage of the firewall subsection is described in security-performance:security-performance.adoc#firewalling:

security:
  firewall:
    enable: no
    logging:
      days_kept: '7'
      enable: yes
      file: /var/log/firewall.log
      tag: NGCPFW
    nat_rules4: ~
    nat_rules6: ~
    policies:
      forward: DROP
      input: DROP
      output: ACCEPT
    rules4: ~
    rules6: ~

  • security.firewall.enable: Enable/disable iptables configuration and rule generation for IPv4 and IPv6 (default: no)

  • security.firewall.logging.days_kept: Number of days logfiles are kept on the system before being deleted (log files are rotated daily, default: 7)

  • security.firewall.logging.enable: Enables/disables logging of all packets dropped by Sipwise C5 firewall (default: yes)

  • security.firewall.logging.file: File firewall log messages go to (default: /var/log/firewall.log)

  • security.firewall.logging.tag: String prepended to all log messages (internally DROP is added to any tag indicating the action triggering the message, default: NGCPFW)

  • security.firewall.nat_rules4: Optional list of IPv4 firewall rules added to table nat using iptables-persistent syntax (default: undef)

  • security.firewall.nat_rules6: Optional list of IPv6 firewall rules added to table nat using iptables-persistent syntax (default: undef)

  • security.firewall.policies.forward: Default policy for iptables FORWARD chain (default: DROP)

  • security.firewall.policies.input: Default policy for iptables INPUT chain (default: DROP)

  • security.firewall.policies.output: Default policy for iptables OUTPUT chain (default: ACCEPT)

  • security.firewall.rules4: Optional list of IPv4 firewall rules added to table filter using iptables-persistent syntax (default: undef)

  • security.firewall.rules6: Optional list of IPv6 firewall rules added to table filter using iptables-persistent syntax (default: undef)

sems

The following is the SEMS section:

sems:
  bindport: 5080
  conference:
    enable: yes
    max_participants: 10
  debug: no
  highport: 50000
  lowport: 40001
  media_processor_threads: 10
  prepaid:
    enable: yes
  sbc:
    calltimer_enable: yes
    calltimer_max: 3600
    outbound_timeout: 6000
    profile:
    - custom_header: []
      name: ngcp
    - custom_header: []
      name: ngcp_cf
    sdp_filter:
      codecs: PCMA,PCMU,telephone-event
      enable: yes
      mode: whitelist
    session_timer:
      enable: yes
      max_timer: 7200
      min_timer: 90
      session_expires: 300
  session_processor_threads: 10
  vsc:
    block_override_code: 80
    cfb_code: 90
    cfna_code: 93
    cft_code: 92
    cfu_code: 72
    clir_code: 31
    directed_pickup_code: 99
    enable: yes
    park_code: 97
    reminder_code: 55
    speedial_code: 50
    unpark_code: 98
    voicemail_number: 2000
  xmlrpcport: 8090

  • b2b.conference.enable: Enable/Disable conference feature.

  • b2b.conference.max_participants: Sets the number of concurrent participant.

  • b2b.highport: Maximum ports used by sems for RTP traffic.

  • b2b.debug: Enable/Disable debug mode.

  • b2b.lowport: Minimum ports used by sems for RTP traffic.

  • b2b.prepaid.enable: Enable/Disable prepaid feature.

  • b2b.sbc.calltimer_max: Set the default maximum call duration. Note that this value can be overwritten in subscriber/customer/domain preferences setting max_call_duration parameter. Attention: in case of call transfer done by the callee, with max_call_duration set, the timer will be restarted from 0 for the new transferred call.

  • b2b.sbc.outbound_timeout: Set INVITE transaction timeout if the destination is not responding with provisional response message.

  • b2b.sbc.profile.name: Profile’s name where to add the custom headers in 'header_list' config parameter. Supported values: ngcp and ngcp_cf.

  • b2b.sbc.profile.custom_header: List of the custom headers that has to be whitelisted (default) by sems sbc in the corresponding profile.

  • b2b.sbc.session_timer.enable: If set to "no" all session timer headers are stripped off without considering the session timer related configuration done via the web interface. If set to "yes" the system uses the subscriber/peer configurations values set on the web interface. If set to "transparent" no validation is performed on Session Timer headers, they are ignored by SEMS and therefore negotiated end-to-end.

  • b2b.vsc.*: Define here the VSC codes.

sms

This section provides configuration of Short Message Service on the NGCP. Description of the SMS module is provided earlier in this handbook here.

In the below example you can see the default values of the configuration parameters.

sms:
  core:
    admin_port: '13000'
    smsbox_port: '13001'
  enable: no
  loglevel: '0'
  sendsms:
    max_parts_per_message: '5'
    port: '13002'
  smsc:
    dest_addr_npi: '1'
    dest_addr_ton: '1'
    enquire_link_interval: '58'
    host: 1.2.3.4
    id: default_smsc
    max_pending_submits: '10'
    no_dlr: yes
    password: password
    port: '2775'
    source_addr_npi: '1'
    source_addr_ton: '1'
    system_type: ''
    throughput: '5'
    transceiver_mode: '1'
    username: username

  • sms.core.admin_port: Port number of admin interface of SMS core module (running on LB nodes).

  • sms.core.smsbox_port: Port number used for internal communication between bearerbox module on LB nodes and smsbox module on PRX nodes. This is a listening port of the bearerbox module (running on LB nodes).

  • sms.enable: Set to yes if you want to enable SMS module.

  • sms.loglevel: Log level of SMS module; the default '0' will result in writing only the most important information into the log file.

  • sms.sendsms.max_parts_per_message: If the SM needs to be sent as concatenated SM, this parameter sets the max. number of parts for a single (logical) message.

  • sms.sendsms.port: Port number of smsbox module (running on PRX nodes).

  • sms.smsc. : Parameters of the connection to an SMSC

    • dest_addr_npi: Telephony numbering plan indicator for the SM destination, as defined by standards (e.g. '1' stands for E.164)

    • dest_addr_ton: Type of number for the SM destination, as defined by standards (e.g. '1' stands for "international" format)

    • enquire_link_interval: Interval of SMSC link status check in seconds

    • host: IP address of the SMSC

    • id: An arbitrary string for identification of the SMSC; may be used in log files and for routing SMs.

    • max_pending_submits: The maximum number of outstanding (i.e. not acknowledged) SMPP operations between Sipwise C5 and SMSC. As a guideline it is recommended that no more than 10 (default) SMPP messages are outstanding at any time.

    • no_dlr: Do not request delivery report; when sending an SM and this parameter is set to yes, Sipwise C5 will not request DR for the message(s). May be required for some particular SMSCs, in order to avoid "Incorrect status report request parameter usage" error messages from the SMSC.

    • password: This is the password used for authentication on the SMSC.

    • port: Port number of the SMSC where Sipwise C5 will connect to.

    • source_addr_npi: Telephony numbering plan indicator for the SM source, as defined by standards (e.g. '1' stands for E.164)

    • source_addr_ton: Type of number for the SM source, as defined by standards (e.g. '1' stands for "international" format)

    • system_type: Defines the SMSC client category in which Sipwise C5 belongs to; defaults to "VMA" (Voice Mail Alert) when no value is given. (No need to set any value)

    • throughput: The max. number of messages per second that Sipwise C5 will send towards the SMSC. (Value type: float)

    • transceiver_mode: If set to 1 (yes / true), Sipwise C5 will attempt to use a TRANSCEIVER mode connection to the SMSC. It uses the standard transmit port of the SMSC for receiving SMs too.

    • username: This is the username used for authentication on the SMSC.

sshd

The following is the sshd section:

sshd:
  listen_addresses:
    - 0.0.0.0

  • sshd: specify interface where SSHD should run on. By default sshd listens on all IPs found in network.yml with type 'ssh_ext'. Unfortunately sshd can be limited to IPs only and not to interfaces. The current option makes it possible to specify allowed IPs (or all IPs with 0.0.0.0).

sssd

The following is the sssd section:

sssd:
  enable: no
  ldap:
    host: localhost
    port: 636
    base_dn: ''
    access_filter: '(objectClass=posixAccount)'

  • sssd.enable: Enable/disable LDAP authentication via SSSD.

  • sssd.ldap.host: The LDAP hostname to use. The 'localhost' default is there for lack of a better hostname, but it is not currently set up with any account information. This would usually be set to the organization LDAP.

  • sssd.ldap.port: The LDAP port to use for the ldaps protocol, that is LDAP over TLS.

  • sssd.ldap.base_dn: The LDAP base DN to use for searches.

  • sssd.ldap.access_filter: The access filter to apply on searches. The default setting is intended to work for POSIX accounts, but depending on how the LDAP accounts are set up and on the site policies, another filter might be needed.

sudo

The following is in the sudo section:

sudo:
  logging: no
  max_log_sessions: 0

  • logging: enable/disable the I/O logging feature of sudo. See man page of 'sudoreplay(8)'.

  • max_log_sessions: when I/O logging is enabled, specifies how many log sessions per individual user sudo should keep before it starts overwriting old ones. The default '0' means no limit.

ngcp-witnessd

The following is the ngcp-witnessd tool section:

witnessd:
  debug: no
  interval: ~
  gather:
    asr_ner_statistics: yes
    kamailio_concurrent_calls: yes
    kamailio_dialog_active: yes
    kamailio_dialog_early: yes
    kamailio_dialog_incoming: yes
    kamailio_dialog_local: yes
    kamailio_dialog_outgoing: yes
    kamailio_dialog_relay: yes
    kamailio_shmem: yes
    kamailio_usrloc_regdevices: yes
    kamailio_usrloc_regusers: yes
    peering_groups: yes
    mta_queue_len: yes
    mysql_global_status: yes
    mysql_slave_status: yes
    oss_provisioned_subscribers: yes
    sip_responsiveness: yes
    sip_stats_num_packets: yes
    sip_stats_num_packets_perday: yes
    sip_stats_partition_size: yes

  • witnessd.interval: The number of seconds between each data gathering iteration, when the value is undefined, the code will fallback to use monitoring.interval.

  • witnessd.gather.asr_ner_statistics: Enable ASR/NER statistics data.

  • witnessd.gather.kamailio_*: Enable Kamailio statistics data.

  • witnessd.gather.mta_queue_len: Enable MTA (exim4) queue length data.

  • witnessd.gather.mysql_global_status: Enable global MySQL data.

  • witnessd.gather.mysql_slave_status: Enable slave (replication) MySQL data.

  • witnessd.gather.oss_provisioned_subscribers: Enable OSS provisioned subscribers count data.

  • witnessd.gather.sip_*: Enable SIP statistics data.

www_admin

The following is the WEB Admin interface (www_admin) section:

www_admin:
  apache:
    autoprov_port: 1444
  callingcard_features: 0
  callthru_features: 0
  conference_features: 1
  contactmail: adjust@example.org
  fastcgi_workers: 2
  fax_features: 1
  fees_csv:
    element_order:
      - source
      - destination
      - direction
      - zone
      - zone_detail
      - onpeak_init_rate
      - onpeak_init_interval
      - onpeak_follow_rate
      - onpeak_follow_interval
      - offpeak_init_rate
      - offpeak_init_interval
      - offpeak_follow_rate
      - offpeak_follow_interval
      - use_free_time
  http_admin:
    autoprov_port: 1444
    port: 1443
    serveradmin: support@sipwise.com
    servername: "\"myserver\""
    ssl_enable: yes
    sslcertfile: '/etc/ngcp-config/shared-files/ssl/myserver.crt'
    sslcertkeyfile: '/etc/ngcp-config/shared-files/ssl/myserver.key'
  http_csc:
    autoprov_bootstrap_port: 1445
    autoprov_port: 1444
    port: 443
    serveradmin: support@sipwise.com
    servername: "\"myserver\""
    ssl_enable: yes
    sslcertfile: '/etc/ngcp-config/shared-files/ssl/myserver.crt'
    sslcertkeyfile: '/etc/ngcp-config/shared-files/ssl/myserver.key'
  logging:
    apache:
      acc:
        facility: daemon
        identity: oss
        level: info
      err:
        facility: local7
        level: info
  security:
    password_allow_recovery: 0
    password_max_length: 40
    password_min_length: 6
    password_musthave_digit: 0
    password_musthave_lowercase: 1
    password_musthave_specialchar: 0
    password_musthave_uppercase: 0
    password_sip_autogenerate: 0
    password_sip_expose_subadmin: 1
    password_web_autogenerate: 0
    password_web_expose_subadmin: 1
  speed_dial_vsc_presets:
    vsc:
      - '*0'
      - '*1'
      - '*2'
      - '*3'
      - '*4'
      - '*5'
      - '*6'
      - '*7'
      - '*8'
      - '*9'

  • www_admin.http_admin.*: Define the Administration interface and certificates.

  • www_admin.http_csc.*: Define the Customers interface and certificates.

  • www_admin.contactmail: Email to show in the GUI’s Error page.

constants.yml Overview

/etc/ngcp-config/constants.yml is one of the main configuration files that contains important (static) configuration parameters, like Sipwise C5 system-user data.

Sipwise C5 platform administrator should not change content of constants.yml file unless absolutely necessary. Please contact Sipwise Support before changing any of the parameters within the constants.yml file!

maintenance.yml Overview

/etc/ngcp-config/maintenance.yml is one of the main configuration files that contains the maintenance configuration option.

general

The following is the general section:

general:
  maintenance: no

  • general.maintenance: maintenance mode necessary for safe upgrades.

network.yml Overview

/etc/ngcp-config/network.yml is one of the main configuration files that contains network-related configuration parameters, like IP addresses and roles of the node(s) in Sipwise C5 system.

The next example shows a part of the network.yml configuration file. Explanation of all the configuration parameters is provided in Network Configuration section of the handbook.

Sample host configuration for Sipwise C5

A CE would look like:

  self:
    dbnode: '1'
    eth0:
      ip: 10.0.2.15
      netmask: 255.255.255.0
      type:
        - web_ext
        - web_int
        - ssh_ext
    eth1:
      ip: 10.15.20.143
      netmask: 255.255.255.0
      type:
        - ssh_ext
        - web_ext
        - web_int
        - sip_ext
        - rtp_ext
    interfaces:
      - lo
      - eth0
      - eth1
    lo:
      cluster_sets:
        - default
      ip: 127.0.0.1
      netmask: 255.255.255.0
      shared_ip: []
      shared_v6ip: []
      type:
        - sip_int
        - ha_int
        - aux_ext
        - ssh_ext
        - api_int
      v6ip: '::1'
    role:
      - proxy
      - lb
      - mgmt
      - rtp
      - db
    status: 'online'
hosts_common:
  etc_hosts_global_extra_entries:
  - 10.100.1.1 server-1 server-1.internal.example.com
  - 10.100.1.2 server-2 server-2.internal.example.com
The option 'hosts_common' is optional and it allows administrator to provide extra entries in /etc/hosts.

The administrator can create new entries in network.yml to specify extra entries for the file /etc/hosts. One entry is global and two per-host, one of which is local only for the host, and the other overrides global for this host. These entries will be appended without further processing.

The example of adding new entries using 'ngcpcfg set':

ngcpcfg set --diff /etc/ngcp-config/network.yml \
  hosts_common.etc_hosts_global_extra_entries='["10.100.1.1 server-1 server-1.internal.example.com","10.100.1.2 server-2 server-2.internal.example.com"]'

Global is useful if the entries are to be added to all hosts. These probably make more sense in most set-ups.

Per-host local is useful if the entries are only to be added to some node, but not needed or convenient to add to all of them.

Per-host override of the global config is useful if the global entries are to be added to a potentially large number of nodes and to be excluded only in a few of them, to not have to do the contrary (duplicate entries in many hosts except a couple).

Example of modifications to network.yml:

hosts_common:
  etc_hosts_global_extra_entries:
  - 10.100.1.1 server-1 server-1.internal.example.com
  - 10.100.1.2 server-2 server-2.internal.example.com
hosts:
  db01b:
    etc_hosts_local_extra_entries:
    - 127.0.1.1 local-alias-1.db01b
    - 127.0.2.1 local-alias-2.db01b
    - 172.30.52.180 db01b.example.com
  ...
  web01a:
    etc_hosts_local_extra_entries:
    - 127.0.1.1 local-alias-1.web01a
    - 127.0.2.1 local-alias-2.web01a
    - 172.30.52.168 web01a.example.com
    etc_hosts_global_extra_entries:
    - 10.100.1.1 server-1 server-1.internal.example.com
  ...

With this, the output in /etc/hosts for db01b will be:

  # local extra entries for host 'db01b'
  127.0.1.1 local-alias-1.db01b
  127.0.2.1 local-alias-2.db01b
  172.30.52.180 db01b.example.com

  # global extra entries
  10.100.1.1 server-1 server-1.internal.example.com
  10.100.2.1 server-2 server-2.internal.example.com

the content in /etc/hosts on web01a will be:

  # local extra entries for host 'web01a'
  127.0.1.1 local-alias-1.web01a
  127.0.2.1 local-alias-2.web01a
  172.30.52.168 web01a.example.com

  # global extra entries overridden for host 'web01a'
  10.100.1.1 server-1 server-1.internal.example.com

Appendix C: Sipwise C5 Authentication Tokens

Sipwise C5 defines many system users and their authentication credentials in order to provide the necessary security level for its components / services.

Authentication with Password

Credentials of System Users

The list of system users that use password for their authentication is stored in /etc/ngcp-config/constants.yml configuration file.

The table below shows the default usernames. Unless you have a good reason, please do not change the credentials in the file because this may render the related service unavailable!
Table 1. List of system users with password authentication
Purpose / Use case Username Configuration parameters: username / password

Generic system users

Config parameter root: credentials.

Autoprovisioning of Yealink devices

N/A

n/a / autoprov.yealink.p

Faxserver manager

faxserver

faxserver.manager.u / faxserver.manager.p

Fileshare service generic authentication

comx

fileshare.authentication.u / fileshare.authentication.p

Fileshare service app authentication

app

fileshare.simple_upload.u / fileshare.simple_upload.p

HA proxy service

N/A

n/a / haproxy.p

Key for Kamailio load balancer topology hiding

N/A

n/a / kamailio.lb.topoh_key.p

Password for Kamailio proxy UAC encryption

N/A

n/a / kamailio.proxy.uaccryptpw.p

LDAP server access

N/A

n/a / ldap.root.p

REST API internal access

system

rest_api.auth_system.u / rest_api.auth_system.p

Users in MySQL database

Config parameter root: credentials.mysql.

Asterisk voicemail application

asterisk

asterisk.u / asterisk.p

CDR exporter

exporter

cdrexport.u / cdrexport.p

Monitoring subsystem

nagios

monitoring.u / monitoring.p

Cleanuptools (DB purging) utility

dbcleaner

cleanuptools.u / cleanuptools.p

Debian system maintenance

debian-sys-maint

debian.u / debian.p

Fileshare service

fileshare

fileshare.u / fileshare.p

Kamailio read-write DB access

kamailio

kamailio.u / kamailio.p

Kamailio read-only DB access

kamailioro

kamailioro.u / kamailioro.p

LDAP access

ldap

ldap.u / ldap.p

Mediator (CDR pre-processing) service

mediator

mediator.u / mediator.p

Prosody IM server

prosody

prosody.u / prosody.p

Provisioning SOAP interface

soap

provisioning.u / provisioning.p

Rate-o-mat (CDR rating) service

rateomat

rateomat.u / rateomat.p

DB replicator

replicator

replicator.u / replicator.p

Rsyslog service

rsyslog

rsyslog.u / rsyslog.p

RTPEngine service

rtpengine

rtpengine.u / rtpengine.p

B2BUA pre-paid module

sems_prepaid

sems.u / sems.p

Voisniff call capturing service

voisniff

voisniff.u / voisniff.p

SMS service credentials

Config parameter root: sms.

SMS core module admin password

N/A

core.admin_password

SMS API access token

N/A

panel_api_token

SMS sending

sipwise

sendsms.username / sendsms.password

Credentials for External Sipwise C5 Interfaces

Some Sipwise C5 services used by external entities and some external services that NGCP needs to connect to make use of password based authentication. The list of credentials is stored in /etc/ngcp-config/config.yml configuration file.

The table below shows the default usernames. Changing some of them may render the related service unavailable!
Table 2. List of credentials used for external Sipwise C5 interfaces
Purpose / Use case Username Configuration parameters: username / password

Access to exported events (EDR files)

youruser

eventexport.transfer.username / eventexport.transfer.password

Homer LI (Lawful Interception) service

2001

homer.capture_id / homer.capture_pass

SOAP API

ngcpsoap

ossbss.htpasswd[n].user / ossbss.htpasswd[n].user

Sipwise C5 access to SMSC interface

username

sms.smsc.username / sms.smsc.password

TURN access for Sipwise C5 standard RTP media

turnuser

turnserver.user / turnserver.pass

NGCP Panel password encryption

In NGCP Panel, both administrators passwords and subscribers web passwords should be encrypted for obvious security reasons. For subscribers web password, plain text was used until mr8.4 release. From this release on, every newly created subscriber will have the web password properly ecrypted. For customers that have upgraded from earlier versions but full web password encryption is needed, there’s a script that should be used called ngcp-bcrypt-webpassword.

The ngcp-bcrypt-webpassword script will attept to change all subscribers web passwords so it might take some time. Just to have an overview, it will take about 5 minutes for 500 000 subscribers, processing on 8 threads. This works really fast because the cost of bcrypt is lower in this case, but it will be upgraded to default 13 when subscriber logs in but also because it prepares batches of 10 000 subscribers and updates them at once using INSERT INTO ... ON DUPLICATE KEY UPDATE.

Authentication with PKI (Keys and Certificates)

Keys and Certificates for Using Sipwise C5 Services

Some system users of Sipwise C5 authenticate themselves using PKI (Public Key Infrastructure), i.e. keys and certificates. The location of those keys and certificates may be selected in /etc/ngcp-config/config.yml file, using the configuration parameters as listed in the following table.

Table 3. List of keys and certificates used in authentication
Purpose / Use case Configuration parameters: certificate / key

Device autoprovisioning server’s CA certificate

autoprov.server.ca_certfile

Device autoprovisioning server’s own credentials

autoprov.server.server_certfile / autoprov.server.server_keyfile

Load-balancer SIP service TLS connection server side credentials

kamailio.lb.tls.sslcertfile / kamailio.lb.tls.sslcertkeyfile

Generic HTTPS access server side credentials

ossbss.apache.sslcertfile / ossbss.apache.sslcertkeyfile

REST API access server side credentials

ossbss.apache.restapi.sslcertfile / ossbss.apache.restapi.sslcertkeyfile

Mobile Push notification client side credentials for iOS apps

pushd.apns.certificate

Mobile Push notification (local) server’s server side credentials

pushd.sslcertfile / pushd.sslcertkeyfile

RTPEngine service HTTPS credentials

rtpengine.https.crt / rtpengine.https.key

TURN server’s server side credentials

turnserver.sslcertfile / turnserver.sslcertkeyfile

LI (Lawful Interception) X2 / X3 interface client credentials

voisniff.daemon.li_x1x2x3.client_certificate

HTTPS-based admin interface ("Sipwise C5 web panel") server side credentials

www_admin.http_admin.sslcertfile / www_admin.http_admin.sslcertkeyfile

HTTPS-based CSC (Customer Self-Care) interface server side credentials

www_admin.http_csc.sslcertfile / www_admin.http_csc.sslcertkeyfile

HTTPS-based internal API server side credentials

www_admin.http_system.sslcertfile / www_admin.http_system.sslcertkeyfile

Location of Certificates

The following locations of keys and certificates are in use:

  • /etc/ngcp-config/shared-files/ssl

  • /etc/ssl/certs

  • /etc/ssl/private

  • /etc/prosody/certs

  • /etc/kamailio

Appendix D: MariaDB encryption

Overview

MariaDB encryption support (officially called as "Data-at-Rest") enables innodb files, tables and binlogs data encryption so that if copied over the data is not usable without the master key. All the data accessed or modified by clients is encrypted/decrypted on the fly and transparent for the users. The feature comes with a price of 3% to 5% MariaDB performance loss (depending on the hardware, and CPU in particular).

Configuration

There are new options in constants.yml

mysql:
  encryption:
	enable: yes
	encrypt_binlog: yes
	key: 1;a356c82422a9031f2e472047ad8220eeea257d611849fbdc9f75b49933f75241
	threads: 1

NOTE: all changes in the configuration section will cause the MariaDB server to restart when ngcpcfg templates are applied.

  • mysql.encryption.enable: Switch encryption on/off. Values: 'yes','no', Default: 'yes'. When enabled, all tables are being encrypted, it takes from a few seconds to several minutes for MariaDB to encrypt all the data (depending on the overall size) and the encryption procedure is performed in the background, while all the data continues to be fully accessible. Also all new tables are created encrypted by default and it is not possible to disable encryption for specific tables as the encryption is 'forced'.

  • mysql.encryption.encrypt_binlog: Encrypt binlogs. Values: 'yes','no', Default: 'yes'. While it is preferred to have this option enabled by default, for scenarios where binlog files need to be parsed, this option can be turned off. It is also possible to use mysqlbinlog with --read-from-remote-server option to read encrypted binlogs.

  • mysql.encryption.key: Encryption key. The value is randomly generated during the cfg-schema upgrade when the option is added into constants.yml. The key is located in /etc/mysql/keyfile and normally MUST NOT be changed. Changing or losing the key permanently will render all the MariaDB tablespaces data (databases/tables) unusable.

  • mysql.encryption.threads: Amount of encryption threads. Default: 1 How many MariaDB encryption threads should be running, this value depends on how many tables are created/removed or the encryption keys are rotated.

What is not encrypted

  • slow-queries log

  • mysqld.err log

  • general queries log, if enabled

Data restoration remarks

  • When restoring data from an sql backup from another platform it is safe to do that as the currently used 'encryption_key' (inside my.cnf) is not affected this way.

  • When copying constants.yml file from another platform and the encryption is enabled, the current 'mysql.encryption.key' (inside constants.yml) must be restored in constants.yml to the same one the MariaDB server is originally started with or it will fail to start otherwise after ngcpcfg apply.

Appendix E: Disk partitioning

This chapter documents possible disk partitioning on Sipwise C5 available after installation the Sipwise C5. It should be helpful to understand the overall disk partitioning schema.

Supported IO drives

At the moment the following drives are supported: HDD, SSD, and NVMe. We recommend installing NVMe type SSD storage for the best performance. Otherwise, install SATA SSDs for an average performance as SATA hard disks are a good option only for test/development purpose.

The exact model and size depend on the type of the system and the load. We recommend running the initial performance test on the selected hardware before going into production.

Hardware vs. software RAID

The Sipwise C5 can be installed on the pre-configured hardware RAID. In this case, the actual Debian release must support the RAID adapter. Otherwise, the Install CD can configure software RAID 1 if two identical HDD/SSD/NVMe drives are installed (follow the on-screen wizard suggestions). The installation on a single/plain drive is also possible although not recommended for production platforms.

The default disk partitions

The Sipwise C5 supports the modern concept of installing several releases side by side. The ability to switch between the releases simplifies software upgrades and enables rollbacks. You can find all the benefits here here.

The new partitioning logic is simple. The 'code' of services (e.g., kamailio, MariaDB) is separated from the 'data' (e.g., databases, CDR files) generated and processed by the 'code', and is located in a different partition of the disk. Additionally, there are two partitions for 'code' with different services versions. This way, the version of the code can be switched very quickly, by rebooting the system. The 'data' partition will be the same for both versions of the 'code', and it will always be mounted and ready to be used before the services start.

New partition layout:

  NAME                MAJ:MIN RM  SIZE RO TYPE  MOUNTPOINT
  sda                   8:0    0    xG  0 disk             # Your disk with size X Gb
  |-sda1                8:1    0    1M  0 part             # BIOS legacy boot
  |-sda2                8:2    0  486M  0 part  /boot/efi  # UEFI boot
  `-sda3                8:3    0    yG  0 part             # LVM partition
    `-md0               9:0    0    yG  0 raid1            # SW RAID (if requested)
      |-ngcp-root     253:0    0   10G  0 lvm   /          # 'code' partition
      |-ngcp-fallback 253:1    0   10G  0 lvm              # 'fallback' partition
      `-ngcp-data     253:3    0    zG  0 lvm   /ngcp-data # 'data' partition
                                                           # unassigned space

  • 1st partition: 1M BIOS boot, for BIOS/GPT (legacy) boot

    • this allows fallback to grub-pc package (This partition must have its GUID set to 21686148-6449-6E6F-744E-656564454649 To switch to grub-pc, boot from a rescue/live CD, set to bios_grub with parted, then install grub to disk, so it properly embeds core.img)

  • 2nd partition: ~500MB EFI System, for UEFI/GPT boot

    • used as /boot/efi, if EFI support is available

  • 3rd partition: LVM that is divided into:

    • /dev/mapper/ngcp-root with 10GB (rootfs target)
      /dev/mapper/ngcp-fallback with 10GB (for rollback/install/upgrade)

    • 10% or >=500MB (whichever is bigger) of the remaining space is unassigned to allow LVM snapshots during maintenance

    • /dev/mapper/ngcp-data is the /ngcp-data partition with the rest of the disk space for the whole platform 'data' (e.g., databases, CDR files, logs, etc.)

The installer can only boot from GPT and does not support ms-dos partitions anymore. The legacy 'BIOS' systems can also boot from GPT, while (U)EFI systems can only boot from GPT (and not from BIOS/legacy boot).

UEFI

UEFI installation is supported. The dedicated UEFI partition has been created on the disk during the installation (being the second partition in the list).

Swap partition vs. file

The Sipwise C5 performance heavily depends on the IO operations, hence if Swap is used (either the Swap file and/or the Swap partition), the performance might deteriorate. We highly recommend increasing RAM if the platform uses Swap during normal operation.

The Swap partition is no longer in use. The Sipwise C5 has been migrated to the Swap file on the 'data' partition. It gives the following benefits:

  • more space is now available for the 'root', 'rollback' and 'data' partitions.

  • the Swap file size can be easily changed on the fly (if necessary).

  • the Swap file can be migrated to a new location easily: create a new Swap file with the necessary size and location using the 'mkswap' command and activate the new Swap file with 'swapon'. Add the new location to /etc/fstab. Now, you can deactivate the old swapfile with 'swapoff' and remove it to release the disk space.

  • The main reason for the Swap partition usage, used to be 'data fragmentation' on hard disk drives (HDDs) and old types of filesystems. For modern SSD drives, the fragmentation issue is irrelevant and the 'ext4' filesystem does not require manual defragmentation either. The free space on fast SSDs is more important nowadays, as it allows storing more 'data'.

Appendix F: NGCP Internals

This chapter documents internals of Sipwise C5 that should not be usually needed, but might be helpful to understand the overall system.

Pending reboot marker

The Sipwise C5 has the ability to mark a pending reboot for any server, using the file /run/reboot-required. As soon as the file exists, several components will report about a pending reboot to the end-user. The following components report about a pending reboot right now: ngcp-status, ngcpcfg status, motd, ngcp-upgrade. Also, ngcp-upgrade will NOT allow proceeding with an upgrade if it notices a pending reboot. It might affect rtpengine dkms module building if there is a pending reboot requested by a newly installed kernel, etc.

Redis id constants

The list of current Sipwise C5 Redis DB IDs:

Service central (role 'db') pair Release Ticket Description

sems

-

0

mr3.7.1+

-

HA switchover

rtpengine

-

1

mr3.7.1+

-

HA switchover

proxy

2

-

mr3.7.1+

-

Counter of hunting groups

proxy

3

-

mr3.7.1+

-

Concurrent dialog counters

proxy

-

4

mr3.7.1+

-

List of keys of the central counters

prosody

5

-

mr3.7.1+

-

XMPP cluster

sems

7

-

mr4.1.1+

MT#12707

Sems malicious_call app

captagent

-

8

mr4.1.1+ - mr7.1

MT#15427

Old captagent internal data (unused)

monitoring

9

-

mr4.3+ - mr5.5

MT#31

Old SNMP agent monitoring data (unused)

proxy

10

-

mr4.3+

MT#16079

SIP Loop detection

ngcp-panel sessions

-

19

mr6.3+

TT#35523

Panel login sessions

proxy usrloc

20

-

mr6.2+

TT#32971

SIP registrations

proxy acc

-

21

mr6.2+

TT#32971

Accounting records

proxy auth

-

22

mr6.2+

TT#32971

Subscriber data

proxy dialog

-

23

mr6.2+

TT#34100

Dialog data

lb topos

-

24

mr6.5+

TT#40617

Topos data

proxy b2b

25

-

mr8.0+

TT#64404

B2B in use by each subscriber

proxy 181 HIH

26

-

mr8.5+

TT#89301

HIH stored for 181 messages

lb debug_uri

-

27

mr9.1+

TT#93950

Send SIP messages to inactive node

websocket

-

30

mr7.1+

TT#49703

Internal data

websocket monitors

-

31

mr7.1+

TT#49703

Monitors

websocket subscriptions

-

32

mr7.1+

TT#49703

Subscriptions

proxy push

33

-

mr10.0+

TT#131255

Suspended transactions

Monitoring database metrics

Prometheus monitoring metrics

The Prometheus monitoring database contains time series metrics of several monitoring sources. The following are some of the current metrics namespaces:

ngcp_node_

Cluster node information.

ngcp_tls_certs_

TLS certificate information.

ngcp_monit_

Monit supervised processes information.

ngcp_mail_

MTA information.

ngcp_mysql_

MySQL database information.

ngcp_kamailio_

Kamailio statistics information.

ngcp_peer_

Peering information.

ngcp_sip_

SIP statistics information.

ngcp_cdr_

CDR statistics information.

The ngcp_node namespace consists of the following metrics:

ngcp_node_active

Cluster node HA state (boolean: 1/0).

ngcp_node_ha_proc_state

Cluster node GCS/CRM process state (boolean: stopped/running).

ngcp_node_ha_host_state

Cluster node host state (boolean: up/down).

ngcp_node_ha_node_state

Cluster node HA state (ngcp-check-active -q).

The ngcp_tls_certs namespace consists of the following metrics:

ngcp_tls_certs_expires_on

TLS certificate expiration information; the value is the expiration date as seconds since the epoch, with labels: filename of the certificate or bundle; fingerprint of the certificate, relevant on bundles).

The ngcp_monit namespace consists of the following metrics:

ngcp_monit_proc_info

Information about the process, the value is always 1, with labels: name, pid, ppid, proc_status, monit_status, service_cur_status is the current systemd service status, service_exp_status is the expected systemd service status.

ngcp_monit_proc_children

The number of children.

ngcp_monit_proc_uptime

The process uptime in seconds.

ngcp_monit_proc_cpu_ratio

The CPU usage in for this process.

ngcp_monit_proc_cpu_total_ratio

The CPU usage in for the process group.

ngcp_monit_proc_memory_bytes

The memory in bytes for this process.

ngcp_monit_proc_memory_total_bytes

The memory in bytes for the process group.

ngcp_monit_proc_port_response_seconds

The monitored port response in seconds.

ngcp_monit_proc_sock_response_seconds

The monitored socket response in seconds.

ngcp_monit_proc_data_collected

The timestamp when the data was collected.

The ngcp_mysql namespace consists of the following metrics:

ngcp_mysql_queries_per_second_average

Average of queries per second.

ngcp_mysql_global_status_innodb_buffer_pool_pages_total

Total number of InnoDB buffer pool pages.

ngcp_mysql_global_status_innodb_buffer_pool_pages_free

Number of free InnoDB buffer pool pages.

ngcp_mysql_global_status_innodb_buffer_pool_pages_dirty

Number of dirty InnoDB buffer pool pages.

ngcp_mysql_global_status_commands_total

Total number of commands used.

ngcp_mysql_slave_status_slave_io_running

Whether the IO slave is running.

ngcp_mysql_slave_status_slave_sql_running

Whether the SQL slave is running.

ngcp_mysql_slave_status_seconds_behind_master

Seconds behind master replication.

ngcp_mysql_slave_status_last_io_errno

Last IO error description.

ngcp_mysql_slave_status_last_sql_errno

Last SQL error description.

The ngcp_peer namespace consists of the following metrics:

ngcp_peer_group_info

Peer group information; the value is the group ID, and contains group name, priority and description labels.

ngcp_peer_host_info

Peer host information; the value is the host ID, and contains host name, ip, and group_id labels.

ngcp_peer_host_status

Peer host status, where the value is -1=unknown on standby node, 0=unknown, 1=admin-down, 2=admin-up, 3=pending, 4=down, 5=up; contains the host id label.

ngcp_peer_host_cc_inout

Peer host concurrent call (in/out) counter; contains the host id label.

ngcp_peer_host_cc_out

Peer host concurrent call (in) counter; contains the host id label.

The ngcp_sip namespaces consists of the following metrics:

ngcp_sip_answer_seizure_ratio

Current ASR (Answer Seizure Ratio).

ngcp_sip_concurrent_calls

Number of concurrent calls.

ngcp_sip_dialog_active

Number of calls currently in active dialog stage.

ngcp_sip_dialog_early

Number of calls currently in early media dialog stage.

ngcp_sip_dialog_incoming

Number of calls currently in incoming dialog stage.

ngcp_sip_dialog_local

Number of calls currently in local dialog stage.

ngcp_sip_dialog_outgoing

Number of calls currently in outgoing dialog stage.

ngcp_sip_dialog_relay

Number of calls currently in relay dialog stage.

ngcp_sip_network_efficiency_ratio

Current NER (Network Efficiency Ratio).

ngcp_sip_packets_total

Total number of SIP packets in storage.

ngcp_sip_packets_total_perday

Total number of SIP packets since 00:00 today.

ngcp_sip_partition_bytes

Size of packets partition.

ngcp_sip_provisioned_subscribers

Provisioned subscribers.

ngcp_sip_registered_devices

Registered devices.

ngcp_sip_registered_subscribers

Registered subscribers.

ngcp_sip_responsiveness_seconds

SIP server responsiveness in seconds.

The ngcp_cdr namespaces consists of the following metrics:

ngcp_cdr_total

Total number of generated CDRs.

ngcp_cdr_rated_total

Total number of rated CDRs.

NGCP Preferences

Tables

Currently available tables for preferences are

provisioning.voip_preferences

contains all available preferences, do not contain user data.

provisioning.voip_preference_group

contains preference group names, so the preferences can be put into groups.

provisioning.voip_preferences_enum

contains enum values for preferences, do not contain user data.

The following tables contain user data and depend on voip_preferences and optionally on voip_preferences_enum:

provisioning.voip_dev_preferences

PBX device model preferences

provisioning.voip_devprof_preferences

PBX device profile preferences

provisioning.voip_dom_preferences

domain preferences, replicated by triggers to kamailio.dom_preferences

provisioning.voip_contract_preferences

customer preferences, replicated by triggers to kamailio.contract_preferences

provisioning.voip_peer_preferences

peering server preferences, replicated by triggers to kamailio.peer_preferences

provisioning.voip_prof_preferences

subscriber profile preferences

provisioning.voip_reseller_preferences

reseller preferences

provisioning.voip_usr_preferences

subscriber preferences, replicated by triggers to kamailio.usr_preferences

Columns

Columns for table 'provisioning.voip_preferences'

id

primary key, used in user tables as the foreign key

voip_preference_groups_id

preference group id

attribute

preference name

label

tooltip that can be used as a mouseover tooltip on the UI

type

0 - 'string', 1 - 'integer'/'boolean'

max_occur

how many preferences with the name are allowed 0: list, 1: only one

usr_pref

defines if the preference can be used in subscribers

prof_pref

defines if the preference can be used in subscriber profiles

dom_pref

defines if the preference can be used in domains

peer_pref

defines if the preference can be used in peering servers

contract_pref

defines if the preference can be used in customers

contract_location_pref

defines if the preference can be used in customer locations

dev_pref

defines if the preference can be used in PBX device models

devprof_pref

defines if the preference can be used in PBX device profiles

fielddev_pref

defines if the preference can be used in PBX devices that are assigned to a subscriber

modify_timestamp

preference last modification time

internal

the preference is for internal use only and not shown in the UI/API

expose_to_customer

indicates that the preference can be read/modified by 'subscriberadmin' role

data_type

data type 'enum', 'boolean', 'int', 'string'

read_only

ready only flag

description

long description of the preference

dynamic

set to 1 if it is a custom preference that is created by a user (usually for a PBX device model that requires specific preferences) but can be used for all preferences when needed

reseller_pref

defines if the preference can be used in resellers

expose_to_subscriber

indicates that the preference can be read/modified by 'subscriber' role

Enum

All tables are in database "provisioning".

So called "enum preferences" allow a fixed set of possible values, an enumeration, for preferences. Following the differences between other preferences are described.

Setting the attribute "data_type" of table "voip_preferences" to "enum" marks a preferences as an enum. The list of possible options is stored in table "voip_preferences_enum".

Columns for table 'provisioning.voip_preferences_enum' are:

id

primary key

preference_id

Reference to table voip_preferences.

label

A label to be displayed in frontends.

value

Value that will be written to voip_[usr

dom

peer]preferences.value if it is NOT NULL. Will not be written if it IS NULL. This can be used to implement a "default value" for a preference that is visible in frontends as such (will be listed first if nothing is actually selected), but will not be written to voip[usr

dom

peer]_preferences.value. Usually forcing a domain or peer default. Should also be named unambiguous (e.g. "use domain default"). (Note: Therefore will also not be written to any kamailio table.)

usr_pref

Flag if this is to be used for usr preferences.

dom_pref

Flag if this is to be used for dom preferences.

peer_pref

Flag if this is to be used for peer preferences.

default_val

Flag indicating if this should be used as a default value when creating new entities or introducing new enum preferences (both done via triggers). (Note: For this to work, value must also be set.)

Relevant triggers:

enum_update

Propagates changes of voip_preferences_enum.value to voip_[usr

dom

peer]_preferences.value

enum_set_default

Will create entries for default values when adding a new enum preference. The default value is the tuple from voip_preferences_enum WHERE default_val=1 AND value NOT NULL.

voip_dom_crepl_trig

The trigger will set possible default values (same condition as for enum_set_default) when creating new domains.

voip_phost_crepl_trig

The trigger will set possible default values (same condition as for enum_set_default) when creating new peers.

voip_sub_crepl_trig

The trigger will set possible default values (same condition as for enum_set_default) when creating new subscribers.

Find a usage example in a section in db-schema/db_scripts/diff/9086.up.

Appendix G: Kamailio pv_headers module

This chapter documents the new kamailio "pv_headers" modules introduced in Sipwise C5 starting from version mr7.0.1.

Module overview

This new module enables storing all headers in XAVP to freely modify them in the kamailio logic and only apply them once when it’s time for the packet to be routed outside. The main goal of the module is to offload the intermediate header processing into the XAVP dynamic container as well as provide with high level methods and pseudovariables to simplify SIP message header modifications.

In few words:

  • as soon as a SIP message enters the proxy, kamailio reads all the headers (using the function "pv_collect_headers()") and stores them in an XAVP called "headers".

  • starting from this point all the header changes are directly performed on the "headers" XAVP. For example the From header is available at '$xavp(headers[0]⇒From[0])'.

  • right before the SIP message leaves the proxy, kamailio writes back all the headers changes (using the function "pv_apply_headers()").

RURI and the headers listed in the module parameter "skip_headers" are left untouched and not saved in the XAVP. Therefore they should be handled in the usual way.

Template changes

As described before in the upgrade procedures, the module is enabled by default in kamailio proxy and all the templates have been already updated to use this new logic. Before proceeding with the upgrade, it is essential that the customtt/patchtt files you have in place are updated to this new format.

Here some few examples of what has been changed in the proxy templates:

  • variables $fu, $fU, $fd, $fn, $ft have been substituted by $x_fu, $x_fU, $x_fd, $x_fn, $x_ft

  • variables $tu, $tU, $td, $tn, $tt have been substituted by $x_tu, $x_tU, $x_td, $x_tn, $x_tt

  • variables $rr, $rs have been substituted by $x_rr, $x_rs

  • variables $ua have been substituted by $x_hdr(User-Agent)

  • variables $ai have been substituted by $x_hdr(P-Asserted-Identity)

  • variables $pU, $pd have been substituted by $x_hdr(P-Preferred-Identity)

  • variables $re have been substituted by $x_hdr(Remote-Party-ID)

  • variables $di have been substituted by $x_hdr(Diversion)

  • variables $ct have been substituted by $x_hdr(Contact)

  • $hdr("name") has been substituted by $x_hdr("name")

  • is_present_hf("name") has been sustituted by $x_hdr(name)!= $null

  • remove_hf("name") has been substituted by pv_remove_header("name") function or $(x_hdr(name)[*]) = $null

  • append_hf("name: value\r\n") has been substituted by pv_append_header("name", "value") / pv_modify_header("name", "value") functions or $(x_hdr(name)[*]) = value

  • t_check_status(code) has been substituted by $T_reply_code == code

  • save("location") has been updated in save("location", "0x00", "$x_tu")

  • sd_lookup("speed_dial") has been updated in sd_lookup("speed_dial", $x_fu)

  • added pv_collect_headers() and pv_reset_headers() functions in the dedicated ROUTE_COLLECT_HDR route

  • added pv_apply_headers() function in the dedicated ROUTE_APPLY_HDR route

  • added pv_reset_headers() function in the following routing sections

Module documentation

Parameters

xavp_name (string)

Name of the XAVP there the collected headers are stored.

Default: headers

modparam("pv_headers", "xavp_name", "headers")

Result:
  $xavp(headers[0]=>From)
  $xavp(headers[0]=>To)
  $xavp(headers[0]=>Call-ID)
  ....

skip_headers (string)

A comma separated headers list that must be excluded from processing (they are skipped when pv_apply_headers() changes the sip message headers). If the parameter is not set then the "Default" list is used. If the parameter is set to an empty string then all the sip message headers are processed.

Default: Record-Route,Via,Route,Content-Length,Max-Forwards

split_headers (string)

A comma separated headers list that must be split into multi headers if their value is a comma separated list. If the parameter is not set then the "Default" is used. If the parameter is set to an empty string then no headers are split.

Default: None

modparam("pv_headers", "split_headers", "Diversion")

    Result:
        Received Diversion header:
            Diversion: <user1@test.local>,<user2@test.local>,<user3@test.local>
        After split:
            Diversion: <user1@test.local>
            Diversion: <user2@test.local>
            Diversion: <user3@test.local>
        Becomes handy if used together with pv_modify_header() or pv_remove_header()
        to change or remove value 2 for instance.

Functions

pv_collect_headers()

This function collects all headers from the message into the XAVP. It should be used preferably just when the sip message is reveived by kamailio.

Returns:

  • 1 - on success

  • -1 - if there were errors

pv_apply_headers()

This function applies the current XAVP headers state to the real headers and should be called only once per branch when the message is about to leave kamailio.

The following rules apply:

  • all headers in the XAVP except for ones provided in the "skip_headers" parameter and From/To are recreated in the sip message.

  • From/To headers are processed by the uac module if it is loaded.

  • From/To headers are not changed in the reply messages.

  • headers with NULL value are removed if exist in the sip message.

  • the initial order of the sip headers is preserved.

Usage:

if (pv_apply_headers())
{
    "success"
}
else
{
    "errors"
}

pv_reset_headers()

This function resets the current XAVP headers list and enables pv_collect_headers() and pv_apply_headers() to be called again in the same branch.

Usage:

if (pv_reset_headers())
{
    "success"
}
else
{
    "errors"
}

pv_check_header(hname)

This function checks if the header already exists in the XAVP. It can be freely called from anywhere, but only after pv_collect_headers().

Usage:

if (pv_check_header(hname))
{
    "exists"
}
else
{
    "does not exist"
}

pv_append_header(hname, hvalue)

This function appends a new header into the XAVP. It can be freely called from anywhere, but only after pv_collect_headers(). Please note that subsequent "pv_append_header" calls will result in multiple headers. If the provided "hvalue" is $null then the header is added into the XAVP but it is not going to be added into the message.

Usage:

if (pv_append_header(hname, hvalue))
{
    "appended"
}
else
{
    "errors"
}

pv_modify_header(hname, hvalue)

This function modifies an existing header in the XAVP. It can be freely called from anywhere, but only after pv_collect_headers(). Please note that if the header does not exist it will be explicitly appended. If there are multiple headers with the same name only the first one will be affected. If the provided header value is $null then the header is modified in the XAVP then it is removed from the sip message when pv_apply_headers() is called.

Usage:

if (pv_modify_header(hname, hvalue))
{
    "modified"
}
else
{
    "errors"
}

pv_modify_header(hname, idx, hvalue)

This function works similar to pv_modify_header(hname, hvalue) but should be used when there are multiple headers with the same name one of them to be modified. Index order is top to bottom.

Usage:

if (pv_modify_header(hname, idx, hvalue))
{
    "modified"
}
else
{
    "errors"
}

pv_remove_header(hname)

This function removes an existing header from the XAVP. It can be freely called from anywhere, but only after pv_collect_headers(). If there are multiple headers with the same name all of them are removed. It returns -1 if the header does not exist.

Usage:

if (pv_remove_header(hname, hvalue))
{
    "removed"
}
else
{
    "does not exist or errors"
}

pv_remove_header(hname, idx, hvalue)

This function works similar to pv_remove_header(hname, hvalue) but should be used when there are multiple headers with the same name one of them to be removed. Index order is top to bottom.

Usage:

if (pv_remove_header(hname, idx, hvalue))
{
    "removed"
}
else
{
    "does not exist or errors"
}

Pseudovariables

$x_hdr

This pseudovariable is used to append/modify/remove headers by their name and can be used instead of the pv_append_header(), pv_modify_header(), pv_remove_header() functions.

Usage:

  • append header "X-Header" with value "example". NOTE: It always appends a header, even there is already one with the same name

$x_hdr(X-Header) = "example";

  • modify header "X-Header" with index 0. Returns an error if there is no such index

$(x_hdr(X-Header)[0]) = "example";

  • remove all occurrences of header "X-Header" and append one with value "example"

$(x_hdr(X-Header)[*]) = "example";

  • remove header "X-Header" with index 2 (if there are multiple headers). Returns an error if there is no such index

$(x_hdr(X-Header)[2]) = $null;

  • remove all occurrences of the header. Does not produce an error if there is no such header

$(x_hdr(X-Header)[*]) = $null;

  • retrieve a value of header "X-Header" with index 0, otherwise $null

$var(test) = $x_hdr(X-Header);

  • retrieve a value of header "X-Header" with index 0 otherwise $null

$var(test) = $x_hdr(X-Header)[*]);

  • retrieve a value of header "X-Header" with index 2 otherwise $null

$var(test) = $(x_hdr(X-Header)[2]);

$x_fu, $x_tu

These pseudovariables are used to modify/retrieve the "From" and "To" headers.

Usage:

  • modify the header

$x_fu = "User1 <440001@example.local>";

  • retrieve a value of the header

$var(test) = $x_fu;

  • $x_tu usage is the same

$x_fU, $x_tU

These pseudovariables are used to modify/retrieve the username part of the "From" and "To" headers.

Usage:

  • modify the username part

$x_fU = "440001";

  • retrieve the username part

$var(test) = $x_fU;

  • $x_tU usage is the same

$x_fd, $x_td

These pseudovariables are used to modify/retrieve the domain part of the "From" and "To" headers.

Usage:

  • modify the domain part

$x_fd = "example.local";

  • retrieve the domain part

$var(test) = $x_fd;

  • $x_td usage is the same

$x_fn, $x_tn

These pseudovariables are used to modify/retrieve the display part of the "From" and "To" headers.

Usage:

  • modify the username part

$x_fn = "User1";

  • retrieve the domain part

$var(test) = $x_fn;

  • $x_tn usage is the same

$x_ft, $x_tt

These pseudovariables are used to retrieve the tag part of the "From" and "To" headers.

Usage:

  • retrieve the tag part

$var(test) = $x_ft;

  • $x_tt usage is the same

$x_rs, $x_rr

These pseudovariables are used to modify/retrieve or change "status" and "code" of the SIP reply NOTE: Only messages with reply status > 300 can be changed as well as reply status 1xx and 2xx cannot be set

Usage:

  • modify the reply status

$x_rs = 486

  • retrieve the reply status

$var(test) = $x_rs;

  • modify the reply reason

$x_rr = "Custom Reason"

  • retrieve the reply reason

$var(test) = $x_rr;

Appendix H: Extra Configuration Scenarios

AudioCodes devices workaround

Old AudioCodes devices suffer from a problem where they replace 127.0.0.1 address in Record-Route headers (added by Sipwise C5’s internal components) with the device’s IP address. Supposedly, the whole range of AudioCodes devices with a firmware version below 6.8.X are affected. As a workaround, you may enable the topos feature to stop sending Record-Route headers out. To achieve this, execute the following commands:

ngcpcfg set /etc/ngcp-config/config.yml kamailio.lb.security.topos.enable=yes
ngcpcfg apply 'enable topos for audiocodes devs workaround'

"Debug Proxy" for troubleshooting

This functionality only makes sense on Sipwise C5 CARRIER appliance environment that has an inactive proxy node available.

In order to troubleshoot/debug/capture a scenario, the "debug proxy" allows defining a list of "debug subscribers" that will be matched against From/To headers for every SIP message on a specific lb node. If matched that SIP message will be delivered to the assigned proxy node. In summary, any call to/from that subscriber will be easily traced since no calls are delivered by default to an inactive "debug proxy" node. Also, you can enable extra debug levels on the "debug proxy" node which will NOT affect production traffic on the platform.

The subscribers have to be specified in the same format as they are received on Kamailio LB (before all the rewrite rules applied).
In the following examples both proxy node 'prx99a' and 'prx99b' must be set to inactive nodes 'hosts.prx99a.status=inactive' and 'hosts.prx99b.status=inactive' in network.yml!

To enable the feature for INACTIVE 'prx99' proxy pair, execute:

ngcpcfg set /etc/ngcp-config/network.yml hosts.prx99a.status=inactive # for the safety
ngcpcfg set /etc/ngcp-config/network.yml hosts.prx99b.status=inactive # for the safety
ngcpcfg set /etc/ngcp-config/config.yml kamailio.lb.debug_uri.enable=yes
ngcpcfg apply 'Enable debug proxy on node prx99'
ngcpcfg push-parallel all

And make sure 'prx99' active node has this new config applied.

There’s a command-line tool available to manage the subscriber list. An example of use:

ngcp-debug-subscriber add lb01 +4310001000@example.org sipuser@example.org prx99
ngcp-debug-subscriber delete lb01 +4310001000@example.org
ngcp-debug-subscriber list lb01

Be aware that the list of debug subscribers belongs to just one lb pair, the info is kept in REDIS 'local' database, it is necessary to survive LB restarts and/or HA switchovers. To skip saving in REDIS 'local' database, specifying the option '--no-store' (in this case the information will stay in memory only and will be void on Kamailio LB restart):

ngcp-debug-subscriber add --no-store lb01 +10001042@example.org prx99

See more available options in general and per-action help messages:

ngcp-debug-subscriber --help
ngcp-debug-subscriber add --help
It is recommended to keep the amount of "debug subscribers" as small as possible (for performance reasons).

The "debug subscribers" is kept in a kamailio htable. htable index size value can be changed if necessary in config.yml using the option 'kamailio.lb.debug_uri.htable_idx_size'. This is not the maximum size. From Kamailio htable documentation:

size - number to control how many slots (buckets) to create for the hash table.
A larger value means more slots with a higher probability for fewer collisions.
The actual number of slots (or buckets) created for the table is 2^size.
The possible range for this value is from 2 to 31, smaller or larger values
will be increased to 3 (8 slots) or decreased to 14 (16384 slots).
Note that each slot can store more than one item, when there are collisions of
hash ids computed for keys. The items in the same slot are stored in a linked list.
In other words, the size is not setting a limit of how many items can be
stored in a hash table, as long as there is enough free shared memory,
new items can be added.

The default value 'kamailio.lb.debug_uri.htable_idx_size=4' is enough for all the use cases in production.

Appendix I: NGCP CLI helpers and tools

Main NGCP tools

Sipwise C5 provides a list of various scripts, helpers, and tools to successfully maintain the system from the POSIX console. You can access those scripts using ssh or login into the Unix terminal. All Sipwise C5 scripts start with the prefix 'ngcp-'.

Currently services and daemon executables namespaced too with 'ngcp-' can be found within PATH, but are not intended for general execution, and might eventually be moved out under /usr/libexec/. These are listed in the table "Internal NGCP component" below.

A must-have list to learn for everyday usage:

  • ngcpcfg

  • ngcp-loglevel

  • ngcp-service

  • ngcp-status

Public NGCP tools

Name Description

Configuration tools:

ngcpcfg

main NGCP configuration tool

ngcp-initial-configuration

configure 'bare' node as NGCP (cluster) member

ngcp-network

command line interface to ngcp-config network configuration settings

ngcp-support-access

enable/disable Sipwise Support team access to NGCP

ngcp-toggle-performance-config

switch NGCP performance modes: low/high

Maintenance tools:

ngcp-approx-cache

update cached APT metadata in Approx

ngcp-approx-snapshots

manage (create/delete/export/import) snapshots of Approx

ngcp-customtt-diff-helper

prepare local customtt/patchtt files for Sipwise analyses

ngcp-loglevel

show/set debug level per component in run-time

ngcp-ppa

handle Sipwise PPA APT repositories for NGCP customization

ngcp-prepare-upgrade

prepare NGCP to upgrade to the new release/build

ngcp-reset-db

reset MariaDB database. NOTE: think twice before calling it!

ngcp-update

wrapper for the latest hotfixes installations inside the same release

ngcp-update-cfg-schema

update ngcp-config YML files. Safe to re-execute

ngcp-update-db-schema

upgrade MariaDB. Safe to re-execute

ngcp-upgrade

Sipwise NGCP platform upgrade framework to upgrade on new release/build. Execute with caution!

ngcp-upgrade-pre-checks

check possible issues/misconfigurations before the upgrade

Operational tools:

ngcp-active-calls

show/drop active calls matching search criteria

ngcp-cdr-md5

validate the integrity of exported CDR files

ngcp-check-active

show HA node status (active/standby)

ngcp-check-redis-dialogs

script to check stalled Kamailio dialogs in Redis DB

ngcp-disk-usage

disk usage statistic tool (symlink to ncdu)

ngcp-kamcmd

Kamailio console debug tool

ngcp-kamctl

Kamailio command-line interface

ngcp-location-cleanup

Delete expired location entries from Redis

ngcp-log-flow

create a call flow of a single Call-ID taking NGCP logs as input

ngcp-logs

search a string in NGCP logs. Useful to retrieve Kamailio and SEMS logs given a call-id

ngcp-make-active

make HA node active (revoke standby HA state from the peer)

ngcp-make-standby

make HA node standby (revoke active HA state from the peer)

ngcp-memory-usage

report processes with the biggest RAM/SWAP usage

ngcp-mysql-compare-dbs

fast compare MariaDB schemas between two hosts

ngcp-redis-helper

easier various data requests from Redis DB

ngcp-service

manage NGCP system services. See 'man ngcp-service' for more details

ngcp-status

show general overall NGCP status. It is a wrapper for many NGCP tools

ngcp-support-upload

upload files to the ticket on support.sipwise.com

ngcp-system-tests

main self-check tool. Safe to execute in production

ngcp-usr-location

show the correct VoIP registrations (from Redis DB). See 'ngcp-usr-location --help'

REST API tools:

ngcp-api-admins

manage NGCP Administrators

ngcp-api-delete

send arbitrary DELETE request to NGCP REST API

ngcp-api-get

send arbitrary GET request to NGCP REST API

ngcp-api-patch

send arbitrary PATCH request to NGCP REST API

ngcp-api-ping

fast check for NGCP REST API availability

ngcp-api-post

send arbitrary POST request to NGCP REST API

ngcp-api-put

send arbitrary PUT request to NGCP REST API

ngcp-create-customer

create NGCP Customer

ngcp-create-domain

create NGCP Domain

ngcp-create-subscriber

create NGCP Subscriber

ngcp-delete-domain

delete an NGCP Domain. Execute with caution (subscribers are deleted with a domain)!

ngcp-get-customer

get customer info by the customer ID

ngcp-terminate-customer

terminate an NGCP Customer

ngcp-terminate-subscriber

terminate an NGCP Subscriber

Deprecated tools (will be removed soon):

ngcp-delete-subscriber

backward compatibility symlink to ngcp-terminate-subscriber

ngcp-delete-voip-account

backward compatibility symlink to ngcp-terminate-customer

ngcp-get-voip-account

backward compatibility symlink to ngcp-get-customer

ngcp-voicemail-table-cleanup

backward compatibility symlink to ngcp-cleanup-voicemail-table

Internal NGCP tools

they can be used, but they might be changed without the notification.
Name Description

ngcp-bcrypt-webpassword

migration encrypt subscribers' WEB passwords using bcrypt

ngcp-check-rev-applied

check which DB/config revisions have been executed

ngcp-check-sip-option

monitoring tool that sends an OPTIONS request to a SIP server

ngcp-chroot-shell

a suid root program that will take care of securely opening a shell inside a jail

ngcp-create-testusers

developers generate a batch of customers/subscribers

ngcp-dlgcnt-check

check Kamailio dialogs counters in Redis DB

ngcp-dlgcnt-clean

remove Kamailio dialogs from Redis DB

ngcp-dlglist-clean

remove Kamailio queue dialogs from Redis DB

ngcp-ha-host-state

keep HA peers in sync (used by ngcp-config)

ngcp-ha-proc-state

keep HA peers in sync (used by ngcp-config)

ngcp-ha-crm

print current CRM in use

ngcp-io-scheduler

systemd helper to set proper IO scheduler on the system boot (HDD related only)

ngcp-kamailio-shm-usage

developers generate Kamailio shared memory usage report

ngcp-location-migrate

temporary migrate from Kamailio locations from MariaDB to Redis DB

ngcp-location-sync

temporary sync Kamailio locations after migration from MariaDB to Redis

ngcp-memdbg-csv

developers generate Kamailio modules memory usage

ngcp-network-validator

dynamically validates the network.yml file (used by ngcp-config)

ngcp-nodename

print the current NGCP HA node name

ngcp-panel-create-keys

generate encryption keys for ngcp-panel

ngcp-peerprobe-status

internal NGCP monitoring tool

ngcp-prepare-translations

developers tool for NGCP localization files. Available on 'trunk' systems only

ngcp-screen-check

check if the current session is running inside a screen/tmux

ngcp-ssh

NGCP wrapper for SSH. Used inside various NGCP scripts to access neighbors in the cluster

ngcp-sync-constants

backwards compatibility symlink for ngcp-sync-db-creds

ngcp-sync-db-creds

sync MariaDB credentials with /etc/ngcp-config/constants.yml (used by ngcp-config)

ngcp-sync-db-grants

sync MariaDB grants with /etc/mysql/grants.yml (used by ngcp-config)

ngcp-sync-grants

backwards compatibility symlink for ngcp-sync-db-grants

ngcp-type

reports back NGCP type: spce/sppro/carrier

ngcp-upgrade-redis-usrloc

move Kamailio locations from MariaDB to Redis in mr7.5

ngcp-virt-identify

check hardware/virtual installation type. See 'man ngcp-virt-identify' for more details

Internal NGCP component

do NOT execute them directly. Use ngcp-service to start/stop service.
Name Description

ngcp-backup

main executable binary file for backup component

ngcp-cdr-exporter

main executable binary file for CDR exporter component

ngcp-cleanup-acc

script responsible for cleaning up accounting database is by cron

ngcp-cleanup-cdr-files

script responsible for cleaning up exported CDR files by cron

ngcp-cleanup-sems

script cleans up SEMS calling card tokens in Redis by cron

ngcp-cleanup-voicemail-table

script cleans up voicemail records on a monthly basis by cron

ngcp-credit-warning

main executable binary file for check for contract balances above credit warning thresholds

ngcp-emergency-mode

main executable binary file for emergency mode component

ngcp-event-exporter

main executable binary file for events exporter component

ngcp-fraud-notifier

sends fraud notifications for customers that exceed the threshold

ngcp-installer

main executable binary file for installer component

ngcp-int-cdr-exporter

main executable binary file for intermediate CDRs exporter component

ngcp-licensed

main executable binary file for licensed component

ngcp-mediator

main executable binary file for mediator component

ngcp-provisioning-template

create subscribers with detailed settings according to provisioning templates

ngcp-rate-o-mat

main executable binary file for rate-o-mat component

ngcp-reminder

main executable binary file for reminder component

ngcp-rtpengine-iptables-setup

systemd related helper for rtpengine

ngcp-rtpengine-recording-nfs-setup

systemd related helper for rtpengine-recording

ngcp-sems

main executable binary file for B2BUA component

ngcp-vmnotify

an Asterisk VoiceMail compatible MWI notification script

ngcp-vmsmsnotify

same as ngcp-vmnotify, but for SMS notifications

ngcp-witnessd

main executable binary file for witnessd component

Appendix J: Generation of 181 Call Is Being Forwarded

[[181_call_is_being_forwarded]]

Overview

SIP message '181 - Call Is Being Forwarded' is an optional provisional response that can be sent towards the caller user to inform it of an ongoing call forward. The message can also contain History-Info headers necessary to the caller to identify which is the new destination of the call.

How to enable it

By default Sipwise C5 doesn’t generate any 181 message. To enable this feature two steps are required:

  • set config.yml option 'kamailio.proxy.cf_send_181.enable' to 'yes'

  • set config.yml option 'b2b.sbc.reset_tag_on_fork' to 'yes'

The first preference will actually activate the 181 message generation. The second one, instead, allows SEMS to forward back to caller all the provisional messages even if they contain a different To-Tag. Without this second preference set, the 181 message is sent towards the caller but all the following 18x messages are blocked by SEMS.

Additionally to add the History-Info headers to the 181 message:

  • the option 'outbound_history_info' has to be set in subscriber/domain preferences

How it works

When a call forward is triggered in Sipwise C5, Kamailio Proxy stores in the Redis database, which is selected by 'kamailio.proxy.cf_send_181.redis_db' preference in config.yml, the History-Info headers that are added to the outgoing INVITE message. Kamailio LB receives the outgoing INVITE and it generates a '182 - Connecting' message back towards the caller. The 182 message is received by Kamailio Proxy that converts it in a '181 - Call Is Being Forwarded' message and adds the History-Info headers previously stored in the Redis DB, if any. The message is then sent back to the caller.

Appendix K: Handling WebRTC Clients

WebRTC is an open project providing browsers and mobile applications with Real-Time Communications (RTC) capabilities. Configuring your platform to offer WebRTC is quite easy and straightforward. This allows you to have a SIP-WebRTC bridge in place and make audio/video call towards normal SIP users from WebRTC clients and vice versa. Sipwise C5 listens, by default, on the following WebSockets and WebSocket Secure: ws://your-ip:5060/ws, wss://your-ip:5061/ws and wss://your-ip:1443/wss/sip/.

The WebRTC subscriber is a normal subscriber which has just a different configuration in his Preferences. You need to change the following preferences under Subscribers→Details→Preferences→NAT and Media Flow Control:

  • use_rtpproxy: Always with rtpproxy as additional ICE candidate

  • transport_protocol: RTP/SAVPF (encrypted SRTP with RTCP feedback)

The transport_protocol setting may change, depending on your WebRTC client/browser configuration. Supported protocols are the following:

  • Transparent (Pass through using the client’s transport protocol)

  • RTP/AVP (Plain RTP)

  • RTP/SAVP (encrypted SRTP)

  • RTP/AVPF (RTP with RTCP feedback)

  • RTP/SAVPF (encrypted SRTP with RTCP feedback)

  • UDP/TLS/RTP/SAVP (Encrypted SRTP using DTLS)

  • UDP/TLS/RTP/SAVPF (Encrypted SRTP using DTLS with RTCP feedback)

The below configuration is enough to handle a WebRTC client/browser. As mentioned, you may need to tune a little bit your transport_protocol configuration, depending on your client/browser settings.

In order to have a bridge between normal SIP clients (using plain RTP for example) and WebRTC client, the normal SIP clients' preferences have to have the following configuration:

transport_protocol: RTP/AVP (Plain RTP)

This will teach Sipwise C5 to translate between Plain RTP and RTP/SAVPF when you have calls between normal SIP clients and WebRTC clients.

Appendix L: Batch Provisioning Extras

Built-in Template

NGCP comes with a built-in template with basic settings. It is shown by default when creating a new template via Admin Panel, which can be edited for advanced configurations. It is also possible to define a list of templates in the /etc/ngcp-config/config.yml file.

By default, the built-in template will set the subscriber’s SIP URI as [CC][AC][SN]@[DOMAIN], where [DOMAIN] is defined within the template as a static value (in the subscriber.domain attribute). An alpha-numeric string will be generated automatically for the SIP password. Additionally, the contract_contact.reseller and contract.billing_profile attributes (among others) may need to be adjusted to particular provisioning needs.

Below, are detailed:

  1. The built-in template available in Admin Panel.

  2. Configurations for the built-in template in config.yml file.

for both JavaScript and Perl languages, respectively.

(a.1) Built-in Admin Panel Template (JavaScript):

fields:
  - name: first_name
    label: "First Name:"
    type: Text
    required: 1
  - name: last_name
    label: "Last Name:"
    type: Text
    required: 1
  - name: cc
    label: "Country Code:"
    type: Text
    required: 1
  - name: ac
    label: "Area Code:"
    type: Text
    required: 1
  - name: sn
    label: "Subscriber Number:"
    type: Text
    required: 1
  - name: sip_username
    type: calculated
    value_code: "function() { return row.cc.concat(row.ac).concat(row.sn); }"
  - name: purge
    label: "Terminate subscriber, if exists:"
    type: Boolean
contract_contact:
  identifier: "firstname, lastname, status"
  reseller: default
  firstname_code: "function() { return row.first_name; }"
  lastname_code: "function() { return row.last_name; }"
  status: "active"
contract:
  product: "Basic SIP Account"
  billing_profile: "Default Billing Profile"
  identifier: contact_id
  contact_id_code: "function() { return contract_contact.id; }"
subscriber:
  domain: "example.org"
  primary_number:
    cc_code: "function() { return row.cc; }"
    ac_code: "function() { return row.ac; }"
    sn_code: "function() { return row.sn; }"
    username_code: "function() { return row.sip_username; }"
    password_code: "function() { return row.sip_password; }"
subscriber_preferences:
  gpp0: "test"

(a.2) Built-in Admin Panel Template (Perl):

fields:
  - name: first_name
    label: "First Name:"
    type: Text
    required: 1
  - name: last_name
    label: "Last Name:"
    type: Text
    required: 1
  - name: cc
    label: "Country Code:"
    type: Text
    required: 1
  - name: ac
    label: "Area Code:"
    type: Text
    required: 1
  - name: sn
    label: "Subscriber Number:"
    type: Text
    required: 1
  - name: sip_username
    type: calculated
    value_code: "sub { return $row{cc}.$row{ac}.$row{sn}; }"
  - name: purge
    label: "Terminate subscriber, if exists:"
    type: Boolean
contract_contact:
  identifier: "firstname, lastname, status"
  reseller: default
  firstname: "sub { return $row{first_name}; }"
  lastname: "sub { return $row{last_name}; }"
  status: "active"
contract:
  product: "Basic SIP Account"
  billing_profile: "Default Billing Profile"
  identifier: contact_id
  contact_id_code: "sub { return $contract_contact{id}; }"
subscriber:
  domain: "example.org"
  primary_number:
    cc_code: "sub { return $row{cc}; }"
    ac_code: "sub { return $row{ac}; }"
    sn_code: "sub { return $row{sn}; }"
    username_code: "sub { return $row{sip_username}; }"
    password_code: "sub { return $row{sip_password}; }"
subscriber_preferences:
  gpp0: "test"

(b.1) Config.yml Template Configuration (JavaScript):

A template can be defined at system level by using the www_admin.provisioning_templates property in the config.yml file. This template will also be displayed on Admin Panel.

www_admin:
  batch_provisioning_features: 1
  provisioning_templates:
    "My First Provisioning Template":
      description: "Create a contract including contact with firstname and lastname for a single subscriber."
      lang: js
      fields:
        - name: first_name
          label: "First Name:"
          type: Text
          required: 1
        - name: last_name
          label: "Last Name:"
          type: Text
          required: 1
        - name: cc
          label: "Country Code:"
          type: Text
          required: 1
        - name: ac
          label: "Area Code:"
          type: Text
          required: 1
        - name: sn
          label: "Subscriber Number:"
          type: Text
          required: 1
        - name: sip_username
          type: calculated
          value_code: "function() { return row.cc.concat(row.ac).concat(row.sn); }"
        - name: purge
          label: "Terminate subscriber, if exists:"
          type: Boolean
      contract_contact:
        identifier: "firstname, lastname, status"
        reseller: default
        firstname_code: "function() { return row.first_name; }"
        lastname_code: "function() { return row.last_name; }"
        status: "active"
      contract:
        product: "Basic SIP Account"
        billing_profile: "Default Billing Profile"
        identifier: contact_id
        contact_id_code: "function() { return contract_contact.id; }"
      subscriber:
        domain: "example.org"
        primary_number:
          cc_code: "function() { return row.cc; }"
          ac_code: "function() { return row.ac; }"
          sn_code: "function() { return row.sn; }"
        username_code: "function() { return row.sip_username; }"
        password_code: "function() { return row.sip_password; }"
      subscriber_preferences:
        gpp0: "test"

(b.2) Config.yml Template Configuration (Perl):

A template can be defined at system level by using the www_admin.provisioning_templates property in the config.yml file. This template will also be displayed on Admin Panel.

www_admin:
  batch_provisioning_features: 1
  provisioning_templates:
    "My First Provisioning Template":
      description: "Create a contract including contact with firstname and lastname for a single subscriber."
      fields:
        - name: first_name
          label: "First Name:"
          type: Text
          required: 1
        - name: last_name
          label: "Last Name:"
          type: Text
          required: 1
        - name: cc
          label: "Country Code:"
          type: Text
          required: 1
        - name: ac
          label: "Area Code:"
          type: Text
          required: 1
        - name: sn
          label: "Subscriber Number:"
          type: Text
          required: 1
        - name: sip_username
          type: calculated
          value_code: "sub { return $row{cc}.$row{ac}.$row{sn}; }"
        - name: purge
          label: "Terminate subscriber, if exists:"
          type: Boolean
      contract_contact:
        identifier: "firstname, lastname, status"
        reseller: default
        firstname: "sub { return $row{first_name}; }"
        lastname: "sub { return $row{last_name}; }"
        status: "active"
      contract:
        product: "Basic SIP Account"
        billing_profile: "Default Billing Profile"
        identifier: contact_id
        contact_id_code: "sub { return $contract_contact{id}; }"
      subscriber:
        domain: "example.org"
        primary_number:
          cc_code: "sub { return $row{cc}; }"
          ac_code: "sub { return $row{ac}; }"
          sn_code: "sub { return $row{sn}; }"
        username_code: "sub { return $row{sip_username}; }"
        password_code: "sub { return $row{sip_password}; }"
      subscriber_preferences:
        gpp0: "test"

Call Forwards Template Example

The following example considers the definition of call forward mappings inside the template. Let us assume that subscribers will be set with the following configuration:

Table 4. Call Forward Mappings Example.

Type

Answer Timeout

Timeset

Sources

To (B-Numbers)

New Destinations

Enabled

Call Forward Busy

always

all sources

any number

123456

Yes

Call Forward Timeout

15s

always

all sources

any number

654321

Yes

Call Forward Unavailable

always

all sources

any number

VoiceMail

Yes

Then, the following cf_mappings section can be appended to the batch provisioning template:

cf_mappings:
  cfu: []
  cfb:
    - enabled: 1
      destinationset:
        name: "Phone2"
        destinations:
          - destination: "123456"
            priority: 1
            timeout: 300
  cft:
    - enabled: 1
      destinationset:
        name: "Phone3"
        destinations:
          - destination: "654321"
            priority: 1
            timeout: 300
  cft_ringtimeout: 15
  cfna:
    - enabled: 1
      destinationset:
        name: "VoiceMail"
        destinations:
          - destination: "voicebox"
            priority: 1
            timeout: 300
  cfs: []
  cfr: []
  cfo: []