Script: Get-CsConnections.ps1 – See User Connections, Client Versions, Load Balancing in Lync Server
Tracy A. Cerise and Mahmoud Badran came up with a script to show Lync connections, and the users connected. This was quite informative as it could be used to show load balance distribution, client versions being used, and more.
I took the script and updated it a little, including:
- Removed the help function and the header block and inserted comment based help. So a user can run get-help Get-CsConnections.ps1 and get the help, just like any other script and cmdlet.
- Added a parameter to display the user list. My needs didn’t require the user list – just the statistics at the beginning. So I added the feature to show the user list by running Get-CsConnections.ps1 –IncludeUsers.
- Added a couple of functions, including one that cleans up some variables when exiting.
- Adjusted some of the formatting. I noticed things didn’t always line up when the server FQDNs were really long, like those in child domains.
- Did a prereq check to verify the Lync module is loaded. If not, it gets loaded. That way, the script will still run fine if it’s run from an ordinary PowerShell console.
- Accounted for the pool parameter being just a NetBIOS name by adding the $env:userdnsdomain to the NetBIOS name to create the FQDN. This appears to work fine if the Lync servers and user running the script are both in the same domain. If not, then an FQDN would be required.
- Renamed the script to Get-CsConnections.ps1 and some of the functions to the normal verb-noun format.
- Added a feature to show just a specific client version number, and the users connected with that client version. This can help you determine who is connecting with what versions, which is helpful when looking into licensing, upgrades, etc.
- Added support for Lync Server 2013, which uses a different query than Lync Server 2010.
- Tons more info in updates and releases following that. See the changelog for more info.
Get-CsConnections.ps1 [[-Pool] ] [[-SIPAddress] ] [[-FilePath] ] [-IncludeUsers] [-IncludeHighUsers] [-IncludeSystem] [[-UserHighConnectionFlag] ] [[-ClientVersion] ] [-ShowFullClient] [ShowTotal] [[-Server] ] [-WhatIf] [-Confirm] 
Run the script specifying the front end pool or server to target:
Get-CsConnections.ps1 -Pool [pool FQDN]
Get-CsConnections.ps1 -Server [server FQDN]
The script automatically determines the version (2010 or 2013) of the pool, and uses the correct query.
If I can find an auto-detect method for server versions, I’ll include that in a later build.
Will show you unique client versions, their user agent, and the number of connections for each:
Distribution of connections across frontend servers (load balancing):
The number of unique users and clients connected:
And, adding the -IncludeUsers switch, such as:
Get-CsConnections.ps1 -Pool [pool FQDN] -IncludeUsers
will also show the users who are connected, and the number of connections they each have:
Using -IncludeHighUsers instead of -IncludeUsers will only list those users who meet the UserHighConnectionFlag (shown in white) or exceed the UserHighConnectionFlag (shown in red).
Get-CsConnections.ps1 -SipAddr [sip address] -Pool [pool FQDN]
Will show you the information for a single user:
Get-CsConnections.ps1 -Pool [pool FQDN] -ClientVersion [version number]
Will show the connection data for just that version number, including listing the users connected with that client version. This is helpful if the first method lists some version numbers you’d like to track down. Here, I used a client version of 13.1. MC/13.1.x is the OCS client on the Mac.
Using the -ShowFullClient option will show extended info for client name/version. However, the previous ‘Client Version’ column is not shown due to formatting restrictions. Here we can see more info, especially about mobile devices, Lync Phone Edition, and Mac clients.
Using -ShowTotal will also add additional info to the bottom section, including total number of users who are Lync enabled, total who are voice enabled, and percentage of total Lync enabled users who are connected.
You can export the info to a .csv file for viewing/manipulation in Excel using:
Get-CsConnections.ps1 -Pool [pool FQDN] -FilePath [path to csv file]
Execution Policy: Third-party PowerShell scripts may require that the PowerShell Execution Policy be set to either AllSigned, RemoteSigned, or Unrestricted. The default is Restricted, which prevents scripts – even code signed scripts – from running. For more information about setting your Execution Policy, see Using the Set-ExecutionPolicy Cmdlet.
NOTE: In order to gain remote access to each Front End server’s RTCLOCAL database where connection information is found, you need to open two local firewall ports; one static UDP port (1434), and one dynamic TCP port. We can use netsh to open the two required ports. First, open an elevated command prompt, and paste the following line. You should get “Ok.” in return:
netsh advfirewall firewall add rule name="SQL Browser (UDP 1434)" dir=in action=allow protocol=UDP localport=1434 profile=domain description="Created for Get-CsConnections.ps1. For more information, see http://www.ehloworld.com/269"
Next, find the dynamically assigned port used by the Named Instance (RTCLOCAL):
- On the Front End server, open SQL Server Configuration Manager.
- Expand SQL Server Network Configuration.
- Click on Protocols for RTCLOCAL.
- On the right side, right click on TCP/IP, and choose Properties.
- Click on the IP Addresses tab.
- Scroll to the last section, called IPAll.
- Note the TCP Dynamic Ports value
Replace [dynamic port] in the code below with the dynamic port number, and run the entire following command:
netsh advfirewall firewall add rule name="SQL RTCLOCAL Dynamic Port (tcp-in)" dir=in action=allow protocol=TCP localport=[dynamic port] profile=domain description="Created for Get-CsConnections.ps1. For more information, see http://www.ehloworld.com/269"
If you look at the inbound rules for the firewall, you’ll now see the two new rules:
Repeat the process for both ports on each Front End server.
Note: The dynamically assigned port is unique to each Front End server, not the pool. So you’ll need find the value on each server. Once the two ports are open on each Front End server in the pool, the script should work fine.
v2.5 – 11-26-2013 Get-CsConnections.v2.5.zip
v2.4 – 09-13-2013 Get-CsConnections.v2.4.zip
v2.3 - 08-01-2013 Get-CsConnections.v2.3.zip
v2.2 – 05-10-2013 Get-CsConnections.v2.2.zip
v2.1 – 12-13-2012 Get-CsConnections.v2.1.zip
v2.0 – 10-16-2012 Get-CsConnections.v2.0.zip
v1.9 – 09-21-2012 Get-CsConnections.v1.9.zip
v1.8 – 09-14-2012 Get-CsConnections.v1.8.zip
See the changelog for a complete list of features added in each release