Read label before

Using: the CS AD

Domain cmdlets.

Last night the author of today's haiku faced a crisis: he turned on the TV, and couldn't find a basketball game to save his soul! (Yes, there was an NBA game on, but he wanted to watch real basketball.) Faced with the prospect of having to do something other than watch TV (fix those bookshelves he's been meaning to fix for over a year now, or maybe have a nice, thoughtful chat with the missus) he tried (and failed) to find something worth watching on his 500 channels of cable TV that costs him over $100 a month.

Now, back in the old days, that wouldn't have been a problem: if he couldn't find a sporting event worth watching he'd simply turn on the History Channel. But that was back in the days when the History Channel actually had something to do with history. Today – well, here are some of the shows regularly broadcast on the "History" Channel:

·         American Pickers

·         Ax Men

·         Extreme Marksmen

·         Ice Road Truckers

·         More Extreme Marksmen (!)

·         Pawn Stars

·         Sharpshooters (who apparently aren't also extreme marksmen)

·         Swamp People

·         Top Shot (for people who aren't sharpshooters or extreme marksmen)

·         UFO Hunters

All of these shows are so-called "reality shows," named because they depict real people doing real things (like Swamp People, which is all about people hunting alligators in the swamps of Louisiana). The author of today's haiku is, in general, not a big fan of reality shows, but considering the fact that nearly everything on TV is a reality show (go check out the nighttime schedule for the Food Network if you need proof of that) somebody must like them. And that got him to thinking: maybe there's a way to turn the Lync Server PowerShell blog into a reality show.

Now, you might not think that the Lync Server PowerShell blog would be interesting enough to be the setting for a reality show. (Unlike, say, Pawn Stars, which is about a family that runs a pawn shop.) But, believe it or not, a day at the Lync Server PowerShell blog is a day filled with excitement and intrigue. For example, just last week someone emailed us about a script that didn't work; it turned out that, in copying the script to the blog, one of the a's in the keyword param got deleted.

So what did we do about the missing a? Well, we went to the page containing the broken script, and we changed the incorrect word pram to the correct word param.

True story.

Anyway, the author of today's haiku will keep you posted on his efforts to turn the Lync Server PowerShell blog into a reality show. (And yes, now that you mention it, his managers would be happy if he'd first try to turn the Lync Server PowerShell blog into something resembling a real Lync Server PowerShell blog.) In the meantime, we need to talk about the subject of today's haiku: the CsAdDomain cmdlets (Disable-CsAdDomain, Enable-CsAdDomain, and Get-CsAdDomain).

Not that there's really all that much to talk about. The CsAdDomain cmdlets are kind of like the first aid kit that you're supposed to have in the trunk of your car: it's great to have them available, just in case, but all things considered, you're probably better off if you never have to use them. And, for most people, you probably never will have to use them; instead, those cmdlets are typically used only by the Lync Server installation program and, if all goes well with setup, you'll probably never need to run any of the CsAdDomain cmdlets.

Of the three, Get-CsAdDomain is the cmdlet you're most likely to run. As you probably know, before you can install Lync Server you need to prepare your Active Directory domain (hence the Domain Prep stage of Lync Server deployment). What does it mean to "prepare your Active Directory domain?" Well, for the most part, it means extending the Active Directory schema to allow for the addition of attributes specific to Lync Server, as well as assigning the required Access Control Entries to the universal groups used for managing and operating Lync Server. Get-CsAdDomain is designed to tell you if all these preparations are in place. To run the command against your local domain just do this:

Get-CsAdDomain

And to run the command against another domain in your forest just include the Domain parameter followed by the fully qualified domain name of that domain:

Get-CsAdDomain –Domain litwareinc.com

Get-CsAdDomain will return the value LC_DOMAINSETTINGS_STATE_READY if the domain is ready for Lync Server, and the value LC_DOMAINSETTINGS_STATE_NOT_READY if it's not ready.

OK, now what about Enable-CsAdDomain? Well, again, typically you won't need to ever run Enable-CsAdDomain; Setup will do that for you. However, suppose you run Get-CsAdDomain and you get back the value LC_DOMAINSETTINGS_STATE_NOT_READY. If you want to, you can try to prep the domain by running Enable-CsAdDomain:

Enable-CsAdDomain

Or, to prep a domain other than your local domain:

Enable-CsAdDomain –Domain litwareinc.com

Incidentally, Enable-CsAdDomain is harmless: if your domain is already fully-prepared and you run Enable-CsAdDomain anyway, well, nothing bad is going to happen. And, many months ago, we even did this: we intentionally went in and messed up some of Access Control Entries created by Lync Server's setup program, then ran Enable-CsAdDomain to see if it would repair the damage. And guess what? It did!

Now, do we recommend that you go mucking around with Active Directory and then see if Enable-CsAdDomain can fix the problem? Uh, no, not exactly. In addition, we also don't recommend that you run the Disable-CsAdDomain cmdlet. Disable-CsAdDomain is designed to roll back all the changes that Enable-CsAdDomain makes to Active Directory. Does it really do that? Well, we can't say that with 100% certainty. However, we can say this: the one time we ran Disable-CsAdDomain it did something to Active Directory, and we had to reinstall Lync Server.

Before you begin to panic, don't worry: there are a few safeguards built into Disable-CsAdDomain that help protect you from inadvertently wiping out Lync Server. By default, Disable-CsAdDomain will fail if the cmdlet detects a Front End, Conferencing, or Web services server still running in the domain you're trying to disable. You won't get any particularly meaningful error message, but the command will fail.

We should also note that running Disable-CsAdDomain is not the way to uninstall Lync Server (if, heaven forbid, you ever need to uninstall Lync Server). It's possible to force Disable-CsAdDomain to run even if the cmdlet does detect a Front End, Conferencing, or Web services server still running in the domain. However, that's just going to "unprep" your domain; it's not going to uninstall Lync Server. But don't worry: some of our colleagues are currently working on the definitive guide to uninstalling Lync Server, a guide that will likely hit the shelves sometime in the next few weeks.

That's all we have time for today; we need to get back to work on our reality show. If you're interested in starring in that show (The Kissing Lync? The Hissing Lync?) just let us know. Admittedly, right now our show is about nothing at all. Fortunately for us, however, having a purpose or a reason doesn't seem to be a requirement for reality TV.

Once again we’re not convinced that anybody actually needs a hint: even though this week’s challenge was a bit trickier than last week’s, everyone who has submitted an answer thus far seems to be doing OK with it. On the other hand, today is Hint Day, and we’d hate to spoil all the fun for the people who’ve gathered together for their big Hint Day celebration. So here you go, guys; enjoy:

Come one. Or, come all.

Challenge Home

I now pronounce you

Voice policy and voice route.

Thank you, phone usage.

If you glance at the sports page these days, you'll see that former baseball superstar Barry Bonds is currently on trial for allegedly lying to the government as part of a steroids investigation; another ex-baseball star, Roger Clemmons, will go on trial this summer, and Tour de France legend Lance Armstrong might not be far behind. The NFL has locked out its players and there's a 50-50 chance that the 2011 season will be cancelled. The University of Tennessee recently fired its men's basketball coach for lying to NCAA investigators, and the CEO of the Fiesta Bowl has been fired for collecting $2 million for … expenses ….

But as impressive as all those news stories are, guess what the absolute biggest scandal in the sports world is. You got it: former NBA player Jalen Rose was recently quoted as saying that, when he was being recruited by colleges back in 1991, he didn't want to go to Duke University because – gasp! – he didn't like Duke University! Needless to say, Duke supporters were shocked – shocked – to hear that, 20 years ago, someone didn’t like them.

Imagine that.

Rose, of course, has been forced to at least partially backpedal from his statements, even though he never said that he didn't like Duke University now, just that he didn't like Duke University 20 years. Based on the fallout caused by Rose's statements, the author of today's haiku has decided to be proactive and apologize for the following statements that he made about Duke University 20 years ago:

·         In a 1990 article in the New England Journal of Medicine, he wrote that the death toll from the Black Death that swept across Europe in the 14^th century was due, in part, to people saying that they would rather die from the plague than go to Duke University. He has since learned that Duke University was not even founded until 1838 (how was he supposed to know that?), and apologizes for the mistake.

·         In 1991, while accepting the Academy Award for Best Supporting Actor, he mentioned offhandedly that Attila the Hun, Ivan the Terrible, and Jack the Ripper all graduated from Duke University. As it turns out, he was incorrect: Jack the Ripper did not graduate from Duke University. (However, former President Richard M. Nixon did graduate from the Law School in 1937.)

·         In 1992, after losing the election for the President of Sierra Leone, he stated that, if Duke University offered him a basketball scholarship, he would decline that offer. That was not true. (After all, enrolling at Duke University on a basketball scholarship would probably be the fastest and most effective way for him to ruin both the academic and the athletic reputation of the school.) If Duke is still prepared to offer him a basketball scholarship he is prepared to accept.

To make a long story short, the author of today's haiku regrets anything and everything he has ever said about Duke University. (For that matter, he pretty much regrets anything and everything he has ever said, period.) After visiting the Duke University Web site, he now realizes that the school has world-class faculty helping to expand the frontiers of knowledge, and that the university has a strong commitment to applying knowledge in service to society, both near its North Carolina campus and around the world.

He also learned that the motto of Duke University is Eruditio et Religio, which means "Knowledge and Religion."

As you might expect of any place that has Latin motto, Duke University has earned world renown for its academic program and for the achievements of its graduates; for example, William Styron won a Pulitzer Prize for the novel The Confessions of Nat Turner, and Robert Richardson won the Nobel Prize in Physics for his work in superfluidity. As impressive as all those achievements are, however, the author of today's haiku did manage to find one breakthrough discovery that did not take place at Duke University: the creation of the CsPstnUsage cmdlets (Get-CsPstnUsage and Set-CsPstnUsage).

So what are the CsPstnUsage cmdlets and, for that matter, what the heck are PSTN usages? Wow; you would have to ask that question, wouldn't you? Well, let's see if we can explain this.

A PSTN usage is really nothing more than a string value that links a voice policy and a voice route. If a voice route and a voice policy share at least one PSTN usage, then that route and that policy are linked. What happens if a voice policy doesn't share a PSTN usage with a voice route? That's easy: in that case, phone calls made by any user who has been assigned that voice policy will not be able to traverse that route.

It actually kind of makes sense, although we've never fully understood why you need a separate object – a PSTN usage – to link a route and a policy as opposed to, say, simply listing the policy as a route property and vice-versa. However, we don't have anywhere near enough time today to discuss all the things that we don't fully understand, so we'll simply accept PSTN usages for what they are and get on with our lives.

In Lync Server, all your PSTN usages are stored in a single global collection. How do you know what usages are available to you? That's another easy one; all you have to do is call the Get-CsPstnUsage cmdlet:

Get-CsPstnUsage | Select-Object –ExpandProperty Usage

That was easy. Now here's a tougher one: what do you do if you need to create a brand-new usage?

New usages are created (or, to look at it another way, new usages are added to the global collection) by using the Set-CsPstnUsage cmdlet. For example, this command adds the usage International (remember, a usage is just a string value) to the global collection:

Set-CsPstnUsage -Identity global -Usage @{Add="International"}

And this command removes the usage International from the global collection:

Set-CsPstnUsage -Identity global -Usage @{Remove="International"}

That's really all there is to it.

After a usage has been added to the global collection, that value can then be used in a voice policy and/or a voice route. We won't bother to go into a detailed explanation of voice policies and voice routes today; that's a bit beyond the scope of the daily haiku. However, this command adds the PSTN usage International to a voice policy:

Set-CsVoicePolicy –Identity "RedmondVoicePolicy" -PstnUsages @{Add="International"}

If it turns out that there isn't a PSTN usage named International then the preceding command will generate the following error message:

Set-CsVoicePolicy : Cannot find PSTN usage "International" in the Central Management Store.

Which, of course, explains why we needed to add this usage to the global collection in the first place: if you don't do that, the usage can't be added to a voice policy or voice route.

Note that it's possible to create a voice policy that doesn't have any PSTN usages associated with it. We should emphasize, however, that while this is possible, it's not very practical: if there aren't any PSTN usages associated with a voice policy then users assigned that policy won't be able to make outbound telephone calls to the PSTN network.

And there you have it: the truth behind PSTN usages. We hope you enjoyed today's haiku and, again, our apologies if we have ever offended anyone from Duke University.

Oh, and if you happen to work with someone who graduated from Duke, could you please read that last sentence to them, slowly? Thanks!

Gone phishin'? Not if

You used the CSIM

Filter cmdlets.

We don't mean to alarm anyone, but the Internet isn't always a friendly place. We know, we know, but trust us: it's true. Most of us tend to think of the Internet as a happy place, a place where we all going skipping merrily through the flowers, holding hands, singing songs, and wearing all of our clothes. But, hard as this might be to believe, the Internet does have a dark side. For example, every morning the author of today's haiku opens his email and sees invitations to Web sites that promise to verify his bank account password; connect him to a beautiful girl who has admired him from afar and is dying to meet him; and to help him BECOME THE MAN SHE'S ALWAYS DREAMED OF!!!

Which, as near as he can tell, would make him a young Cary Grant.

Now, it's always possible that some of these sites are semi-legitimate, at least in the sense that they won't actually do you any harm. (Unless the sugar pills they want to sell you end up turning you into an old Ulysses S. Grant rather than a young Cary Grant.) On the other hand, many of these sites are designed specifically to do you harm: many of them are "phishing" sites designed to trick you into giving away such things as your user name, your password, or your credit card number. Likewise, there are other sites out there that won't steal anything from you, but might not be the sort of place you want your users lurking in during work hours.

If you know what we mean.

Of course, by itself Microsoft Lync Server 2010 can't prevent your users from going places they really shouldn't go. However, by using the CsImFilterConfiguration cmdlets (Get-CsImFilterConfiguration, New-CsImFilterConfiguration, Remove-CsImFilterConfiguration, and Set-CsImFilterConfiguration) you can at least make it a little harder for users to share hyperlinks (to any web site, legitimate or not) via instant messaging. If you enable IM filtering (and, by default, IM filtering is not enabled), then any time you send an instant message Lync Server scans that message for the presence of a hyperlink.

Let's suppose that Lync Server does find a hyperlink in an instant message; what then? Well, as an administrator, you have three options available to you:

·         Block the message from being sent altogether. If you choose this option, messages containing hyperlinks will be stopped dead in their tracks and won't be sent. Instead, the user trying to send the hyperlink will see an error message similar to this:

This message was not delivered to Ken Myer because the message contents are restricted by policy. For more information, contact your system administrator.

To block the use of hyperlinks altogether, use Set-CsImFilterConfiguration (or New-CsImFilterConfiguration) to enable IM filtering and to set the Action property to Block. In other words:

Set-CsImFilterConfiguration –Identity global –Enabled $True –Action Block

·         Allow the message to be sent, but issue a warning that the message contains hyperlinks. If you do this, two things will happen. First, the "toast" that appears when a user is first notified about the instant message will appear with a warning; this warning is something you compose. Second, any hyperlinks in the message itself will also be prefaced by that warning. In other words, the message text might look like this:

Warning: Be sure you are following company policy before clicking a hyperlink in this message:

Hey, Ken. Go to http://blogs.technet.com/b/csps/ to BECOME THE MAN SHE'S ALWAYS DREAMED OF!!!

How do you configure Lync Server to do this? That's easy: set the Action property Warn, and configure a value for the WarnMessage property:

Set-CsImFilterConfiguration –Identity global –Enabled $True –Action Warn –WarnMessage "Warning: Be sure you are following company policy before clicking a hyperlink in this message"

·         Allow the message to be sent, but disable the hyperlink so that a user can't just click the link and be transported to that site. If you go this route, hyperlinks will be prefaced by an underscore, making them unclickable:

Hey, Ken. Go to _http://blogs.technet.com/b/csps/ to BECOME THE MAN SHE'S ALWAYS DREAMED OF!!!

Obviously a user could copy the link portion of the text and then paste that link in to Internet Explorer, but at least that requires them to do a little bit of work and (keep your fingers crossed here) a little bit of thinking before they visit the site in question.

To configure this behavior, set the Action property to Allow. (And yes, that's kind of misleading, to say the least, seeing as how we aren't really allowing hyperlinks. But, for better or worse, that's what we're stuck with.) For example:

Set-CsImFilterConfiguration –Identity global –Enabled $True –Action Allow

Incidentally, you can also set an AllowMessage just like we did a WarningMessage. But that sounded like too much work for one haiku.

IM filtering can be configured at the site scope as well as the global scope; that gives you the ability to, for example, allow some things in the Dublin site that you don't allow in the Redmond site. As we noted earlier, you can use the Get-CsImFilterConfiguration cmdlet to review the prefixes that Lync Server tags as hyperlink prefixes. If you're wondering "Can we modify that list of prefixes?" the answer this: you bet you can. Without going into a lot of detail, here's a command that adds a prefix (urn:) to the list:

Set-CsImFilterConfiguration -Identity global -Prefixes @{add="urn:"}

And here's a command that removes the prefix urn: from the list:

Set-CsImFilterConfiguration -Identity global -Prefixes @{replace="urn:"}

Pretty simple, if we do say so ourselves.

We should probably point out that, in testing the commands used in today's haiku, we occasionally ran into some odd situations. Most of the time things worked as expected. However, on a couple of occasions we would change the Action property to Allow then start a new instant messaging session. We would include a hyperlink in the first instant message in a session; that hyperlink would be clickable, but any other messages in that session would correctly put the underscore in front of the hyperlink:

_http://blogs.technet.com/b/csps/

Why would that happen? We don't know: it didn't always happen and, to be honest, we don't expect it will happen to you. (Our test machines, which technically don't even meet the hardware requirements for running Lync Server in the first place, often do … interesting … things.) Nevertheless, we thought we should mention it, just in case. If any of you implement IM filtering and run into similar weirdness, please let us know and we'll dig into it a little further.

In the meantime we just got the following email:

Money back guarantee? Nothing to lose and lots to gain? We'd be crazy not to visit that site!

In other words, we've got things to do this morning. See you tomorrow!

The bare essentials:

Food, water, clothing, and the

LisPort cmdlets.

Recently, the author of today's haiku has been reading the book Collapse by Jared Diamond, a book that tries to explain why civilizations that were once vibrant and thriving – like the Anasazi Indians in the American southwest, or the Mayan culture in Mexico and Central American – ended up failing. As you might expect, there are typically a number of factors that end up causing a society to fail; for example, on Easter Island the inhabitants ended up cutting down every last tree on the island (not good when you rely on wood for heating and cooking); eroded all their topsoil and farmland (in part because they cut down every last tree on the island); and devoted more of their time and resources to erecting those famous statues than they did trying to stay alive. We admit that, considering the state of the modern world, we probably shouldn't be the ones to point fingers. Nevertheless, come on, guys: giant statues instead of food? Really?

One factor that Diamond does not cite, however, is this: despite all the research and all the study, archeologists have yet to find evidence that indicates that any of these failed civilizations used the CsLisPort cmdlets (Get-CsLisPort, Remove-CsListPort, and Set-CsLisPort). In fact, as near as we can tell, all the civilizations in the world that have ever failed had one thing in common: none of them used the CsLisPort cmdlets.

And yes, that includes the Norse explorers who tried to settle in Newfoundland, but then were forced to return to Greenland.

That's the bad news, particularly if you’re an ex-Viking or former ruler of Easter Island. The good news, however, is that modern-day civilization is in absolutely no danger of ever collapsing. Why not? Because we do have access to the CsLisPort cmdlets.

So what exactly are the CsLisPort cmdlets, and why are they so useful? Well, the CsLisPort cmdlets are used as part of the Enhanced 9-1-1 (E9-1-1) location service; E9-1-1 provides a way for users to make an emergency call using a Lync Server Phone Edition phone and, more importantly, for emergency responders to be able to pinpoint the physical location from which that phone call came. (That's important, because Phone Edition phones aren't necessarily tied to a specific location, like a good old-fashioned landline is.)

In order for the E9-1-1 system to work, administrators need to configure a location map (called a wiremap) that determines a caller’s physical location. The CsLisPort cmdlets allow these administrators to map the physical location of the port that the client is connected to. In turn, and in conjunction with the rest of the wiremap, that helps identify where the emergency call is coming from.

The CsListPort cmdlets are pretty easy to use, although there is one important thing to note right away: like most of the E9-1-1 cmdlets, there is no New-CsListPort cmdlet. Instead, you use Get-CsLisPort to retrieve information about ports configured for the E9-1-1 service; you use the Remove-CsListPort cmdlet to remove ports from your E9-1-1 wiremap; and you use the Set-CsLisPort cmdlet both to create new ports and to modify existing ports.

Oh, and there's another important thing to note, too: port locations have a more complicated identity than most Lync Server components. For one thing, port locations don't even have an Identity property; there's no single name or label that can be used to uniquely identify a port. Instead, ports are identified by a unique combination of the following fields:

·         ChassisID. This is typically the MAC address of the port switch, although the ChassisID can also be the IP address of the switch.

·         PortID. A string value that specifies the port ID.

·         PortSubTypeID. An integer value that specifies how the PortID was derived. By default, the PortSubTypeID is set to 7, which means "locally assigned;" in turn, that means that an algorithm was used to generate the PortID for the port. Alternatively, the PortSubTypeID might be set to 1 (InterfaceAlias), which indicates that the port ID value is a network alias. (A network alias is used to allow multiple IP addresses to point to a single port.) Or, the PortSubTypeID can be set to 5 (InterfaceName), which indicates that the PortId represents the name of the port.

As we noted, the combination of those three properties determines the Identity of a port. If you want to create a new port, just be sure that the combination of those three properties is unique. For example, this command creates a new port with the ChassisID of 99-99-99-99-99-99, a PortId of 4200, and a PortIdSubType of 1:

Set-CsLisPort -ChassisID 99-99-99-99-99-99 -PortID 4200 -PortIdSubType 1 -Location "30/1000" -HouseNumber 1234 -PreDirectional NE -StreetName First -StreetSuffix Avenue -City Redmond -State WA -Country US -PostalCode 99999

If Lync Server can't find a port with that unique combination of ChassisID, PortID, and PortIdSubType then it will create a brand-new port. And what if it does find a port with that identity? In that case, it will modify the existing properties of that port. For example, maybe the port used to be located at 6789 NE First Avenue in Redmond, WA. Based on the preceding command, that location will now be changed to 1234 NE First Avenue in Redmond, WA.

And yes, it can be a little overwhelming, at least at first. But you'll catch on in no time.

Another thing you might want to keep in mind here is that the Get-CsLisPort cmdlet has no parameters at all. (None.) So then how do you retrieve information about a specific port? That's actually easy; you just need to retrieve information about all the ports and then pipe that information to the Where-Object cmdlet. For example, here's a command that retrieves one (and only one) port:

Get-CsLisPort | Where-Object {$_.ChassisID -eq "99-99-99-99-99-99" –and $_.PortId –eq "4200" –and $_.PortIdSubType –eq 1}

And here's a command that returns any port that has a ChassisID equal to 99-99-99-99-99-99 (and yes, most of the time you'll only have one port with that ChassisId):

Get-CsLisPort |Where-Object {$_.ChassisID -eq "99-99-99-99-99-99"}

And there you have it: the CsLisPort cmdlets. We're not saying that you have to use the CsLisPort cmdlets; that's up to you. All we are saying is this: if you don't use the CsLisPort cmdlets your E9-1-1 system isn't going to work as well as it could. Is that why civilization on Easter Island collapsed, because the Easter Islanders tried to make emergency calls for help only to discover that their port locations had never been configured and thus the emergency responders had no idea where the 9-1-1 calls were coming from? As far as we know, no researcher has ever stated that this wasn't why the civilization on Easter Island collapsed.

Something to think about.