Next

The sip:carrier Handbook mr6.0.1

Table of Contents

1. Introduction
1.1. About this Handbook
1.2. What is the sip:carrier?
1.3. The Advantages of the sip:carrier
1.4. Who is the sip:carrier for?
1.5. Getting Help
1.5.1. Phone Support
1.5.2. Ticket System
2. System Architecture
2.1. Hardware Architecture
2.2. Component Architecture
2.2.1. Provisioning
2.2.2. Signaling and Media Relay
2.2.3. Scaling beyond one Hardware Chassis
2.2.4. Architecture for central core and local satellites
3. VoIP Service Configuration Scenario
3.1. Creating a SIP Domain
3.2. Creating a Customer
3.3. Creating a Subscriber
3.4. Domain Preferences
3.5. Subscriber Preferences
3.6. Creating Peerings
3.6.1. Creating Peering Groups
3.6.2. Creating Peering Servers
3.6.3. Authenticating and Registering against Peering Servers
3.7. Configuring Rewrite Rule Sets
3.7.1. Inbound Rewrite Rules for Caller
3.7.2. Inbound Rewrite Rules for Callee
3.7.3. Outbound Rewrite Rules for Caller
3.7.4. Outbound Rewrite Rules for Callee
3.7.5. Emergency Number Handling
3.7.6. Assigning Rewrite Rule Sets to Domains and Subscribers
3.7.7. Creating Dialplans for Peering Servers
3.7.8. Call Routing Verification
4. Features
4.1. Managing System Administrators
4.1.1. Configuring Administrators
4.1.2. Access Rights of Administrators
4.2. Access Control for SIP Calls
4.2.1. Block Lists
4.2.2. NCOS Levels
4.2.3. IP Address Restriction
4.3. Call Forwarding and Call Hunting
4.3.1. Setting a simple Call Forward
4.3.2. Advanced Call Hunting
4.4. Local Number Porting
4.4.1. Local LNP Database
4.4.2. External LNP via LNP API
4.5. Emergency Mapping
4.5.1. Emergency Mapping Description
4.5.2. Emergency Mapping Configuration
4.6. Header Manipulation
4.6.1. Header Filtering
4.6.2. Codec Filtering
4.6.3. Enable History and Diversion Headers
4.7. SIP Trunking with SIPconnect
4.7.1. User provisioning
4.7.2. Inbound calls routing
4.7.3. Number manipulations
4.7.4. Registration
4.8. Trusted Subscribers
4.9. Peer Probing
4.9.1. Introduction to Peer Probing Feature
4.9.2. Configuration of Peer Probing
4.9.3. Monitoring of Peer Probing
4.9.4. Further Details for Advanced Users
4.10. Fax Server
4.10.1. Fax2Mail Architecture
4.10.2. Sendfax and Mail2Fax Architecture
4.11. Voicemail System
4.11.1. Accessing the IVR Menu
4.11.2. IVR Menu Structure
4.11.3. Type Of Messages
4.11.4. Folders
4.11.5. Voicemail Languages Configuration
4.11.6. Flowcharts with Voice Prompts
4.12. Configuring Subscriber IVR Language
4.13. Sound Sets
4.13.1. Configuring Early Reject Sound Sets
4.14. Conference System
4.14.1. Configuring Call Forward to Conference
4.14.2. Configuring Conference Sound Sets
4.14.3. Joining the Conference
4.14.4. Conference Flowchart with Voice Prompts
4.15. Malicious Call Identification (MCID)
4.15.1. Setup
4.15.2. Usage
4.15.3. Advanced configuration
4.16. Subscriber Profiles
4.16.1. Subscriber Profile Sets
4.17. SIP Loop Detection
4.18. Call-Through Application
4.18.1. Administrative Configuration
4.18.2. Call Flow
4.19. Calling Card Application
4.19.1. Administrative Configuration
4.19.2. Call Flow
4.20. Invoices and Invoice Templates
4.20.1. Invoices Management
4.20.2. Invoice Management via REST API
4.20.3. Invoice Templates
4.20.4. Invoices Generation
4.21. Email Reports and Notifications
4.21.1. Email events
4.21.2. Initial template values and template variables
4.21.3. Password reset email template
4.21.4. New subscriber notification email template
4.21.5. Invoice email template
4.21.6. Email templates management
4.22. The Vertical Service Code Interface
4.22.1. Vertical Service Codes for PBX customers
4.22.2. Configuration of Vertical Service Codes
4.22.3. Voice Prompts for Vertical Service Code Configuration
4.23. Handling WebRTC Clients
4.24. XMPP and Instant Messaging
4.25. Call Recording
4.25.1. Introduction to Call Recording Function
4.25.2. Information on Files and Directories
4.25.3. Configuration
4.25.4. REST API
4.26. SMS (Short Message Service) on Sipwise NGCP
4.26.1. Configuration
4.26.2. Monitoring, troubleshooting
4.26.3. REST API
5. Customer Self-Care Interface and Menus
5.1. The Customer Self-Care Web Interface
5.1.1. Login Procedure
5.1.2. Site Customization
5.2. The Voicemail Menu
6. Billing Configuration
6.1. Billing Profiles
6.1.1. Creating Billing Profiles
6.1.2. Creating Billing Fees
6.1.3. Creating Off-Peak Times
6.2. Peak Time Call Rating Modes
6.2.1. Introduction to Call Rating Modes
6.2.2. Typical Use Cases for Call Rating Modes
6.2.3. Configuration of Call Rating Modes
6.3. Prepaid Accounting
6.4. Fraud Detection and Locking
6.4.1. Fraud Lock Levels
6.5. Billing Customizations
6.5.1. Billing Networks
6.5.2. Profile Mapping Schedule
6.5.3. Profile Packages
6.5.4. Vouchers
6.5.5. Top-up
6.5.6. Balance Overviews
6.5.7. Usage Examples
6.6. Billing Data Export
6.6.1. Glossary of Terms
6.6.2. File Name Format
6.6.3. File Format
6.6.4. File Transfer
7. Provisioning REST API Interface
7.1. API Workflows for Customer and Subscriber Management
7.2. API performance considerations
8. Configuration Framework
8.1. Configuration templates
8.1.1. .tt2 and .customtt.tt2 files
8.1.2. .prebuild and .postbuild files
8.1.3. .services files
8.2. config.yml, constants.yml and network.yml files
8.3. ngcpcfg and its command line options
8.3.1. apply
8.3.2. build
8.3.3. commit
8.3.4. decrypt
8.3.5. diff
8.3.6. encrypt
8.3.7. help
8.3.8. initialise
8.3.9. pull
8.3.10. push
8.3.11. services
8.3.12. status
9. Network Configuration
9.1. General Structure
9.1.1. Available Host Options
9.1.2. Interface Parameters
9.2. Advanced Network Configuration
9.2.1. Extra SIP Sockets
9.2.2. Extra SIP and RTP Sockets
9.2.3. Cluster Sets
10. Licenses
10.1. What is Subject to Licensing?
10.2. How Licensing Works
10.3. How to Configure Licenses
10.4. How to Monitor License Client
11. Software Upgrade
11.1. Release Notes
11.2. Overview
11.3. Planning a software upgrade
11.4. Preparing the software upgrade
11.4.1. Log into the standby management server (web01a/db01a).
11.4.2. Log into the remaining servers
11.5. Upgrading the sip:carrier
11.5.1. Preparing for maintenance mode
11.5.2. Upgrading ONLY the first standby management node "A" (web01a/db01a)
11.5.3. Upgrading the standby database node "A" (db*a)
11.5.4. Upgrading other standby nodes "A" (lb*a/prx*a)
11.5.5. Promote ALL standby nodes "A" to active.
11.5.6. Upgrading ALL standby nodes "B" (web*b/db*b/lb*b/prx*b)
11.6. Post-upgrade steps
11.6.1. Disabling maintenance mode
11.6.2. Post-upgrade checks
11.7. Applying the Latest Hotfixes
11.7.1. Apply hotfixes on the standby management node
11.7.2. Apply hotfixes on all other standby nodes
11.7.3. Promote the standby nodes to active
11.7.4. Apply hotfixes on new standby nodes
12. Backup, Recovery and Database Maintenance
12.1. sip:carrier Backup
12.1.1. What data to back up
12.1.2. The built-in backup solution
12.2. Recovery
12.3. Reset Database
12.4. Accounting Data (CDR) Cleanup
12.4.1. Cleanuptools Configuration
12.4.2. Accounting Database Cleanup
12.4.3. Exported CDR Cleanup
13. Platform Security, Performance and Troubleshooting
13.1. Sipwise SSH access to sip:carrier
13.2. Firewalling
13.2.1. Firewall framework
13.2.2. NGCP firewall configuration
13.2.3. IPv4 System rules
13.2.4. Custom rules
13.2.5. Example firewall configuration section
13.3. Password management
13.3.1. The "root" account
13.3.2. The "administrator" account
13.3.3. The "cdrexport" account
13.3.4. The MySQL "root" user
13.3.5. The "ngcpsoap" account
13.4. SSL certificates.
13.5. Securing your sip:carrier against SIP attacks
13.5.1. Denial of Service
13.5.2. Bruteforcing SIP credentials
13.6. Topology Hiding
13.6.1. Introduction to Topology Hiding on NGCP
13.6.2. Configuration of Topology Hiding
13.6.3. Considerations for Topology Hiding
13.7. System Requirements and Performance
13.8. Troubleshooting
13.8.1. Collecting call information from logs
13.8.2. Collecting SIP traces
14. Monitoring and Alerting
14.1. Internal Monitoring
14.1.1. Process monitoring via monit
14.1.2. System monitoring via Telegraf
14.1.3. NGCP-specific monitoring via ngcp-witnessd
14.1.4. Monitoring data in InfluxDB
14.2. Statistics Dashboard
14.3. External Monitoring Using SNMP
14.3.1. Overview and Initial Setup
14.3.2. Details
15. Extensions and Additional Modules
15.1. Cloud PBX
15.1.1. Configuring the Device Management
15.1.2. Preparing PBX Rewrite Rules
15.1.3. Creating Customers and Pilot Subscribers
15.1.4. Creating Regular PBX Subscribers
15.1.5. Assigning Subscribers to Devices
15.1.6. Configuring Sound Sets for the Customer PBX
15.1.7. Auto-Attendant Function
15.1.8. Configuring Call Queues
15.1.9. Device Auto-Provisioning Security
15.1.10. Device Bootstrap and Resync Workflows
15.1.11. Device Provisioning and Deployment Workflows
15.1.12. List of available pre-configured devices
15.1.13. Phone features
15.1.14. Shared line appearance
15.2. Sipwise sip:phone App (SIP client)
15.2.1. Zero Config Launcher
15.2.2. Mobile Push Notification
15.3. Lawful Interception
15.3.1. Introduction
15.3.2. Architecture and Configuration of LI Service
15.3.3. X1, X2 and X3 Interface Specification
15.4. 3rd Party Call Control
15.4.1. Introduction
15.4.2. Details of Call Processing with PCC
15.4.3. Voicemail Notification
15.4.4. Incoming Short Message Acceptance
15.4.5. Configuration of PCC
15.4.6. Troubleshooting of PCC
A. Basic Call Flows
1. General Call Setup
2. Endpoint Registration
3. Basic Call
4. Session Keep-Alive
5. Voicebox Calls
B. NGCP configs overview
1. config.yml Overview
1.1. apps
1.2. asterisk
1.3. autoprov
1.4. backuptools
1.5. bootenv
1.6. cdrexport
1.7. checktools
1.8. cleanuptools
1.9. cluster_sets
1.10. database
1.11. faxserver
1.12. general
1.13. haproxy
1.14. heartbeat
1.15. intercept
1.16. kamailio
1.17. lnpd
1.18. mediator
1.19. modules
1.20. nginx
1.21. ntp
1.22. ossbss
1.23. pbx (only with additional cloud PBX module installed)
1.24. prosody
1.25. pushd
1.26. qos
1.27. rate-o-mat
1.28. redis
1.29. reminder
1.30. rsyslog
1.31. rtpproxy
1.32. security
1.33. sems
1.34. sms
1.35. snmpagent
1.36. sshd
1.37. sudo
1.38. voisniff
1.39. www_admin
2. constants.yml Overview
3. network.yml Overview
C. NGCP-Faxserver Configuration
1. Faxserver Components
2. Enabling Faxserver
3. Fax Templates Configuration
4. Fax Services Configuration per Subscriber
5. Fax2Mail and SendFax Settings
6. Mail2Fax Settings
7. Sending Fax from Web Panel
8. Faxserver Mail2Fax Configuration
9. Sending Fax Using E-mail Clients
10. Managing Faxes via the REST API
10.1. Configuring Fax Settings
10.1.1. Retrieving Fax Settings
10.1.2. Updating Fax Settings
10.2. Sending a Fax
10.3. Receiving a Fax
10.4. Configuring Mail2Fax Settings
10.4.1. Retrieving Mail2Fax Configuration
10.4.2. Updating Mail2Fax Configuration
10.5. Using Advanced Faxserver and Mail2Fax Settings via the REST API
11. Troubleshooting
11.1. Session ID (SID)
11.2. Fax Storage Location
D. RTC:engine
1. Overview
2. RTC:engine enabling
2.1. Enabling services via CLI
2.2. Enabling via Panel for resellers and subscribers
2.3. Create RTC:engine session
2.3.1. Create sessions
2.3.2. Receive sessions
3. RTC:engine protocol details
3.1. Terminology
3.1.1. Connector
3.1.2. Router
3.1.3. User
3.1.4. App
3.1.5. Network
3.1.6. Session
3.1.7. Account
3.1.8. Browser SDK
3.2. Messages
3.2.1. Fields
3.2.2. method
3.2.3. from
3.2.4. to
3.2.5. session
3.2.6. body
3.3. Account
3.3.1. Flow
3.3.2. Messages
3.3.3. account.connect
3.3.4. account.state
3.3.5. State reasons
3.3.6. States
3.4. Call
3.4.1. Flow
3.4.2. call.start
3.4.3. Body properties
3.4.4. id
3.4.5. gcid
3.4.6. account
3.4.7. replace
3.4.8. trickle
3.4.9. target
3.4.10. sdp
3.4.11. call.alive
3.4.12. call.ringing
3.4.13. call.accept
3.4.14. call.ack.accept
3.4.15. call.candidate
3.4.16. call.fullsdp
3.4.17. call.change….
3.4.18. call.change.lock.reset
3.4.19. call.change.lock
3.4.20. call.change.lock.ok
3.4.21. call.change.offer
3.4.22. call.change.answer
3.4.23. call.dtmf
3.4.24. call.end
3.4.25. call.ack.end
3.5. Session
3.5.1. Flow
3.5.2. Messages
3.5.3. session.open
3.5.4. session.validated
3.5.5. Reason types
E. comx-fileshare-service
1. Overview
2. Configuration and Usage
2.1. Change authentication method
2.2. Database Structure
3. Activation of Filesharing Service on NGCP
4. Message Sequence Chart
4.1. Simple Message Sequence
4.2. Detailed Message Sequence
5. API of Filesharing Service
5.1. HTTP Authentication
5.2. Upload and Download with Simple Identification
5.3. Upload and Download with Session Identification
5.4. Curl Example for Simple Upload Request
5.5. Upload Parameters
5.5.1. file
5.5.2. user
5.5.3. TTL
5.6. Number of Possible Downloads
F. NGCP Internals
1. Pending reboot marker
2. Redis id constants
2.1. InfluxDB monitoring keys
3. Enum preferences

1. Introduction

1.1. About this Handbook
1.2. What is the sip:carrier?
1.3. The Advantages of the sip:carrier
1.4. Who is the sip:carrier for?
1.5. Getting Help
1.5.1. Phone Support
1.5.2. Ticket System

1.1. About this Handbook

This handbook describes the architecture and the operational steps to install, operate and modify the Sipwise sip:carrier.

In various chapters, it describes the system architecture, the installation and upgrade procedures and the initial configuration steps to get your first users online. It then dives into advanced preference configurations such as rewrite rules, call blockings, call forwards, etc.

There is a description of the customer self-care interface, how to configure the billing system and how to provision the system via the provided APIs.

Finally, it describes the internal configuration framework, the network configuration and gives hints about tweaking the system for security and performance.

1.2. What is the sip:carrier?

The sip:carrier is a SIP based Open Source Class5 VoIP soft-switch platform providing rich telephony services. It offers a wide range of features to end users (call forwards, voicemail, conferencing, call blocking, click-to-dial, call-lists showing near-realtime accounting information, etc.), which can be configured by them using the customer-self-care web interface. For operators, it offers a fully web-based administrative panel, allowing them to configure users, peerings, billing profiles, etc., as well as viewing real-time statistics of the system. For tight integration into existing infrastructures, it provides a powerful REST API.

The sip:carrier comes pre-installed on six+ servers in one+ IBM Flex Chassis, see Section 2, “System Architecture”. Apart from your product specific configuration, there is no initial configuration or installation to be done to get started.

1.3. The Advantages of the sip:carrier

Opposed to other free VoIP software, the sip:carrier is not a single application, but a whole software platform, the Sipwise NGCP (Sipwise Next Generation Communication Platform), which is based on Debian GNU/Linux.

Using a highly modular design approach, the NGCP leverages popular open-source software like MySQL, NGINX, Kamailio, SEMS, Asterisk, etc. as its core building blocks. These blocks are glued together using optimized and proven configurations and workflows and are complemented by functionality developed by Sipwise to provide fully-featured and easy to operate VoIP services.

The installed applications are managed by the NGCP Configuration Framework, which makes it possible to change system parameters in a single place, so administrators don’t need to have any knowledge of the dozens of different configuration files of the different packages. This provides a very easy and bullet-proof way of operating, changing and tweaking the otherwise quite complex system.

Once configured, integrated web interfaces are provided for both end users and administrators to use the sip:carrier. By using the provided provisioning and billing APIs, it can be integrated tightly into existing OSS/BSS infrastructures to optimize workflows.

1.4. Who is the sip:carrier for?

The sip:carrier is specifically tailored to companies who want to provide fully-featured SIP-based VoIP service without having to go through the steep learning curve of SIP signalling, integrating the different building blocks to make them work together in a reasonable way. The sip:carrier is already deployed all around the world by all kinds of VoIP operators, using it as Class5 soft-switch, as Class4 termination platform or even as Session Border Controller with all kinds of access networks, like Cable, DSL, WiFi and Mobile networks.

1.5. Getting Help

1.5.1. Phone Support

Depending on your support contract, you are eligible to contact our Support Team by phone either in business hours or around the clock. Business hours refer to the UTC+1 time zone (Europe/Vienna). Please check your support contract to find out the type of support you’ve purchased.

Before calling our Support Team, please also open a ticket in our Ticket System and provide as much detail as you can for us to understand the problems, fix them and investigate the cause. Please provide the number of your newly created ticket when asked by our support personnel on the phone.

You can find phone numbers, Ticket System URL, and account information in your support contract. Please make this information available to the persons in your company maintaining the sip:carrier.

1.5.2. Ticket System

Depending on your support contract, you can create either a limited or an unlimited amount of support tickets on our Web-based Ticket System. Please provide as much information as possible when opening a ticket, especially the following:

  • WHAT is affected (e.g. the whole system is unreachable, or customers can’t register or place calls)
  • WHO is affected (e.g. all customers, only parts of it, and WHICH parts - only customers in a particular domain or customers with specific devices, etc.)
  • WHEN did the problem occur (time frames, or after the firmware of specific devices types have been updated, etc.)

Our Support Team will ask further questions via the Ticket System along the way of troubleshooting your issue. Please provide the information as soon as possible to solve your issue promptly.

  Next