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

3 Agenda Why have this session? Brief review of SIP When things don t work Overview of SIP Transparency and Normalization Overview of Lua Normalization Scripts Case Study Conclusion 3

4 Why have this session? More systems than ever use SIP I counted 103 SIP Products on SIP Wikipedia Page Google Search for SIP Server yields 2.8 Million Hits Many 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! 4

5 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 Content of SIP Message Body What do we do when Fact #1 and Fact #2 are at odds in our deployment? 5

6 Typical Interop Scenario 6

7 Brief Review of SIP

8 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 response Main purpose of request Messages contain bodies 8

9 SIP Methods and Messages Call signaling performed by SIP Methods Six Standard 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 9

10 SIP Methods For Your Reference 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 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 10

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

12 Negotiating the Session For Your Reference 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 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

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

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

15 When things don t work

16 Identifying A Problem Goal is to make two SIP systems talk Both systems 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 for it to fail 16

17 Symptoms Two possible failure modes: Wait forever and get fast busy Call rejected right away These can be symptoms of numerous problems No bandwidth No DNS Bad Codecs Missing SIP Headers You will need to isolate the issue 17

18 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 (see next slide) Attend Paul Giralt s SIP Troubleshooting session for many more details: BRKUCC-2932 Troubleshooting SIP with Cisco Unified Communications 18

19 Getting SIP Headers Three main sources of SIP Header Information 1. Unified CM Trace Files 2. Unified CM Network Capture utils network capture 3. Network Packet Capture (Wireshark) 19

20 Example of Unified CM Trace File 17:38: //SIP/SIPTcp/wait_SdlReadRsp: Incoming SIP TCP message from on port with 1872 bytes: [563735,NET] 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/

21 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. 21

22 Using Wireshark 22

23 Determine Needed Results Make calls in both directions: Get SIP Captures of test calls in both directions 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 May have to research each system s SIP trunk requirements... Use your research and troubleshooting to determine the fix: Change the domain name of messages from misconfigured system Add a missing domain Remove headers that cause a failure 23

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

25 Overview of SIP Transparency & Normalization

26 Goals of SIP Transparency & Normalization Provide an interface for customization of SIP messages Initially conceived for Cisco Unified CM- Session Management (SME) Also supports Cisco Unified Communications Manager without SME Include a Lua execution environment Cisco Transparency & Normalization APIs Supports SIP Transparency and Normalization functionality 26

27 SIP Transparency Cisco 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 Allows 3 rd -Party Headers to pass through Unified CM 27

28 SIP Normalization The process of transforming inbound and outbound SIP messages Inbound message normalization makes the SIP message useable by Cisco Unified Communications Manager For Example, Cisco Unified CM supports Diversion header for carrying redirecting number information Other SIP devices use the History-Info header for this purpose Normalization transforms History-Info headers into Diversion headers so Unified CM recognizes the redirecting information Outbound normalization makes the SIP message useable by an external SIP device Example: Use normalization to transform Unified CM s Diversion headers into History-Info headers for a 3 rd -Party SIP PBX 28

29 Normalization Script Examples Reorder codecs in the SDP of an early offer Convert History-Info headers to Diversion headers 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 misconfigured system Switch to domain names if only IP address is used Add lines to SIP Message Body 29

30 What can a normalization script change? Normalization scripts can 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 30

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

32 Case Study-Problem Statement Customer has several PBXs trunked to Cisco Unified CM Unified CM interfaced to a 3 rd -party voice mail system via SIP Some 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: Reaching the voice mail of the station that finally forwarded the call to voice mail Not the voice mail of the station originally called Will solve this problem with SIP Normalization in just a little while 32

33 Overview of Lua

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

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

36 Lua Data Types Lua has the typical data types you would expect: Numbers Strings Boolean (true or false) Tables Tables are the only aggregate data type available in Lua 36

37 Lua Tables Tables are used for storing collections lists, arrays, and associative arrays These collections contain other objects including numbers, strings, or even other tables Tables are 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 exist to insert and remove table elements Library functions allow iterating over the contents of a table 37

38 Using Lua Tables for SIP Headers Tables are a key part of how Lua is used to 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" 38

39 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) 39

40 Looping With For For has two forms 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 Print the contents of a table For is passed an iterator function, pairs(), that supplies the values of each iteration for key,value in pairs({10, math.pi, "banana"}) do print(key, value) end banana 40

41 pairs and ipairs pairs() function iterates over 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 index-value pairs Elements returned in numeric order of the indices Non-integer keys are skipped Using the same table as in the example above: for index,value in ipairs(t) do print(index,value) end

42 Handy Lua Bits 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 --]] 42

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

44 Pop Quiz! True or False: Cisco created Lua just for processing SIP messages? A. True B. False Which Lua Libraries does Unified CM Normalization Scripts support? A. None of Them B. All of Them C. Complete String Library D. Subset of Base Library E. Both C & D 44

45 Overview of Normalization Scripts

46 Putting SIP Normalization to Work Scripts have message handlers to manipulate the actual SIP messages The message handler name tells you when it will be invoked and for what type of message For Example, you want your script to process INVITEs that Unified CM receives: Script should have an inbound_invite message handler Corresponding message handler will be invoked when an inbound INVITE is received A single parameter called msg represents the SIP Message Scripts use Cisco SIP Message API library to access and manipulate the msg parameter Let s look at a diagram 46

47 How a Normalization Script Gets Run 47

48 How a Normalization Script Gets Run 48

49 How a Normalization Script Gets Run 49

50 How a Normalization Script Gets Run 50

51 How a Normalization Script Gets Run 51

52 How a Normalization Script Gets Run 52

53 How a Normalization Script Gets Run 53

54 How a Normalization Script Gets Run 54

55 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 also run when Unified CM sends an INVITE 55

56 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

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

58 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 API to convert History-Info into Diversion Header function M.outbound_INVITE(msg) msg:removeheader("cisco-guid") end return M 58

59 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 to remove a header (in this case, Cisco-Guid) return M 59

60 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 Last line returns the Lua Table with the message handlers Line is required Cisco SIP Lua Environment uses table to identify the message handlers in the script 60

61 SIP Message Handler Formalities Each Normalization script provides a set of call-back functions to manipulate SIP messages These call-back functions are called message handlers The message handler s name indicates when a handler is invoked There can only be one Transparency and Normalization Script per Trunk Must define all needed 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 61

62 Request Message Handlers Request message handler is named: According to the message direction AND The SIP request method name The method name is in the 'request line' of the SIP message Request format: <direction>_<method> Examples: inbound_invite outbound_update 62

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

64 Using Wild Cards in Message Handler Names For Request Messages A wildcard ANY can be used in place of <method> The <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 The <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

65 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

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

67 Built-In Normalization Scripts 67

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

69 SIP Objects and Normalization Which SIP methods can be normalized? You can invoke a script 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

70 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

71 Case Study

72 Case Study-Calls going to the wrong mail box Customer has several PBXs trunked to Cisco Unified CM Unified CM interfaced to a 3 rd -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 72

73 Case study call flow 5 Call from PSTN for x Call from PSTN for x Call Forward All to x No Answer to Voice Mail 2 Call Forward All to x No Answer to Voice Mail Bad Result 8 Greeting for x Greeting for x2100 Good Result 73

74 Found the 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: Session-Expires: 1800 Diversion: Diversion: Contact: Content-Length: 0 Call goes to x1200 greeting instead of x

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

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

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

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

79 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 to Unified CM 2. From Add Screen, import from a text file or copy/paste 3. Save the Script 4. Apply the Script to the appropriate SIP trunk 79

80 Add a SIP Normalization Script 80

81 Import the Script 81

82 Configure and save the Script 82

83 Apply the Script to the SIP trunk 83

84 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 Expires: 180 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) 84

85 Other Normalization Script Examples Set-Silence Modifies SDP to set Silence Suppression off Add-Reply Adds a Header to the SIP INVITE 85

86 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 ") end msg:setsdp(sdp) end return M 86

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

88 Conclusion 88

89 Some Final Thoughts If you can identify the problem, you can fix it Traces and packet captures are your friend All normalization scripts have same beginnings Just need a few Lua basics Test, write, test, fix, test, then go to production 89

90 Resources Use these for additional details SIP Chapter in Unified CM System Guide: CM_BK_CD2F83FA_00_system-guide_chapter_ html Developer Guide for SIP Transparency and Normalization Cisco Interoperability Portal Cisco Developer Network 90

91 Questions? Thanks for Attending! 91

92 Recommended Reading for 92

93 Call to Action Visit the Cisco Campus at the World of Solutions to experience the following demos/solutions in action: Get hands-on experience with the following Walk-in Labs Meet the Engineer I m available all day Thursday for MTE meetings. Please use the scheduler! I am scheduled for walk-in meetings Thursday from Discuss your project s challenges at the Technical Solutions Clinics 93

94 94

95