Thursday, 1 October 2015

Skype for Business / Lync Polycom VVX Manager Version 2


Polycom’s VVX range of phones on Lync/Skype for Business have come a long way in the past few years. The release of version 5.4 has delivered further improvements and new features and moved them into a position of superiority over even Lync Phone Edition devices. As a result, the VVX range are now being taken much more seriously by businesses for large scale rollout. Version 5.4 of VVX software has now also brought about support for remote management features by way of a RESTful web service interface. This was music to my ears as my previous VVX Management Tool was built on a combination of hacked together legacy features of the phones and can now be replaced with a supported API. So with this new API at my disposal, I decided to rip the guts out of the old version of the tool and re-engineer it from the ground up for an all new version 2.0 release!


Polycom VVX Manager Version 2 Features


Polycom VVX Phone Manager 2


Phone discovery – Phones can be discovered either by automatically querying the Lync/Skype for Business Monitoring database (provided there is a monitoring role deployed in the environment) by pressing the “Discover from Monitoring DB” button. Alternatively, this can be done by entering IP Address ranges and “pinging” contiguous subnet ranges for phones using the “Discover from IP Range” button (format: "192.168.0.1-192.168.0.20" OR "192.168.0.0/24" OR add multiple with comma separation "192.168.0.0/24,192.168.1.0/24"). During the discovery process, phones that are logged in to user accounts will be listed in the users list. If the tool finds a VVX handset that is not signed in, 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 signed into the system.

Important Note: The VVX Phone Manager Tool uses the registration database within the Lync/Skype for Business monitoring database to determine the IP addresses of phones. However, registrations are only added to this database at the time when a user manually signs in with a PIN or with Domain authentication details. If a user moves a phone to a new subnet or the IP Address changes without signing it out/back in then its new IP Address will not be written to the Monitoring database. So, in some cases, the Monitoring database may not produce a complete list of registered VVX devices. The "Monitoring DB Query Time" value in the "Settings" dialog can be used to extend how far back the Monitoring DB query will go to find VVX registrations. This can help to find phones that haven't been manually signed in for an extended period of time. Or alternatively, the "Discover from IP Range" option can be used to do an exhaustive scan of all subnets if required. 

Export/Import Phone Info – This feature outputs a CSV file that contains all the Users, IPs, Firmware Version, Serial Numbers, Lync/Skype for Business Server, and MAC Address (if available) for all phones. If you select the "More" checkbox you will also get the additional Lync/Skype for Business policy settings for each user (this is slower).

Access Web Interface - Access the web interface of a VVX phone by selecting a user in the user list and clicking the “Web Config” button. This will automatically load the web browser to the phone's web interface.

Pin control – The “Pin…” button will load a dialog that will Set, Test, Lock, Unlock a user’s PIN number.

PIN Dialog


Send Text Messages - Send text messages to be displayed on a Polycom VVX phone. 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.

Example of Message Screen

Note: Sending messages relies on the PUSH interface being enabled on the phone in order to accept the message. See the VVX Requirements section for more detail of this configuration. 

Get More Info – By pressing the “More Info” button you can get extended information about a VVX phone including: Device Info, Call Status, Presence Info, Network Info, Line Info, SIP Status, Network Statistics.

Reboot/Restart Phones – You have the choice of Rebooting or Restarting a single, multiple, or All phones.

Reset Config – You have the option to Reset the Config or Factory Reset the configuration with one or many phones.

Get/Set Config - You can Get or Set any setting in the phone configuration. You simply need to enter the configuration setting name (as you would find in the configuration file eg. log.level.change.hset) and click the Get or Set buttons to view or change the setting's value.

Dial / End Call – You can choose to remotely dial a SIP URI (eg. john.smith@domain.com or +61395551111@domain.com) on a phone by entering a URI and pressing the “Dial” button. If the phone is on a call you can also choose to end the call using the “End Call” button.

Test FTP Config Server - Test your FTP Configuration File 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.

View Screen – The “Screen…” button will open a dialog that will show you the user's screen. Before the user's screen can be viewed the user must first manually allow access to the Screen Capture feature (this is a security measure so that the user is aware that someone is viewing their screen). This setting within the Basic->Preferences screen will only be made available while the VVX screen dialog is displayed (the tool automatically makes the setting "up.screenCapture.enabled" in the device to turn on this preference setting). When the dialog first loads you will see a screen that looks like this:

VVX Screen Dialog


At this point the user will have to enable the following setting in their phone preferences:

Settings -> Basic -> Preferences -> Screen Capture -> Enabled

Note: The Screen Capture option is only available to the user once you have open the screen dialog with the VVX Manager Tool (so don’t close the dialog until the user has turned on the manual preference setting).

Now you will be able to see the user's screen and save screenshots of the screen as JPG files if you so desire:

VVX Screen Dialog



Command Line Settings – If you would like to load the script with your own specific settings to save time, you can specify these in the command line when loading the script. The format of the parameters are as follows:

Script command line settings:
.\Skype4B-Lync-PolycomVVXManager2.00.ps1 -WebPortInput 443 -UseHTTPSInput false -AdminUsernameInput AdminUsername -AdminPasswordInput AdminPassword -PushUsernameInput PUSHUsername -PushPasswordInput PUSHPassword -IPRangeInput 192.168.0.1-192.168.0.200



Settings Dialog – The “Settings…” button allows you to configure your own passwords, web service port and HTTPS settings for the tool.

Note: Continue reading for definitions of these settings.

UPDATES

2.01 Enhancements
  • Fixed issue with the Get Config function
  • Increased the timeout for discovery ping from 200ms to 350ms to handle sites that might be over a higher latency connection. Also added a setting called "Discovery Wait Time" which allows you to tune the time that the tool will wait for responses from discovery messages sent to phones (setting between 200ms-1000ms).

2.02 Enhancements
  • Fixed issue with rescan on CSV import.
  • Included new Polycom MAC Address range 64:16:7F
  • Added a discovery summary at the end of IP Based discovery. This gives a useful summary when scanning multiple IP ranges.
  • The command line input for IPRangeInput now accepts muiltple ranges in comma separated format. eg. Skype4B-Lync-PolycomVVXManager2.02.ps1 -IPRangeInput "192.168.0.1-192.168.0.200,192.168.0.10/24"

2.03 Bug Fix
  • There was an issue with detecting users when capital "SIP:" was used as part of their SIP URI. This has been fixed.
2.04 Bug Fix
  • Fixed a couple of typos that affected operation on Powershell 5
  • Added more VVX types when discovering logged out phones
2.05 Bug Fix
  • Added port number to screen viewing URL. Required when non-standard HTTP/HTTPS port is used.


Available on the TechNet Gallery:

DOWNLOAD HERE



Polycom VVX Manager Configuration Requirements


Firmware Requirements


The VVX phone must be at firmware version 5.4 in order to be controlled by the VVX Phone Manager Tool because this version is the first to support the new REST based management API. If you select a user that has a phone with an older version of software, the tool will display a warning in the Powershell window and give you limited access to features for that user. Note: software version 5.4.0A is required for VVXs connecting to Skype for Business.

VVX Web Server Settings


Since version 5.1 of VVX software, there have some increased security enhancements added to the phones. This increased security will affect your ability to connect to the web interface and web services interface of VVX devices when you are running them in an out-of-the-box configuration. So in order to use this tool you will need to edit some basic configuration settings on your phones (usually done via configuration files).

The following web server settings were added in version 5.1 VVX firmware:

Web Config Mode
httpd.cfg.enabled
httpd.cfg.secure
TunnelEnabled
httpd.cfg.secure
TunnelRequired
Disabled
0
0
0
HTTP Only
1
0
0
HTTPS Only
1
1
1
HTTP/HTTPS
1
1
0


Different combinations of these setting will give you access to either HTTP, HTTPS or both at the same time. Below are examples of how to achieve all of these settings:

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. If you do this, you will need to change the Web Port setting in the settings screen of the tool to match your selected port.


In addition to enabling the web server in the phone you must also change the default password on the device as well. If you do not do this the phone will display errors/warnings on the phone display and web interface (“Default admin password is in use, please contact your administrator”). Passwords can be configured in the configuration file as follows:

<!-- 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 has changed.

Enable REST API:


Config File Setting:

The following REST API setting must be enabled in order to use the Polycom VVX Manager Tool:

<apps apps.restapi.enabled="1" />

Web Interface Setting:

Settings -> Applications -> REST API

Note: If this setting is not configured you will receive "(404) Not Found" errors when trying to send commands to the phone.

Text Messaging Settings


In order to send messages to VVX phones you need to enable the Push settings in the configuration. You can do this with the following settings:

Config File Settings:
<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”. This can be changed in the Settings dialog in the tool.
  • apps.push.password: The phones use digest authentication for push connections. The password sent by the tool by default is “vvxmanager”. This can be changed in the Settings dialog in the tool.
  • apps.push.alertSound: Play a sound when the message is displayed. This is the standard Polycom sound that you hear when a phone reboots. This can help the user to see the message, as it will only be displayed for 30 seconds.


Web Interface Settings:

Settings -> Applications -> PUSH



MAC Address Display


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"/>
</device>

This will result in the MAC address being included in the device string, eg: “VVX Version: PolycomVVX-VVX_500-UA/5.0.0.6874_0004f28038f9”. 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.


Polycom VVX Manager Tool Settings


When connecting from the VVX Phone Manager you need to match the password that you configured in your phone with the tool. The settings can be entered into the tool by pressing the “Settings…” button:
  • REST Username: This setting is always set to “Polycom”.
  • REST Password: This setting needs to match the “device.auth.localAdminPassword” setting in your VVX phone. If the password is wrong and doesn't match your phone setting you will see "(401) Unauthorized" errors being returned from the phone when you try to send it commands.
  • PUSH Username: This setting needs to  match the “apps.push.username” setting in your VVX phone.
  • PUSH Password: This setting needs to match the “apps.push.password” setting in your VVX phone.
  • HTTPS: This needs to match your phone's configuration settings for “httpd.cfg.secureTunnelEnabled”
  • Web Port: This needs to match your phone's configuration settings for either “httpd.cfg.port” for HTTP or “httpd.cfg.secureTunnelPort” for HTTPS.
  • Monitoring DB Query Time: This setting determines how many months back in the monitoring database the tool will look for VVX phone registrations. By default this setting is 6 months, meaning that the IP Address of any VVX phone registered in the past 6 months will be scanned to see if it is still located at that IP Address. This setting can be increased if your VVX phones have not been manually signed out/in for longer than 6 months. Or if you have a site where users are frequently signing in and out of their VVX phones you can reduce this value to save time scanning old IP Addresses for VVXs. The setting can be set between 1-48 months (ie. from 1 month up to 4 years).
  • Discovery Wait Time: This setting allows you to tune the time that the tool will wait for responses from discovery messages sent to phones (setting between 200ms-1000ms). This can be helpful if you are trying to discover phones on a distant subnet with a high levels of latency.


SQL Requirements


In VVX Phone Manager 1.xx there was a requirement that SQL ports were opened on each Front End server for accessing information on phone IP Addresses (which work some of the time). This new version of the tool only requires access to the Monitoring database on the Lync / Skype for Business Backend SQL server in order to discover the IP Addresses of phones signed into the system.


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' great post on the different ways to deploy Polycom phones is here: 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 too.

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 subtle errors can cause things not to work as desired.


The Wrap Up


Well, that's it, my first version 2.0 script! Enjoy, and let me know if you have any issues, feedback or have any enhancement requests.



17 comments:

  1. Excellent work as usual! Great to see community support for these phones. One note to add, Lync/SfB customers should be running the just-released 5.4.0A firmware which is officially supported for Lync and SfB platforms.

    ReplyDelete
  2. This is great!! You sir, are amazing!
    I have been seeing mixed messages about "Text Messaging" Is this different than the push messages?
    I am getting the following powershell output:
    INFO: This phone has version 5.4 or higher software. All features supported.
    INFO: Sending message to: https://192.168.0.40:4433/push
    ERROR: Failed to connect to phone...
    Exception: The remote server returned an error: (405) Method Not Allowed.

    This is what i read from polycom advanced features page.
    "Enable Instant Messaging
    All phones (except the SoundPoint IP 321/331/335) can send and receive instant text messages. Phones registered with Microsoft Lync Server cannot send or receive instant messages"

    ReplyDelete
  3. Hi Ross, the tool is using the PUSH web interface on the phone to send HTML encapsulated text that gets displayed via the phones web browser. I believe the article that you have referenced is referring to SIP based text messaging (ie. SIP SIMPLE) which is a completely different thing. SIP based text messaging is not yet supported by the phone on Lync/Skype for Business.

    ReplyDelete
  4. Hi, thanks for the article, however I'm not able to see VVX phones on the tool even if I know for sure the are several VVX phones up and running (external trough the edge server)

    Any comment will be appreciated

    Have a nice day.

    ReplyDelete
    Replies
    1. Hi Dagho, the tool needs to be able to send a SIP message directly to the VVX and receive a response back. It sends the SIP message from a random source port to destination port 5060 on the VVX. So if the phones are on IP Addresses that are outside of the Edge you may not be able to directly connect to them due to firewalls blocking the ports or there being no direct route from your server to the VVX. This is a limitation of the way the tool works.

      Thanks for your message.

      Delete
  5. I can't seem to manage any phones in this GUI with the newest VVX firmware (5.5.0)anymore. It recognizes that the proper amount of phones exist, but they don't show up in the GUI. Is there an update for this tool?

    ReplyDelete
    Replies
    1. Hi Matt, I have not tested with Verison 5.5 of VVX because this version is not supported by Polycom on Lync/Skype for Business. The 5.5.0 release notes say the following: "Polycom will not support UC Software 5.5.0 use in Lync or Skype for Business deployments."

      Release notes are available here: http://downloads.polycom.com/voice/voip/uc/uc_software_release_notes_5_5_0.pdf

      Delete
    2. James - now that 5.5.1 is supported when will you be releasing version 2.05 that will recognized devices running that firmware?

      Delete
    3. Hi, version 2.04 works fine for me with 5.5.1. Is there a specific issue you are having?

      Delete
    4. James - I apologize, it is recognize them correctly. However, we are getting this error when trying to view the screen remotely:

      INFO: Enabling Screen Capture on 172.16.10.14
      ERROR: Failed to connect to phone...
      Exception: The remote server returned an error: (401) Unauthorized.
      ERROR: Unabled to enable screen capture for 172.16.10.14

      What could cause this?

      Delete
    5. This comment has been removed by the author.

      Delete
    6. Hi Again, in order to see the screen, a setting in the phone needs to be set by the tool (in addition to a setting made by the user). Polycom doesn't like the show screen feature turned on all the time because it uses CPU time and gets automatically turned off after every reboot (so the tool turns this setting on remotely each time). To turn the setting on the tool sends a special command to the VVX via the REST web interface. For this REST request to work the "REST Username" and "REST Password" must be set in the Settings section of the tool (to match your phone username/password). It is assumed that you have also configured the phone as detailed in the "VVX WEB SERVER SETTINGS" and "ENABLE REST API" of the blog post.

      Delete
  6. Very cool tool but I am having issues with adding phones by ip searching. after troubleshooting, I saw the vvx411's didn't have an -imatch since they are pretty new so I added that in the two spots IF statements but around line 7906, I noticed the $returndataSplit isn't splitting the string properly on my computer, just is a blank result. Not sure if there is a problem going on with that with Windows 10 powershell but wasn't able to query the vvx411 phones I have. Below is the print out of what it saw on my VVX411 phone as it scanned my network. Thanks.

    SIP/2.0 200 OK
    Via: SIP/2.0/UDP 10.101.2.9:55113
    From: ;tag=1530231855-106746376154
    To: "NAME" ;tag=8229510-7BBB22EF
    CSeq: 1500 NOTIFY
    Call-ID: 11092016131018msgtodiscover
    Contact:
    User-Agent: Polycom/5.4.5.6770 PolycomVVX-VVX_411-UA/5.4.5.6770
    Accept-Language: en
    P-Preferred-Identity: "NAME" ,
    Authorization: TLS-DSK qop="auth", realm="SIP Communications Service", opaque="975F0F23", crand="29BA8AF6", cnum="340", targetname="SFE.domain.com", response="77cd6fcbe6492a9c340efbd9c97fee125879c599"
    Content-Length: 0

    ReplyDelete
    Replies
    1. Hi Nicholas, The issue with your VVX not being discovered appears to be that the Contact field of the OK message is empty. This should at least have something in it because it's a mandatory SIP field! Did you delete this information from the message that you sent? If so, can you send me a full OK message from a "signed in" and "signed out" phone? Email: mylynclab at gmail. Thanks.

      Delete
  7. Hello,

    I've written before, but I'm not sure if I've gotten a response. The issue that I'm having is that the MAC address isn't being populated in the results. Can you tell me what I could potentially be doing wrong? Is there an output file that you need from me to see what is going on?

    ReplyDelete
    Replies
    1. Hi Chris,

      Yes, there are special settings you need to put in the configuration file to display the MAC Address. This was documented in the original post, I have brought forward the details to this post under the MAC Address Display heading.

      Cheers,
      James

      Delete
  8. Hi James,
    thank you for your terrific job! I'm getting 405 method not allowed error from VVX 201 phones whereas other VVX phones work properly. I'm using the same configs and 5.5.1.11526 firmware.
    Regards,
    Alessandro

    ReplyDelete

Popular Posts