 | 6AOSCG0046-29A February 2013 |
Configuring Distinctive Ring Tone in AOS Units |
This guide describes the configuration of distinctive ring tones in ADTRAN Operating System (AOS) voice products. Distinctive ring tones can be applied to call queues, ring groups, or shared line appearances (SLAs) using SIP header manipulation rules (HMR). Call queues, ring groups, and shared line appearances can all be configured using either the command line interface (CLI) or web-based graphical user interface (GUI). SIP HMR is only configured using the CLI. To simplify this guide, only the CLI explanation is provided. GUI instructions for configuring the other voice features are provided in the documents referenced in Additional Resources.
This guide contains the following sections:
- Overview of Distinctive Ring Tones
- Hardware and Software Requirements and Limitations
- Basic Configuration Using the CLI
- Command Summary Table
- Configuration Examples
- Additional Resources
Overview of Distinctive Ring Tones
Distinctive ring tones are tones that differ from each other either by cadence or some other distinguishing feature to inform a SIP user to a unique call origin. They can be useful in situations where an AOS unit is receiving calls from multiple trunks. The ring tone is determined by the incoming trunk or called number. This allows the user an opportunity to customize their response or greeting appropriately before answering the call.
AOS units can be configured for four types of Bellcore ring tones: Bellcore-dr1, Bellcore-dr2, Bellcore-dr3, and Bellcore-dr4.
 | The name Bellcore refers to a set of ring cadences. Because ring tones are based on cadence, they may sound different depending on the telephone used. Providers may use different cadences for each ring. The Bellcore name is used as a generic term for identifying ringers. |
Distinctive ring tones can be configured for a call queue, ring group, or SLA using SIP HMR on the AOS unit. Configuring SIP HMR can be a complex procedure and additional information is provided for this feature in Manipulating SIP Headers and Messages in AOS available online at https://supportforums.adtran.com.
Understanding Alert-Info Header
The Alert-Info header is used to pass special instructions to the phone about a call. One of these special instructions is the overriding of ring tones. The system administrator can configure unique ring tones if they know which tones are supported on the phones in use. Knowledge of how to populate the Alert-Info header to invoke those tones is also necessary. The NetVanta 7000 Series units allow manipulating the Alert-Info header by using SIP HMR in AOS.
SIP Header Manipulation
With the release of AOS firmware R10.1.0, the SIP header manipulation feature was introduced. This feature allows the manipulation of both SIP headers and message bodies in SIP transmissions, based on configurable rules. These rules can be applied to both outbound and inbound messages, and can be used to match/add/remove SIP headers, modify existing headers or bodies of SIP messages using regular expressions and store variable information. One of the benefits of using SIP header and message manipulation is that the feature can give you enhanced control over the behavior of SIP traffic on your AOS device, as well as help solve interoperability issues between the AOS device and other products.
SIP header manipulation is achieved by creating an HMR policy, a set of HMR rules, and applying those rules to the HMR policy. The policy is then applied to a SIP trunk, to all SIP traffic in the AOS device, to SIP traffic sent or received by a SIP proxy user, or to SIP traffic sent or received by a SIP proxy server. The HMR policies can be applied to either inbound or outbound SIP traffic.
Hardware and Software Requirements and Limitations
Distinctive ring tones are supported on AOS voice products with SIP HMR capabilities as outlined in the Product Feature Matrix, available online at ADTRAN’s Support Forum, https://supportforums.adtran.com. SIP header and message manipulation is a feature that is available only on AOS products running AOS firmware R10.1.0 or later.
The supported configurable ring tones are Bellcore-dr1, dr2, dr3, dr4 since those ring tones function with both Polycom and ADTRAN IP 700 Series phones. The administrator can configure other ring tones if they know which ring tones are supported for the phones in use, for example, MP3 format ring tones. This guide assumes that at least two trunks have been previously configured for the AOS product. Each trunk must have one of the following configured using the supporting documentation:
Call queue
Ring group
Shared line appearance (SLA)
Record the extension(s) configured during these methods. You will use those extensions in the following instructions.
Configuration Using the CLI
SIP header and message manipulation is achieved in AOS products using the CLI. The following are the basic configuration steps necessary to implement SIP header and message manipulation to allow distinctive ring tones.
Step 1: Access the CLI
To access the CLI on your AOS unit, follow these steps:
1. Boot up the unit.
2. Telnet to the unit (telnet <ip address>), for example:
telnet 10.10.10.1.
| If during the unit’s setup process you have changed the default IP address (10.10.10.1), use the configured IP address. |
3. Enter your user name and password at the prompt.
 | The AOS default user name is admin and the default password is password. If your product no longer has the default user name and password, contact your system administrator for the appropriate user name and password. |
4. Enable your unit by entering enable at the prompt as follows:
>enable
5. If configured, enter your Enable mode password at the prompt.
6. Enter the unit’s Global Configuration mode as follows:
#configure terminal
(config)#
Step 2: Create a Call Queue, Ring Group, or Shared Line Appearance
One of the following prerequisites must be completed prior to configuring distinctive ring tones. Select the method that best fits your situation and follow the instructions provided through the link.
Create a call queue using the instructions provided in Configuring Call Queuing in the NetVanta 7000 Series.
Create a Ring Group using the instructions provided in Configuring NetVanta 7000 Series Ring Groups.
Create an SLA using instructions provided in Configuring Shared Line Appearances for Analog Trunks.
Step 3: Configure the HMR Policy and Rule Set
Configure an HMR policy to match the either the FROM header prefix (for call queue or ring groups) or match the SIP-Req-Uri header extension (for SLAs). The HMR policy identifies calls with the prefix you configured previously (Sales_) or the SLA receiving the SIP INVITE. Once identified, the HMR rule set assigns a specific ring tone to the call. Configuring HMR policies is a complex function and is only briefly explained in this step. Refer to Additional Resources for more detailed instructions.
1. Create an HMR rule set
An HMR rule set is a named collection of one or more sequenced message rules. When a rule set is applied to a message, all matching message rules are processed in sequence.
To create an HMR rule set and enter the rule set’s configuration mode, enter the hmr rule-set <name> command from the Global Configuration mode. The <name>parameter is the name given to the HMR rule set. Names must be unique for each rule set you configure. Multiple rule sets can be created by entering the command multiple times. To create the HMR rule set, and enter its configuration mode, enter the command as follows:
(config)#hmr rule-set RingToneSet
(config-rule-set-RingToneSet)#
2. Create HMR message rules for the rule set
A message rule is a collection of one or more header commands, which determine the types of SIP headers to act upon, and the action to be taken. When a message rule is applied to a SIP message, all matching header commands are processed. Message rules are processed in the order determined by the sequence number of the message rule within the rule set. When multiple rules are applied to a message, the results of each rule are applied before the next rule is evaluated and applied.
Each message rule is named, and can be configured to apply to all SIP messages, or only to SIP requests or responses. To create an HMR message rule, and enter the rule’s configuration mode, enter the message-rule <name> [message-type [request | response | any]] [<sequence number>] command from the rule set’s configuration mode. The <name> parameter specifies the name of the message rule. Message rule names must be unique within the HMR rule set. The optional message-type parameter specifies whether the rule is applied to SIP request or response messages, or to both (any keyword). The optional <sequence number> parameter specifies the sequence number given to the message rule, which determines the order in which the rules are processed. By default, sequence numbering occurs in increments of 10, and all commands are processed in sequence. Valid sequence number range is 1 to 99999. Entering the command from the HMR Rule Set Configuration mode prompt as follows creates a message rule named RingToneSet that applies to request SIP message type and has a sequence number of 10, and it also enters the rule’s configuration mode:
(config-rule-set-RingToneSet)#message-rule RingToneSet message-type request 10
(config-msg-rule-RingToneSet)#
3. Specify the HMR message rule’s action
HMR message rules can be used to add new SIP headers to the message, remove SIP headers from the message, modify existing SIP headers in the message, and modify the existing body in a SIP message. These actions are completed on SIP headers/messages that match specified criteria. When multiple rules are applied to a message, the results of each rule are applied before the next rule is evaluated and applied.
Matching Headers
First, use HMR message rules to match specified SIP headers in a SIP message using the match header <header> [match-value <pattern>] command. Match commands allow you to specify conditions that must be true in order for the message rule to be processed. If a match header command is present in the message rule’s configuration, the message rule is processed only if the match header resolves as true. Multiple match header commands can be present, but all of them must resolve as true for the message rule to be processed. The <header> parameter of the command indicates the SIP header to be used for matching. The match-value <pattern>parameter specifies the pattern to be used for matching.
The match criteria depends on the method you are using to distinguish between incoming calls. If you are using a call queue or ring group, the match criteria must match the FROM SIP header and the specified prefix (for example, Sales_). Enter the command from the HMR Message Rule Configuration mode as follows:
(config-msg-rule-RingToneSet)#match header from match-value Sales_
If you are using SLA, the match criteria must match the Sip-Req-Uri SIP header and contain the specified SLA extension (for example, 4001) in the <pattern> text. Enter the command from the HMR Message Rule Configuration mode as follows:
(config-msg-rule-RingToneSet)#match header sip-req-uri match-value “/^INVITE sip:4001/”
Removing Headers
Second, use the HMR rules to remove SIP headers from SIP messages. This allows you to remove any Alert-Info headers that could conflict with the new ring tone we are adding to the SIP message.
Headers are removed from messages by entering the remove header <header> position [all | first | first-match | last] [<sequence number>] command from the HMR Message Rule Configuration mode. The <header> parameter specifies the SIP header type that you would like to remove from the SIP message. The position keyword specifies the position in the SIP message of the header to be removed. You can remove all matching headers of the specified header type (all), remove the first header of the specified header type if there is a match (first), remove the first matching header of the specified header type regardless of its position within the message (first-match), or remove the last header of the specified header type is there is a match (last).
| Multiple headers of the same type can occur in SIP messages. Therefore, the specified position of the header can determine whether a match occurs. |
The optional <sequence number> parameter specifies the sequence number given to the message rule, which determines the order in which the rules are processed. By default, sequence numbering occurs in increments of 10, and all commands are processed in sequence. The valid sequence number range is 1 to 99999.
To remove an Alert-Info header from the SIP message, enter the remove header command as follows from the HMR Message Rule Configuration mode:
(config-msg-rule-RingToneSet)#remove header Alert-Info position all 10
Adding Headers
The last message rule action to apply is to add an Alert-Info header using SIP header manipulation to specify the new ring tone to use.
To add a new header to the SIP message, enter the add header <header> position if-not-present new-value <value string> [<sequence number>] command from the HMR Message Rule Configuration mode. The <header> parameter specifies the SIP header type that you would like to add to the SIP message. The position if-not-present keywords specifies adding the new header only if it is not already present.
The new-value <value string> parameter specifies the value to assign to the new header, and is expressed as a text string, for example, “<http://127.0.0.1/Bellcore-dr1>”. The optional <sequence number> parameter specifies the sequence number given to the message rule, which determines the order in which the rules are processed. By default, sequence numbering occurs in increments of 10, and all commands are processed in sequence. the valid sequence number range is 1 to 99999.
To add a new SIP header to the SIP message, enter the add header command as follows from the HMR Message Rule Configuration mode:
(config-msg-rule-RingToneSet)#add header Alert-Info position if-not-present new-value <http://127.0.0.1/Bellcore-dr1> 20
(config-msg-rule-RingToneSet)#exit
(config)#
4. Create an HMR policy
The HMR policy is a named collection of one or more rule sets. The policy is used to apply the rule sets to specific SIP traffic. Create the HMR policy using the hmr policy<name> command from the Global Configuration mode. The <name> parameter is the name given to the policy. For example, to create the HMR policy RingPolicy1, enter the command as follows:
(config)#hmr policy RingPolicy1
Configuring new HMR policy RingPolicy1
(config-policy-RingPolicy1)#
5. Apply the rule set to the HMR policy
After creating the HMR policy in the Global Configuration mode, you must then apply the relevant rule sets to the policy. Rule sets are added to the policy using the rule-set<name> [<sequence number>] command from the HMR Policy Configuration mode. The <name> parameter is the name of the previously created rule set that you want to apply to the policy. Multiple rule sets can be added to a single policy. When multiple rule sets are applied to a message, the results of each rule set are applied before the next rule set is evaluated and applied. The optional <sequence number> parameter specifies the sequence number given to the rule set within the policy. This number determines the sequence for applying the various rule sets in the policy. By default, sequence numbering occurs in increments of 10, and all commands are processed in sequence. The valid sequence number range is 1 to 99999.
To add a rule set to an HMR policy, enter the rule-set command from the HMR Policy Configuration mode as follows:
(config-policy-RingPolicy1)#rule-set RingToneSet 10
(config-policy-RingPolicy1)#exit
Step 4: Apply the HMR Policy Globally To All Sip Traffic
To apply an HMR policy to all SIP traffic on the AOS unit, enter the ip sip hmr <policy name> [in | out] command from the Global Configuration mode prompt. The<policy name> parameter specifies the HMR policy you are applying. In addition, you must specify whether the policy is applied to incoming SIP traffic or outgoing SIP traffic on the device by using either the in or out keywords.
To add the HMR policy RingPolicy1 to the AOS unit for all outbound SIP traffic, enter the command as follows:
(config)#ip sip hmr RingPolicy1 out
This policy will now apply the configured manipulation rules to the outbound SIP traffic on the AOS device.
Command Summary Table
The following table provides a summary of the commands used to configure the HMR to supply a distinctive ring tone when receiving incoming calls.
Prompt | Command | Description |
|---|---|---|
(config)# | hmr policy <name> | Creates an HMR policy and enters the policy’s configuration mode. |
(config-policy-MyPolicy1)# | rule-set <name> [<sequence number>] | Applies a rule set to an HMR policy and optionally specifies a sequence number for the rule set within the policy. By default, sequence numbering occurs in increments of 10, and all commands are processed in sequence. Valid sequence number range is 1 to 99999. |
(config)# | hmr rule-set <name> | Creates an HMR rule set and enters the rule set’s configuration mode. |
(config-rule-set-set1)# | message-rule <name> [message-type[request | response | any]] [<sequence number>] | Creates a message rule for the rule set. Specifies the message type to which the rule applies, and assigns a sequence number to the rule. By default, sequence numbering occurs in increments of 10, and all commands are processed in sequence. Valid sequence number range is 1 to 99999. |
(config-msg-rule-rule1)# | match header <header> [match-value<pattern>] | Specifies the match criteria to apply to the rule set using a specific SIP header and matching text pattern. Patterns can be a regular expression, text string, or variable. |
(config-msg-rule-rule1)# | add header <header> position [if-not-present] new-value <value string>[<sequence number>] | Specifies the header to add to a SIP message if the header does not already exist. Thenew-value parameter specifies the value to assign to the new header, and is expressed as a text string. The <sequence number> parameter assigns a sequence number to the rule. By default, sequence numbering occurs in increments of 10, and all commands are processed in sequence. Valid sequence number range is 1 to 99999. |
(config)# | ip sip hmr <policy name> [in | out] | Applies an HMR policy to all SIP traffic and specifies whether the policy is applied to incoming or outgoing traffic. |
Configuration Examples
Call Queue with Prefix
The following example provides the CLI commands to create a linear hunt call queue at extension 3001 that prepends all incoming calls with the prefix Sales_. It includes two members, extension 2008 and 2009. The HMR rule set RingToneSet is created and identifies incoming SIP messages by matching the FROM header prefix (Sales_). Once identified, the SIP messages are altered by removing all Alert-Info headers and applying a new Alert-Info header specifying the ring tone to use for these incoming calls. The HMR policy RingPolicy1 is created and the HMR rule set RingToneSet is applied to it.
(config)#voice queue 3001
(config-3001)#name TSQUEUE
(config-3001)#description Tech Support Queue
(config-3001)#call-distribution linear-hunt
(config-3001)#prefix Sales_
(config-3001)#member 2008
(config-3001)#member 2009
(config)#hmr rule-set RingToneSet
(config-rule-set-RingToneSet)#message-rule RingToneSet message-type request 10
(config-msg-rule-RingToneSet)#match header from match-value Sales_
(config-msg-rule-RingToneSet)#remove header Alert-Info position all 10
(config-msg-rule-RingToneSet)#add header Alert-Info position if-not-present new-value <http://127.0.0.1/Bellcore-dr1> 20
(config-msg-rule-RingToneSet)#exit
(config)#hmr policy RingPolicy1
Configuring new HMR policy RingPolicy1
(config-policy-RingPolicy1)#rule-set RingToneSet 10
(config-policy-RingPolicy1)#exit
(config)#ip sip hmr RingPolicy1 out
|
|
Ring Group with Prefix
The following example provides the CLI commands used to create a linear hunt ring group at extension 3001 that prepends all incoming calls with the prefix Sales_. It includes two members, extension 2008 and 2009. The HMR rule set RingToneSet is created and identifies incoming SIP messages by matching the FROM header prefix (Sales_). Once identified, the SIP messages are altered by removing all Alert-Info headers and applying a new Alert-Info header specifying the ring tone to use for these incoming calls. The HMR policy RingPolicy1 is created and the HMR rule set RingToneSet is applied to it.
(config)#voice queue 3001
(config-3001)#description Tech Support Queue
(config-3001)#type linear-hunt
(config-3001)#prefix Sales_
(config-3001)#member 2008
(config-3001)#member 2009
(config)#hmr rule-set RingToneSet
(config-rule-set-RingToneSet)#message-rule RingToneSet message-type request 10
(config-msg-rule-RingToneSet)#match header from match-value Sales_
(config-msg-rule-RingToneSet)#remove header Alert-Info position all 10
(config-msg-rule-RingToneSet)#add header Alert-Info position if-not-present new-value <http://127.0.0.1/Bellcore-dr1> 20
(config-msg-rule-RingToneSet)#exit
(config)#hmr policy RingPolicy1
Configuring new HMR policy RingPolicy1
(config-policy-RingPolicy1)#rule-set RingToneSet 10
(config-policy-RingPolicy1)#exit
(config)#ip sip hmr RingPolicy1 out
Shared Line Appearance
In this example, an SLA (for extension 4001) is used instead of configuring a ring group or call queue with a prefix. When a call is received on the SLA matching the specified extension, the HMR is applied. This examples creates the HMR rule set RingToneSet and identifies incoming SIP messages by matching the Sip-Req-Uri header with an INVITE to 4001. Once identified, the SIP message is altered by removing all Alert-Info headers and applying a new Alert-Info header specifying the ring tone to use for these incoming calls. The HMR policy RingPolicy1 is created and the HMR rule set RingToneSet is applied to it.
(config)#voice line 4001
(config-4001)#password 1234
(config-4001)#trunk "T01"
(config-4001)#codec-group g711_first
(config-4001)#coverage vm 2010
(config-4001)#exit
(config)#hmr rule-set RingToneSet
(config-rule-set-RingToneSet)#message-rule RingToneSet message-type request 10
(config-msg-rule-RingToneSet)#match header sip-req-uri match-value “/^INVITE sip:4001/”
(config-msg-rule-RingToneSet)#remove header Alert-Info position all 10
(config-msg-rule-RingToneSet)#add header Alert-Info position if-not-present new-value <http://127.0.0.1/Bellcore-dr1> 20
(config-msg-rule-RingToneSet)#exit
(config)#hmr policy RingPolicy1
Configuring new HMR policy RingPolicy1
(config-policy-RingPolicy1)#rule-set RingToneSet 10
(config-policy-RingPolicy1)#exit
(config)#ip sip hmr RingPolicy1 out
Additional Resources
Manipulating SIP Headers and Messages in AOS
Configuring Call Queuing in the NetVanta 7000 Series
