http mediamaster feature

111© 2001, Cisco Systems, Inc. All rights reserved.Presentation_ID

HTTP MediaMaster Feature

Overview of HTTP MediaMaster.

Overview of Configuration Settings.

Overview of Architecture.

Overview of Authentication.

Example Diagnostics.

Diagnostic collection tutorial.

Overview of Error codes.



Feature Summary: Unity’s MediaMaster can use HTTP instead of DCOM as a form of network communication.

Leveraging HTTP can alleviate complex DCOM permission problems due to topology, environment and changes to operating systems.

SA, CPCA and VMO MediaMaster all can use HTTP for network communication.

MediaMaster communicates with the VMWS (Voice Mail Web Services) on the Unity server.

HTTP communication leveraged for Secure Messaging, TRAP and audio streams (SA/CPCA).



Overview:

The Media Master can use either HTTP/HTTPS or DCOM as the communication protocol when a phone is used as the recording and playback (TRAP) device for playing or recording names, greetings, and messages in the Cisco Unity Administrator, the Cisco PCA web tools, and ViewMail for Outlook.

Beginning with Cisco Unity version 8.0, the Media Master defaults to using HTTP/HTTPS as the TRAP connection method. HTTP/HTTPS is preferred because it is more reliable when connecting through a firewall, and because it uses TCP ports that are already opened for administration access.

In the Cisco Unity Administrator and the Cisco PCA web tools, the Media Master uses HTTP or HTTPS as the default protocol (depending on the URL that is used to access the Cisco Unity Administrator and Cisco PCA web tools, and whether SSL is configured for the Cisco Unity server).

If your browser already has the Cisco Unity 8.0 or later version of the Media Master Active-X control installed, but you are browsing to a server that is running Cisco Unity version 7.x or earlier (which does not support HTTP/HTTPS as a communication protocol for TRAP connections), the Media Master will automatically switch to using DCOM as the communication protocol for TRAP connections.

If a client is using a version 7.x or earlier Media Master Active-X control , Cisco Unity version 8.0 will still continue support DCOM connections.



The following Advanced Settings apply for SA/CPCA MediaMaster :

• Administration - TRAP Connection method for SA and PCA0 - Automatic means that the Media Master Active X control will use HTTP/HTTPS but if

the server is running a version prior to Unity 8.0 it will revert to using DCOM. This is the default setting.

1 - HTTP/HTTPS only. Select this if you want the Media Master to always use HTTP/HTTPS and never attempt to use DCOM if HTTP/HTTPS fails.

2 - DCOM only. Select this if you want the Media Master to always use DCOM and never attempt to use HTTP/HTTPS.

•Administration - TRAP Connections Ignore Certificate Errors0 - Do not ignore certificate errors. This setting means that if there is a certificate error

when the Media Master is establishing an SSL connection, the Media Master will be unable to send recordings and audio streams to and from Cisco Unity.

1 - Ignore certificate errors. This means that if there is a certificate error when the Media Master is establishing an SSL connection, the error will be ignored and the connection attempt will continue. This setting is useful when using self-signed certificates. (Default)



The following Registry Settings apply for VMO MediaMaster :

HKLM\Software\Cisco Systems\Cisco Unity\VMO\Trap Connection Type:

When a subscriber uses the Media Master component to play or record messages, ViewMail uses either HTTP/HTTPS or DCOM to communicate with the Cisco Unity server, depending on the value of the Trap Connection Type registry key:0—ViewMail will automatically determine the communication protocol based on the Cisco Unity server it is connecting to. It attempts HTTP/HTTPS first and will switch to DCOM if necessary. This is the default setting.1—ViewMail will attempt to use only HTTP/HTTPS as the communication protocol, regardless of how the Cisco Unity server is configured.2—ViewMail will attempt to use only DCOM as the communication protocol, regardless of how the Cisco Unity server is configured.

HKLM\Software\Cisco Systems\Cisco Unity\VMO\HTTP Connection Type:

When ViewMail is using HTTP/HTTPS to communication with the Cisco Unity server, whether ViewMail uses HTTP or HTTPS depends on the value of the HTTP Connection Type registry key:0—ViewMail will use only HTTPS as the communication protocol, regardless of how the Cisco Unity server is configured. This is the default setting.1—ViewMail will attempt to use only HTTP as the communication protocol, regardless of how the Cisco Unity server is configured.



The following Registry Settings apply for VMO MediaMaster :

HKLM\Software\Cisco Systems\Cisco Unity\VMO\Ignore Cert Errors:

This registry key applies when HTTPS is configured as the communication protocol between the ViewMail and the Cisco Unity server. During the installation of the Cisco Unity server, if you use the self-signed certificate to provide an SSL (HTTPS) connection to ViewMail, the Media Master will encounter certificate authenticity warning errors due to the self-signed certificate. How the Media Master handles the certificate errors depends on the value of the Ignore Cert Errors registry key:0—ViewMail will not ignore certificate errors. The user will not be able to play or record secure messages or use the telephone to record and play messages in ViewMail.1—ViewMail will ignore certificate errors, allowing ViewMail to accept self signed certificates. This is the default setting.



Architecture Overview:

• VMWS is the web server on Unity that allows for client communication.

• VMWS runs in IIS (as an instance of w3wp.exe).

• VMWS installed at Unity 8.0 install/upgrade time.

• VMWS also supports secure messaging for CUPC and CUMA along with messaging, call control for Visual Voice Mail.

• VMWS is a “front end” and relays client requests for backend Unity services like TRaP, Secure Messaging, audio streams.

• MediaMaster (and client-side TRAP i.e. AvTrapConnectionHolderSvr.exe) HTTP communication with VMWS is SOAP.

• VMWS communication with backend Unity services is COM.



Architecture Diagram:



Communication “Stack”:

From client to server, the different pieces of code that handle the messages can be thought of as a stack.

Each SOAP request/response consists of messages traversing different parts of the stack.

Request is on the left, response is on the right.



Authentication Overview (SA/CPCA):

• Upon successful SA/CPCA authentication, the SA/CPCA code retrieves a ticket from the Unity Authentication Manager.• The SA/CPCA code “seeds” the MediaMaster with this ticket.• The MediaMaster passes the ticket to AvTrapConnectionHolderSvr.exe• Both the MediaMaster and client side TRAP can create a session with VMWS by logging on to VMWS with the ticket.

Authentication Overview (VMO):• MediaMaster attempts logon to VMWS with the currently logged on user’s credentials.• If upon failure with current credentials, the MediaMaster will prompt for username and password.• TRAP uses the same credentials as the MediaMaster (whether from currently logged on user or prompted creds).



Authentication Example(SA/Anonynous IIS config):

1. The SA takes the credentials and passes them to the AuthenticationMgr for authentication using the “Windows” authentication provider.

2. Assuming the credentials provided can be authenticated by the AuthenticationMgr a ticket is generated and handed back to the SA.

3. The SA takes the ticket and passes it into the MediaMaster.

4. The MediaMaster uses the ticket for a VMWS ticket-based Login request.

5. The VMWS verifies the ticket with the original ticket issuer, the AuthenticationMgr.

6. Given the ticket is correct and has not expired, the AuthenticationMgr successfully validates the ticket and associates it with a given Unity Subscriber.

7. Based only on the ticket, the VMWS now knows the Login attempt is valid and knows what Subscriber is associated with the Login request.

The VMWS generates a VMWS-based session ID and passes that back to the MediaMaster. This VMWS-based session ID can be used for subsequent VMWS methods.



Authentication Example(“Integrated” VMO Login to VMWS):

To leverage Integrated IIS connections, the security negotiation has to be forced. This is because the VMWS virtual directory is configured for both Anonymous access and Integrated authentication. Since anonymous access is enabled, IIS will always accept anonymous connections. However, the anonymous connection does not contain information about the logged on user at the workstation running VMO. So, to force Integrated access, the client adds a special HTTP header to the VMWS Login method. If the server sees the “Pragma: ForceNTLM” header, it will return a 401 Unauthorized code to the client. The client will then authenticate with the server allowing the server to have access to the credentials of the user logged on at the VMO workstation. If this user is associated with a Unity subscriber, access is granted.



Diagnostic Overview:

• MediaMaster and client-side TRAP can be configured to write to OutputDebugString.

• Network communication can be captured with packet sniffer such as WireShark.

• VMWS diags can be enabled via UDT. Output will be in diag_w3wp* files.

• AuthenticationMgr diags can be enabled via UDT. Output will be in diag_AvCsGateway* files.

• TRAP (server side) diags can be enabled via UDT. Output will be in diag_AvCsMgr* files.

•CuSessionKeySvr diags can be enabled via UDT. Output will be in diag_AvMMProxySvr* files.



Diagnostic “Stack”:

Each component in the stack has some form of diagnostic available.

By following the communication flow through the stack, troubleshooting potential failures is easier.



Diagnostic Example (MM-to-VMWS connection attempt in VMO – diags collected from MediaMaster output):

7:06:07.296 PM [1364] IN CAvVMWSConnection::DoLogin7:06:07.312 PM [1364] 7:06:07.312 PM [1364] Proxy.SetScheme(ATL_URL_SCHEME_HTTPS) 7:06:07.312 PM [1364] 7:06:07.312 PM [1364] Proxy.SetIgnoreCertErrors(true) 7:06:07.312 PM [1364] 7:06:07.312 PM [1364] Proxy.SetTimeout(m_dwTimeout) 7:06:07.312 PM [1364] 7:06:07.312 PM [1364] Proxy.SetUseCurrentCreds(true) 7:06:07.312 PM [1364] 7:06:08.328 PM [1364] SendRequest error - WinHttpSendRequest:120297:06:08.328 PM [1364] 7:06:08.328 PM [1364] AuthService.Login returned: 0x800464037:06:08.328 PM [1364] 7:06:08.328 PM [1364] Proxy Url = https://unity/VMWS/VMWS.dll?Handler=Authentication7:06:08.328 PM [1364] 7:06:08.328 PM [1364] SOAP fault: 7:06:08.328 PM [1364] 7:06:08.328 PM [1364] CAvVMWSConnection::ConvertFaultToHr converts SOAP fault () to 0x80046403.

1. Connection parameters are set up: 1. ignoring HTTPs cert errors, 2. timeout3. use current credentials4. URL: https://unity/VMWS/VMWS.dll?

Handler=Authentication

2. WinHTTP error: 12029 ( defined by Microsoft as: ERROR_WINHTTP_CANNOT_CONNECT -12029

Returned if connection to the server failed).

3. Cisco C++ proxy code error: 0x80046403 ( defined by Unity as: E_WIN_HTTP_SOAP_CLIENT_CANNOT_CONNECT



Diagnostic Example (MM-to-VMWS connection attempt in VMO – summary of diags):

1. MediaMaster code sets up Proxy class based on configuration and default behavior(proxy class is an object of code that handles the network communication of HTTP/SOAP requests and responses.

2. HTTPs will be attempted. This can be seen with the ATL_URL_SCHEME of “HTTPS” (also by the leading “https” portion of the URL).Proxy.SetScheme(ATL_URL_SCHEME_HTTPS)

3. HTTPs errors will be ignored. If the server running VMWS had a self-signed certificate, that’s often considered a HTTPS “error”. If such a condition happened, the error would be ignored.Proxy.SetIgnoreCertErrors(true)

4. Timeout of the request is set to 30 seconds.Proxy.SetTimeout(m_dwTimeout)

5. The request will be made using the currently logged-on user’s credentials. Proxy.SetUseCurrentCreds(true)

6. The attempt to send the HTTP request failed. 12029 is the Microsoft error code under the condition,” Returned if connection to the server failed”SendRequest error - WinHttpSendRequest:12029

7. Unity code that wraps the WinHTTP requests returns error code signifying the connection attempt failed.E_WIN_HTTP_SOAP_CLIENT_CANNOT_CONNECT

Essentially, this failure happened because HTTPs was not configured on the Unity server running VMWS. Analysis of a network capture would show the 3-way TCP handshake to port 443 on the Unity server failing. In this condition, there would be no VMWS diags



Diagnostic Example (excerpts from a network trace):

POST /VMWS/VMWS.dll?Handler=CallControl HTTP/1.1SOAPAction: "#PlaceCall"User-Agent: WinHTTP Client/1.0Host: sea-alpha-utyContent-Length: 513Connection: Keep-Alive

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">

<soap:Body><PlaceCall xmlns="urn:CallControl">

<SessionId>4GJtwPn5nfBwShmqE1LEDZN3rwO6hFUCX1XrG4Lj32GuM8DukHUktQn81txU40ZHALglOpk6Y3KV/UdOAKTnNUBiHM80ak</SessionId>

<DestAddress>3011</DestAddress><MaxRings>4</MaxRings>

</PlaceCall></soap:Body>

</soap:Envelope>

HTTP/1.1 200 OKDate: Fri, 22 Jan 2010 18:29:16 GMTServer: Microsoft-IIS/6.0X-Powered-By: ASP.NETContent-Type: text/xmlContent-Length: 347Via: 1.1 Application and Content Networking System Software 5.5.13Connection: Close

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">

<soap:Body><PlaceCallResponse xmlns="urn:CallControl">

<CallId>9</CallId></PlaceCallResponse>

</soap:Body></soap:Envelope>



Diagnostic Example (IIS diags):

2010-01-22 00:19:38 10.93.132.69 POST /VMWS/VMWS.dll Handler=Authentication 80 - 64.101.44.136 WinHTTP+Client/1.0 200 0 02010-01-22 00:19:40 10.93.132.69 POST /VMWS/VMWS.dll Handler=CallControl 80 - 64.101.44.136 WinHTTP+Client/1.0 200 0 02010-01-22 00:20:49 10.93.132.69 POST /VMWS/VMWS.dll Handler=Authentication 80 - 64.101.44.136 WinHTTP+Client/1.0 401 5 02010-01-22 00:20:49 10.93.132.69 POST /VMWS/VMWS.dll Handler=Authentication 80 - 64.101.44.136 WinHTTP+Client/1.0 401 1 02010-01-22 00:20:49 10.93.132.69 POST /VMWS/VMWS.dll Handler=Authentication 80 CISCO\oliviers 64.101.44.136 WinHTTP+Client/1.0 500 0 02010-01-22 00:20:49 10.93.132.69 POST /VMWS/VMWS.dll Handler=Authentication 80 - 64.101.44.136 WinHTTP+Client/1.0 401 5 02010-01-22 00:20:49 10.93.132.69 POST /VMWS/VMWS.dll Handler=Authentication 80 - 64.101.44.136 WinHTTP+Client/1.0 401 1 02010-01-22 00:20:49 10.93.132.69 POST /VMWS/VMWS.dll Handler=Authentication 80 CISCO\oliviers 64.101.44.136 WinHTTP+Client/1.0 500 0 02010-01-22 00:21:02 10.93.132.69 POST /VMWS/VMWS.dll Handler=Authentication 80 - 64.101.44.136 WinHTTP+Client/1.0 200 0 02010-01-22 00:21:02 10.93.132.69 POST /VMWS/VMWS.dll Handler=Authentication 80 - 64.101.44.136 WinHTTP+Client/1.0 200 0 02010-01-22 00:21:05 10.93.132.69 POST /VMWS/VMWS.dll Handler=CallControl 80 - 64.101.44.136 WinHTTP+Client/1.0 200 0 02010-01-22 00:21:05 10.93.132.69 POST /VMWS/VMWS.dll Handler=CallControl 80 - 64.101.44.136 WinHTTP+Client/1.0 200 0 02010-01-22 00:21:05 10.93.132.69 POST /VMWS/VMWS.dll Handler=Authentication 80 - 64.101.44.136 WinHTTP+Client/1.0 200 0 02010-01-22 00:21:05 10.93.132.69 POST /VMWS/VMWS.dll Handler=CallControl 80 - 64.101.44.136 WinHTTP+Client/1.0 200 0 02010-01-22 00:21:05 10.93.132.69 POST /VMWS/VMWS.dll Handler=Messaging 80 - 64.101.44.136 WinHTTP+Client/1.0 500 0 02010-01-22 00:21:05 10.93.132.69 POST /VMWS/VMWS.dll Handler=Authentication 80 - 64.101.44.136 WinHTTP+Client/1.0 200 0 0

IIS is configured to write diags as well. Timestamps, IP address of client, URL content and HTTP returncodes are all present.

There is a lot of information on analyzing IIS logs. Here’s an interesting Microsoft link



Diagnostic Example (portion of VMWS diags from a SOAP request):

16:16:09:480 [64.101.44.136] SOAP/XML Request >>> <soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns:xsi='http://www.w3.org/2 16:16:09:481 [64.101.44.136] SOAP/XML Request >>> 001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:soapenc='http://schemas.x 16:16:09:480 [64.101.44.136] SOAP/XML Request >>> mlsoap.org/soap/encoding/'><soap:Body><IsConnected xmlns='urn:CallControl'><SessionId>n2QVVpq5EEsu32 16:16:09:481 [64.101.44.136] SOAP/XML Request >>> BcnUVT09SwMVWRLjPzGzA49ew01t9H9X4Ka2jYO/f/SHSXDVeip2tu3nm7eOiSrdBruB9KsL13nm+w3gfLeys18spJd2PewNKu2e 16:16:09:480 [64.101.44.136] SOAP/XML Request >>> uYiMnD4tVb</SessionId><CallId>6</CallId><TimeoutMs>1000</TimeoutMs></IsConnected></soap:Body></soap: 16:16:09:481 [64.101.44.136] SOAP/XML Request >>> Envelope> 16:16:09:480 [64.101.44.136] VMWSServerMgr::IncrementRequestCount - Request Count:1 16:16:09:481 [64.101.44.136:n2QVVpq5EEsu32BcnUVT09SwMVWRLj] IsConnected entered. 16:16:09:480 [64.101.44.136:n2QVVpq5EEsu32BcnUVT09SwMVWRLj] VMWSComponentMgr::GetAvCsGateway entered. 16:16:09:481 [64.101.44.136:n2QVVpq5EEsu32BcnUVT09SwMVWRLj] CoCreateInstance(CLSID_AvCsGateway 0 CLSCTX_LOCAL_SERVER IID_IAvCsGateway (void**)ppUnkGateway ) returned: 0x00000000 16:16:09:480 [64.101.44.136:n2QVVpq5EEsu32BcnUVT09SwMVWRLj] VMWSComponentMgr::GetAvCsGateway exited with 0x00000000. 16:16:09:481 [64.101.44.136:n2QVVpq5EEsu32BcnUVT09SwMVWRLj] VMWSServerMgr::EnusreServerActive -CoCreateInstance(CLSID_AvCsNodeMgrClientSupport) returned 0x00000000

1. Time stamp is in BLUE.2. IP address of calling client is in GREEN.3. “Raw” SOAP request is in RED.4. First 30 characters of the VMWS Session ID (returned from a SOAP request to “Login”) is in PURPLE.

(notice the same Session ID in the “Raw” SOAP request in the <SessionId> tags)5. Internal VMWS methods are in ORANGE.



Live Diagnostic Collection Tutorial…



Not Un-common Error Codes (WinHTTP from this link )

1. ERROR_WINHTTP_CANNOT_CONNECT (12029) - Returned if connection to the server failed.

2. ERROR_WINHTTP_CONNECTION_ERROR (12030) - The connection with the server has been reset or terminated, or an incompatible SSL protocol was encountered. For example, WinHTTP version 5.1 does not support SSL2 unless the client specifically enables it.

3. ERROR_WINHTTP_NAME_NOT_RESOLVED (12007) - The server name cannot be resolved.

4. ERROR_WINHTTP_SECURE_FAILURE (12175) - One or more errors were found in the Secure Sockets Layer (SSL) certificate sent by the server.

5. ERROR_WINHTTP_TIMEOUT (12002) - The request has timed out.



VMWS SOAP Faults

E_VMWS_GEN_SERVER_NOT_RUNNING - 0x80046202This fault signifies that a dependent voice mail service of the web service is not running. Receiving this fault can signify that although the VMWS is running, the voice mail server is not. Since the VMWS is a pass-through into the inner workings of the voice mail server, it may be inoperable when voice mail services are down.

E_VMWS_GEN_SERVER_NOT_ACTIVE - 0x80046203This fault signifies that the voice mail server in a Unity failover configuration is in an inactive state. A client can expect to receive this fault when one node in a Unity failover configuration has failed over to another node.

E_VMWS_GEN_SERVER_TOO_BUSY - 0x80046204This fault signifies that the VMWS server has surpassed its maximum, concurrent requests. A client can expect to receive this fault when the VMWS is under heavy load. The maximum, concurrent requests is configurable and can vary from server to server

E_VMWS_GEN_INVALID_SESSION - 0x80046205This fault signifies that the session obtained from the Login request has expired. Session expiry occurs upon lack of subsequent operations on a session. When a client request is made within a valid session, the session timeout is reset. Session timeouts are configurable and can vary from server to server.

E_VMWS_GEN_INVALID_INPUT - 0x80046206This fault signifies one of the elements of data provided by the client is deemed invalid. It is analogous to the common “invalid argument” return code often provided by APIs.



VMWS SOAP Faults (continued…)

E_VMWS_GEN_SUBSYSTEM_FAILURE - 0x8004620AThis fault signifies an underlying unknown error has occurred. It is analogous to the common and dreaded "E_FAIL“return code provided by APIs.

E_VMWS_AUTH_INVALID_USER_OR_PASSWORD - 0x80046240This fault signifies that either the username or password provided in the Login request was not valid.

E_VMWS_AUTH_PASSWORD_EXPIRED - 0x80046241This fault signifies that the password for the given username in the Login request has been expired.

E_VMWS_AUTH_ ACCOUNT_LOCKED - 0x80046242This fault signifies that the account for the given username in the Login request has been locked.

E_VMWS_CC_INVALID_CALL - 0x80046260This fault signifies that the call ID provided by the client is invalid. This can occur if client presents a call ID that has

beenpreviously disconnected.

E_VMWS_CC_NO_RESOURCE - 0x80046261This fault signifies that the voice mail server has no available voice ports to service the request.



VMWS SOAP Faults (continued yet again…)

E_VMWS_CC_DENIED_BY_RESTRICTION_TABLE - 0x80046262This fault signifies that the client has requested a call be made to a number that has been administratively restricted

forthe associated Subscriber.

E_VMWS_CC_DEST_RNA - 0x80046264This fault signifies that the client has requested a call be made to a number that did not answer.

E_VMWS_MSG_INVALID_MESSAGE_ID - 0x80046280This fault signifies that the message ID provided by the client is invalid. This can occur if client presents a message IDthat has been previously deleted.

E_VMWS_MSG_MAILSERVER_OFFLINE - 0x80046280This fault signifies that a required mail server to complete the requested operation is unavailable.



Resources:

• www.ciscounitytools.com

• Cisco Unity 8.0 Release Notes

• Cisco Unity 8.0 System Administration Guide

• Cisco Unity Voice Mail for Outlook Release Notes • http://msdn.microsoft.com/en-us/library/aa383770(VS.85).aspx (HTTP error codes)

•http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/3e27a577-a6e3-4b0b-9379-68efb5d52ee9.mspx?mfr=true (IIS diags)

http mediamaster feature

Documents