Active Directory tool commands in AD Bridge
AD Bridge includes a tool (named adtool) to modify objects in Active Directory. Use the tool to:
- Query and modify objects in Active Directory.
- Find and manage objects in AD Bridge Cells.
Command:
/opt/pbis/bin/adtool
Help syntax:
/opt/pbis/bin/adtool --help -a
Use adtool
Privileges: The adtool provides similar features as native Microsoft Active Directory tools. When using adtool, be sure to use an account that has appropriate permissions in place to apply changes to Active Directory objects.
For example, to add a user to a security group, you must be a member of a security group, such as the Enterprise Administrators security group.
Note
For more information on Active Directory privileges, permissions, and security groups, see the following references on the Microsoft TechNet website:
Options: There are short and long options. Separate arguments from options with either space or equal sign. If you are not sure about the results of an action you want to execute, run it in read-only mode first (-r). It can also be useful to set the log level to TRACE (-l 5) to see all execution steps the tool is taking.
Authentication: The adtool uses single sign-on by default if the computer is domain-joined. Otherwise, it uses krb5 using a cached ticket, keytab file, or username and password (unless secure authentication is turned-off (--no-sec).
Name resolution: In most cases, you can reference objects by FQDN, RDN, UPN, or names that make sense for a specific action. Use a dash if you want the tool to read values from stdin. This allows you to combine commands using pipes, such as search and lookup actions.
Multi-forest support: You can reference an object from a name context (forest) different from the one you are currently connected to, provided that there is a proper trust relation between them. In this way, for instance, you can add a user from one forest to a cell defined in another forest.
Create a New Cell: When you create a new cell, the tool adds the default primary group (domain users) to the cell. If you add a user to the cell and the user has a primary group different from the default group, which is an atypical case, you must also add the primary group to the cell. The tool does not do this automatically.
Add Users or Groups Across Domains: When you add a user or group to a cell, and if the user or group is in a domain different from the one hosting the cell, you must use an account that has write permissions in the cell domain and at least read permissions in the domain hosting the user or group.
For example, let's say you want to add a user such as CORP\kathy whose primary group is domain users, to a cell in a domain named CORPQA. Two conditions must be met:
- You must be authenticated to the CORPQA domain as a user with administrative rights in the CORPQA domain.
- Your user account must exist in the CORP domain with at least read permissions for the CORP domain.
Since, in this example, the primary group of CORP\kathy is CORP\domain users, you must also add CORP\domain users to the cell in the CORPQA domain.
Automate Commands with a Service Account: To run the tool under a service account, such as a cron job, avoid using krb5 tickets for authentication, especially those cached by the AD Bridge authentication service in the directory. The tickets may expire, and the tool will not renew them. Instead, we recommend that you create an entry for the service account in a keytab file and use the keytab file for authentication.
Work with a Default Cell: The tool uses the Default Cell only when the value of the parameter is the root naming context, such as when you use an expression like --dn DC=corp,DC=example,DC=com to represent corp.example.com.
Options
To view the tool's options and to see examples of how to use them, execute the following command:
/opt/pbis/bin/adtool --help
/
Example
Here is an example with the information that is returned:
[root@rhel5d bin]# ./adtool --help Usage: adtool [OPTIONS] <ACTION> [ACTION_ARGUMENTS] HELP OPTIONS -u, --usage Display brief usage message -?, --help Show this message, help on all actions (-a), or help on a specific action (-a <ACTION>). -e, --examples Display a list of examples. -v, --version Print program version and exit. COMMON OPTIONS -l, --log-level=LOG_LEVEL Acceptable values: 1 (error), 2(warning), 3(info), 4(verbose), 5 (trace) (Default: warning). -q, --quiet Suppress printing to stdout. Just set the return code. print-dn option makes an exception. -t, --print-dn Print DNs of the objects to be looked up, modified or searched for. -r, --read-only Do not actually modify directory objects when executing actions. CONNECTION OPTIONS -s, --server=STRING Active Directory server to connect to. -d, --domain=STRING Domain to connect to. -p, --port=INT TCP port number -m, --non-schema Turn off schema mode AUTHENTICATION OPTIONS -n, --logon-as=STRING User name or UPN. -x, --passwd=STRING Password for authentication. (use '-' for stdin input) -k, --keytab=STRING Full path of keytab file, e.g. /etc/krb5.keytab -c, --krb5cc=STRING Full path of krb5 ticket cache file, e.g. /tmp/[email protected] -z, --no-sec Turns off secure authentication. Simple bind will be used. Use with caution! ACTION -a, --action[=<ACTION>] Action to execute. Type '--help -a' for a list of actions, or '--help -a <ACTION>' for information on a specific action. EXAMPLES Create OU in a root naming context: adtool -a new-ou --dn OU=ADToolOU Create a new account for user ADToolUser in OU=Users,OU=ADToolOU: adtool -a new-user --dn OU=Users,OU=ADToolOU --cn=ADToolUserCN --logon-name=ADToolUser --password=$PASSWD Reset user's password reading the password from ADToolUser.pwd file: cat ADToolUser.pwd | adtool -a reset-user-password --name=ADToolUser --password=- --no-password-expires Enable the user account: adtool -a enable-user --name=ADToolUser Add user ADToolUser to AD Bridge Cell in ADToolOU: adtool -a add-to-cell --dn OU=ADToolOU --user=ADToolUser Search for AD Bridge Cells in root naming context containing user ADToolUser: adtool -a search-cells --user ADToolUser Look up properties of user ADToolUser in cell created in ADToolOU: adtool -a lookup-cell-user --dn OU=ADToolOU --user ADToolUser Look up all attributes of an AD object using filter-based search: adtool -a search-object --filter '(&(Name=ADToolUser))' -t | adtool -a lookup-object --dn - Look up "description" attribute of a user with samAccountName ADToolUser: adtool -a search-user --name ADToolUser -t | adtool -a lookup-object --dn=- --attr=description Remove user ADToolUser from AD Bridge Cell in ADToolOU: adtool -a remove-from-cell --dn OU=ADToolOU --user=ADToolUser Try '--help -a' for a list of actions. Or 'man adtool' for full information on adtool.
Additional commands and options
To get information about the options for each action, use the following syntax:
/opt/pbis/bin/adtool --help -a <ACTION>
List of Actions
Generic Active Directory actions:
--------------------------------
add-to-group - add a domain user/group to a security group.
delete-object - delete an object.
disable-user - disable a user account in Active Directory.
enable-user - enable a user account in Active Directory.
unlock-account - unlock user or computer account.
lookup-object - retrieve object attributes.
move-object - move/rename an object.
new-computer - create a new computer object.
new-group - create a new global security group.
new-ou - create a new organizational unit.
new-user - create a new user account. Requires one of the follow arguments: first-name, last-name or cn
remove-from-group - remove a user/group from a security group.
reset-user-password - reset user's password.
search-computer - search for computer objects, print DNs.
search-group - search for group objects, print DNs.
search-object - search for any type of objects using LDAP filter.
search-ou - search for organizational units, print DNs
search-user - search for users, print DNs.
set-attr - set/un-set attribute.
AD Bridge Cell Management actions:
--------------------------------
add-to-cell - add user/group to a AD Bridge Cell.
delete-cell - delete a AD Bridge Cell.
edit-cell - modify AD Bridge Cell properties.
edit-cell-group - modify properties of a cell's group.
edit-cell-user - modify properties of a cell's user.
link-cell - link AD Bridge Cells.
lookup-cell - retrieve AD Bridge Cell properties.
lookup-cell-group - retrieve properties of cell's group.
lookup-cell-user - retrieve properties of cell's user.
new-cell - create a new AD Bridge Cell.
remove-from-cell - remove user/group from a AD Bridge Cell.
search-cells - search for AD Bridge Cells.
unlink-cell - unlink AD Bridge Cells.
Try '--help -a <ACTION>' for information on a specific action.
Or 'man adtool' for full information on adtool.
Here is an example with the information that is returned:
/opt/pbis/bin/adtool --help -a new-user
Usage: adtool [OPTIONS] (a |-action) new-user <ARGUMENTS>new-user - create a new user account. Requires one of the follow arguments: first-name, last-name or cn
Acceptable arguments ([X] - required):
--dn=STRING DN/RDN of the parent container/OU containing the user. (use '-' for stdin input)
--cn=STRING Common name (CN) of the new user. (use '-' for stdin input)
--logon-name=STRING Logon name of the new user. Sets upn attribute. (use '-' for stdin input) [X]
--pre-win-2000-name=STRING Pre Windows-2000 logon name.
--first-name=STRING First name of the new user.
--last-name=STRING Last name of the new user.
--description=STRING Description of the user.
--password=STRING User's password. (use '-' for stdin input)
--spn=STRING Set new user account service principal name attribute. A comma separated list can be specified (eg. --spn="nfs, http/"). Default is an empty SPN attribute.
--keytab-file=STRING Generate a keytab file for the user. Specify /path/to/file.keytab. Requires --password argument.
--no-must-change-password User is not required to change the password at next logon. If omitted - user must change password at next logon unless "--no-password-expires" option is specified.
--no-password-expires The password never expires.
--account-enabled User account will be enabled. By default the account is disabled on creation.
Active Directory commands
add-to-group
Add a domain user, group, or computer to a security group.
Add TestUser to TestGroup:
/opt/pbis/bin/adtool -a add-to-group --user TestUser --to-group=TestGroup
Add TestGroup2 to TestGroup:
/opt/pbis/bin/adtool -a add-to-group --group TestGroup2 --to-group=TestGroup
Add TestComputer3 to TestGroup:
/opt/pbis/bin/adtool -a add-to-group --computer TestComputer3 --to-group=TestGroup
delete-object
Delete an object.
/opt/pbis/bin/adtool -a delete-object --dn OU=TestOU,DC=testdomain,DC=com
Delete a cell object and all its children if any (--force):
/opt/pbis/bin/adtool -a delete-object --dn OU=TestOU --force
disable-user
Disable a user account in Active Directory.
/opt/pbis/bin/adtool -a disable-user --name=user6
enable-user
Enable a user account in Active Directory.
/opt/pbis/bin/adtool -a enable-user --name=TestUser
unlock-account
Unlock a user or computer account.
/opt/pbis/bin/adtool -a unlock-account --user=aduser
lookup-object
Retrieve object attributes.
/opt/pbis/bin/adtool -a lookup-object --dn CN=RHEL7,CN=Computers,DC=company,DC=com
move-object
Move and rename an object.
Rename AD object OU=OldName and move it to a new location:
/opt/pbis/bin/adtool -a move-object --from OU=OldName,DC=department,DC=company,DC=com --to OU=NewName,OU=TestOU,DC=department,DC=company,DC=com
new-computer
Create a computer object.
/opt/pbis/bin/adtool -d domain.com -n pbisadmin -x XXXXXXXX -a new-computer --dn OU=Test,DC=domain,DC=com --name tst-QAmachine
new-computer --keytab
Create a computer object with a keytab file. An additional option --spn can be used to set the Service Principal Name on the computer object.
/opt/pbis/bin/adtool -a new-computer --dn OU=TestOU,DC=domain,DC=com --name pbisadmin --password XXXXX --keytab-file /tmp/keytab.keytab --spn "Host, NFS"
new-group
Create a global security group.
Create a new group in OU=Groups,OU=TestOu:
/opt/pbis/bin/adtool -a new-group --dn OU=Groups,OU=TestOu --name TestGroup
new-ou
Create an organizational unit.
/opt/pbis/bin/adtool -a new-ou --dn OU=TestOU,DC=testdomain,DC=com
new-user
Create a user account.
Create a user in OU=TestOu:
/opt/pbis/bin/adtool -a new-user --dn OU=TestOU,DC=domain,DC=com --cn testusertwenty --logon-name testuser20 --first-name test --last-name user
new-user --keytab
Create a user account with a keytab file. An additional option --spn can be used to set the Service Principal Name on the user object.
If there is no keytab with an existing account, then password changes that include a keytab location will create a keytab file for that account.
If a keytab exists for an account, then password changes are added to the current keytab.
Note
To create a keytab file, you must use: --no-must-change-password --account-enabled
/opt/pbis/bin/adtool -a new-user --dn OU=TestOU,DC=domain,DC=com --logon-name testusertwentyone --first-name test --last-name user --password XXXXXX --keytab-file /tmp/user.keytab --spn "NFS" --no-must-change-password --account-enabled
remove-from-group
Remove a user, group, or computer from a security group.
Remove TestUser from TestGroup:
/opt/pbis/bin/adtool -a remove-from-group --user TestUser --fromgroup=TestGroup
Remove TestGroup2 from TestGroup:
/opt/pbis/bin/adtool -a remove-from-group --group TestGroup2 --fromgroup=TestGroup
Remove TestComputer3 from TestGroup:
/opt/pbis/bin/adtool -a remove-from-group --computer TestComputer3 --fromgroup=TestGroup
reset-user-password
Reset a user password.
Reset a user's password reading the password from the TestUser.pwd file:
cat TestUser.pwd | /opt/pbis/bin/adtool -a reset-user-password --name=TestUser --password=- --no-password-expires
search-computer
Search for computer objects, print DNs.
/opt/pbis/bin/adtool -d domain.com -a search-computer --search-base OU=Test,DC=domain,DC=com --scope subtree --name tst-QAmachine
search-group
Search for group objects, print DNs.
/opt/pbis/bin/adtool -a search-group --search-base OU=TestOU,DC=domain,DC=com --scope subtree --name testgroupone
search-object
Search for any type of objects using LDAP filter.
Look up all attributes of an AD object using filter-based search:
/opt/pbis/bin/adtool -a search-object --filter '(&(objectClass=person) (displayName=TestUser))' -t | adtool -a lookup-object
search-ou
Search for organizational units, print DNs.
Look up the description attribute of an OU specified by name with a wildcard:
/opt/pbis/bin/adtool -a search-ou --name='*RootOu' -t | adtool -a lookup-object --dn=- --attr= description
search-user
Search for users, print DNs.
Look up the unixHomeDirectory attribute of a user with sAMAccountName TestUser:
/opt/pbis/bin/adtool -a search-user --name TestUser -t | adtool -a lookup-object --dn=- --attr= unixHomeDirectory
Look up the userAccountControl attribute of a user with CN TestUserCN:
/opt/pbis/bin/adtool -a search-user --name CN=TestUserCN -t | adtool -a lookupobject --dn=- --attr=userAccountControl
set-attr
Set or clear a value for an attribute.
Note
Multi-value entries are limited to 100 entries.
To set:
/opt/pbis/bin/adtool -a set-attr --dn CN=$HOSTNAME-u,OU=$HOSTNAME-ou,OU=adtool,OU=automation --attrName gecos --attrValue "setattr"
To clear:
/opt/pbis/bin/adtool -a set-attr --dn CN=$HOSTNAME-u,OU=$HOSTNAME-ou,OU=adtool,OU=automation --attrName gecos
To set multi-value:
/opt/pbis/bin/adtool -a set-attr --dn CN=$HOSTNAME-u,OU=$HOSTNAME-ou,OU=adtool,OU=automation --attrName businessCategory --attrValue "Engineering;QA;Development"
To clear multi-value:
/opt/pbis/bin/adtool -a set-attr --dn CN=$HOSTNAME-u,OU=$HOSTNAME-ou,OU=adtool,OU=automation --attrName businessCategory
AD Bridge cell management commands
add-to-cell
Add a user or group to an AD Bridge Cell.
Add group TestGroup to an AD Bridge Cell in TestOU:
/opt/pbis/bin/adtool -a add-to-cell --dn OU=TestOU,DC=department,DC=company,DC=com --group=TestGroup
delete-cell
Delete an AD Bridge Cell.
Change the default login shell property of an AD Bridge Cell in TestOU:
/opt/pbis/bin/adtool -a delete-cell --dn OU=TestOU,DC=domain,DC=com --force
edit-cell
Modify AD Bridge Cell properties.
/opt/pbis/bin/adtool -a edit-cell --dn OU=TestOU,DC=domain,DC=com --default-login-shell /bin/ksh
edit-cell-group
Modify properties of a cell's group.
Change login shell property of TestUser in a cell created in TestOU:
/opt/pbis/bin/adtool -a edit-cell-group --dn DC=domain,DC=com --group CN=TestGroupOne,OU=TestOU,DC=domain,DC=com --description TestGroup
edit-cell-user
Modify properties of a cell's user.
/opt/pbis/bin/adtool -a edit-cell-user --dn OU=TestOU,DC=domain,DC=com --user CN=testuser,OU=Test,DC=domain,DC=com --uid=123456789
link-cell
Link AD Bridge Cells.
Link cell in OU=TestOU1 to the Default Cell in DC=country:
/opt/pbis/bin/adtool -a link-cell --source-dn OU=TestOU1,DC=department,DC=company,DC=com --target-dn DC=country,DC=company,DC=com
lookup-cell
Retrieve AD Bridge Cell properties.
Find cells linked to an AD Bridge Cell in OU=TestOU,DC=department,DC=company,DC=com:
/opt/pbis/bin/adtool -a lookup-cell --dn OU=TestOU --linked-cells
lookup-cell-group
Retrieve AD Bridge Cell groups.
Find groups that are provisioned to a Cell:
/opt/pbis/bin/adtool -a lookup-cell --dn OU=TestOU,DC=domain,DC=com --groups
lookup-cell-user
Retrieve properties of a cell's user.
Look up login shell property of TestUser in a cell created in TestOU:
adtool -a lookup-cell-user --dn OU=TestOU --user TestUser --login-shell
new-cell
Create a new AD Bridge Cell.
/opt/pbis/bin/adtool -a new-cell --dn OU=Husky,DC=domain,DC=com --default-login-shell /bin/bash
remove-from-cell
Remove a user or group from a AD Bridge Cell.
Remove TestUser from an AD Bridge Cell in TestOU:
/opt/pbis/bin/adtool -a remove-from-cell --dn OU=TestOU,DC=department,DC=company,DC=com --user=TestUser
search-cells
Search for AD Bridge Cells.
Search for cells in a specific location:
/opt/pbis/bin/adtool -a search-cells --search-base OU=department,DC=country,DC=company,DC=com
unlink-cell
Unlink AD Bridge Cells.
Unlink cell in OU=TestOU1 from the Default Cell in DC=country:
/opt/pbis/bin/adtool -a unlink-cell --source-dn OU=TestOU1,DC=department,DC=company,DC=com --target-dn DC=country,DC=company,DC=com
Example
This example shows how to use two authentication methods and how to search Active Directory even though the computer on which the command was executed was not connected to the domain. The account specified in the options is an Active Directory administrative account.
root@ubuntu:/opt/pbis/bin# ./adtool -a search-cells --search-base dc=connecticut,dc=com --logon-as=Administrator --passwd=-
In this case, the successful result would be:
Enter password:
CN=$LikewiseIdentityCell,DC=connecticut,DC=com
CN=$LikewiseIdentityCell,OU=mySecureOU,DC=connecticut,DC=com
Total cells: 2
Updated about 1 month ago