The Directory Services Query (DSQuery) utility helps
you to obtain information about Active Directory content. For example,
you can obtain a complete list of the computers attached to the network
or the names of the users who rely on the network. Each kind of data
requires that you use a specific object type or the asterisk (*) for all
object types. The following list shows the most common objects (those
supported by the utility).
computer
contact
group
ou (organizational unit)
site
server
user
quota
partition
* (all objects)
All of these
objects require some basic input to obtain the data. For example, you
can expect to provide a username. The following list provides the common
inputs for each of the objects.
{StartNode | forestroot | domainroot | ObjectDN}
Determines the node
where the search starts. You can specify a node's distinguished name,
or use one of the default starting nodes that include forestroot (forest
root) or domainroot (domain root). Searching in the forest root means
that the utility performs a global catalog search of all the domain
controllers. Only the quota object uses the Object Distinguished Name
variable, which defines the distinguished name of the object to use as a
starting point for searches. The default setting is domainroot.
-o {dn | rdn | samid | upn}
Specifies the output
format for the list of entries the search obtains. Not every object can
use every output format. For example, when you search the contact
object, you can't use the samid output. See the individual object descriptions for additional details. The default setting relies on the dn format. The following list describes the common formats.
dn
Displays the distinguished name for each entry.
rdn
Displays
the relative distinguished name for each entry. A relative
distinguished name only shows the path from the starting point to the
current location in the Active Directory hierarchy.
samid
Displays the Security Access Manager (SAM) account name for each entry.
upn
Displays the User Principal Name (UPN) for each entry. This output only applies to the user object.
-scope {subtree | onelevel | base}
Defines the scope
of the search. The scope determines how far down the hierarchy the
utility searches for the specified object. The subtree option searches the subtree root and the specified start node. The onelevel option searches the immediate children (one level down the hierarchy) of the start node only. The basesubtree.
option searches the single object represented by the start node. When
working with the forest root node, you can only perform a subtree
search. The default search scope is
-name
Name
Searches for the object with the specified name. You can use the asterisk (*) to signify wildcard searches. For example, A* would search for all objects beginning with the letter A, while *ing would search for objects that end with "ing." You can also combine wildcards. For example, A*ing would search for objects that begin with "A" and end with "ing."
-desc
Description
Searches for an object with a specific description. As with the -name
argument, you can use wildcard characters as part of the search
criteria. Always enclose arguments that contain spaces within quotes.
Because most descriptions contain spaces, you can reduce errors by
always enclosing descriptions in quotes.
{-s
Server
| -d
Domain}
Connects to the
specified remote server or domain (not both). You must have the
required rights to access the server or domain. The default settings
rely on the domain controller for the logon domain. If you aren't logged
into a domain, the utility attempts to use the logon server. When a
logon server isn't available, the utility uses the local machine or
registers an error that Active Directory isn't installed.
-u
UserName
Specifies the name of
the user account to use to log onto a remote server. The default setting
relies on the user account of the currently logged on user. The
username can take several forms as shown in the following list.
UserName
The account name such as GeorgeS.
Domain\UserName
The domain name combined with the username such as MyDomain\GeorgeS.
User Principal Name (UPN)
The UPN version of the username that includes the fully qualified domain such as [email protected].
-p
{Password
| *}
Specifies the
user password. The utility prompts you for a password when you provide
the asterisk (*) in place of the actual password. Using this second
option is actually better from a security perspective because the prompt
dialog box will replace your password with asterisks. Using the command
line option displays your password in plaintext.
-q
Places the utility in quiet mode. The utility doesn't output any information to the command line.
-r
Searches using
recursive techniques. A recursive search follows all referrals in
children of the starting object, which means that you'll see all
potential results for a particular search. However, recursive searches
can consume considerable resources and require additional time to
complete. The default setting doesn't perform a recursive search.
-gc
Performs the
search using the Active Directory global catalog, which means searching
the entire forest. The default search only searches the current domain.
A global catalog search locates objects that meet the search criteria
across the entire network, but requires more resources and additional
time to complete.
-limit
NumberOfObjects
Determines the
number of objects that the utility returns for the specified search.
Limiting the number of objects that the utility returns can enhance
performance and use resources more efficiently. Setting this argument to
0 returns all of the objects. The default setting returns the first 100
objects.
{-uc | -uco | -uci}
Forces the utility
to output the results or input arguments in Unicode. The following list
describes each of these Unicode options.
-uc
Specifies a Unicode format for both input and output when using a pipe (|).
-uco
Specifies a Unicode format for output when using a pipe (|) or file.
-uci
Specifies a Unicode format for input when using a pipe (|) or file.
|
Use the pipe (|) to
transfer data between Active Directory utilities. In fact, you can use
the output of one search as input to a second search to create complex
searches.
|
|
Even though the basic
concepts are the same for each object, the individual objects present
small differences in the manner in which you query them. The following
sections describe these common objects and tell how you can access them.
1. computer
The computer object
locates computers on the network that match the search criteria. A
computer can serve any purpose in this case—everything from a server to a
workstation. This object uses the following syntax:
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}]
The following list describes each of the special command line arguments.
-samid
SAMName
Searches for computers that have the specified SAM account name.
-inactive
NumberOfWeeks
Searches for
computers that have been inactive for the specified number of weeks. In
this case, the system measures activity by logons to the domain.
Consequently, even if someone uses a computer daily, the system
considers it inactive until the user logs into the domain.
-stalepwd
NumberOfDays
Searches for computers that have not changed their password for the specified number of days.
-disabled
Searches for computers that have disabled accounts. The reason the system disabled the account isn't important.
