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.

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        
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/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.
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.