adtool 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.
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
[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/krb5cc_foo@example.com -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.
/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.