Fixing SIP Problems with UC Manager's SIP Normalization Tools

Fixing SIP Problems with UC Manager's SIP Normalization Tools Mark Stover, CCIE #6901 Collaboration Consulting SE

Why have this session? More systems than ever use SIP Last count was 107 Products on SIP Wikipedia Page Google Search for SIP Server yields 16 Million Hits increase of almost 400% in 2 years Many of the SIP bits don t quite match up Hence, the need for Interoperability events Things in the real world don t go the way of data sheets and Interoperability Forums! 3

What this Session is About Fact 1: SIP is a Standard Fact 2: SIP Configurations are not standardized Which headers are included Format of data in headers (URIs, etc.) Ordering of header fields Contents of the SIP Message Body What do we do when Fact #1 and Fact #2 are at odds in our deployment? We have tools in our toolbox: Unified CM s SIP Transparency and Normalization CUBE s SIP Profiles 4

Typical Interop Scenario 5

Agenda Introduction (Very) Brief Review of SIP When Things Don t Work Overview of SIP Normalization Methods Using Unified CM Normalization Scripts Using IOS SIP Profiles Normalization Case Studies Conclusion Appendix (Info on Lua Programming) 9

Brief Review of SIP

Basic Design SIP is a Client-Server Protocol Clients send requests, receive responses Servers receive requests, send responses Modeled after HTTP Text Encoded Protocol Client request Server Each request invokes method on server Main purpose of request response Messages contain bodies 11

SIP Methods and Messages Call signaling performed by SIP Methods Six Original SIP Methods: INVITE ACK OPTIONS BYE CANCEL REGISTER SIP Messages have distinct parts: IP/TCP/UDP Envelope SIP Header SIP Message Body MIME-Encoded Session Description Protocol (SDP) May contain other data 12

SIP Methods INVITE Invites a participant to a session idempotent - reinvites for session modification BYE Ends a client s participation in a session CANCEL Terminates a search For Your Reference OPTIONS Queries a participant about their media capabilities, and finds them, but doesn t invite PING identifies reachability ACK For reliability and call acceptance REGISTER Informs a SIP server about the location of a user 13

SIP Message Syntax Many header fields from http Payload contains a media description SDP Session Description Protocol INVITE sip:alice@company.com SIP/2.0 From: Bob <sip:bob@university.edu> To: Alice <sip:alice@company.com> Via: SIP/2.0/UDP pc.university.edu Call-ID: 199723450578@192.169.100.100 Content-type: application/sdp CSeq: 4711 INVITE Content-Length: 187 v=0 o=ccm-sip 2000 1 IN IP4 192.168.100.100 s=sip Call c=in IP4 192.168.200.200 m=audio 26542 RTP/AVP 0 8 18 101 a=rtpmap:0 PCMU/8000 a=ptime:20 a=mid:1 c=in IP6 2001:0db8:aaaa::0987:65ff:fe01:234b m=audio 26662 RTP/AVP 0 a=mid:2 14

Negotiating the Session Called party receives SDP offered by caller Each stream can be accepted rejected Accepting involves generating an SDP listing same stream port number and address of called party subset of codecs from SDP in request Rejecting indicated by setting port to zero Resulting SDP returned in 200 OK Media can now be exchanged For Your Reference Audio stream accepted, PCMU only Video stream rejected, Port 0 v=0 o=user2 16255765 8267374637 IN IP4 4.3.2.1 t=0 0 m=audio 3456 RTP/AVP 0 c=in IP4 4.3.2.1 m=video 0 RTP/AVP 86 c=in IP4 4.3.2.1 15

SIP Responses Look much like requests Headers, bodies Differ in top line Status Code Numeric, 100-699 Meant for computer processing Protocol behavior based on 100s digit Other digits give extra info Reason Phrase Text phrase for humans Can be anything 16 Status Code Classes 100-199 (1XX): Informational 200-299 (2XX): Success 300-399 (3XX): Redirection 400-499 (4XX): Client Error 500-599 (5XX): Server Error 600-699 (6XX): Global Failure Two groups 100-199: Provisional (Not reliable) 200-699: Final, Definitive Example 200 OK 180 Ringing

SIP Transactions Fundamental unit of messaging exchange Request Zero or more provisional responses Usually one final response Maybe ACK All signaling composed of independent transactions Transactions identified by Cseq Sequence number Method tag 17

When things don t work

Identifying A Problem Goal is to make two SIP systems talk Both systems already configured with: Appropriate Network Configurations Trunk configuration to reach the other system Routing (dial plan) information in place Make a call From: 1001 on System A; To: 2001 on System Z Both phones exist, are configured, and are able to make other calls And wait 19

Symptoms Possible failure modes: Wait forever and get fast busy Call rejected right away Calls work, but other services (e.g. MWI) fail These can be symptoms of numerous problems No bandwidth No DNS Bad Codecs SIP Header Mismatches Etc. Unfortunately, it will take some troubleshooting to isolate the issue 20

Gather Information Logs are good: Will help you determine if SIP is the problem May not reflect what is really on the wire May not include the header level detail Packet Capture is your friend Various ways to gather traces Further discussion just ahead Review Paul Giralt s SIP Troubleshooting session for many more details: BRKUCC-2932 Troubleshooting SIP with Cisco Unified Communications It was scheduled for Tuesday Afternoon 21

Getting SIP Messages Three main sources of SIP Message Information 1. Unified CM Trace Files 2. Unified CM Network Capture utils network capture 3. Cisco IOS Packet Capture IP Traffic Capture Feature 4. Network Packet Capture (Wireshark) 22

Example of Unified CM Trace File 17:38:59.871 //SIP/SIPTcp/wait_SdlReadRsp: Incoming SIP TCP message from 192.168.100.100 on port 65067 with 1872 bytes: INVITE sip:4125551212@192.168.200.200:5060 SIP/2.0 Via: SIP/2.0/TCP 192.168.100.100:5060;branch=z9hG4bK1266281727 From: "Alice" <sip:918145551212@192.168.100.100>;tag=3e6d44cc-ce4 To: <sip:4125551212@192.168.200.200> Date: Wed, 12 Oct 2011 21:38:59 GMT Call-ID: 6E2FCA41-F45111E0-95FBF44A-5979DA79@192.168.100.100 Supported: 100rel,timer,resource-priority,replaces,sdp-anat Cisco-Guid: 1847785776-4098953696-3044132940-1967707264 User-Agent: Cisco-SIPGateway/IOS-12.x CSeq: 101 INVITE Timestamp: 1318455539 Expires: 180 Allow-Events: telephone-event Content-Type: multipart/mixed;boundary=uniqueboundary Mime-Version: 1.0 Content-Length: 929 --uniqueboundary Content-Type: application/sdp Content-Disposition: session;handling=required v=0 o=ciscosystemssip-gw-useragent 4535 5918 IN IP4 192.168.100.100 s=sip Call c=in IP4 192.168.100.100 t=0 0 m=audio 17620 RTP/AVP 0 100 101 c=in IP4 192.168.100.100 a=rtpmap:0 PCMU/8000 23

Using Unified CM Network Capture admin:utils network capture size 1500 port 5060 file testsipcap verbose Executing command with options: size=1500 count=1000 interface=eth0 src= dest= port=5060 ip= admin:file list activelog platform/cli/ testsipcap.cap dir count = 0, file count = 1 admin:file get activelog platform/cli/testsipcap.cap Please wait while the system is gathering files info...done. Sub-directories were not traversed. Number of files affected: 1 Total size in Bytes: 6040 Total size in Kbytes: 5.8984375 Would you like to proceed [y/n]? y SFTP server IP: 192.168.101.101 SFTP server port [22]: User ID: admin Password: ******** Download directory: Downloads. Transfer completed. 24

Using Wireshark 25

Determine Needed Results 1. Make calls in both directions: Get SIP Captures of test calls in both directions 2. Traces may give you a clue: Mismatch in domain names No domain in one direction Mailbox you want is last redirect instead of first in list 3. May have to research each system s SIP trunk requirements Compare it to the other vendor s normal operation 4. Use your research and troubleshooting to determine the fix: Change the domain name of messages from incorrectly configured system Add a missing domain Remove headers that cause a failure 26

Write, Test, and Deploy Use the desired result to formulate a plan Configure SIP Normalization to process appropriate headers Test against traffic on a SIP trunk that does not carry production traffic Deploy to production trunk and verify 27

SIP Transparency & Normalization vs. IOS SIP Profiles

SIP Transparency & Normalization Unified CM s Normalization Tool Provide an interface for customization of SIP messages Initially conceived for Cisco Unified CM Session Management Edition (SME) Also supports Cisco Unified Communications Manager without SME Available in Release 8.5 and later Include: A Lua execution environment SIP Transparency & Normalization APIs Support: Transparent passing of SIP information from one call leg to another Normalizing SIP Messages to provide interoperability 29

IOS SIP Profiles Unified Border Element s (CUBE) Normalization Tool Key Cisco Unified Border Element (CUBE) function Customize SIP messaging to enable session negotiation with SIP Service Provider (to meet policy and security needs) Resolve incompatibilities between SIP devices inside the enterprise network Use IOS feature navigator to confirm minimum version requirements First available in IOS 12.4.15XZ Inbound SIP Profiles available in IOS 15.4.2T Uses regular expressions to match and replace fields in SIP messages 30

Normalization Comparison What s the difference between SIP Profiles and SIP T&N Feature IOS SIP Profiles SIP T&N Platform CUBE Unified CM Outbound Messages Yes Yes Inbound Messages Yes (15.4.2T) Yes Transparency No Yes Programmability Match & Replace Lua Scripting Matching RegEx (egrep) Lua Matching (globbing) Conditionals & Loops No Yes Headers Yes Yes Message Body SDP Only Any

Overview of SIP Transparency & Normalization

SIP Transparency Unified CM is a Back to Back User Agent (B2BUA) In a Session Management role, Unified CM will (by default ) insert itself in the call Will become the call agent for next leg Will remove any unsupported headers on the next leg Transparency allows SIP information to be passed from one call leg to another What that means? Transparency allows 3rd-Party Headers to pass through Unified CM 34

What can a transparency script do? To provide transparency, the script has to pass SIP information Almost any information in a SIP message can be passed through Currently, SIP Transparency can manage: SIP headers SIP parameters Content bodies 35

SIP Normalization The process of transforming inbound and outbound SIP messages Inbound normalization makes the SIP message useable by Unified CM For Example, how can we handle SIP redirecting numbers? Unified CM uses the Diversion header for redirecting number(s) Other SIP devices use the History-Info header for this purpose Normalization can transform History-Info headers into Diversion headers Outbound normalization makes the SIP message useable by another SIP device Use normalization to transform Unified CM s Diversion headers into History-Info headers for another SIP PBX 36

What can a normalization script change? Manipulate almost every aspect of a SIP message Currently, SIP Normalization can change: The request URI The response code and phrase SIP headers SIP parameters Content bodies SDP 37

Normalization Script Examples Reorder codecs in the SDP of an early offer Remove specific headers such as Cisco-Guid Mask the number to E.164 in a Diversion header to meet Service Provider requirements Fix the domain name of a system with the wrong one using a configured parameter in Unified CM Convert IP addresses to domain names Add content to the SIP Message Body 38

Case Study-Problem Statement Customer has several PBXs trunked to a Unified CM cluster Unified CM SIP trunked to a 3rd-party voice mail system After multiple call forwards, some calls are sent to voice mail Most calls go to the correct voice mail box Calls from one PBX did not In the broken case: Reaching the greeting for the station that finally forwarded the call to voice mail Not reaching the voice mail of the station originally called Will solve this problem with SIP Normalization in just a little while 39

Overview of SIP Profiles Normalization

IOS SIP Profiles Unified Border Element s (CUBE) Normalization Tool CUBE supports normalization of SIP messages Includes add/remove/modify/copy of headers in a SIP message SIP Profiles feature added in 12.4(20)T and enhanced in 15.1(3)T and 15.4(1)T Inbound SIP Profiles available in IOS 15.4(2)T Inbound normalization takes place before regular SIP call processing CUBE acts as if it directly received the normalized message 41

IOS SIP Profile Uses Situations that IOS SIP Profiles can address Device rejects an unknown (IOS) header instead of ignoring it Device sends incorrect data in a SIP message For example, uses internal extension instead of E.164 number Device does not implement (or implements incorrectly) protocol procedures Device expects an optional header value or parameter that can be implemented in different ways Device sends a value or parameter that must be changed (or suppressed) before it leaves or enters the network Variations in the SIP standards on how to achieve certain functions 42

What can SIP Profiles normalization change? Add, modify, remove or copy any SIP or SDP header value in a SIP message SIP Profiles does not allow you to remove or add mandatory SIP headers Only the modify option is available for mandatory headers Mandatory SIP headers include: To From Via Cseq Call-Id Max-Forwards Mandatory SDP headers include v, o, s, t,c, and m 43

Case Study-Problem Statement Customer has SIP trunks configured to the SIP service provider Unified CM configured to turn 4-digit extension into a valid E.164 number Dialed calls to the PSTN are completed Calls forwarded to PSTN fail Will solve this problem with SIP Profiles 44

Using Unified CM Normalization Scripts

Putting SIP Normalization to Work Using message handlers to manipulate SIP messages Message Handler name tells you: When the Handler will be invoked What type of message the Handler is for You want your script to process INVITEs received by Unified CM: Script should have an inbound_invite message handler Corresponding message handler invoked anytime an inbound INVITE is received A single parameter called msg represents the SIP Message in script Scripts use Cisco SIP Message API library to access and manipulate the msg parameter Let s try looking at a diagram 46

How a Normalization Script Gets Run 47

How a Normalization Script Gets Run 48

How a Normalization Script Gets Run 49

How a Normalization Script Gets Run 50

How a Normalization Script Gets Run 51

How a Normalization Script Gets Run 52

How a Normalization Script Gets Run 53

How a Normalization Script Gets Run 54

Let s Start with a Simple Script Need to convert incoming History-Info headers into Diversion headers Script will run when Unified CM receives an INVITE Need to remove Cisco-Guid from outgoing headers Script will run when Unified CM sends an INVITE 55

Our First SIP Normalization Script M = {} function M.inbound_INVITE(msg) msg:converthitodiversion() end function M.outbound_INVITE(msg) msg:removeheader("cisco-guid") end return M 56

Focus on SIP Normalization Script - 1 M = {} Creates an empty Lua Table called M for all Handlers M is also the name of the Lua Module function M.inbound_INVITE(msg) msg:converthitodiversion() end function M.outbound_INVITE(msg) msg:removeheader("cisco-guid") end return M 57

Focus on SIP Normalization Script - 2 M = {} function M.inbound_INVITE(msg) msg:converthitodiversion() end Inbound INVITE Message Handler Inbound SIP Message accessed through msg Invokes an API call to perform the actual conversion function M.outbound_INVITE(msg) msg:removeheader("cisco-guid") end return M 58

Focus on SIP Normalization Script - 3 M = {} function M.inbound_INVITE(msg) msg:converthitodiversion() End function M.outbound_INVITE(msg) msg:removeheader("cisco-guid") end Outbound INVITE Message Handler Outbound SIP Message accessed through msg Invokes API call to remove a header (in this case, Cisco-Guid) return M 59

Focus on SIP Normalization Script - 4 M = {} function M.inbound_INVITE(msg) msg:converthitodiversion() end function M.outbound_INVITE(msg) msg:removeheader("cisco-guid") end return M Line is required Returns the Lua Table containing the message handlers to Unified CM execution environment Cisco SIP Lua Environment uses Table M to identify the message handlers 60

SIP Message Handler Formalities Each Transparency and Normalization script provides: Set of call-back functions to manipulate SIP messages Call-back functions are called message handlers The message handler s name indicates when a handler is invoked Only one Transparency AND Normalization Script per SIP Trunk or Device Must define all message handlers in that single script Mix and match methods and directions in a single script Handlers for requests and responses have slightly different formats Will be covered next 61

Request Message Handlers Request message handler is named by combining: the SIP message direction AND the SIP method name Identify the method name from the 'request line' of the SIP message Request format: <direction>_<method> Examples: inbound_invite outbound_update 62

Response Message Handlers Response message handler is named by combining: the message direction PLUS the response code AND the SIP method Identify the method name from the CSeq header Response format: <direction>_<response code>_<method> Examples: inbound_183_invite inbound_200_invite outbound_200_update 63

Using Wild Cards in Message Handler Names For Request Messages A wildcard ANY can be used in place of <method> <direction> does not support a wild card For Response Messages: A wildcard ANY can be used in place of <method> A wildcard ANY can be used in place of <response code> <method> and <response code> can both be ANY <direction> does not support a wild card Cannot have a wildcard ANY <method> with a specific <response code> A wildcard character X can be used in <response code> 64

Examples of Wild Cards Valid Request Message Handler Names M.inbound_INVITE M.inbound_ANY M.outbound_ANY Valid Response Message Handler Names M.inbound_183_INVITE M.inbound_18X_INVITE M.outbound_ANY_INVITE M.outbound_ANY_ANY Invalid Response Names M.inbound_183_ANY 65

Rules for picking a message handler Unified CM uses these rules to choose a message handler: Message handlers are case-sensitive The direction is either inbound or outbound The direction is always written as lowercase The message direction is relative to Unified CM For Your Reference Note: The message direction has nothing to do with the dialog direction of the SIP session The method name in the SIP message is converted to uppercase to pick the message handler Longest match criteria: Unified CM uses the longest-match to choose the message handler A script has two message handlers: inbound_any_any and inbound_183_invite A 183 response is received by Unified CM The inbound_183_invite handler will be executed since it is the longest match 66

Built-In Normalization Scripts You can also find Transparency & Normalization scripts in some Interoperability guides. 67

APIs for SIP and SDP Normalization SIP Messages APIs: Allows script to manipulate the SIP message For Your Reference SDP APIs: Allows script to manipulate the SDP SIP Pass Through APIs: Allows script to pass information from one call leg to another SIP Utility APIs: Utilities to manipulate header data such a parsing URIs into a SIP URI object SIP URI APIs: Allows script to manipulate the parsed SIP URI object Trace APIs: Allows script to enable, disable and manage tracing Script Parameters API: Allows script to obtain trunk or line specific parameters 68

SIP Objects and Normalization Which SIP methods can be normalized? You can invoke a scripts based on any Method that Unified CM handles Which SIP headers can your script access? You can access any headers in the message that invokes the script Which lines in the message s SDP can you access? Your script can access any of the SDP lines For normalization, scripts can manipulate almost every aspect of a SIP message 69

SIP Objects and Transparency support Transparency is limited to INVITE dialogs on SIP trunks Transparency scripts can pass almost any information in a SIP message SIP Headers SIP Parameters Content Bodies These SIP objects do not support Transparency scripts SUBSCRIBE dialogs PUBLISH out-of-dialog REFER out-of-dialog unsolicited NOTIFY MESSAGE 70

Using IOS SIP Profiles Normalization

Putting SIP Profiles to Work Using profiles to manipulate SIP messages SIP profiles can be configured either at the dial-peer or global levels Message modification uses regular expressions to match and replace fields Modification can also be used to change a header name to the compact form For example, From to f By default, IOS never sends the compact form (it receives either long or short form) SIP Profiles cannot modify compact form headers Changes made to messages are not remembered by CUBE Content-length field is recalculated after normalization is applied 72

Using Wild Cards in Rules ANY keyword indicates that a rule will be applied to any message within the specified category Note that rules configured for an INVITE message only apply to the first INVITE in the call REINVITE supports operations needed on subsequent INVITEs in the call 73

Using SIP Profiles: Adding Headers Add new information that might be missing from a message s SIP or SDP Headers Useful for adding fixed value headers to SIP Messages Used for: Adding new headers to SIP Requests or Responses Adding new SDP headers to specific SDP lines 74

Example: Adding Headers Adding a Retry-After Header Incoming Outgoing 480 Temporarily Not Available CUBE 480 Temporarily Not Available Retry-After: 60 voice class sip-profiles 10 response 480 sip-header Retry-After add Retry-After: 60 75

Using SIP Profiles: Removing Headers Provides the ability to remove a message s SIP or SDP Headers Used for: Removing an incompatible header Discarding internal information not needed by SIP Service Provider 76

Example: Removing Headers Removing the Cisco-Guid Header Incoming INVITE sip:5551000@sip.com:5060 SIP/2.0 Cisco-Guid: 3386501632-0000065536 CUBE Outgoing INVITE sip:5551000@sip.com:5060 SIP/2.0 voice class sip-profiles 20 request ANY sip-header Cisco-Guid remove response ANY sip-header Cisco-Guid remove 77

Using SIP Profiles: Modifying Messages Using regular expressions to match and replace fields Add fixed strings to existing header Substrings that have been matched can be part of replacement patterns When multiple rules apply to the same header, the second rule applies to the result string of the first rule Used for: Adding parameters to a header Modifying the URI Changing SDP 78

Example: Modifying Headers (1) Modify the originator SDP o= line Incoming INVITE sip:5551000@sip.com:5060 SIP/2.0 o=ciscosystemssip-gw-useragent 4535 5918 IN IP4 192.168.100.100 CUBE Outgoing INVITE sip:5551000@sip.com:5060 SIP/2.0 o=- 4535 5918 IN IP4 192.168.100.100 voice class sip-profiles 30 request INVITE sdp-header Session-Owner modify CiscoSystems-SIP-GW-UserAgent - 79

Example: Modifying Headers (2) Change anonymous to a directory number Incoming INVITE sip:5551000@sip.com:5060 SIP/2.0 From: <sip:anonymous@public.com:5060> CUBE Outgoing INVITE sip:5551000@sip.com:5060 SIP/2.0 From: <sip:5551212@public.com:5060> voice class sip-profiles 40 request INVITE sip-header From modify sip:anonymous@" sip:5551212@ 80

Using SIP Profiles: Copying Header Information Matched substrings can be saved in variables to copy into another header Variables u01 to u99 are shared by inbound and outbound SIP Profiles Can be used to copy information from inbound message to outbound message Uses peer-header feature of SIP Profiles Can use additional rules to modify the copied information Used for: Duplicating content of existing header to another header 81

Example: Copying Headers Copying phone number to Request URI Incoming INVITE sip:tjones@sip.com:5060 SIP/2.0 To: tjones <5551000@sip.com:5060> CUBE Outgoing INVITE sip:5551000@sip.com:5060 SIP/2.0 To: tjones <5551000@sip.com:5060> voice class sip-profiles 50 request INVITE sip-header To copy "sip:(.*)@" u01 request INVITE sip-header SIP-Req-URI modify ".*@(.*)" "INVITE sip:\u01@\1" 82

Inbound versus Outbound SIP Profiles SIP profiles can be applied to outgoing SIP messages Outbound rules are applied as the last step before the message leaves CUBE Normalization is after destination dial-peer matching has taken place Changes to the SIP message are not remembered after the message is sent SIP profiles can be applied to incoming SIP messages Inbound rules are first applied as the message enters CUBE Normalization is done prior to dial-peer matching CUBE will perform a preliminary match to determine if inbound SIP Profile exists After normalization, final dial peer will be chosen 83

Some Inbound SIP Profile Notes Incoming messages can contain multiple instances of same header For example, an INVITE can have multiple Diversion headers Header values will be in a comma separated list Must keep this in mind if you plan to modify these headers If preliminary inbound dial-peer matching fails, Inbound SIP Profiles attached to dial peers will not run Could happen if the inbound message has an invalid Request URI. A global Inbound SIP profile could be used, but use caution Performing SIP normalization will add extra processing logic, which slightly reduces CUBE performance

Enabling Inbound SIP Profile Feature Inbound SIP Profile has to be enabled at global level for normalizing incoming messages Configuration Example voice service voip sip sip-profiles inbound

Enabling Outbound SIP Profile Dial-Peer Profile Configuration Outbound SIP Profile removes the Cisco-Guid from any message leaving CUBE via specified Dial-Peer Configuration Example: voice class sip-profiles 20 request ANY sip-header Cisco-Guid remove response ANY sip-header Cisco-Guid remove dial-peer voice 10 voip voice-class sip profiles 20

Troubleshooting Commands Debug and Show Debug commands: debug ccsip info debug ccsip feature sip-profile debug ccsip error debug ccsip message Show commands: Verify the SIP Profile is assigned to a dial-peer: show dial-peer voice 1 include sip profile

Troubleshooting Sample sip profile to change user part of From header from anonymous to some value. voice class sip-profiles 1 request INVITE sip-header FROM modify "sip:anonymous@" "sip:1234@" INVITE sip:1111@192.168.1.1:5060 SIP/2.0 Via: SIP/2.0/UDP 192.168.2.1;branch=z9hG4bK-24227-1-0 From: anonymous <sip:anonymous@192.168.2.1:9232>;tag=1 To: 1111 <sip:1111@192.168.1.1:5060> Call-ID: 1-24227@192.168.2.1 Sample log: Sample incoming message with From header set to anonymous. Sip profile invoked for modifying the message is displayed here Jan 17 18:24:00 EST: //-1/xxxxxxxxx/SIP/Info/verbose/64/ccsip_inbound_profile_populate_callinfo_in_ccb: Dial-peer 1 is used for inbound profiles config Jan 17 18:24:00 EST: //-1/xxxxxxxxx/SIP/Info/info/64/sipSPISetSipProfilesTag: voice class SIP Profiles inbound tag is set : 1 Jan 17 18:24:00 EST: //-1/xxxxxxxxx/SIP/Info/info/64/sip_profiles_application_modify_remove_header: Header before modification : From: sipp <sip:anonymous@192.168.2.1:9232>;tag=1 Jan 17 18:24:00 EST: //-1/xxxxxxxxx/SIP/Info/info/64/sip_profiles_application_modify_remove_header: Header after modification : From: sipp <sip:1234@192.168.2.1:9232>;tag=1 From header after modification

Unified CM Normalization Case Study

Case Study Calls going to the wrong mail box Customer has several PBXs trunked to Cisco Unified CM Unified CM interfaced to a 3rd-party voice mail system via SIP Calls sent to voice mail after multiple call forwards Most calls were going to the correct voice mail box Calls from one PBX were not In the broken case, calls were going to the voice mail box of the last station the call was forwarded to Let s look in detail at these call flows 90

Case study call flow 5 Call from PSTN for x1100 1 Call from PSTN for x2100 6 Call Forward All to x1200 Bad Result 7 8 No Answer to Voice Mail Greeting for x1200 4 Greeting for x2100 2 Call Forward All to x2200 Good Result 3 No Answer to Voice Mail 91

Problem: SIP header from call to wrong mail box INVITE sip:4125553000@192.168.1.1:5060 SIP/2.0 Via: SIP/2.0/TCP 192.168.2.2:5060;branch=z9hG4bK12b5cc229a69621 From: "PSTN" <sip:8145551212@192.168.2.2>;tag=16101269~0458486e-22501993c802-145785687 To: <sip:4125553000@192.168.1.1> Date: Wed, 19 Dec 2012 16:45:01 GMT Call-ID: c9d9ea00-eef16a0d-46c59c-a5086cc6@192.168.2.2 Supported: 100rel,timer,resource-priority,replaces User-Agent: Cisco-CUCM8.5 Allow: INVITE, OPTIONS, INFO, BYE, CANCEL, ACK, PRACK, UPDATE, REFER, SUBSCRIBE, NOTIFY CSeq: 101 INVITE Expires: 180 Call-Info: <sip:192.168.2.2:5060>;method="notify;event=telephone-event;duration=500" Cisco-Guid: 3386501632-0000065536-0002912165-2768792774 Diversion: <sip:4125551200@192.168.2.2>;reason=no-answer;privacy=off;screen=yes Diversion: <sip:4125551100@192.168.2.2>;reason=unconditional;privacy=off;screen=yes Contact: sip:8145551212@192.168.2.2:5060;transport=tcp Content-Length: 0 Call goes to x1200 greeting instead of x1100 92

What the script will have to accomplish Keep it simple & just remove the headers we don t need for voice mail 93

Minimal Normalization Script for outbound INVITEs M = {} function M.outbound_INVITE(msg) to VM -- Process outbound INVITES -- Process INVITE to normalize it... end return M 94

Add logic to remove extra Diversion Headers -- Get all Diversion Headers local DiversArray = msg:getheadervalues("diversion ) local DiversCount = #DiversArray if DiversCount > 1 then for I = 1, (DiversCount - 1) do -- Number of Diversion Headers -- Only if there s more than one -- Remove all but last header -- remove a Diversion Header msg:removeheadervalue("diversion", DiversArray[I]) end end 95

Completed Script M = {} function M.outbound_INVITE(msg) local DiversArray = msg:getheadervalues("diversion ) local DiversCount = #DiversArray if DiversCount > 1 then for I = 1, (DiversCount - 1) do -- Process outbound INVITES to VM -- Get all Diversion Headers -- # of Diversion Headers in Invite -- Only if there s more than one -- Remove all but last header msg:removeheadervalue("diversion", DiversArray[I]) -- remove a Diversion Header end end end return M 96

Deploy the script to Unified CM Now that we have a script, what do we do with it? Apply it to the voice mail SIP trunk in Unified CM: 1. Add a SIP Normalization Script 2. Can be imported from a text file or copy/paste 3. Save the Script 4. Apply the Script to the appropriate SIP trunk 97

Add a SIP Normalization Script 98

Import the Script 99

Configure and save the Script 100

Apply the Script to the SIP trunk 101

Verify that your script fixes the problem INVITE sip:4125553000@192.168.1.1:5060 SIP/2.0 Via: SIP/2.0/TCP 192.168.2.2:5060;branch=z9hG4bK12b5cc229a69621 From: "PSTN" <sip:8145551212@192.168.2.2>;tag=16101269~0458486e-22501993c802-145785687 To: <sip:4125553000@192.168.1.1> Date: Wed, 19 Dec 2012 16:45:01 GMT Call-ID: c9d9ea00-eef16a0d-46c59c-a5086cc6@192.168.2.2 Supported: 100rel,timer,resource-priority,replaces User-Agent: Cisco-CUCM8.5 Allow: INVITE, OPTIONS, INFO, BYE, CANCEL, ACK, PRACK, UPDATE, REFER, SUBSCRIBE, NOTIFY CSeq: 101 INVITE Call-Info: <sip:192.168.2.2:5060>;method="notify;event=telephone-event;duration=500" Cisco-Guid: 3386501632-0000065536-0002912165-2768792774 Session-Expires: 1800 Diversion: <sip:4125551100@192.168.2.2>;reason=unconditional;privacy=off;screen=yes Contact: sip:8145551212@192.168.2.2:5060;transport=tcp Content-Length: 0 Call now goes to x1100 greeting (1 Diversion Header) 102

Revisiting Use Last Diversion Header Same symptoms, different cause Thought this had been solved Another customer had calls to voicemail going to the wrong destination Discovered there were multiple Diversion Headers Diversion: Doe, John" <sip:jdoe@192.168.3.3>;reason=no-answer;privacy=off Diversion: Doe, John" <sip:1000@192.168.3.3>;reason=no-answer;privacy=off" Because of the comma in the Header, it breaks the processing It actually causes an issue with the SIP Normalization API The Headers are parsed into a Lua Table using commas and <CR><LF> 103

New Approach to Choosing the Last Diversion Process all Diversion Headers as one long string getheader( Diversion ) returns all Diversion Headers in a single string Each header will be comma separated Doe, John" <sip:jdoe@192.168.3.3>;reason=no-answer;privacy=off, Doe, John" <sip:1000@192.168.3.3>;reason=no-answer;privacy=off To get right voicemail box, really care about: Doe, John <sip:1000@192.168.3.3>;reason=no-answer Rest of the string can be discarded Can use Lua string matching to greedy match everything up to the last, "(.+),\" -- Note the \ to be able to match a Can replace everything matched with using: \ Doe, John" <sip:1000@192.168.3.3>;reason=no-answer;privacy=off 104

Complete Lua Script M = {} function M.outbound_INVITE(msg) -- Get all Diversion Headers local DiversHeaders = msg:getheader("diversion") if string.len(diversheaders) == 0 then -- no Diversion Headers else -- Greedy match everything up to the last," and replace with " newdiversheader = string.gsub(diversheaders, "(.+),\", "\"") msg:removeheader("diversion") -- remove Diversion Headers msg:addheader("diversion", newdiversheader) -- add last Diversion Header back end end return M 105

Some Common Scripting Forms 106

Navigating Script Formats Sample Normalization Scripts are available Can be confusing, not all scripts follow same format Scripts follow two basic formats: Function Name made up of the direction and SIP method example: function M.inbound_INVITE(msg) Function Name indicates purpose, but not direction or SIP Method example: function add_reply_to_header(msg) 107

Name = Direction + Method M = {} function M.inbound_INVITE(msg)... (function code)... end return M Good: Know exactly what SIP messages will be acted on Bad: Cannot reuse the function for anything else Need to repeat the code to duplicate processing on outbound INVITE 108

Example: Name with Purpose M = {} local function add_reply_to_header(msg)... (function code)... end M.outbound_INVITE = add_reply_to_header return M 109

Name with Purpose Good: Function name describes exactly what it does Can reuse the function without repeating it To use add_reply_to_header for inbound INVITES: M.inbound_INVITE = add_reply_to_header To use add_reply_to_header for outbound INVITES: M.outbound_INVITE = add_reply_to_header Bad: Might search through entire script to figure out the direction and SIP Method 110

Using Script Parameters SIP T&N allows you to set script parameters Available in Unified CM Admin pages Allows deployment of a generic script Provide script with site settings at load time Use same script in multiple locations without rewriting Example: local mydomain = scriptparameters.getvalue("localdomain") local fqdn = host..... mydomain 111

Setting a Script Parameter Access Unified CM Admin Set on the SIP Trunk Configuration page Must know the Parameter Name from the script Parameters are not indexed by Unified CM No pick-list provided 112

Enabling Tracing in Scripts Scripts can write trace information to Unified CM logs Tracing must be enabled in BOTH: Your script Unified CM Configuration Can embed tracing in every script: Use for testing and troubleshooting Disable from Unified CM Admin in production to optimize performance Trace output added to Unified CM SDI Trace 113

Adding Tracing to Your Scripts trace.enable() function M.inbound_NOTIFY(msg) local callid = msg:getheader("call-id") trace.format("m.inbound_notify: callid is '%s'", callid) trace.format(" -- missing URI host, no changes made") 114

Enabling Tracing from Unified CM 115

SIP Profiles Case Study 116

Case Study-Problem Statement Forwarded PSTN calls fail Customer has SIP trunks configured to the SIP service provider Unified CM configured to turn 4-digit extension into a valid E.164 number Dialed calls to the PSTN are completed Calls forwarded to PSTN fail Let s look at the problem 117

SIP Headers for Forwarded Call INVITE sip:4125553000@192.168.1.1:5060 SIP/2.0 Via: SIP/2.0/TCP 192.168.2.2:5060;branch=z9hG4bK12b5cc229a69621 From: Mark" <sip:8145551212@192.168.2.2>;tag=16101269~0458486e-22501993c802-145785687 To: <sip:4125553000@192.168.1.1> CSeq: 101 INVITE Cisco-Guid Cisco-Guid: 3386501632-0000065536-0002912165-2768792774 meaningless outside Diversion: <sip:1100@192.168.2.2>;reason=unconditional;privacy=off;screen=yesenterprise Content-Length: 0 Diversion Header contains internal Extension (x1100) 118

Tackling the Problem (1) Removing Cisco-Guid Removing Cisco-Guid from all requests and responses is straightforward No downside on trunks to SIP SP since it has no meaning outside enterprise SIP profile rules: request ANY sip-header Cisco-Guid remove response ANY sip-header Cisco-Guid remove

Tackling the Problem (2) Modifying Diversion Header Need to add the required E.164 digits to the extension in the Diversion Header Take advantage of the dial-plan All internal extensions have the format 1xxx Insert the digits 814555 in front of the extension Match the 1200@ in Diversion Header: (1 )@ Replace the match with 8145551200@ : 814555\1@ Complete SIP profile rule: request INVITE sip-header Diversion modify (1 )@ 814555\1@

Complete the Configuration Applying the SIP Profile rules to outgoing dial-peer Sample Configuration: voice class sip-profiles 100 request ANY sip-header Cisco-Guid remove response ANY sip-header Cisco-Guid remove request INVITE sip-header Diversion modify (1 )@ 814555\1@! dial-peer voice 100 voip voice-class sip profiles 100!

Verify Results of SIP Profiles INVITE sip:4125553000@192.168.1.1:5060 SIP/2.0 Via: SIP/2.0/TCP 192.168.2.2:5060;branch=z9hG4bK12b5cc229a69621 From: Mark" <sip:8145551212@192.168.2.2>;tag=16101269~0458486e-22501993c802-145785687 To: <sip:4125553000@192.168.1.1> CSeq: 101 INVITE Cisco-Guid removed Diversion: <sip:8145551200@192.168.2.2>;reason=unconditional;privacy=off;screen=yes Content-Length: 0 Diversion Header normalized to E.164 122

Bonus Case Study 123

MWI Lights Don t Light Adapting SIP Notify Problem: Unity Connection provides voicemail for user on multiple vendor PBXs Unity Connection homed to Unified CM SME SME connects to other PBXs via SIP One vendors PBX fails to update MWI status Initial Troubleshooting: Gathered traces: SIP Notify being sent to system Opened case with vendor Software release running on system needs Message-Account in the Notify 124

First Try Add a Message-Account header No detail available on what Notify should look like You need a Message-Account Header Make it look like the To: Header That s easy Use geturi(to) gives me the URI from the To: Use that to add a new header to message: addheader( Message-Account, <uri from geturi>) Turns out it wasn t so easy 125

Revisiting the Problem Discover that Message-Account isn t a SIP Header at least for this release Message-Account should be in the content body Oh, and by the way Can you make sure it is right after the Messages-Waiting line That s a bit more complicated 126

Tackling the Problem Can use the geturi( To ) function to grab the To: header like before You can t edit the content body in place: Read the body and save it: getcontentbody() Delete the current body: removecontentbody() Add updated body: addcontentbody() Easy: Add the Message-Account: line to beginning or end of body Harder content body processing: Add Message-Account: line right after Messages-Waiting: line Don t know where in the body Messages-Waiting: line is Maintain CR-LF terminator on each line of body Use string matching and (partial) substitution 127

Updating the Content Body Before and After Content-Body from Unity Connection: Messages-Waiting: yes Voice-Message: 5/0 (0/0) Fax-Message: 0/0 (0/0) Content-Body desired: Messages-Waiting: yes Message-Account: sip:5000@10.10.10.10 Voice-Message: 5/0 (0/0) Fax-Message: 0/0 (0/0) 128

Build the Script Basics M = {} function M.outbound_NOTIFY(msg)... end return M 129

Create the Message-Account Line -- Get the URI from To: and extract user and host local uristring = msg:geturi("to") local nuri = siputils.parseuri(uristring) nuser = nuri:getuser() nhost = nuri:gethost() -- Build the Message-Account line ma = string.format( Message-Account: sip:%s@%s\r\n, nuser, nhost) 130

Update the Content Body -- Set the content type of the body local ct = "application/simple-message-summary" -- Get the existing content body local cb = msg:getcontentbody(ct) -- Build a new content body local ncb = string.gsub(cb, "Messages%-Waiting%:%s%w+%c+", "%0".. ma) -- Have to remove the existing content body and re-add msg:removecontentbody(ct) msg:addcontentbody(ct, ncb) 131

Taking a Look at the String Operation Breaking down the key string operation string.gsub(cb, "Messages%-Waiting%:%s%w+%c+", "%0".. ma) string.gsub takes three arguments: 1. String you want to process 2. String you want to find (match) 3. What you want to replace the matched string with Looking for Messages-Waiting: yes\r\n (or no) Take what we matched: %0 concatenate on the Message-Address we built before get the two lines we want for the Content Body 132

Conclusion 134

How to Choose Your Tool Should I pick Unified CM or IOS There is overlap between what you can accomplish with both tools Some things to consider when choosing a tool: What does the call flow look like? Programming versus Match/Replace? Knowledge of Language (Lua vs. RegEx)? Is the right version available? Are needed features available? 135

Some Final Thoughts If you can identify the problem, you can fix it Traces and packet captures are your friend All normalization scripts or expressions have same beginnings Test, write, test, fix, test, then go to production 136

Resources Unified CM Transparency & Normalization SIP Chapter in Unified CM System Guide: http://www.cisco.com/en/us/docs/voice_ip_comm/cucm/admin/10_0_1/ccmsys/cucm_ BK_SE5FCFB6_00_cucm-system-guide-100_chapter_0101000.html Developer Guide for SIP Transparency and Normalization http://www.cisco.com/en/us/docs/voice_ip_comm/cucm/sip_tn/9_1_1/sip_t_n.html Cisco Interoperability Portal http://www.cisco.com/go/interoperability Cisco Developer Network http://developer.cisco.com/ 137

Resources IOS SIP Profiles Configuration Note for CUBE SIP Normalization: http://www.cisco.com/c/en/us/support/docs/voice-unified-communications/unifiedborder-element/105624-cube-sip-normalization.html SIP Configuration Guide (15M&T) http://www.cisco.com/c/en/us/td/docs/ios-xml/ios/voice/sip/configuration/15-mt/sipconfig-15-mt-book.html CUBE Configuration Guide for SIP Profiles http://www.cisco.com/c/en/us/td/docs/ios-xml/ios/voice/cube/configuration/cubebook/voi-sip-param-mod.html#reference_869720458984374988879107666015624 138

Resources: Where to Ask Questions Cisco Developer Network has a SIP Transparency and Normalization Forum Part of the SIP Developer Portal Post questions there and interact with other developers 139

Questions? Thanks for Attending! 140

Key References for SIP T&N 141 141

Call to Action Visit the World of Solutions for Cisco Campus Walk in Labs Technical Solution Clinics Meet the Engineer Lunch time Table Topics DevNet zone available to discuss Cisco Development Resources Recommended Reading: for reading material and further resources for this session, please visit www.pearson-books.com/clmilan2015 142