on - edited on by
Kyzer Davis (kydavis)
- Introduction
- User Guide
- Finding theSIP Profile Tester (SPT) Tool
- Using the SIP Profile Tester Tool (SPT)
- SIP Profile Tester (SPT) Example
- Examining the SPT Results
- SIP Profile Documentation
- Development and Feedback
- Disclaimers
Introduction
Cisco Unified Border Element (CUBE) features a rich and powerful command set called "SIP Profiles" which allow an administrator the ability to modify, add, remove or copy elements of a SIP header or SDP Body from requests or responses. These rules can be configured for many scenarios; for example, to add a specific header required by a peer device, remove a problematic header to workaround an issue or modify a value not configurable by other command line interface (CLI) methods.
The sheer number of permutations and complexity of SIP Profile configuration means that administrators required a way to test and validate the regex and logic will not cause more harm than help.
That is where the SIP Profile Tester (SPT) tool features within Collaboration Solution Analyzer (CSA) comes into play. This SIP Profile Tester tool allows an administrator to simulate SIP Profile rule logic on real SIP messages. The outputs can then be examined by to determine if the rules logic is satisfactory or if continued iteration of the rule logic is required. All without ever touching production traffic.
The net benefit is that administrators can apply or modify rules with confidence that a change will not cause a P1 outage. Further, an administrator does not need to simulate in a lab and/or open a TAC case to have an expert review. This saves time for customers, partners and Cisco.
User Guide
Finding the SIP Profile Tester (SPT) Tool
- External Tool: https://cway.cisco.com/csa-new/#/sipprofiletest
The tool can be found from the CSA homepage by selecting the "Validate SIP Profile Configs" option in the card.
Using the SIP Profile Tester Tool (SPT)
The tool itself has 3 main text inputs:
- SIP Profile Rules: This required field will contain one or more SIP profile rule configurations which an admin wishes to test.
- SIP Message To Test Rules On: This required field is where an admin will enter a SIP message to test.
- Peer SIP Message To Copy From: This is an optional item only required when an admin wishes to test profiles that use the "peer-header" keyword. e.g. copylist configuration where headers are passed from one call-leg to the other call-leg. Note, if the word "peer" appears in the sip profile rules this input will change to required
SIP Profile Tester (SPT) Example
A very common scenario is to work on a Diversion header within a SIP INVITE.
The rule below will modify a diversion header so that the user portion of the SIP URI is converted from 4 digits to 10 digits with the "\1" being the first group of parenthesis.
For regex logic, please refer to https://regex101.com/
The example regex in the modify statement can bee viewed here: https://regex101.com/r/0g8XPq/1
1. SIP Profile Rules:
rule 1 request ANY sip-header Diversion modify "sip:(.*)@" "sip:111222\1@"
2.SIP message to apply rules
INVITE sip:8675309@172.18.110.58:5060 SIP/2.0
Via: SIP/2.0/UDP 172.18.110.65:5060;branch=z9hG4bK-1972256-1-0
From: sipp <sip:1234@172.18.110.65:5060>;tag=1
To: sut <sip:kydavis@172.18.110.58:5060>
Call-ID: 1-1972256@172.18.110.65
CSeq: 1 INVITE
Contact: sip:sipp@172.18.110.65:5060
Max-Forwards: 70
Diversion: <sip:5100@10.10.10.10>
Example Output:
Examining the SPT Results
After selecting "apply" a the SPT tool will show multiple entries:
1. Original SIP Message: For the sake of "stare and compare" the original message is included on the left pane.
2. Modified SIP Message: The final result of the SPT simulation will be shown in the right pane.
3. Copy Registers: If using copy rules, a list of register: value entries is provided to help determine if the expected data is being copied to a variable.
4. Logs: The action, before, after and rule are listed in a table. This is to help an admin debug. This may also have information messages or exceptions encountered while parsing the input rules or messages.
5. Errors: If there are any errors found while parsing the SIP message or the SIP Profile Rules. Those will be shown as a final table at the end.
Highlighting of the Original/Modified SIP Message results:
- Modified SIP Headers or SDP Body will be highlighted blue in both message areas.
- Added SIP Headers or SDP Body will be highlighted green in the Modified SIP message result only.
- Removed SIP Headers or SDP body will be highlighted red in the original SIP message result only.
An example of the modify/add/remove highlighting can be seen below:
Note: If the SDP Body is modified, the content-length header will be modified to account for the new SDP Body length. While this does not highlight in the original/modified window an INFO log is provided describing this behavior.
Loading prebuilt rules and messages
SPT makes prebuilt rules available via a dropdown selector above the SIP Profile Rules input.
These cover basic features such as adding/removing/modifying headers, copying from the input message, copying from the peer message and even more advanced features such as CSEQ based method modifications or mline-index based modifications. Further, some of the more common profile types have been includes as scenarios.
Further, various sample SIP message request/response have been included as selectable options in the dropdown above the SIP Message To Test Rules On input. These feature interesting headers and SDP Body (audio/video/app/mime/t38) built around the prebuilt SIP profile Rules.
These rules and messages can be a good starting point to learn SIP profiles or used to start building your next custom rule.
 |
 |
SIP Profile Documentation
There are a plethora of places to review SIP Profile logic and documentation. Some samples are provided below.
- Cisco IOS XE 17.6 Onwards
- Cisco IOS XE 17.5 and Older
- Use SIP Profiles on CUBE Enterprise Common Use Cases
- IOS-XE Call Routing - SIP Profiles
- https://www.youtube.com/watch?v=oFicL8yJUG4&ab_channel=Cisco
Development and Feedback
The original SPT tool has been deprecated as of 2023: https://www.cisco.com/c/en/us/support/web/retired-tools.html
Feedback can be submitted via the "Report Problem" button in the top right header of CSA.
Please include the following when submitting an issue involving IOS or Regex Logic:
- Full SIP Message(s) being used
- SIP Rule(s) being tested
- Expected Results (If possible, with supporting debug logic from CUBE on the latest version of XE code.)
debug ccsip mess
debug ccsip info
debug ccsip feature sip-profile
Disclaimers
- The SPT script simulates SIP Profile logic used by the most up-to-date version of IOS XE / CUBE and the rule logic is tested against only that version. Read: There is no ability to test rule logic for specific X version of XE code.
- There may be features supported by SPT that are not supported by a specific release. It is up to the administrator to review the official documentation and understand if a SIP Profile feature / command set is available in the desired version.
- All simulation and testing for underlying script logic is performed in a controlled lab environment using a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command and the effect other commands may have on the SIP Profile feature.
Hello All,
The old SIP Profile Tester tool has been retired. See: https://www.cisco.com/c/en/us/support/web/retired-tools.html
The good news is that we have published a new, updated, version of the tool as part of Cisco Collaboration Solutions Analyzer (CSA).
The new tool can be found at the following link: https://cway.cisco.com/csa-new/#/sipprofiletest
Sample Screenshot:
I'm trying to create a Diversion header based on the number in the From field but the tool keeps erroring with "bad escape \x at position"
I modified the profile from "Example: Create a Diversion header depending on the area code" of the CUBE guide:
When I drop in the exact same rule from the guide example, the tool still gives the error. Is something missing?
Attached images are the outputs from my modified rule and the guide's original rule.
I'm not getting any output in the "Modified SIP message" field after running the apply rules.
The "Original message" field displays the SIP message inputted but nothing for anything else, see screenshot.
I've tried different browsers, accepted all cookies, clearing the cache and using InPrivate/Incognito but all with same issue.
@Edward Lau, I am aware of the the "blank modified sip message" output error. I fixed it recently while implementing new features and re-working the GUI for the July Update.
Coincidentally the new SPT update should be live soon externally in CSA.
You will know it is live when you see the GUI look like the screenshots below. Please test your profile again when the new update is live. I will edit this message when I know the team has pushed the update but for now I have compiled the release notes below.
Edit 7/15/2024: Update is live!
---
July Update
Input Changes:
- Better input descriptions, placeholder text and input help with links to CUBE documentation.
- Peer header input is renamed to better describe its usage and is now collapsed by default but can be toggled with the "show peer header input" button. Input help and placeholder text was added to detail that it is only required for "peer-header" type rules. Note, will change to required if a peer-header rule is detected in the input rules area.
Results Changes:
- Inputs are now hidden but can be re-opened to tweak rules and rerun the test by clicking the "show inputs" button.
- Line numbers have been added to the SIP Message areas. A button will toggle these if you do not want them in a screenshot.
- Change Highlighting
- Modified SIP Headers or SDP Body will be highlighted blue in both message areas.
- Added SIP Headers or SDP Body will be highlighted green in the Modified SIP message result only.
- Removed SIP Headers or SDP body will be highlighted red in the original SIP message result only.
- Copy register area will not show if copy rules are not in use. Otherwise no changes.
- Logs have been overhauled to show action, before, after, and the rule that was applied
- Logs will also show INFO messages such as when an SDP body is modified the content-length header will be re-calculated to account for the new length. This will not highlight blue but the logs table will detail this change since this is something CUBE will do.
- Errors: Where possible I tried to ensure errors report something useful and do not block execution of further rules (like could sometimes be seen with the modified output being empty.)
New: prebuilt rule scenarios and test messages:
I hand crafted 26 rule scenarios comprising of 164 various rule combinations that cover about anything one can do with a SIP profile. These prebuilt selections are available via a dropdown selector above the SIP Profile Rules input.
These cover basic features such as adding/removing/modifying headers, copying from the input message, copying from the peer message and even more advanced features such as CSEQ based method modifications or mline-index based modifications. Further, some of the more common SIP profile usages have been includes as scenarios.
Finally, various sample SIP message request/response have been included as selectable options in the dropdown above the SIP Message To Test Rules On input. These messages feature interesting headers and SDP Body (audio/video/app/mime/t38) built around the prebuilt SIP profile Rules.
These prebuilt rules and messages can be a good starting point to learn SIP profiles or used to start building your next custom rule.
Dropdowns in the update:
 |
 |
New: Error Reporting
You should also be able to report errors through the "Report Problem" button now.
Final Notes:
In preparing this release I ended up testing and debugging 180+ SIP Profile scenarios against a real IOS XE 17.14 CUBE in the lab. I then compared those results to the output of SPT to ensure things are as 1:1 with real CUBE as possible. As such this release fixes a number of corner case issues I found with SPT logic between now and the June 18th release.