Enterprise Software

SolutionBase: Using the Dsquery command in Windows Server 2003

Microsoft includes some handy GUI tools with Windows Server 2003 to help you manage Active Directory. Sometimes, however, command-line tools such as Dsquery can give you more flexibility and control. Here's a detailed look at the Dsquery command.

In the article "Getting started with Windows Server 2003's directory service command-line tools," I introduced you to the six basic directory service command-line tools and provided an expanded list showing you the particular objects that each tool is designed to work with. I also got you started with a basic understanding of distinguished names and the Lightweight Directory Access Protocol (LDAP) attribute tags.

The directory service command-line tools rely on these names to locate and work with objects in Active Directory. As I closed out that article, I briefly showed you how to use the Dsquery command to look at the distinguished names assigned to the objects in your Active Directory structure.

In this article, I'll pick up with the Dsquery command and examine its features. I'll then show you some cool search techniques you can perform with the Dsquery command to quickly and easily reveal information that would be a bit tricky to get out of GUI interface tools.

The commands

While the Dsquery command is one of the six main directory service command-line tools, it actually consists of 11 separate commands, as shown in Table A. Ten of these commands are designed to find objects of a specific type, and one is designed to find any object type in Active Directory.

Table A

Command Description
Dsquery * Finds any object
Dsquery computer Finds computer accounts
Dsquery contact Finds contacts
Dsquery group Finds group accounts
Dsquery ou Finds organizational units
Dsquery partition Finds Active Directory partitions
Dsquery quota Finds object quotas
Dsquery server Finds domain controllers
Dsquery site Finds Active Directory sites
Dsquery subnet Finds subnet objects
Dsquery user Finds user accounts
The Dsquery commands

Of course, each of these commands comes with a set of object-specific parameters that allow you to define the search criteria for each object. However, the majority of the parameters are common to most of the Dsquery commands.

The common parameters

Let's examine the common parameters and see how they work. Once you understand their function, you'll be able to look at the overly complex syntax layouts for each command and more easily pick out the object-specific parameters.

Targeting your search

The first set of common search parameters allows you to specify where you want your search operation to begin:

[{StartNode | forestroot | domainroot}]

To more narrowly focus your search, you can use a node's distinguished name (StartNode). To broaden your search, use the forestroot parameter, in which case the search is done using the global catalog. The default value is domainroot; while it's implied, if you don't type anything else, you can enter it on the command line if you really like to type out long command strings.

The second set of parameters in this category allows you to specify the scope of your search:

[-scope {subtree | onelevel | base}]

If you use the ï¿?scope base parameter, you target the search on a single object specified by command and the start node. In other words, you prevent the search from progressing down to child objects. Now, if you use the ï¿?scope onelevel parameter, you target the search on the object specified by command, the start node, and the object's immediate children. The ï¿?scope subtree parameter is the default, and it allows the search to freely progress down the tree from the start node.

As I mentioned, you can use the forestroot parameter in order to search the global catalog. You can also use the ï¿?gc parameter to require that your search specifically use the Active Directory global catalog.

One more way that you can target your search is by using the ï¿?r parameter. In this case, the r stands for recursion. This parameter allows you to specify that your search use recursionï¿?also described as following referrals during a search. As I understand it, this parameter allows you to extend your search to multiple servers.

Formatting output

The next set of common parameters lets you specify the output format for the search results:

[-o {dn | rdn}]

The default output is the distinguished name and uses the -o dn parameter. If you want to see the relative distinguished name, you'd use the -o rdn parameter.

As I said in the previous article, the Dsquery command will display only 100 objects by default. The next parameter allows you to expand the number of items displayed in the output:

-limit NumberofObjects

Essentially, you can use any number you want here. While it may seem a bit weird at first glance, if you want to see all of the objects, follow the -limit parameter with a zero. However, be careful when changing the limit because Microsoft's goal in limiting the output to 100 objects is to prevent the domain controller from being unnecessarily taxed by an exhaustive Active Directory search operation.

The last set of output format parameters also double as input format parameters and are designed to allow you to specify Unicode format:

{-uc | -uco | -uci}

The -uc parameter specifies a Unicode format for input from or output to a pipe (|). The -uco parameter specifies a Unicode format for output to a pipe (|) or a file. The -uci parameter is used to specify a Unicode format for input from a pipe (|) or a file.

While I'm on the topic of output, should you ever decide to run the Dsquery command and not see the results, you can use the -q parameter (a.k.a. Quiet Mode), which will suppress all output to the console. At first, this seemed like an odd thing to do, but then I thought it might be useful when you're redirecting output to a file. However, I've not had any luck getting the -q parameter to work at all.

Remote connection

The final set of common parameters that we'll look at are the remote connection parameters. By default, the Dsquery command assumes that you're running the command in the domain to which you're logged in. However, you can also run the Dsquery command on a remote server or domain.

{-s Server | -d Domain}

Using these parameters, you can connect to a specified remote server or domain. You might also need to specify a username and password, in which case you'd use these parameters:

-u UserName

-p {Password | *}

If you use the asterisk, you'll be prompted for a password.

Dsquery examples

Now that you have a good idea of how the Dsquery command works with its common parameters, let's look at some examples of where using this command will come in handy.

Tracking down servers

Suppose that while troubleshooting a problem, you discover that you need to quickly identify the domain controller that is performing one of the five Flexible Single Master Operation (FSMO) roles for a forest. What if you need to quickly identify which domain controllers are performing all five FSMO roles: the Schema Master, Domain Naming Master, RID Master, PDC Emulator, and Infrastructure Master? To perform this operation, you'll use the command:

Dsquery server

along with the parameters:


-hasfsmo {schema | name | infr | pdc | rid}

If you wanted to find only the Schema Master, you'd use the command:

Dsquery server -forest -hasfsmo schema

If you wanted to find all five, you'd use the command:

For %x in (schema name infr pdc rid) do Dsquery server -forest -hasfsmo %x

Here, I've simply incorporated the Dsquery server command in a pretty standard For In Do loop. To use this command line, you might want to type it in Notepad and save it as a batch file. You might also want to capture the output in a file. If so, you can add the following to the end of the command line:

>> FSMO-Query.txt

Tracking down inactive or disabled accounts

Suppose you've just taken a new job as a systems administrator. After a couple of days on the job, you discover that your predecessor wasn't very conscientious about cleaning up inactive and disabled user and computer accounts of employees who either left the company or were there only on a temporary contract basis.

You've already changed the name and passwords on all the Administrative accounts, and you want to plug any potential security breaches that have been left open by your predecessor. You need a way to quickly ascertain the magnitude of the problem. Fortunately, you can quickly gather the information you need with a few simple Dsquery commands. To find all user accounts that have been inactive for at least the last week or longer, you'd use the command:

dsquery user - inactive 1

To find all user accounts that have been disabled, but never dealt with further, you'd use the command:

dsquery user -disabled

To find all computers whose accounts have been inactive for the last week or more, you'd use the command:

dsquery computer - inactive 1

To track down all computers whose accounts are disabled, you'd use the command:

dsquery computer -disabled

Performing an inventory on the fly!

Now imagine this scenario: As a young network administrator, you learned the importance of documenting a network. Over the years, you've become very diligent when it comes to filling in the Description fields for every object account in Active Directory. The Description field for each computer account in your Active Directory structure contains a very detailed string of information that begins with a three-letter acronym specifying the operating system.

Suppose that your colleague asks you to find out how many computers in the Laptops organizational unit are still running Windows 2000 Professional. You could quickly open a command prompt window and type the command:

Dsquery computer OU=Laptops,DC=gcs,DC=com -desc W2K*

Similarly, you could find out how many computers in the Laptops organizational unit are now running Windows XP Professional by using the command:

Dsquery computer OU=Laptops,DC=gcs,DC=com -desc WXP*

Stay tuned

You should now have a pretty good handle on how to use the Dsquery command; you can use my examples as a starting point in your own explorations. In fact, if you come up with any cool examples of using the Dsquery command, please take a moment to share your command line by dropping a note in the Discussion area. In the next article, I'll focus on the Dsget command as I continue examining the directory service command-line tools.

About Greg Shultz

Greg Shultz is a freelance Technical Writer. Previously, he has worked as Documentation Specialist in the software industry, a Technical Support Specialist in educational industry, and a Technical Journalist in the computer publishing industry.

Editor's Picks

Free Newsletters, In your Inbox