Share via


Dfsutil Syntax

Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2

DFSUtil Syntax

DFSUtil uses the following syntax:

Art Imagedfsutil [/?] [parameters]

Parameters

/api

/verbose

/? | /command /?

/root:

/server:

/share:

/domain:dfsDomainName

/newDomain:dfsDomainName

/oldDomain:dfsDomainName

/comment:

/AddFTRoot:

/AddStdRoot:

/RemFTRoot

/RemStdRoot

/RenameFTRoot

/RootScalability

/SiteName

/InSite

/SiteCosting

/Export

/Import

/UpdateWin2kStaticSiteTable

/ShowWin2kStaticSiteTable

/PurgeWin2kStaticSiteTable

/View

/PktInfo

/SpcInfo

/ExportBlob:filepathname

/CheckBlob

/DisplayBlob:filepathname

/ViewDfsDirs:volume

/ImportRoot:SrcDfsName /{Mirror|Compare}

/UnMapFtRoot

/Clean

/PktFlush

/SpcFlush

/PurgeMupCache

/RemoveReparse:absolute_directory_path

/api

Instructs DFSUtil to go through regular server APIs instead of directly connecting to the Active Directory.

DFSUtil normally operates on domain-based roots directly, without communicating with the DFS Service on the server hosting a particular root. This default mode is known as Direct Mode. In Direct Mode, commands execute faster, especially when importing large namespaces. However, for debugging purposes, you may decide to communicate with the DFS server by using its APIs instead.

Syntax

Art Imagedfsutiloption**/api** [/verbose]

Parameters

  • option
    The option that is to be modified by the /api parameter.
  • [ /verbose]
    Provides verbose output to the screen. This mode also notifies the user what mode a command executes in.

Remarks

Direct mode is essential when using parameters such as /RenameFtRoot, /UnmapFtRoot, and /Insite. These parameters will fail if Direct Mode does not initialize properly. Parameters that do not require a well-initialized Direct Mode (such as /View, /Import, and /export) will attempt to execute in the /api mode if the default Direct Mode fails. Specifying /Verbose displays the following information:

Sample Usage

dfsutil /view /root:\\dfsname\dfsshare /api

/verbose

Displays more detailed information when used with an Dfsutil Remarks.

Syntax

Art Imagedfsutiloption**/verbose**

Parameters

  • [ option]
    The option to be modified by /verbose.

Sample Usage

dfsutil /view /root:\\dfsname\dfsshare /verbose

/? | /command /?

Displays command-line help. The /command /? parameter displays more specific help about that command.

Syntax

Art Imagedfsutil [option] {/? | /help}

Parameters

  • [ option]
    The option that is to be modified by the /? or /help parameter.

Remarks

Some parameters provide additional help text when used with /? or /help.

Sample Usage

dfsutil /?

dfsutil /help

dfsutil /export /?

/root:

Specifies the DFS root context where the specified command is to be performed.

Syntax

Art Imagedfsutiloption**/root:**dfs_root_name

Parameters

  • option
    The option that is to be modified by the /root: parameter.
  • ****/root:dfs_root_name
    The UNC path to the DFS root context.

Sample Usage

To display the DFS configuration data of a specific DFS root:

dfsutil /view /root:\\dfsname\dfsshare

/server:

Specifies the DFS namespace server on which the designated command is performed.

Syntax

Art Imagedfsutiloption**/server:**dfs_server_name

Parameters

  • [ option]
    The option that is to be modified by the /server: parameter.
  • ****/server:dfs_server_name
    Specifies a DFS name space server.

Sample Usage

dfsutil /view /server:mycomputer.mydomain.com

/share:

Specifies the DFS or SMB share on which the designated command is performed.

Syntax

Art Imagedfsutil [option] **/share:**dfs_share_name

Parameters

  • [ option]
    The option that is to be modified by the /share: parameter.
  • ****/share:dfs_share_name
    The name of a DFS or SMB share.

Sample Usage

dfsutil /clean /server:aseanl-test1 /share:dfsroot

/domain:dfsDomainName

Specifies the DFS domain on which the designated command is performed.

Syntax

Art Imagedfsutiloption**/domain:**dfs_domain_name

Parameters

  • [ option]
    The option that is to be modified by the /domain: parameter.
  • dfsDomainName
    The netbios name or the fully qualified name of a domain.

/newDomain:dfsDomainName

Specifies the DFS domain on which the designated command is performed.

Syntax

Art Imagedfsutiloption**/newdomain:**dfs_domain_name

Parameters

  • [ option]
    The option that is to be modified by the /newdomain: parameter.
  • dfsDomainName
    The netbios name or the full qualified name of a domain.

/oldDomain:dfsDomainName

Specifies the DFS domain on which the designated command is performed.

Syntax

Art Imagedfsutiloption**/olddomain:**dfs_domain_name

Parameters

  • [ option]
    The option that is to be modified by the /olddomain: parameter.
  • dfsDomainName
    The netbios name or the fully qualified name of a domain.

/comment:

Adds a custom text comment to the blob when creating or deleting a Root, Link, or Target.

Syntax

Art Imagedfsutiloption**/comment:**text

Parameters

  • [ option]
    The option that is to be modified by the /comment parameter.
  • text
    The text to be added.

Remarks

Because they consume blob space, keep comments short.

Important

  • Avoid or reduce the usage of comments if you have a fairly high number of links and targets for a given root. Doing so will save blob space and improve overall DFS performance and scalability.

Sample Usage

dfsutil /AddFtRoot:MyDfs /server:MyServer /share:MyShare /comment:"A root of my dfs."

/AddFTRoot:

Creates a new DFS root in an existing domain-based DFS namespace. This command can also be used to add a computer as a root target to an existing namespace.

Syntax

Art Imagedfsutil/addftroot:new_dfs_root_name/server:dfs_server_name/share:dfs_share_name [/comment: text]

Parameters

  • newDfsRootName
    Name of the DFS to which the root will belong.
  • ****/server:dfsServerName
    Name of the server on which to create the root.
  • ****/share:dfsShareName
    Name of the share that will back the root.
  • ****/comment:text
    Optional custom text added to the blob related to this action.

Remarks

Because they consume blob space, keep comments short.

Sample Usage

In a domain-based DFS named \\DomainName\MyDfs, add \\MyServer\MyShare as a root of that DFS.

dfsutil /AddFtRoot:MyDfs /server:MyServer /share:MyShare /comment:"A root of my dfs."

/AddStdRoot:

Creates a new DFS root in an existing standalone DFS namespace. This command can also be used to add a computer as a root target to an existing namespace.

Syntax

Art Imagedfsutil/addstdroot:dfsRootName/server:dfsServerName/share:dfsShareName [/comment: text] [/api]

Parameters

  • dfsRootName
    Name of the root to remove.
  • ****/server:dfsServerName
    Name of the server on which to delete the root.
  • ****/share:dfsShareName
    Name of the root backup share.
  • /comment:''text''
    Optional custom text added to the blob related to this action.

Remarks

Because they consume blob space, keep comments short.

Sample Usage

In a domain-based DFS named \\DomainName\MyDfs, add \\MyServer\MyShare as a root of that DFS.

dfsutil /AddStdRoot:MyDfs /server:MyServer /share:MyShare /comment:"A root of my dfs."

/RemFTRoot

Removes a root target from an existing domain-based DFS root.

Syntax

Art Imagedfsutil/RemFTRoot:dfsRootName/server:dfsServerName/share: dfsShareName [/api]

Parameters

  • dfsRootName
    Name of root to remove.
  • ****/server:dfsServerName
    Name of the server on which to delete the root.
  • ****/share:dfsShareName
    Name of the root backup share.

Remarks

Prior to using this option, use /View to see how many replicas exist for this namespace.

Caution

  • Removing the last replica of a DFS namespace causes the namespace to be wiped out.

To back up a namespace, use /export. To reload a namespace which has been backed up with /export, use /import.

Sample Usage

To remove the root target of MyDfs which currently is backed up by \\MyServer\MyShare:

dfsutil /RemFtRoot:MyDfs /server:MyServer /share:MyShare

/RemStdRoot

Removes a root target from an existing stand-alone DFS root.

Syntax

Art Imagedfsutil/RemStdRoot:dfsRootName/server: dfsServerName /share: dfsShareName [/api]

Parameters

  • dfsRootName
    Name of the root to remove.
  • ****/server:dfs_server_name
    Name of the server on which to delete the root.
  • ****/share:dfsShareName
    Name of the root backup share.

Remarks

Prior to using this option, use /View to see how many replicas exist for this namespace.

Caution

  • Removing the last replica of a DFS namespace causes the namespace to be wiped out.

To back up a namespace, use /export. To reload a namespace which has been backed up with /export, use /import.

Sample Usage

To remove a root target of MyDfs that is backed up by \\MyServer\MyShare:

dfsutil /RemFtRoot:MyDfs /server:MyServer /share:MyShare

/RenameFTRoot

Given a DFS namespace, /RenameFtRoot renames references to an obsolete domain within that namespace.

This command can also be used to rename any link or target in a namespace.

Syntax

Art Imagedfsutil/renameftrootroot:dfs_root_name/olddomain:domain_name/newdomain:domain_name [/verbose]

Parameters

  • ****/root:dfs_root_name
    The UNC path to the DFS root context.
  • ****/olddomain:domain_name
    The name that you want to change your DFS namespace from. The same name that the /root: parameter references. This is a required parameter.
  • ****/newdomain:domain_name
    The name that you want to change your DFS namespace to. This is a required parameter.
  • [ /verbose]
    Displays verbose information in the output.

Remarks

Prior to changing the root, it is a good practice to discover the existing state. The /verbose parameter is useful with this command as it lists all changes which have been made to the namespace.

Important

  • After running this parameter, you must restart the DFS service on the servers where this command was run. Restarting the service causes the servers to recognize the new domain name in the namespace.

This command is typically run as a part of a domain rename. It is expected that the domain has already been renamed and the affected systems have been rebooted by the time this command is run. DFS servers that are running Windows 2000 Server or earlier are supported as root target servers; /RenameFtRoot will in fact change the registry entries of those systems appropriately.

/RenameFtRoot does not run in the /Api Mode. If Direct Mode initialization fails on the root specified (typically because the root is not Domain-based), then this command will fail.

Sample Usage

dfsutil /renameftroot /root: machname.OLDDOMAIN.company.com /olddomain: machname.OLDDOMAIN.company.com /newdomain: machname.NEWDOMAIN.company.com

/RootScalability

An advanced command which increases the performance of a large scale deployment of DFS namespaces.

Syntax

Art Imagedfsutil/rootscalability/root:dfs_root_name {/Enable|/Disable|/Display} [/verbose]

Parameters

  • ****/root:dfs_root_name
    The UNC path to the DFS root context.
  • /rootscalability { /enable| disable| display}
    Select the appropriate root scaleability action.

    Value Description

    enable

    Enables root scalability among DFS root servers. When enabled, network traffic among DFS root servers is kept to a minimum. In addition, there will be less traffic between the primary domain controller and DFS servers. This option is a tradeoff between users needing up-to-date information from DFS servers, and administrators needing minimal bandwidth consumptions by the DFS operations, (inter-DFS-server and DFS-to-domain-controller communication).

    disable

    Default behavior. This option results in tighter synchronization between DFS servers and Domain Controllers.

    display

    Display the current root scalability mode (enabled or disabled).

  • [ /verbose]
    Displays whether the root-scalability feature is currently enabled.

Remarks

Use this option in scenarios where the DFS metadata is comparably less dynamic and the network bandwidth has priority over up-to-date information or accessibility to up-to-date targets. Enabling this option may cause users to see outdated information from DFS servers at times, in terms of the target links and related information.

Notes

  • This command does not work in /Api mode.

  • The path specified must be a root, not a link.

  • This has no effect on Standalone roots.

  • It is a good practice to find out the current state before changing it.

  • When /rootscalability is enabled, it is not uncommon to see an event log message such as, "DFS could not access its private data from the DS...". While this error may still indicate a problem in DS connectivity, typically this occurs because the nearest domain controller has outdated DFS information (expected behavior when /rootscalability is enabled).

/SiteName

Displays the site name that a certain computer belongs to.

Syntax

Art Image**dfsutil/sitename:**dfsSiteName

Parameters

  • dfsSiteName
    The name of the computer on which site(s) reside. Valid formats in which to specify the computer name include:
    • computer name (local only)

    • UNC name

    • IP address

Sample Usage

dfsutil /sitename:machine4

dfsutil /sitename:mailserver.dom.com

dfsutil /sitename:georgeLaptop.domain.com

dfsutil /sitename:12.230.25.24

/InSite

Set or reset the insite setting on a root or a link, and view the current insite setting of a link or a root.

The insite setting on a link or root in a DFS defines how the DFS redirects the client access to that link or root, depending on the sites in which the client and the targets reside. The target could be a link target or a root target. This becomes important when the administrator wants to control the client accessing the root targets or link targets outside its own site. By using /InSite, the administrator can force the server to provide, in the referral list it returns to the client, only those targets which are in the same site as that of the client, when the client requests access to a certain root or link.

The /InSite setting has two modes: enabled and disabled.

Syntax

Art Imagedfsutil/root:dfs_root_name/insite /{Enable | Disable | Display} [/verbose]

  • ****/root:dfs_root_name
    The root name or the entire link name in UNC.
  • /insite { /enable| disable| display}
    Select the appropriate insite action.

    Value Description

    enable

    Clients will only access insite targets. This mode saves bandwidth by prohibiting client access to targets outside its site. However, this also reduces the availability of the DFS root on the link.

    disable

    Client will also access targets outside its site if necessary.

    display

    Displays the current insite mode (enabled or disabled) for the link or root.

  • [ /verbose]
    Displays verbose output to the screen.

Remarks

If you do not want to enable /InSite, see the /SiteCosting parameter. /SiteCosting provides more control over the DFS target referrals sent by the DFS server.

Sample Usage

dfsutil /root:\\dom.com\dfsroot /insite /display

Displays the current insite setting of the root dfsroot on domain dom.com.

Dfsutil /root:\\dom.com\DfsName\LinkA\B\C /insite /enable /verbose

This forces the DFS server to provide only insite target lists in the referrals for the link LinkA\B\C under the root \\dom.com\DfsName. As a result, the client accessing the link \\dom.com\DfsName\LinkA\B\C will not get a referral outside its site and will fail if there are NO targets responding in its site.

dfsutil /root:\\dom.com\DfsName\LinkA\B\C /insite /disable /verbose

This instructs the DFS server to provide all the link targets under link LinkA\B\C under the root \\dom.com\DfsName. As a result, the client accessing the link \\dom.com\DfsName\LinkA\B\C will get a list of referrals with targets in its site and outside its site as well. In fact, the targets of its site will be listed first (randomly), followed by the targets outside its site (also randomly).

/SiteCosting

Enables the DFS to issue referrals to the clients. The order in which the target referrals are listed is based on the following rules:

  1. The targets of the same site as that of the client are listed first. The order is randomized to provide load balancing.

  2. The targets from the next closest site are listed next (randomized again). This repeats until #3 occurs.

  3. The targets without any site information are taken as the farthest site, listed at the end of the referrals and randomized.

Syntax

Art Imagedfsutil/root:dfs_root_name /sitecosting {/Enable | /Disable | /Display} [/verbose]

Parameters

  • ****/root:dfs_root_name
    The UNC path to the DFS root context. This is a required parameter.
  • /sitecosting { /enable| disable| display}
    Select the appropriate sitecosting action.

    Value Description

    enable

    Enable sitecosting.

    disable

    Disable sitecosting. (Default.)

    display

    Display the current sitecosting mode (enabled or disabled).

Remarks

To illustrate how SiteCosting works, the Root \\dom5.com\fsRoot has a link named linkA\B\C, which, in turn, has 10 targets in different sites as follows:

  Entity Site Cost from client site

Client

\\myLaptop.dom1.com

NY-MANHATTAN-01

0

Targets for link LinkA\B\C

\\nyServ1\Folder

NY-MANHATTAN-01

0

 

\\Asterix\universal

--

Infinite

 

\\laOrange\ShareData

LA-ORANGE-21

5

 

\\Bromley02\Kohinoor

LONDON-UK-10

22

 

\\Champs1\Elysee

PARIS-Douxieme-01

19

 

\\Eiffel4\Distributed

PARIS-Douxieme-01

19

 

\\LondonBridge01\Data

LONDON-UK-06

21

 

\\ny43rdFloor\Data

NY-MANHATTAN-01

0

 

\\Submarine\Air

--

Infinite

 

\\laOrange5\Replicated

LA-ORANGE-21

5

When SiteCosting is disabled, the DFS server issues the referral as follows:

  1. Targets \\nyServ1\Folder, \\ny43rdFloor\Data randomly sequenced.

  2. Remaining targets randomly sequenced irrespective of their site.

When SiteCosting is enabled, the Referral list looks like this:

  1. Targets from the site same as the client randomly sequenced: \\ny43rdFloor\Data, \\nyServ1\Folder

  2. Targets from the next least expensive Site randomly sequenced: here site LA-ORANGE-21. Targets: \\laOrange\ShareData, \\laOrange5\Replicated.

  3. Targets from 3rd least expensive site randomly sequenced: here the site PARIS-Douxieme-01. Targets: \\Eiffel4\Distributed, \\Champs1\Elysee.

  4. Targets from 4th least expensive Site randomly sequenced: here the site LONDON-UK-06. Targets: \\LondonBridge01\Data.

  5. Targets from 5th least expensive Site randomly sequenced: here the site LONDON-UK-10. Targets: \\Bromley02\Kohinoor.

  6. Finally, targets without any site information known, believed to be the most expensive, are randomly sequenced. Targets: \\Asterix\universal, \\Submarine\Air.

Sample Usage

dfsutil /root:\\dom5.com\fsroot /sitecosting /enable /verbose

/Export

The /export parameter converts the configuration data into a reusable script file that describes an entire namespace. You specify the DFS namespace to export, and a file in which to save the exported configuration data. This file typically is the input for the /import parameter described later.

Syntax

Art Imagedfsutil/root: dfs_root /export: file_name

Parameters

  • ****/root:dfs_root_name
    The UNC path to the DFS root context. This is a required parameter.
  • ****/export:file_name
    The name of the file to export DFS configuration data to.

Remarks

The output file of the export is an XML file in DFS on a Windows Server 2003 system. Hence, it is important to note that if your current DFS is of a prior version, or the output files are coming from a prior version, it should be converted to the XML format to be reloaded by using the /import command option.

Warning

  • If the file you specify to export already exists it will be overwritten without any warning. You will lose any data in the original file.

Sample Usage

dfsutil /root:\\dfsname\dfsshare /export:dfsoutput.txt

/Import

The /import parameter creates or updates a DFS namespace from a DFS metadata stored in a specified file.

Syntax

Art Imagedfsutil/Root:dfsRootName/import:filename/{Verify | Set | Merge} [/Verbose]

Parameters

  • dfsRootName
    An existing DFS root to which the filename file is imported. Only the namespace specified by the root argument is affected.
  • filename
    An XML-formatted text file containing the DFS namespace. This file has usually been created by running /export.
  • ****/{ Verify| Set| Merge}
    Select the appropriate namespace action. This is a required parameter.

    Value Description

    Verify

    Displays changes that may happen during the import.

    Set

    Replaces the old namespace with the new namespace. All links and targets specified in the import file but not present in the new namespace are deleted.

    Merge

    Merge options decide the fate of the namespace that existed before the import command. The Merge option updates not only the links and targets that are common to both namespaces but also the new links and targets scripted in the input file. This is, in effect, a union of the existing namespace with the importing file-based namespace. If there is a conflict between the two, the file-based configuration is considered final.

Remarks

Use /Verify prior to the actual import (that is, using /Set or /Merge), to assess changes that may happen during the import.

The output file of the export is in XML format for Windows Server 2003 DFS. If your current DFS is of a prior version, or the output files are coming from a prior version, it should be converted to the XML format to be reloaded in the import command option with this version 4.0, that is, this version of DFSUtil.exe.

/UpdateWin2kStaticSiteTable

This is a mixed mode-only (Windows 2000 and Windows Server 2003) option.

In case of a DFS environment with servers running both Windows 2000 and Windows Server 2003, this option runs on the server running Windows Server 2003 to update the site information useful to the server running Windows 2000. When a link target is being added to a link on a domain-based DFS from a server running Windows Server 2003, the site information for that link target is not added to the DFS blob on the Active Directory. (This is different from a Windows 2000 domain-based DFS, where it would be added to the blob. The reason for this difference in behavior is that the server running Windows Server 2003 determines the site information dynamically (on an as-needed basis), so there is no need to add it to the blob in order to save the blob space. In the mixed mode scenario, where there is a domain-based DFS with at least one member server running Windows Server 2003 and at least one member server running Windows 2000, site information of any link target added by the server running Windows Server 2003 will not be added to the blob. So the member server running Windows 2000 will never know its site information.

Syntax

Art Imagedfsutil/root:dfsRootName/UpdateWin2kStaticSiteTable

Parameters

  • ****/root:h dfsRootName
    The DFS root on which this command is performed. Valid names are constructed as: \\dfsname\dfsshare.

Remarks

This command updates the Windows 2000 Site table.

The problem of mixed-mode interoperability is solved until more link targets are added from any server running Windows Server 2003. It is a good practice to update this site information table, as it is static, and an up-to-date table keeps the blob size optimal.

Use /ShowWin2kStaticSiteTable to display the state of the existing namespace. This can be especially useful in determining if the actual DFS namespace matches your namespace design.

/ShowWin2kStaticSiteTable

This is a mixed mode-only (Windows 2000 and Windows Server 2003) option.

Displays the current Target-to-Site mapping information stored in the blob of a DFS server running Windows 2000.

In a domain-based DFS with at least one member server running Windows Server 2003, and at least one member server is running Windows 2000, site information of any link target added by the server running Windows Server 2003 will not be added to the blob. So the member server running Windows 2000 will never know its site information.

To verify what the server running Windows 2000 knows about the sites of various targets, this option displays the Target-to-Site mapping.

Syntax

Art Imagedfsutil/Root:dfsRootName/ShowWin2kStaticSiteTable

Parameters

  • dfsRootName
    The DFS root on which this command is performed. Valid names are constructed as: \\dfsname\dfsshare.

Remarks

This helps the Administrator verify if member server running Windows 2000 has all the necessary site information.

/PurgeWin2kStaticSiteTable

This is a mixed mode-only (Windows 2000 and Windows Server 2003) option.

This parameter flushes site information from the blob. In a domain-based DFS with at least one member server is running Windows Server 2003, and at least one member server is running Windows 2000, site information of any link target added by the server running Windows Server 2003 will not be added to the blob. So the member server running Windows 2000 will never know its site information.

Syntax

Art Imagedfsutil/Root:dfsRootName/PurgeWin2kStaticSiteTable

Parameters

  • dfsRootName
    The DFS root on which this command is performed. Valid names are constructed as: \\dfsname\dfsshare.

/View

Displays the DFS configuration data of a DFS root. Included in the configuration data is a list of the roots of the DFS, a list of all of the links of the DFS, and site information for the DFS.

Syntax

Art Imagedfsutil/view {/Root: dfsRootName|/server: dfs_root|/domain: dfs_root}

Parameters

  • dfsRootName
    The DFS root on which this command is performed. Valid names are constructed as: \\dfsname\dfsshare.
  • ****/server:dfs_root
    Specifies the DFS namespace server on which this command is performed.
  • ****/domain:dfs_root
    Specifies the domain on which this command is performed.

Sample Usage

dfsutil /view

/PktInfo

Displays the following client information currently in the Partition Knowledge Table (PKT):

  • Parts of the DFS namespace cached by the client

  • Names of the servers participating in the DFS share

  • Clients’ randomization order of the participating servers

  • Current "go to" server

See Dfsutil Remarks for a description of the output produced by this parameter.

Syntax

Art Imagedfsutil/pktinfo [level:{0|1}]

Parameters

  • ****/level:{ 0|1}
    Optional report detail argument which takes a value of either 0 (low detail) or 1 (high detail).

Remarks

This is a DFS client-side operation.

Each entry will report a name, both full and short, the remaining time that the referral and information contained in it will remain in the referral list, followed by the referral list itself. Active alternate DFS client targets are indicated by the number "0X31" after the alternate name entry.

Note

  • Flushing the Partition Knowledge Table (PKT) clears existing information and force the DFS client to fetch new information for the next series of access attempts. See \PKTFlush.

DFS servers store the DFS namespace and the servers backing up the namespace in a BLOB format in the registry (stand-alone DFS) or Active Directory (domain DFS). The DFS BLOB is formally known as the Partition Knowledge Table (PKT). DFS clients retrieve and cache each piece of the DFS namespace for a period of time determined by the server.

For DFS servers running Windows NT 4.0, the servers send the list of servers backing a piece of the DFS namespace in the same order. Clients randomize the list of servers to provide a degree of load balancing.

For DFS servers running Windows 2000, Windows XP, or Windows Server 2003 that are accessed by Windows 2000 DFS clients, the scrambling and site preference takes place on the server.

Sample Usage

dfsutil /pktinfo

/SpcInfo

Displays the content of SPC. The SPC contains the list of trusted domains; under each trusted domain there may be one or more domain controllers.

See Dfsutil Remarks for a description of the output produced by this parameter.

Syntax

Art Imagedfsutil/spcinfo

Remarks

This is a DFS client-side operation.

This cache can be flushed if you feel the client has inaccurate information or is not aligned with the design of a DFS environment. See the SPCflush option.

Sample Usage

dfsutil /spcinfo

/ExportBlob:filepathname

Exports the blob of a DFS namespace which already exists (that is, specific to a root). This option saves the blob of the namespace specified, without any format changes, directly to a file.

Syntax

Art ImagedfsutildfsRootName**/exportblob:**filename

Parameters

  • dfsRootName
    The DFS root on which this command is performed. Valid names are constructed as: \\dfsname\dfsshare.
  • filename
    An absolute or relative pathname or working directory file.

Sample Usage

dfsutil /Root:\\dom.com\homedirroot /ExportBlob:e:\Backups\DFSbackups\Homedirroot\today.dfs

/CheckBlob

Checks the blob of a DFS namespace which already exists (that is, specific to a root). This is a basic consistency check.

Syntax

Art Imagedfsutil/Root:dfsRootName/checkblob

Parameters

  • dfsRootName
    The DFS root on which this command is performed. Valid names are constructed as: \\dfsname\dfsshare.

Sample Usage

dfsutil /Root:\\dom.com\homedirroot /checkBlob

/DisplayBlob:filepathname

Displays the blob stored in a blob file. The blob file is generally exported with /ExportBlob. This option is used to view the blob of a specific root.

Syntax

Art Image**dfsutil/displayblob:**filepathname

Parameters

  • filepathname
    Displays an existing file containing blob information.

/ViewDfsDirs:volume

Scans the specified volume and lists all DFS reparse directories. Reparse directories can also be removed when this option is used with the RemoveReparse option.

Syntax

Art Imagedfsutil/viewdfsdirs:volume [/removereparse: path] [/verbose]

Parameters

  • volume
    Name of the volume to scan.
  • /removereparse: path
    Removes all DFS reparse directories under a given absolute path directory/ hierarchy.
  • /verbose
    Displays more detailed information.

Remarks

The /RemoveReparse parameter can be used separately over a directory tree to remove all the DFS reparse directories under it.

Sample Usage

The following syntax lists all DFS reparse directories existing on volume (drive) e:dfsutil /viewdfsdirs:e:

The following syntax views and deletes (removes) all DFS reparse directories on volume (drive) c:. The /verbose parameter includes more descriptive details.dfsutil /ViewDfsDirs:c: /removereparse /verbose

/ImportRoot:SrcDfsName /{Mirror|Compare}

Copies an entire namespace under a DFS root to another DFS root, which, in turn, enables you to perform other operations such as Namespace Backup, DFS Server Maintenance, Create DFS mirror etc.

Syntax

Art Image dfsutil /Root:dfsRootName/ImportRoot:SrcDfsName {/Mirror | /Compare} [/Api]

Parameters

  • SrcDfsName
    An existing DFS namespace (root).
  • /{Mirror| Compare}
    Select the appropriate namespace action.

    Value Description

    Mirror

    Back up the SrcDfsName namespace.

    Compare

    Compare the SrcDfsName namespace with the new namespace.

  • / API
    Execute in API mode.

Remarks

Back up the existing namespace using the /export parameter before performing this operation.

Warning

  • When mirroring the DFS namespace, be careful to provide the /Root and /ImportRoot parameters in the correct order. Specifying these parameters in reverse order could be disastrous and irrecoverable.

Sample Usage

The namespace \\dom1\existing is compared to \\dom2\bin, where \\dom\bin can also exist.dfsutil /Root:\\dom2\bin /ImportRoot:\\dom1\existing /Compare The namespace \\dom1\existing is to be mirrored to \\dom2\bin, where \\dom\bin can also exist but this will overwrite the existing namespace.

dfsutil /Root:\\dom2\bin /ImportRoot:\\dom1\existing /Mirror

/UnMapFtRoot

Manually removes references to an obsolete domain-based root target. At times it may not be feasible for the administrator to remove a root target server from the namespace gracefully. This command eliminates the resultant obsolete root target in the DFS namespace. Since the target host server is unlikely to exist at this point, DFSUtil does not attempt to contact it.

Syntax

Art Image**/unmapftroot /server:root_target_server/share:**root_target_share

Parameters

  • ****/server:root_target_server
    This option specifies the root target server. This is a required parameter.
  • ****/share:root_target_share
    This option specifies the target share server.

Remarks

This advanced command should be used only to delete references to a fault-tolerant root target that does not exist. It works only on domain-based roots.

Caution

  • This command is essentially a problem/corruption repair tool. Do not confuse it with commands such as /RemFtRoot or /Clean.

The command will fail if Direct Mode was unable to initialize.

Sample Usage

dfsutil /UnmapFtRoot /root:\\mydomain.com\namespaceroot /server:\\otherservername /share:\\myserver\share

/Clean

A troubleshooting option which removes a reference to an obsolete root.

Syntax

Art Imagedfsutil/clean/server:hostServer/share:rootname [/verbose]

Parameters

  • ****/server:hostServer
    The server where the obsolete root existed.
  • ****/share:rootname
    The root reference to remove.

Remarks

If a root was not removed properly (by using the /RemFtRoot command), other root target servers may still try to reference the obsolete root. This option fixes the incorrect references.

This command contacts the registry of the specified system to delete obsolete references. It does not affect the Domain Controller or the Active Directory. This option should not be confused with commands such as /UnmapFtRoot and /RemFtRoot.

/PktFlush

Flushes the client's locally cached target referral list provided by the DFS server. When the client tries to access the corresponding link, this forces the client to refresh the referral list of targets from the DFS server. Some of the entries in the PKT may not get flushed, especially if DFS is in the process of using the referrals.

Syntax

Art Imagedfsutil/pktflush

Remarks

This is a DFS client-side operation.

Important

  • This option should be avoided unless absolutely necessary. Under normal DFS operating conditions, there is no reason to flush the existing referral list.

DFS clients cache the portions of the DFS namespace (PKT) for the duration of time specified in the Distributed File System Manager and referred to as the Time to Live (TTL). For DFS version 4.1, the PKT was cached for a hard-coded seven (7) days. Servers running Windows 2000 use 1800 seconds (30 minutes) as the default TTL. All Microsoft DFS clients delete the PKT for a given folder in the DFS tree if not accessed by the TTL expiration or when the client is rebooted, whichever occurs first.

Computers running Windows 2000 and Windows XP operating systems support the DFS tab in the Windows Explorer property sheet, which uses the NetDFSGetClientInfo() and NetDFSSetClientInfo() APIs to show the list of alternative paths residing in the volume, and which allows choosing another alternative (refresh PKT) without having to reboot or wait for TTL to expire.

DFS clients that run an operating system other than Windows 2000 or Windows XP must reboot or wait for the TTL for a cached portion of the DFS tree to expire.

/SpcFlush

Forces the client to fetch the latest information on the trusted domains and their domain controllers, when the client programs try to access a corresponding link or root. By using this option, the client flushes out its cached knowledge about the trusted domains and the domain controllers of these domains.

Syntax

Art Imagedfsutil/spcflush

Remarks

This is a DFS client-side operation.

/PurgeMupCache

Resets the client's knowledge about the various sites' information. This is a troubleshooting option which should only be run on the client.

Clears the client MUP cache, preventing confusion about the current provider when such names conflict. Except for a temporary performance hit, this command has no other adverse effects. This command does not affect any DFS metadata. If this command is not run, and the namespace is not accessed, the obsolete cache entry eventually expires.

Syntax

Art Imagedfsutil/purgemupcache

Remarks

This is a DFS client-side operation.

The MUP cache keeps information about both DFS and other shares on the client system. You create a non-DFS (for example, SMB) share and access it before mapping a DFS namespace by the same name on it. The MUP cache might still think that the share is served by the previous provider (SMB) although DFS is the correct provider now.

/RemoveReparse:absolute_directory_path

Removes all DFS reparse directories under a given absolute path directory/hierarchy.

Syntax

Art Imagedfsutil/removereparse:absolute_directory_path [/viewdfsdirs]

Parameters

  • absolute_directory_path
    The AbsoluteDirectoryPath is the path of the directory tree under which your reparse directories exist, all of which you intend to remove.
  • [ /viewdfsdirs]
    See /viewdfsdirs for more information

Remarks

This option can be used as an additional parameter to /viewdfsdirs. In this context, it removes all the DFS reparse directories under a specified volume.

Sample Usage

The following syntax removes all DFS reparse directories under the specified directory. dfsutil /RemoveReparse: c:\dfspath\dfsshares

See Also

Concepts

Dfsutil Overview
Dfsutil Remarks
Dfsutil Examples
Alphabetical List of Tools
Topchk.cmd
Rsdir Overview
Rsdiag Overview
Iologsum Overview
Health_chk Overview
Ftonline Overview
Filever Overview
Efsinfo Overview
Dmdiag Overview
Dskprobe Overview
Diruse Overview
Connstat Overview
Cabarc Overview
Bitsadmin Overview