Haiku #156

  • Article

Mom says that we have

To tell everyone about

Policy profiles.

 

We thought we'd try something a little different today: today we're going to randomly select one of the many emails sent in by our devoted readers and see if we can answer the reader's question by writing a haiku; this is our way of trying to give everyone what they really want. Let's see what we have here:

 

"The Lync Server PowerShell blog is a travesty. This is by far the worst example of – "

 

Um, never mind. As it turns out, that mail was sent by a family member, and it wouldn't seem sporting (or ethical) to use something sent by a family member.

 

Note. Speaking of family members: Mom, how could you?!?

 

Let's try another one:

 

"I cannot believe that this is what Microsoft pays you to do. As far as I'm concerned – "

 

Hmmm …. Apparently Steve Ballmer isn't the soft-spoken guy we always assumed he was. OK, let's try a – whoa. Never mind about that one.

 

OK, by now it should be pretty obvious what everyone really wants: everyone really wants us to address the CsNetworkBandwidthPolicyProfile cmdlets!

 

Note. For those of you who like to keep track of that sort of thing, that's Get-CsNetworkBandwidthPolicyProfile, New-CsNetworkBandwidthPolicyProfile, Remove-CsNetworkBandwidthPolicyProfile, and Set-CsNetworkBandwidthPolicyProfile.

 

So what exactly is a network bandwidth policy profile, and why do we need cmdlets to manage these policy profiles? Good question. As you probably know by now, in Lync Server 2010 Microsoft introduced Call Admission Control, the ability to place bandwidth usage restrictions on all (or some) of your network connections. We won't go into all the whys and wherefores of Call Admission Control today; if you need that sort of background information, take a look at the article Call Admission Control in Lync Server.

 

Note. Don't worry; we didn't write that particular article. Therefore, it should be perfectly safe to take a look at.

 

What we will tell you is that bandwidth policies are used to determine the amount of bandwidth that can be used for audio and/or video transmissions. These policies let you place two different kinds of restrictions on bandwidth use: you can limit the total bandwidth allocated for all audio/video sessions, and you can limit the amount of bandwidth allocated for a single session. For example, you might decide that an individual audio session will be allowed 100 kilobits per seconds (kbps) of bandwidth use, while a grand total of 1000 kbps will be allocated for all the current audio sessions. What does that mean? Well, suppose you have 10 audio sessions going on right now, each using the allotted 100 kbps. 10 audio sessions times 100 kbps equals 1000 kbps, the total amount of bandwidth allocated for audio. Suppose that user no. 11 now tries to make an audio call. Is that call going to go through? Nope; there's no bandwidth available for audio sessions. User no. 11 is going to have to wait for an existing session to end before he or she can place the call.

 

Make sense? We thought it would.

 

Bandwidth policies are assigned to your network sites; for example, this command assigns the policy LowBWLimits to the Vancouver site:

 

Set-CsNetworkSite -Identity Vancouver - BWPolicyProfileID LowBWLimits

 

And how did we create that bandwidth policy in the first place? Like this:

 

New-CsNetworkBandwidthPolicyProfile -Identity LowBWLimits -AudioBWLimit 2000 -AudioBWSessionLimit 200 -VideoBWLimit 1400 -VideoBWSessionLimit 500

 

As you can see, we simply called the New-CsNetworkBandwidthPolicyProfile cmdlet, gave our new policy an identity (LowBWLimits), and then assigned values to the individual session and total session parameters for both audio and video. If we now run the command Get-CsNetworkBandwidthPolicyProfile, we should see the following:

 

Identity : LowBWLimits

BWPolicy : {BWLimit=2000;BWSessionLimit=200;BWPolicyModality=Audio,

                    BWLimit=1400;BWSessionLimit=500;BWPolicyModality=Video}

BWPolicyProfileID : LowBWLimits

Description :

 

Actually, that is kind of hard to read, isn't it? OK, try this command instead:

 

Get-CsNetworkBandwidthPolicyProfile | Select-Object –ExpandProperty BWPolicy

 

That will give you output that looks like this:

 

BWLimit : 2000

BWSessionLimit : 200

BWPolicyModality : Audio

 

BWLimit : 1400

BWSessionLimit : 500

BWPolicyModality : Video

 

Much better. Right, Mom?

 

That's actually pretty straightforward. Unfortunately, it now starts to get a little bit tricky. Why? Well, suppose you want to change the audio bandwidth to 2200, but want to leave everything else exactly as-is. Logically enough, you'd probably run this command:

 

Set-CsNetworkBandwidthPolicyProfile -Identity LowBWLimits -AudioBWLimit 2200

 

Is that going to work? Well, it depends on your definition of "work." Here's what your bandwidth policy profile will look like now:

 

Identity : LowBWLimits

BWPolicy : {BWLimit=2200;BWSessionLimit=175;BWPolicyModality=Audio}

BWPolicyProfileID : LowBWLimits

Description :

 

Uh-oh. As you can see, the audio bandwidth limit got bumped up to 2200, just like we wanted. However, the audio session limit got switched to 175, and the video settings disappeared altogether. What's the deal here?

 

Well, the deal here is that the Set-CsNetworkBandwidthPolicyProfile cmdlet always replaces the entire policy with whatever parameters you gave it. We gave Set-CsNetworkBandwidthPolicyProfile just one parameter: AudioBWLimit. Therefore, it essentially created a brand-new policy, one with a limit of 2200 (as we asked) and a session limit of 175 (the default value, which is used because we didn't specify a session limit). And what happened to the video settings? Well, we didn't include any video settings, so Set-CsNetworkBandwidthPolicyProfile … helpfully … removed all those settings from the policy.

 

Thanks, Set-CsNetworkBandwidthPolicyProfile.

 

So is there a way to work around that? To the best of our knowledge, no, there isn't. If you want to make one little change to an existing policy you have to be sure to also include all the settings and values that you don't want changed:

 

Set-CsNetworkBandwidthPolicyProfile -Identity LowBWLimits -AudioBWLimit 2200 -AudioBWSessionLimit 200 -VideoBWLimit 1400 -VideoBWSessionLimit 500

 

Is that a hassle? Yes. But, then again, you probably won't be changing your bandwidth policy profiles very often, so ….

 

If you decide you don't need a bandwidth policy profile after all, you can simply delete that profile by using Remove-CsNetworkBandwidthPolicyProfile:

 

Remove-CsNetworkBandwidthPolicyProfile -Identity LowBWLimits

 

And if you have a desire to do something really weird, try these commands:

 

$x = Get-CsNetworkBandwidthPolicyProfile -Identity LowBWLimits

 

$x.BWPolicy.RemoveAt(1)

$x.BWPolicy.RemoveAt(0)

 

Set-CsNetworkBandwidthPolicyProfile –Instance $x

 

What do those commands do? Well, after creating an object reference ($x) to the policy profile LowBWLimits, they then use the RemoveAt method to remove the second policy in the profile (the video settings) and then the first policy in the profile (the audio settings).

 

Note. So why RemoveAt(1) and RemoveAt(0)? Because these policies are stored as an array, and the second item in an array is always item no. 1. And that makes the first item in the array item no. 0.

 

That will give you an "empty" policy profile:

 

Identity : LowBWLimits

BWPolicy : {}

BWPolicyProfileID : LowBWLimits

Description :

 

Why would you ever want to do that? We have no idea; we just wanted to show off for Mom. Mom, did you see what we did? Mom? Mom, are you watching?

 

Dang.

 

Oh, one other note: we also recommend that you use the CsNetworkBandwidthPolicyProfile cmdlets instead of the New-CsNetworkBWPolicy cmdlet. You can pretty much do the same thing with either the CsNetworkBandwidthPolicyProfile cmdlets or the New-CsNetworkBWPolicy cmdlet. But, for the most part, the CsNetworkBandwidthPolicyProfile cmdlets are much easier to work with. (And, besides, the New-CsNetworkBWPolicy cmdlet is really intended for future use, when additional types of bandwidth policies might be available to you.)

 

Note. And, yes, we can hardly wait for the future ourselves.

 

That's pretty much all we have for today. A special thanks to Mom, Steve Ballmer, and everyone else for your words of … encouragement …. Keep those cards and letters coming in!

 

Note. Um, please don't keep those cards and letters coming in. If you know what we mean.