├── .gitignore ├── README.md ├── antora.yml └── modules └── ROOT ├── assets └── images │ ├── AdvancedSearchQueryExample.png │ ├── CallDetailsWidget.png │ ├── CallDetailsWidgetHeader.png │ ├── CallDetailsWidgetInfo.png │ ├── CallDetailsWidgetLegs.png │ ├── CallDetailsWidgetMessages.png │ ├── CallDetailsWidgetTitle.png │ ├── CallFlowMediaEventsSitcking.png │ ├── CallFlowMediaMessage.png │ ├── CallFlowSequenceDiagram.png │ ├── CallFlowSidebarButtonHighlighted.png │ ├── CallFlowSidebarDisplaySettingsControl.png │ ├── CallFlowSidebarOpened.png │ ├── CallFlowSidebarTimeSettingsControl.png │ ├── CallFlowSipEventsHighlighting.png │ ├── CallFlowSipMessage.png │ ├── CallSetupStatisticByTrunk.png │ ├── CallSetupTroubleshootingByTrunk.png │ ├── Components.png │ ├── CustomMetricsDashboardDatadog.png │ ├── CustomSearchLayout.png │ ├── DashboardForCallAttemptsBlockedByApiban.png │ ├── ExportToDropdown.png │ ├── HostAddIcon.png │ ├── HostEditIcon.png │ ├── HostMap.png │ ├── InstallationGuideBasicInstallationDiagram.jpg │ ├── MediaQoSMetricsDashboardDatadog.png │ ├── MediaQoSMetricsDashboardGrafana.png │ ├── MediaQualityWidget.png │ ├── PowerOffIcon.png │ ├── SIPQoSMetricsDashboardDatadog.png │ ├── SIPQoSMetricsDashboardGrafana.png │ ├── SearchAttributeWithFiniteAmountOfPossibleValues.png │ ├── SearchAttributeWithInfiniteAmountOfPossibleValues.png │ ├── SearchForCallAttemptsBlockedByApiban.png │ ├── SearchHistory.png │ ├── SettingsIcon.png │ ├── ShowIpListBlockedByApiban.png │ ├── SidebarExample.png │ ├── TopProfilesByThreeSecondsCallsRate.png │ ├── TopProfilesByTotalCalls.png │ ├── TrashBinIcon.png │ └── WangiriFraudDetectionSolutionArchitecture.png ├── attachments └── SIP3_CommCon2021.pdf ├── nav.adoc └── pages ├── CommunityEditionVsEnterpriseEdition.adoc ├── GettingStartedGuide.adoc ├── InstallationGuide.adoc ├── ReleaseNotes.adoc ├── UpgradeGuide.adoc ├── features ├── AccessControl.adoc ├── AdvancedSearch.adoc ├── CallDetails.adoc ├── CallFlowDiagram.adoc ├── Components.adoc ├── HoofConfiguration.adoc ├── HostMap.adoc ├── MediaRecordingOnDemand.adoc ├── ServiceMetrics.adoc └── UserDefinedFunctions.adoc └── tutorials ├── HowToBuildSip3BasedSolutions.adoc └── HowToInroduceUserDefinedAttribute.adoc /.gitignore: -------------------------------------------------------------------------------- 1 | .idea 2 | *.iml 3 | *.ipr 4 | 5 | *.class 6 | target -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # SIP3 Documentation # 2 | 3 | **SIP3 Documentation** is a documentation as a code project structured and built with [Antora](https://antora.org/). 4 | 5 | ## 1. Documentation 6 | 7 | The entire SIP3 Documentation including `Installation Guide`, `Features`, `Tutorials` and `Realease Notes` can be found [here](https://sip3.io/docs/InstallationGuide.html). 8 | 9 | ## 2. Support 10 | 11 | If you have a question about SIP3, just leave us a message in our community [Slack](https://join.slack.com/t/sip3-community/shared_invite/enQtOTIyMjg3NDI0MjU3LWUwYzhlOTFhODYxMTEwNjllYjZjNzc1M2NmM2EyNDM0ZjJmNTVkOTg1MGQ3YmFmNWU5NjlhOGI3MWU1MzUwMjE) and [Telegram](https://t.me/sip3io), or send us an [email](mailto:support@sip3.io). We will be happy to help you. 12 | -------------------------------------------------------------------------------- /antora.yml: -------------------------------------------------------------------------------- 1 | name: docs 2 | title: SIP3 Documentation 3 | version: master 4 | start_page: ROOT:InstallationGuide.adoc 5 | nav: 6 | - modules/ROOT/nav.adoc -------------------------------------------------------------------------------- /modules/ROOT/assets/images/AdvancedSearchQueryExample.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/AdvancedSearchQueryExample.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallDetailsWidget.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallDetailsWidget.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallDetailsWidgetHeader.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallDetailsWidgetHeader.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallDetailsWidgetInfo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallDetailsWidgetInfo.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallDetailsWidgetLegs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallDetailsWidgetLegs.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallDetailsWidgetMessages.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallDetailsWidgetMessages.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallDetailsWidgetTitle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallDetailsWidgetTitle.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallFlowMediaEventsSitcking.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallFlowMediaEventsSitcking.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallFlowMediaMessage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallFlowMediaMessage.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallFlowSequenceDiagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallFlowSequenceDiagram.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallFlowSidebarButtonHighlighted.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallFlowSidebarButtonHighlighted.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallFlowSidebarDisplaySettingsControl.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallFlowSidebarDisplaySettingsControl.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallFlowSidebarOpened.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallFlowSidebarOpened.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallFlowSidebarTimeSettingsControl.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallFlowSidebarTimeSettingsControl.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallFlowSipEventsHighlighting.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallFlowSipEventsHighlighting.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallFlowSipMessage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallFlowSipMessage.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallSetupStatisticByTrunk.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallSetupStatisticByTrunk.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CallSetupTroubleshootingByTrunk.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CallSetupTroubleshootingByTrunk.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/Components.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/Components.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CustomMetricsDashboardDatadog.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CustomMetricsDashboardDatadog.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/CustomSearchLayout.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/CustomSearchLayout.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/DashboardForCallAttemptsBlockedByApiban.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/DashboardForCallAttemptsBlockedByApiban.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/ExportToDropdown.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/ExportToDropdown.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/HostAddIcon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/HostAddIcon.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/HostEditIcon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/HostEditIcon.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/HostMap.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/HostMap.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/InstallationGuideBasicInstallationDiagram.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/InstallationGuideBasicInstallationDiagram.jpg -------------------------------------------------------------------------------- /modules/ROOT/assets/images/MediaQoSMetricsDashboardDatadog.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/MediaQoSMetricsDashboardDatadog.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/MediaQoSMetricsDashboardGrafana.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/MediaQoSMetricsDashboardGrafana.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/MediaQualityWidget.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/MediaQualityWidget.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/PowerOffIcon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/PowerOffIcon.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/SIPQoSMetricsDashboardDatadog.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/SIPQoSMetricsDashboardDatadog.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/SIPQoSMetricsDashboardGrafana.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/SIPQoSMetricsDashboardGrafana.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/SearchAttributeWithFiniteAmountOfPossibleValues.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/SearchAttributeWithFiniteAmountOfPossibleValues.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/SearchAttributeWithInfiniteAmountOfPossibleValues.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/SearchAttributeWithInfiniteAmountOfPossibleValues.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/SearchForCallAttemptsBlockedByApiban.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/SearchForCallAttemptsBlockedByApiban.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/SearchHistory.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/SearchHistory.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/SettingsIcon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/SettingsIcon.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/ShowIpListBlockedByApiban.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/ShowIpListBlockedByApiban.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/SidebarExample.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/SidebarExample.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/TopProfilesByThreeSecondsCallsRate.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/TopProfilesByThreeSecondsCallsRate.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/TopProfilesByTotalCalls.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/TopProfilesByTotalCalls.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/TrashBinIcon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/TrashBinIcon.png -------------------------------------------------------------------------------- /modules/ROOT/assets/images/WangiriFraudDetectionSolutionArchitecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/assets/images/WangiriFraudDetectionSolutionArchitecture.png -------------------------------------------------------------------------------- /modules/ROOT/attachments/SIP3_CommCon2021.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sip3io/sip3-documentation/0af732c67a5d654f4b7d3a62b813a4ae465198cc/modules/ROOT/attachments/SIP3_CommCon2021.pdf -------------------------------------------------------------------------------- /modules/ROOT/nav.adoc: -------------------------------------------------------------------------------- 1 | * xref:InstallationGuide.adoc[Installation Guide] 2 | * xref:UpgradeGuide.adoc[Upgrade Guide] 3 | * Features 4 | ** xref:features/AdvancedSearch.adoc[Advanced Search] 5 | ** xref:features/CallDetails.adoc[Call Details] 6 | ** xref:features/CallFlowDiagram.adoc[Call Flow Diagram] 7 | ** xref:features/ServiceMetrics.adoc[Service Metrics] 8 | ** xref:features/MediaRecordingOnDemand.adoc[Media Recording On Demand] 9 | ** xref:features/UserDefinedFunctions.adoc[User-Defined Functions] 10 | ** xref:features/HostMap.adoc[Host Map] 11 | ** xref:features/Components.adoc[Components] 12 | ** xref:features/HoofConfiguration.adoc[Hoof Configuration] 13 | ** xref:features/AccessControl.adoc[Access Control] 14 | * Tutorials 15 | ** xref:tutorials/HowToInroduceUserDefinedAttribute.adoc[How To Introduce a User-Defined Attribute or Integration with APIBAN Example] 16 | ** xref:tutorials/HowToBuildSip3BasedSolutions.adoc[How To Build SIP3 Based Solutions or Wangiri Fraud Detection Example] 17 | * Media 18 | ** link:{attachmentsdir}/SIP3_CommCon2021.pdf[CommCon2021 Slides - SIP3 Usage Guide and Features Overview] 19 | ** https://www.youtube.com/watch?v=__CvehK71vg[CommCon2021 Video - SIP3 Usage Guide and Features Overview] 20 | * xref:CommunityEditionVsEnterpriseEdition.adoc[CE vs EE] 21 | * xref:ReleaseNotes.adoc[Release Notes] 22 | -------------------------------------------------------------------------------- /modules/ROOT/pages/CommunityEditionVsEnterpriseEdition.adoc: -------------------------------------------------------------------------------- 1 | = Community Edition vs Enterprise Edition 2 | :description: SIP3 Community Edition vs Enterprise Edition 3 | 4 | == Overview 5 | 6 | Every SIP3 release comes with Community and Enterprise versions. In this document we put together most of the differences between these two. 7 | 8 | == Comparison 9 | 10 | [cols="66,~,~"] 11 | |=== 12 | ||CE |EE 13 | 14 | 3+^| *1. Data Sources* 15 | 16 | | SIP3 Captain real-time capture agent 17 | | Yes 18 | | 19 | 20 | | SIP3 Captain high-load optimized capture agent 21 | | 22 | | Yes 23 | 24 | | DPDK support 25 | | 26 | | Yes 27 | 28 | | HEP support 29 | | Yes 30 | | Yes 31 | 32 | | SPAN/RSPAN/ERSPAN/IP-in-IP support 33 | | Yes 34 | | Yes 35 | 36 | 3+^| *2. Transport Protocols* 37 | 38 | | UDP 39 | | Yes 40 | | Yes 41 | 42 | | TCP 43 | | Yes 44 | | Yes 45 | 46 | | SCTP 47 | | 48 | | Yes 49 | 50 | 3+^| *3. Data Processing* 51 | 52 | | SIP analysis 53 | | Yes 54 | | Yes 55 | 56 | | SIP-I (ISUP encapsulation) analysis 57 | | 58 | | Yes 59 | 60 | | RTCP analysis 61 | | Yes 62 | | Yes 63 | 64 | | RTP/SRTP analysis 65 | | 66 | | Yes 67 | 68 | | DTMF analysis 69 | | 70 | | Yes 71 | 72 | 73 | | Custom events analysis (i.e. Push Notifications) 74 | | 75 | | Yes 76 | 77 | | RTP recording 78 | | Yes 79 | | 80 | 81 | | RTP recording on demand 82 | | 83 | | Yes 84 | 85 | | RTP recording in GDPR-compliant mode 86 | | 87 | | Yes 88 | 89 | 3+^| *4. Service Metrics* 90 | 91 | | Elasticsearch 92 | | Yes 93 | | Yes 94 | 95 | | InfluxDB 96 | | Yes 97 | | Yes 98 | 99 | | Prometheus 100 | | 101 | | Yes 102 | 103 | | Datadog 104 | | Yes 105 | | 106 | 107 | | Datadog cost optimized 108 | | 109 | | Yes 110 | 111 | 3+^| *5. Customizations and Integrations* 112 | 113 | | xref:features/UserDefinedFunctions.adoc[User-Defined Functions (UDFs)] 114 | | Yes 115 | | Yes 116 | 117 | 3+^| *6. Management* 118 | 119 | | Component management 120 | | 121 | | Yes 122 | 123 | | Centralized configuration 124 | | 125 | | Yes 126 | 127 | | Call stash 128 | | 129 | | Yes 130 | 131 | 3+^| *7. Authorization* 132 | 133 | | Grafana authorization 134 | | Yes 135 | | Yes 136 | 137 | | LDAP authorization 138 | | 139 | | Yes 140 | 141 | | OAuth and OIDC authorization (Google, Okta, etc) 142 | | 143 | | Yes 144 | 145 | 3+^| *8. Deployment* 146 | 147 | | xref:InstallationGuide.adoc[Ansible automation] 148 | | Yes 149 | | Yes 150 | 151 | | High-availability cluster 152 | | 153 | | Yes 154 | 155 | 3+^| *9. Services* 156 | 157 | | Cloud and on-premise deployment 158 | | 159 | | Yes 160 | 161 | | Integrations and customizations 162 | | 163 | | Yes 164 | 165 | | Community support 166 | | Yes 167 | | Yes 168 | 169 | | SLA support 170 | | 171 | | Yes 172 | 173 | | Audit and consultament (fraud detection, traffic profiling, etc) 174 | | 175 | | Yes 176 | |=== 177 | 178 | == Contacts 179 | 180 | If you have additional questions please contact us though https://join.slack.com/t/sip3-community/shared_invite/enQtOTIyMjg3NDI0MjU3LWUwYzhlOTFhODYxMTEwNjllYjZjNzc1M2NmM2EyNDM0ZjJmNTVkOTg1MGQ3YmFmNWU5NjlhOGI3MWU1MzUwMjE[Slack] or https://t.me/sip3io[Telegram] for the community support and though mailto:contact@sip3.io[email] for the enterprise support. We will be happy to help you. 181 | -------------------------------------------------------------------------------- /modules/ROOT/pages/GettingStartedGuide.adoc: -------------------------------------------------------------------------------- 1 | = Getting Started 2 | :description: SIP3 Getting Started Guide 3 | 4 | This document will be updated soon... 5 | -------------------------------------------------------------------------------- /modules/ROOT/pages/InstallationGuide.adoc: -------------------------------------------------------------------------------- 1 | = Installation Guide 2 | :description: SIP3 Installation Guide 3 | 4 | == Overview 5 | 6 | WARNING: This document is `work in progress`. 7 | For instance, at the moment `sip3-ansible` has no support for `all.hosts.backend` property. 8 | Still, you can use this document to get an idea of how to deploy the product using `sip3-ansible`. 9 | In case of any problems we recommend you to compare configuration with the https://github.com/sip3io/sip3-ansible/blob/master/inventories/inventory.yml[default invetory file] or ask us a question in the SIP3 community channels. 10 | 11 | SIP3 leverages a traditional microservice architecture that makes it easy to scale, in the cloud and on-premise. 12 | 13 | Having each one of the SIP3 components deployed independently saves you money, time and resources, but it also brings a layer of extra complexity to the deployment process. 14 | To make your life easier the SIP3 team introduced the https://github.com/sip3io/sip3-ansible[`sip3-ansible`] Github project. 15 | 16 | NOTE: At the moment you can use `sip3-ansible` to deploy each of the SIP3 components as a service to CentOS, Debian or as a docker container to any Linux OS. 17 | Please, contact mailto:support@sip3.io[the SIP3 team] if you need help with specific environment. 18 | 19 | By following the traditional Ansible approach, you will be creating an inventory file that describes the SIP3 installation process. 20 | By doing so, you will be able to quickly deploy your project to any infrastructure, regardless of the size and amount of its traffic. 21 | 22 | NOTE: The `sip3-ansible` project requires Ansible version 2.10 or higher. 23 | 24 | == Basic Installation 25 | 26 | In the following section we will deploy SIP3 to a simple VoIP network, consisting of one PBX server, as shown on the diagram below. 27 | In the beginning SIP3 Captain will be installed as an agent to the same server. 28 | Afterwards, all the SIP3 backend components will be installed to another server as a monolithic application. 29 | 30 | image::InstallationGuideBasicInstallationDiagram.jpg[Installation Guide Basic Installation Diagram] 31 | 32 | === Installing SIP3 Captain To Single PBX 33 | 34 | Clone `sip3-ansible` repository and checkout the latest release branch: 35 | 36 | [source,ssh] 37 | ---- 38 | git clone https://github.com/sip3io/sip3-ansible.git 39 | git checkout -b release/2025.1.1 40 | ---- 41 | 42 | Create a `sip3-captain.yml` file inside the `inventories` directory: 43 | 44 | [source,yaml] 45 | ---- 46 | all: 47 | hosts: 48 | captain: 49 | ansible_host: 23.08.20.15 // <1> 50 | vars: 51 | ansible_user: root 52 | ansible_port: 22 53 | ansible_become: true 54 | 55 | edition: ce // <2> 56 | 57 | features: // <3> 58 | - rtcp 59 | 60 | captain: 61 | pcap: // <4> 62 | dev: eth0 63 | bpf_filter: udp 64 | sender: // <5> 65 | uri: udp://192.168.1.2:15060 66 | management: // <6> 67 | uri: udp://192.168.1.2:15090 68 | metrics: 69 | logging: 70 | step: 5000 71 | ---- 72 | 73 | Let's take a closer look at the inventory file: 74 | 75 | <1> SSH address. 76 | Ansible uses it to connect to the PBX via SSH. 77 | 78 | <2> Component edition. 79 | 80 | <3> Features help to customize SIP3 behaviour and enable/disable certain functionality. 81 | They also help to separate CE and EE configuration. 82 | You can find more information in the corresponding section of this document. 83 | 84 | <4> Standard `libpcap` settings. 85 | Specify on which interface you want to capture VoIP traffic and set https://biot.com/capstats/bpf.html[BPF filter] to avoid capturing all the packets (e.g. If you want to capture only SIP protocol on port 5060 use `udp and port 5060` as a filter). 86 | 87 | <5> SIP3 Salto data interface. 88 | SIP3 Captain uses this interface to send application data. 89 | 90 | <6> Management interface. 91 | Must be defined if `rtp` or `rtcp` features enabled. 92 | SIP3 Salto and Captain use this interface to exchange SDP information. 93 | 94 | Our minimalistic SIP3 Captain configuration is ready. 95 | Now, let's install SIP3 Captain to the PBX using the command below: 96 | 97 | ``` 98 | ansible-playbook -i inventories/sip3-captain.yml playbooks/sip3.yml 99 | ``` 100 | 101 | Once Ansible successfully finished with the playbook we can check that SIP3 Captain is actually working. 102 | At the first check bootstrap information from `/var/log/sip3-captain/default.log` if you deployed SIP3 Captain without Docker or `~/sip3/var/log/sip3-captain/default.log` in other case: 103 | 104 | ``` 105 | 05-10-2020 11:36:34.758 [vert.x-eventloop-thread-0] INFO i.s.captain.ce.capturing.PcapEngine - Listening network interface: eth0 106 | 05-10-2020 11:36:34.885 [vert.x-eventloop-thread-1] INFO io.sip3.captain.ce.sender.Sender - UDP connection opened: udp://192.168.1.2:15060 107 | ``` 108 | 109 | Now let's check `/var/log/sip3-captain/metrics.log` and `~/sip3/var/log/sip3-captain/metrics.log` accordingly to get some insights on the amount of traffic captured by SIP3 Captain and to make sure that the traffic goes to the SIP3 Salto: 110 | 111 | ``` 112 | 05-10-2020 12:27:09.298 - packets_captured{name=sip3-captain,source=pcap} throughput=2.4/s 113 | 05-10-2020 12:27:09.299 - packets_sent{name=sip3-captain} throughput=1.2/s 114 | ``` 115 | 116 | Congratulations, SIP3 Captain is up and capturing traffic. 117 | So, we can move to the next section of the document. 118 | 119 | === Installing SIP3 Captain To Multiple PBXs 120 | 121 | In the previous section we configured SIP3 Captain for single PBX. However, in real life we usually have multiple VoIP nodes. 122 | 123 | Let's add another PBX to our previous example and define a group of hosts called `captain` as it's shown in the example below: 124 | 125 | [source,yaml] 126 | ---- 127 | all: 128 | children: 129 | captain: 130 | hosts: 131 | pbx1: 132 | ansible_host: 23.08.20.15 133 | pbx2: 134 | ansible_host: 29.11.19.88 135 | captain: // <1> 136 | pcap: 137 | dev: eth1 138 | vars: 139 | ansible_user: root 140 | ansible_port: 22 141 | ansible_become: true 142 | 143 | edition: ce 144 | 145 | features: 146 | - rtcp 147 | 148 | captain: 149 | pcap: 150 | dev: eth0 151 | bpf_filter: udp 152 | sender: 153 | uri: udp://192.168.1.2:15060 154 | management: 155 | uri: udp://192.168.1.2:15090 156 | metrics: 157 | logging: 158 | step: 5000 159 | ---- 160 | 161 | <1> Each SIP3 Captain instance can be configured separately by re-assigning global variables withing the host section. 162 | Re-assigned variables will be merged with the global one accordingly to https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable[Ansible precedence convention]. 163 | 164 | Now we can use the same command from the previous section to install both SIP3 Captains: 165 | 166 | ``` 167 | ansible-playbook -i inventories/sip3-captain.yml playbooks/sip3.yml 168 | ``` 169 | 170 | As you can see installing multiple SIP3 Captains as easy as installing one. 171 | 172 | === Uninstalling SIP3 Captain 173 | 174 | To uninstall SIP3 Captain use the command bellow. 175 | Please, take a look at additional `extra-vars` parameter: 176 | 177 | ``` 178 | ansible-playbook -i inventories/sip3-captain.yml playbooks/sip3.yml --extra-vars "state=absent" 179 | ``` 180 | 181 | === Installing SIP3 Backend Components 182 | 183 | Let's create a `sip3-backend.yml` file inside the `inventories` directory in analogy with what we've done in the <>: 184 | 185 | [source,yaml] 186 | ---- 187 | all: 188 | hosts: 189 | backend: 190 | ansible_host: 26.03.19.23 // <1> 191 | 192 | vars: 193 | ansible_user: root 194 | ansible_port: 22 195 | ansible_become: true 196 | 197 | edition: ce // <2> 198 | 199 | features: // <3> 200 | - call 201 | - register 202 | - rtcp 203 | 204 | mongodb: // <4> 205 | path: /var/lib/mongodb 206 | db: sip3 207 | influxdb: // <5> 208 | path: /var/lib/influxdb 209 | db: sip3 210 | grafana: // <6> 211 | datasources: 212 | database: sip3 213 | salto: 214 | server: // <7> 215 | uri: udp://0.0.0.0:15060 216 | management: 217 | uri: udp://0.0.0.0:15090 // <8> 218 | ---- 219 | 220 | Let's take a closer look at the inventory file: 221 | 222 | <1> SSH address. 223 | Ansible uses it to connect to the SIP3 backend via SSH. 224 | 225 | <2> Component edition. 226 | 227 | <3> Features help to customize SIP3 behaviour and enable/disable certain functionality. 228 | They also help to separate CE and EE configuration. 229 | You can find more information in the corresponding section of this document. 230 | 231 | <4> MongoDB section where you can put a specific path and name of the database. 232 | 233 | <5> InfluxDB section where you can put a specific version, path and name of the database. 234 | 235 | <6> Grafana section where you can configure `sip3` datasource. 236 | 237 | <7> SIP3 Salto data interface. 238 | SIP3 Captain uses this interface to send application data. 239 | 240 | <8> Management interface. 241 | Must be defined if `rtp` or `rtcp` features enabled. 242 | SIP3 Salto and Captain use this interface to exchange SDP information. 243 | 244 | As you can see our default configuration file is pretty small and simple. 245 | However, there are lots of additional properties we will explore in further sections of this document. 246 | Now let's install SIP3 backend components by running the same simple command: 247 | 248 | ``` 249 | ansible-playbook -i inventories/sip3-backend.yml playbooks/sip3.yml 250 | ``` 251 | 252 | This document will be updated soon... -------------------------------------------------------------------------------- /modules/ROOT/pages/ReleaseNotes.adoc: -------------------------------------------------------------------------------- 1 | = Release Notes 2 | :description: SIP3 Release Notes 3 | 4 | == Version: 2025.1.1 5 | 6 | === Captain 7 | 8 | * Various performance improvements and bugfixes 9 | 10 | === Salto 11 | 12 | * Various performance improvements and bugfixes 13 | 14 | === Twig 15 | 16 | * Advanced error processing for calls with invalid data 17 | * Various performance improvements and bugfixes 18 | 19 | === Hoof 20 | 21 | * Export to JSON for calls to share data with SIP3 support 22 | * User Interface to work with stored configurations 23 | * Handle render errors for calls 24 | * Various performance improvements and bugfixes 25 | 26 | == Version: 2024.3.1 27 | 28 | === Captain 29 | 30 | * Various performance improvements and bugfixes 31 | 32 | === Salto 33 | 34 | * Improve stability of Management Socket 35 | * Various performance improvements and bugfixes 36 | 37 | === Twig 38 | 39 | * Multiply values for user-defined columns 40 | * Extend Component's configuration 41 | * Various performance improvements and bugfixes 42 | 43 | === Hoof 44 | 45 | * Multiply values in Custom Search Results for user-defined columns 46 | * Fixed alignments for some UI components 47 | * Various performance improvements and bugfixes 48 | 49 | == Version: 2024.2.2 50 | 51 | === Captain 52 | 53 | * Remote configuration improvements 54 | * Various performance improvements and bugfixes 55 | 56 | === Salto 57 | 58 | * Remote configuration improvements 59 | * Various performance improvements and bugfixes 60 | 61 | === Twig 62 | 63 | * Remote configuration improvements 64 | * Various performance improvements and bugfixes 65 | 66 | === Hoof 67 | 68 | * Added Recording Tasks management from UI 69 | * Added component version to Component list 70 | * Various performance improvements and bugfixes 71 | 72 | == Version: 2024.2.1 73 | 74 | === Captain 75 | 76 | * Added TCP protocol for Management 77 | * Added WebSocket protocol for Management and data sending(EE) 78 | * Added response handling for SIP3 Component Register messages 79 | * Various performance improvements and bugfixes 80 | 81 | === Salto 82 | 83 | * Added TCP protocol for Management 84 | * Added WebSocket protocol for Management and data sending(EE) 85 | * Support different protocols for Server and Management in same time 86 | * Various performance improvements and bugfixes 87 | 88 | === Twig 89 | 90 | * Update Salto multi-protocol configuration 91 | * Various performance improvements and bugfixes 92 | 93 | === Hoof 94 | 95 | * Various performance improvements and bugfixes 96 | 97 | == Version: 2024.1.3 98 | 99 | === Captain 100 | 101 | * Extend New Relic metrics configuration 102 | * Added response for Register message in Management Socket 103 | * Various performance improvements and bugfixes 104 | 105 | === Salto 106 | 107 | * Extend New Relic metrics configuration 108 | * Added response for Register message in Management Socket 109 | * Remove configuration improvements 110 | * Various performance improvements and bugfixes 111 | 112 | === Twig 113 | 114 | * Extend Role-based authorization model in EE version 115 | * Various performance improvements and bugfixes 116 | 117 | === Hoof 118 | 119 | * Role-based authorization model for EE version 120 | * Various performance improvements and bugfixes 121 | 122 | == Version: 2024.1.2 123 | 124 | === Captain 125 | 126 | * Fixed SIP over TCP capturing 127 | * Added WebSocket support in EE version 128 | * Added IPFIX support in EE version 129 | * Added HEP3 Server in EE version 130 | * Various performance improvements and bugfixes 131 | 132 | === Salto 133 | 134 | * Various performance improvements and bugfixes 135 | 136 | === Twig 137 | 138 | * Various performance improvements and bugfixes 139 | * Update dependencies with security issues 140 | 141 | === Hoof 142 | 143 | * Various performance improvements and bugfixes 144 | 145 | For upgrade procedure, please read xref:UpgradeGuide.adoc[Upgrade Guide] 146 | 147 | == Version: 2024.1.1 148 | 149 | === Captain 150 | * Added new SIP3 Packet Type - RAW 151 | * Added custom exit code for remote shutdown 152 | * Sender network optimizations 153 | * Improved SIP3 component communications via TCP 154 | * Various performance improvements and bugfixes 155 | 156 | === Salto 157 | 158 | * Added new SIP3 Packet Type - RAW 159 | * Added unknown(unparsed) SIP Message processing 160 | * Fixed RTP stream duration calculations 161 | * Improved SIP3 component communications via TCP 162 | * Various performance improvements and bugfixes 163 | * Update dependencies with security issues 164 | 165 | === Twig 166 | 167 | * Added unknown(unparsed) SIP Message processing 168 | * Added custom exit code for remote shutdown 169 | * Various performance improvements and bugfixes 170 | * Update dependencies with security issues 171 | 172 | === Hoof 173 | 174 | * Fixed routing issues 175 | * Fixed scrolling issue in Winbox 176 | * Added refresh button for Components 177 | * Added unknown(unparsed) SIP Message processing 178 | * Various performance improvements and bugfixes 179 | 180 | _For upgrade procedure, please read xref:UpgradeGuide.adoc[Upgrade Guide]_ 181 | 182 | == Version: 2023.2.1 183 | 184 | === Captain 185 | 186 | * Java 17 is required as a minimum version 187 | * Various performance improvements and bugfixes 188 | * Update dependencies with security issues 189 | 190 | === Salto 191 | 192 | * Java 17 is required as a minimum version 193 | * Support MongoDB up to version 7.0 194 | * Various performance improvements and bugfixes 195 | * Update dependencies with security issues 196 | 197 | === Twig 198 | 199 | * Java 17 is required as a minimum version 200 | * Added Salto components in the SIP3 Hoof Configuration 201 | * Full compatible authorization with OAuth2.0 for EE 202 | * Upgrade to Spring Boot 3 version 203 | * Support MongoDB up to version 7.0 204 | * Various performance improvements and bugfixes 205 | * Update dependencies with security issues 206 | 207 | === Hoof 208 | 209 | * Added support for Custom Search Layouts 210 | * Full compatible authorization with OAuth2.0 for EE 211 | * Various performance improvements and bugfixes 212 | 213 | _For upgrade procedure, please read xref:UpgradeGuide.adoc[Upgrade Guide]_ 214 | 215 | == Version: 2023.1.2 216 | 217 | === Captain 218 | 219 | * Fixed backward compatibility with SIP3 Salto 2022.2.x version 220 | * Various performance improvements and bugfixes 221 | 222 | === Salto 223 | 224 | * Fixed backward compatibility with SIP3 Captain 2022.2.x version 225 | * Various performance improvements and bugfixes 226 | 227 | === Twig 228 | 229 | * Extended SIP3 Hoof Configuration 230 | * Various performance improvements and bugfixes 231 | 232 | === Hoof 233 | 234 | * User Session prolongation if webpage is open 235 | * Configurable Winbox behaviour on layout switching 236 | * Configurable Sidebar links: Dashboards, Searches and External links 237 | * Various performance improvements and bugfixes 238 | 239 | == Version: 2023.1.1 240 | 241 | === Captain 242 | 243 | * Migrate from `kebab-case` to `snake_case` property naming strategy 244 | * Added https://newrelic.com/[New Relic] metrics support 245 | * Added filter by port ranges for `RTP` and `RTCP` 246 | * Removed offline capturing from `pcap` 247 | * Centralized remote configuration via SIP3 Management Socket 248 | * Kotlin version upgrade 249 | * Various performance improvements and bugfixes 250 | 251 | === Salto 252 | 253 | * Migrate from `kebab-case` to `snake_case` property naming strategy 254 | * Added https://newrelic.com/[New Relic] metrics support 255 | * Extended control over connected SIP3 Components 256 | * Kotlin version upgrade 257 | * Various performance improvements and bugfixes 258 | 259 | === Twig 260 | 261 | * Components API with extended control 262 | * Replace SpringFox with Springdoc 263 | * Centralized remote configuration 264 | * Kotlin version upgrade 265 | * Various performance improvements and bugfixes 266 | 267 | === Hoof 268 | 269 | * Added SIP3 Components status page 270 | * Added Host Map page with CRUD operations 271 | * Advanced Search: double-click on time range opens dropdown with suggestions 272 | * Various performance improvements and bugfixes 273 | 274 | == Version: 2022.2.2 275 | 276 | === Captain 277 | 278 | * Added Transparent Ethernet Bridging GRE protocol type support 279 | * Centralized storage for Captain configurations 280 | * Various performance improvements and bugfixes 281 | 282 | === Salto 283 | 284 | * Removed JavaScript support in https://sip3.io/docs/features/UserDefinedFunctions.html[`UDF`] 285 | * Various performance improvements and bugfixes 286 | 287 | === Twig 288 | 289 | * Added OpenID Connect (OIDC) authentication provider support 290 | * Various performance improvements and bugfixes 291 | 292 | === Hoof 293 | 294 | * Various performance improvements and bugfixes 295 | 296 | == Version: 2022.2.1 297 | 298 | === Captain 299 | 300 | * Various performance improvements and bugfixes 301 | 302 | === Salto 303 | 304 | * Various performance improvements and bugfixes 305 | 306 | === Twig 307 | 308 | * Added `Stash` feature for calls 309 | * Various performance improvements and bugfixes 310 | 311 | === Hoof 312 | 313 | * Re-written in https://svelte.dev/[Svelte] 314 | * Added new time range for search: `Next 15 min` 315 | * Added customizable Timezones in user interface via configuration 316 | * Added ability to search by attributes with options by regex 317 | * Added `Export to CSV` for search results 318 | * Improved Advanced Search query user experience 319 | * Resizable Callflow and Event windows 320 | * Improved Display settings in Callflow 321 | * Various performance improvements and bugfixes 322 | 323 | == Version: 2022.1.2 324 | 325 | === Captain 326 | 327 | * Added RTP events processing 328 | * Various performance improvements and bugfixes 329 | 330 | === Salto 331 | 332 | * Added RTP events processing 333 | * Added MongoDB hints configuration 334 | * Modified `SipRegisterHandler` aggregation logic 335 | * Various performance improvements and bugfixes 336 | 337 | === Twig 338 | 339 | * Added RTP events processing 340 | * Various performance improvements and bugfixes 341 | 342 | == Version: 2022.1.1 343 | 344 | === Salto 345 | 346 | * Added optional management connection to MongoDB 347 | * Added `sip.message.parser.mode` parameter 348 | * Introduced UDAs provisioning modes 349 | * Various performance improvements and bugfixes 350 | 351 | === Twig 352 | 353 | * Fixed critical cache performance issue 354 | * Various performance improvements and bugfixes 355 | 356 | == Version: 2021.3.2 357 | 358 | === Captain 359 | 360 | * Shutdown SIP3 Captain via management socket 361 | * Optimized performance with `PeriodicallyExpiringHashMap` 362 | * Various performance improvements and bugfixes 363 | 364 | === Salto 365 | 366 | * Added `publish-media-control-mode` parameter 367 | * Optimized performance with `PeriodicallyExpiringHashMap` 368 | * Added UDFs dynamic re-deployment 369 | * Various performance improvements and bugfixes 370 | 371 | === Twig 372 | 373 | * Various performance improvements and bugfixes 374 | 375 | === Hoof 376 | 377 | * Added ability to share a link to search results and a particular call 378 | * Various performance improvements and bugfixes 379 | 380 | == Version: 2021.3.1 381 | 382 | === Captain 383 | 384 | * Switched to new `sip3-libpcap` version 385 | * Various performance improvements and bugfixes 386 | 387 | === Salto 388 | 389 | * Implemented a brand new search engine 390 | * Various performance improvements and bugfixes 391 | 392 | === Twig 393 | 394 | * Implemented a brand new search engine 395 | * Various performance improvements and bugfixes 396 | 397 | === Hoof 398 | 399 | * Implemented a brand new call details look and feel 400 | * Various performance improvements and bugfixes 401 | 402 | == Version: 2021.2.3 403 | 404 | === Captain 405 | 406 | * Added IPv6 support 407 | * Various performance improvements and bugfixes 408 | 409 | === Salto 410 | 411 | * Added IPv6 support 412 | * Added `ranked` attribute for filtering reliable QoS metrics 413 | * Various performance improvements and bugfixes 414 | 415 | === Twig 416 | 417 | * Introduced an algorithm of positioning `media` participants on the call flow 418 | * Various performance improvements and bugfixes 419 | 420 | === Hoof 421 | 422 | * Introduced an algorithm of positioning `media` participants on the call flow 423 | * Various performance improvements and bugfixes 424 | 425 | == Version: 2021.2.2 426 | 427 | === Captain 428 | 429 | * Added duration limit for `Media Recording On Demand` 430 | * Various performance improvements and bugfixes 431 | 432 | === Salto 433 | 434 | * Added `Media Recording On Demand` feature 435 | * Added distribution tag to `rtpr_rtp_r-factor` and `rtpr_rtcp_r-factor` metrics 436 | * Added IPv6 binding for Salto 437 | * Fixed SIP retransmits handling 438 | * Optimized RTCP processing 439 | * Various performance improvements and bugfixes 440 | 441 | === Twig 442 | 443 | * Added `Media Recording On Demand` feature 444 | * Various performance improvements and bugfixes 445 | 446 | === Hoof 447 | 448 | * Fixed timestamps in `Media Widget` 449 | * Various performance improvements and bugfixes 450 | 451 | == Version: 2021.2.1 452 | 453 | === Captain 454 | 455 | * Added `Media Recording On Demand` feature 456 | * Various performance improvements and bugfixes 457 | 458 | === Salto 459 | 460 | * Added `Media Recording On Demand` feature 461 | * Added `sip.overlapped_interval` and `sip.overlapped_fraction` attributes 462 | * Optimized SIP messages processing 463 | * Optimized SIP registrations handling 464 | * Various performance improvements and bugfixes 465 | 466 | === Twig 467 | 468 | * Added `Media Recording On Demand` feature 469 | * Various performance improvements and bugfixes 470 | 471 | === Hoof 472 | 473 | * Added `Media Recording On Demand` feature 474 | * Various performance improvements and bugfixes 475 | 476 | == Version: 2021.1.1 477 | 478 | === Captain 479 | 480 | * Switched to the new version of SIP3 protocol 481 | * Added `VXLAN` encapsulation support 482 | * Added `sender.dns-cache-ttl` property 483 | * Various performance improvements and bugfixes 484 | 485 | === Salto 486 | 487 | * Switched to the new version of SIP3 protocol 488 | * Introduced a new RTP/RTCP correlation engine 489 | * Added a set of `media.xxx` attributes 490 | * Added `sip.cancel_time` and `sip.terminated_by` attributes 491 | * Various performance improvements and bugfixes 492 | 493 | === Twig 494 | 495 | * Added new media correlation engine support 496 | * Various performance improvements and bugfixes 497 | 498 | === Hoof 499 | 500 | * Removed simple search `caller` and `callee` restrictions 501 | * Added `media.xxx` attributes support 502 | * Various performance improvements and bugfixes 503 | 504 | == Version: 2020.3.1 505 | 506 | === Captain 507 | 508 | * Moved RTCP related calculations to the SIP3 Salto 509 | * Added `timestamp` parameter to the management socket exchange 510 | * Various performance improvements and bugfixes 511 | 512 | === Salto 513 | 514 | * Added RTCP related calculations support 515 | * Added HEP3 RTCP packets processing 516 | * Added dynamic codecs support 517 | * Various performance improvements and bugfixes 518 | 519 | === Twig 520 | 521 | * Fixed Swagger UI integration 522 | * Various performance improvements and bugfixes 523 | 524 | == Version: 2020.2.1 525 | 526 | === Captain 527 | 528 | * `pcap.dlt` property to support various https://www.tcpdump.org/linktypes.html[DataLink] types 529 | 530 | === Salto 531 | 532 | * Search registrations by `sip.duration` attribute 533 | * Call duration distribution statistic 534 | * https://sip3.io/docs/features/UserDefinedFunctions.html#sip_call_udf[`sip_call_udf`] endpoint 535 | * Various performance improvements and bugfixes 536 | 537 | === Twig 538 | 539 | * Switch to https://github.com/sip3io/sip3-twig-ce[`sip3-twig-ce`] from the Github 540 | * Various performance improvements and bugfixes 541 | 542 | === Hoof 543 | 544 | * `Today` option in datetimepicker 545 | * Advanced call flow implementation 546 | * Various performance improvements and bugfixes 547 | 548 | == Version: 2020.1.1 549 | 550 | === Captain 551 | 552 | * Payload compression to avoid problems with MTU 553 | * https://en.wikipedia.org/wiki/TZSP[TZSP] protocol support 554 | * `sip3-libpcap` integration 555 | * https://dev.to/sip3/how-to-monitor-remote-jvm-applications-with-logback-webhook-appender-2oc5[`logback-webhook-appender`] integration 556 | * Various performance improvements and bugfixes 557 | 558 | === Salto 559 | 560 | * https://sip3.io/docs/features/UserDefinedFunctions.html#_packet_udf[`packet_udf`] endpoint 561 | * SIP Register handling support 562 | * https://dev.to/sip3/how-to-monitor-remote-jvm-applications-with-logback-webhook-appender-2oc5[`logback-webhook-appender`] integration 563 | * Various performance improvements and bugfixes 564 | 565 | === Twig 566 | 567 | * SIP Register handling support 568 | * `/session/media` API endpoint 569 | * Various performance improvements and bugfixes 570 | 571 | === Hoof 572 | 573 | * Media QoS widget 574 | * Dynamic (per participant) call flow 575 | * Time scale switcher 576 | * Various performance improvements and bugfixes 577 | -------------------------------------------------------------------------------- /modules/ROOT/pages/UpgradeGuide.adoc: -------------------------------------------------------------------------------- 1 | = Upgrade Guide 2 | :description: SIP3 Upgrade Guide 3 | 4 | == Overview 5 | 6 | The document describes the steps to upgrade the SIP3 solution to a new version. 7 | These steps are necessary for quick, successful update without negative outcome. 8 | 9 | NOTE: We recommend upgrading the SIP3 solution using the configuration described in the `sip3-ansible` project inventory file. 10 | We support an update procedure between subsequent versions. 11 | 12 | Since release 2023.2.1 requires to use Java Virtual Machine version 17. 13 | The SIP3 solution begins to use JVM 17 developed by Adoptium (https://adoptium.net/temurin/releases[JRE Eclipse Temurin by Adoptium]), 14 | which we packaged into `sip3-java` package for Linux. This package is required for other SIP3 solution packages. 15 | 16 | You should pay attention to checking JAVA_HOME variable in the configuration files. 17 | The file `environment.conf` exists in all application of SIP3 solution. Locations: `/etc/sip3-{application}/environment.conf` 18 | (e.g. '/etc/sip3-salto/environment.conf`). 19 | JAVA_HOME variable should be setted to `/opt/sip3-java`. 20 | 21 | Example of `environment.conf`: 22 | ``` 23 | JAVA_HOME=/opt/sip3-java 24 | JAVA_XMS=-Xms512M 25 | JAVA_XMX=-Xmx1024M 26 | JAVA_GC=-XX:+UseG1GC 27 | JAVA_OTHER= 28 | ``` 29 | -------------------------------------------------------------------------------- /modules/ROOT/pages/features/AccessControl.adoc: -------------------------------------------------------------------------------- 1 | = Access Control 2 | :description: SIP3 Access control. 3 | 4 | == Overview 5 | 6 | To offer security and access control in SIP3 was developed and implemented Role-based access control model. SIP3 supports OpenID Connect or SAML 2.0 Identity Providers like https://www.keycloak.org[Keycloak]. 7 | 8 | == Security Roles 9 | 10 | There are 5 predefined roles in SIP3: 11 | 12 | <1> [[SIP3_UNAUTHORIZED]] `SIP3_UNAUTHORIZED` 13 | <2> [[SIP3_VIEWER]]`SIP3_VIEWER` 14 | <3> [[SIP3_SUPPORT]]`SIP3_SUPPORT` 15 | <4> [[SIP3_SUPERVISOR]]`SIP3_SUPERVISOR` 16 | <5> [[SIP3_ADMIN]]`SIP3_ADMIN` 17 | 18 | These roles can grant access for support users to search and view SIP sessions, enable xref:features/MediaRecordingOnDemand.adoc[Media Recording On Demand] and deny access to setting up and editing the system. System administrators will also have access to configuration and management of SIP3 components, advanced Media Recording functionality, etc. 19 | 20 | === Access control matrix 21 | [cols="1,2,3,^4,^5,^6,^7,^8,^9"] 22 | |=== 23 | 4+| 24 | 5+^|<<_security_roles, Roles>> 25 | ^|Site 26 | ^|Action 27 | ^|Endpoint 28 | ^|Method 29 | ^|`<>` 30 | ^|`<>` 31 | ^|`<>` 32 | ^|`<>` 33 | ^|`<>` 34 | 35 | |Attributes 36 | |View attributes 37 | |`/api/attributes` 38 | ^|* 39 | | 40 | | 41 | |X 42 | |X 43 | |X 44 | 45 | |Search 46 | |Session search 47 | |`/api/search` 48 | ^|* 49 | | 50 | | 51 | |X 52 | |X 53 | |X 54 | 55 | .5+|Sessions 56 | .3+|View session 57 | |`/api/session/flow` 58 | ^|* 59 | | 60 | |X 61 | |X 62 | |X 63 | |X 64 | 65 | |`/api/session/details` 66 | ^|* 67 | | 68 | |X 69 | |X 70 | |X 71 | |X 72 | 73 | |`/api/session/media` 74 | ^|* 75 | | 76 | |X 77 | |X 78 | |X 79 | |X 80 | 81 | |Export to PCAP 82 | |`/api/session/pcap` 83 | ^|* 84 | | 85 | | 86 | |X 87 | |X 88 | |X 89 | 90 | |Stash session 91 | |`/api/session/stash` 92 | ^|* 93 | | 94 | | 95 | |X 96 | |X 97 | |X 98 | 99 | .4+|Hosts 100 | .2+|View hosts 101 | |`/api/hosts` 102 | <|GET 103 | | 104 | | 105 | |X 106 | |X 107 | |X 108 | 109 | |`/api/hosts/` 110 | <|GET 111 | | 112 | | 113 | |X 114 | |X 115 | |X 116 | 117 | |Edit hosts 118 | |`/api/hosts` 119 | |POST + 120 | PUT + 121 | DELETE 122 | | 123 | | 124 | | 125 | |X 126 | |X 127 | 128 | |Import hosts 129 | |`/api/hosts/import` 130 | |POST 131 | | 132 | | 133 | | 134 | | 135 | |X 136 | 137 | .4+|Tasks 138 | |View task 139 | |`/api/tasks/` 140 | <|GET 141 | | 142 | | 143 | |X 144 | |X 145 | |X 146 | 147 | |Search task 148 | |`/api/tasks/search` 149 | |POST 150 | | 151 | | 152 | |X 153 | |X 154 | |X 155 | 156 | |Add task 157 | |`/api/tasks/` 158 | <|POST 159 | | 160 | | 161 | | 162 | |X 163 | |X 164 | 165 | |Cancel task 166 | |`/api/tasks//cancel` 167 | <|PUT 168 | | 169 | | 170 | | 171 | |X 172 | |X 173 | 174 | .4+|Recordings 175 | .4+|Add recording task 176 | |`/api/tasks/recording/user/` 177 | <|POST 178 | | 179 | | 180 | |X 181 | |X 182 | |X 183 | 184 | |`/api/tasks/recording/addr/` 185 | |POST 186 | | 187 | | 188 | |X 189 | |X 190 | |X 191 | 192 | |`/api/tasks/recording/host/` 193 | |POST 194 | | 195 | | 196 | |X 197 | |X 198 | |X 199 | 200 | |`/api/tasks/recording/filter` 201 | |POST 202 | | 203 | | 204 | | 205 | |X 206 | |X 207 | 208 | .4+|Components 209 | |View 210 | |`/api/management/components` 211 | <|GET 212 | | 213 | | 214 | | 215 | |X 216 | |X 217 | 218 | |Reset recording-status 219 | |`/api/management/components/recording-reset` 220 | ^|* 221 | | 222 | | 223 | | 224 | | 225 | |X 226 | 227 | |Shutdown 228 | |`/api/management/components/shutdown` 229 | ^|* 230 | | 231 | | 232 | | 233 | | 234 | |X 235 | 236 | |Delete 237 | |`/api/management/components` 238 | |DELETE 239 | | 240 | | 241 | | 242 | | 243 | |X 244 | 245 | .3+|Configuration 246 | |View 247 | |`/api/management/configuration` 248 | <|GET 249 | | 250 | | 251 | | 252 | | 253 | |X 254 | 255 | |Edit 256 | |`/api/management/configuration` 257 | |POST + 258 | PUT 259 | | 260 | | 261 | | 262 | | 263 | |X 264 | 265 | |Delete 266 | |`/api/management/configuration` 267 | |DELETE 268 | | 269 | | 270 | | 271 | | 272 | |X 273 | |=== 274 | 275 | == Customization 276 | 277 | To be more flexible SIP3 Access control matrix is ready to be modified according to customer requirements. Standard roles can be changed, and new roles with a limited set of rights can be added. -------------------------------------------------------------------------------- /modules/ROOT/pages/features/AdvancedSearch.adoc: -------------------------------------------------------------------------------- 1 | = Advanced Search 2 | :description: SIP3 Advanced Search. 3 | 4 | == Overview 5 | 6 | `Advanced Search` is a very minimalistic user interface to a very powerful SIP3 search API. Its syntax was inspired by Wireshark filters and includes three main groupings of search attributes: `sip`, `rtp` and `rtcp`. `Advanced Search` input represents a SIP3 query which consists of selected time range and one or many search attributes expressions connected via logical `AND` operator: 7 | 8 | image::AdvancedSearchQueryExample.png[Advanced Search Query Example] 9 | 10 | == Expressions 11 | 12 | Search attributes expressions are very simple syntactic constructions: 13 | ``` 14 | 15 | ``` 16 | 17 | SIP3 supports 3 main attributes types: `String`, `Boolean` and `Number`. In meantime each of the types support a certain list of operators: 18 | 19 | |=== 20 | |Operator | Types | Description 21 | 22 | | `=` 23 | | `String`, `Boolean`, `Number` 24 | | Equals 25 | 26 | | `!=` 27 | | `String`, `Boolean`, `Number` 28 | | Not equals 29 | 30 | | `>` 31 | | `Number` 32 | | More than 33 | 34 | | `<` 35 | | `Number` 36 | | Less than 37 | 38 | | `=~` 39 | | `String` 40 | | Regular expression 41 | |=== 42 | 43 | If search attribute has finite amount of possible values (as for instance any `Boolean` or some `String` attributes do) all its values will be shown in a dropdown menu: 44 | 45 | image::SearchAttributeWithFiniteAmountOfPossibleValues.png[Search Attribute With Finite Amount Of Possible Values] 46 | 47 | Otherwise, you can just write anything as its value: 48 | 49 | image::SearchAttributeWithInfiniteAmountOfPossibleValues.png[Search Attribute With Infinite Amount Of Possible Values] 50 | 51 | For Number attributes `duration`, `trying_delay` etc you can use `s`(Seconds) and `m`(Minutes) suffix in values. I.e. next expressions has the same result: 52 | 53 | - `sip.duration>60000` 54 | - `sip.duration>60s` 55 | - `sip.duration>1m` 56 | 57 | == Groupings 58 | 59 | As it was mentioned above every SIP3 query is a combination of multiple search attributes expressions. And here you have no limitations. Feel free to combine as many attributes as you need. They also can be from different groupings like `"sip.caller=plami rtp.r_factor<30"`. There is only one thing you need to account for: 60 | 61 | IMPORTANT: Queries `"sip.caller=plami rtp.r_factor<30"` and `"rtp.r_factor<30 sip.caller=plami"` are not the same because SIP3 uses different database collections for signaling and media data indexes. It's up to you to decide which one of these queries will be faster. 62 | 63 | === `"sip"` attributes 64 | 65 | As you already got it the `sip` grouping is a set of attributes corresponding to the SIP protocol. The `sip` grouping consists of 25 default search attributes but could be easily extended with xref::features/UserDefinedFunctions.adoc#_user_defined_attributes[User-Defined Attributes]. 66 | 67 | |=== 68 | |Attribute |Type |Description 69 | 70 | | `sip.addr` 71 | | `String` 72 | | Source or destination IP address. Virtual attribute which helps to cover queries like `sip.src_addr=127.0.0.1 or sip.dst_addr=127.0.0.1` 73 | 74 | | `sip.src_addr` 75 | | `String` 76 | | Source IP address 77 | 78 | | `sip.dst_addr` 79 | | `String` 80 | | Destination IP address 81 | 82 | | `sip.host` 83 | | `String (with options)` 84 | | Source or destination host. Virtual attribute which helps to cover queries like `sip.src_host=PBX-1 or sip.dst_host=PBX-1` 85 | 86 | | `sip.src_host` 87 | | `String (with options)` 88 | | Source host 89 | 90 | | `sip.dst_host` 91 | | `String (with options)` 92 | | Destination host 93 | 94 | | `sip.user` 95 | | `String` 96 | | `From` or `To` SIP headers user. Virtual attribute which helps to cover queries like `sip.caller=plami or sip.callee=plami` 97 | 98 | | `sip.caller` 99 | | `String` 100 | | `From` SIP header user. Take into account that `sip.caller` might be re-assigned within a xref::features/UserDefinedFunctions.adoc#_service_attributes[User-Defined Function] 101 | 102 | | `sip.callee` 103 | | `String` 104 | | `To` SIP header user. Take into account that `sip.callee` might be re-assigned within a xref::features/UserDefinedFunctions.adoc#_service_attributes[User-Defined Function] 105 | 106 | | `sip.method` 107 | | `String(with options)` 108 | | SIP method. Helps to optimize your search request performance by querying corresponding data only 109 | 110 | | `sip.call_id` 111 | | `String` 112 | | `Call-ID` SIP header 113 | 114 | | `sip.state` 115 | | `String(with options)` 116 | | Call, registration or transaction state. For instance, possible call states are `unknown`, `redirected`, `answered`, `canceled` and `failed` 117 | 118 | | `sip.error_code` 119 | | `String(with options)` 120 | | Last SIP session's transaction error code 121 | 122 | | `sip.error_type` 123 | | `String(with options)` 124 | | Last SIP session's transaction error type: `client`, `server` or `global` 125 | 126 | | `sip.duration` 127 | | `Number` 128 | | SIP call duration in milliseconds 129 | 130 | | `sip.trying_delay` 131 | | `Number` 132 | | Time in milliseconds between SIP INVITE request and corresponding 100 SIP response 133 | 134 | | `sip.setup_time` 135 | | `Number` 136 | | Time in milliseconds between SIP INVITE request and corresponding 18x SIP response 137 | 138 | | `sip.cancel_time` 139 | | `Number` 140 | | Time in milliseconds between SIP INVITE request and corresponding 487 SIP response 141 | 142 | | `sip.establish_time` 143 | | `Number` 144 | | Time in milliseconds between SIP INVITE request and corresponding 200 SIP response 145 | 146 | | `sip.disconnect_time` 147 | | `Number` 148 | | Time in milliseconds between SIP BYE request and corresponding 200 SIP response 149 | 150 | | `sip.transactions` 151 | | `Number` 152 | | Amount of SIP transactions 153 | 154 | | `sip.retransmits` 155 | | `Number` 156 | | Amount of SIP retransmits 157 | 158 | | `sip.terminated_by` 159 | | `String(with options)` 160 | | Party terminated SIP session: `caller` or `callee` 161 | 162 | | `sip.overlapped_interval` 163 | | `Number` 164 | | Difference in milliseconds between a time when REGISTER session is supposed be expired and a time when renewal SIP REGISTER message came. Helps to find SIP user agents who ignore `Expiration` SIP header contract 165 | 166 | | `sip.overlapped_fraction` 167 | | `Number` 168 | | `sip.overlapped_interval` ratio. Helps to find SIP user agents who ignore `Expiration` SIP header contract 169 | 170 | | `sip.my_custom_attribute` 171 | | `String(with or without options)`, `Boolean` 172 | | Custom xref::features/UserDefinedFunctions.adoc#_user_defined_attributes[User-Defined Attributes] 173 | |=== 174 | 175 | === `"rtp"` and `"rtcp"` attributes 176 | 177 | It doesn't make sense to separate `rtp` and `rtcp` groupings definition because after all both groupings have the same set of attributes. The only one difference between these two - is a source of data: RTP or RTCP protocols. 178 | 179 | |=== 180 | |Attribute |Type |Description 181 | 182 | | `rtp.addr`, `rtcp.addr` 183 | | `String` 184 | | Source or destination IP address. Virtual attribute which helps to cover queries like `sip.src_addr=127.0.0.1 or sip.dst_addr=127.0.0.1` 185 | 186 | | `rtp.src_addr`, `rtcp.src_addr` 187 | | `String` 188 | | Source IP address 189 | 190 | | `rtp.dst_addr`, `rtcp.dst_addr` 191 | | `String` 192 | | Destination IP address 193 | 194 | | `rtp.host`, `rtcp.host` 195 | | `String (with options)` 196 | | Source or destination host. Virtual attribute which helps to cover queries like `sip.src_host=PBX-1 or sip.dst_host=PBX-1` 197 | 198 | | `rtp.src_host`, `rtcp.src_host` 199 | | `String (with options)` 200 | | Source host 201 | 202 | | `rtp.dst_host`, `rtcp.dst_host` 203 | | `String (with options)` 204 | | Destination host 205 | 206 | | `rtp.mos`, `rtcp.mos` 207 | | `Number` 208 | | Mean Opinion Score. Always stays in from 0 to 5 range 209 | 210 | | `rtp.r_factor`, `rtcp.r_factor` 211 | | `Number` 212 | | R-Factor. Always stays in from 0 to 100 range 213 | 214 | | `rtp.codec`, `rtcp.codec` 215 | | `String (with options)` 216 | | Codec used for media data processing 217 | 218 | | `rtp.bad_report_fraction`, `rtcp.bad_report_fraction` 219 | | `Number` 220 | | During a media session participants generate and send multiple RTCP messages. Each of the messages represents a single report. This metric helps to find media sessions with problems during entire time of the session 221 | 222 | | `rtp.one_way`, `rtcp.one_way` 223 | | `Boolean` 224 | | Helps to find one-way media streams 225 | 226 | | `rtp.duration`, `rtcp.duration` 227 | | `Number` 228 | | Media session duration in milliseconds 229 | |=== 230 | 231 | == Search History 232 | 233 | It happens that we can go into wrong direction while troubleshooting a particular problem. In such cases it might be good to be able to get a few steps back. That's why `Advanced Search` has a history of searches section: 234 | 235 | image::SearchHistory.png[Search History] 236 | 237 | Search History can be opened by hitting `Ctrl`/`Cmd` + `Arrow Down` as well. 238 | 239 | == Conclusions 240 | 241 | Now when you know how to use `Advanced Search` let's take a look at xref::features/CallDetails.adoc[Call Details] section. -------------------------------------------------------------------------------- /modules/ROOT/pages/features/CallDetails.adoc: -------------------------------------------------------------------------------- 1 | = Call Details 2 | :desription: SIP3 Call Details 3 | 4 | == Overview 5 | Here is an example of the SIP3 `Call Details Widget` which allows to effectively inspect visualized information about any particular call. 6 | 7 | image::CallDetailsWidget.png[Call Details Widget] 8 | 9 | == Structure 10 | Call Details Widget consists of title and 3 main areas. 11 | 12 | === Title 13 | Title contains __Caller__ and __Callee__ information and 3 buttons 14 | 15 | image::CallDetailsWidgetTitle.png[Call Details Widget Title] 16 | 17 | With these buttons you can Minimize, Maximize and Close `Call Details Widget`. 18 | 19 | === Header 20 | Left side of Header is used for navigation. Currently, you could switch between 3 different tabs. 21 | 22 | image::CallDetailsWidgetHeader.png[Call Details Widget Header] 23 | 24 | - The `Flow` tab shows a xref:features/CallFlowDiagram.adoc[Call Flow Diagram]. 25 | - The `Legs` tab shows info about Call Legs list. 26 | - The `Messages` tab shows info about Call Messages list. 27 | 28 | On the right side of Header are control elements for this Call. 29 | 30 | - Stash the call. It helps to save the call to special collections for storing them for as long as you need (xref:CommunityEditionVsEnterpriseEdition.adoc[EE feature]). 31 | - Share this call. Get link to the call and share it with you teammates. 32 | - Export this call. It allows to export either all or selected call legs in _PNG_ and _PCAP_. 33 | 34 | NOTE: Check out the Display settings section of xref:features/CallFlowDiagram.adoc[Call Flow Diagram page] to find out how to select call legs. 35 | 36 | image::ExportToDropdown.png[Export To Dropdown] 37 | 38 | === Info 39 | Info always shows main information, that needs to be easily accessible from any tab, like call's __caller__ and __callee__, __start time__, __status__ and __duration__. 40 | 41 | image::CallDetailsWidgetInfo.png[Call Details Widget Info] 42 | 43 | === Body 44 | Body is used to show the content of a currently selected tab. It shows either the xref:features/CallFlowDiagram.adoc[Call Flow Diagram], the Call Legs list or the Call Messages list. 45 | 46 | ==== Call Legs 47 | The Call Legs tab allows going through information about each call leg in the call. 48 | 49 | image::CallDetailsWidgetLegs.png[Call Details Widget Legs] 50 | 51 | ==== Call Messages 52 | The Call Messages tab provides detailed information about all call messages in the call. 53 | 54 | image::CallDetailsWidgetMessages.png[Call Details Widget Messages] 55 | -------------------------------------------------------------------------------- /modules/ROOT/pages/features/CallFlowDiagram.adoc: -------------------------------------------------------------------------------- 1 | = Call Flow Diagram 2 | :desription: SIP3 Call Flow Diagram 3 | 4 | == Overview 5 | Here is an example of the SIP3 `Call Flow Diagram` which allows to analyze a call as a sequence diagram. It's the key feature of a xref:features/CallDetails.adoc[Call Details Widget]. 6 | 7 | image::CallFlowSequenceDiagram.png[Call Flow Sequence Diagram] 8 | 9 | The diagram visualizes cryptic information about the call and represents it as a combination of call events between participants. 10 | 11 | == Events 12 | Both `SIP Events` and `Media Events` are placed in chronological order. 13 | 14 | NOTE: Keep in mind, that each `Media Event` stay in place on scroll between its start and finish timestamp in the call. 15 | 16 | === SIP Events 17 | Each `SIP Event` has short info about its method and timestamp. If you hover a `SIP Event`, all sip events, that belongs to the same transaction highlights. 18 | 19 | image::CallFlowSipEventsHighlighting.png[Call Flow Sip Events Highlighting] 20 | 21 | The more detailed info is shown on event click and looks like this: 22 | 23 | image::CallFlowSipMessage.png[Call Flow Sip Message] 24 | 25 | NOTE: Ctrl/Cmd + click on event opens all messages for selected SIP transaction 26 | 27 | Each `SIP Event` timestamp is clickable and cycles through `Absolute`, `Delta` and `Relative` time on each mouse click. 28 | 29 | NOTE: There is another way to change timestamps settings from call flow sidebar menu, and it's discussed later in this manual. 30 | 31 | === Media Events 32 | Each `Media Event` has info about its codecs and r-factor value. 33 | 34 | image::CallFlowMediaEventsSitcking.png[Call Flow Media Events Sticking] 35 | 36 | The xref:features/MediaRecordingOnDemand.adoc[Media Quality Widget] is shown on event click. 37 | 38 | image::CallFlowMediaMessage.png[Call Flow Media Message] 39 | 40 | == Call Flow Sidebar 41 | 42 | Also, the `Call Flow` interface has sidebar, where all main controls live. 43 | 44 | image::CallFlowSidebarButtonHighlighted.png[Call Flow Sidebar Button Highlighted] 45 | 46 | image::CallFlowSidebarOpened.png[Call Flow Sidebar Opened] 47 | 48 | The `Call Flow` sidebar has a `Display settings` and `Time settings` control. 49 | 50 | NOTE: All settings and controls are going to be placed inside the call flow sidebar. Follow us on https://twitter.com/sip3_io[twitter] to keep up to date with latest and greatest additions to the controls of the call flow diagram. 51 | 52 | == Display Settings 53 | 54 | The `Display Settings` control allow selecting different legs. All Legs are grouped by leg type: 55 | 56 | - `SIP` 57 | - `Media` 58 | - `DTMF` 59 | 60 | The selection affects which legs are shown on the call flow diagram and which legs are exported as a PNG and PCAP from the `Export` dropdown. Also, the control shows info about leg's Call ID on hover. 61 | 62 | image::CallFlowSidebarDisplaySettingsControl.png[Call Flow Sidebar Display Settings Control] 63 | 64 | === Selection Logic 65 | [options="header"] 66 | |======================= 67 | | Action | Result 68 | | Single click on a selected leg | Leg is deselected. 69 | | Single click on a non-selected leg | Leg is selected. 70 | | Single click on a selected group | All legs of this group are deselected. 71 | | Single click on a partially selected group | All legs of this group are selected. 72 | | Single click on a non-selected group | All legs of this group are selected. 73 | | Ctrl/Cmd + click on a leg | Only this leg is selected. All other will be deselected. 74 | | Ctrl/Cmd + click on a group | Only legs of this group are selected. All other will be deselected. 75 | |======================= 76 | 77 | NOTE: If no leg will be selected, previous selection choice will be applied. 78 | 79 | === Time Settings 80 | 81 | The `Time Settings` control allow changing timestamps type of all events, except the first and the last one. 82 | 83 | [options="header"] 84 | |======================= 85 | |Time setting|Explanation 86 | |Absolute time |A timestamps displays the "real" time. 87 | |Delta time |A timestamp of any given event displays the time from previous event. 88 | |Relative time |A timestamp of any given event displays time from the first event. 89 | |======================= 90 | 91 | image::CallFlowSidebarTimeSettingsControl.png[Call Flow Sidebar Time Settings Control] 92 | -------------------------------------------------------------------------------- /modules/ROOT/pages/features/Components.adoc: -------------------------------------------------------------------------------- 1 | = Components 2 | :description: SIP3 Components. 3 | 4 | == Overview 5 | SIP3 provides control over its components. On Components page there is table that shows all Captains connected to Salto. 6 | 7 | image::Components.png[Components table] 8 | 9 | - `Name` - the name of the component from its configuration 10 | - `Type` - component type 11 | - `Connected to` - the name of the Salto to which the component is connected 12 | - `Registered at` - date and time of the first `register` message from the Captain 13 | - `Updated at` - date and time of the last `register` message from the Captain 14 | - `Time difference` - time difference between the timestamp of `register` message on Captain host and the timestamp of receiving this message on Salto 15 | 16 | - `Actions` - available actions for this type of component 17 | * image:SettingsIcon.png[Settings] - view configuration of remote component in JSON 18 | * image:PowerOffIcon.png[Shutdown] - shutdown component (available in xref:CommunityEditionVsEnterpriseEdition.adoc[Enterprise Edition]). 19 | 20 | NOTE: The Shutdown action will cause the component restart if it was installed as `systemd` service. 21 | 22 | -------------------------------------------------------------------------------- /modules/ROOT/pages/features/HoofConfiguration.adoc: -------------------------------------------------------------------------------- 1 | = Hoof Configuration 2 | :description: SIP3 Hoof Configuration. 3 | 4 | == Overview 5 | 6 | In general SIP3 Hoof can be deeply customized by our developers. Also SIP3 Hoof can be customized with configuration. What can be customized? 7 | 8 | * Common configuration 9 | * Sidebar Menu 10 | * Timezones 11 | * Custom Searches 12 | * Custom Search Results 13 | * Winbox behaviour 14 | 15 | 16 | Hoof configuration is stored in JSON format: 17 | 18 | [source,json] 19 | ---- 20 | { 21 | "time_zones": [], // <1> 22 | "winbox": {}, // <2> 23 | "sidebar": { // <3> 24 | "dashboards": [], 25 | "searches": [], 26 | "links": [] 27 | }, 28 | "searches": [], // <4> 29 | "features": [], // <5> 30 | "root_path": "", // <6> 31 | "default_route": "/search/advanced", // <7> 32 | "oauth2": {} // <8> 33 | } 34 | ---- 35 | 36 | <1> `time_zones` - List of available timezones 37 | <2> `winbox` - Winbox behaviour configuration 38 | <3> `sidebar` - Sidebar menu configuration. Contains from 39 | `dashboards` - Links to dashboards. Always place on the top of the sidebar 40 | `searches` - Links to Searches 41 | `links` - Internal and External links to resources 42 | <4> `searhes` - Custom search configurations 43 | <5> `features` - List of features to be enabled in Hoof 44 | <6> `root_path` - Root path used when Hoof is placed after proxy and have prefix in path 45 | <7> `default_route` - Default route after successful login or going to `root_path` 46 | <8> `oauth2` - OAuth2 configuration 47 | 48 | == Timezones 49 | 50 | Default configuration have 2 timezones: 51 | 52 | * Local timezone based on Browser environment 53 | * UTC timezone 54 | 55 | Timezone configuration JSON: 56 | [source,json] 57 | ---- 58 | { 59 | "label": "NPT", // <1> 60 | "name": "Nepal", // <2> 61 | "value": "+05:45" // <3> 62 | } 63 | ---- 64 | 65 | <1> `label` - Short name of Timezone that will be showed in User Interface 66 | <2> `name` - Name of Timezone to be showed in dropdown 67 | <3> `value` - Timezone offset 68 | 69 | Timezone will appear in dropdown in same order as in JSON Array. 70 | 71 | == Winbox 72 | 73 | Winbox configuration contains parameters that define behaviour of all winboxes: 74 | [source,json] 75 | ---- 76 | { 77 | "auto_close": true // <1> 78 | } 79 | ---- 80 | <1> `auto_close` - If `true` all winboxes will be closed after changing layouts. 81 | 82 | == Sidebar configuration 83 | 84 | Sidebar contains 4 main sections: 85 | 86 | * Dashboards 87 | * Searches 88 | * Management 89 | * Links 90 | 91 | image::SidebarExample.png[Sidebar example] 92 | 93 | NOTE: Management section is not configurable directly 94 | 95 | Sections contain links to resources. A link may be `internal` or `external`. 96 | 97 | * `internal` link type used to navigate through Hoof layouts. 98 | * `external` links opens in new tab and must have full URL to resource. 99 | 100 | [source,json] 101 | ---- 102 | { 103 | "order": 0, // <1> 104 | "name": "Technical Dashboard", // <2> 105 | "type": "internal", // <3> 106 | "url": "/dashboard/technical" // <4> 107 | } 108 | ---- 109 | 110 | <1> `order` - Priority that determine position of the link. 111 | <2> `name` - Link name 112 | <3> `type` - Type of the link 113 | <4> `url` - URL 114 | 115 | == Searches 116 | 117 | Hoof allows to add custom search layout with additional fields in search results. 118 | 119 | image::CustomSearchLayout.png[Custom Search Layout] 120 | 121 | .Full Custom Search configuration example 122 | [%collapsible] 123 | ==== 124 | [source,json] 125 | ---- 126 | { 127 | "id": "custom", 128 | "name": "Custom search", 129 | "sections": [ 130 | { 131 | "id": "main", 132 | "name": "Main search attributes", 133 | "attributes": [ 134 | [ 135 | { 136 | "name": "timeRange", 137 | "type": "time_range" 138 | }, 139 | { 140 | "name": "sip.caller", 141 | "placeholder": "Caller" 142 | }, 143 | { 144 | "name": "sip.callee", 145 | "placeholder": "Callee" 146 | } 147 | ], 148 | [ 149 | { 150 | "name": "sip.state", 151 | "placeholder": "State" 152 | }, 153 | { 154 | "name": "callsOnly", 155 | "type": "checkbox", 156 | "placeholder": "Calls only", 157 | "init_value": "sip.method=INVITE", 158 | "if_true": "sip.method=INVITE", 159 | "if_false": "" 160 | } 161 | ] 162 | ] 163 | }, 164 | { 165 | "id": "hosts", 166 | "name": "Host search attributes", 167 | "attributes": [ 168 | [ 169 | { 170 | "name": "sip.src_addr" 171 | }, 172 | { 173 | "name": "sip.src_host", 174 | "init_value": "domru" 175 | }, 176 | { 177 | "name": "sip.dst_addr" 178 | }, 179 | { 180 | "name": "sip.dst_host", 181 | "init_value": "PBX-.*", 182 | "init_operator": "=~" 183 | } 184 | ] 185 | ] 186 | } 187 | ], 188 | "results": { 189 | "columns": [ 190 | { 191 | "header": "Establish time", 192 | "src": "sip.establish_time", 193 | "formatter": "duration" 194 | }, 195 | { 196 | "header": "Terminated at", 197 | "src": "sip.terminated_at", 198 | "formatter": "datetime" 199 | }, 200 | { 201 | "header": "Transactions", 202 | "src": "sip.transactions" 203 | }, 204 | { 205 | "header": "Src addr", 206 | "src": "sip.src_addr" 207 | } 208 | ] 209 | } 210 | } 211 | ---- 212 | ==== 213 | 214 | Search configuration consist of 4 main parameters: 215 | 216 | [source,json] 217 | ---- 218 | { 219 | "id": "custom", // <1> 220 | "name": "Custom search", // <2> 221 | "sections": [ ], // <3> 222 | "results": { } // <4> 223 | } 224 | ---- 225 | <1> `id` - Custom search ID 226 | <2> `name` - Custom search name 227 | <3> `sections` - Section of search attributes 228 | <4> `results` - Configuration for search results 229 | 230 | === Section 231 | 232 | Section used to group attributes and arrange it on gird for better usability. 233 | 234 | [source,json] 235 | ---- 236 | { 237 | "id": "main", // <1> 238 | "name": "Main search attributes", // <2> 239 | "attributes": [ // <3> 240 | [ ], 241 | [ ] 242 | ] 243 | } 244 | ---- 245 | <1> `id` - Section ID 246 | <2> `name` - Section name 247 | <3> `attributes` - List of attribute lines. 248 | 249 | NOTE: Recommended attributes in one line is not more than 4. 250 | 251 | === Custom Search Attribute 252 | 253 | All Custom Search Attributes have `name`, other parameters are optional. Attribute may be one of types: 254 | 255 | * `time_range` - Date and time range selector 256 | * `checkbox` - Checkbox that define query to be added to Search query 257 | * `string` - String type 258 | * `boolean` - Boolean type 259 | * `number` - Number type. 260 | 261 | [source,json] 262 | ---- 263 | { 264 | "name": "callsOnly", // <1> 265 | "type": "checkbox", // <2> 266 | "placeholder": "Calls only", // <3> 267 | "init_value": "sip.method=INVITE", // <4> 268 | "init_operator": "=", // <5> 269 | "if_true": "sip.method=INVITE", // <6> 270 | "if_false": "" // <7> 271 | } 272 | ---- 273 | 274 | <1> `name` - Attribute name 275 | <2> `type` - Attribute type. 276 | <3> `placeholder` - Placeholder that will be displayed in Input field. 277 | <4> `init_value` - Initial value 278 | <5> `init_operator` - Initial operator 279 | <6> `if_true` - Search query expression if checkbox is checked 280 | <7> `if_false` - Search query expression if checkbox is not checked 281 | 282 | === Custom search results 283 | 284 | Search result in Custom Search may be modified by adding custom columns from Search Results: 285 | 286 | [source,json] 287 | ---- 288 | { 289 | "columns": [ 290 | { 291 | "header": "Establish time", // <1> 292 | "src": "sip.establish_time", // <2> 293 | "formatter": "duration" // <3> 294 | }, 295 | { 296 | "header": "Terminated at", 297 | "src": "sip.terminated_at", 298 | "formatter": "datetime" 299 | }, 300 | { 301 | "header": "Transactions", 302 | "src": "sip.transactions" 303 | }, 304 | { 305 | "header": "Src addr", 306 | "src": "sip.src_addr", 307 | "display_type": "set" // <4> 308 | } 309 | ] 310 | } 311 | ---- 312 | <1> `header` - Column name in Search Result Table 313 | <2> `src` - Field name from Search Result 314 | <3> `formatter` - Formatter for the value. Available types: `datetime`, `duration` or raw value if not set 315 | <4> `display_type` - Define display type for values. 316 | 317 | - `first` - Display only first non-null value for `src` 318 | - `set` - Display all unique values 319 | - `list` - Display all values in the same order as this value appears in Call legs. 320 | 321 | === Features 322 | 323 | To enable some features in SIP3 Hoof you need to add this named feature to `features`: 324 | 325 | [source,json] 326 | ---- 327 | { 328 | "features": [ 329 | "recording_tasks" 330 | ] 331 | } 332 | ---- 333 | 334 | Available features in 2025.1.1: 335 | 336 | - `recording_tasks` 337 | - `configurations` 338 | 339 | NOTE: Starting from 2024.2.2 version only one feature is available: `recording_tasks` 340 | 341 | === OAuth2 Configuration 342 | 343 | SIP3 Hoof supports OAuth2 authentication and need to be configured properly: 344 | [source,json] 345 | ---- 346 | { 347 | "oauth2": { 348 | "enabled": true, // <1> 349 | "provider": "sip3" // <2> 350 | } 351 | } 352 | ---- 353 | <1> `enabled` - Enables OAuth2 authorization in UI 354 | <2> `provider` - OAuth2 provider in SIP3 Twig 355 | 356 | IMPORTANT: SIP3 Twig must be configured first to enable OAuth2 authentication. 357 | 358 | === Other parameters 359 | 360 | ==== root_path 361 | 362 | Root path used when Hoof is placed after proxy and have prefix in path 363 | 364 | ==== default_route 365 | 366 | Default route after successful login or going to `root_path` -------------------------------------------------------------------------------- /modules/ROOT/pages/features/HostMap.adoc: -------------------------------------------------------------------------------- 1 | = Host Map 2 | :description: SIP3 Host Map. 3 | 4 | == Overview 5 | Host Map is used to map IP addresses to named host. That helps to correlate legs to one call, aggregate all VoIP traffic going through one host, improve metrics and search abilities. 6 | 7 | Host Map page contains table with list of hosts in SIP3. 8 | 9 | image::HostMap.png[Host Map table] 10 | 11 | - `Name` - the name of the host 12 | - `Address` - IPs or IP Ranges of the host 13 | - `Feature` - the list of feature of the host. A feature has simple format: `:` 14 | - `Address mapping` - the list of address mappings 15 | 16 | - `Actions` - available actions for this type of component 17 | * image:HostEditIcon.png[Edit Host] - view and edit the Host 18 | * image:TrashBinIcon.png[Remove Host] - delete the host from Host Map 19 | 20 | === Add new host 21 | 22 | Click image:HostAddIcon.png[Add Host] to add new host. In opened window add new host in JSON format. -------------------------------------------------------------------------------- /modules/ROOT/pages/features/MediaRecordingOnDemand.adoc: -------------------------------------------------------------------------------- 1 | = Media Recording On Demand 2 | :description: SIP3 Media Recording On Demand. 3 | 4 | == Overview 5 | 6 | Here is an example of the SIP3 `Media Quality Widget` which helps to classify most of the problems within just a few seconds: 7 | 8 | image::MediaQualityWidget.png[Media Quality Widget] 9 | 10 | However, there are some situations where detailed quality analysis is still required. In such situations, VoIP engineers usually have to capture an entire call session (including RTP streams) and analyze it in Wireshark manually. 11 | 12 | Often case, capturing an entire call session is not an easy thing because of the amount of servers and VoIP traffic. To automate it and provide a better user experience the SIP3 team designed and implemented `Media Recording On Demand` feature. 13 | 14 | Let's see how you can configure a set of filters to capture entire call session (including RTP streams in `FULL` or `GDPR` modes) and analyze it later in Wireshark. 15 | 16 | == Usage 17 | 18 | Here is an example of `recording.yml` file with `Media Recording On Demand` configured: 19 | 20 | [source,yaml] 21 | ---- 22 | recording: 23 | enabled: true 24 | filters: 25 | - filter: "sip.src_addr=26.03.19.93 sip.user=desi" // <1> 26 | mode : 0 // <2> 27 | - filter: "rtp.host=RTP_ENGINE_1 rtp.r_factor<75 rtp.duration>10000" // <3> 28 | mode : 1 // <4> 29 | 30 | ---- 31 | 32 | <1> SIP signaling filter that enables recording of session from `26.03.19.93` and to or from user `desi`. 33 | <2> `FULL` mode. In this mode SIP3 will record full RTP packets including voice payload. 34 | <3> Media quality filter that enables recording of Media sessions with host `RTP_ENGINE_1`, R-Factor calculated from RTP less that 75 and duration of RTP stream more than 10000ms (10 seconds) 35 | <4> `GDPR` mode. In this mode SIP3 will record only headers of RTP packets without voice payload. 36 | 37 | WARNING: `Recording on Demand` filters from files will no longer supported be once this feature is added to the SIP3 UI. 38 | 39 | Now more about filters. 40 | 41 | == Filters 42 | 43 | The `Media Recording On Demand` feature support two types of filters: 44 | 45 | 1. `Signaling filters` - applied at the codec negotiation phase. 46 | 2. `Media filters` - applied to each periodic RTP Report handled by `Salto`. 47 | 48 | Configuration of `Media Recording On Demand` may contain multiple filters of both types. SIP3 loads and uses filters in the order defined in configuration. The first matching filter's recording mode will be applied to matched Call/Media session. 49 | 50 | === Modes 51 | 52 | Each filter controls a `Media Recording Mode`. SIP3 supports `FULL` and `GDPR` modes: 53 | 54 | [%header,cols=3*] 55 | |=== 56 | |Mode |Value |Description 57 | 58 | |`FULL` 59 | |`0` 60 | |Full RTP/RTCP and related ICMP packets with the voice payload included. 61 | 62 | |`GDPR` 63 | |`1` 64 | |Only headers of RTP/RTCP and related ICMP packets without the voice payload. 65 | |=== 66 | 67 | In addition to GDPR compliance `GDPR` mode also requires way less storage space (economy is about 75%). 68 | 69 | NOTE: Recording Mode can't be overridden for the same Media Session. 70 | 71 | === Expressions 72 | 73 | Each filter consists of one or more attributes expressions (similar to what you could see in the xref::features/AdvancedSearch.adoc#_expressions[`Advanced Search` document]) separated with a space. Attributes expressions are very simple syntactic constructions: 74 | ``` 75 | 76 | ``` 77 | 78 | SIP3 supports 3 main attributes types: `String`, `Boolean`, `Number`. In meantime each of the types support a certain list of operators: 79 | 80 | |=== 81 | |Operator | Types | Description 82 | 83 | | `=` 84 | | `String`, `Boolean`, `Number` 85 | | Equals 86 | 87 | | `!=` 88 | | `String`, `Boolean`, `Number` 89 | | Not equals 90 | 91 | | `>` 92 | | `Number` 93 | | More than 94 | 95 | | `<` 96 | | `Number` 97 | | Less than 98 | 99 | | `=~` 100 | | `String` 101 | | Regular expression 102 | |=== 103 | 104 | NOTE: A filter is matched when all attributes expressions are `True`. 105 | 106 | === "'sip'" attributes 107 | 108 | |=== 109 | |Attribute |Type |Description 110 | 111 | |`sip.src_addr` 112 | | `String` 113 | | Signaling source IP address 114 | 115 | |`sip.dst_addr` 116 | | `String` 117 | | Signaling destination IP address 118 | 119 | |`sip.addr` 120 | | `String` 121 | | Signaling source or destination IP address 122 | 123 | |`sip.src_host` 124 | | `String` 125 | | Signaling source host 126 | 127 | |`sip.dst_hodt` 128 | | `String` 129 | | Signaling destination host 130 | 131 | |`sip.host` 132 | | `String` 133 | | Signaling source or destination host 134 | 135 | |`sip.caller` 136 | | `String` 137 | | Caller 138 | 139 | |`sip.callee` 140 | | `String` 141 | | Callee 142 | 143 | |`sip.user` 144 | | `String` 145 | | Caller or Callee 146 | 147 | | Custom `sip.*` 148 | | `String`, `Boolean` 149 | | Custom xref::features/UserDefinedFunctions.adoc#_user_defined_attributes[User Defined Attribute] 150 | |=== 151 | 152 | === "`rtp`" and "`rtcp`" attributes 153 | 154 | [%header,cols=3*] 155 | |=== 156 | |Attribute |Type |Description 157 | 158 | |`rtp.src_addr`, `rtcp.src_addr` 159 | | `String` 160 | | RTP/RTCP source IP address 161 | 162 | |`rtp.dst_addr`, `rtcp.dst_addr` 163 | | `String` 164 | | RTP/RTCP destination IP address 165 | 166 | |`rtp.addr`, `rtcp.addr` 167 | | `String` 168 | | RTP/RTCP source or destination IP address 169 | 170 | |`rtp.src_host`, `rtcp.src_host` 171 | | `String` 172 | | RTP/RTCP source host 173 | 174 | |`rtp.dst_host`, `rtcp.dst_host` 175 | | `String` 176 | | RTP/RTCP destination host 177 | 178 | |`rtp.host`, `rtcp.host` 179 | | `String` 180 | | RTP/RTCP source or destination host 181 | 182 | |`rtp.mos`, `rtcp.mos` 183 | | `Float` 184 | | RTP/RTCP MoS value 185 | 186 | |`rtp.r_factor`, `rtcp.r_factor` 187 | | `Float` 188 | | RTP/RTCP R-Factor value 189 | 190 | |`rtp.duration`, `rtcp.duration` 191 | | `Integer` 192 | | RTP/RTCP media stream duration in milliseconds 193 | 194 | |`rtp.one_way` 195 | | `Boolean` 196 | | One-way RTP media stream. Please, use this attribute in combination with `rtp.duration` to make sure that RTP stream has already started some time ago. 197 | |=== 198 | -------------------------------------------------------------------------------- /modules/ROOT/pages/features/ServiceMetrics.adoc: -------------------------------------------------------------------------------- 1 | = Metrics 2 | :description: SIP3 Metrics. 3 | 4 | == Overview 5 | 6 | SIP3 uses vendor-neutral application metric facade called http://micrometer.io/[Micrometer]. It allows SIP3 to send multi-dimensional QoS metrics to the most popular monitoring systems such as CloudWatch, Datadog, Elastic, InfluxDB, New Relic, Prometheus, etc. 7 | 8 | Please read http://micrometer.io/docs[Micrometer Documentation] to get more information about basic concepts, metric types, dimensional data models and specific implementation details. 9 | 10 | == SIP Quality of Service Dashboard 11 | 12 | You can use SIP QoS Metrics to retrieve the most important QoS metrics described in RFC 6076 and build informative dashboards for monitoring and troubleshooting 13 | 14 | Datadog: 15 | image:SIPQoSMetricsDashboardDatadog.png[SIP QoS Metrics in Datadog] 16 | 17 | Grafana: 18 | image:SIPQoSMetricsDashboardGrafana.png[SIP QoS Metrics in Grafana] 19 | 20 | === Building a chart 21 | 22 | Under the hood of most charts there are simple expressions. Let's look closer to `Answer Seizure Ratio (ASR)` metric with formula: 23 | 24 | asciimath:[ASR = "Seizures resulting in answer signal"/"Total seizures" * 100] 25 | 26 | In the case of using InfluxDB and Grafana query for chart will be: 27 | [source,sql] 28 | ---- 29 | SELECT sum(Answered)/sum(Seizure)*100 FROM 30 | (SELECT sum("value") as Answered FROM "sip_call_attempts" WHERE ("state" = 'answered') AND $timeFilter GROUP BY time($__interval) fill(null)), 31 | (SELECT sum("value") as Seizure FROM "sip_call_attempts" WHERE $timeFilter GROUP BY time($__interval) fill(null)) 32 | GROUP BY time($__interval) fill(null) 33 | ---- 34 | 35 | For Datadog query is pretty simple: 36 | [source,text] 37 | ---- 38 | (sum:sip_call_attempts{state:answered}.as_count()/sum:sip_call_attempts{state:*}.as_count())*100 39 | ---- 40 | 41 | === SIP Metrics 42 | 43 | The list below contains entire set of SIP QoS metrics aggregated and reported by SIP3. You can use it to retrieve the most important QoS metrics described in RFC 6076. 44 | 45 | [%header,cols=4*] 46 | |==================== 47 | |Name 48 | |Type 49 | |Tags 50 | |Description 51 | 52 | |`sip_call_messages` 53 | |Counter 54 | |`src_host`, `dst_host`, `cseq_method`, `method`, `status_code`, `status_type` 55 | |Call messages 56 | 57 | |`sip_call_attempts` 58 | |Counter 59 | |`src_host`, `dst_host`, `state`, `error_code`, `error_type`, `expired`, `retransmits` 60 | |Call attempts 61 | 62 | |`sip_call_transactions` 63 | |Counter 64 | |`src_host`, `dst_host`, `state`, `error_code`, `error_type`, `expired`, `retransmits` 65 | |Call transactions 66 | 67 | |`sip_call_retransmits` 68 | |Counter 69 | |`src_host`, `dst_host`, `state`, `error_code`, `error_type`, `expired`, `retransmits` 70 | |Call retransmits 71 | 72 | |`sip_call_duration` 73 | |Timer 74 | |`src_host`, `dst_host`, `state`, `distribution`, `error_code`, `error_type`, `expired`, `retransmits` 75 | |Call duration 76 | 77 | |`sip_call_established` 78 | |Counter 79 | |`src_host`, `dst_host`, `retransmits` 80 | |Established calls 81 | 82 | |`sip_call_trying-delay` 83 | |Timer 84 | |`src_host`, `dst_host`, `retransmits` 85 | |The time interval between initial `INVITE` message and corresponding `100` response 86 | 87 | |`sip_call_setup-time` 88 | |Timer 89 | |`src_host`, `dst_host`, `retransmits` 90 | |The time interval between initial `INVITE` message and corresponding `18x` response 91 | 92 | |`sip_call_establish-time` 93 | |Timer 94 | |`src_host`, `dst_host`, `retransmits` 95 | |The time interval between initial `INVITE` message and corresponding `200` response 96 | 97 | |`sip_call_disconnect-time` 98 | |Timer 99 | |`src_host`, `dst_host`, `retransmits` 100 | |The time interval between the first `BYE` message and corresponding `200` response 101 | 102 | |`sip_transaction_response-delay` 103 | |Timer 104 | |`src_host`, `dst_host` 105 | |The time interval between SIP request message and corresponding response 106 | 107 | |`sip_register_messages` 108 | |Counter 109 | |`src_host`, `dst_host`, `cseq_method`, `method`, `status_code`, `status_type` 110 | |Registration messages 111 | 112 | |`sip_register_request-delay` 113 | |Timer 114 | |`src_host`, `dst_host` 115 | |The time interval between initial `REGISTER` message and corresponding `200` response 116 | 117 | |`sip_register_active` 118 | |Timer 119 | |`src_host`, `dst_host` 120 | |The amount of active registrations 121 | 122 | |==================== 123 | 124 | == Media Quality of Service Dashboard 125 | 126 | You can use RTP/RTCP Metrics and Media Metrics to retrieve the most important QoS metrics such as R-Factor, Mean Opinion Score(MOS) according to `ITU-T Recommendation G.107: The E-model: a computational model for use in transmission planning`, Jitter, etc. Creating Dashboards with this metrics helps to investigate Media issues more effectively: 127 | 128 | Datadog: 129 | image:MediaQoSMetricsDashboardDatadog.png[Media QoS Metrics in Datadog] 130 | 131 | Grafana: 132 | image:MediaQoSMetricsDashboardGrafana.png[Media QoS Metrics in Grafana] 133 | 134 | === RTP/RTCP Metrics 135 | 136 | The list below contains entire set of RTP/RTCP QoS metrics aggregated and reported by SIP3. 137 | 138 | [%header,cols=4*] 139 | |==================== 140 | |Name 141 | |Type 142 | |Tags 143 | |Description 144 | 145 | |`rtpr_rtp_mos`, `rtpr_rtcp_mos` 146 | |Summary 147 | |`src_host`, `dst_host`, `codec` 148 | |Mean opinion score 149 | 150 | |`rtpr_rtp_r-factor`, `rtpr_rtcp_r-factor` 151 | |Summary 152 | |`src_host`, `dst_host`, `codec` 153 | |R-Factor 154 | 155 | |`rtpr_rtp_duration`, `rtpr_rtcp_duration` 156 | |Timer 157 | |`src_host`, `dst_host`, `codec` 158 | |Call media duration 159 | 160 | |`rtpr_rtp_jitter`, `rtpr_rtcp_jitter` 161 | |Summary 162 | |`src_host`, `dst_host`, `codec` 163 | |Average jitter 164 | 165 | |`rtpr_rtp_expected-packets`, `rtpr_rtcp_expected-packets` 166 | |Summary 167 | |`src_host`, `dst_host`, `codec` 168 | |Expected RTP packets 169 | 170 | |`rtpr_rtp_lost-packets`, `rtpr_rtcp_lost-packets` 171 | |Summary 172 | |`src_host`, `dst_host`, `codec` 173 | |Lost RTP packets 174 | 175 | 176 | |`rtpr_rtp_rejected-packets`, `rtpr_rtcp_rejected-packets` 177 | |Summary 178 | |`src_host`, `dst_host`, `codec` 179 | |Rejected RTP packets 180 | 181 | |`rtpr_rtp_bad-reports`, `rtpr_rtcp_bad` 182 | |Summary 183 | |`src_host`, `dst_host`, `codec_name` 184 | |Number of bad reports 185 | 186 | |`rtpr_rtp_bad-reports-fraction`, `rtpr_rtcp_bad-reports-fraction` 187 | |Summary 188 | |`src_host`, `dst_host`, `codec_name` 189 | |Bad reports fraction 190 | 191 | |`rtpr_rtp_duration`, `rtpr_rtcp_duration` 192 | |Timer 193 | |`src_host`, `dst_host`, `codec_name` 194 | |RTP/RTCP stream duration 195 | |==================== 196 | 197 | == Custom Dashboards 198 | 199 | You can build custom dashboards to improve troubleshooting and monitoring. With xref::features/UserDefinedFunctions.adoc#_user_defined_attributes[User Defined Attributes], like `User-Agent` or custom `Reason` Attribute: 200 | 201 | Datadog: 202 | image:CustomMetricsDashboardDatadog.png[Custom dashboard with UDAs] 203 | 204 | -------------------------------------------------------------------------------- /modules/ROOT/pages/features/UserDefinedFunctions.adoc: -------------------------------------------------------------------------------- 1 | = User-Defined Functions 2 | :description: SIP3 User-Defined Functions. 3 | 4 | == Overview 5 | 6 | VoIP systems are very generic. Their basic call flow is strictly defined in various RFCs, however there are still a plenty of ways to customize the business logic on behalf of the protocol itself. 7 | 8 | Kamailio SIP proxy is one example of such system. It strictly follows RFC 3261. At the same time it gives you a card blanche for modifying each SIP message accordingly to your business logic. That is what makes every Kamailio configuration specific and harder for engineers to properly set granular VoIP monitoring. 9 | 10 | We designed the SIP3 platform with generic VoIP systems in mind. User-Defined Functions (UDFs) let engineers get granular monitoring data, based on various user-defined and service attributes. 11 | 12 | At the moment the SIP3 platform lets you write UDFs using Groovy. 13 | 14 | This document will walk you though the process of writing UDFs. For more information about deployment, please read the xref:InstallationGuide.adoc[SIP3 Installation Guide]. 15 | 16 | == User-Defined Function Base Structure 17 | 18 | To better understand SIP3 UDF structure let's analyze following `sip_message_udf` example: 19 | 20 | ++++ 21 |
22 | Groovy 23 | ++++ 24 | [source,groovy] 25 | ---- 26 | def eventBus = vertx.eventBus() // <1> 27 | eventBus.localConsumer("sip_message_udf", { event -> // <2> 28 | // `event.body` is a Map: 29 | // { 30 | // "src_addr" : String, 31 | // "src_host" : String (Optional), 32 | // "src_port" : Integer, 33 | // "dst_addr" : String, 34 | // "dst_host" : String (Optional), 35 | // "dst_port" : Integer, 36 | // "payload" : Map, 37 | // "attributes" : Map 38 | // } 39 | def packet = event.body() 40 | 41 | def sip_message = packet['payload'] // <3> 42 | if (sip_message['from'].matches(' 44 | } 45 | 46 | event.reply(true) // <5> 47 | }) 48 | ---- 49 | ++++ 50 |
51 | ++++ 52 | 53 | <1> Under the hood SIP3 uses https://vertx.io[Vert.x] framework which makes it very simple to write code extensions in different languages. You can find more about that in the https://vertx.io/docs/[Vert.x Documentation]. Alternatively you can copy the code snippet above and modify it according to your needs. 54 | 55 | <2> `"sip_message_udf"` is a name of the SIP3 UDF endpoint. 56 | As an input it receives a SIP3 packet with generic payload represented as a `Map`. 57 | 58 | <3> `"sip_message_udf"` endpoint receives as a payload a SIP message represented as a `Map` where keys are SIP header names and values are corresponding SIP header values. 59 | 60 | <4> In our example `robocall` is an User-Defined Attribute which is assigned to a SIP3 packet. There is no limit of the amount of user defined attributes that can be assigned to a packet. Every assigned attribute is automatically populated as a search criteria in the Advanced Search and all related Service Metrics. 61 | 62 | <5> Each UDF has to return boolean result which may be used by SIP3 Salto to define further message flow. 63 | 64 | == User-Defined Attributes 65 | 66 | As mentioned in the previous section, the main purpose of any SIP3 UDF is assigning `String` or `Boolean` attribute to a SIP3 packet according to its business logic. 67 | 68 | We call such attributes User-Defined Attributes (UDAs). Each UDA by default will be provisioned as an xref::features/AdvancedSearch.adoc#_expressions[Advanced Search expression] and as a xref::features/ServiceMetrics.adoc[Metrics tag]. 69 | 70 | However, in some cases you may want to have more control over your UDAs provisioning by using a special SIP3 UDAs syntax in attributes names. 71 | 72 | - _Database_ (*d*) - in this mode your attribute will be saved to a database and provisioned as an Advanced Search expression. 73 | - _Options_ (*o*) - enables autocompletion for Advanced Search expressions. 74 | - _Metrics_ (*m*) - in this mode your attribute will be provisioned as a Metrics tag. 75 | 76 | Let's take a closer look at provisioning modes: 77 | [source,text] 78 | ---- 79 | user_agent // <1> 80 | do:operation_system // <2> 81 | d:x_session_id // <3> 82 | m:robo_call // <4> 83 | :wangiri_candidate // <5> 84 | ---- 85 | 86 | <1> `user_agent` - The UDA with default behaviour: provisioning as the Advanced Search expression `sip.user_agent` and as the Metrics tag `user_agent`. 87 | <2> `do:operation_system` - The UDA `operation_system` will be provisioned to a database and available in the Advanced Search expression `sip.operation_system` with options for autocompletion. 88 | <3> `d:x_session_id` - `x_session_id` provisioned to a database and available in the Advanced Search expression `sip.x_session_id` without options. 89 | <4> `m:robo_call` - will be provisioned as Metrics tag `robo_call`. 90 | <5> `:wangiri_candidate` - `wangiri_candidate` will be available only in xref:features/UserDefinedFunctions.adoc[User-Defined Functions]. Neither the Advanced Search expression nor the Metrics tag will be provisioned. 91 | 92 | UDAs can bring your SIP3 experience to a next level if you follow the following rule: 93 | 94 | IMPORTANT: Always choose `String` attributes with a limited amount of possible values when you use _Options_ write mode for UDA. Otherwise, it may affect your database performance and can even bring it down. For instance, if you have a mobile application: `operation_system` or `application_version` are good choice of UDAs with _Options_. 95 | 96 | == Service Attributes 97 | 98 | Most attributes assigned within a UDF are UDAs. Along with those each UDF endpoint carries out its own set of attributes called Service Attributes. Service Attributes help resolving various call aggregation and correlation problems. 99 | 100 | SIP3 correlates same call legs by strictly matching `From` and `To` users. Now, let's imagine that you have a SIP node which receives all SIP messages containing `From` headers with US numbers in international format (`From: `). The SIP node handles SIP messages and routes them further while modifying the `From` header according to the US national number format (`From: `). Such configuration breaks the SIP3 call correlation. Fortunately, there is a solution to that problem. We can simply do a pattern matching and assign the results to the `caller` and `callee` Service Attributes defined for the `"sip_message_udf"` endpoint, as shown below. 101 | 102 | ++++ 103 |
104 | Groovy 105 | ++++ 106 | [source,groovy] 107 | ---- 108 | def eventBus = vertx.eventBus() 109 | eventBus.localConsumer("sip_message_udf", { event -> 110 | def packet = event.body() 111 | 112 | def from_header = packet['payload']['from'] 113 | def matcher = (from_header =~ /1(\d*)/) 114 | if (matcher) { 115 | packet['attributes']['caller'] = matcher[0][1] 116 | } 117 | 118 | event.reply(true) 119 | }) 120 | ---- 121 | ++++ 122 |
123 | ++++ 124 | 125 | The example above shows just a simple customization which can be done by analyzing SIP message content. However, you can build a very complex business logic using `vertx` object. Read in the https://vertx.io/docs/[Vert.x Documentation] and xref:tutorials/HowToInroduceUserDefinedAttribute.adoc[this tutorial] how to send HTTP requests or query a remote database just in a few lines of code. 126 | 127 | == Endpoints 128 | 129 | Below you can find a list of all avaialble service UDF endpoints. 130 | 131 | === `"packet_udf"` 132 | 133 | ==== 1. Description 134 | 135 | `"packet_udf"` UDF is called for every packet received by SIP3 Salto. The main purpose of this UDF is to filter duplicates (e.g. traffic sent from SIP3 Captain and Heplify can be filtered only by this function). 136 | 137 | ==== 2. Payload 138 | 139 | `"packet_udf"` UDF receives as a payload a `Map` of `src_addr`, `src_port`, `src_host`, `dst_addr`, `dst_port` and `dst_host`. 140 | 141 | ==== 3. User-Defined and Service Attributes 142 | 143 | `"packet_udf"` UDF doesn't support User-Defined and Service Attributes. 144 | 145 | ==== 4. Usage Example 146 | 147 | Following example shows how to filter traffic passing between `SBC` and `SSW` hosts: 148 | ++++ 149 |
150 | Groovy 151 | ++++ 152 | [source,groovy] 153 | ---- 154 | def eventBus = vertx.eventBus() 155 | eventBus.localConsumer("packet_udf", { event -> 156 | // `event.body` is a Map: 157 | // { 158 | // "sender_addr" : String, 159 | // "sender_host" : String (Optional), 160 | // "sender_port" : Integer, 161 | // "payload" : Map, 162 | // "src_addr" : String, 163 | // "src_host" : String (Optional), 164 | // "src_port" : Integer, 165 | // "dst_addr" : String, 166 | // "dst_host" : String (Optional), 167 | // "dst_port" : Integer, 168 | // } 169 | def packet = event.body() 170 | 171 | if (packet['sender_host'] == 'SBC' 172 | && (packet['payload']['src_host'] == 'SSW' || packet['payload']['dst_host'] == 'SSW')) { 173 | event.reply(false) 174 | } else { 175 | event.reply(true) 176 | } 177 | }) 178 | ---- 179 | ++++ 180 |
181 | ++++ 182 | 183 | === `"sip_message_udf"` 184 | 185 | ==== 1. Description 186 | 187 | `"sip_message_udf"` UDF is called for every SIP message received by SIP3 Salto. UDAs and Service Attributes assigned within the UDF are used for further registration, call aggregation and search. 188 | 189 | ==== 2. Payload 190 | 191 | `"sip_message_udf"` UDF receives as a payload a `Map` where keys are SIP header names and values are corresponding SIP header values. 192 | 193 | ==== 3. User-Defined and Service Attributes 194 | 195 | `"sip_message_udf"` UDF has no restrictions on assigning User-Defined Attributes. However, it considers `caller`, `callee` and `x_call_id` as a Service Attributes used to resolve various call correlation problems. 196 | 197 | ==== 4. Usage Example 198 | 199 | Following example shows how to define and assign `robocall` attribute: 200 | ++++ 201 |
202 | Groovy 203 | ++++ 204 | [source,groovy] 205 | ---- 206 | def eventBus = vertx.eventBus() 207 | eventBus.localConsumer("sip_message_udf", { event -> 208 | // `event.body` is a Map: 209 | // { 210 | // "src_addr" : String, 211 | // "src_host" : String (Optional), 212 | // "src_port" : Integer, 213 | // "dst_addr" : String, 214 | // "dst_host" : String (Optional), 215 | // "dst_port" : Integer, 216 | // "payload" : Map, 217 | // "attributes" : Map 218 | // } 219 | def packet = event.body() 220 | 221 | def sip_message = packet['payload'] 222 | if (sip_message['from'].matches(' 231 | ++++ 232 | 233 | === `"sip_call_udf"` 234 | 235 | ==== 1. Description 236 | 237 | `"sip_call_udf"` UDF is called for every SIP call session aggregated by SIP3 Salto. UDAs and Service Attributes assigned within the UDF are used for further registration, call aggregation and search. Also, this UDF is a perfect source of real-time CDRs. 238 | 239 | ==== 2. Payload 240 | 241 | `"sip_call_udf"` UDF receives as a payload a `Map` of session attributes. 242 | 243 | ==== 3. User-Defined and Service Attributes 244 | 245 | `"sip_call_udf"` UDF has no restrictions on assigning User-Defined Attributes. However, it considers `caller`, `callee` and `x_call_id` as a Service Attributes used to resolve various call correlation problems. 246 | 247 | ==== 4. Usage Example 248 | 249 | Following example shows how to define and assign `problematic` attribute to a call with `setup_time` greater than 5 seconds: 250 | ++++ 251 |
252 | Groovy 253 | ++++ 254 | [source,groovy] 255 | ---- 256 | def eventBus = vertx.eventBus() 257 | eventBus.localConsumer("sip_call_udf", { event -> 258 | // `event.body` is a Map: 259 | // { 260 | // "src_addr" : String, 261 | // "src_host" : String (Optional), 262 | // "src_port" : Integer, 263 | // "dst_addr" : String, 264 | // "dst_host" : String (Optional), 265 | // "dst_port" : Integer, 266 | // "payload" : Map, 267 | // "created_at" : Long, 268 | // "terminated_at" : Long, 269 | // "state" : String, 270 | // "caller" : String, 271 | // "callee" : String, 272 | // "call_id" : String, 273 | // "duration" : Long (Optional), 274 | // "setup_time" : Long (Optional), 275 | // "cancel_time" : Long (Optional), 276 | // "establish_time" : Long (Optional), 277 | // "terminated_by" : String (Optional) 278 | // "attributes" : Map 279 | // } 280 | def session = event.body() 281 | 282 | def setup_time = session['payload']['setup_time'] 283 | if (setup_time != null && setup_time > 5000) { 284 | session['attributes']['problematic'] = true 285 | } 286 | 287 | event.reply(true) 288 | }) 289 | ---- 290 | ++++ 291 |
292 | ++++ 293 | -------------------------------------------------------------------------------- /modules/ROOT/pages/tutorials/HowToBuildSip3BasedSolutions.adoc: -------------------------------------------------------------------------------- 1 | = How To Build SIP3 Based Solutions or Wangiri Fraud Detection Example 2 | :description: How To Build SIP3 Based Solutions or Wangiri Fraud Detection Example. 3 | 4 | == Overview 5 | 6 | For the last two years SIP3 has become a mission critical system for many telecom companies of different size and business verticals. 7 | 8 | The reason why it happened is very simple. The SIP3 team has been always trying to look beyond the monitoring and troubleshooting challenges. That's why we strive to help our customers stand out of their competition by finding non-standard ways of solving visibility issues. 9 | 10 | This tutorial is based on the real story of one of our customers, and outlines why and how to build SIP3 based solutions. 11 | 12 | == Use Case 13 | 14 | There was an average size VoIP provider who had around 1K Call Attempts per Second (at around 20M Call Attempts per Day). A few months ago those started growing. However, the amount of active clients stayed the same. 15 | 16 | With the growing number of Call Attempts this provider had to choose either to buy more licenses from their VoIP hardware and software vendor, or to introduce throttling policies for some of their clients. 17 | 18 | In addition, the provider started noticing more and more https://en.wikipedia.org/wiki/Phone_fraud[Wangiri (Autodialers)] fraud activities while troubleshooting support tickets. 19 | 20 | That was the moment when they came to the SIP3 team and asked if we can find all the Wangiri (Autodialers) clients and estimate their presence within the network. 21 | 22 | Let's see how did we do that. 23 | 24 | == Solution 25 | 26 | All the SIP3 solutions are based on xref:features/UserDefinedFunctions.adoc[User-Defined Functions]. In our use case, the best function to use is `sip_call_udf`. 27 | 28 | If you think about it `sip_call_udf` is nothing else but a real-time CDR which can be used to build subscriber profiles for further analysis. 29 | 30 | Let's take a closer look at a schema of our solution: 31 | 32 | image::WangiriFraudDetectionSolutionArchitecture.png[Wangiri Fraud Detection Solution Architecture] 33 | 34 | <1> A very important moment is that we won't be implementing entire solution within the `sip_call_udf`, but will send all the real-time CDRs as a Json via UDP socket. With this approach we don't need to touch the SIP3 business logic every time when we want to adjust subscriber profiles data. 35 | <2> Another good thing is that `Profiler` is just a UDP server with little business logic. It could be implemented not only in Groovy and JS, but in any language popular among of your team. 36 | <3> `CSV` is a clean and simple format integrated into most of the popular ML engines. That's why we recommend using it while prototyping. 37 | <4> Once `CSV` files are analyzed and all profile patterns are defined, you can train a `TenserFlow model` and integrate it back in your system. 38 | 39 | Now that the schema has been defined we can move forward with the implementation details. 40 | 41 | === User-Defined Function 42 | 43 | As we discussed in the previous section `sip_call_udf` will be used only to send CDRs as a Json via UDP socket. With the power of the https://vertx.io[Vert.x Framework] it can be implemented in less than 10 lines of code (excluding blank lines and comments): 44 | 45 | [source,groovy] 46 | ---- 47 | package udf 48 | 49 | import io.vertx.core.AbstractVerticle 50 | import io.vertx.core.json.Json 51 | 52 | class SipCallUdfHandler extends AbstractVerticle { 53 | 54 | def udp = vertx.createDatagramSocket() // <1> 55 | 56 | @Override 57 | void start() throws Exception { 58 | vertx.eventBus().localConsumer("sip_call_udf") { event -> 59 | // `event.body` is a Map: 60 | // { 61 | // "src_addr" : String, 62 | // "src_host" : String (Optional), 63 | // "src_port" : Integer, 64 | // "dst_addr" : String, 65 | // "dst_host" : String (Optional), 66 | // "dst_port" : Integer, 67 | // "payload" : Map, 68 | // "created_at" : Long, 69 | // "terminated_at" : Long, 70 | // "state" : String, 71 | // "caller" : String, 72 | // "callee" : String, 73 | // "call_id" : String, 74 | // "duration" : Long (Optional), 75 | // "setup_time" : Long (Optional), 76 | // "establish_time" : Long (Optional), 77 | // "terminated_by" : String(Optional), 78 | // "attributes" : Map 79 | // } 80 | def session = event.body() // <2> 81 | 82 | def buffer = Json.encodeToBuffer(session) // <3> 83 | 84 | udp.send(buffer, 15080, "127.0.0.1") {} // <4> 85 | 86 | event.reply(true) // <5> 87 | } 88 | } 89 | } 90 | ---- 91 | 92 | <1> Create UDP socket. 93 | <2> Retrieve a CDR. 94 | <3> Encode it as a Json. 95 | <4> Send it via UDP. 96 | <5> Return control back to SIP3. 97 | 98 | You can use the code snippet above in your own SIP3 solution. If you are looking for a way to send data to various databases, message brokers or HTTP webhooks check out the https://vertx.io/docs[Vert.x Documentation]. 99 | 100 | === Profiler 101 | 102 | We will skip the part of UDP server implementation because you can easily find an example of it in any programming language in the Internet. 103 | 104 | To start with, we will define a set of features we will use to certainly detect Wangiri (Autodialers) profiles: 105 | 106 | [source,kotlin] 107 | ---- 108 | class Profile { 109 | 110 | val outgoingCallStats = CallStats() 111 | val incomingCallStats = CallStats() 112 | 113 | class CallStats { 114 | 115 | var totalCalls = 0 // <1> 116 | 117 | var totalDuration = 0 // <2> 118 | var chargedMinutes = 0 119 | 120 | var failedCalls = 0 // <3> 121 | var canceledCalls = 0 122 | var answeredCalls = 0 123 | 124 | var terminatedCalls = 0 // <4> 125 | var threeSecondsCalls = 0 126 | } 127 | } 128 | ---- 129 | 130 | <1> `totalCalls` is a feature which helps to estimate subscriber's presence within the network. 131 | <2> `totalDuration` and `chargedMinutes` facilitates the calculation of an average price of call attempt. 132 | <3> `failedCalls`, `canceledCalls` and `answeredCalls` show the quality of the dialing lists. 133 | <4> `terminatedCalls` and `threeSecondsCalls` are the main features reflecting Wangiri (Autodialers) behaviour. 134 | 135 | Have a look at the example of `Profiler` implementation in Kotlin: 136 | 137 | [code,kotlin] 138 | ---- 139 | fun handleCdr(msisdn: String, callType: String, cdr: JsonObject) { 140 | val newTimeSuffix = timeSuffix.format(System.currentTimeMillis()) 141 | if (currentTimeSuffix < newTimeSuffix) { 142 | currentTimeSuffix = newTimeSuffix 143 | } 144 | 145 | val profile = profiles.getOrPut(currentTimeSuffix) { mutableMapOf() }.getOrPut(msisdn) { Profile() } 146 | 147 | val callStats = when (callType) { 148 | CallType.OUTGOING -> profile.outgoingCallStats 149 | else -> profile.incomingCallStats 150 | } 151 | 152 | callStats.apply { 153 | val duration = cdr.getInteger("duration")?.let { it / 1000 } 154 | 155 | totalCalls++ 156 | duration?.let { duration -> 157 | totalDuration += duration 158 | 159 | if (duration < 3) { 160 | threeSecondsCalls++ 161 | } else { 162 | chargedMinutes += (duration / 60) + 1 163 | } 164 | } 165 | 166 | when (cdr.getString("state")) { 167 | "failed" -> failedCalls++ 168 | "canceled" -> canceledCalls++ 169 | "answered" -> answeredCalls++ 170 | } 171 | 172 | when (callType) { 173 | CallType.OUTGOING -> if (cdr.getString("terminated_by") == "caller") terminatedCalls++ 174 | CallType.INCOMING -> if (cdr.getString("terminated_by") == "callee") terminatedCalls++ 175 | } 176 | } 177 | } 178 | ---- 179 | 180 | Once the subscriber profiles are ready we can load them in CSV files and perform the analysis. 181 | 182 | === Basic Analysis 183 | 184 | Below is the result we got from our VoIP provider - statistic of outgoing calls sorted by the amount of call attempts: 185 | 186 | image::TopProfilesByTotalCalls.png[Top Profiles By Total Calls] 187 | 188 | As you can see those profiles clearly don't belong to Wangiri (Autodialers). After a few minutes of debugging with SIP3 we figured out that the growing amount of Call Attempts was caused by UAC misconfigurations. 189 | 190 | We notified the VoIP provider and their problem with hardware and software capacity got resolved. However, we were still curious to find out if it's possible to detect Wangiti (Autodialers) profiles. 191 | 192 | Let's look at the same statistics of outgoing calls but this time sorted by the amount of calls shorter than 3 seconds: 193 | 194 | image::TopProfilesByThreeSecondsCallsRate.png[Top Profiles By Three Seconds Calls Rate] 195 | 196 | It seems that we've got a clear pattern of Wangiri (Autodialers) profiles. The majority of calls are cancelled while the rest lasted less than 3 seconds and got terminated by the caller. 197 | 198 | All left to do is to train and integrate a TenserFlow model. 199 | 200 | == Conclusions 201 | 202 | The SIP3 team considers this tutorial not a step-by-step how-to but a motivation for our community to start using the SIP3 advanced features. 203 | 204 | We hope you now have some clues and maybe even ideas about SIP3 based solutions you would like to have in your VoIP network. 205 | 206 | We would love to hear back from you! Share your thoughts with us in our https://join.slack.com/t/sip3-community/shared_invite/enQtOTIyMjg3NDI0MjU3LWUwYzhlOTFhODYxMTEwNjllYjZjNzc1M2NmM2EyNDM0ZjJmNTVkOTg1MGQ3YmFmNWU5NjlhOGI3MWU1MzUwMjE[Slack] or https://t.me/sip3io[Telegram] community channels. -------------------------------------------------------------------------------- /modules/ROOT/pages/tutorials/HowToInroduceUserDefinedAttribute.adoc: -------------------------------------------------------------------------------- 1 | = How To Introduce a User-Defined Attribute or Integration with APIBAN Example 2 | :description: SIP3 How To Introduce a User-Defined Attribute Tutorial or Integration with APIBAN Example. 3 | 4 | == Overview 5 | 6 | With SIP3 you can search for calls and build metric dashboards based on a set of defined criteria. 7 | 8 | For instance, you can find all calls sent though particular SIP trunk, filter them by state and check which of those had problems with setup time, like it's shown on the picture below: 9 | 10 | image::CallSetupTroubleshootingByTrunk.png[Troubleshooting Example] 11 | 12 | We call each of the criteria above Service Attributes. They are assigned automatically by SIP3 to each call. You can also use those attributes for building metric dashboards: 13 | 14 | image::CallSetupStatisticByTrunk.png[Statistic Example] 15 | 16 | Service Attributes can help you troubleshoot and address various problems. That, however, is not enough to cover different traffic profile use cases. 17 | 18 | In this tutorial we will define a specific use case, introducing a User-Defined Attribute, and learn how to use it later. 19 | 20 | == Use Case 21 | 22 | Everyone in the VoIP community knows https://twitter.com/fredposner[Fred Posner] as a great VoIP engeener and very talented baker. 23 | 24 | Awhile back Fred introduced a new community-driven service called https://apiban.org[APIBAN]. A platform for sharing and retrieving a list of fraud IP addresses. 25 | 26 | APIBAN is integrated with https://apiban.org/doc.html#kamailioex[Kamailio] and https://apiban.org/doc.html#iptablesex[iptables] which makes it possible to automatically update firewall rules and block any fraud attempts. 27 | 28 | Unfortunately, as with any other open source platform, APIBAN's data may be compromised. Thus, the need of a verification via another service. 29 | Thanks to the SIP3 architecture design you can have a monitoring set in place that works in front of iptables. 30 | So even if the traffic has been blocked you will still be able detect fraud attempts and whitelist wrongly blocked IP addresses. You will also: 31 | 32 | * see statistics of fraud attempts and determine the size of a fraud attack 33 | * analyze SIP messages retrieved from blacklisted IPs 34 | * be able to find a similar fraud attempts pattern in your own traffic from addresses that are not yet added to your blacklist. 35 | 36 | Let's see how this works in action! 37 | 38 | NOTE: Before you start, make sure you get yourself familiar with the concept of xref:features/UserDefinedFunctions.adoc[User-Defined Functions]. 39 | 40 | For this use case we will introduce two User-Defined Attributes: `blocked` as a Boolean and `blocked_addr` as a String. 41 | The first one will let us search for all calls originated from blacklisted IPs while the second one will show us more detailed information per IP. 42 | 43 | == User-Defined Function 44 | 45 | NOTE: The SIP3 team recommends you to use https://www.jetbrains.com/idea[InteliJ IDEA]. 46 | Just clone the https://github.com/sip3io/sip3-salto-ce[SIP3 Salto] project, open it in your IDEA, create `.groovy` file within the project and take an advantage of syntax highlight and autocomplete. 47 | 48 | The use case, we are going to implement, is a bit more complex. 49 | However, it's enough to just go though the https://vertx.io/docs/vertx-core/groovy[Vert.x Documentation] to understand the logic behind the code snippet below: 50 | 51 | [source,groovy] 52 | ---- 53 | class ApiBanUdfExample extends AbstractVerticle { // <1> 54 | 55 | private final APIBAN_URL = 'https://apiban.org/api/%API_KEY%/banned' 56 | 57 | private Set blocked = [] 58 | 59 | @Override 60 | void start() throws Exception { 61 | vertx.eventBus().localConsumer("sip_message_udf") { event -> // <2> 62 | def packet = event.body() 63 | 64 | if (blocked.contains(packet['src_addr'])) { 65 | packet['attributes']['blocked'] = true 66 | packet['attributes']['blocked_addr'] = packet['src_addr'] 67 | } 68 | 69 | event.reply(true) 70 | } 71 | 72 | asyncUpdateBlocked() // <3> 73 | } 74 | } 75 | ---- 76 | 77 | <1> Don't be confused by the fact that our code doesn't look like a Groovy script from xref:features/UserDefinedFunctions.adoc[User-Defined Functions] document. 78 | This is because every SIP3 User-Defined Function is a verticle which can be written in https://vertx.io/docs/vertx-core/groovy/#_writing_verticles[multiple ways]. 79 | We've chosen to extend the `AbstractVerticle` class because it gives more control on the IDEA level. 80 | <2> This part is a very simple and looks exactly like any Groovy script from xref:features/UserDefinedFunctions.adoc[User-Defined Functions] document. 81 | In our case, we will analyze packet's `src_addr` attribute. If this attribute is found in the `blocked` set we will assign the User-Defined Attributes stated above. 82 | <3> To update the `blocked` list we need to call APIBAN API. The `asyncUpdateBlocked` method is pretty big. That's why you can find it in a separate code snippet below: 83 | 84 | [source,groovy] 85 | ---- 86 | private void asyncUpdateBlocked(String controlId) { 87 | def url = controlId ? "$APIBAN_URL/$controlId" : APIBAN_URL // <1> 88 | 89 | WebClient.create(vertx).getAbs(url).send { asr -> 90 | if (asr.failed()) { 91 | vertx.setTimer(5 * 60000) { 92 | asyncUpdateBlocked() 93 | } 94 | return 95 | } 96 | 97 | def response = asr.result().bodyAsJsonObject() 98 | def id = response.get('ID') as String 99 | def addresses = response.get('ipaddress') as ArrayList 100 | 101 | blocked.addAll(addresses) // <2> 102 | 103 | if (addresses.size() == 250) { 104 | asyncUpdateBlocked(id) // <3> 105 | } else { 106 | vertx.setTimer(5 * 60000) { // <4> 107 | asyncUpdateBlocked(id) 108 | } 109 | } 110 | } 111 | } 112 | ---- 113 | <1> When SIP3 is just started we don't have an APIBAN control ID. That's why we will use a generic API method to get the first bulk of the blacklisted IPs. 114 | Otherwise, we will use control ID to get the next bulk. You can find more information about this in the official https://apiban.org/doc.html#banned[APIBAN Documentation]. 115 | <2> Once the HTTP request retuns a list of blacklisted IPs we will add them to the `blocked` set. 116 | <3> If the amount of returned IPs equals 250 (which is a bulk size) we will do the following API call using the control ID immediately. 117 | <4> Otherwise, we will be checking every 5 minutes for new portion of the blacklisted IPs. 118 | 119 | That's it! Our User-Defined Function is ready. Check out the xref:InstallationGuide.adoc[Installation Guide] for more instructions on how to deploy it. 120 | 121 | == Real Life Example 122 | 123 | In order to make this use case more interesting and show you real data, we agreed to deploy the User-Defined Function from above to one of our customers who wasn't sure if they are experiencing fraud attacks. 124 | 125 | As soon as it was deployed we built a metric dashboard using the `blocked` attribute. Here is what we've got: 126 | 127 | image::DashboardForCallAttemptsBlockedByApiban.png[Dashboard For Call Attempts Blocked By APIBAN] 128 | 129 | As you can see there is a good amount of fraud attempts blocked by the list of IPs retrieved from APIBAN API. Let's see what are those: 130 | 131 | image::SearchForCallAttemptsBlockedByApiban.png[Search For Call Attempts Blocked By APIBAN] 132 | 133 | Now let's see how many blacklisted IPs are attacking the customer's VoIP servers: 134 | 135 | image::ShowIpListBlockedByApiban.png[Show IP List Blocked By APIBAN] 136 | 137 | After seeing this data, our customer decided to leave the SIP3 integration with APIBAN working, hoping that the APIBAN database will keep expanding in future and help more businesses like his. 138 | 139 | == Minimizing VoIP fraud attempts with SIP3 140 | 141 | As the VoIP fraud attempts have begun to rise in the last few years, it is important to understand how you can minimize the impact they have on your business. 142 | 143 | While it might be difficult to prevent VoIP fraud from happening, the right tools in place could help you reduce your chances of becoming a victim. Why to wait for fraud attacks to effect your business when SIP3 can give you 360-degree service visibility? 144 | --------------------------------------------------------------------------------