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:
- Namespace-scoped: Each DFS namespace presents one virtual folder view. This set of cmdlets operates on one or more such DFS namespace(s).
- 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.
- 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.
- 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.
- 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!