$AdminSessionADSettings and you

Jared has previously posted twice on topics that skirt around the issue of "scope" in Exchange 2007: first in October as Tips 1 and 2 of the Exchange 2007 Console Tips and Tricks post and then again in January as Tip 1 of the Tips for Managing the Exchange Server 2007 Console Views post.

In these two posts, he does a pretty solid job of explaining scope, what it is, and (most importantly for his two topics) how it affects behavior in the GUI.

In this post, I'm going to review again what is scope... and I'm also going to introduce the AdminSession and show you how to control it in the Exchange management shell interface.

Admin Session

All AD access by Exchange 2007 is managed through a layer called "ADDriver". If you're familiar with Exchange 2003 technicals, just think of it as roughly the Exchange 2007 version of "DSAccess". AdminSession is the interface of ADDriver that is used to do all of the administrative management actions (as opposed to the reads/writes done through ADDriver on behalf of various Exchange services). Pretty much anything you do in the Exchange management shell or in the Exchange management console that reads/writes the AD is one of these administrative management actions. In short - nearly all of your management of the Exchange environment is done through the Admin Session of ADDriver.

Scope

Ok, now we have a context for Admin Session, let's talk about scope. The default scope for the admin session (whether in the Exchange management console or the shell) is what's called "Domain scope". This means that your admin session is configured to talk to a DC (not to the GC port, even if it's also a GC). And it means that your reads/writes will only operate within this DC's domain. This is pretty much how AD Users & Computers snap-in handled scope too.

Already, I have to take a step back and clarify something -- scope for the admin session only applies to first-class objects. What does that mean? It means if I do "Get-Mailbox" while I'm in domain scope, I'll only get back mailboxes (the first-class object I'm requesting) for my current domain scope. HOWEVER, if I try to set a forwarding address on a particular mailbox with "Set-Mailbox -ForwardingAddress username", the "username" entry can be from anywhere in the forest -- even though you're in domain scope. In the GUI, in particular, you can toggle the "picker scope" between domain scope and forest scope to refine the set of pickable entries shown.

Right back to it... Forest scope is a little different. When you're in Forest scope, the admin session talks to a GC for all reads (to get the whole forest view), but does any writes back to a DC in the appropriate domain. This is great because it means it's possible to get a view of all mailboxes in the whole forest, for instance. But it's also bad, because when you're in this mode, replication latency can make things in your view be out of date -- since you're reading from a GC and writing to a DC in the object's domain, it's quite possible you won't read the latest data if it's just been changed.

So, short version -- forest mode is great because it lets you see a unified, forest-wide view. But beware of replication latency in some cases.

$AdminSessionADSettings variable

On to the last part, what is this $AdminSessionADSettings variable? Well, you probably haven't heard of it unless you've stumbled across this little Gem at the Exchange Ninjas Wiki:

Q: How do I see objects in other domains ?

A: The scope of a query (such as get-mailbox) is controlled by a variable called $AdminSessionADSettings. To view object in other domains, try setting $AdminSessionADSettings.ViewEntireForest=$true and then issuing this command. You can also set this in your profile if you want this to be the default value.

Exactly! $AdminSessionADSettings is a variable exposed by the Exchange management shell to allow you to control a number of aspects of the AdminSession (let's just say it lets you control the Admin Session's AD settings <grin>).

The variable gets initially populated with some default values, and some from the Exchange management shell profile file. Initial values might look something like this:

 

[PS] C:\Documents and Settings\Administrator>$AdminSessionADSettings

ViewEntireForest : False
DefaultScope : domain.com
PreferredGlobalCatalog :
ConfigurationDomainController : server1.domain.com
PreferredDomainControllers : {}

Let's explain each of these values on the variable:

  • ViewEntireForest. This is a boolean (set with $true or $false) that controls whether we're in Forest scope ($true) or Domain scope ($false)
  • DefaultScope. This is the path you're scoped to (ie - domain.com, domain.com/Users, domain.com/Users/SubContainer). It's ignored if you're in forest scope.
  • PreferredGlobalCatalog. This is how you can "hard code" a global catalog server to be used for anything that requires a GC (forest scope, and also doing resolution of any global objects you're referencing in the admin session).
  • ConfigurationDomainController. This is how you can "hard code" a configuration domain controller.
  • PreferredDomainControllers. This is how you can configure one (or more) domain controllers to be used by the admin session any time a DC is required (domain scope, or writes while in forest mode). This is a multivalued entry, so you can add more than one. Note that if you need a DC for a domain where there's not any DC specified here, ADDriver will go find one automatically and ignore this list.  

$AdminSessionADSettings Usage

The easiest way to manipulate this variable is just like you'd manipulate any other variable. Here's some syntax examples:

Set to Forest Scope

[PS] C:\Documents and Settings\Administrator>$AdminSessionADSettings.ViewEntireForest = $true
[PS] C:\Documents and Settings\Administrator>$AdminSessionADSettings

ViewEntireForest : True
DefaultScope :
PreferredGlobalCatalog :
ConfigurationDomainController : server1.domain.com
PreferredDomainControllers : {}

Adjusting the DefaultScope property

 

[PS] C:\Documents and Settings\Administrator>$AdminSessionADSettings.DefaultScope = 'domain.com/Users'
[PS] C:\Documents and Settings\Administrator>$AdminSessionADSettings

ViewEntireForest : False
DefaultScope : domain.com/Users
PreferredGlobalCatalog :
ConfigurationDomainController : server1.domain.com
PreferredDomainControllers : {}

Configuring a Preferred GC

 

[PS] C:\Documents and Settings\Administrator>$AdminSessionADSettings.PreferredGlobalCatalog = 'server1'
[PS] C:\Documents and Settings\Administrator>$AdminSessionADSettings

ViewEntireForest : False
DefaultScope : domain.com
PreferredGlobalCatalog : server1.domain.com
ConfigurationDomainController : server1.domain.com
PreferredDomainControllers : {}

 

Configuring a Preferred DC

 

[PS] C:\Documents and Settings\Administrator>$AdminSessionADSettings.PreferredDomainControllers = 'server1'
[PS] C:\Documents and Settings\Administrator>$AdminSessionADSettings

ViewEntireForest : False
DefaultScope : domain.com
PreferredGlobalCatalog :
ConfigurationDomainController : server1.domain.com
PreferredDomainControllers : { server1.domain.com }

 

Configuring multiple Preferred DCs

 

[PS] C:\Documents and Settings\Administrator>$AdminSessionADSettings.PreferredDomainControllers = 'server1','server2'
[PS] C:\Documents and Settings\Administrator>$AdminSessionADSettings

ViewEntireForest : False
DefaultScope : domain.com
PreferredGlobalCatalog :
ConfigurationDomainController : server1.domain.com
PreferredDomainControllers : { server1.domain.com, server2.domain.com }