Elves are useless. Try

The UserReplicator

Cmdlets instead.

You'll have to forgive the author of today's haiku for being a bit excited and distracted this morning: after all, later on today he gets to attend his first ELF meeting!

Now, before you get too excited and distracted, the author of today's haiku should clarify that this meeting has nothing to do with those kind of elves, the kind who sneak into your house late at night and build shoes for you, or the kind that help Santa in his workshop. (Or at least he doesn't think those are the kind of elves we're talking about; he probably should pay more attention to the official emails that get sent out around here.)

And, sadly, these are definitely not the kind of elves that sneak into your office late at night and write daily Lync Server PowerShell haikus for you. (The author of today's haiku knows: he checks his desk every morning when he comes in and, so far anyway, nothing.) Instead, ELF is an acronym for Exchange, Lync, and Forefront, the three documentation teams that will be getting together this morning to do ... well, whatever it is that documentation teams do when they get together. Isn't Microsoft taking a huge risk by having all three of those teams gather in the same place at the same time; after all, what if extraterrestrials chose that very moment to aim their new Destructo-Ray at the conference center where they're meeting? For some reason, Microsoft seems willing to take that risk. Hmmm ....

At any rate, it should be an interesting meeting, and the author of today's haiku is really looking forward to it.

Of course, because these aren't the kind of elves who write daily haikus for you, that means the author of today's haiku actually has to author today's haiku. (And yes, at today's meeting he just might raise the issue of how unfair that is.) And so, with no further ado, here's the subject for today's haiku: the CsUserReplicatorConfiguration cmdlets.

Please hold your applause until the end.

As everyone knows, there are good elves and there are bad elves. The historian Snorri Snurluson summarized the difference between the two types by saying this:

"Sá er einn staðr þar, er kallaðr er Álfheimr. Þar byggvir fólk þat, er Ljósálfar heita, en Dökkálfar búa niðri í jörðu, ok eru þeir ólíkir þeim sýnum ok miklu ólíkari reyndum. Ljósálfar eru fegri en sól sýnum, en Dökkálfar eru svartari en bik."

So does that mean that there are good CsUserReplicatorConfiguration cmdlets and bad CsUserReplicatorConfiguration cmdlets? Not exactly. However, there are CsUserReplicatorConfiguration cmdlets that will work with the on-premises version of Microsoft Lync Server, and CsUserReplicatorConfiguration cmdlets that will not work with the on-premises version of Microsoft Lync Server. And the difference between those cmdlets will be the focus of our discussion today.

Well, in a minute. First, we should probably explain what the CsUserReplicatorConfiguration cmdlets are even for. As you know, Lync Server 2010 depends on Active Directory as the ultimate source for user information. For example, when a new Active Directory user account is created, you must supply basic information about the user account (such as the Active Directory display name). However, when a user is enabled for Lync Server you do not need to specify a new display name for that user. Why not? Because Lync Server uses the display name already stored in Active Directory. You need to supply some Lync Server-specific information, but that's about it.

What's wrong with that? Nothing; you just have to make sure that Lync Server and Active Directory remain in synch. To do that, Lync Server must periodically check in with Active Directory, retrieve the latest user account updates, and then modify its user database accordingly. This synchronization between Active Directory and Lync Server is carried out by the User Replicator.

When you install Lync Server, a global set of User Replicator configuration settings is created for you; these settings are used to manage the User Replicator on an organization-wide basis. Management of the User Replicator primarily consists of identifying the domains that Lync Server needs to synch with, as well as indicating how often the User Replicator checks Active Directory for user account updates. By default, the User Replicator discovers and synchs with all available domains. However, by using the ADDomainNamingContextList property you can restrict synchronization to a specific set of domains: the domains that appear in the ADDomainNamingContextList property.

Good point: that passage from Snorri Snurluson was easier to understand than the preceding paragraph, wasn't it? OK, let's put it this way. By default, you don't have to do anything to the User Replicator: it automatically seeks out and synchronizes with every domain it can find. Most of the time that's good. However, suppose you're working in a multiple domain organization and there are some domains that you'd prefer not be synched with the User Replicator. In that case, you can use a command like this one to specify that the User replicator should only synch with the fabrikam.com domain:

Set-CsUserReplicatorConfiguration -Identity global -ADDomainNamingContextList @{Add="dc=fabrikam,dc=com"}

You say there are actually two domains you need to synch with? That's fine; just list both domains in your command, separating the two by using a comma:

Set-CsUserReplicatorConfiguration -Identity global -ADDomainNamingContextList @{Add="dc=fabrikam,dc=com","dc=litwareinc,dc=com"}

And if you later decide that you don't need to synch with Fabrikam.com after all, well, then you can easily remove that domain from the list:

Set-CsUserReplicatorConfiguration -Identity global -ADDomainNamingContextList @{Remove="dc=fabrikam,dc=com"}

As you can see, it's all pretty easy. And no elves required!

Oh, and if you decide to revert to the default behavior and synch with all the available domains, just set ADDomainNamingContextList to a null value. You know, like this:

Set-CsUserReplicatorConfiguration -Identity global -ADDomainNamingContextList $Null

That's all for the Set-CsUserReplicatorConfiguration cmdlet. (There's also a Get-CsUserReplicatorConfiguration cmdlet that lets you review your current settings.) Now, what about the other two cmdlets in this cmdlet family, New-CsUserReplicatorConfiguration and Remove-CsUserReplicatorConfiguration? Well, those two cmdlets are intended for use with Lync Online, and aren't something you need to concern yourself with right now. (In the future, yes. For now, no.) As you might expect, New-CsUserReplicatorConfiguration will allow you to create additional sets of user replicator settings, with these settings scoped at the service scope. In turn, Remove-CsUserReplicatorConfiguration will let you remove those custom settings. But that's how things will work in the future, as soon as our team of elves finalizes Lync Online.

And there you have it: the CsUserReplicatorConfiguration cmdlets. In closing, we'd like to leave you with one final comment about elves:

"In Denmark and Sweden, the elves appear as beings distinct from the vetter, even though the border between them is diffuse."

We couldn't have said it better ourselves.

The topology

Cmdlets: When your actions

Need to be active.

The author of today's Lync Server PowerShell haiku learned something new yesterday: he learned that when the military takes up arms these days, they don't go into battle or fight a war or do anything distasteful like that. Instead, they engage in "kinetic military action." And when they aren’t actually taking up arms, but just offering tacit support for something? That's "non-kinetic military action." For some reason, the author of today's haiku found that interesting.

Actually, what's really interesting is the fact that the term kinetic military action has apparently been around for years; the author of today's haiku simply was oblivious to it. Although, in his defense, he has been busy: these Lync Server PowerShell haikus don't write themselves you know.

At any rate, now that he learned a couple of new phrases, the author of today's haiku decided to put this new knowledge to the test: he set out to find a Lync Server PowerShell noun that performed both kinetic action and non-kinetic action. And, believe it or not, he found the very noun he was looking for: CsTopology.

Let's talk first about kinetic action, an action that actually does something. With CsTopology, there are three cmdlets that actually perform actions, including Get-CsTopology and Enable-CsTopology. The Get-CsTopology cmdlet returns information about your Lync Server topology. (Imagine that!) Do you want information about your Lync Server topology? Then just call the cmdlet without any parameter:

Get-CsTopology

In turn, you'll get back something that looks like this:

Identity             : Global

InternalDomains      : {litwareinc.com, fabrikam.com, contoso.com}

Clusters             : {Redmond:1, Redmond:2, Redmond:3, Redmond:4, Redm...}

Machines             : {Redmond:1-1, Redmond:2-1, Redmond:3-1, Redmond:4...}

MachinesByMacAddress : {}

Services             : {Redmond-CentralMgmt-1, Redmond-CentralMgmtStore-1...}

Sites                : {Redmond, Dublin}

SqlInstances         : {Redmond:3\archinst, Redmond:3\rtc}

Signature            : 435df8f0-1381-4410-9f82-258350a8dc5f

If you'd like detailed information about any of these items just pipe the returned data to the Select-Object cmdlet, and use the ExpandProperty parameter to retrieve that detailed information:

Get-CsTopology | Select-Object –ExpandProperty Services

In turn, you'll get back all sorts of service-related information:

ServiceId         : Redmond-ProvisionStore-1

ServiceVersion    : 5

Backup            :

RoleID            : ProvisionStore:1   

Site              : Redmond:Redmond

InstalledOn       : Microsoft.Rtc.Management.Deploy.Internal.SqlInstance

DependentServices : {}

NetPorts          : {}

Topology          : Microsoft.Rtc.Management.Deploy.Internal.DefaultTopology

If that's not kinetic, well, we don't know what it is.

If you'd like to see your entire topology in XML format, just use a command like this one (note that we piped the output to more so you could see the XML one screen at a time):

Get-CsTopology –AsXML | more

Even better, use this command to actually save that XML:

Get-CsTopology –AsXML | Out-File C:\Topology\CurrentTopology.xml

If you want to know everything there is to know about how you've deployed Lync Server, well, this is definitely a good place to start.

As it turns out, Enable-CsTopology is also a kinetic cmdlet. When you make changes to your Lync Server topology those changes don't take effect until the new topology has been enabled. Typically you make your changes in Topology Builder and then use that same tool to enable the new topology. However, there are times when you can make a change at the command prompt and then use the Enable-CsTopology cmdlet to enable those changes. One instance that comes to mind is this: creating a new Kerberos account. For example, here are a set of commands that create a new Kerberos account, assign that account to a site, then use the Enable-CsTopology cmdlet to ensure that Lync Server actually begins to use the new account:

New-CsKerberosAccount -UserAccount "litwareinc\kerberostest" -ContainerDN "cn=Computers,dc=litwareinc,dc=com"

New-CsKerberosAccountAssignment -UserAccount "litwareinc\kerberostest" -Identity "site:Redmond"

Enable-CsTopology

Pretty darn kinetic, isn't it? Oh, and while we're at it, we should also mention the Test-CsTopology cmdlet, a kinetic cmdlet that checks your entire Lync Server infrastructure, verifying that the required services are running and that the appropriate permissions have been set for these services and for the universal security groups created when you install Lync Server:

Test-CsTopology

You can also test a particular service by tacking on the Service parameter:

Test-CsTopology –Service ConferencingServer:atl-conf-001.litwareinc.com –Report "C:\Reports\ConferencingServer.htm"

And what if you'd like to test all of your conferencing servers? Well, Test-CsTopology doesn't directly accept pipelined input. But you can achieve the same results by retrieving all your Conferencing servers and then piping that data to the ForEach-Object cmdlet:

Get-CsService –ConferencingServer | ForEach-Object {$i++; Test-CsTopology –Service $_.Identity –Report "C:\Reports\ConferencingServer_$i.htm"}

OK, now what about the non­-kinetic cmdlet? Well, as it turns out we have one: Publish-CsTopology. We're calling this a non-kinetic cmdlet because you really shouldn't use it. Originally, this was a perfectly valid way to publish a Lync Server topology. However, shortly before the product shipped they changed the XML format used by Topology Builder. There wasn't time to redo the Publish-CsTopology cmdlet, which means that Publish-CsTopology no longer works with the XML files created by Topology Builder. Because of that, you'll need to do your publishing in Topology Builder. In theory, you could use Publish-CsTopology to republish the existing topology, but we really don't know why you'd want to do that. Just use Topology Builder for publishing topologies and your life will be much easier. We promise.

That should do it for today. We'd like to tell you more, but right now we have to engage in some non-kinetic action of our own. And yes, it's a tough job, but someone has to do it, right?

Please don't boo: today

We are talking about the

User database.

This past weekend the author of today's Lync Server PowerShell haiku spent some time watching the Seattle Mariners play the Oakland Athletics.

At any rate, while watching the game he once again noticed something that has driven him crazy for years now. Picture this: the Mariners get a man on base. The next batter comes up to the plate, the opposing pitcher peers in to get the sign from the catcher, and the runner on first leads off. The pitcher looks over at the runner and then, deciding that the runner is a little too far off first base, throws the ball over to first in attempt to get the runner out. (Or, as we baseball people like to say, tries to "pick him off.") All the fans at the game (both of them) immediately begin to boo at the top of their lungs. In fact, baseball fans always boo any time a pitcher tries to pick off a runner. And that's what drives the author of today's haiku crazy: why in the world are these people booing? Is it because the pitcher is doing something illegal? Of course not: baseball rules allow you to try and pick the runner off. Is it because the pitcher is trying to get the runner out? Well, maybe. But how much fun would baseball be if the other team didn't try to get you out? Baseball fans (and especially Seattle Mariners fans) routinely boo all pickoff plays, and the author of today's haiku is mystified as to why they routinely boo all pickoff plays.

Of course, that put a little pressure on the author of today's haiku: he didn’t want to write a haiku that would result in everyone booing. (He already hears enough booing each morning as he walks down the hall towards his office.) Because of that, he decided to pick a topic that no one would dare boo: the CsUserDatabaseState cmdlets (Get-CsUserDatabaseState and Set-CsUserDatabaseState).

So how does he know that no one will boo him for writing about the CsUserDatabaseState cmdlets? Well, after all, what's there to boo? The Get-CsUserDatabaseState cmdlet lets you know whether or not your user database is online and available. (The user database, also known as the user store, maintains presence and routing information for Lync Server users.) To quickly retrieve the status of all your user databases, just run this command:

Get-CsUserDatabaseState

To check the status of all the user databases in a specified pool, just add the RegistrarPool parameter and the fully qualified domain name of that pool:

Get-CsUserDatabaseState –RegistrarPool atl-cs-001.litwareinc.com

Heck, you can even check the status of a single user database instance:

Get-CsUserDatabaseState –Identity "UserDatabase:atl-cs-002.litwareinc.com"

Not much to boo about, is there?

Likewise, the Set-CsUserDatabaseState cmdlet lets you (essentially) turn your user databases on or off. Suppose you need to take the user databases down in one of your pools. That's fine; all you have to do is run a command like this one:

Set-CsUserDatabaseState –RegistrarPool atl-cs-001.litwareinc.com –Online $False

And then what do you do when you need to bring that database back online? Why, you do this, of course:

Set-CsUserDatabaseState –RegistrarPool atl-cs-001.litwareinc.com –Online $True

In other words, set the Online parameter to $False to take a database offline, and then set the Online parameter to $True to bring the database back online.

Incidentally, Lync Server will still continue into chug along (albeit with some limited functionality) if you take the user database offline. For example, if you happen to be working in Microsoft Lync when the user database goes offline, you'll see a message similar to this:

A network or server issue is temporarily limiting features. Your Contacts list is unavailable but you can search for contacts and make calls. Call forwarding may not be working and delegates or team call group members may not be receiving your calls.

In turn, Lync might end up looking like this:

However, Lync will still work. Just like the error message noted, the user can search for contacts and send instant messages. It's just that certain features – like the Contacts list, phone call log, and Activity Feeds – are unavailable until the database is brought back online.

So see? The CsUserDatabaseState cmdlets: simple and sweet. And, best of all, they give you no reason to boo today's haiku.

Well, except for those of you who boo every day's haiku. But that's another story.

When you work on the Lync Server PowerShell blog, people tend to stop you all the time and ask the same question: is your blog truly promoting peace and harmony throughout the entire world? Needless to say, we always thought that the Lync Server PowerShell blog was promoting peace and harmony throughout the entire world, but we didn't have any proof of that. But now we do. When he submitted his answer for last week's challenge, Makovec noted that, the week before that, he wasn't completely confident in his answer. Because of that, he sent the answer to his wife and asked for her opinion. A few seconds later she replied, and she agreed with him! That's right: the first known instance of a husband and wife actually agreeing on something! Can any other Lync Server blog make the same claim?

Well, OK. But other than that, can any Lync Server blog make the same claim? We didn't think so.

Speaking of last week's challenge, that challenge also helped bring people together: in fact, everyone who submitted an answer submitted the same exact answer.

To quickly recap the story, last week we presented you with the following four cmdlet parameters (without the typo this time) and asked you which of those parameters was not like the others:

The answer (as everyone already knows) is this: New-CsExUmContact.SipAddress. Why? Because this is a mandatory parameter: if you don't include the SIP address you won't be able to create a new Exchange UM contact. The other parameters are all optional; for example, if you don't include the EnforcePhoneLock parameter you can still create a new collection of UC phone configuration settings. In that case, the EnforcePhoneLock property for this new setting will be set to the default value of True.

So how do you know which parameters are optional and which parameters are mandatory? Well, probably the easiest way is to look at the help topic for a given cmdlet. But if that seems a little humdrum, you can also run a command like this one:

Get-Command New-CsUCPhoneConfiguration | Select-Object -ExpandProperty ParameterSets | Select-Object -ExpandProperty Parameters | Select-Object

 Name, IsMandatory

Give that a try and see what happens.

And while you do that, we're going to start working on our acceptance speech for the Nobel Peace Prize. What happens if you get done before we do? That's OK; we have another challenge you can work on while we wrap up our speech.

Challenge Home