Windows Server 2003 Command-Line Utilities

Microsoft's Windows OSs owe much of their early success to their GUI, a dramatic departure from the text-oriented OSs of the day. I can still remember the effect the Windows 3.0 interface had on me after years of working with 24 * 80 green-screen systems. As the OS has matured, however, Microsoft has realized that a command-line utility is superior to a graphical one in many situations. Automation is the most obvious area. You can use a few command-line utilities and a batch file to create a scheduled task that's just about impossible to create by using a Microsoft Management Console (MMC) snap-in. A rich set of scripting resources, including languages such as VBScript and interfaces such as Active Directory Service Interfaces (ADSI) and Windows Management Instrumentation (WMI), are available to the administrator.

Unfortunately, the average administrator doesn't usually have the time to get comfortable enough with these tools to build useful utilities. Administrators need powerful, already-built utilities that they can throw into a batch file, and they usually need them yesterday. Because administrators need to figure out how to use the programs quickly, decent documentation is important. Consistent syntax across the utilities and informative error messages, both sorely lacking in the past, are important in helping administrators learn utilities quickly.

Microsoft formed Command Line Management, a distinct program office in the Windows Server 2003 development project, to address these administrator needs. Let's take a high-level look at nine significant command-line utilities for Windows 2003 that the Command Line Management program team either created or improved from existing tools.

Preliminaries
One of the goals of the Command Line Management program is to provide administrators with command-line utilities to perform their top management tasks. Not only are these utilities flexible and powerful enough for any administrator to use them to whip up useful scripts, they also improve on previous tools in several much-appreciated ways:

As I mentioned earlier, not all of the utilities are new. Many, such as Shutdown, are from the resource kit or Windows 2003 Support Tools, and are now more robust and standardized.

To be proficient with many of these tools, you have to become comfortable with the distinguished name (DN) convention of describing Active Directory (AD) objects. The DN of an AD object describes the object and where it sits in the AD hierarchy. A domain is prefaced with DC= (domain component); an organizational unit (OU), with OU=; and other objects, with CN= (common name). You start the DN with the object itself, then climb to the top of the AD hierarchy. For example, the DN of a DC in the BigTex.net domain would be CN=firstdomcont,OU=domain controllers,DC=bigtex,DC=net. If the DC were in the Sales child domain of BigTex.net, its DN would be CN=firstdomcont,OU=domain controllers,DC=sales,DC=bigtex,DC=net. Remember to enclose the DN in quotes if any of the object names include a space. Don't put a space between the comma and the following object name. I tend to capitalize CN, OU, and DC for clarity, but that practice isn't required.

Be careful if you build command-line utility scripts with anything other than Notepad. By default, Microsoft Word adds smart quotes, replaces double hyphens with em dashes, and uses all sorts of other symbols to make the text look better. As a result, you can spend an hour or two discovering that your command syntax is indeed correct but that the utility is rejecting a few nondisplayable symbols in your code.

The Adprep Utility
Adprep should come first in any discussion of new AD-related command-line utilities because as you might guess from its name, you use Adprep to prepare your existing Windows 2000 AD for upgrade to Windows 2003. If you've planned or installed Microsoft Exchange 2000 Server and Active Directory Connector (ADC) in your enterprise, you'll have worked with an earlier version of Adprep. Although upgrading a Win2K DC to Windows 2003 is straightforward, the Adprep process is a significant new step in this and future upgrades of Windows server OSs.

Adprep has two command switches: /forestprep and /domainprep. You use /forestprep to update the AD schema from the Win2K version 13 to the Windows 2003 version 30. To perform the update, /forestprep does the equivalent of running the Ldifde utility against each of 17 .ldf files (sch14.ldf through sch30.ldf). (For more information about the Ldifde utility, see the Microsoft article "Using LDIFDE to Import and Export Directory Objects to Active Directory" (http://support.microsoft.com/?kbid=237677). Each .ldf file contains schema updates (new object classes or attributes, or changes to existing ones) that Microsoft developers created during the course of the beta program. If you want to see the updates, you can view the .ldf files in the i386 directory on the Windows 2003 CD-ROM. You run /forestprep once for the entire forest, and its schema updates must have replicated to every DC in the forest before you can continue with the next step: running /domainprep. Figure 1 shows /forestprep updating the schema from version 29 to version 30.

You use /domainprep to update AD objects and security (e.g., access control entries—ACEs) for each domain. You must run /domainprep from the console of the infrastructure master DC in every domain. The /domainprep switch is much faster and generates a lot less output than /forestprep. If all goes well, the only feedback you receive is Adprep successfully updated the domain-wide information.

Adprep is located in the i386 directory on the Windows 2003 CD-ROM; it isn't installed by default into the %windir% folder as are the other command-line tools in this article. To successfully run Adprep /forestprep you must

To run Adprep /domainprep, you must

You can find many more details about the crucial process of preparing your Win2K forest for Windows 2003 in "Preparing for Upgrades in a Domain Containing Windows 2000 Domain Controllers," Section 4.1 in docsxxxsrv1.txt (where xxx is the product SKU number) on the Windows 2003 CD-ROM.

You must successfully complete both Adprep procedures before you can begin your DC upgrades. Although you won't run Adprep nearly as much as the other command-line utilities, it's more important than any of them.

The Dsadd Utility
The Dsadd utility adds to AD the most common types of objects: users, computers, groups (security or distribution), OUs, and even contacts. You can specify many common attributes to add with the object, but the command doesn't support all possible objects.

To add an OU to BigTex.net, type

dsadd ou OU=roughnecks,  DC=bigtex,DC=net  -desc "Oilfield Roughnecks"

all on one line. To add a group in the new OU, type

dsadd group CN=goodolboys,  OU=roughnecks,DC=bigtex,  DC=net -secgrp yes

At the same time you create the group, you can add members to it by using the -members option and nest it in other groups by using the -memberof option. To add a user named Jim Bob to the new group, type

dsadd user "CN=James Robert,  CN=Users,DC=bigtex,DC=net"  -samid JIMBOB  -upn [email protected]  -fn James -ln Robert  -empid 123456 -pwd n0tsecure!  -mustchpwd yes  -memberof CN=goodolboys,  OU=roughnecks,DC=bigtex,DC=net

Note that I've specified a password so that I can add multiple users without pausing at each one to enter a password. However, because I've set the -mustchpwd parameter to yes, users must change their password on first logon.

The Dsquery Utility
You can use two new command-line utilities to retrieve information about eight Windows 2003 AD objects: sites, subnets, servers, computers, OUs, groups, users, and contacts. Dsquery is meant for broader searches and supports the asterisk character (*) as a wildcard to search for all objects that match specific criteria. Dsget is more specific; you use it to view the properties of a specific object in the directory.

Figure 2 shows Dsquery's syntax with the most common parameters and their possible values. For Dsquery's first parameter you can specify a starting node for the search; forestroot, to use the GC; or domainroot (the default), to start at the root of the domain to which you're connected. The -scope parameter defines how deeply you want to search: subtree (the default) searches subtrees under the starting node, onelevel doesn't search any subtrees, and base searches only the object you specified in StartNode. The -filter parameter lets you specify a Lightweight Directory Access Protocol (LDAP) query filter if you want to retrieve only a specific object or attribute. An example of a valid search filter is (&(objectCategory=Person)(sn=smith*)). The -attr parameter returns only the attributes specified in AttributeList; and the -attrsonly parameter displays only the attributes that are present, not their values. The -l parameter returns the results in list format instead of the default table format.

For example, if you have an extensive AD implementation with many subnets, you could use the following Dsquery command to search for a specific subnet without digging through all the subnet definitions in the MMC Active Directory Sites and Services console:

dsquery * cn=subnets,cn=sites,  cn=configuration,dc=bigtex,  dc=net -scope subtree

Dsquery would return the results that Figure 3 shows.

The Dsget Utility
You can use the Dsget utility to display certain properties of AD objects. Like all the other AD-related command-line utilities, you select the object you want to display by DN. Figure 4 shows the general syntax of Dsget. DN is the DN of the object you're searching for, and AttributeOptions lists which of up to 33 attributes (e.g., -empid, -office) you want to display. The number of available attributes depends on the kind of object you're searching for.

For example, to check a user account to see whether the password was set to never expire (a setting that usually requires a security waiver), you could type

dsget user "cn=James Robert,  OU=roughnecks,DC=bigtex,  DC=net" -pwdneverexpires

and receive the following result:

pwdneverexpires     yesdsget succeeded

The Dsmod Utility
The Dsmod utility modifies existing AD users, computers, groups, OUs, and contacts. For example, you can change a group's membership or scope. Dsmod's OU option isn't as useful as the other options; you can't do much other than to change the description. To reset Jim Bob's password and force him to change it at the next logon, type

dsmod user "CN=James Robert,  CN=Users,DC=bigtex,DC=net"  -pwd Uf@tfingeredIt  -mustchpwd yes

If Jim Bob has just been too much trouble, you can disable his account by typing

dsmod user "CN=James Robert,  CN=Users,DC=bigtex,DC=net"  -disabled yes

To reset a computer account, type

dsmod computer CN=JimBobsPC,  CN=goodolboys,CN=roughnecks,  DC=bigtex,DC=net -reset

To change the GoodOlBoys group's scope from global to universal, type

dsmod group CN=GoodOlBoys,  CN=roughnecks,DC=bigtex,  DC=net -scope u

The Dsmod server command can make the task of creating a Global Catalog (GC) server easier than picking and clicking your way through the Active Directory Sites and Services console, as the following command shows:

dsmod server CN=firstdomcont,  CN=servers,  CN=default-first-site-name,  CN=configuration,DC=bigtex,  DC=net -isgc yes

Note that the DN of the server you want to make a GC server isn't the name you'd see in the MMC Active Directory Users and Computers console; instead, the name you need to type is the DC's representation in the Configuration naming context. (The Sites portion of the Active Directory Sites and Services console is really a view of the sites container in the Configuration naming context.)

The Dsmove Utility
The Dsmove utility moves an object within a domain. (You must use Movetree, in Support Tools on the Windows 2003 CD-ROM, to move objects between domains.)

Dsmove has two options: -newname and -newparent. You use -newname when you want to rename an object, as in

dsmove CN=sdeuby,CN=users,  CN=bigtex,CN=com  -newname "CN=Sean Deuby"

Note that to rename an object, you need to specify in the -newname option only the relative distinguished name (RDN) of the object, not the complete DN. If you wanted to relocate the SDeuby object within the domain to the Roughnecks OU we created earlier, you'd use the -newparent option, as in

dsmove CN=sdeuby,CN=users,  CN=bigtex,CN=com  -newparent OU=roughnecks,  DC=bigtex,DC=net

In this case, you must tell the target object (SDeuby) exactly where to go by specifying the full DN of the destination parent object (the Roughnecks OU in Bigtex.net).

The Dsrm Utility
In contrast to the other Ds utilities, Dsrm is quite simple: It deletes an AD object whose DN you specify. Other than the options for alternate credentials and server connections that all these tools share, Dsrm has only two options. The -subtree option specifies that you want to delete both the object and all objects under it. If you don't use the -subtree option, Dsrm deletes only the object. The -subtree option's -exclude parameter ensures that you keep the target object while deleting everything under it. The -noprompt option stops the utility from asking you to confirm the deletion. For example, the command

dsrm OU=roughnecks,DC=bigtex,  DC=net -subtree -exclude  -noprompt

deletes everything in the Roughnecks OU but leaves the OU intact.

The Shutdown Utility
Win2K and Windows NT originally didn't have a command-line utility to shut down the system. To address this omission, the Microsoft Windows 2000 Server Resource Kit added a Shutdown utility to perform some basic shutdown functions such as rebooting, forcing running applications to close, providing a simple GUI, and setting a countdown-to-shutdown timer. This Shutdown utility also has an abort switch (/a) to stop the countdown timer—which can be exciting to try to remember when you have less than 30 seconds before the system shuts down.

In Windows 2003, Shutdown has moved from the resource kit to %windir%system32. You can now do practically anything related to shutdowns and restarts right from the command line: shut down (/s), restart (/r), power down (/p), hibernate (/h), force-close applications (/f), and abort (/a). You can also use the /l switch to log off without shutting down.

An improved GUI, which Figure 5 shows, lets you shut down multiple computers with one command and specify the reason you're shutting down or restarting the computers. You open the Shutdown GUI by typing

shutdown /i

The new Shutdown Event Tracker tries to collect the reason for every operator-initiated shutdown. If the system has shut down unexpectedly, a reason-collection dialog box pops up the first time an administrator logs on after rebooting the system. The command-line Shutdown also lets you document the shutdown reason by using the /d switch and one of 23 reasons. For example, the command

shutdown /r /t 30 /f  /d p:02:04 /c:"This is a test  of the SHUTDOWN  command line utility"

reboots the computer after 30 seconds, forcing applications to close, leaving a message in the System event log, and specifying the reboot reason as "Operating System: Reconfiguration (planned)". The new Shutdown has a thorough Help file, which you open by clicking Help on the Shutdown GUI.

The Bootcfg Utility
In the sixth release of the Windows server OS, we finally have a way to programmatically manage the file that controls boot.ini, the system's boot menu. The Bootcfg utility lets you configure, change, or simply query the boot.ini file from the command line. The simplest way to use Bootcfg is to query the boot.ini configuration. At the C:winntsystem32> command prompt, type

bootcfg /query

Windows will display the system's boot.ini file, which will resemble the one that Figure 6 shows.

You could also use Bootcfg in a batch file that reconfigures a DC's startup sequence to boot automatically into Directory Service Repair (DSREPAIR) mode. Listing 1 shows such a batch file. If the first OS entry in your boot.ini file were

multi(0)disk(0)rdisk(0)  partition(1)WINNT="Windows  Server 2003" /fastdetect

the batch file would first copy the entry to use as the basis for a new entry. The batch file would then add the correct OS load options to enable DSREPAIR for the new entry and give the new entry an ID of 2. Then the batch file would set the new entry as the default. This simple script could remotely put DCs into DSREPAIR mode to run tasks such as offline defragmentation of the AD database.

Windows 2003's command-line utilities are a solid improvement over Win2K's utilities. You can quickly develop powerful scripts around them without VBScript experience or create a short batch file to run common queries. The utilities are yet another reason to upgrade from Win2K.