Scripting DFS

Distributed File System (DFS) is becoming increasingly popular as a way to present users with a link to resources without regard for the actual back-end storage location. As the Microsoft article "How DFS Works" (http://technet2.microsoft.com/WindowsServer/en/Library/a9096e88-1634-4da6-b820-537341d349061033.mspx) explains, DFS lets you create a virtual view of shared folders through a namespace that an administrator creates. Users can view the namespace without needing to know where the data resides, regardless of whether it's on a Windows server or a non-Windows storage device. Because of DFS's increased popularity, I'm getting more frequent questions about how to script configuration and reporting of DFS. Fortunately for script writers, Microsoft provides several command-line tools that you can use to configure and query DFS. (For details about these tools, see the sidebar "DFS Scripting Tools," linked above.) However, these tools can return a lot more information than you really need. For example, most systems administrators and backup operators simply need to know the locations of specific back-end servers so that they can restore accidentally deleted files. To address this need, I wrote the DFSReportBuilder.bat script, a tool that will help you get valid output on the back-end target server locations that your DFS links are really pointing to. Using this script will make it easier for systems administrators and backup operators to locate backups that require restoration.

Listing 1 shows an excerpt from DFSReportBuilder.bat. You can download the complete script by clicking the Download the Code Here button above. I tested this script on a Windows XP Service Pack 2 (SP2) node running in a Windows Server 2003 domain. Always be sure to test your scripts in a development environment before deploying them in a production setting.

Requirements
The basic requirements for the DFSReportBuilder.bat script are that we capture all the DFS links and send an email message containing those links and the back-end server locations that the links map to. The Dfsutil.exe tool offers a switch option, /Export, for exporting the results to a file, but unfortunately, the export mode generates some XML output that isn't useable in the email message. Consequently, DFSReportBuilder.bat instead uses the /View option to capture and filter the output before using the Blat public domain command-line email program to send the report to a recipient list. The report format that we want the script to produce will contain only header information, the date of the report, and the DFS root name. Each line in the report will include the root name, link name, and target-server locations. If a link has more than one target-server location, the additional locations will appear on subsequent report lines. Although the Dfsutil.exe tool output contains the information we need, the output will require some massaging to yield the specific information we want for the email report. Let's look at four simple steps that will help you think through data filtering.

Step 1: Identify Important and Trivial Information
The first step in determining how to filter command output is to identify the information you need. I generally start by redirecting the command from my chosen tool (in this case, Dfsutil.exe) to a text file by using syntax such as:

DFSutil.exe /Root:\Sales   Reports /View>C:DFS.txt 

An examination of the output reveals a series of entries that include a line containing the link name and one or more lines with the target server or servers that are the back-end location of the data. Also, the output includes a line that gives us the DFS root name.

Step 2: Determine Your Filtering Execution Strategy
There are two basic ways to handle filtering. One way is to process the command output one line at a time, getting it into the format you need as it's coming from a file or For command. The second way is to use a batch technique in which you capture some or all of the command output in an array or file and process it all at once.

For this article's example, we'll first use a temporary file to hold the original output, as the sidebar "Arrays and Temporary Files," explains. Then, in the DFSReportBuilder.bat script, we'll use a two-stage filter. First, we'll use the batch strategy, as the code at callout C in Listing 1 shows. Second, we'll use the single-line approach, as the code at callout D shows.

Step 3: Dealing with Gotchas
Whenever you're dealing with groups, shares, links, or any user-specified object name, you face two big potential gotchas that can cause a script to fail. The first gotcha is spaces in the name, which can cause problems if you don't structure your tokens and variable sets to handle the presence of spaces correctly. The second gotcha is the ampersand character (&) in names, which can cause the script to exit prematurely when it's interpreted as a chain of commands.

Another problem that can thwart your filtering is dealing with separators such as quotation marks that fall in less-than-ideal places. The DFSReportBuilder.bat script uses the @ symbol to encapsulate non-trivial information. As callout G shows, the code removes the double quotes and adds them back in after adding the @ symbol.

Step 4: Reorganize the Output
Whenever you're dealing with reports, the utility you're using might return output in an order that's not user friendly. A common final processing step is to arrange output numerically or alphabetically. Dfsutil.exe, like many other utilities, doesn't return links in alphabetical order. So the last step of the output filtering is to rearrange the output into a user-friendly order.

The code at callout E shows the syntax of the Sort command.

Getting DFSReportBuilder.bat Working
To get the DFSReportBuilder.bat script working in your environment, you first need to download the script by clicking the Download the Code Here button above and download the Blat.exe SMTP mail tool from http://sourceforge.net/project/showfiles.php?group_id=81910. You also need to get the Dfsutil.exe tool, which is available with the Windows Server 2003 or 2000 Support Tools. Then, work through these steps:

Now you're ready to use the script. DFSReportBuilder.bat will help you give your systems administrators and backup operators the specific server-location information they need without making them wade through unnecessary output.