Introducing DFS Namespaces Windows PowerShell Cmdlets

Overview

In this blog post, let me introduce you to the new DFS Namespaces (DFSN) Windows PowerShell cmdlets that we have added in Windows Server 2012.

Windows PowerShell is designed for automation and complex scripting, in part due to its powerful pipelining feature. Its object-based design streamlines user experience into focusing on the tasks you want to accomplish, and allows sophisticated output and input data processing. If you need further convincing on the value in using it for all your system administration needs, check out the extensive Windows PowerShell TechNet material.

The DFSN PS cmdlets cover most of the DFSN server-side management functionality that was previously available through the dfsutil command. As a side note, note that DFSN client-side management functionality, e.g. flush the local referral cache, is not yet supported through the new cmdlets – this functionality of course continues to be available through the “dfsutil client ..” command line tool. The really nice thing about the DFSN PS cmdlets is that while they run only on Windows Server 2012 or Windows 8 computers, you can use them to manage DFS Namespaces hosted even on previous Windows Server versions: Windows Server 2008, and Windows Server 2008 R2.

I suspect most of you reading this blog post have used DFS Namespaces for a while, so the namespace concepts and terms in the following discussion should be very familiar. In case you need to refresh your terminology, Overview of DFS Namespaces is a good one to refer to.

At the top-level, the new cmdlets fall into one of the following categories, here is the quick tour:

1. Namespace-scoped: Each DFS namespace presents one virtual folder view. This set of cmdlets operates on one or more such DFS namespace(s).
2. Namespace root target-scoped: Each DFS namespace can have one or more root targets - think of a root target as an SMB share presenting the namespace folder structure. This set of cmdlets acts on a root target.
3. Namespace server-scoped: Each DFS namespace server can host one or more namespace root targets. This set of cmdlets acts on a namespace server at the aggregate level.
4. Namespace folder-scoped: Each DFS namespace consists typically of a number of namespace folders organized in a virtual folder hierarchy. This set of cmdlets acts on one or more such namespace folders.
5. Namespace folder target-scoped: Each “bottom-most” DFS namespace folder or a leaf node in the folder hierarchy is associated with one or more folder targets where the real data is stored (such folders with associated folder targets were referred to as “links” in previous versions). This set of cmdlets acts on one or more such namespace folder targets.

Let us explore each of these categories of cmdlets in the same order.

Namespace-scoped cmdlets

This set of cmdlets provides Get/Set/New/Remove operations (called verbs in PS parlance) on a “DfsnRoot” object – which represents a DFS namespace.

Cmdlet	Description
Get-DfsnRoot	The Get-DfsnRoot cmdlet retrieves the configuration settings for the specified – or all the known - namespaces.
New-DfsnRoot	The New-DfsnRoot cmdlet creates a new DFS namespace with the specified configuration settings.
Set-DfsnRoot	The Set-DfsnRoot cmdlet modifies the configuration settings for the specified existing DFS namespace.
Remove-DfsnRoot	The Remove-DfsnRoot cmdlet deletes an existing DFS namespace.

Here are a few examples:

• Get the namespace information for a standalone namespace \\Contoso_fs\Public

PS C:\> Get-DfsnRoot –Path \\Contoso_fs\Public | Format-List

Path : \\Contoso_fs\Public

Description : Standalone test namespace

Type : Standalone

State : Online

Flags : Site Costing

TimeToLiveSec : 300

• Create a new Windows Server 2008 mode namespace

PS C:\> New-DfsnRoot –Path \\corp.Contoso.com\Sales -TargetPath \\contoso_fs\Sales -Type Domainv2 | Format-List

Path : \\corp.Contoso.com\Sales

Description : Domain-based test namespace

Type : Domain V2

State : Online

Flags :

TimeToLiveSec : 300

Note: TargetPath is the path to an SMB share to be used as the root target for this namespace. It is just as easy to create the SMB share using Windows PowerShell, run the following on file server \\contoso_fs:

New-Item C:\Sales_root_folder –type directory

New-SmbShare –Name Sales –Path C:\Sales_root_folder

• Set the root scalability mode and TTL properties for a domain-based namespace

PS C:\> Set-DfsnRoot –Path \\corp.Contoso.com\Sales -EnableRootScalability $true -TimeToLive 400

Path : \\corp.Contoso.com\Sales

Description : Domain-based test namespace

Type : Domain V2

State : Online

Flags : Root Scalability

TimeToLiveSec : 400

• Remove a domain-based namespace

PS C:\> Remove-DfsnRoot -Path \\corp.Contoso.com\Sales -Force

Namespace Root Target-scoped

These cmdlets support the same Get/Set/New/Remove operations, but on root targets. And remember that there can be multiple active root targets for a domain-based DFS namespace (which is why domain-based namespaces are generally the recommended option).

Cmdlet	Description
Get-DfsnRootTarget	The Get-DfsnRootTarget cmdlet by default retrieves all the configured root targets for the specified namespace root, including the configuration settings of each root target.
New-DfsnRootTarget	The New-DfsnRootTarget cmdlet adds a new root target with the specified configuration settings to an existing DFS namespace.
Set-DfsnRootTarget	The Set-DfsnRootTarget cmdlet sets configuration settings to specified values for a namespace root target of an existing DFS namespace.
Remove-DfsnRootTarget	The Remove-DfsnRootTarget cmdlet deletes an existing namespace root target of a DFS namespace.

Here are a few examples:

• Retrieve the namespace root target information for a domain-based namespace \\corp.Contoso.com\Sales, it has two root targets in this example.

PS C:\> Get-DfsnRootTarget –Path \\corp.Contoso.com\Sales | Format-List

Path : \\corp.Contoso.com\Sales

TargetPath : \\contoso_fs\Sales

State : Online

ReferralPriorityClass : sitecost-normal

ReferralPriorityRank : 0

Path : \\corp.Contoso.com\Sales

TargetPath : \\contoso_fs_2\Sales

State : Online

ReferralPriorityClass : sitecost-normal

ReferralPriorityRank : 0

• Add a new root target \\contoso_fs_3\Sales to an existing domain-based namespace, \\corp.Contoso.com\Sales

PS C:\> New-DfsnRootTarget –Path \\corp.Contoso.com\Sales -TargetPath \\contoso_fs_3\Sales

Path : \\corp.Contoso.com\Sales

TargetPath : \\contoso_fs_3\Sales

State : Online

ReferralPriorityClass : sitecost-normal

ReferralPriorityRank : 0

• Set the referral priority for a domain-based namespace root target

PS C:\> Set-DfsnRootTarget –Path \\corp.Contoso.com\Sales -TargetPath \\contoso_fs_2\Sales -ReferralPriorityClass globallow

Path : \\corp.Contoso.com\Sales

TargetPath : \\contoso_fs_2\Sales

State : Online

ReferralPriorityClass : global-low

ReferralPriorityRank : 0

• Remove a domain-based namespace root target \\contoso_fs_2\Sales for a domain namespace \\corp.Contoso.com\Sales

PS C:\> Remove-DfsnRootTarget -Path \\corp.Contoso.com\Sales –TargetPath \\contoso_fs_2\Sales

Namespace server-scoped

These two cmdlets operate on the namespace server overall – support Get/Set on the “DfsnServerConfiguration” object.

Cmdlet	Description
Get-DfsnServerConfiguration	The Get-DfsnServerConfiguration cmdlet retrieves the configuration settings of the specified DFS namespace server.
Set-DfsnServerConfiguration	The Set-DfsnServerConfiguration cmdlet modifies configuration settings for the specified server hosting DFS namespace(s).

Here are a few examples:

• Retrieve the namespace server configuration

PS C:\> Get-DfsnServerConfiguration –ComputerName contoso_fs | Format-List

ComputerName : contoso_fs

LdapTimeoutSec : 30

PreferLogonDC :

EnableSiteCostedReferrals :

EnableInsiteReferrals :

SyncIntervalSec : 3600

UseFqdn : False

• Set the Sync interval for the namespace server contoso_fs to 7200 seconds

PS C:\> Set-DfsnServerConfiguration –ComputerName contoso_fs -SyncIntervalSec 7200 | Format-List

ComputerName : contoso_fs

LdapTimeoutSec : 30

PreferLogonDC :

EnableSiteCostedReferrals :

EnableInsiteReferrals :

SyncIntervalSec : 7200

UseFqdn : False

Namespace Folder-scoped

This set of cmdlets operates on a DFS namespace folder path. In addition to Get/Set/New/Remove operations on a “DfsnFolder” object, renaming (Move) is also supported. Further, retrieving (Get), setting (Grant), revoking (Revoke) and removing (Remove) enumerate access on namespace folders is also supported through this set of cmdlets.

Cmdlet	Description
New-DfsnFolder	The New-DfsnFolder cmdlet creates a new folder in an existing DFS namespace with the specified configuration settings.
Get-DfsnFolder	The Get-DfsnFolder cmdlet retrieves configuration settings for the specified, existing DFS namespace folder.
Set-DfsnFolder	The Set-DfsnFolder cmdlet modifies settings for the specified existing DFS namespace folder with folder targets.
Move-DfsnFolder	The Move-DfsnFolder cmdlet moves an existing DFS namespace folder to an alternate specified location in the same DFS namespace.
Grant-DfsnAccess	The Grant-DfsnAccess cmdlet grants access rights to the specified user/group account for the specified DFS namespace folder with folder targets.
Get-DfsnAccess	The Get-DfsnAccess cmdlet retrieves the currently configured access rights for the specified DFS namespace folder with folder targets.
Revoke-DfsnAccess	The Revoke-DfsnAccess cmdlet revokes the right to access a DFS namespace folder with folder targets or enumerate its contents from the specified user or group account.
Remove-DfsnAccess	The Remove-DfsnAccess cmdlet removes the specified user/group account from access control list (ACL) of the DFS namespace folder with folder targets
Remove-DfsnFolder	The Remove-DfsnFolder cmdlet deletes an existing DFS namespace folder with a folder target.

Here are some examples for this set of cmdlets:

• Create a new namespace folder data1 under a domain-based namespace \\corp.Contoso.com\Sales pointing to a folder target of \\contoso_fs\df1 and using client failback mode

PS C:\> New-DfsnFolder -Path \\corp.Contoso.com\Sales\data1 -TargetPath \\contoso_fs\df1 -Description "My Data set 1" -EnableTargetFailback $true | Format-List

Path : \\corp.Contoso.com\Sales\data1

Description : My Data set 1

State : Online

Flags : Target Failback

TimeToLiveSec : 300

• Get the properties of a namespace folder data1

PS C:\> Get-DfsnFolder -Path \\corp.Contoso.com\Sales\data1 | Format-List

Path : \\ corp.Contoso.com\Sales\data1

Description : My Data set 1

State : Online

Flags : Target Failback

TimeToLiveSec : 300

• Set the EnableInsiteReferrals property of a namespace folder data1 (this example of combining target failback with in-site-only referrals makes practical sense only if there are multiple folder targets for data1 that are in the same site as the client)

PS C:\> Set-DfsnFolder -Path \\corp.Contoso.com\Sales\data1 -EnableInsiteReferrals $true | Format-List

Path : \\ corp.Contoso.com\Sales\data1

Description : My Data set 1

State : Online

Flags : {Target Failback, Insite Referrals}

TimeToLiveSec : 300

• Rename a namespace folder data1 to dataset1

PS C:\> Move-DfsnFolder -Path \\corp.Contoso.com\Sales\data1 -NewPath \\corp.Contoso.com\Sales\dataset1 -Force

• Grant enumerate access to User22 for the folder dataset1

PS C:\> Grant-DfsnAccess -Path \\corp.Contoso.com\Sales\dataset1 -AccountName Contoso\User22 | Format-List

Path : \\corp.Contoso.com\Sales\dataset1

AccountName : Contoso\User22

AccessType : enumerate

• Get ACLs for namespace folder dataset1 (let’s say User44 was also granted access to the same folder)

PS C:\> Get-DfsnAccess -Path \\corp.Contoso.com\Sales\dataset1 | Format-List

Path : \\corp.Contoso.com\Sales\dataset1

AccountName : Contoso\User22

AccessType : enumerate

Path : \\corp.Contoso.com\Sales\dataset1

AccountName : Contoso\User44

AccessType : enumerate

• Revoke access for User22 for namespace folder dataset1

PS C:\> Revoke-DfsnAccess -Path \\corp.Contoso.com\Sales\dataset1 -AccountName Contoso\User22 | Format-List

Path : \\corp.Contoso.com\Sales\dataset1

AccountName : Contoso\User22

AccessType : none

Path : \\corp.Contoso.com\Sales\dataset1

AccountName : Contoso\User44

AccessType : enumerate

• Remove a user User22 from the access control list for namespace folder dataset1

PS C:\> Remove-DfsnAccess -Path \\corp.Contoso.com\Sales\dataset1 -AccountName Contoso\User22

A Get-DfsnAccess on the same path would now show the following:

Path : \\corp.Contoso.com\Sales\dataset1

AccountName : Contoso\User44

AccessType : enumerate

• Remove a namespace folder dataset1

PS C:\> Remove-DfsnFolder -Path \\corp.Contoso.com\Sales\dataset1 -Force

Namespace Folder Target-scoped

This set of cmdlets operates on one or more folder target(s) of a namespace folder. Specifically, the same four operations Get/Set/New/Remove are supported on the “DfsnFolderTarget” object.

Cmdlet	Description
New-DfsnFolderTarget	The New-DfsnFolderTarget cmdlet adds a new folder target with the specified configuration settings to an existing DFS namespace folder.
Get-DfsnFolderTarget	The Get-DfsnFolderTarget cmdlet retrieves configuration settings of folder target(s) of an existing DFS namespace folder.
Set-DfsnFolderTarget	The Set-DfsnFolderTarget cmdlet modifies settings for the folder target of an existing DFS namespace folder.
Remove-DfsnFolderTarget	The Remove-DfsnFolderTarget cmdlet deletes a folder target of an existing DFS namespace folder.

Here are some examples for this set of cmdlets:

• Add a new namespace folder target \\contoso_fs2\df1 for the namespace folder \\corp.Contoso.com\Sales\dataset1

PS C:\> New-DfsnFolderTarget -Path \\corp.Contoso.com\Sales\dataset1 -TargetPath \\contoso_fs2\df1 | fl

Path : \\corp.Contoso.com\Sales\dataset1

TargetPath : \\contoso_fs2\df1

State : Online

ReferralPriorityClass : sitecost-normal

ReferralPriorityRank : 0

• Retrieve all the folder targets for the namespace folder \\corp.Contoso.com\Sales\dataset1

PS C:\> Get-DfsnFolderTarget -Path \\corp.Contoso.com\Sales\dataset1 | fl

Path : \\corp.Contoso.com\Sales\dataset1

TargetPath : \\contoso_fs\df1

State : Online

ReferralPriorityClass : sitecost-normal

ReferralPriorityRank : 0

Path : \\corp.Contoso.com\Sales\dataset1

TargetPath : \\contoso_fs2\df1

State : Online

ReferralPriorityClass : sitecost-normal

ReferralPriorityRank : 0

• Set the folder target state for \\contoso_fs2\df1 to offline

PS C:\> Set-DfsnFolderTarget -Path \\corp.Contoso.com\Sales\dataset1 -TargetPath \\contoso_fs2\df1 -State Offline | fl

Path : \\corp.Contoso.com\Sales\dataset1

TargetPath : \\contoso_fs2\df1

State : Offline

ReferralPriorityClass : sitecost-normal

ReferralPriorityRank : 0

• Remove the folder target \\contoso_fs2\df1 for the namespace folder \\corp.Contoso.com\Sales\dataset1

PS C:\> Remove-DfsnFolderTarget -Path \\corp.Contoso.com\Sales\dataset1 -TargetPath \\contoso_fs2\df1 -Force

Conclusion

I hope this gave you a decent overview of the new DFSN cmdlets in Windows Server 2012. And hope you will start using them soon!

Just be sure to download the "Windows Server 2012 and Windows 8 client/server readiness cumulative update" before you start working with the DFSN PS cmdlets, as the update includes a couple of fixes related to DFSN PS cmdlets. I am told that this update should be eventually available as a General Distribution Release (GDR) on Windows Update, but why wait? You can download it today and start playing with the cmdlets!