Haiku #97

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.

Note. What's that? You say that sitting around doing nothing shouldn't be called non-kinetic military action? You say instead that it should be called "writing for the Lync Server PowerShell blog?" Ha-ha. Very funny. Don't you people have work to do?

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.

Note. Interesting idea: maybe these articles would be better if the haikus did write themselves. We'll have to think about that.

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.

Note. What exactly do we mean when we say we have a PowerShell noun that performs both kinetic action and non-kinetic action? Well, to be perfectly honest, we're not all that sure ourselves. Our advice? Just keep reading, and hopefully everything will sort itself out by the end of the article.

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.

Note. OK, technically we don't know what kinetic is. But that was just an expression, so it doesn't matter.

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"

Note. We also tacked on the Report parameter to save the results of the test to a specified file. If Test-CsTopology has a weakness, it's this: it doesn't always give you a lot of onscreen output, even if you include the Verbose parameter. But that's all right: you'll find a ton of good information in the HTML file that it generates.

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"}

Note. You might have noticed that the first thing we did in our foreach loop was run this command:

$i++

What that does is take the variable $i and increment it by 1; in turn, that lets us give each of our reports a unique name. In this case, that's ConferencingServer_ followed by the value of $i. In other words:

ConferencingServer_1.htm

ConferencingServer_2.htm

ConferencingServer_3.htm

Etc.

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?