Making Directory Queries Using the DSQUERY Command

---

You use the DSQUERY command to search Active Directory for objects matching a specific set of criteria. For instance, you could search for all computer accounts that start with “D” or all user accounts that are disabled and DSQUERY would return a list of objects that match the criteria.

DSQUERY Subcommands and Syntax

You make directory queries using the following subcommands and command- line syntaxes:

• DSQUERY COMPUTER Searches for computer accounts matching criteria

  dsquery computer [{StartNode | forestroot | domainroot}] [-o {dn | 
  rdn | samid}] [-scope {subtree | onelevel | base}] [-name Name] 
   [-desc Description] [-samid SAMName] [-inactive NumberOfWeeks] 
   [-stalepwd NumberOfDays] [-disabled] [{-s Server | -d Domain}]
  [-u UserName] [-p {Password | *}] [-q] [-r] [-gc] [-limit
  NumberOfObjects] [{-uc | -uco | -uci}]

• DSQUERY CONTACT Searches for contacts matching criteria

  dsquery contact [{StartNode | forestroot | domainroot}] [-o {dn | 
  rdn}] [-scope {subtree | onelevel | base}] [-name Name] [-desc  Description] [{-s Server | -d Domain}] [-u UserName] [-p {Password 
  | *}] [-q] [-r] [-gc] [-limit NumberOfObjects] [{-uc | -uco |
  -uci}]

• DSQUERY GROUP Searches for group accounts matching criteria

  dsquery group [{StartNode | forestroot | domainroot}] [-o {dn | rdn 
  | samid}] [-scope {subtree | onelevel | base}] [-name Name] [-desc  Description] [-samid SAMName] [{-s Server | -d Domain}] [-u User Name] [-p {Password | *}] [-q] [-r] [-gc] [-limit NumberOfObjects] 
   [{-uc | - uco | -uci}]

• DSQUERY OU Searches for organizational units matching criteria

  dsquery ou [{StartNode | forestroot | domainroot}] [-o {dn | rdn }] 
   [-scope {subtree | onelevel | base}] [-name Name] [-desc Description] 
   [{-s Server | -d Domain}] [-u UserName] [-p {Password | *}] [-q]
  [-r] [-gc] [-limit NumberOfObjects] [{-uc | -uco | -uci}]

• DSQUERY PARTITION Searches for Active Directory partitions matching criteria

  dsquery partition [-o {dn | rdn}] [-part Filter] [{-s Server | -d  Domain}] [-u UserName] [-p {Password | *}] [-q] [-r] [-limit  NumberOfObjects] [{-uc | -uco | -uci}]

• DSQUERY QUOTA Searches for object quotas matching criteria

  dsquery quota {domainroot | ObjectDN} [-o {dn | rdn}] [-acct  Name] [-qlimit Filter] [-desc Description] [{-s Server | -d  Domain}] [-u UserName] [-p {Password | *}] [-q] [-r] [-limit  NumberOfObjects] [{-uc | -uco | -uci}]

• DSQUERY SERVER Searches for domain controllers matching criteria

  dsquery server [-o {dn | rdn}] [-forest] [-domain DomainName]
  [-site SiteName] [-name Name] [-desc Description] [-hasfsmo 
  {schema | name | infr | pdc | rid}] [- isgc] [{-s Server | -d  Domain}] [-u UserName] [-p {Password | *}] [-q] [-r] [-gc] [-limit  NumberOfObjects] [{-uc | -uco | -uci}]

• DSQUERY SITE Searches for Active Directory sites matching criteria

  dsquery site [-o {dn | rdn}] [-name Name] [-desc Description] [{-s  Server | -d Domain}] [-u UserName] [-p {Password | *}] [-q] [-r]
  [-gc] [-limit NumberOfObjects] [{-uc | -uco | -uci}] 

• DSQUERY SUBNET Searches for subnet objects matching criteria

  dsquery subnet [-o {dn | rdn}] [-name Name] [-desc Description] 
   [-loc Location] [-site SiteName] [{-s Server | -d Domain}] [-u  UserName] [-p {Password | *}] [-q] [-r] [-gc] [-limit NumberOfObjects] [{-uc | -uco | -uci}]

• DSQUERY USER Searches for user accounts matching criteria

  dsquery user [{StartNode | forestroot | domainroot}] [-o {dn | 
  rdn | upn | samid}] [-scope {subtree | onelevel | base}] [-name  Name] [-desc Description] [-upn UPN] [-samid SAMName] [- inactive  NumberOfWeeks] [-stalepwd NumberOfDays] [-disabled] [{-s Server | 
  -d Domain}] [- u UserName] [-p {Password | *}] [-q] [-r] [-gc]
  [-limit NumberOfObjects] [{-uc | -uco | -uci}]

• DSQUERY * Searches for any Active Directory objects matching criteria

  dsquery * [{StartNode | forestroot | domainroot}] [-scope {subtree 
  | onelevel | base}] [-filter LDAPFilter] [-attr {AttributeList | 
  *}] [-attrsonly] [-l] [{-s Server | -d Domain}] [-u UserName] [-p 
  {Password | *}] [-q] [-r] [-gc] [-limit NumberOfObjects] [{-uc | 
  -uco | -uci}]

At first glance, the syntax is almost overwhelming. Don’t let this put you off of using DSQUERY. Most DSQUERY subcommands share a standard syntax and include only a few extensions to the standard syntax that are specific to the type of object with which you are working. The best way to learn the DSQUERY subcommands is to dive right in. So here goes.

Searching Using Names, Descriptions, and SAM Account Names

Regardless of the other parameters you use, the search parameters should include the name, description, or SAM account name on which you want to search. When you type the –name parameter, you search for the specified type of object whose name matches the given value. You can use an asterisk as a wildcard to make matches using partial names, typing, for example, –name Will* to match William Stanek. A simple search on a name looks like this:

dsquery user -name Will*

The resulting output from this query is the DN of any matching user account or accounts, such as

"CN=William R. Stanek,CN=Users,DC=cpandl,DC=com"

That’s all there is to a basic search. And you only had to use one parameter to get the results you needed.

Note

Keep in mind that with users, the –Name parameter searches on the Display Name as listed in the user’s properties dialog box. In this example, the account display name is William R. Stanek. With other types of objects, this would be the value in the Name field on the General tab in the object’s associated Properties dialog box.

The asterisk can appear in any part of the search criteria. If you know a user’s last name but not the user’s first name, you can search on the last name, such as

dsquery user -name *Stanek

You can also search using a partial beginning and ending of a name, such as

dsquery user -name W*Stanek

When you type the –desc parameter, you search for the specific type of object whose description matches the given value. Use an asterisk as a wildcard to make matches using partial descriptions, such as typing –desc Eng* to match Engineering Workstation. Consider the following example:

dsquery computer -desc Server*

The resulting output from this query is the DN of any matching computer account or accounts, such as

"CN=CORPSVR02,OU=Domain Controllers,DC=cpandl,DC=com"

Note

The –Desc parameter searches on the Description field as listed in the object’s associated properties dialog box. In the previous example, the computer account description began with the word “Server.”

When you use the –Samid parameter, you search for the specific type of object whose SAM account name matches the given value. Use an asterisk as a wildcard to make matches using partial SAM account names, such as typing –samid wr* to match wrstanek.

Note

In the user’s properties dialog box, the SAM account name is listed on the Account tab as the User Logon Name. For computers and groups, the SAM account name is the same as the related account name.

Setting Logon and Run As Permissions for Searches

By default when you use DSQUERY you are connected to a domain controller in your logon domain. You can connect to a specific domain controller in any domain in the forest by using the –S parameter. Follow the –S parameter with the DNS name of the server, such as

-s corpdc01.cpandl.com 

Here, you are connecting to the corpdc01 domain controller in the cpandl.com domain.

Note

Technically, you don’t have to use the fully qualified domain name (DNS name) of the server. You can use only the server name if you want. However, this slows the search because Active Directory must perform a DNS lookup to obtain the full name and then make the query.

Rather than connect to a specific domain controller in a domain, you can connect to any available domain controller. To do this, you can use the –D parameter. Follow the parameter with the DNS name of the domain, such as

-d tech.cpandl.com

Here, you connect to any available domain controller in the tech.cpandl.com domain. Keep in mind that you can’t use the –S and the –D parameters together. This means you either connect to a specific domain controller or any available domain controller in a given domain.

As with many other types of commands, you can authenticate yourself if necessary by specifying a user name and password. To do this, you use the following parameters:

-u [Domain\]User [-p Password]

where Domain is the optional domain name in which the user account is located, User is the name of the user account whose permissions you want to use, and Password is the optional password for the user account. If you don’t specify the domain, the current domain is assumed. If you don’t provide the account password, you are prompted for the password.

To see how these parameters can all be used together, consider the following examples:

Connect to the corpsvr02 domain controller in the tech.cpandl.com domain using the WRSTANEK user account in the CPANDL logon domain and search for a user account whose display name ends with Stanek:

dsquery user -name *Stanek -s corpsvr02.tech.cpandl.com -u  cpandl\wrstanek

Connect to any domain controller in the tech.cpandl.com domain using the Wrstanek user account in the cpandl logon domain and search for a user account whose display name begins with Will:

dsquery user -name Will* -d tech.cpandl.com -u cpandl\wrstanek 

Setting the Start Node, Search Scope, and Object Limit

In the command syntax, the start node is denoted by {StartNode | forestroot | domainroot} or it may include ObjectDN. This specifies the node where the search will start. You can specify the forest root (type forestroot), domain root (type domainroot), or a node’s DN (StartNode), such as: “CN=Users,DC=cpandl, DC=com”. If you specify by typing forestroot, the search is done using the global catalog. The default value is domainroot. This means that the search begins in the top container for the logon domain for the user account you are using. Some subcommands can be passed the actual DN of the object you want to work with (ObjectDN), such as: “CN=William Stanek,CN=Users,DC=cpandl, DC=com”.

Note

You may have noticed that I’m using double-quotes to enclose both object DNs. This is a good technique because it is required if the DN contains a space, as is the case for the second object DN used.

When you want to perform exhaustive searches, you will want to specify a node’s DN and the real value of doing so becomes apparent when you want to return complete object sets. You can, for example, return a list of all objects of a specific type in a specific container simply by specifying the start node to use and not specifying –Name, –Desc, or –Samid parameters.

To see how start nodes can be used, consider the following examples:

Return a list of all computer accounts in the domain:

dsquery computer "DC=cpandl,DC=com"

Return a list of all computer accounts in the Computers container:

dsquery computer "CN=Computers,DC=cpandl,DC=com"

Return a list of all computers in the Domain Controllers OU:

dsquery computer "OU=Domain Controllers,DC=cpandl,DC=com"

Return a list of all users in the domain:

dsquery user "DC=cpandl,DC=com"

Return a list of all users in the Users container:

dsquery user "CN=Users,DC=cpandl,DC=com" 

Return a list of all users in the Tech OU:

dsquery user "OU=Tech,DC=cpandl,DC=com"

In addition to being able to specify the start node, you can specify the scope for the search. The search scope is denoted by {–scope subtree | onelevel | base} in the command syntax. By default, the subtree search scope is used, which means the scope is the subtree rooted at the start node. For domainroot, this means the search scope is the entire domain. For forestroot, this means the search scope is the entire forest. For a specific container, this means the search scope is the specified container and any child containers. For example if the start node is set as "OU=Tech,DC=cpandl,DC=com", Active Directory would search the Tech OU and any OUs within it.

You use a value of onelevel to set the scope for the specified start node and its immediate children. With domainroot, for example, this would mean that the domain and its top-level containers and OUs would be included. However, if any of the OUs contained additional (child) OUs these would not be searched.

If you use a value of base, this sets the scope to the single object represented by the start node. For example, you would only search the specified OU and not its child OUs.

Note

subtree is the only valid value for the scope when forestroot is set as the start node.

To see how search scopes can be used, consider the following examples:

Search the Tech OU and any OUs below it for computer accounts:

dsquery computer "OU=Tech,DC=cpandl,DC=com"

Note

The default scope is for a subtree, which means –scope subtree is implied automatically.

Search only the Tech OU for computer accounts:

dsquery computer "OU=Tech,DC=cpandl,DC=com" -scope base

Search the Tech OU as well as OUs immediately below it for computer accounts:

dsquery computer "OU=Tech,DC=cpandl,DC=com" -scope onelevel 

Another optional parameter you can use is –Limit. This parameter sets the maximum number of objects to return in the search results. By default, if this parameter is not specified, the first 100 results are displayed. If you want to set a different limit, follow the parameter with the number of objects to return. For example, if you wanted only the first 10 results to be displayed, you can type –limit 10. To remove the limit and have all matching results displayed, you use a value of 0, typing –limit 0, for example.

Tip

In a large organization where there are potentially thousands of objects, you shouldn’t remove the limit. Instead, set a specific limit on the number of objects that can be returned or simply accept the default. This will ensure that your queries don’t unnecessarily burden the domain controller you are working with.

Setting the Output Format for Names

With DSQUERY, you can set the output format for the name values returned as well as the format for individual characters. In the command syntax, the output format for names is denoted by –o followed by one of these elements: {dn | rdn | upn | samid}. By default, the output format is as a DN (designated as –o dn), such as "CN=William R. Stanek,CN=Users,DC=cpandl,DC=com". You may also be able to specify the output format as a relative DN (by typing –o rdn), user principal name (by typing –o upn), or SAM account name (by typing –o samid).

The RDN is the common name of the object, taken from the lowest level name part of the DN. With users, the RDN is the same as the Display Name as listed in the associated properties dialog box. With other types of objects, this would be the value in the Name field on the General tab in the object’s associated properties dialog box. Some examples of RDNs include

• “William R. Stanek”

• “CORPSVR01”

• “Administrators”

UPNs are applicable only to user accounts. In Active Directory, there is an actual field with this name, which is used for logon and authentication. In the user’s properties dialog box, you’ll find the user logon name and logon domain on the Account tab. An example of a UPN is [e-mail]. Here, wrstanek is the logon name and @cpandl.com is the logon domain information.

The SAM account name applies to users, computers, and groups. Again, there is an actual field with this name in Active Directory but you can navigate the properties dialog to find it as well. For users, the SAM account name is the pre–Windows 2000 account name as designated on the Account tab of the related properties dialog box. For groups, the SAM account name is the same as the value listed in the name field on the General tab. For computers, the SAM account name is the same as the value listed in the name field on the General tab with a dollar sign ($) as a suffix.

Note

The dollar sign ($) is part of the actual computer account name but is normally hidden and isn’t referenced. Active Directory uses $ to allow you to have a user account and a computer account with the same name. This allows, for example, the user JAMESW to have a computer named JAMESW, which wasn’t possible with pre–Windows 2000 computers.

To learn more about name formats, consider the following examples:

Return the RDN for computers matching the search criteria:

dsquery computer -name corp* -o rdn

Return the SAM account name for the users matching the search criteria:

dsquery user -name Wi* -o samid

Return the UPN for the users matching the search criteria:

dsquery user "OU=Tech,DC=cpandl,DC=com" -o upn

Return the DN for the users matching the search criteria:

dsquery user "CN=Users,DC=cpandl,DC=com"

Note

The default format is as a DN, which means –o dn is implied automatically.

Using DSQUERY with Other AD Command-Line Tools

Because DSQUERY returns the DN of matching objects, the result set it returns is useful for piping as input to other Active Directory command-line utilities. Consider the following example where you search for all user accounts whose names begin with Willia:

dsquery user -name Willia*

The resulting output from this query is the DN of any matching account or accounts, such as

"CN=William R. Stanek,CN=Users,DC=cpandl,DC=com"

You could then pipe the result set as input for DSGET USER to display a list of groups of which this user is a member, such as

dsquery user -name Willia* | dsget user -memberof –expand 

The resulting output would show the group memberships according to their DNs, such as

"CN=Domain Admins,CN=Users,DC=cpandl,DC=com"
"CN=Enterprise Admins,CN=Users,DC=cpandl,DC=com"
"CN=Administrators,CN=Builtin,DC=cpandl,DC=com"
"CN=Domain Users,CN=Users,DC=cpandl,DC=com"
"CN=Users,CN=Builtin,DC=cpandl,DC=com"

---