Script Your Own Desktop Diagnostic Tool

What if you could offer your Help desk technicians one-stop shopping in computer configuration information that included group memberships, installed software, hot fixes, disk space, uptime information, and blue screen instances? If you collected such data before dispatching a technician, you'd give the tech a detailed picture that could help him or her find hidden problems more quickly. In many cases, problems could be identified and resolved without an onsite tech visit. Another benefit would be that you could identify potential problems and resolve them before they become headaches. No single tool that I know of will produce a report with all the details of user permissions and PC configuration, but the good news is that you can build your own reporting tool by using command shell scripting utilities. If you're new to scripting, the DesktopDiag.bat script that I've developed will introduce you to the world of command shell scripting. As a bonus, the script can do double duty on servers. Having a detailed list of installed server software, services, and various configuration options can be an asset in server configuration control, disaster recovery planning, and server virtualization migrations.

Why Build Your Own Configuration Reporting Solution?
In many IT departments, the push is toward using Commercial Off-the-Shelf (COTS) tools and away from developing custom solutions. However, the main disadvantages of using a custom solution—development costs, maintenance costs, and breakage risk—don't apply to a scripted solution such as DesktopDiag.bat because such tools are simple to create, easy to maintain, and run only in an acquisition mode without making any configuration changes. In addition, your environment might require unique information that wouldn't be of interest to other companies with dissimilar environments. Having your own tool gives you the flexibility to add and remove items from the report. And, if you discover a new resource kit or third-party utility that has useful output for your report, you can easily incorporate it in the tool. Another advantage to a home-grown tool is cost. Because most scripting utilities are freeware, the cost of putting your own scripted solution together is minimal. Finally, if you decide to go shopping for a COTS solution in the future, you'll have developed an accurate requirements list.

Compiling the Output Wish List
When I developed DesktopDiag.bat, I first listed the information I wanted to capture. The list divides naturally into the categories of user and computer settings.

User settings (for logged on user or a specified user account)

Logged on username(s)

Username data such as user domain, friendly user name, user ID

User details such as home drive, home path, logon script, account expiration, logon hours, password age, password last reset

Level of authority the logged on user has

Local groups the logged on user is a member of

User profiles on the PC

User local and global group memberships

Computer settings

OS and service pack level

List of installed hotfixes

Network setting, including IP address information and MAC address

List of automatically starting programs

Processor type, speed, and installed memory

Resultant Set of Policies (RSoP)

OU location

List of Installed programs

Services and their status

List of shared folders

Details on logical drives, including drive letter, space-free and space-used statistics

Physical drives details

Video card details

Installed printers

Local computer group memberships

Bluescreen and uptime information

Local Administrator group members

Local groups the computer is a member of

Identifying Tools to Obtain the Data
Choosing utilities that will extract the data you want to see is a simple matter of listing the information you want, then locating the utilities that deliver that output. In many situations, a utility can give you more information than you require. You can either filter the output to just what you need or dump and sort through all the information that a particular tool supplies. The disadvantage to relying on a lot of filtering is that doing so adds overhead and increases script runtime. In some cases, you'll need to chain commands together; for example, you'll pull an initial piece of information such as the logged on username, then use that information to get group memberships. DesktopDiag.bat minimizes filtering. You'll likely see runtimes of well under 1 minute if the script is run locally, or from 1 to 1.5 minutes if run remotely. It would take much longer to retrieve the same information by running the tools individually or by using the Windows GUI.

DesktopDiag.bat uses 14 utilities and many built-in commands to capture report information. Table 1 lists these utilities. I've also developed a utility matrix that offers more detail about the tools and commands that DesktopDiag.bat depends on. To download the matrix and DesktopDiag.bat, magazine subscribers and registered Web site users can go to http://www.windowsitpro.com, enter 46268 in the InstantDoc ID text box, then click the 46268.zip hotlink. Because it's unusual for the resource kit and third-party tools to be installed on a local machine, I recommend that you create a shared folder to house the utilities on a server. Your script can point to this location. Keep in mind that limitations exist on what a given utility can accomplish. Some of the best tools for capturing information, such as the Ipconfig command, don't work remotely unless you use a remote command tool such as Sysinternals' PsExec or Beyond Logic's BeyondExec to launch them.

Identifying Capture Scenarios
In any solution you create, certain capture scenarios and tool limitations will affect what you can accomplish. In a PC configuration report, for example, if you plan for the report to show user information, what will happen if the user isn't logged on when you are querying his or her machine remotely? I identified four capture scenarios for DesktopDiag.bat that are representative of most troubleshooting situations.

Assembling Script Elements
After you've identified the utilities you plan to use, you need to assemble the utility commands into a code sequence that gives you the report output you want. I typically proceed by choosing the simplest capture scenario (i.e., number 1 from the list above) and concentrate on addressing that one scenario. After the local version of the script is working, I leverage that code to handle the other capture scenarios. DesktopDiag.bat's basic syntax format follows below. It contains a heading line followed by a blank line, then includes the output of a command or utility followed by another blank line. The double-redirect greater than (i.e., >>) characters send the output to a file in an append mode. The file is created if it doesn't already exist; if the file exists, the information is appended to the end of the file. A single redirect character (i.e., >) creates a file, overwriting any old data if a file of the same name exists.

The following basic syntax is used for the 14 utilities and built-in commands I've identified:

ECHO ********** Title Information Line **********>>"%file%"ECHO.>>"%file%"C:UtilLocToolName.exe >>"%file%"ECHO.>>"%file%"

Listing 1 gives an example of how the syntax is implemented in a script with the Microsoft Windows 2000 Resource Kit's Gpresult.exe tool.

To address the second capture scenario, DesktopDiag.bat retrieves data from a remote machine. Fortunately, gone are the days when most commands and tools would run only locally. The built-in remote functionality of tools such as the Microsoft Windows Server 2003 Resource Kit's Srvinfo.exe and Sysinternals' PsInfo and the availability of remote execution tools such as PsExec and BeyondExec enables remote queries that weren't possible only a few years ago. The code for data capture from a remote machine is very similar to the code for capture from a local machine but adds N/A comments for some commands that don't work well remotely. Note the breakout point for the remote code in Listing 2. If the script operator doesn't specify an argument at runtime, the script runs locally. If a single argument is specified, the script flow jumps to the remote section of the code.

The third capture scenario occurs when a username is specified and used in place of the logged-on username in a remote machine query. The username input is a argument specified at script runtime that immediately follows the target computer PC name argument.

While we're on the subject of specified arguments, one of the toughest but most necessary aspects of script coding is determining whether user input is flawed, particularly if you need to hand off the script to someone who might not be familiar with scripting. If I hadn't included error handling code in DesktopDiag.bat and you ran the script with an incorrect computer name or username, or if you specified a PC that wasn't online, the script would run through the code returning errors and produce a mystifyingly blank report.

To return to the third capture scenario, one of the first things to do is test for the existence and the online condition of the PC. Callout A in Listing 3 contains the "If Exist" code to test for the PC's existence. If the C$ share on the remote computer doesn't exist, the script terminates with an error message that tells the operator to check the computer's name or online condition. The code at Callout C determines whether the user account exists by checking it with joeware's GetUserInfo utility. If GetUserInfo returns the string "memberships" as part of its output, it has located a valid user account and is returning group memberships for the user. If GetUserInfo doesn't return "memberships," the script terminates and sends an error message to the operator. This operation prevents wasting time running the utility with bogus input. Some tools can seem to take forever to error out if input is incorrect.

Regarding the user account specified as a second argument in Listing 3, note the breakout point where the script flow detects the second argument in the code at callout B. First, the DUres variable is left blank, then made equal to the %2, or second script argument. The "If defined" code tests whether the DUres variable has content, then the For command breaks that string into the domain and username information that's tested against the GetUserInfo utility.

Capturing data on a remote machine while multiple users are logged on locally is the fourth capture scenario. You might be thinking, "How can a PC or server node have multiple local logons?" Terminal Services makes it possible for multiple users to log on locally to a node at the same time. Because DesktopDiag.bat has no idea which user you intend in the user portion of the code, you must work around this potential problem. You can use the Win2K resource kit's Findgrp tool with a For loop to capture group memberships for multiple users. However, if we run the Gpresult tool to get the logged in user's RSoP, the tool won't return accurate results because each time it runs it will query only against the console user's account. Consequently, the script must detect whether there are multiple logged-on users and disable Gpresult for the user policies if multiple local users are detected. Listing 4 contains the For command code that uses the usercntr variable to count the number of users who are logged on locally. Listing 5 contains the If command code that disables the Gpresult utility's run portion of the code if more than one user (i.e., if %usercntr% GTR 1) has been detected.

Testing the Script and Deploying to Support Technicians and Help Desk Teams
Extensive testing in your environment is the logical prior step to take before training users on and deploying the DesktopDiag.bat script. After you configure the script and place it in a shared location, you can make a trial run on a test box. Be sure to test the script under the four capture scenarios I've discussed. After you've tested the script, you might deploy it selectively so that you can easily observe the results and make changes as required. After the script is working to your satisfaction and you have any necessary management approval, you can fully deploy it to your Help desk team and other support technicians.

I've tested the DesktopDiag.bat script code on Windows Server 2003, Win2K Server Service Pack (SP) 3, Win2K SP3, and Windows XP Professional SP1. You can see the kind of output the script produces in the sample report file WORK1-diag.txt, which is available in the 46268.zip file. Here are step-by-step instructions for deploying the script.

Most configuration items will display correctly when you run DesktopDiag.bat on a local PC, even if the logged on user lacks local Administrator permissions. To run remote queries, you must have Administrator permissions on the target PCs.

You have several options for displaying the diagnostic results output from DesktopDiag.bat. At the conclusion of the script run, the code opens IE to display the output. If you prefer to use a different browser or another application to open the report file, you can modify the script so that it opens the report file with an alternate browser, Notepad, or WordPad. After the script creates and displays the output file, the file remains in the user's Temp folder—you can move or copy the file to an administrative location for retention or further analysis or delete it. If you want to delete the text output file after closing IE, uncomment the following line of code:

rem del "%file%"

If you want to move the text output file to another location after closing IE, uncomment the following line of code:

rem Move "%file%" "\servernamesharename%computername%-diag.txt"

If you want to copy the text output file to another location after closing IE, uncomment the following line of code:

rem Copy "%file%" "\servernamesharename%computername%-diag.txt"

You can deploy DesktopDiag.bat on a removable drive such as a mini USB drive or a floppy drive. Alternatively, you can locate the script on a central share location, such as the shared folder in which you stored the utilities.

Modifying the Script to Capture Additional Data
One of the advantages of scripting your own solution is that you can always add or remove scope quickly, particularly if you locate your script in a shared folder so that you can change the code in one location and all potential users will have access to your update. When the latest virus attack or spyware slips in under the radar, you can use DesktopDiag.bat to look for signature files or registry settings. When you have additional information needs, just add additional code lines following the basic syntax format I've shown you.

The DesktopDiag.bat script should prove to be an extremely flexible and useful utility in your troubleshooting toolkit. In just a minute or two it can query problem PCs and help you eliminate or at least shorten support technician visits.