Microsoft DS Tools – part 2
DSQUERY is one of the most powerful tool which can be used to query any existing object within any domain in a forest.
It can be run in one of available method
- standard predefined context (basic query)
- LDAP syntax (more advanced query)
The first one is limited and it’s mostly used with cooperation with other DS Tools. DSQUERY always returns a Distinguished Name of a queried object. That’s the only one purpose of it in any context search. There is no possibility to change any object’s attribute using DSQUERY command. So, don’t worry, you cannot break anything in an environment using it!
You may ask “What’s so great in this tool if it can only return a DN of an object”? At this point the answer in not obvious but for those who used it at least once with other DS commands (i.e. DSGET) it’s one of the greatest tool which simplifies a life. It will become much more clear for us a little bit latter when we use it in “piped” mode.
Let’s check what contexts are available for that command. Each time you want to get help for DSQUERY, run in command-line
and you will receive an output where you can find these contexts:
the last one * (asterisk) is used for more advanced query (using LDAP syntax) which will be discussed in this article latter.
The most frequent used contexts are: computer, user, group and server. We use them almost every day in Active Directory management. Let’s start to see these tools a little bit closer to understand how to get them working.
We start explanation only with user context of DSQUERY tool. The rest works the same way. It’s time to check what we can request using that context. First of all, we will review its help by running in command-line
dsquery user /?
after typing this in command-line, we received all available switches to use in the syntax. This may look scary but don’t worry, we will discuss all necessary parts here. You need only couple of minutes to understend them all.
As each command-line tool, DSQUERY also requires some parameters to start working. There must be given at leat one parameter to start quering Active Directory for object(s). The most basic is -name parameter which meaning is equal to “Name” column in “Active Directory Users and Computers” console
OK, let’s try to run our first syntax of DSQUERY tool in command-line for “Krzysztof Pytko” user-object
dsquery user -name “Krzysztof Pytko”
Why do you put user Full Name in quotas? Because it’s necessary part of syntax, if object name contains a space.
REMEMBER! In each command-line tool, where you need to place an object name containing space, you have to put it within quotas “” to get it working properly!
and after typying that, review an output
Do you remember when I said that DSQUERY tool in context mode always returns Distinguished Name of an object? Now, you see that’s true! An output of typed command syntax is
OK, but this output is not valuable for us. Very few information can be read in this string:
- object common name – CN=Krzysztof Pytko
- Organizational Unit (OU) location of that object – OU=it,OU=users,OU=wroc (wroc/users/it)
- and a domain in which object exists – DC=testenv,DC=local (testenv.local)
what about other attributes? Actually, there is no possibility to get more using context mode of DSQUERY. Once again, as I said, the output is DN of an object. If you want to get more details, you need to use DSQUERY in “piped” mode.
That was the most simple syntax for querying user object in a domain. What if we want to find more users with common search criteria? Then we can use and * (asterisk) charecter which means:
- at the beginning of a syntax – find everything ending with specified string (i.e. -> *Pytko find all users with Pytko string at the end or simply saying, find all users with Pytko surname in the domain)
- at the end of a syntax – find everything beginning with specified string (i.e. -> Krzysztof* find all users starting with Krzysztof string or simply saying, find all users with Krzysztof first name in the domain)
- at the beginning and at the end of a syntax – find everything containing specified string (i.e. -> *Krzysztof* find all users with Krzysztof pattern in a string)
syntax for all users which surname is Pytko
dsquery user -name *Pytko
will return all user objects found in a domain.
OK, what if we want to find all users in a domain? Then instead of typing name to find, put * (asterisk) character
dsquery user -name *
The output will be limited to first 100 found entries (default limit). If you want to really display all users, you need to specify at the end of a command -limit 0 parameter
dsquery user -name * -limit 0
Now, you have listed all users in the domain in which query was run (by default query is performed in a domain from which was initiated).
Another possible way to search users is -samid parameter. Using it, you can query a domain for particular user login
dsquery user -samid iSiek
and like in previous parameter, you can query all user logins with * (asterisk) character
dsquery user -samid * -limit 0
similarly to previous command, you will get all users in the domain
So, let’s try to experiment a liitle bit more with DSQUERY user in your environment. Don’t worry, you cannot destroy anything!
The second usage of DSQUERY is more powerful. You can query for any object attibute and get value from it. For that you need to use generic LDAP queries. To start performing LDAP queries you need to know a DSQUERY syntax and a liitle bit more about object classes and categories.
To start LDAP query you need to use this syntax
dsquery * -filter “&(&(objectClass=objectClass)(objectCategory=objectCategory))” -attr AttributesListToQuery
the most common classes and categories used in LDAP queries are:
- for user object (objectClass=User)(objectCategory=Person)
- for computer object (objectClass=Computer)(objectCategory=Computer)
- for group object (objctClass=Group)(objectCategory=Group)
using this DSQUERY method for getting object attributes, you can get everything what you want. OK, but you can ask, how can I find LDAP attributes to be able to start querying a domain? You have few ways, one of them is to search the Internet and the second is to create sample query to get all set up attributes for the object.
User LDAP attributes you can find here
Group LDAP attributes you can find here
When you check both above links to LDAP attributes, you will be able to get any of them.
Another mentioned method by me is using sample query. Let’s try to do this for user object.
In this example we use existing user login (iSiek) to get all its attributes. We need to know that LDAP attribute for user login is sAMAccountName. When you skip (sAMAccountName=iSiek) in a syntax, you will request all attributes for 100 users in a domain. If you want to do that for all users, remember that you have to add -limit 0 at the end of syntax
Run this query in command-line
dsquery * -filter “&(&(objectClass=User)(objectCategory=Person)(sAMAccountName=iSiek))” -attr *
this query will request all LDAP attributes for iSiek user. Please notice, that each LDAP attribute is on the left side of colon (:) character whereas attrubute’s value is on the righ side of colon (:) character
if you wish to use only few of them, then instead of * character use LDAP attribute name. When you want to get more than one attribute, separate them using <space>
To get only First Name, Last Name and user login use this structure
dsquery * -filter “&(&(objectClass=User)(objectCategory=Person(sAMAccountName=iSiek))” -attr givenName sn sAMAccountName
I hope that this article helped you with basic DSQUERY understanding and now you can practice yourself in your test/production environment. Once again, don’t worry, DSQUERY works in read-only mode and you cannot break anything. Good luck!
Author: Krzysztof Pytko