Registering Cisco Unity Express Endpoints to Cisco Unified Messaging Gateway
This section describes Cisco Unity Express endpoints, covering principally the new commands in Cisco Unity Express 3.1 to enable endpoints of this type to autoregister with Cisco Unified Messaging Gateway (UMG).
Endpoints running Cisco Unity Express 3.0 or earlier do not support autoregistration. They must be manually configured on Cisco UMG.
The section contains the following topics:
Overview of the Autoregistration Process
The purpose of autoregistration is for Cisco UMG to automatically “discover” a legitimate Cisco Unity Express 3.1 endpoint.
Note
Currently, the only type of endpoint that can autoregister is Cisco Unity Express 3.1. In the current section, the term ‘endpoint’ refers exclusively to that type of endpoint, unless otherwise specified.
A messaging gateway discovers whether an endpoint is legitimate by attempting to validate the shared secret information in the autoregistration message sent by the endpoint. Successful validation ensures that VPIM messages can only be exchanged between trusted peers.
The autoregistration process starts after the endpoint boots up. An appropriately configured endpoint is enabled to autoregister and it has the following information:
- The location-id and IP address or domain name of its primary (and where applicable, its secondary) messaging gateway
- Registration ID and password that the messaging gateways will be expecting.
–
The instructions for configuring this ID and password on Cisco UMG are given in the Cisco UMG 1.0 CLI Administrator Guide.
–
The instructions for configuring this ID and password on Cisco Unity Express 3.1 are given below, in Configuring Autoregistration with Cisco UMG.
Beginning the process, the endpoint sends registration requests to both the primary Cisco UMG and the secondary messaging gateway in that order, if a secondary is configured. In the registration message is information about itself, such as its own location ID, broadcast ID, and so on. If the primary messaging gateway encounters configuration problems during registration (for example, a missing location-id), the process will fail, and the endpoint will not try to register with the secondary messaging gateway. If the problems are of a different nature (for example, connectivity problems) the endpoint will go ahead and try to register with the secondary messaging gateway.
When the endpoint autoregisters, the messaging gateway adds the endpoint to a trusted endpoints table and the endpoint is then allowed to send and receive VPIM messages to and from the messaging gateway with which it has registered, as well as to retrieve remote user information.
Automatic directory information exchange takes place a couple of minutes after registration, thereby enabling the messaging gateway to learn about the endpoint’s properties.
Endpoints of the types Cisco Unity Express 3.0 or earlier, Cisco Unity, and Avaya Interchange do not support autoregistration, so they must be individually provisioned from messaging gateways. Instructions for doing this are given in the Cisco UMG 1.0 CLI Adminstrator Guide. An endpoint running Cisco Unity Express 3.1 that is not enabled to autoregister will be treated the same as these other types of endpoint.
Configuring Autoregistration with Cisco UMG
An endpoint running Cisco Unity Express 3.1 or later can autoregister with Cisco Unified Messaging Gateway. This means that when the endpoint comes online, it seeks out its messaging gateways (both primary and secondary, if configured) and registers itself. The alternative - manual provisioning (as opposed to autoregistration) - entails configuring all relevant details of each endpoint on its messaging gateway. This is the only option available to endpoints not running Cisco Unity Express 3.1.
After the messaging gateway authorizes the endpoint, it exchanges directories with its peers so that the whole system becomes aware that this endpoint is now online. Once you have enabled autoregistration, any time either the endpoint or the messaging gateway goes offline, the endpoint will re-register automatically as soon as both come back online.
Before enabling autoregistration, you must first specify the primary and then the secondary messaging gateway access information. Only after this do you enable autoregistration. Issuing these commands causes the profile(s) for the messaging gateways to be stored in the running configuration on Cisco Unity Express 3.1.
Note
The endpoint cannot autoregister until you issue the messaging-gateway registration command.
Caution
You must copy the configurations to the startup-config to make them persistent.
Save the configuration to the startup config by using the write command.
SUMMARY STEPS
1.
config t
2.
messaging-gateway registration
3.
messaging-gateway primary location-id umg-ip-addr [ port umg-port ]
4.
username umg-reg-id password encryption-level umg-passwd
5.
(Optional) retry-interval retry-interval ]
6.
end
7.
(Optional) messaging-gateway secondary location-id umg-ip-addr [ port umg-port ]
8.
(Optional) username umg-reg-id password encryption-level umg-password
9.
(Optional) retry-interval retry-interval ]
10.
end
11.
end
12.
show messaging-gateway
DETAILED STEPS
|
|
|
Step 1 |
se-10-0-0-0# config t |
Enters configuration mode. |
Step 2 |
messaging-gateway registration
se-10-0-0-0(config)# messaging-gateway registration |
Causes the endpoint (Cisco Unity Express) to send a registration message to its primary and, if applicable, to its secondary messaging gateway, unless registration with the primary fails due to a configuration error. |
Step 3 |
messaging-gateway primary location-id umg-ip-addr [ port umg-port ]
se-10-0-0-0(config)# messaging-gateway primary 100 192.0.2.0 port 8080 |
Enters gateway configuration mode and specifies the following information for the primary messaging gateway:
- location-id-- the location-id of the primary messaging gateway
- umg-ip-addr-- the IP address or domain name of the primary messaging gateway
- (optional) port --port the primary messaging gateway will be listening on. The default port is 80.
The primary Cisco UMG must be configured before the secondary. Otherwise, you will get the error message “Primary messaging gateway needs to be configured first.” |
Step 4 |
username umg-reg-id password encryption-level umg-password
se-10-0-0-0(config-gateway)# username cue31 password text herein |
(Optional) Specifies the username and password required to authorize registration with the message gateway.
- umg-reg-id-- the registration ID the endpoint will use to register with the messaging gateway.
Note that it is not necessarily the same as the location-id, because multiple endpoints may be assigned the same umg-reg-id.
You can give either an encrypted password or non-encrypted password: encrypted and text tokens need to be used.
- encryption-level -- The two acceptable values for this variable are
– text – encrypted
- umg-password --the password for registration with a messaging gateway is an alphanumeric string up to x in length.
|
Step 5 |
retry-interval retry-interval
se-10-0-0-0(config-gateway)# retry-interval 2 |
(Optional) The retry-interval is the delay before the endpoint attempts to re-register with the messaging gateway. The value is expressed in minutes. The default is 5 minutes. |
Step 6 |
end
se-10-0-0-0(config-gateway)# end |
Exits gateway configuration mode and enters configuration mode. |
Step 7 |
messaging-gateway secondary location-id umg-ip-addr [ port umg-port ]
se-10-0-0-0(config)# messaging-gateway secondary 200 192.0.2.1 port 8080 |
(Optional) Enters gateway configuration mode and specifies the following information for the secondary messaging gateway:
- location-id-- the location-id of the secondary messaging gateway
- umg-ip-addr-- the IP address or domain name of the secondary messaging gateway, and
- (optional) port --port the secondary messaging gateway will be listening on. The default port is 80.
The secondary Cisco UMG must be configured after the primary. Otherwise, you will get the error message “Primary messaging gateway needs to be configured first.” |
Step 8 |
username umg-reg-id password encryption-level umg-password
se-10-0-0-0(config-gateway)# username cue31 password text herein |
(Optional) Specifies the username and password required to authorize registration with the message gateway.
- umg-reg-id-- the registration ID the endpoint will use to register with the messaging gateway.
Note that it is not necessarily the same as the location-id, because multiple endpoints may be assigned the same umg-reg-id.
You can give either an encrypted password or non-encrypted password: encrypted and text tokens need to be used.
- encryption-level -- The two acceptable values for this variable are
– text – encrypted
- umg-password --the password for registration with a messaging gateway is an alphanumeric string up to x in length.
|
Step 9 |
retry-interval retry-interval
se-10-0-0-0(config-gateway)# retry-interval 2 |
(Optional) The retry-interval is the delay before the endpoint attempts to re-register with the messaging gateway. The value is expressed in minutes. The default is 5 minutes. |
Step 10 |
end
se-10-0-0-0(config-gateway)# end |
Exits gateway configuration mode and enters config mode. |
Step 11 |
messaging-gateway registration
se-10-0-0-0(config)# messaging-gateway registration |
Causes the endpoint to send a registration message to its primary and, if applicable, to its secondary messaging gateway - unless registration with the primary fails due to a configuration error. |
Step 12 |
end
se-10-0-0-0(config)# end |
Exits config mode and enters EXEC mode. |
Step 13 |
show messaging-gateway
se-10-0-0-0# show messaging-gateway |
(Optional) Displays the details associated with the registration of the messaging gateway, successful or otherwise. For more information, see the “Verifying the Registration Status of a Cisco Unity Express Endpoint” section. |
Step 14 |
write memory
se-10-0-0-0# write memory |
Copies the running-config to the startup-config and thereby ensures that the foregoing autoregistration configurations are not lost if the endpoint goes down. |
Example
The following commands on a Cisco Unity Express 3.1 endpoint set it up to autoregister with Cisco UMG, and then enable autoregistration and finally write the configuration to startup-config.
se-10-0-0-0(config)# messaging-gateway primary 100 192.0.2.0 port 8080
se-10-0-0-0(config-gateway)# username cue31 password text herein
se-10-0-0-0(config-gateway)# retry-interval 2
se-10-0-0-0(config-gateway)# end
se-10-0-0-0(config)# messaging-gateway secondary 200 192.0.2.1 port 8080
se-10-0-0-0(config-gateway)# username cue31 password text herein
se-10-0-0-0(config-gateway)# retry-interval 2
se-10-0-0-0(config-gateway)# end
se-10-0-0-0(config)# messaging-gateway registration
se-10-0-0-0# write memory
Manually Registering a Cisco Unity Express Endpoint
If you want to add a Cisco Unity Express endpoint to your Cisco UMG system, and it is either
- running Cisco Unity Express 3.0 or earlier, or
- you want to avoid autoregistration activity with an endpoint running Cisco Unity Express 3.1,
you must manually provision it from Cisco UMG. First configure the endpoint, then provision it on Cisco UMG.
Note
You need to perform these steps only if the endpoint has never undergone initial configuration - if the endpoint is already in operation, you will already have done all this. In that case, there is nothing left to do on the endpoint.
SUMMARY STEPS
1.
config t
2.
network location-id number
3.
(Optional) name location-name
4.
(Optional) abbreviation name
5.
email domain domain-name
6.
voicemail phone-prefix digit string
7.
(Optional) voicemail extension-length number [min number | max number]
8.
(Optional) voicemail vpim-encoding {dynamic | G711ulaw | G726}
9.
(Optional) voicemail spoken-name
10.
end
Repeat Steps 2 through 10 for each remote location.
11.
network local location-id number
12.
end
13.
show network locations configured
14.
show network detail location-id number
15.
show network detail local
16.
show network queues
DETAILED STEPS
|
|
|
Step 1 |
config t
se-10-0-0-0# config t |
Enters configuration mode. |
Step 2 |
network location-id number
se-10-0-0-0(config)# network location-id 9 |
Enters location configuration mode to allow you to add or modify a location.
- number—A unique numeric ID assigned to the location. This number is used to identify the location and is entered when a subscriber performs addressing functions in the TUI. The maximum length of the number is 7 digits. Cisco Unity Express supports up to 500 locations on a single system.
- To delete a location, use the no form of this command.
|
Step 3 |
name location-name
se-10-0-0-0(config-location)# name “San Jose” |
(Optional) Descriptive name used to identify the location. Enclose the name in double quotes if spaces are used.
- To delete a location name description, use the no form of this command.
|
Step 4 |
abbreviation name
se-10-0-0-0(config-location)# abbreviation sjcal |
(Optional) Creates an alphanumeric abbreviation for the location that is spoken to a subscriber when the subscriber performs addressing functions in the TUI. You cannot enter more than 5 characters.
- To delete an abbreviation, use the no form of this command.
|
Step 5 |
email domain domain-name
se-10-0-0-0(config-location)# email domain mycompany.com |
Configures the e-mail domain name or IP address for the location. The domain name is added when sending a VPIM message to the remote location (for example, “4843000@mycompany.com”). If you do not configure a domain name or IP address, the Cisco Unity Express system at this location cannot receive network messages.
- To remove the e-mail domain name or IP address and disable networking, use the no form of this command.
Caution If you remove the e-mail domain for a network location, the system automatically disables networking from the Cisco Unity Express module to that location.
If you remove the e-mail domain for the local location, then networking on that Cisco Unity Express module is disabled.
To reenable a location, assign it a valid e-mail domain.
|
Step 6 |
voicemail phone-prefix digit-string
se-10-0-0-0(config-location)# voicemail phone-prefix 484 |
(Optional) Configures the phone number prefix that is added to an extension to create a VPIM address for a subscriber at the location. A prefix is required only if an e-mail domain services multiple locations and extensions between the locations are not unique. Valid values: 1 to 15 digits. Default value: empty.
- To delete a phone prefix, use the no form of this command.
|
Step 7 |
voicemail extension-length {number | min number max number}
se-10-0-0-0(config-location)# voicemail extension-length 8 se-10-0-0-0(config-location)# voicemail extension-length min 5 max 9 |
(Optional) Configures the voice mail extension length for the location.
- number—Configures the number of digits contained in extensions at the location.
- max number—Sets the minimum number of digits for extensions. Default value: 2.
- min number—Sets the maximum number of digits for extensions. Default value: 15.
- To remove the configuration for the number of digits for extensions, use the no form of this command.
|
Step 8 |
voicemail vpim-encoding {dynamic | G711ulaw | G726}
se-10-0-0-0(config-location)# voicemail vpim-encoding G711ulaw |
(Optional) Configures the encoding method used to transfer voice-mail messages to this location.
- dynamic—Cisco Unity Express negotiates with the location to determine the encoding method
- G711ulaw—Cisco Unity Express always sends messages as G711 mu-law.wav files. Set this only if the receiving system supports G711 mu-law encoding (such as Cisco Unity).
- G726—Cisco Unity Express always sends messages as G726 (32K ADPCM). Use for low-bandwidth connections or when the system to which Cisco Unity Express is connecting does not support G711 u-law.
- Default value: dynamic.
- To return to the default value for encoding, use the no or default form of this command.
|
Step 9 |
voicemail spoken-name
se-10-0-0-0(config-location)# voicemail spoken-name |
(Optional) Enables sending the spoken name of the voice-mail originator as part of the message. If the spoken name is sent, it is played as the first part of the received message. Default: enabled.
- To disable sending the spoken name, use the no form of this command.
|
Step 10 |
end
se-10-0-0-0(config-location)# end |
Exits location configuration mode. |
Step 11 |
network local location-id number
se-10-0-0-0(config)# network local location-id 1 |
Enables networking for the local Cisco Unity Express system identified by the location-id number.
- To delete the local location, use the no form of this command.
Caution If you delete the local network location and then save your configuration, when you reload Cisco Unity Express, the local network location will remain disabled. After Cisco Unity Express restarts, reenter the
network local location-id command to reenable networking at this location.
|
Step 12 |
exit
se-10-0-0-0(config)# exit |
Exits configuration mode. |
Step 13 |
show network locations configured
se-10-0-0-0# show network locations configured |
(Optional) Displays the location-id, name, abbreviation, and domain name for each configured Cisco Unity Express location. |
Step 14 |
show network detail location-id number
se-10-0-0-0# show network detail location-id 9 |
(Optional) Displays network information for the specified location-id, including the number of messages sent and received. |
Step 15 |
show network detail local
se-10-0-0-0# show network detail local |
(Optional) Displays network information for the local Cisco Unity Express location, including the number of messages sent and received. |
Step 16 |
show network queues
se-10-0-0-0# show network queues |
(Optional) Displays information about messages in the outgoing queue that are to be sent from this Cisco Unity Express system. The queue information contains three displays: one for urgent job queue information, one for normal job queue information, and one for running job information. |
Examples
The following examples illustrate the output from the show network commands on company Mycompany’s call control system in San Jose with remote voice-mail provided by six remote Cisco Unity Express sites.
se-10-0-0-0# show network locations
101 'San Jose' SJC sjc.mycompany.com
102 'Dallas/Fort Worth' DFW dfw.mycompany.com
201 'Los Angeles' LAX lax.mycompany.com
202 'Canada' CAN can.mycompany.com
301 'Chicago' CHI chi.mycompany.com
302 'New York' NYC nyc.mycompany.com
401 'Bangalore' BAN bang.mycompany.com
se-10-0-0-0# show network detail location-id 102
Email domain: dfw.mycompany.com
Minimum extension length: 2
Maximum extension length: 15
Send spoken name: enabled
se-10-0-0-0# show network detail local
Email domain: sjc.mycompany.com
Minimum extension length: 2
Maximum extension length: 15
Send spoken name: enabled
The following example illustrates output from the show network queues command. The output includes the following fields:
- ID—Job ID.
- Retry—Number of times that Cisco Unity Express has tried to send this job to the remote location.
- Time—Time when the job will be resent.
se-10-0-0-0# show network queues
ID TYPE TIME RETRY SENDER RECIPIENT
107 VPIM 06:13:26 20 jennifer 1001@sjc.mycompany.com
106 VPIM 06:28:25 20 jennifer 1001@sjc.mycompany.com
ID TYPE TIME RETRY SENDER RECIPIENT
123 VPIM 16:33:39 1 andy 9003@lax.mycompany.com
ID TYPE TIME RETRY SENDER RECIPIENT
122 VPIM 16:33:23 1 andy 9001@lax.mycompany.com
124 VPIM 16:34:28 1 andy 9003@lax.mycompany.com
125 VPIM 16:34:57 1 andy 9002@lax.mycompany.com
126 VPIM 16:35:43 1 andy 9004@lax.mycompany.com
After performing on the endpoint the steps just listed, on the Cisco UMG that is to be the endpoint’s primary messaging gateway, manually provision the endpoint by following the instructions given in the Cisco UMG 1.0 CLI Adminstrator Guide.
Register the endpoint by issuing the Cisco UMG command location-id cue enabled (fully described in the Cisco UMG 1.0 CLI Adminstrator Guide) on the endpoint’s primary messaging gateway.
On that messaging gateway, verify that the endpoint is registered to it by using the command show endpoint local.
Verifying the Registration Status of a Cisco Unity Express Endpoint
You can verify whether the current Cisco Unity Express 3.1 or later version endpoint is registered with a messaging gateway, and check all the details associated with the registration - successful or otherwise - by using the show messaging-gateway command in Cisco Unity Express EXEC mode.
You can see which Cisco UMGs you have configured as its primary and secondary messaging gateways, with their respective port numbers. Indications in the status column show whether or not the endpoint has registered with the messaging gateway successfully.
Table 23-1 show messaging-gateway Output
AutoRegister to messaging gateway(s) |
Enabled / disabled |
|
|
Remote directory lookup |
Enabled / disabled |
with / without TUI prompt |
|
Primary/secondary messaging gateway |
IP address (port number) |
|
|
|
Status |
Registered / Not Registered |
If registered, timestamp of initial registration confirmation; if not registered, reason is given as a code (see Table 23-2 ) |
|
Default route |
Enabled/ disabled |
|
|
Location-id |
location-id of the messaging gateway |
|
|
Reg-id |
Registration username the Cisco UMG expects from endpoint |
|
|
Reg-password |
(Not displayed) |
Registration password the Cisco UMG expects from endpoint. It is never displayed. |
|
|
Delay in minutes before the endpoint attempts to register again. Default is 5 minutes. |
Not displayed if not set. |
If the endpoint has registered successfully, you will see the date and time of the initial registration in the status column. You can also check the configuration for a default routing destination for a message to a voicemail address that can be resolved by neither Cisco Unity Express nor Cisco UMG. To illustrate: if you give a phone number that cannot be found in a Cisco Unity Express local search or in a Cisco UMG remote lookup, the message will be forwarded to that default route destination.
If the endpoint has not registered successfully, the reason for the failure will be displayed in the status column:
Table 23-2 show messaging-gateway: Status Codes
|
|
Registered |
|
Not registered |
Autoregistration is not enabled |
Not configured |
|
Not registered (general error) |
Autoregistration failed due to an error other than those specified in this table. |
Not registered (connection timeout) |
Connection timed out |
Not registered (authentication failed) |
Authentication failed |
Not registered (link is down) |
Link is down |
Not registered (location is forbidden) |
The Cisco Unity Express endpoint with that location-id has been blocked by Cisco UMG and is thus is not allowed to register (for instructions on how to prevent an endpoint from registering, see the Cisco UMG 1.0 CLI Adminstrator Guide. |
Not Registered (duplicated location) |
The Cisco Unity Express location-id is not globally unique: there is another entity in the system with the same location-id. |
Not Registered (invalid configuration) |
General configuration error such as the secondary messaging gateway location ID not being configured on the primary messaging gateway. |
Not Registered (manually de-registered) |
An intermediate state to indicate manually triggered re-registration, for example, the messaging gateway’s access information being updated. |
The following command on a Cisco Unity Express 3.1 or later version endpoint displays its registration status:
se-10-0-0-0# show messaging-gateway
AutoRegister to messaging gateway(s) : Enabled
Remote directory lookup : Enabled (without TUI prompt)
Primary messaging gateway :
Status : Registered (Sun Jun 10 20:35:43 GMT 2007)
Reg-password : (Not displayed)
Retry-interval : 5 minute(s)
Secondary messaging gateway :
Enabling or Disabling Remote Lookup, With or Without TUI Confirmation
Enabling Remote Directory Lookup Without TUI Prompt
When you enable autoregistration by issuing the messaging-gateway registration command on a Cisco Unity Express 3.1 endpoint, you also enable the endpoint to do remote lookup automatically. This includes a short prompt informing subscribers that the lookup may take some time.
Enabling Remote Directory Lookup With TUI Prompt
Enabling the remote directory lookup feature does not also enable the directory lookup confirmation in the TUI flow feature, in which Cisco Unity Express 3.1 gives subscribers the option to do remote lookup if there is no local match. To enable TUI directory lookup confirmation, use the config-mode command messaging-gateway directory lookup tui-prompt.
Disabling Remote Directory Lookup
To have no remote lookup at all, disable it by issuing the no messaging-gateway directory lookup command.
Note
Disabling the remote directory lookup feature also disables directory lookup confirmation in the TUI flow, and conversely, enabling directory lookup confirmation in the TUI flow will also enable remote directory lookup.
Viewing Status
To view the status of these features, use the show messaging-gateway command, which displays the following output:
Remote directory lookup status:
- No--remote directory lookup is disabled
- Yes--remote directory lookup is enabled
–
Enabled with TUI-prompt--TUI confirmation prompt is enabled
–
Enabled without TUI-prompt--TUI confirmation prompt is disabled.
Viewing Cached and/or Configured Network Locations
To view a list of all cached remote location entries on Cisco Unity Express 3.1, use the EXEC-mode show network locations cached command.
To list all configured remote location entries on Cisco Unity Express 3.1, use the EXEC-mode show network locations configured command. This command replaces the old show network locations command.
Refreshing Locations
To manually refresh a cached location entry on Cisco Unity Express 3.1, use the network location cache refresh id command in EXEC-mode. This command will not generate any response if it is performed successfully. Otherwise, an error message appears.
Setting the Expiration for Cached Locations
To set the expiration time for a cached location on Cisco Unity Express 3.1, use the network location cache expiry int command in config-mode. The int value stands for number of days. By default, this value is set to 4. The no command will set the value back to its default value. The value is persisted by means of the nvgen method. It is not stored in the database.
Overloading a NAT Device: the Consequences for Endpoints
One endpoint can be configured to get to its primary messaging gateway with complete connectivity if :
- Two Cisco Unity Express endpoints are behind a NAT device that has only one IP address to assign --an overload situation--
- Those endpoints have two different messaging gateways configured as primary messaging gateways,
Note
The other endpoint can only do HTTP-related activities (assuming proper configuration) and not the SMTP activities.