Fixing SIP Problems with UC Manager's SIP Normalization Tools

Transcription

1

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

3 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

4 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

5 Typical Interop Scenario 5

6 Typical Interop Scenario 5

7 Typical Interop Scenario 5

8 Typical Interop Scenario 5

9 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

10 Brief Review of SIP

11 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

12 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

13 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

14 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:2 14

15 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=user IN IP t=0 0 m=audio 3456 RTP/AVP 0 c=in IP m=video 0 RTP/AVP 86 c=in IP

16 SIP Responses Look much like requests Headers, bodies Differ in top line Status Code Numeric, 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 (1XX): Informational (2XX): Success (3XX): Redirection (4XX): Client Error (5XX): Server Error (6XX): Global Failure Two groups : Provisional (Not reliable) : Final, Definitive Example 200 OK 180 Ringing

17 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

18 When things don t work

19 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

20 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

21 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

22 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

23 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/

24 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: Would you like to proceed [y/n]? y SFTP server IP: SFTP server port [22]: User ID: admin Password: ******** Download directory: Downloads. Transfer completed. 24

25 Using Wireshark 25

26 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

27 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

28 SIP Transparency & Normalization vs. IOS SIP Profiles

29 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

30 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 30

31 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

32 Overview of SIP Transparency & Normalization

33 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

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

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

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

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

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

39 Overview of SIP Profiles Normalization

40 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

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

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

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

44 Using Unified CM Normalization Scripts

45 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

46 How a Normalization Script Gets Run 47

47 How a Normalization Script Gets Run 48

48 How a Normalization Script Gets Run 49

49 How a Normalization Script Gets Run 50

50 How a Normalization Script Gets Run 51

51 How a Normalization Script Gets Run 52

52 How a Normalization Script Gets Run 53

53 How a Normalization Script Gets Run 54

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

70 Using IOS SIP Profiles Normalization

71 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

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

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

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

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

76 Example: Removing Headers Removing the Cisco-Guid Header Incoming INVITE SIP/2.0 Cisco-Guid: CUBE Outgoing INVITE SIP/2.0 voice class sip-profiles 20 request ANY sip-header Cisco-Guid remove response ANY sip-header Cisco-Guid remove 77

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

78 Example: Modifying Headers (1) Modify the originator SDP o= line Incoming INVITE SIP/2.0 o=ciscosystemssip-gw-useragent IN IP CUBE Outgoing INVITE SIP/2.0 o= IN IP voice class sip-profiles 30 request INVITE sdp-header Session-Owner modify CiscoSystems-SIP-GW-UserAgent - 79

79 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: @ 80

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

81 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 82

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

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

84 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

85 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

86 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

87 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. 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@ :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

88 Unified CM Normalization Case Study

89 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

90 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 91

91 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

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

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

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

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

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

97 Add a SIP Normalization Script 98

98 Import the Script 99

99 Configure and save the Script 100

100 Apply the Script to the SIP trunk 101

101 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) 102

102 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> 103

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@ >;reason=no-answer;privacy=off, Doe, John" <sip:1000@ >;reason=no-answer;privacy=off To get right voic box, really care about: Doe, John <sip:1000@ >;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@ >;reason=no-answer;privacy=off 104

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

105 Some Common Scripting Forms 106

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

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

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

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

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

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

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

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

114 Enabling Tracing from Unified CM 115

115 SIP Profiles Case Study 116

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

117 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 Cisco-Guid: meaningless outside Diversion: Content-Length: 0 Diversion Header contains internal Extension (x1100) 118

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

119 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: (1 Replace the match with : Complete SIP profile rule: request INVITE sip-header Diversion modify ( \1@

120 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!

121 Verify Results of SIP Profiles INVITE SIP/2.0 Via: SIP/2.0/TCP :5060;branch=z9hG4bK12b5cc229a69621 From: Mark" To: CSeq: 101 INVITE Cisco-Guid removed Diversion: Content-Length: 0 Diversion Header normalized to E

122 Bonus Case Study 123

123 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 124

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

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

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

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: Voice-Message: 5/0 (0/0) Fax-Message: 0/0 (0/0) 128

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

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

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

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

132 Conclusion 134

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? 135

134 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

135 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 137

136 Resources IOS SIP Profiles Configuration Note for CUBE SIP Normalization: SIP Configuration Guide (15M&T) CUBE Configuration Guide for SIP Profiles 138

137 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

138 Questions? Thanks for Attending! 140

139 Key References for SIP T&N

140 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 142

141 Recommended Reading for 143

142 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 144

143

144

145 Appendix Overview of Lua & Lua Programming Additional SIP Normalization Scripts 147

146 Overview of Lua

147 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:

148 A Brief Lua Tutorial This is not a programming course! Will cover some Lua basics to allow writing SIP T&N Scripts Will briefly consider: Lua Data Types Lua Tables Lua Control Structures Unified CM Support for Lua 150

149 Lua Data Types Lua has the typical data types you would expect: Numbers Strings Boolean (true or false) Lua has one data type you might not have heard of: Tables Tables are the only aggregate data type available in Lua 151

150 Lua Tables Tables are used for storing collections lists, arrays, and associative arrays Tables can contain other objects including numbers, strings, or tables Tables created using a pair of curly brackets { } t = { 1,1,2,3,5,8,13 } t[1] == 1 Note that table indexes begin at 1 Methods (functions) exist to insert and remove table elements Library functions allow iterating over the contents of a table 152

151 Using Lua Tables for SIP Headers Tables are a key part of how Lua can process SIP headers Tables are useful when more than one of a specific header is present For example: History-Info: <sip:userb@hostb?reason=sip;cause=408>;index=1 History-Info: <sip:userc@hostc?reason=sip;cause=302>;index=1.1 History-Info: <sip:userd@hostd>;index=1.1.1 Values from all three headers can be stored in a Table (history_info) history_info[1] == "<sip:userb@hostb?reason=sip;cause=408>;index=1" history_info[2] == "<sip:userc@hostc?reason=sip;cause=302>;index=1.1" history_info[3] == "<sip:userd@hostd>;index=1.1.1" 153

152 Lua Control Structures Lua has the typical programmatic control structures There are four main forms: 1. While: conditional looping statement with the form: while <exp> do <block> end 2. Repeat: conditional looping statement with the form: repeat <block> until <exp> 3. If: selection statement with the form: if <exp> then <block> { elseif <exp> then <block> } [ else <block> ] end 4. For: iterating statement (see the next slide) 154

153 Looping With For The two forms that for can take The first is for numerical iteration for <var> = <from_exp>, <to_exp> [, <step_exp>] do <block> end for count = 1,3 do print(count) end The second is for sequential iteration for <var> {, <var>} in <explist> do <block> end Example: Use for to print the contents of a table: For is passed an function, pairs(), that supplies the values of each iteration for key,value in pairs({10, math.pi, "banana"}) do print(key, value) end banana 155

154 pairs and ipairs Part of the standard Lua library pairs() function iterates over all key-value pairs items are NOT returned in a defined order for key,value in pairs(t) do print(key,value) end pi banana yellow ipairs() function iterates over only index-value pairs Returned in numeric order of the indices; Non-integer keys are skipped for index,value in ipairs(t) do print(index,value) end

155 Handy Lua Bits Available on Unified CM tostring() is handy for getting numbers back to strings for SIP headers Comments can be single or multiple lines: -- This is a comment --[[ This is a comment that crosses multiple lines --]] 157

156 Formatting Strings Often necessary to create a formatted string by combing other strings (concatenation) Two ways to accomplish with Lua: Concatenation Operator:.. String Library: string.format String library is more efficient and is recommended Example: host..... cisco.com makes a string: host.cisco.com string.format( %s.%s, host, cisco.com ) also makes: host.cisco.com 158

157 CUCM Lua Support Cisco SIP Lua Environment supports the following libraries: The complete string library A subset of the base library Other Lua libraries are not supported Cisco SIP Lua Environment provides Global environment for the scripts to use Default Lua global environment (_G) is not available to SIP T&N scripts Supported base library functions: ipairs pairs next unpack error type tostring 159

158 Additional SIP Normalization Scripts 160

159 Two Additional Normalization Scripts Set-Silence Modifies SDP to set Silence Suppression off Add-Reply Adds a Header to the SIP INVITE 161

160 SDP Example: Set Silence Suppression M = {} local function M.outbound_INVITE(msg) local sdp = msg:getsdp() if sdp then sdp = sdp:gsub("a=rtpmap:8 PCMA/8000", "a=rtpmap:8 PCMA/8000\r\na=silenceSupp:off ") msg:setsdp(sdp) end end return M 162

161 Add Header Example: Add Reply-To Header M = {} local top_level_domain = scriptparameters.getvalue("top-level-domain") local function add_reply_to_header(msg) if not top_level_domain then return end local rpid = msg:getheader("remote-party-id") if not rpid then return end local replacement = string.format("<sip:%s@%s>", "%1", top_level_domain) local reply_to = rpid:gsub("<sip:(.*)@[^>]*>.*", replacement) if reply_to then msg:addheader("reply-to", reply_to) end end M.outbound_INVITE = add_reply_to_header return M 163