Tuesday 3 December 2013

Lync Polycom VVX Manager Tool

UPDATE: There is now a new 2.0 version of the Polycom VVX Manager Tool available. See the blog post here for more details.

I’ve recently been doing a lot of work with deployment and management of Polycom VVX phones on Lync. Like always, I’ve found that when rolling out hundreds of any device, there are certain challenges that arise. One of the main challenges is: how do you centrally administer hundreds of devices that are distributed around a large geography, remotely? The short answer to this usually turns out to be: with great difficulty!

One of the first rules of a good centralised management solution is how much information you can get out of a system without having to ask the end user over the phone to tell you something about what they are seeing. A simple example of this might be with a VVX phone, when you get a report from a user that their phone is “broken”. In most cases this is about the level of detail you can expect from an end user, because to them the fact that the system voice policy is blocking them from dialling out is the same as their phone having caught fire and exploding while they were out at lunch… The fact is, they can’t make a call, so the phone is “broken”. As IT professionals though, we know there are a great many nuances as to why the phone may not be working for the end user. So we start stepping through the troubleshooting process… Is the phone plugged in? Is the phone configuration FTP server available? Did it receive the adequate information from DHCP to prompt for PIN sign in? Does the user even have a PIN assigned for them to actually sign in? Is the phone registered with the system? Does the user have the rights to dial the number they were dialling? etc…

So you probably get the picture. There’s a tonne of questions that need to be answered, and the last thing you want to do to answer them is ring the user on their mobile (because their desk phone is "broken") and ask them if they see a little green tick or a little red cross next to the phone icon on the upper left hand side of the screen… followed by a thousand other questions about the smouldering piece of burnt up plastic on their desk.  

So I figured I would try and put together a tool that might make answering these questions a little bit easier:

Lync Polycom VVX Manager

Last Updated ( 1/7/2014 )

1.01 Enhancements:
  • In the 1.00 release there can be cases where there is a VVX registered to the system but the tool reports them as having NO VVX in the ListView. This issue is a caused by the database entry for SipCallId containing junk information instead of the devices IP address. The processing has been changed in 1.01 so now when a VVX is registered it will always show up as YES in the listView. If there was no IP address in the database for the device then the IP will show as "IP NOT IN LYNC DATABASE" within the tool. A work around for this is to manually reboot the VVX, when it re-registers to the system the database field usually gets updated to contain the IP address again.
  • Text layout within the information text box has been changed to make it easier to read.
  • Added port variable for connecting to VVX via web browser when non standard port is used in the VVX configuration. Edit the $script:WebPort = "80" to whatever port your VVXs are using.
1.02 Enhancements:
  • Support added for secondary device discovery method. In previous versions the phone manager would discover the IP address of VVX phones from the Lync Server database. However, sometimes the Lync database did not have the data in it for every registered phone. So in version 1.02 a secondary "IP Range discovery" method has been added to discover phones on LAN segments. Simply type an IP Range (format: "" OR "" OR add multiple with comma separation ",") into the listbox and press the "Discover from IP Range" button. The tool will then "ping" the phones to see if they are at each IP in the range. This method is slower than the Lync database discovery (it can scan a 254 host range in ~60 seconds or less. Note: scanning directly connected subnets is slow because of ARP wait time), so you should only use it if you reciving "IP NOT IN LYNC DATABASE" for the IP Address of users with the default Lync Database discovery method.
  •  Added a new variable for https connections to the VVX web interface (as this will be the default in VVX 5.1 for the web interface when enabled). Change the variable $script:useHTTPS to be $true if you would like all web interface connections to use https instead of http. This will also require that you change the $script:WebPort variable to be "443" as well (or whatever port you set in the configuration file for https).
  • Export VVX phone deployment information. This outputs a CSV file that contains all the Users, IPs, Firmware Version, Serial Numbers, Lync Server, and MAC Address (if available) for all logged in phones. If you select the "More" checkbox you will also get the additional Lync settings for the phone (this is slower).
1.03 Enhancements:
  • Added the ability to send text messages to Polycom VVX phones. An example of this would be to send a message to warn before a system upgrade or a reboot. Messages are displayed on the screen for 30 seconds.

Version 1.03 Text Messaging Settings:

The Polycom VVX phones require special settings in order to receive messages from the Lync Polycom VVX Manager tool. The settings below will need to be added to your configuration files:

<apps.push apps.push.alertSound="1" apps.push.messageType="5" apps.push.serverRootURL="push" apps.push.password="vvxmanager" apps.push.username="vvxmanager"></apps.push>
  • apps.push.messageType: This sets the level of messages that will be displayed for the phone. The VVX Manager always sets the messages as “critical” so they will always be received. The setting “5” means that all levels of messages will be displayed by the phone.
  • apps.push.serverRootURL: This setting needs to be set to "push". This is used as part of the URI for sending messages to the VVX.
  • apps.push.username: The phones use digest authentication for push connections. The username sent by the tool by default is “vvxmanager”.
  • apps.push.password: The phones use digest authentication for push connections. The password sent by the tool by default is “vvxmanager”.
  • apps.push.alertSound: Play a sound when the message is displayed. This is the standard Polycom sound that you heard when a phone reboots. This can help the user to see the message, as it will only be displayed for 30 seconds.

Within the Powershell script you can change the Username and Password used for authentication to something else if you desire. Settings are here:

#Edit these settings if you would like to you customer username and password for messaging.
$script:pushUsername = "vvxmanager"
$script:pushPassword = "vvxmanager"

Example Message:
System Outage

1.04 Enhancements:
  • Had a report of some issues with case sensitivity with SIP URI's. Removed case sensitivity to correct the issue. (Thanks to Benoit Machiavello for reporting this issue)
  • (Request) Added ability to filter users list to only show users with VVX phones.

1.05 Enhancements:
  • Added the ability to import previously exported CSV files containing user/device information. This can save time scanning IP ranges for devices by only checking (ie. pinging each device to check who is logged in) the IP addresses from the CSV file. If you have a "known good" export (eg. an export that you may have been taken minutes earlier) you can directly import the settings without rescanning each device for changes. Importing without rescan can be a little risky if you're working with an older export, due to IP addresses and user logins of each VVX's possibly changing over time. So it is recommended that you use the rescan option to refresh all the user data within the VVX Phone Manager Tool's database.
  • If a VVX handset that is signed out is discovered, it will be added to the user list under the name “VVXNot@LoggedIn_<index number>”. This allows you to use the tool to access these devices even though they are not logged into Lync. This method only works with the IP Scanning method of discovery, it does not work when discovering from the Lync database.
  • Corrected an issue with the display of users that are logged into multiple phones. The tool will display multiple entries in the user list when user are logged into more than one phone.
  • The tool in previous versions would automatically load the user list and try to discover user information from the Lync database. This could waste time when first opening the tool for users that only wanted to use the IP Discovery method. To save time in these circumstances, from version 1.05, the tool will not automatically try to connect to the Lync server database when first opens. On first boot you can update the user list by clicking the "Discover From Lync Database" or enter an IP range and click the "Discover From IP Range(s)" button.
  • Added information in this post about using the VVX Phone Manager Tool with Version 5.1 VVX firmware. Read this section before updating your production firmware!

Download Version 1.05 here:

IMPORTANT UPDATE: Polycom VVX 5.1 Software Update Changes

Read this section before updating your production firmware!

Version 5.1 of Polycom VVX firmware has some increased security enhancements. This will affect your ability to connect to the web interface of VVX devices when you are running them in an out-of-the-box configuration. However, you can still have access to the web interface of the VVX phones by editing some configuration settings on the devices (usually done via a configuration FTP server).

The following web server settings have been enhanced in version 5.1 VVX firmware:

Web Config Mode

Example settings:

HTTP Web access only:
<!-- HTTP Admin Settings -->
<httpd httpd.enabled="1" httpd.cfg.enabled="1" httpd.cfg.port="80" httpd.cfg.secureTunnelEnabled="0" />

HTTPS Web access only:
<!-- HTTPS Admin Settings -->
<httpd httpd.enabled="1" httpd.cfg.enabled="1" httpd.cfg.secureTunnelPort="443" httpd.cfg.secureTunnelEnabled="1" httpd.cfg.secureTunnelRequired="1" />

Both HTTP and HTTPS web access: 
<!—HTTP and HTTPS Admin Settings -->
<httpd httpd.enabled="1" httpd.cfg.enabled="1" httpd.cfg.port="80" httpd.cfg.secureTunnelEnabled="1" httpd.cfg.secureTunnelPort="443" httpd.cfg.secureTunnelRequired="0" />

Note: If you would like to make the Web Admin harder for people to find you can change the port number to something different from the default 80 or 443 settings. Then in the VVX Phone manager you can change the $script:WebPort variable to whatever value you have chosen. If you want to use HTTPS from the tool, set the $script:useHTTPS setting to $true.

In addition to this you need to change the default password on the devices as to avoid errors/warnings popping up on the phone display and web interface (“Default admin password is in use, please contact your administrator”). These can be set here:

<!-- Passwords and Security -->
<device device.auth.localAdminPassword="12345" device.auth.localUserPassword="12345" />

Note: Make these passwords whatever you want them to be, however, they must be different than the default of 456 in order to avoid the warning message being displayed on the phone screen.

After you have changed these settings the web login and phone screen login passwords will be changed. So if your support staff have been trained to enter the default “456” password, don’t forget to tell them that it’s changed.

Features of Lync VVX Phone Manager

1. Find out information about VVX handsets connected to a Lync system (IP Address, the Lync server that the handset is registered to, user policies, PIN status).

2. Remotely reboot VVX handsets using the ‘Reboot’ button. Reboot a selection of handsets by selecting (hold shift/ctrl) multiple users in the list, then press the ‘Reboot’ button. Or reboot all the VVX handsets on a Lync system with the “Reboot All” button.

3.Set the PIN for a user - either a random PIN (if the PIN field is left blank), or specify a PIN number by filling in the field. This can also be done on multiple selected users.

4. Lock and unlock the PIN for a selected user with the ‘Lock PIN’ and ‘Unlock PIN’ buttons. This can also be done on multiple selected users.

5. Test your FTP Configuration server by simply entering the IP address of the FTP server and pressing the “Test FTP” button. The tool will attempt to connect to the FTP server and download information about key files associated with a Polycom configuration server deployment. These include the base configuration file (000000000000.cfg), configuration files in the CONFIG_FILES tag, any MAC address files associated directly with phones, and firmware files (*.sip.ld). The tool will give feedback as to the state of the FTP server.

6. Test PIN and device bootstrapping by entering a PIN number for the selected user and pressing the "Test PIN" button. The tool uses the Test-Bootstrap command in the background to imitate the process of a Lync Optimised Phone connecting to the system. Part of this process is that the Lync server generates a DHCP Inform request from the Lync server and sends it out to discover the Vendor Class Options (Option 43), and SIP server Option (Option 120) which it will then use the results of to generate a PIN authentication with the system. Below is an example of the DHCP message that the server sends out for this test:

This is awesome, but in some ways not a perfect test. It will depend on how you have set up your DHCP architecture throughout your sites as to the result of this process. You may either be using your Lync Server’s inbuilt DHCP server to respond to these INFORM messages, or you might be using a real DHCP server on your phone subnet to respond to these messages.

If you always receive the error “Did not receive any response for the DHCP discovery message.” when testing the PIN number, then it’s likely that there’s no DHCP server capable of responding to INFORM messages in the subnet that your Lync server is on. To get around this you can enable a special DCHP INFORM message responder in the Lync server.

The Lync Server DHCP server configuration lives under the registrar configuration. You can see the setting in Powershell by running this command:

PS > Get-CsRegistrarConfiguration

Identity                        : Global
MinEndpointExpiration           : 300
MaxEndpointExpiration           : 900
DefaultEndpointExpiration       : 600
MaxEndpointsPerUser             : 8
EnableDHCPServer                : True
PoolState                       : Active
BackupStoreUnavailableThreshold : 00:30:00
MaxUserCount                    : 7500
Note: This setting only answers DHCP inform requests with Vendor Class “MS-UC-Client”, and not basic Discover messages used for IP address configuration.

If this setting is set to True, the Lync server will respond to INFORM requests it sees broadcast on the subnet. So if you don’t have a DHCP server on you Lync server subnet (which you may not if your servers are deployed in a data centre) you may have to substitute for this by turning on the DHCP server in the Lync server.

If you do choose to implement this work-around, be sure to understand that the environment the Lync server is in may not be the same as the one the phone is deployed in. You will need to ensure that the phone is getting the correct information for its DHCP INFORM requests as well. So be sure to check your DHCP configuration for the subnets that the phones are deployed on (ie. 001 – UCIdentifier, 002 – URLSchme, 003 - WeServerFqdn, 004 - WebServerPort, 005 - CertProvRelPath, 120 - UCSipServer). If you want to know more about the DHCP options required for Lync phones, have a read of the in-depth Understanding DHCP Option 43 article by Jeff Schertz.

7. Easily connect to the VVX web interface of any user on the system by clicking the “Web Config” Button.

 The Polycom VVX has a web interface which can be quite useful for troubleshooting issues with Lync. It includes a page dedicated to Lync specific settings (Diagnostics->Lync Status), that gives lots of good information:

As you can see in the picture above, there is some very useful information held in the Lync Status page.  So if you’re having some issues with a phone, just find the user in the Lync Polycom VVX Manager Tool and click the “Web Config” button. This will connect you directly to the user’s VVX web interface. You can also configure logging on the phone from the web configuration page, and view/download the logs directly from the browser as well.

Note: When Polycom phones are put into Lync mode, not all of the features in the web interface are relevant. This is because the web interface still has all the Standard SIP mode features (used for other platforms) still in it. So be careful not to assume that changing random settings will have the desired effect.

Prerequisites to use VVX Manager

In order for the “Reboot” and “Reboot All” buttons to actually reboot your phones, you will need to configure a special setting within the configuration files used by your phones. The reboot buttons in the tool use a specially crafted SIP NOTIFY message that tells the phone to re-download its configuration files from the configuration FTP server. This updates most settings in the phone, but not always all of them. To force the phone to do a full reboot, which ensures that all settings are applied you need to add the following settings in your phones configuration files:

<voIpProt voIpProt.SIP.specialEvent.checkSync.alwaysReboot="1" />

Note: If you already have phones deployed, you can add the setting to the configuration file, and press the reboot button on the tool once to make the phones re-download their files (which will also update this setting). From then on you will be able to do full reboots of the phone from the tool.

Another suggestion that may be of use: if you want to be able to remotely tell what the MAC address is of a phone (useful when building phone specific config files) from the VVX Phone Manager tool interface without having to open the web config, add the following setting:

<device sec.tagSerialNo="1">
   <prov device.prov.tagSerialNo="1"/>

This will result in the MAC address being included in the device string, eg: “VVX Version: PolycomVVX-VVX_500-UA/”. If you do this, the tool will also check the FTP server for individual MAC address files and tell you which phones have these when the “Test FTP” button is pressed.

Note: See 1.03 release information for Text Messaging requirements.

Allow Call Park Manager to Connect to Remote Pools

In order for the Lync VVX Phone Manager to learn about the phones connected to your deployment, it needs access to your RTCLOCAL databases for each Front End server pool. If you only have one Standard Edition server, then you can run the tool directly on this server and it will be able to access the RTCLOCAL database directly. However, if you have multiple pools, the VVX Phone Manager will try and connect to each pool to download all the registered endpoint data for each pool.

In order for the SQL connection to be made, inbound connections to the SQL Browser Service and RTCLOCAL database will need to be allowed through the Windows firewall. These rules are not created automatically during Lync Server Setup like most of the other rules are. So to open the ports, download the script below and run it on all of your front end servers (including SBA and SBS servers).

Run the script included in the VVX Manager Tool zip file (OpenSQLPortsForVVXManager1.00.ps1) on the server you want to open the SQL Browser and RTCLOCAL Dynamic TCP SQL ports on (ie. all Front End servers and SBAs/SBSs). If you would like to know more about how to manually do this configuration, there’s more information on my Call Pickup Group Manager Tool post.

Note: This is the same process as is used for the Lync 2013 Call Pickup Group Manager tool. So if you have already opened the ports to run that tool, you don’t have to do it again.

Getting Started with a Polycom VVX Deployment

This article was written under the assumption that you already have VVX phones deployed, and you are now looking to manage them. If you need some more help with the initial deployment part of the process, I can point you to some useful resources:

Jeff Schertz' post on the different ways to deploy Polycom phones here in his article entitled Provisioning Polycom SIP Phones. Greig Sheridan also has a nice post on Optimising the Polycom VVX for Lync that you might want to check out.

If you would like to know more about what is supported on Lync with VVX phones and setting up a FTP server to support Polycom Configuration files on Lync, go to the Polycom VVX support page and grab a copy of the lovingly entitled: “Deploying Polycom® UC Software for use with Microsoft® Lync™ Server”.

An important recommendation that I can give you is to always test your configuration files on a real phone before deploying them into the wild, because very subtle errors can cause things not to work as desired.

The Wrap Up

As always, feel free to give feedback regarding bugs and issues you find with the tool, I will endeavour to fix any issues that I can reproduce. Other than that, I hope that you get many hours of enjoyment out of this new tool, and that it saves you many additional hours in the process. As Humphrey Bogart says at the end of Casablanca “Louis, I think this is the beginning of a beautiful friendship.” Fade to black. Roll credits.


Popular Posts