21 User Information Commands to Run Before You Die

Perhaps the hottest trend in the publishing world these days is the 1,001 Things approach: 1,001 Places to See Before You Die; 1,001 Movies You Must See Before You Die; 1,001 Books You Must Read Before You Die. So what’s wrong with these books? Nothing, nothing at all. However, they did get us to thinking. Imagine this scenario:

It’s many years from now, and you’re lying on your death bed thinking, “Well, OK, so I did get to see the covered souks of Aleppo, and I did visit the Okavango Delta in Botswana. But I never got a chance to run any Microsoft Lync Server 2010 commands that return information about my users and their user accounts. I wasted my entire life!”

Do you want this to happen to you? We didn’t think so. That’s why we’ve put together our own addition to the 1,001 Things genre: 21 User Information Commands to Run Before You Die!

With our writing style, there’s always a good chance one or more of our readers will die of boredom at any given time. Therefore, we better get right to the 21 commands. Note that we won’t bother to explain how these commands work. For more information, take a look at the article Retrieving Active Directory and Microsoft Lync Server 2010 User Accounts.

And, sure, go ahead and finish those 1,001 books first. But then take a look at that article.

Here are the commands:

Returning all the users in an OU

This one is pretty straightforward: it returns a collection of all the Active Directory users accounts found in the Sales OU (as well as any child OUs of the Sales OU). Note that you must enter the Active Directory distinguished name of the OU in question:

Get-CsAdUser –OU "OU=Sales,dc=litwareinc,dc=com"

If you want a collection of all the user accounts that have been enabled for Lync Server (as opposed to all the user accounts, enabled for Communications Server or not) then use the Get-CsUser cmdlet instead:

Get-CsUser –OU "OU=Sales,dc=litwareinc,dc=com"

Although there will be some exceptions, for most of these commands you can use either Get-CsAdUser (if you want information about all your Active Directory user accounts) or Get-CsUser (if you want information only about accounts that have been enabled for Lync Server).

Note that this returns users who have had their Active Directory accounts disabled. If you can wait a second, we’ll show you a command that returns users who have had their Lync Server accounts disabled.

Get-CsAdUser | Where-Object {$_.UserAccountControl –match "AccountDisabled"}

This is another easy one: as you can see, it returns all the users who work in the Sales department. Need a list of all the users who work in the Human resources department? That’s fine; just replace Sales with Human Resources: –LdapFilter "Department=Human Resources".

Here’s the command:

Get-CsAdUser –LdapFilter "Department=Sales"

In the world of LDAP (Lightweight Directory Access Protocol), the l (lower L) attribute is short for locality:

Get-CsAdUser –LdapFilter "l=Redmond"

Here’s a command that returns all the users who work in the country (c) of Uruguay:

Get-CsAdUser –LdapFilter "c=UY"

What if you some of your users don’t work in Uruguay? That’s OK; just use the appropriate ISO-3166 country code. You can find a list of two-letter country codes here: http://www.iso.org/iso/english_country_names_and_code_elements.

Oh, here we go. This command returns a collection of users whose accounts have been enabled for Microsoft Lync Server:

Get-CsAdUser –Filter {CsEnabled –eq $True}

And, as promised, this one returns all the accounts that have not been enabled for Lync Server:

Get-CsAdUser –Filter {CsEnabled –eq $False}

You say you created a per-user conferencing policy named RedmondConferencingPolicy only you can’t remember which users have actually been assigned that policy. This command should help:

Get-CsUser –Filter {ConferencingPolicy –eq "RedmondConferencingPolicy"}

Here’s a useful query: it returns a collection of all the users who have been assigned a per-user voice policy of some kind:

Get-CsUser –Filter {VoicePolicy –ne $Null}

See Command 7 if you’re interested in returning information about users who have been assigned a specific policy.

Which user was assigned the line URI (425)555-1298? Beats us. But this command should tell you:

Get-CsUser –Filter {LineUri –eq "TEL:+14255551298"}

Remember that famous line from Shakespeare “First, kill all the lawyers”? Scholars now believe that that was a misprint. What Shakespeare actually said was, “First, find all the lawyers.” That line was inspired by the following command:

Get-CsAdUser –LdapFilter "Title=Attorney"

OK, we showed you how to find a user who had been assigned a specific line URI. But now you need to find a list of all the Lync Server-enabled users who’ve been assigned a line URI of some kind. Okey-doke:

Get-CsUser –Filter {LineUri –ne $Null}

And this command shows you all the Lync Server-enabled users who haven’t been assigned a line URI:

Get-CsUser –Filter {LineUri –eq $Null}

This one’s so easy we’re almost too embarrassed to add it to the list.

Like we said, almost too embarrassed:

Get-CsUser -Filter {EnterpriseVoiceEnabled –eq $True}

This one is pretty handy; just make sure you configure the Office property in Active Directory Users and Computers:

Get-CsUser –LdapFilter "physicalDeliveryOfficeName=Building 32"

Yes, you can use PIN numbers for dial-in conferencing authentication, but only if you’ve actually been assigned a PIN number. Here’s a command that returns a collection of all the users who’ve been assigned a PIN number:

Get-CsUser | Get-CsClientPinInfo | Where-Object {$_.IsPinSet –eq $True}

Audio Conferencing Providers enable users to conduct audio-only conferences with people both inside and outside the organization. How do you know if any of your users have been assigned an Audio Conferencing Provider? Well, you could walk around and ask them all. Or you could run this command:

Get-CsUserAcp –Filter {AcpInfo –ne $Null}

Microsoft Lynjc Server 2010 is designed to play nicely with others; for example, you can simultaneously run both Communications Server “14” and Office Communications Server 2007 R2 as you slowly begin to migrate from 2007 R2 to the new product. Let’s assume you do that, and let’s assume you now need to know which users are homed on 2007 R2. If that’s the case, then this command should come in handy:

Get-CsUser -OnOfficeCommunicationServer

This is really nice when you’re testing new commands or scripts. If you have 10,000 users in your organization, you might not want to return all 10,000 user accounts, especially if you’re trying out a new script for the first time. Fortunately, the –ResultSize parameter lets you specify the number of accounts to be returned. Only want to get back 10 accounts, even if you do have 10,000 users enabled for Lync Server? Then run this command:

Get-CsUser –ResultSize 10

You say you need to temporarily shut down one of your Registrar pools, and you’d like to run a command that returns a collection of all the user accounts that are homed on that pool? You mean a command like this one?

Get-CsUser –Filter {RegistrarPool –eq "atl-cs-001.litwareinc.com"}

What’s a private line? Let’s quote from the Lync Server PowerShell help:

“A private line is a phone number that is not published in Active Directory, and thus is not readily available to other people. In addition, this private line bypasses most in-bound call routing rules; for example, a call to a private line will not be forwarded to a person's delegates. Private lines are often used for personal phone calls or for business calls that should be kept separate from other team members.”

Here’s how you can return a collection of all the users who have been assigned a private line:

Get-CsUser –Filter {PrivateLine –ne $Null}

Believe it or not, it can happen: sometimes you have users who have been enabled for Lync Server but who are not assigned to a Registrar pool (meaning that they can’t actually log on to Lync Server). Do you have any Lync Server-enabled users who aren’t assigned to a Registrar pool? There’s one way to find out:

Get-CsUser -UnassignedUser

This one is cool, and one that we will explain, sort of. It’s a command that returns all the users whose Active Directory user accounts were created on June 1, 2010 or later:

Get-CsAdUser –LDAPFilter "(WhenCreated>=20100601000000.0Z)"

We won’t go into enormous detail in explaining how this command works; we’ll save that for a future article. (See? Yet another reason to live!) But we will explain what the date 20100601000000.0Z means:

Put them altogether and you get a date that looks like this:

20100601000000.0Z

You don't have to be working on your server machine to manage Microsoft Lync Server 2010 with PowerShell, all you really need is Windows PowerShell 2.0 and this Quick Start guide: Quick Start: Managing Microsoft Lync Server 2010 Using Remote PowerShell. This guide will take you through, step-by-step, setting up a remote connection to Lync Server PowerShell. You'll be up and running in no time.

Most of the articles found on this site assume that you are working on a computer running a Microsoft Lync Server 2010 service or server role, and that the Lync Server Management Shell has been installed on that computer. We did that for two reasons: 1) That’s the easiest way to do things; and, 2) It lets us put the focus on the task at hand (e.g., creating a new voice policy) rather than the preliminary commands required to manage Lync Server from a computer where the Management Shell has not been installed.

But while that might make our lives easier, it doesn’t necessarily make your lives easier. After all, you might want to do at least some of your management tasks remotely; for example, you might want to configure your Address Book servers or enable a few user accounts while sitting at your desk rather than at a Lync Server front end machine. Fortunately, that’s very possible to do; unfortunately, it’s not immediately obvious how you would go about doing that.

But that’s OK; that’s why we decided to put together this Quick Start guide to remote management of Microsoft Lync Server 2010.

Step 1: Make Sure You’re Running Windows PowerShell 2.0

What happens if you’re not running Windows PowerShell 2.0? Nothing – literally. You must have Windows PowerShell 2.0 or you will never, ever be able to use PowerShell to manage Lync Server. If you aren’t sure what version of PowerShell you’re running then start up Windows PowerShell and type this at the PowerShell prompt:

Get-Host

In turn you should get back something similar to this:

Name             : ConsoleHost

Version          : 2.0

InstanceId       : b4c50031-fcae-4d6e-ab0b-200b6beecf9f

UI               : System.Management.Automation.Internal.Host.InternalHostUserInterface

CurrentCulture   : en-US

CurrentUICulture : en-US

PrivateData      : Microsoft.PowerShell.ConsoleHost+ConsoleColorProxy

IsRunspacePushed : False

Runspace         : System.Management.Automation.Runspaces.LocalRunspace

If the Version property isn’t equal to 2.0 then you’re not running PowerShell 2.0.

But hey, don’t cry; after all, you can always download and install the latest and greatest version of Windows PowerShell from here: http://support.microsoft.com/kb/968929.

As soon as you’re confident that you’re running PowerShell 2.0 you can move on to Step 2.

And no, no rush; take your time. We’ll wait.

Step 2: Create a Windows PowerShell Credentials Object

OK, admittedly, this step might be optional: it depends on the user account you used when you logged on to Windows in the first place. For this Quick Start guide, however, we’re going to assume that the account you used to log on to Windows isn’t the same account you use to manage Lync Server. (That’s a security best practice, and we know that everyone always follows our security best practices.) Regardless, we need to create a credentials object (a very secure credentials object, we might add) that contains our user name and password. To do that, first type the following at the command prompt, substituting your domain name for litwareinc and your logon name for kenmyer (make sure you’re using the domain name and logon name for your Lync Server administrator account):

$credential = Get-Credential "litwareinc\kenmyer"

That should bring up a credentials dialog box that looks a little something like this:

Type your password in the Password box and then press ENTER. When you do so, the dialog box will disappear and you should see something like this:

UserName                                               Password

--------                                               --------

litwareinc\kenmyer                  System.Security.SecureString

If you do, then you’ve successfully created the credentials object. But save your self-congratulations for later; it’s time for Step 3. If you don’t see something like this type $credential at the PowerShell prompt and then press ENTER. If you still don’t see something like this then you’ll need to go back and try Step 2 from the beginning.

Step 3: Creating a Remote PowerShell Session

Now the fun part begins: it’s time to make a connection to one of your front end Lync Server machines (in this case, atl-cs-001.litwareinc.com). How do you do that? Why, by running the following PowerShell command, of course:

$session = New-PSSession -ConnectionUri "https://atl-cs-001.litwareinc.com/OcsPowershell" -Credential $credential

When you run this command, it might not look like anything happened. To verify that something did happen (and that you were able to make a connection to atl-cs-001) type $session at the Windows PowerShell prompt and then press ENTER. If all went well you should see something similar to this:

Id  Name      ComputerName  State   ConfigurationName    Availability

--  ----      ------------  -----   ------------------   ------------

 1  Session 1 atl-cs-00...  Opened  Microsoft.PowerShell    Available

OK, so now are we ready to start managing Lync Server remotely? Well, almost. First, however, we have to import our new PowerShell session; that’s because we still don’t have access to all the Communications Server cmdlets. To verify that, type the following at the Windows PowerShell prompt and then press ENTER:

Get-CsVoicePolicy

You should get back an error message stating that:

The term ‘Get-CsVoicePolicy’ is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

So should you check the spelling and try again? No. Instead, move on to Step 4.

Step 4: Importing the Remote PowerShell Session

When you import a PowerShell session you will finally have access to all the Lync Server cmdlets. (Well, maybe not all of them; we’ll explain that in a moment.) To import your new session, just type the following at the Windows PowerShell prompt and then press ENTER:

Import-PsSession $session

There will likely be a momentary pause while PowerShell retrieves all the relevant cmdlets, functions, scripts, and other Communications Server-paraphernalia, and then, at long last, you should see something like this onscreen:

ModuleType   Name                       ExportedCommands

Script       tmp_77b73956-53ca-4e7a...  {New-CsNetworkInterSitePol...}

And now if you type Get-CsVoicePolicy you should get back, well, you should get back information about all your voice policies.

Well, assuming you have permission to run Get-CsVoicePolicy in the first place. It’s important to keep in mind that Lync Server enforces RBAC (Role-Based Access Control) on all remote management sessions. What does that mean? Well, in Lync Server, the administrative tasks you are allowed to carry out are based on the RBAC roles that have been assigned to you; in turn, each RBAC role is assigned a number of Lync Server cmdlets. For example, suppose you’ve been assigned a hypothetical RBAC role that gives you access to only four cmdlets:

·         Disable-CsUser

·         Enable-CsUser

·         Get-CsUser

·         Set-CsUser

What do you suppose is going to happen if you try to run the command Get-CsVoicePolicy? You got it: you’re going to get back this same error message:

The term 'Get-CsVoicePolicy' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

Why that error message? Here’s why: When you import your PowerShell session RBAC ensures that the only Lync Server cmdlets that get imported are the ones that have been assigned to your RBAC role. If you want to see all the Lync Server cmdlets you have access to during your remote session, type this command at the PowerShell prompt and then press ENTER:

Get-Command *-Cs* -CommandType Function

Note. Yes, that command does return functions rather than cmdlets. But that’s because PowerShell imports cmdlets as functions rather than as cmdlets.

If your RBAC role limits you to four cmdlets then Get-Command is only going to return the following items:

Disable-CsUser

Enable-CsUser

Get-CsUser

Set-CsUser

As you can see, the Get-CsVoicePolicy cmdlet was never imported. That’s why PowerShell says it has no idea what you’re talking about when you try to run Get-CsVoicePolicy.

Note: To learn more about RBAC in Lync Server, read A Brief Introduction to Role-Based Access Control – Part 1.

Incidentally, even if you’re the Grand Pooh-Bah of Lync Server you won’t have access to all the Lync Server cmdlets when working remotely. That’s because a handful of cmdlets -- such as Test-CsComputer – can only be run locally; they will not work in a remote session. Fortunately, Lync Server is smart enough not to hand over those cmdlets when you import the PowerShell session. You might not have all the cmdlets available to you in a remote session, but you can rest assured that all the cmdlets that are available to you will work as expected.

Note. Of course, that doesn’t mean that you won’t occasionally run into things that don’t work as expected. For example type this at the Windows PowerShell prompt and then press TAB:

Get-CsV

PowerShell should respond by invoking tab expansion and changing your command to this:

Get-CsVoiceConfiguration

OK, now type this at the PowerShell prompt and then press TAB:

Get-Help Get-CsV

You might expect that PowerShell would invoke tab expansion and change your command to this:

Get-Help Get-CsVoiceConfiguration

For better or worse, however, it won’t expand Get-CsV, at least not in this case. Why not? Well, when you invoke TAB expansion when using Get-Help PowerShell looks for a cmdlet that starts with Get-CsV. However, we don’t have any cmdlets that start with Get-CsV; remember, all our Lync Server cmdlets were imported as functions. As a result, tab expansion won’t work with Get-Help. If you want more information about Get-CsVoiceConfiguration you’ll just have to type in the entire command:

Get-Help Get-CsVoiceConfiguration

Step 5: Ending Your Remote Windows PowerShell Session

What? All that work and now you want to quit? OK, fine; all good things must come to an end, right? If you want to end your remote management session just type the following at the Windows PowerShell prompt and then press ENTER:

Remove-PsSession $session

That’s all you have to do.

Step 6: What Comes Next?

As you might expect, there are plenty of nuances we haven’t covered yet; we’ll have to get to those at a later date. In the meantime, though, this should get you started. Which, needless to say, is about all you can ask from a Quick Start guide.

How to Find That Setting

Our first (of many, we hope!) tip from Edwin Young, lead developer for Microsoft Lync Server 2010 PowerShell. Having played a major role in the design and implementation of the LynServer PowerShell implementation, Edwin knows just how extensive it is. In this article, "How to Find That Setting," Edwin shows you a few commands that will make it easy for you to find the exact setting you're looking for so you can review or modify values.

In-Band Provisioning and Microsoft Lync Server 2010

A Senior Consultant for Microsoft Lync Server, Daniel Monier-Reyes knows all about client management. Here's a little something he put together that maps in-band provisioning to PowerShell. It's come in pretty handy already for some of our other consultants, it just might help you out, too.

Submitted by Edwin Young, Microsoft

Microsoft Lync Server 2010 is a pretty complicated product, and has quite a lot of different options that can be configured. One problem you’ll run into while getting started is working out where the option is that you’re looking for.

Let’s say that in preparation fro an upcoming all-hands meeting you’re trying to check, and maybe change, the maximum meeting size permitted. As a first step, you can try and find all the relevant cmdlets using Get-Command:

PS > Get-Command *conferencing*

CommandType     Name

-----------     ----

Cmdlet          Get-CsConferencingConfiguration

Cmdlet          Get-CsConferencingPolicy

Cmdlet          Get-CsDialInConferencingAccessNumber

Cmdlet          Get-CsDialInConferencingConfiguration

Cmdlet          Get-CsDialInConferencingDtmfConfiguration

Cmdlet          Get-CsDialInConferencingLanguageList

Cmdlet          Grant-CsConferencingPolicy

Cmdlet          New-CsConferencingConfiguration

Cmdlet          New-CsConferencingPolicy

Cmdlet          New-CsDialInConferencingAccessNumber

Cmdlet          New-CsDialInConferencingConfiguration

Cmdlet          New-CsDialInConferencingDtmfConfiguration

Cmdlet          Remove-CsConferencingConfiguration

Cmdlet          Remove-CsConferencingPolicy

Cmdlet          Remove-CsDialInConferencingAccessNumber

Cmdlet          Remove-CsDialInConferencingConfiguration

Cmdlet          Remove-CsDialInConferencingDtmfConfiguration

Cmdlet          Set-CsConferencingConfiguration

Cmdlet          Set-CsConferencingPolicy

Cmdlet          Set-CsDialInConferencingAccessNumber

Cmdlet          Set-CsDialInConferencingConfiguration

Cmdlet          Set-CsDialInConferencingDtmfConfiguration

Cmdlet          Test-CsDialInConferencing

But if it’s not obvious which command you want, this little 1-line script may help:

PS > $params = Get-Command -CommandType Cmdlet *-Cs* | % { $n = $_.Name ; $_.Parameters.Values | % { Add-Member -in $_ noteproperty CmdletName $n; $_ } }

This can be read as follows:

Get-command -CommandType Cmdlet *-Cs*   | # get all the communications server cmdlets, and pipe them into...

% { $n = $_.Name ; $_.Parameters.Values | # for each cmdlet, remember its name, then get all the parameters it takes, and pipe them into...

% { Add-Member -in $_ noteproperty CmdletName $n; $_ } # for each parameter, add the name of the cmdlet it comes from to the parameter object and output it

}

After this, the $params variable contains a list of all the parameters that all of our cmdlets accept. We can use this to search for what we want:

PS > $params | where { $_.Name -like "*meeting*" } | select Name,CmdletName

Name                                       CmdletName

----                                       ----------

DisableMeetingSubjectAndLocation           New-CsClientPolicy

AllowUserToScheduleMeetingsWithAppSharing  New-CsConferencingPolicy

AllowAnonymousParticipantsInMeetings       New-CsConferencingPolicy

AllowExternalUsersToRecordMeeting          New-CsConferencingPolicy

MaxMeetingSize                             New-CsConferencingPolicy

MaxScheduledMeetingsPerOrganizer           New-CsUserServicesConfiguration

DisableMeetingSubjectAndLocation           Set-CsClientPolicy

MeetingPsomPort                            Set-CsConferenceServer

AllowUserToScheduleMeetingsWithAppSharing  Set-CsConferencingPolicy

AllowAnonymousParticipantsInMeetings       Set-CsConferencingPolicy

AllowExternalUsersToRecordMeeting          Set-CsConferencingPolicy

MaxMeetingSize                             Set-CsConferencingPolicy

MaxScheduledMeetingsPerOrganizer           Set-CsUserServicesConfiguration

You can read that as “get all the parameters, select the ones with ‘meeting’ somewhere in their name, and print out the parameter name and cmdlet name.”

From that, it looks like we need to run:

PS > Set-CsConferencingPolicy -MaxMeetingSize 500

You can also use this to find other interesting tidbits, like this:

PS > $standardparams = "WhatIf", "Verbose", "Debug", "Confirm", "Force", "ErrorAction", "WarningAction", "ErrorVariable", "WarningVariable", "OutBuffer", "OutVariable", "Instance", "Identity"

PS > $params | where { $_.CmdletName -like "Set-*" -and $standardparams -notcontains $_.Name } | measure

Count    : 792

Average  :

Sum      :

Maximum  :

Minimum  :

Property :

You can read this as “find each parameter to a Set- cmdlet which is not a ‘standard’ PowerShell parameter, and count them.”

Which indicates that at the time of writing, we have approximately 792 configurable properties in the system.

(By the way, there’s nothing specific to Lync Server here, apart from looking for *-Cs* – this will work for any set of cmdlets)

Enjoy!