Fixing SIP Problems with UC Manager & CUBE Normalization Tools

Transcription

1

2 Fixing SIP Problems with UC Manager & CUBE Normalization Tools Mark Stover, CCIE #6901 Consulting Systems Engineer

3 Agenda Introduction (Very) Brief Review of SIP When Things Don t Work Overview of SIP Normalization Methods Using IOS SIP Profiles Normalization Using Unified CM Normalization Scripts Using Unified CM Transparency Conclusion

4 Cisco Spark Ask Questions, Get Answers, Continue the Experience Use Cisco Spark to communicate with the Speaker and fellow participants after the session Download the Cisco Spark app from itunes or Google Play 1. Go to the Cisco Live Berlin 2017 Mobile app 2. Find this session 3. Click the Spark button under Speakers in the session description 4. Enter the room, room name = 5. Join the conversation! The Spark Room will be open for 2 weeks after Cisco Live 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 7

5 Brief Review of SIP

6 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 response Server Each request invokes method on server Main purpose of request Messages contain bodies 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 9

7 SIP Methods and Messages SIP Messages have distinct parts: IP/TCP/UDP Envelope SIP Header SIP Message Body MIME-Encoded Session Description Protocol (SDP) May contain other data Call signaling performed by SIP Methods Six Original SIP Methods: INVITE ACK OPTIONS BYE CANCEL REGISTER 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 10

8 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: @ Content-type: application/sdp CSeq: 4711 INVITE Content-Length: 187 v=0 o=ccm-sip IN IP s=sip Call c=in IP m=audio RTP/AVP a=rtpmap:0 PCMU/8000 a=ptime:20 a=mid:1 c=in IP6 2001:0db8:aaaa::0987:65ff:fe01:234b m=audio RTP/AVP 0 a=mid: Cisco and/or its affiliates. All rights reserved. Cisco Public 12

9 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 Complete call from INVITE to BYE is a dialog Defines a call leg Maintains the same call-id and tags 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 15

10 When things don t work

11 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 Was delivered earlier this morning 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 19

12 Getting SIP Messages Four potential 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) 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 20

13 Example of Unified CM Trace File 17:38: //SIP/SIPTcp/wait_SdlReadRsp: Incoming SIP TCP message from on port with 1872 bytes: INVITE SIP/2.0 Via: SIP/2.0/TCP :5060;branch=z9hG4bK From: "Alice" To: Date: Wed, 12 Oct :38:59 GMT Call-ID: Supported: 100rel,timer,resource-priority,replaces,sdp-anat Cisco-Guid: User-Agent: Cisco-SIPGateway/IOS-12.x CSeq: 101 INVITE Timestamp: Expires: 180 Allow-Events: telephone-event Content-Type: multipart/mixed;boundary=uniqueboundary Mime-Version: 1.0 Content-Length: uniqueboundary Content-Type: application/sdp Content-Disposition: session;handling=required v=0 o=ciscosystemssip-gw-useragent IN IP s=sip Call c=in IP t=0 0 m=audio RTP/AVP c=in IP a=rtpmap:0 PCMU/ Cisco and/or its affiliates. All rights reserved. Cisco Public 21

14 Using Wireshark 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 23

15 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 Maybe the redirect number only has four digits 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 24

16 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 25

17 SIP Transparency & Normalization vs. IOS SIP Profiles

18 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 27

19 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 XZ Inbound SIP Profiles available in IOS T Uses regular expressions to match and replace fields in SIP messages 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 28

20 New Features in IOS SIP Profiles New Normalization and Transparency features continue to be added Inbound SIP Profiles available in IOS 15.4(2)T (CUBE ) New features in IOS 15.5(2)T (CUBE 11.0): SIP Profile Rule Tags Normalization support for non-standard SIP Headers SDP Pass-Through and Normalization in IOS 15.6 (1)T (CUBE 11.5) 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 29

21 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 SDP Only (15.6.1T) Yes Programmability Match, Replace, Copy Lua Scripting Matching RegEx (egrep) Lua Matching (globbing) Conditionals & Loops No Yes Headers (Std & Non-Std) Yes Yes Message Body SDP Only Any 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 30

22 Overview of SIP Profiles Normalization

23 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 32

24 What can SIP Profiles normalization change? Add, modify, remove or copy any SIP or SDP header value in a SIP message Can not 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 34

25 Using IOS SIP Profiles Normalization

26 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 a subset of standard 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 37

27 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 38

28 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 39

29 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: Cisco and/or its affiliates. All rights reserved. Cisco Public 40

30 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 rule 10 response 480 sip-header Retry-After add Retry-After: 60 Note that, rule tagging is a new CUBE feature in IOS 15.5(2)T 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 41

31 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 42

32 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 44

33 Example: Modifying Headers (1) Modify the originator SDP o= line Incoming INVITE SIP/2.0 o=ciscosystemssip-useragent IN IP CUBE Outgoing INVITE SIP/2.0 o=ua IN IP voice class sip-profiles 30 request INVITE sdp-header Session-Owner modify CiscoSystems-SIP-UserAgent UA 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 45

34 Example: Modifying Headers (2) Change anonymous to a directory number Incoming INVITE sip: @sip.com:5060 SIP/2.0 From: <sip:anonymous@public.com:5060> CUBE Outgoing INVITE sip: @sip.com:5060 SIP/2.0 From: <sip: @public.com:5060> voice class sip-profiles 40 request INVITE sip-header From modify sip:anonymous@" sip: @ 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 46

35 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 47

36 Example: Copying Headers Copying phone number to Request URI Incoming INVITE SIP/2.0 To: tjones CUBE Outgoing INVITE SIP/2.0 To: tjones voice class sip-profiles 50 request INVITE sip-header To copy u01 request INVITE sip-header SIP-Req-URI modify "INVITE 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 48

37 Inbound versus Outbound SIP Profiles SIP profiles applied to outgoing SIP messages by default 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 also 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 49

38 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 50

39 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 51

40 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 rule 10 request ANY sip-header Cisco-Guid remove rule 20 response ANY sip-header Cisco-Guid remove dial-peer voice 10 voip voice-class sip profiles Cisco and/or its affiliates. All rights reserved. Cisco Public 52

41 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 53

42 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@ :5060 SIP/2.0 Via: SIP/2.0/UDP ;branch=z9hG4bK From: anonymous <sip:anonymous@ :9232>;tag=1 To: 1111 <sip:1111@ :5060> Call-ID: @ Sample log: Sample incoming message with From header set to anonymous. Jan 17 18:24:00 EST: //-1/xxxxxxxxx/SIP/Info/verbose/64/ccsip_inbound_profile_populate_callinfo_in_ccb: Dialpeer 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@ :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@ :9232>;tag=1 From header after modification Sip profile invoked for modifying the message is displayed here 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 54

43 The SIP Profile Generation Tool BU had a web-based tool to help build SIP Profiles Paste in messages, edit what you need, see the rule Officially unsupported after release of SIP Profile Test Tool Still available to Cisco internally at: Cisco and/or its affiliates. All rights reserved. Cisco Public 55

44 SIP Profile Test Tool Web-based tool to validate SIP Profiles Checks SIP Profile syntax Use sample SIP messages to test SIP Profile logic Understand features and limitations of RegEx for SIP Profiles Takes the palce of the SIP-Profile Generation Tool 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 60

45 SIP Profile Test Tool Cisco and/or its affiliates. All rights reserved. Cisco Public 62

46 Dialed Number Analyzer (DNA) for CUBE Features Use Cases Emulation of CUBE Dial-Plan validation E164 and URI Call Routing Features 2 Input modes E164 and SIP Message Understand Call routing logic Pre-deployment config validation Interoperability Testing 10 Call Routing features Output SIP Invite Generation Real-time config editing and testing 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 64

47 SIP Profiles Case Study

48 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 66

49 SIP Headers for Forwarded Call INVITE SIP/2.0 Via: SIP/2.0/TCP :5060;branch=z9hG4bK12b5cc229a69621 From: Mark" To: CSeq: 101 INVITE Cisco-Guid: Diversion: Content-Length: 0 Diversion Header contains internal Extension (x1200) Cisco-Guid meaningless outside enterprise 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 67

50 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 68

51 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 in front of the extension Match the in Diversion Header and capture the extension: (1 Replace the match with using the captured digits (\1): Complete SIP profile rule: request INVITE sip-header Diversion modify ( Cisco and/or its affiliates. All rights reserved. Cisco Public 69

52 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 dial-peer voice 100 voip voice-class sip profiles 100! 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 70

53 Verify Results of SIP Profiles INVITE SIP/2.0 Via: SIP/2.0/TCP :5060;branch=z9hG4bK12b5cc229a69621 From: Mark" To: CSeq: 101 INVITE Diversion: Content-Length: 0 Diversion Header normalized to E.164 Cisco-Guid removed 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 71

54 Overview of SIP Transparency & Normalization

55 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 76

56 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 77

57 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 78

58 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 79

59 Using Unified CM Normalization Scripts

60 Putting SIP Normalization to Work Using message handlers to manipulate SIP messages Message Handler name tells you: When the Handler will be invoked (entering or leaving) What type of message the Handler is for (SIP Method) To have a script process the INVITEs received by Unified CM: Script should have an inbound_invite message handler That message handler will run when an inbound INVITE is received A single parameter called msg represents the SIP Message in script Scripts use Cisco SIP Message API to access and manipulate the message Let s try looking at a diagram 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 81

61 How a Normalization Script Gets Run 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 82

62 How a Normalization Script Gets Run 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 83

63 How a Normalization Script Gets Run 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 84

64 How a Normalization Script Gets Run 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 85

65 How a Normalization Script Gets Run 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 86

66 How a Normalization Script Gets Run 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 87

67 How a Normalization Script Gets Run 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 88

68 How a Normalization Script Gets Run 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 89

69 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 90

70 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 91

71 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 92

72 Focus on SIP Normalization Script - 2 M = {} function M.inbound_INVITE(msg) end msg:converthitodiversion() 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 93

73 Focus on SIP Normalization Script - 3 M = {} function M.inbound_INVITE(msg) msg:converthitodiversion() End function M.outbound_INVITE(msg) end msg:removeheader("cisco-guid") Outbound INVITE Message Handler Outbound SIP Message accessed through msg Invokes API call to remove a header (in this case, Cisco-Guid) return M 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 94

74 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 95

75 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 Script per SIP Trunk or SIP Device All message handlers in that single script Can mix and match methods and directions in a single script Handlers for requests and responses have slightly different formats Will be covered next 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 96

76 Request Message Handlers Request message handler is named by combining: the SIP message direction AND the SIP method name Method name from the 'request line' of the SIP message Request format: <direction>_<method> Examples: inbound_invite outbound_update 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 97

77 Using Wild Cards in Request Message Handlers Recall that the Request format is: <direction>_<method> Wildcard ANY can be used in place of <method> <direction> does not support a wild card Valid Request Message Handler Names: M.inbound_INVITE M.inbound_ANY M.outbound_ANY Invalid Name: M.ANY_INVITE 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 98

78 Response Message Handlers Response message handler is named by combining 3 items: 1. the message direction 2. the response code 3. 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 99

79 Using Wild Cards in Response Message Handlers Replace <method> with ANY Replace <response code> with ANY <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> 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 100

80 Wild Card Examples (Response Message Handlers) 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 (specific <response code> with ANY <method>) 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 101

81 Rules for picking a message handler For Your Reference 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 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 102

82 APIs for SIP and SDP Normalization SIP Messages APIs: Allows script to manipulate the SIP message 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 104

83 Unified CM Normalization Case Study

84 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 107

85 Case study call flow 5 Call from PSTN for x Call from PSTN for x Call Forward All to x1200 Bad Result 7 8 No Answer to Voice Mail Greeting for x Greeting for x Call Forward All to x2200 Good Result 3 No Answer to Voice Mail 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 108

86 Problem: SIP header from call to wrong mail box INVITE SIP/2.0 Via: SIP/2.0/TCP :5060;branch=z9hG4bK12b5cc229a69621 From: "PSTN" To: Date: Wed, 19 Dec :45:01 GMT Call-ID: 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: :5060>;method="notify;event=telephone-event;duration=500" Cisco-Guid: Diversion: Diversion: Contact: Content-Length: 0 Call goes to x1200 greeting instead of x Cisco and/or its affiliates. All rights reserved. Cisco Public 109

87 What the script will have to accomplish Keep it simple & just remove the headers we don t need for voice mail 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 110

88 Minimal Normalization Script for outbound INVITEs M = {} function M.outbound_INVITE(msg) -- Process outbound INVITES to VM -- Process INVITE to normalize it... end return M 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 111

89 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 112

90 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 113

91 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 114

92 Add a SIP Normalization Script 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 115

93 Import the Script 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 116

94 Configure and save the Script 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 117

95 Apply the Script to the SIP trunk 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 118

96 Verify that your script fixes the problem INVITE SIP/2.0 Via: SIP/2.0/TCP :5060;branch=z9hG4bK12b5cc229a69621 From: "PSTN" To: Date: Wed, 19 Dec :45:01 GMT Call-ID: 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: :5060>;method="notify;event=telephone-event;duration=500" Cisco-Guid: Session-Expires: 1800 Diversion: Contact: Content-Length: 0 Call now goes to x1100 greeting (1 Diversion Header) 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 119

97 Revisiting Use Last Diversion Header Same symptoms, different cause Thought this had been solved Another customer had calls to voic going to the wrong destination Discovered there were multiple Diversion Headers Diversion: Doe, John" Diversion: Doe, John" 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> 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 120

98 Some Common Scripting Forms

99 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) 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 124

100 Name = Direction + Method Good: Know exactly what SIP messages will be acted on Bad: M = {} function M.inbound_INVITE(msg)... (function code)... end return M Cannot reuse the function for anything else Need to repeat the code to duplicate processing on outbound INVITE 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 125

101 Example: Name with Purpose M = {} local function add_reply_to_header(msg)... (function code)... end M.outbound_INVITE = add_reply_to_header return M 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 126

102 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 127

103 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 128

104 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 129

105 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 130

106 Enabling Tracing from Unified CM 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 131

107 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") 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 132

108 Bonus Case Study and More Normalization Examples

109 MWI Lights Don t Light Adapting SIP Notify Problem: Unity Connection provides voic 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 134

110 Examining the Problem Carefully 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 Can t do this with CUBE Need to use Unified CM Normalization 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 136

111 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() 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 137

112 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: Voice-Message: 5/0 (0/0) Fax-Message: 0/0 (0/0) 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 139

113 Build the Script Basics M = {} function M.outbound_NOTIFY(msg)... end return M 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 140

114 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) 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 141

115 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) 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 142

116 Example: Dealing with Phone Displays Adapting content of SIP INVITE to device types Problem: Some SIP phones have limited display space Typically, provisioned name & number delivered to phone User prefers number if they can t see both 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 144

117 Solution Basics Takes some simple string matching, but relatively straightforward to remove name from 'From:' header frmhdr = msg:getheader( From ) newfrmhdr = string.gsub( frmhdr,.*<sip:, <sip: ) Then, use the API to modifyheader: msg:modifyheader( From, newfrmhdr) 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 145

118 Validating the Solution 'From:' header in INVITE no longer has name...but UPDATE during dialog still includes name Script needs a slight modification to handle both methods 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 146

119 Use Name with Purpose for Final Script M = {} local function remove_from_caller_name(msg) frmhdr = msg:getheader( From ) newfrmhdr = string.gsub('frmhdr', '.*<sip:', '<sip:') msg:modfiyheader( From, newfrmhdr) end M.inbound_INVITE = remove_from_caller_name M.inbound_UPDATE = remove_from_caller_name return M 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 147

120 In Case of SDP Manipulation M={} local function remove_x_cisco(msg) local sdp = msg:getsdp() if sdp then sdp = sdp:removeline("a=x-cisco-media:", "umoh") msg:setsdp(sdp) end end M.outbound_ANY = remove_x_cisco return M 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 148

121 Overview of Unified CM Transparency

122 Some SIP Transparency Background Unified CM is a B2BUA, so it consumes SIP headers that pass through: That s true for KNOWN headers (there s a list of 71 of them) Unknown headers pass through transparently Transparency feature allows you to take information from known headers and preserve it as the call legs pass across Unified CM Unified CM can transparently pass: Parameters Unknown headers Unknown content-bodies 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 151

123 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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 152

124 Why Use SIP Transparency? 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 153

125 Why Use SIP Transparency? Unified CM acting as SME will begin routing calls between PBX-A and PBX-Z 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 154

126 What Unified CM Does to Your Cisco and/or its affiliates. All rights reserved. Cisco Public 155

127 What We Want Unified CM to do 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 156

128 How Can Transparency Preserve 181 Fact 1: Unified CM consumes Reason header it is a known header Fact 2: The transparency feature lets you pass unknown headers through Unified CM Fact 3: Goal is to preserve the 181 Call is being forwarded Therefore Place in an unknown header when it ingresses Unified CM Restore the 181 as it egresses Unified CM 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 157

129 On Inbound 1. Invoked when Unified CM receives a 181 Response in an INVITE dialog 2. Create the PassThrough message block 3. Get the Reason header contents 4. Add the contents to an unknown X-Reason header B = {} function B.inbound_181_INVITE(msg) local pt = msg:getpassthrough() local rson = msg:getheader("reason") if pt and rson then pt:addheader("x-reason", rson) end end return B 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 158

130 What Happens after INBOUND Script Runs Unified CM Processes the SIP Message Because the reason is preserved in the X-Reason header: Unified CM will not consume it (in is an unknown header) It is preserved through call processing in the pass-through object Unified CM will consume the actual 181 Response and Unified CM will create a new 180 Response to take it s place The 180 Response still contains the pass-through object The 180 Response is now ready for OUTBOUND Processing 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 159

131 On Outbound A = {} function A.outbound_180_INVITE(msg) local reason = msg:getheader("x-reason") if reason then if string.find(reason, "cause=181") then msg:setresponsecode(181,"call is being forwarded") msg:addheader("reason", reason) end msg:removeheader("x-reason") end end return A 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 160

132 Conclusion

133 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? 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 162

134 Make a Plan and Practice Patience 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 Transparency relies on turning known headers into unknown ones Test, write, test, fix, test, then go to production 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 163

135 Next Steps Use the available resources to learn more I ve listed many in the following slides Use the Appendix to this deck Introduction to Lua Some additional Normalization examples Start small, and build on your knowledge 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 164

136 Resources Unified CM Transparency & Normalization SIP Chapter in Unified CM System Guide: BK_SE5FCFB6_00_cucm-system-guide-100_chapter_ html Developer Guide for SIP Transparency and Normalization Cisco Interoperability Portal Cisco Developer Network Cisco and/or its affiliates. All rights reserved. Cisco Public 165

137 Resources IOS SIP Profiles Configuration Note for CUBE SIP Normalization: SIP Configuration Guide (15M&T) CUBE Configuration Guide for SIP Profiles Cisco and/or its affiliates. All rights reserved. Cisco Public 166

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 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 167

139 Complete Your Online Session Evaluation Please complete your Online Session Evaluations after each session Complete 4 Session Evaluations & the Overall Conference Evaluation (available from Thursday) to receive your Cisco Live T-shirt All surveys can be completed via the Cisco Live Mobile App or the Communication Stations Don t forget: Cisco Live sessions will be available for viewing on-demand after the event at CiscoLive.com/Online 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 168

140 Continue Your Education Demos in the Cisco campus Walk-in Self-Paced Labs Lunch & Learn Meet the Engineer 1:1 meetings I am on call from 14:00-16:00 Today Related sessions 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 169

141 Q & A

142 Thank You

143

144 Appendix Overview of Lua & Lua Programming Additional SIP Normalization Scripts

145 Overview of Lua

146 What is Lua? A powerful, fast, lightweight, embeddable scripting language A fast language engine with a small footprint that can embed easily into other applications Lua has a simple and well documented API that allows strong integration with code in other languages Adding Lua to an application does not bloat it Many more details about Lua can be found online: Cisco and/or its affiliates. All rights reserved. Cisco Public 175