Brkcol 2455

How to Use the SIP
Normalization Features
of Unified CM and
CUBE
Mark Stover, CCIE #6901
Consulting Systems Engineer
BRKCOL-2455
Cisco Spark
Questions?
Use Cisco Spark to chat
with the speaker after the session
How
1. Find this session in the Cisco Live Mobile App
2. Click “Join the Discussion”
3. Install Spark or go directly to the space
4. Enter messages/questions in the space
Cisco Spark spaces will be cs.co/ciscolivebot/#BRKCOL-2455

available until July 3, 2017.
© 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public
How Some Days Go…
BRKCOL-2455 © 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public 4
SIP is a Standard—What’s the Big Deal?
What Exactly is Standardized?
• 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…
• Different header used for similar function…
Typical Interop Scenario
What this Session is About
• Fact 1: SIP is a “Standard”
• Fact 2: SIP Configurations are not standardized
• What do we do when Fact #1 and Fact #2 are at odds in our deployment?
• We use the tools in our toolbox:
• Unified CM’s SIP Transparency and Normalization
• CUBE’s SIP Profiles
Agenda
• (Very) Brief Review of SIP
• When Things Don’t Work
• SIP Normalization Methods
• IOS SIP Profiles Normalization
• Unified CM Normalization Scripts
• Unified CM Transparency
• Conclusion
Brief Review of SIP
Basic Design
• SIP is a Client-Server Protocol
• Clients send requests, receive
responses
• Servers receive requests, send request
responses
Client Server
• Modeled after HTTP
• Text Encoded Protocol response
• Each request invokes method on

server
• Main purpose of request
• Messages may contain bodies
SIP Methods and Messages
• SIP Messages have distinct • Call signaling performed by SIP
parts: Methods
• IP/TCP/UDP Envelope • Six “Original” SIP Methods:
• SIP Header
• INVITE
• SIP Message Body
• ACK
• MIME-Encoded
• Session Description Protocol (SDP)
• OPTIONS
• Other relevant data • BYE
• CANCEL
• REGISTER
SIP Message Syntax
INVITE sip:alice@company.com SIP/2.0
• Many header fields from http From: Bob <sip:bob@university.edu>
To: Alice <sip:alice@company.com>
Via: SIP/2.0/UDP pc.university.edu
• In this example, Message Body Call-ID: 199723450578@192.169.100.100
contains a media description Content-type: application/sdp
• SDP – Session Description Protocol CSeq: 4711 INVITE
Content-Length: 187
v=0
o=CCM-SIP 2000 1 IN IP4 192.168.100.100
s=SIP Call
c=IN IP4 192.168.200.200
m=audio 26542 RTP/AVP 0 8 18 101
a=rtpmap:0 PCMU/8000
a=ptime:20
a=mid:1
c=IN IP6 2001:0db8:aaaa::0987:65ff:fe01:234b
m=audio 26662 RTP/AVP 0
a=mid:2
SIP Responses
• Status Code Classes • Look much like requests
• 100 - 199 (1XX): Informational • Headers, bodies
• 200 - 299 (2XX): Success
• Differ in top line
• 300 - 399 (3XX): Redirection
• Status Code
• 400 - 499 (4XX): Client Error • Numeric, 100 - 699
• 500 - 599 (5XX): Server Error • Meant for computer processing
• 600 - 699 (6XX): Global Failure • Protocol behavior based on 100s digit
• Other digits give extra info
• Two groups • Reason Phrase
• 100 - 199: Provisional (Not reliable) • Text phrase for humans
• 200 - 699: Final, Definitive • Can be anything
• Example
• 200 OK
• 180 Ringing
SIP Transactions
• Fundamental unit of messaging exchange

• Request
• Zero or more provisional responses
• Usually one final response
• Maybe ACK
• All signaling composed of independent

transactions
• Transactions identified by Cseq
• Sequence number
• Method tag
• Complete call from INVITE to BYE is a dialog

• Defines a call leg
• Maintains the same call-id and tags
When things don’t
work
Identifying A Problem
• Goal is to make two SIP systems ‘talk’
• Both systems already configured with:
• Appropriate Network Configurations
• Trunk configuration to reach the other system
• Routing (dial plan) information in place
• Make a call From: 1001 on System A; To: 2001 on System Z

• Both phones exist, are configured, and are able to make other calls
• And wait…
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
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 Tuesday morning…so be sure to check the recording!
Getting SIP Messages
Sources of the SIP Messages you need
1. Unified CM Trace Files
2. Unified CM Network Capture
• “utils network capture”
3. Cisco IOS Packet Capture
• IP Traffic Capture Feature
4. Cisco IOS call-signaling debugs
5. Network Packet Capture (Wireshark)
Example of Unified CM Trace File
17:38:59.871 |//SIP/SIPTcp/wait_SdlReadRsp: Incoming SIP TCP message from 192.168.100.100 on port 65067 with 1872 bytes:
INVITE sip:4125551212@192.168.200.200:5060 SIP/2.0
Via: SIP/2.0/TCP 192.168.100.100:5060;branch=z9hG4bK1266281727
From: "Alice" <sip:918145551212@192.168.100.100>;tag=3E6D44CC-CE4
To: <sip:4125551212@192.168.200.200>
Date: Wed, 12 Oct 2011 21:38:59 GMT
Call-ID: 6E2FCA41-F45111E0-95FBF44A-5979DA79@192.168.100.100
Supported: 100rel,timer,resource-priority,replaces,sdp-anat
Cisco-Guid: 1847785776-4098953696-3044132940-1967707264
User-Agent: Cisco-SIPGateway/IOS-12.x
CSeq: 101 INVITE
Timestamp: 1318455539
Expires: 180
Allow-Events: telephone-event
Content-Type: multipart/mixed;boundary=uniqueBoundary
Mime-Version: 1.0
Content-Length: 929
--uniqueBoundary
Content-Type: application/sdp
Content-Disposition: session;handling=required
v=0
o=CiscoSystemsSIP-GW-UserAgent 4535 5918 IN IP4 192.168.100.100
s=SIP Call
c=IN IP4 192.168.100.100
t=0 0
m=audio 17620 RTP/AVP 0 100 101
c=IN IP4 192.168.100.100
a=rtpmap:0 PCMU/8000
Using Wireshark
Determining the 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
• Redirecting number is an internal extension
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 on incorrectly configured system
• Add a missing domain
• Remove headers that cause a failure
Write, Test, and Deploy
• Formulate a plan to ‘fix’ the SIP headers
• 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
SIP Transparency
& Normalization vs.
IOS SIP Profiles
SIP Transparency & Normalization
Unified CM’s Normalization Tool
• Provides an interface for customization of SIP messages
• Initially created for Cisco Unified CM Session Management Edition (SME)
• Supports Cisco Unified Communications Manager without SME
• Available in Release 8.5 and later
• Includes:
• A Lua execution environment
• SIP Transparency & Normalization APIs
• Supports:
• Transparent passing of SIP information from one call leg to another
• Normalizing SIP Messages to provide interoperability
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
• Resolve incompatibilities between SIP devices inside the enterprise network
• Use IOS feature navigator to confirm minimum version requirements

• First available in IOS 12.4(15)XZ
• Uses regular expressions to match and replace fields in SIP messages
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 10.0.1)
• 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)
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
Overview of SIP Profiles
Normalization
IOS SIP Profiles
Unified Border Element’s (CUBE) Normalization Tool
• CUBE supports normalization of SIP messages
• Includes add/remove/modify/copy of headers in a SIP message
• SIP Profiles feature added in 12.4(20)T and enhanced in 15.1(3)T and 15.4(1)T
• Inbound SIP Profiles available in IOS 15.4(2)T
• Inbound normalization takes place before regular SIP call processing
• CUBE acts as if it directly received the normalized message
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
Performance Impact
• Keep in mind there is some performance impact from SIP Profiles
• Mainly memory impacting, but some CPU cycles are required
• Plan for 5% performance impact for most SIP Profiles
• Large Profiles will have up to a 6% impact
• Easy (and Conservative) rule of thumb is to ensure you have 10% headroom
before turning on Profiles
Using IOS SIP
Profiles
Normalization
Putting SIP Profiles to Work
Using profiles to manipulate SIP messages
• SIP profiles can be configured at the dial-peer or global level
• Message modification (like the rest of IOS) uses a subset of standard regular
expressions to match and replace fields
• Changes made to messages are not remembered by CUBE
• Content-length field is recalculated after normalization is applied
Just one more SIP Profiles “Feature”
• SIP Profile Modify can also be used to change a header name to its compact
form
• Useful if you have a system that has a restriction on the size of a SIP message
• By default, IOS never sends the compact form
• It can receive either long or short form of the header names
• For example, change From: header to the f: header
• Note: SIP Profiles cannot modify compact form headers
Some Useful SIP Profiles Details
• When multiple rules apply to the same header
• the second rule applies to the result string of the first rule
• SIP Profiles support the ANY wild card
• Indicates that a rule applies to any message within the specified category (SIP or SDP)
• Using ANY in place of a SIP Method makes the rule apply to all SIP Methods
• Dealing with multiple INVITEs during a call:

• Rules for an INVITE message only apply to the first INVITE in the call
• REINVITE support in rules allow you to process the subsequent INVITEs
• Remember! You have to know the call flow includes RE-INVITEs and normalize them!
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
Example: Adding Headers
Adding a Retry-After Header
Incoming Outgoing
480 Temporarily Not Available 480 Temporarily Not Available

CUBE
Retry-After: 60
voice class sip-profiles 10

response 480 sip-header Retry-After add “Retry-After: 60”
Example: Adding Headers
Adding a Retry-After Header
Incoming Outgoing
480 Temporarily Not Available 480 Temporarily Not Available

CUBE
Retry-After: 60

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
Example: Removing Headers
Removing the Cisco-Guid Header
Incoming Outgoing
INVITE sip:5551000@sip.com:5060 SIP/2.0 INVITE sip:5551000@sip.com:5060 SIP/2.0

CUBE
Cisco-Guid: 3386501632-0000065536

rule 10 request ANY sip-header Cisco-Guid remove
rule 20 response ANY sip-header Cisco-Guid remove
Note the use of “ANY” as a wildcard to match any

request or response
Using SIP Profiles: Modifying Messages
• Add fixed strings to existing header values
• Matched substrings can be part of replacement patterns
• Used for:
• Adding parameters to a header
• Modifying the URI
• Changing SDP
Brief Look at RegEx for Modify (1/2)
Modify requires you to match something…
• Given: “To: sip:anonymous@192.168.200.200”
• How do I replace “anonymous” with a number?
• Step 1: Find the relevant and unique parts of string:
• “sip:anonymous@192.168.200.200”
• Step 2: Create a string that matches:
• “sip:anonymous@”
• Using our To: header example:
• “sip:anonymous@” has a positive match: “sip:anonymous@”
Brief Look at RegEx for Modify (2/2)
Replace what you matched
• Given: “To: sip:anonymous@192.168.200.200”
• We matched using “sip:anonymous@” to get “sip:anonymous@”
• Replacement number is: “5551212”
• We have to ‘REPLACE’ the entire string that was matched:
• “sip:5551212@” becomes the replacement string
• General Format: modify “string_to_match” “replacement_string”
• modify “sip:anonymous@” “sip:5551212@”
Example: Modifying Headers (1)
Modify the originator SDP o= line
Incoming Outgoing

CUBE
o=CiscoSystems-SIP-UserAgent 4535 5918 IN IP4 192.168.100.100 o=UA 4535 5918 IN IP4 192.168.100.100

request INVITE sdp-header Session-Owner modify “CiscoSystems-SIP-UserAgent” “UA”
Example: Modifying Headers (2)
Change anonymous to a directory number
Incoming Outgoing

CUBE
From: <sip:anonymous@public.com:5060> From: <sip:5551212@public.com:5060>

request INVITE sip-header From modify “sip:anonymous@" “sip:5551212@”
Using SIP Profiles: Copying Header Information
• Matched substrings can be ‘saved’ in a variable
• Will be used to copy information 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
Revisiting RegEx for Copy / Modify
Generic LHS match
• Common Search Pattern for the LHS (left hand side) of a SIP URI:
• “sip:.*@”
• “.” matches any single character except newline
• “*” zero or more of the preceding “.”
• Can also capture a substring match with “()”: “sip:(.*)@”
• IOS Copy-List Variables can be assigned these substring matches
Assigning the Match to a Variable
Using the Copy command
• For example:
• “To: Tom Jones <sip:5551000@sip.com:5060>”
• SIP Profile command:
• request INVITE sip-header To copy "sip:(.*)@" u01
• u01 now contains: “5551000”
Example: Copying Headers
Copying phone number to Request URI
Incoming Outgoing
INVITE sip:tjones@sip.com:5060 SIP/2.0 INVITE sip:5551000@sip.com:5060 SIP/2.0

CUBE
To: tjones <sip:5551000@sip.com:5060> To: tjones <sip:5551000@sip.com:5060>

request INVITE sip-header To copy "sip:(.*)@" u01
request INVITE sip-header SIP-Req-URI modify “sip:(.*)@" "sip:\u01@"
For Your
Inbound versus Outbound SIP Profiles Reference
• 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
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
Peer Header Copying
Peer Header Copying
Peer Header Copying
Peer Header Copying
Peer Header Copying
voice class sip-copylist 1
sip-header To
dial-peer voice 1 voip
description incoming SIP Trunk
voice-class sip copy-list 1
request INVITE peer-header sip To copy “(;x-dept=sales)” u01
request INVITE sip-header To modify “$” “\u01”
description outgoing SIP Trunk
voice-class sip profiles 1001
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:

rule 10 request ANY sip-header Cisco-Guid remove
rule 20 response ANY sip-header Cisco-Guid remove
Troubleshooting Commands
Debug and Show
• Debug commands:
• debug ccsip info
• debug ccsip feature sip-profile
• debug ccsip error
• debug ccsip message
• Show commands:
• Verify the SIP Profile is assigned to a dial-peer:
show dial-peer voice 1 | include sip profile
Troubleshooting
• Sample sip profile to change user part of From header from anonymous to some value.
request INVITE sip-header FROM modify "sip:anonymous@" "sip:1234@"
Sip profile invoked for modifying
INVITE sip:1111@192.168.1.1:5060 SIP/2.0 the message is displayed here
Via: SIP/2.0/UDP 192.168.2.1;branch=z9hG4bK-24227-1-0
From: anonymous <sip:anonymous@192.168.2.1:9232>;tag=1
To: 1111 <sip:1111@192.168.1.1:5060>
Call-ID: 1-24227@192.168.2.1 Sample incoming message with
From header set to anonymous.
Sample log:
Jan 17 18:24:00 EST: //-1/xxxxxxxxx/SIP/Info/verbose/64/ccsip_inbound_profile_populate_callinfo_in_ccb: Dial-
peer 1 is used for inbound profiles config
Jan 17 18:24:00 EST: //-1/xxxxxxxxx/SIP/Info/info/64/sipSPISetSipProfilesTag: voice class SIP Profiles inbound
tag is set : 1
Jan 17 18:24:00 EST: //-1/xxxxxxxxx/SIP/Info/info/64/sip_profiles_application_modify_remove_header: Header
before modification : From: sipp <sip:anonymous@192.168.2.1:9232>;tag=1
Jan 17 18:24:00 EST: //-1/xxxxxxxxx/SIP/Info/info/64/sip_profiles_application_modify_remove_header: Header
after modification : From: sipp <sip:1234@192.168.2.1:9232>;tag=1
From header after modification
SIP Profile Test Tool
• Web-based tool to validate SIP Profiles
• https://cway.cisco.com/tools/SipProfileTest/
• 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
https://cway.cisco.com/tools/SipProfileTest/
More Information - https://supportforums.cisco.com/document/13058446/sip-profile-test-tool

Dialed Number Analyzer (DNA) for CUBE
https://cway.cisco.com/tools/DNACube
Features Use Cases
• Emulation of CUBE • Dial-Plan validation
• E164 and URI Call Routing • Understand Call routing logic

Features
• Pre-deployment config validation
• 2 Input modes – E164 and SIP
• Interoperability Testing
Message
• 10 Call Routing features
• Output SIP Invite Generation
• Real-time config editing and testing
SIP Profiles
Case Study
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…
SIP Headers for Forwarded Call
INVITE sip:4125553000@192.168.1.1:5060 SIP/2.0
Via: SIP/2.0/TCP 192.168.2.2:5060;branch=z9hG4bK12b5cc229a69621
From: “Mark" <sip:8145551212@192.168.2.2>;tag=16101269~0458486e-22501993c802-145785687
To: <sip:4125553000@192.168.1.1> Cisco-Guid
CSeq: 101 INVITE meaningless outside
Cisco-Guid: 3386501632-0000065536-0002912165-2768792774 enterprise
Diversion: <sip:1200@192.168.2.2>;reason=unconditional;privacy=off;screen=yes
Content-Length: 0 Diversion Header
contains internal
Extension (x1200)
Tackling the Problem (1)
Removing Cisco-Guid
• Removing Cisco-Guid from all requests and responses is straightforward

• No downside on trunks to SIP SP since it has no meaning outside enterprise
• SIP profile rules:
request ANY sip-header Cisco-Guid remove

response ANY sip-header Cisco-Guid remove
Tackling the Problem (2)
Modifying Diversion Header
• Need to add the required E.164 digits to the extension in the Diversion Header
• Take advantage of the dial-plan
• All internal extensions have the format 1xxx
• Insert the digits 814555 in front of the extension
• Match the “1200@” in Diversion Header and capture the extension:

• “sip:(1…)@”
• Replace the match with “8145551200@” using the captured digits (\1):
• “sip:814555\1@”
• Complete SIP profile rule:
request INVITE sip-header Diversion modify “sip:(1…)@” “sip:814555\1@”
Complete the Configuration
Applying the SIP Profile rules to outgoing dial-peer
• Sample Configuration:

request ANY sip-header Cisco-Guid remove
response ANY sip-header Cisco-Guid remove
request INVITE sip-header Diversion modify “sip:(1…)@” “sip: 814555\1@”
!
!
Verify Results of SIP Profiles
INVITE sip:4125553000@192.168.1.1:5060 SIP/2.0
From: “Mark" <sip:8145551212@192.168.2.2>;tag=16101269~0458486e-22501993c802-145785687
To: <sip:4125553000@192.168.1.1>
Cisco-Guid removed
CSeq: 101 INVITE
Diversion: <sip:8145551200@192.168.2.2>;reason=unconditional;privacy=off;screen=yes
Content-Length: 0
Diversion Header
normalized to E.164
Overview of SIP Transparency &
Normalization
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 should pass through transparently
• Unified CM Transparency feature allows you to take information from known

headers and preserve it as the call legs pass
• Unified CM can transparently pass:
• Parameters
• Unknown headers
• Unknown content-bodies
• Will look more closely at Transparency later in the presentation
SIP Normalization
or, How do I make this $*&#^! SIP message do what I want?
• You can normalize inbound or outbound SIP messages (or both)
• Inbound normalization makes a SIP message “useable” by Unified CM
• Outbound normalization makes a message “useable” by another SIP device
Inbound Normalization
• A SIP interoperability question might be:
• How do we handle redirecting numbers when calls are forwarded between systems?
• Unified CM uses the Diversion: header for any redirecting numbers
• Other SIP devices use the History-Info: header for this purpose
• Inbound Normalization can transform History-Info: headers into
Diversion: headers
• Allows Unified CM to maintain all the redirecting numbers even for calls between
systems
Outbound Normalization
• For calls forwarded by Unified CM, redirecting numbers should be maintained
• Outbound normalization transforms Unified CM’s Diversion: headers into
History-Info: headers for another system
What can a normalization script change?
• 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
Performance Impact
• Keep in mind there is some performance impact from SIP Transparency and
Normalization.
• For extensive use of the feature, there is about 10% performance impact
• Consider this during any sizing exercises
Using Unified CM
Normalization
Scripts
Understanding Message Handlers
Foundation of manipulating SIP messages
• Each Message Handler has a unique name (per script)
• The name will tell you:
• When the Handler will be invoked (inbound or oubound)
• What SIP message will be Handled (the SIP Method(s))
• For example, To process the INVITEs received by Unified CM:

• Script needs an “inbound_INVITE” message handler
• That message handler will run when an inbound INVITE is received
• Parameter (msg) passed to the Message Handler with the SIP Message
• Normalization Scripts use API to access and manipulate the message
How a Normalization Script Gets Run
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
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
Focus on SIP Normalization Script - 1
M = {}
• Creates an empty Lua Table called ‘M’
• All Message Handlers in this script are ‘added’ to this table
• Note that ‘M’ is also the name of the Lua Module
end
end
return M
M = {}
end
• Inbound INVITE Message Handler (added to “M”)
• Inbound SIP Message accessed through msg
• Uses a Cisco API call to perform the actual conversion
end
return M
M = {}
End
end
• Outbound INVITE Message Handler (added to ‘M’)
• Outbound SIP Message accessed through msg
• Uses Cisco API call to remove a header (in this case, Cisco-Guid)
return M
M = {}
end
end
return M
• Line is required
• Returns the Lua Table (M) containing the message handlers
• Unified CM adds it to execution environment for assigned SIP entity
• Cisco SIP Lua Environment uses Table ‘M’ to identify the message handlers
SIP Message Handler Formalities
• Each Transparency and Normalization script provides:
• Set of message handler(s) to manipulate SIP messages
• The message handler naming and assignments indicates which handler to use
• Only one Script can be assigned to a SIP Entity

• All message handlers have to be in that single script
• More than one handler is permitted per 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…
Request Message Handlers
• Request message handler is named by combining two (2) items:
1. the message direction
2. the SIP method
• SIP Method comes from the 'request line' of the message
• Request handler format: <direction>_<method>
• Examples:
• inbound_INVITE
• outbound_UPDATE
Using Wild Cards in Request Message Handlers
• Recall that Request Handlers are named: <direction>_<method>
• May want your handler to apply to any SIP method:
• Wildcard ANY can be used in place of <method>
• Examples of valid Request Handler names:
• M.inbound_INVITE
• M.inbound_ANY
• M.outbound_ANY
• Handler <direction> does NOT support a wild card

• Invalid Name: M.ANY_INVITE
<direction> does NOT support a wild card
Response Message Handlers
• Response message handler named by combining 3 items:
1. the message direction
2. the response code
3. the SIP method
• Method name found in the CSeq header
• Response format: <direction>_<response code>_<method>
• Examples:
• inbound_183_INVITE
• inbound_200_INVITE
• outbound_200_UPDATE
Using Wild Cards in Response Message Handlers
• Rules for the ANY wild card in <direction>_<response code>_<method>
• Replace <method> with ANY
• Replace <response code> with ANY
• Both <method> AND <response code> can be ANY
• <direction> does not support a wild card
• Additional restrictions for Handlers using a specific <response code>

• <method> cannot be ANY with a specific <response code>
• A wildcard character ( X ) can replace digits within a <response code>
• Probably easier to look at some examples…
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>
For Your
Rules for picking a message handler 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
Built-In Normalization Scripts
You can also find Transparency & Normalization scripts in some Interoperability guides.
APIs for SIP and SDP Normalization For Your
• SIP Messages APIs: Reference
• 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
Unified CM
Normalization
Case Study
Case Study
Calls going to the wrong mail box
• Customer has several PBXs trunked to Cisco Unified CM
• Unified CM interfaced to a 3rd-party voice mail system via SIP
• Calls sent to voice mail after multiple call forwards
• Most calls were going to the correct voice mail box
• Calls from one PBX were not
• In the “broken” case, calls were going to the voice mail box of the last station the
call was forwarded to
• Let’s look in detail at these call flows…
Case study call flow
5 Call from 1
Call from
PSTN for PSTN for
x1100 x2100
7 No Answer
to Voice 3 No Answer
Mail
to Voice
Mail
6 Call 2 Call
Forward All Forward All
to x1200 to x2200
Bad Result Greeting for Greeting for Good Result
x1200 x2100
8 4
Problem: SIP header from call to wrong mail box
INVITE sip:4125553000@192.168.1.1:5060 SIP/2.0
From: "PSTN" <sip:8145551212@192.168.2.2>;tag=16101269~0458486e-22501993c802-145785687
To: <sip:4125553000@192.168.1.1>
Date: Wed, 19 Dec 2012 16:45:01 GMT
Call-ID: c9d9ea00-eef16a0d-46c59c-a5086cc6@192.168.2.2
Supported: 100rel,timer,resource-priority,replaces
User-Agent: Cisco-CUCM8.5
Allow: INVITE, OPTIONS, INFO, BYE, CANCEL, ACK, PRACK, UPDATE, REFER, SUBSCRIBE, NOTIFY
CSeq: 101 INVITE
Expires: 180
Call-Info: <sip:192.168.2.2:5060>;method="NOTIFY;Event=telephone-event;Duration=500"
Cisco-Guid: 3386501632-0000065536-0002912165-2768792774
Call goes to
Diversion: <sip:4125551200@192.168.2.2>;reason=no-answer;privacy=off;screen=yes x1200 greeting
Diversion: <sip:4125551100@192.168.2.2>;reason=unconditional;privacy=off;screen=yes instead of x1100
Contact: sip:8145551212@192.168.2.2:5060;transport=tcp
Content-Length: 0
What the script will have to accomplish
Keep it simple &

just remove the
headers we don’t
need for voice mail
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
Add logic to remove extra Diversion Headers
-- Get all Diversion Headers
local DiversArray = msg:getHeaderValues("Diversion“)
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
-- remove a Diversion Header
msg:removeHeaderValue("Diversion", DiversArray[I])
end
end
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 -- # 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
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. Configure and Save the Script
4. Apply the Script to the appropriate SIP trunk
1. Add a SIP Normalization Script
2. Import Script from Text File
3. Configure and Save the Script
4. Apply the Script to the SIP trunk
Verify that script fixes the problem
INVITE sip:4125553000@192.168.1.1:5060 SIP/2.0
From: "PSTN" <sip:8145551212@192.168.2.2>;tag=16101269~0458486e-22501993c802-145785687
To: <sip:4125553000@192.168.1.1>
Date: Wed, 19 Dec 2012 16:45:01 GMT
Call-ID: c9d9ea00-eef16a0d-46c59c-a5086cc6@192.168.2.2
Supported: 100rel,timer,resource-priority,replaces
User-Agent: Cisco-CUCM8.5
Allow: INVITE, OPTIONS, INFO, BYE, CANCEL, ACK, PRACK, UPDATE, REFER, SUBSCRIBE, NOTIFY
CSeq: 101 INVITE
Call-Info: <sip:192.168.2.2:5060>;method="NOTIFY;Event=telephone-event;Duration=500"
Cisco-Guid: 3386501632-0000065536-0002912165-2768792774
Session-Expires: 1800 Call now goes to
Diversion: <sip:4125551100@192.168.2.2>;reason=unconditional;privacy=off;screen=yes x1100 greeting
Contact: sip:8145551212@192.168.2.2:5060;transport=tcp (1 Diversion Header)
Content-Length: 0
Sometimes, You Have to Revisit Your Own Work
See the same symptoms, but find a different cause
• Another customer had calls to voicemail going to the wrong destination

• Still have Multiple Diversion Headers…. found a different format for the names
Diversion: “Doe, John" <sip:jdoe@192.168.3.3>

Diversion: “Doe, John" <sip:1000@192.168.3.3>
• Because of the comma in the Header:
• Causes unexpected results with the SIP Normalization API
• Root Cause:
• Multiple Occurrence of the same Header are parsed into a Lua Table
• Processing relies on commas and <CR><LF> between header instances
• In the example above, the API thinks there are four (4) Diversion headers
Some Common
Scripting Forms
Navigating Script Formats
• Sample Normalization Scripts are available
• Developer Guide
• Interoperability Guides
• Unified CM
• Can be confusing because scripts don’t have same format

• Scripts follow two basic formats (that we’ll examine in detail):
• 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)
Name = Direction + Method
M = {}
... (function code) ...
end
return M
• Good:
• Know exactly what SIP messages will be acted on
• Bad:
• Cannot reuse the function for anything else
• Example: Repeat the same code for same processing on outbound INVITEs
Example: Name with Purpose
M = {}
local function add_reply_to_header(msg)
... (function code) ...
end
M.outbound_INVITE = add_reply_to_header
return M
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 that a
particular function will be used for
Using Script Parameters
• SIP T&N allows you to set script parameters
• Available in Unified CM Admin pages
• Configurable for each SIP entity that uses the script
• Allows deployment of a ‘generic’ script

• Provide script with settings at load time
• Use same script in multiple locations (trunks, devices, profiles) without rewriting
local myDomain = scriptParameters.getValue("LocalDomain")
local fqdn = host .. “.” .. myDomain
Setting a Script Parameter
• Access Unified CM Admin
• Set on the SIP Entity’s
Configuration page
• Must know the Parameter Name
used by the script
• Parameters are not indexed by
Unified CM
• No drop-down list provided for you
to pick from
Enabling Tracing in Scripts
• Scripts can write trace information to Unified CM logs
• Tracing must be enabled in BOTH:
• Your script
• Unified CM Admin
• Allows you to 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
Enabling Tracing from Unified CM
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(" -- processing the Call-ID")
Bonus Case
Study and
More
Normalization
Examples
MWI Lights Don’t Light
Adapting SIP Notify
• Problem:
• Unity Connection provides voicemail for user on multiple vendor PBXs
• Unity Connection homed to Unified CM SME
• SME connects to other PBXs via SIP
• One vendors PBX fails to update MWI status
• Initial Troubleshooting:
• Gathered traces: SIP Notify being sent to system
• Opened case with vendor
• Software release running on system needs “Message-Account” in the Notify
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
• Can solve this with CUBE or Unified CM

• Try with Unified CM Normalization…
• 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…
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
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()
Updating the Content Body
Before and After
• Content-Body from Unity Connection:
Messages-Waiting: yes
Voice-Message: 5/0 (0/0)
Fax-Message: 0/0 (0/0)
• Content-Body desired:
Messages-Waiting: yes
Message-Account: sip:5000@10.10.10.10
Voice-Message: 5/0 (0/0)
Fax-Message: 0/0 (0/0)
Build the Script Basics
M = {}
function M.outbound_NOTIFY(msg)
...
end
return M
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)
“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)
For Your
Taking a Look at the String Operation Reference
• Breaking down the key string operation

• string.gsub(cb, "Messages%-Waiting%:%s%w+%c+", "%0" .. ma)
• The Lua string.gsub method 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
Example: Dealing with Phone Displays
Adapting content of SIP INVITE to device types
• Some SIP phones have limited display space
• Unified CM delivers provisioned name & number to phone
• If name and number do NOT both fit on the screen:
• Users prefer to see the number
Solution Basics
• Use string matching to remove calling name in 'From:' header
header frmhdr = msg:getHeader(“From”)

newfrmhdr = string.gsub(frmhdr , “.*<sip:” , “<sip:”)
• Then, use the API to modifyHeader:
msg:modifyHeader(“From”, newfrmhdr)
Validating the Solution
• Testing showed the 'From:' header in INVITE no longer has name
...but…
• UPDATE message sent during the dialog still includes name
• A slight modification allows script to handle both methods
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
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
Unfortunately, Not a Job for SIP Profiles…
• You might think you could:
rule 10 request ANY sdp-header Audio-Attribute remove
rule 20 response ANY sdp-header Audio-Attribute remove
• Cannot determine which 'Audio-Attribute' to remove from the m=audio line

• So, all the a= attributes get removed…
Using Unified CM Transparency
SIP Objects and Transparency support
Transparency is limited to INVITE dialogs on SIP trunks
• Transparency scripts can pass • These SIP objects do not support
almost any information in a SIP Transparency scripts
message • SUBSCRIBE dialogs
• SIP Headers • PUBLISH
• SIP Parameters • out-of-dialog REFER
• Content Bodies • out-of-dialog unsolicited NOTIFY
• MESSAGE
Why Use SIP Transparency?
Why Use SIP Transparency?
Unified CM acting as SME will begin routing calls
between PBX-A and PBX-Z…
What Unified CM Does to Your 181…
What We Want Unified CM to do…
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
• Goal is to preserve the “181 – Call is being forwarded”
• Therefore…
• Why not turn it into an unknown header when it enters Unified CM
• and Restore the 181 as it leaves Unified CM
On Inbound
1. Runs when Unified CM B = {}
receives a 181 Response in function B.inbound_181_INVITE(msg)
an INVITE dialog local pt = msg:getPassThrough()
local rson = msg:getHeader("Reason")
2. Create the PassThrough if pt and rson
message block then
3. Get the “Reason” header pt:addHeader("X-Reason", rson)
contents end
end
4. Add the contents to an return B
unknown “X-Reason” header
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
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
Conclusion
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?
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
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
Resources
Unified CM Transparency & Normalization
• SIP Chapter in Unified CM System Guide:

• http://www.cisco.com/en/US/docs/voice_ip_comm/cucm/admin/10_0_1/ccmsys/CUCM_
BK_SE5FCFB6_00_cucm-system-guide-100_chapter_0101000.html
• Developer Guide for SIP Transparency and Normalization
• http://www.cisco.com/en/US/docs/voice_ip_comm/cucm/sip_tn/9_1_1/sip_t_n.html
• Cisco Interoperability Portal
• http://www.cisco.com/go/interoperability
• Cisco Developer Network
• http://developer.cisco.com/
Resources
IOS SIP Profiles
• Configuration Note for CUBE SIP Normalization:

• http://www.cisco.com/c/en/us/support/docs/voice-unified-communications/unified-
border-element/105624-cube-sip-normalization.html
• SIP Configuration Guide (15M&T)
• http://www.cisco.com/c/en/us/td/docs/ios-xml/ios/voice/sip/configuration/15-mt/sip-
config-15-mt-book.html
• CUBE Configuration Guide for SIP Profiles
• http://www.cisco.com/c/en/us/td/docs/ios-xml/ios/voice/cube/configuration/cube-
book/voi-sip-param-mod.html#reference_869720458984374988879107666015624
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
Complete Your Online
Session Evaluation
• Give us your feedback to be
entered into a Daily Survey
Drawing. A daily winner will
receive a $750 gift card.
• Complete your session surveys
through the Cisco Live mobile
app or on www.CiscoLive.com/us.
Don’t forget: Cisco Live sessions will be

available for viewing on demand after the
event at www.CiscoLive.com/Online.
© 2017 Cisco and/or its affiliates. All rights reserved. Cisco Public
Continue Your Education
• Demos in the Cisco campus
• Walk-in Self-Paced Labs
• Lunch & Learn
• Meet the Engineer 1:1 meetings
• Related sessions
Q&A
Thank you
Appendix
• Overview of Lua & Lua Programming

• Additional SIP Normalization Scripts
Overview of Lua
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:
• http://www.lua.org/about.html
• http://www.lua.org/manual/5.2/
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
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
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
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"
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)
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
1 10
2 3.14159
3 banana
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
3 10
1 3
4 17
2 7
pi 3.14159
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
1 3
2 7
3 10
4 17
Handy Lua Functions
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
--]]
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”
CUCM Lua Support
• Cisco SIP Lua Environment supports • Supported base library functions:
the following libraries: • ipairs
• The complete string library • pairs
• A subset of the base library • next
• Other Lua libraries are not supported • unpack
• error
• Cisco SIP Lua Environment provides
• type
• Global environment for the scripts to
use • tostring
• Default Lua global environment (_G) is
not available to SIP T&N scripts
Additional SIP Normalization Scripts
Two Additional Normalization Scripts
• Set-Silence – Modifies SDP to set Silence Suppression off
• Add-Reply – Adds a Header to the SIP INVITE
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
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

Brkcol 2455

Uploaded by

Copyright:

Available Formats

Brkcol 2455

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Brkcol 2455

Uploaded by

Copyright:

Available Formats

How to Use the SIP

Cisco Spark spaces will be cs.co/ciscolivebot/#BRKCOL-2455

• Each request invokes method on

• Fundamental unit of messaging exchange

• All signaling composed of independent

• Complete call from INVITE to BYE is a dialog

• Make a call From: 1001 on System A; To: 2001 on System Z

• These can be symptoms of numerous problems

• Packet Capture is your friend

3. May have to research each system’s SIP trunk requirements

• Use IOS feature navigator to confirm minimum version requirements

• SDP Pass-Through and Normalization in IOS 15.6 (1)T (CUBE 11.5)

Feature IOS SIP Profiles SIP T&N

• Dealing with multiple INVITEs during a call:

480 Temporarily Not Available 480 Temporarily Not Available

voice class sip-profiles 10

480 Temporarily Not Available 480 Temporarily Not Available

voice class sip-profiles 10

Note that, rule tagging is a new CUBE

INVITE sip:5551000@sip.com:5060 SIP/2.0 INVITE sip:5551000@sip.com:5060 SIP/2.0

voice class sip-profiles 20

Note the use of “ANY” as a wildcard to match any

INVITE sip:5551000@sip.com:5060 SIP/2.0 INVITE sip:5551000@sip.com:5060 SIP/2.0

voice class sip-profiles 30

INVITE sip:5551000@sip.com:5060 SIP/2.0 INVITE sip:5551000@sip.com:5060 SIP/2.0

voice class sip-profiles 40

• IOS Copy-List Variables can be assigned these substring matches

INVITE sip:tjones@sip.com:5060 SIP/2.0 INVITE sip:5551000@sip.com:5060 SIP/2.0

voice class sip-profiles 50

• SIP profiles applied to outgoing SIP messages by default

• SIP profiles can also be applied to incoming SIP messages

voice service voip

voice class sip-profiles 20

More Information - https://supportforums.cisco.com/document/13058446/sip-profile-test-tool

• E164 and URI Call Routing • Understand Call routing logic

• Removing Cisco-Guid from all requests and responses is straightforward

request ANY sip-header Cisco-Guid remove

• Match the “1200@” in Diversion Header and capture the extension:

voice class sip-profiles 100

• Unified CM Transparency feature allows you to take information from known

• Will look more closely at Transparency later in the presentation

• For example, To process the INVITEs received by Unified CM:

• Only one Script can be assigned to a SIP Entity

• Handlers for requests and responses have slightly different formats

• Handler <direction> does NOT support a wild card

<direction> does NOT support a wild card

• Additional restrictions for Handlers using a specific <response code>

• Probably easier to look at some examples…

• Invalid Response Names

specific <response code> with ANY <method>

• Unified CM uses these rules to choose a message handler:

• SIP Pass Through APIs:

• SIP Utility APIs:

• SIP URI APIs:

• Script Parameters API:

Keep it simple &

function M.outbound_INVITE(msg) -- Process outbound INVITES to VM

local DiversArray = msg:getHeaderValues("Diversion“) -- Get all Diversion Headers

local DiversCount = #DiversArray -- # of Diversion Headers in Invite