Don’t Dodge That Documentation

Let's face it—documenting servers is tedious and boring. Although systems administrators know documentation is important, it's often postponed until tomorrow. But, alas, as the infamous James Bond might say, tomorrow never dies, so the task never gets done.

One way to stop postponing this dreaded task is to use a cool gadget to automate the process. In the networking world, there are many Qs creating lots of cool gadgets for you to use. One such tool is SYDI-Server. Before taking this tool for a test drive, though, you should first understand what your mission entails and why it's so important.

The Mission Details
The dreaded day has finally come: A secret agent has blown up your server room. But your company is insured and you have backup tapes, so you're fine, right? Well, there might be a little glitch. I don't know of any insurance company that documents customers' networks for them. That mission is all yours. So, if you haven't documented your network yet, I recommend that you do so. A secret agent might not be lurking around, waiting to blow up your servers, but other foes, such as a fire or hurricane, can produce equally devastating results.

What should you include in the documentation? The answer depends on two factors: intended audience and purpose. If you're writing the documentation for your boss, he or she might only be interested in basic information such as a server's name and OS, the departments that use the server and what they use it for, and who is responsible for operating and maintaining the server. However, fellow IT staff members might want a bit more information. For example, they might want documentation about why certain services are running (or not running), how often to check event logs, or past server or application problems and how they were fixed.

If the purpose is to have a reference sheet that provides a quick overview of a server's setup and configuration, the documentation will be fairly short. If the documentation is for disaster recovery, the level of detail required will be much greater because you'll need in-depth information to create replicas of the destroyed servers.

No matter whether the documentation is detailed or not, I recommend that you document the following items for each server in your organization:

SYDI-Server at Your Service
SYDI (short for Script Your Documentation Instantly) is a collection of scripts to help you start documenting your network. SYDI comes in three versions: SYDI-Server (documents Windows servers or clients), SYDI-SQL (documents servers running Microsoft SQL Server), and SYDI-Exchange (documents Microsoft Exchange Server organizations). In this article, I focus on SYDI-Server, which I wrote to work with Windows Server 2003, Windows XP, and Windows 2000 Service Pack 4 (SP4). You can download the SYDI-Server files from the Windows Scripting Solutions Web site. Go to http://www.windowsitpro.com/windowsscripting, enter 45538 in the InstantDoc ID text box, then click the 45538.zip hotlink. If you're interested in SYDI-SQL or SYDI-Exchange, you can find out more information about them on SYDI's home page on Source Forge.net at http://sydi.sourceforge.net.

SYDI-Server performs gathering processes and reporting processes. To gather data, SYDI-Server queries a computer's Windows Management Instrumentation (WMI) database and its registry. After the data is collected, the reporting process kicks in and produces output in either a Microsoft Word or XML document.

Take SYDI-Server for a Test Drive
Before you use SYDI-Server for the first time, it's good to have an overview of the main script, sydi-server.vbs, and the different options it offers. To view these options, open a command-shell window, navigate to the directory in which you unzipped the sydi-server-1.3.4.zip file, and run the command

cscript.exe sydi-server.vbs -h

As this command's output shows, sydi-server.vbs has quite a few options. However, let's start our test drive by running the script without any options. Run the command

cscript sydi-server.vbs

Note that this command requires Word 2000 or later to be installed on the computer on which you're testing the script. When you run this command, a message box appears asking you which computer you want to target. The default is ".", which represents the local host. The default is fine for now, so press Enter to confirm. You'll now see the script gathering data.

Most of the data comes from the WMI database; the remaining information comes from the registry. After sydi-server.vbs sorts its findings, it begins to write the information in a Word document, as Figure 1 shows. Take a minute to browse the document you just created. As you can see, the script produces a lot of data. To exclude information from the document, you can use the script's command-line switches and options. You can also use switches to target different machines, run the script under different credentials, customize the Word document, create a XML document, and check for the latest version of SYDI-Server.

How to exclude information. By default, sydi-server.vbs gathers all the information it's designed to collect. However, you can choose to exclude certain WMI data by using the -w switch and exclude certain registry data by using the -r switch.

When you use the -w switch, most all the WMI data is automatically excluded. With the slate wiped clean, you then add those options that represent the WMI data you want to include, following the syntax

cscript sydi-server.vbs  -w[OptionList]

where OptionList is the list of desired options. (Although this command appears on a couple of lines here, you would enter it on one line in the command-shell window. The same holds true for the other multiline commands in this article.) Here are the -w switch options you can specify:

Note that some WMI data (e.g., the computer's name and network settings) is always gathered, so WMI is always used, even when you specify the -w switch with no options.

Like the -w switch, the -r switch's presence automatically excludes all registry data. So, after you use the -r switch to wipe the slate clean, you again have to specify those options that represent the registry data you want to include. Follow the syntax

cscript sydi-server.vbs  -r[OptionList]

where OptionList is the list of desired options. Here are the -r switch options from which to choose:

Note that when you specify the -r switch and no options, the registry check is completely eliminated.

Let's suppose you want to create a report that includes all the data except the data detailing the local users, local groups, installed patches, and Windows components. In this case, you'd use the command

cscript.exe sydi-server.vbs  -wabefpr  -rdp

How to target different machines. As I mentioned previously, when you run sydi-server.vbs, a message box appears asking you which computer you want to target. The default is the local host. However, you can specify any computer in your network, as long as the WMI service is running on that machine. Alternatively, you can use the -t switch to specify the target computer. When you use this switch, the message box doesn't appear. Thus, if you plan to use Scheduled Tasks or the Runas command to schedule sydi-server.vbs to run, you need to use the -t switch. (You also need to use the -d and -o switches if you want to create a Word report or the -ex and -o switches to create an XML report. I'll discuss these switches shortly.)

To use the -t switch, you simply specify the computer's IP address or name immediately after the switch. For example, if you want to gather all information from computer 192.168.0.10, you'd use the command

cscript.exe sydi-server.vbs  -t192.168.0.10

If you want only Windows Installer, BIOS, event log, and services information from the WWW1 server, you'd use the command

cscript.exe sydi-server.vbs  -wabes -tWWW1

Note that the -t switch, along with the -T switch (which I'll discuss later), are case sensitive.

How to run the script under different credentials. To run sydi-server.vbs, you need administrative privileges, but as you probably already know, you shouldn't be logged on with a highly privileged account. There are two ways to solve this dilemma. The first approach is to use the script's -u and -p switches. You use the -u switch to specify the administrative account's name and the -p switch to specify that account's password. For example, if you want to run the script on SERVER1 under the Administrator account, which has the password TomorrowNeverDies, you'd use the command

cscript.exe sydi-server.vbs  -uAdministrator  -pTomorrowNeverDies  -tSERVER1

The second approach is to use the Runas command to launch the script. For information about how to use this command, see the Windows online Help files.

How to customize the Word document. By default, sydi-server.vbs exports the information it gathers to a Word document; Word automatically opens and displays the document so that you can see the report as it's being written. If you want the script to run Word silently (which makes the script run faster) and save the report for later viewing, you can use the -d and -o switches. You use the -d switch to tell the script to run Word silently and the -o switch to specify the file's pathname. For example, if you want to run Word silently and save the file as DC1.doc in the C:Server Documentation directory, you'd use the command

cscript.exe sydi-server.vbs 
-tDC1 -d  -o"C:server documentation
dc1.doc"

Note that pathnames with spaces must be enclosed in quotes.

You can also customize the Word document by using the -T, -f, -b, and -n switches. With the -T switch, you can tell Word to use a .dot file as a template (e.g., -TC:corptemplatesserver.dot) for the report. The -f switch lets you change the report's base font size from the default of 12 to the number you specify (e.g., -f10). However, you can't use the -f switch to change the font size in a report created with a template. The -b switch lets you specify a Word table style (e.g., -b"Table Contemporary") to use.

To understand the -n switch, you need to take a look the top section in Figure 1. This section provides basic information that you should have in your documentation. Notice that some entries include instructions in square brackets. You need to replace the instructions (including the brackets) with the information you're instructed to provide. You can do so by editing the report after it's created or by modifying sydi-server.vbs. If you don't want to provide any of this information, you can use the -n switch to automatically exclude the instructions and brackets from the report.

How to create an XML document. If you want to receive your results in an XML document rather than a Word document, you use both the -ex and -o switches. The -ex switch specifies that you want an XML report, and the -o switch specifies the pathname for that report. For example, if you want the script to create an XML report named server1.xml in the C:corpfiles directory, you'd use the command

cscript.exe sydi-server.vbs  -tSERVER1 -ex  -oC:corpfilesserver1.xml

If you open server1.xml in Microsoft Internet Explorer (IE), you'll see a raw XML file. Although this file can serve many purposes, it's not user friendly. To get a report that's easier to read, you need to add the -sh switch, which prompts the script to use an Extensible Style Language (XSL) style sheet. For example, to use the style sheet to create server1.xml, you'd run the command

cscript.exe sydi-server.vbs  -tSERVER1 -ex -sh  -oC:corpfilesserver1.xml

How to check for the latest version of SYDI-Server. You can use the -v switch to determine whether you have the latest version of SYDI-Server. When you run the command

cscript.exe sydi-server.vbs -v

the script compares the SYDI-Server version available on the SourceForge.net Web site with the version currently being used. The script then lets you know whether you have the latest version or whether a newer version is available. You must have Internet access to use the -v switch.

A Good Start
SYDI-Server is a great tool for producing a basic reference for your servers. It can help you take that important step from "I'll do it tomorrow" to actually starting to document your network. Then, if your intended audience and purpose dictates that you need more in-depth information, you can build on the information that SYDI-Server has gathered for you.