Getting Started with ADEdit

This chapter describes ADEdit’s basic syntax, shows the typical logic flow used to handle Server Suite objects, and describes in detail the steps in that logic flow using simple examples.

Starting ADEdit for the First Time

The ADEdit application (adedit) and accompanying library of Tcl procedures (ade_lib) are installed automatically when you install the Server Suite Agent on a UNIX, Linux, or Mac OS X computer. Therefore, both the application and the library are immediately available on any Server Suite-managed computer. You are not required to join the domain before using ADEdit for the first time.

To start a new interactive ADEdit session, type adedit in a standard shell after logging on to your computer. A new angle bracket (>) prompt indicates that you are in an interactive ADEdit session. For example:

[myprompt]$ adedit>

Anyone can launch ADEdit. However, only users who have sufficient privileges can modify Active Directory objects and Server Suite-specific data.

Basic Command Syntax

ADEdit includes a Tcl interpreter and uses Tcl syntax. However, ADEdit commands have their own syntax within the Tcl syntax. Like other Tcl commands, ADEdit commands are always completely lowercase. ADEdit does not recognize commands with uppercase characters.

Arguments and Options

An ADEdit command works very much like a UNIX command. Depending on the command, you might be required to specify one or more arguments. An argument is typically a variable that follows the command name to provide data that controls the operation to be performed. In some cases, values for the variables are required for a command to execute. In other cases, variables might be optional. The reference information for individual commands indicates whether arguments are required or optional. In most cases, however, arguments must be entered in the order specified for the command.

In addition to arguments, ADEdit commands may or may not have options. Options must precede a command’s arguments. Each option is a single word preceded by a hyphen (-) such as -write. Options can also have their own arguments. If an option takes an argument, it must immediately follow the option.

Options are used to control specific operations of ADEdit commands. For example:

>bind -gc acme.com administrator #3gEgh^&4

In this example, the bind command has an option -gc that specifies a global catalog domain controller. Three arguments follow the option. The first argument is required and specifies the domain to which to bind. The second and third arguments are optional and provide a use name and password to be used for binding.

Command Execution and Results

Like most UNIX commands, ADEdit produces no output or return value if a command executes successfully. Only commands that are defined to return a result produce output when an operation completes successfully. If a command fails, however, ADEdit notifies you of an error in execution and reports the general reason for failure. For example, you might see an error message indicating the wrong number of arguments or a connection problem.

Some commands return results as a Tcl list that other commands in a Tcl script can use. Other commands output results directly to standard output (stdout) where the results are displayed in the shell. You can redirect a command’s stdout output to a file or other destination, if desired.

Commands that return Tcl lists start with get followed by an object type (get_zone_users, for example) and return the list of the objects matching the specified object type that are stored in Active Directory. Because other commands can use the Tcl list to act on the returned data, the get commands are especially useful for writing scripts.

Commands that send data to stdout start with list followed by an object type (list_zone_groups, for example) and return the list of the objects matching the specified object type that are stored in Active Directory for the currently selected context. Because the list goes to stdout, the list commands are especially useful for displaying data in interactive sessions as a script executes.

Using Command Abbreviations

Most ADEdit commands have an abbreviation that you can use in place of the full command name. For example, the command list_zone_users has the abbreviation lszu. You can use either the full command name or the abbreviation for any command.

Using the Command History

ADEdit in an interactive session retains a history of previously entered commands. You can visit the command history by pressing the up arrow key to go back in the history and the down arrow key to go forward. Press Enter to run the current command.

ADEdit retains its command history across sessions, so if you quit ADEdit and restart it, you can still visit commands entered in the previous session. The command history has a 50command capacity. Once full, the history drops old commands as you enter new commands.

Using the Help Command

The ADEdit help command provides brief information about ADEdit commands. If you enter help in ADEdit followed by a command or command abbreviation, help returns information about that command, including its syntax.

You can use the wildcard character * to specifying any number of variable characters or ? to specify a single variable character within a command string following the help command. The help command returns help text for all commands that match the wildcard string. For example, the following command returns help for all commands that start with get.

> help get*

Learning to Use ADEdit

You can use ADEdit interactively to run individual commands or to execute scripts directly. You can use ADEdit commands in scripts that you convert into executable files that can be execute outside of ADEdit sessions. Because scripts can automate and simplify many administrative tasks, it is important for you to know how to combine ADEdit commands in the proper sequence to get the results you are looking for.

Before you begin writing scripts that use ADEdit commands, you should be familiar with the most common logical flow for managing Server Suite-specific and Active Directory objects.

The following illustration provides an overview of the logical process.

As illustrated, the typical logic flow in a ADEdit script follows these steps:

1. Bind ADEdit to one or more domains within a forest.

   The domains to which you bind will define the logical boundaries within which all subsequent commands work.

2. Select an existing Active Directory object or create a new object with which to work.

   You can use select commands to retrieve existing object from Active Directory and store them in memory. You can use new commands to create new objects of a specified type and store them in the ADEdit context as the currently selected object.

   There are also create commands that create a new objects in Active Directory without putting the object in the ADEdit context. You must explicitly select objects that are created with create commands.

3. Get or set values for a selected object.

   After you select an object to work with and it is stored in memory—that is, the object is in the ADEdit context—you can read field values to see their current settings or write field values to change their current state.

4. Save the selected object and any settings you changed.

   If you modify an object in memory or you have created a new object in memory, you must save it back to Active Directory for your changes to have any effect.

As these steps suggest, ADEdit is very context-oriented. The bindings you set and the objects you select determine the ADEdit current context. All commands work within that context. If you select a zone, for example, subsequent commands use the selected zone as the context in which to add new zone users, zone computers, and zone groups.

Outside of scripts that perform the most common administrative tasks, you might use ADEdit commands differently and without following these steps. For example, you might use ADEdit to convert data from one format to another, view help, or get information about the local computer without following the typical logic flow, but those tasks would be exceptions to the general rule.

Binding to a Domain and Domain Controller

ADEdit must bind to one or more domains before any ADEdit commands that affect Active Directory objects will work. When you execute the bind command, you specify the domain to which to bind. You can also specify a user name and password for the bind operation to provide authentication.

The domain can be any domain in the current forest. The ADEdit host computer does not have to be joined to a domain to bind to and work with a domain. A binding command can be as simple as:

>bind acme.com

If you specify a domain with no options, ADEdit automatically finds the domain’s closest, fastest domain controller. Options can narrow down the choice of domain controllers. The -write option, for example, specifies that you want ADEdit to choose a writable domain controller. The -gc option specifies that ADEdit use the global catalog (GC) domain controller. You can use both options to choose a writable GC domain controller, for example:

>bind -write -gc acme.com

Alternatively, you can name a specific domain controller as a part of the domain name:

>bind dcserv1@acme.com

Active Directory is a multi-master LDAP system. Changes made at any one domain controller eventually propagate to all other domain controllers in the domain (if they’re universal changes). If any administration tools—such as Active Directory Users and Computers, Access Manager, or other instances of ADEdit—bind to the same domain controller, changes made by any one of the tools are immediately available to the other tools without waiting for propagation.

Authentication

If no credentials are provided with a bind command, ADEdit gets its authentication data from the Kerberos credentials cache if one exists. Alternatively, you can provide a user name or both a user name and password. For example:

>bind acme.com administrator {e$t86&CG}

Notice that the password is enclosed in braces ({}) to ensure that Tcl handles it correctly. Without the braces, Tcl syntax will automatically substitute for some characters such as the $ used in the password. For example, a dollar sign specifies the contents of a variable in Tcl. Enclosing a string in braces guarantees that Tcl will not try to substitute for any of the characters in the string. Tcl drops the braces when it passes the string on.

You can also use the credentials of the ADEdit’s host computer by using the -machine option:

>bind -machine acme.com

Whatever credentials you use, they must be for an account on the Active Directory domain controller with enough authority to read from and make changes to Active Directory objects in the domain. Without the proper authority, ADEdit commands that use Active Directory won’t work.

Binding Scope and Persistence

Binding to a single domain allows ADEdit commands to work on Active Directory in that domain. You can bind to multiple domains to allow ADEdit commands to work on more than one domain. To bind to multiple domains, you simply use multiple bind commands, one for each domain.

Once bound to a domain, ADEdit remains bound to that domain until another binding occurs to the same domain (possibly using a different authentication or specifying a different domain controller) or until the current interactive session or executing script ends. Binding might also end if the current context is popped and ADEdit reverts to an earlier context without the binding.

Binding and Join Differences

The ADEdit bind operation is not the same as having the ADEdit host computer join an Active Directory domain. A join is the adclient connection to Active Directory for the host computer. A computer is only allowed to join one domain. A bind is an ADEdit connection to Active Directory, and it can be to more than one domain in the forest. The binding is completely independent of the host computer’s joined domain.

A few ADEdit commands that start with joined_* use adclient to retrieve data from Active Directory. Those commands are affected by the host computer’s joined domain because they require adclient to be connected to Active Directory and can only get data from the joined domain.

Controlling Binding Operation

You can control the way ADEdit’s binding to Active Directory operates. The set_ldap_timeout command sets a time interval for ADEdit’s LDAP queries to execute by Active Directory. ADEdit considers a query that doesn’t execute by the time-out interval as failed.

Selecting an Object

ADEdit manages Server Suite information by working with the objects in Active Directory. The Server Suite-specific object types are:

• Zones
• Zone users
• Zone computers
• Zone groups
• Roles
• Role assignments
• Privileged UNIX command rights
• PAM application rights
• NIS maps

However, you are not limited to using ADEdit only for managing Server Suite-specific object types. You can also use ADEdit commands to work with generic Active Directory objects, including computers, users, groups, and other classes.

Selection Commands

The ADEdit object select commands have the form select_xxx where xxx is an object type. When you select an object (select_zone, for example), ADEdit looks for the object specified in Active Directory and retrieves it to store the object in the current context.

Each select command is tailored to the type of object it retrieves. As an example, after binding to acme.com, you can use a get_zones command to list the zones in the bound domain, then use a select_zone command to select the zone you want to work with:

 >get_zones acme.com  
 {CN=default,CN=Zones,CN=Acme,CN=Program Data,DC=acme,DC=com}
 {CN=cz1,CN=Zones,CN=Acme,CN=Program Data,DC=acme,DC=com}
 {CN=cz2,CN=Zones,CN=Acme,CN=Program Data,DC=acme,DC=com}
 {CN=global,CN=Zones,CN=Acme,CN=Program Data,DC=acme,DC=com}
 >select_zone {CN=global,CN=Zones,CN=Acme,CN=Program Data,DC=acme,DC=com}

As this example illustrates, each zone is list by its distinguished name (DN) and you use the distinguished name to identify the zone you want to use.

Selection as Part of Context

Once an object is selected, it resides in memory (context) with all attendant field values. Further ADEdit commands can examine and modify the object in context.

ADEdit keeps only one selected object of each type in context at a time. If you select or create another object of the same type, the new object replaces the old object in memory without saving the old object to Active Directory. ADEdit can and does keep multiple objects in context, but each object must be a different type.

A currently selected object often affects work on other objects types, especially the currently selected zone. For example, if you select a zone user, you must first select a zone so that ADEdit knows in which zone to look for the zone user. If you don’t first select a zone, you can’t select and work on various zone objects such as zone users, zone computers, and zone groups. Knowing your context as you work on objects is important.

Persistence

A selected object stays selected until another object of the same type replaces it or until the current interactive session ends or executing script ends. When an ADEdit session ends, all selected objects are removed from ADEdit’s memory. In most cases, you must explicitly save changes to objects in memory to ensure the changes are stored in Active Directory.

Creating a New Object

You can use ADEdit new_xxx commands, where xxx is the object type, to create new objects to work on instead of selecting existing objects. When you use new_xxx commands, commands, ADEdit creates an object of the specified type and stores the object as the currently selected object of that type in ADEdit’s current context.

In most cases, ADEdit does not provide default values for a new object’s fields. If you create a new object, its fields are empty. You can use the ADEdit set_xxx commands to set values for the fields that are specific to each object type.

Here are some notes about creating objects in ADEdit:

• Creating a new zone works differently than all other object types: ADEdit does not create a new zone in memory. ADEdit creates new zones directly in Active Directory and fills in zone fields with default values. After you create a zone, you must then select it to examine and modify it.
• ADEdit cannot create AIX extended attributes in a Microsoft Services for UNIX (SFU) zone (Ref: CS-25392c).
• Some non-alphanumeric characters are valid for Windows user or group names and are converted to underscore ("_") when changed to be UNIX names in the Access Manager, but cannot be used in adedit. (Ref: IN-90001) The following characters cannot be used in adedit: \ ( ) + ; " , < > =

Examining Objects and Context

The ADEdit context is a combination of current bindings and currently selected objects. You can examine the properties of currently selected objects using ADEdit get_xxx or list_xxx commands, where xxx is an object type. For example, you can use the get_roles or list_roles command to see a list of roles in the current zone.

Getting Field Values for Objects

You can also use get_xxx_field commands to retrieve field values for different types of objects. For example:

>select_zone_user adam.avery@acme.com
>get_zone_user_field uname
adam

In this example, ADEdit retrieves the value of the field uname—in this case, the UNIX user name field—for the currently selected zone user adam.avery@acme.com.

Getting Current Context Information

You can examine ADEdit’s current context at any time using two different commands: the show command and the get_bind_info command.

The show command returns all bindings and selected objects in the current context. For example:

 >show  
 Bindings:  
     acme.com: calla.acme.com  
 Current zone:  
     CN=global,CN=Zones,CN=ACME,CN=Program Data,DC=acme,DC=com  
 Current nss user:  
     adam.avery@acme.com:adam:10001:10001:%{u:samaccountname}:%{home}/%{user}:%{shell}:

You can use optional arguments to limit the information the show command returns.

The get_bind_info command returns information about a bound domain. When you use this command, you specify the information you want to retrieve, such as the domain’s forest, the name of the current domain controller, the domain’s security identifier (SID), the functional level of the domain, or the functional level of the domain’s forest. For example:

>get_bind_info acme.com server
adserve02.acme.com

In this case, ADEdit returns the name of the bound server for the domain acme.com.

Modifying or Deleting Selected Objects

Once an object is selected and residing in the ADEdit context, you can modify its fields using the ADEdit set_xxx_field commands, where xxx is the object type. These commands allow you to specify a field name and a field value. For example:

>select_zone_user adam.avery@acme.com
>set_zone_user_field uname buzz

This example selects the zone user adam.avery@acme.com and sets the uname field for the zone user—the UNIX user name—to buzz. The field is set to the new value only in memory., however. You must save the object before the new field value is stored in Active Directory and takes effect within the object’s domain. For example:

>save_zone_user

Deleting an Object

You can delete a currently selected object using the ADEdit delete_xxx commands, where xxx is the object type. When you delete an object, it is deleted from both memory and Active Directory. For example:

>select_zone_user adam.avery@acme.com
>delete_zone_user

This example deletes the currently selected zone user, adam.avery@acme.com, from the he ADEdit context so there’s no longer a selected zone user. The command also deletes the zone user object associated with the user adam.avery@acme.com so there’s no longer a zone user by that name in Active Directory.

There is no undo for a delete command. Once the object is deleted from Active Directory, you must recreate it if you want it back. Be especially careful if you set up an ADEdit script to delete multiple objects.

Saving Selected Objects

Any new or modified object in ADEdit’s context has no effect until you save the object back to Active Directory. You do so using a save_xxx command where xxx is the object type. For example:

>save_zone

This example saves the currently selected zone object back to Active Directory along with any field values that have been modified since the zone was selected.

Saving an object does not deselect the object. It remains the selected object in memory so that you can further read and modify it.

Pushing and Popping Context

There are times when you may want to save ADEdit’s current context, change it to a new context to work on different objects in different domains, and then revert back to the original context. This is particularly true when writing Tcl scripts with subroutines, where you may want to feel free to complete a completely new context without altering the context of the calling code.

ADEdit offers a push and a pop command to save and retrieve contexts to a stack maintained in memory. push saves the complete current context—all of its bindings and selected objects—to the stack. Subsequent push commands save more contexts to the top of the stack, pushing the older contexts further down the stack, allowing for nested subroutines.

pop reads the context from the top of the stack and restores it to memory as the current context. pop also removes the restored context from the stack. Subsequent pop commands pop more contexts off the stack until the stack is empty, at which point pop returns an error.

Creating ADEdit Scripts

You can combine ADEdit commands into scripts that perform many common administrative tasks, such as creating new zones, adding users to zones, or pre-creating computer accounts. After you create a script, you can execute it from a shell that calls adedit or convert it to an executable file that can run directly from the command line.

Starting with a Simple Script

If you are new to scripting, Tcl, or both, you might want to experiment first with a few simple commands before trying to develop scripts that perform administrative tasks. The steps in this section are intended to help you get started.

If you are already familiar with scripting languages or with using Tcl, you might want to skip ahead to the discussion of the sample scripts or directly to the command reference.

To write a simple ADEdit script:

1. Open a new file—for example, my_adedit_script—in a text editor.

2. Type the following line to set up the adedit environment and include the ADedit Tcl library:

   #!/bin/env adedit
   package require ade_lib

   If your version of Linux or UNIX has the env command in a location other than the /bin directory, modify the first line to specify that directory. For example, another common location for the env command is /usr/bin. In this case, you would type:

   #!/usr/bin/env adedit
   

3. Type an appropriate bind command to identify the Active Directory domain or domains to use.

   bind pistolas.org maya.garcia {$m1l3s88}

   Depending on whether you are going to run this script interactively or as an executable file, you might include or exclude authentication information.

4. Type the appropriate commands to create and select a new zone.

   create_zone tree “cn=sample,cn=zones,ou=acme,dc=acme,dc=com” std 
    select_zone “cn=sample,cn=zones,ou=acme,dc=acme,dc=com”

5. Type the command to list the current zones to stdout to verify the new zone.

   list_zones pistolas.org

6. Type the command to save the zone and quit.

    save_zone  
    quit

7. Save the text file and execute it using ADEdit or as an executable file.

   After you have tested the basic script, you edit it to create new zones, make a zone a child zone, add new zone computers, groups, or users. for example, you might add lines similar to these:

    new_zone_user AD_user_UPN
    set_zone_user_field field value
    save_zone_user
    list_zone_users

   If your sample script creates and selects a zone successfully, you should delete or rename the zone each time you iterate through the execution.

The following is a sample of what the simple script might look like:

#! /bin/env adeditpackage require ade_lib  
bind pistolas.org maya.garcia {$m1l3s88}  
create_zone tree "cn=test6,cn=zones,ou=acme,dc=pistolas,dc=org" std  
select_zone "cn=test6,cn=zones,ou=acme,dc=pistolas,dc=org"  
set_zone_field parent "cn=US-HQ,cn=zones,ou=acme,dc=pistolas,dc=org"  
list_zones pistolas.org  
save_zone  
new_zone_user tim@pistolas.org  
set_zone_user_field uname tim  
set_zone_user_field uid 81000  
set_zone_user_field gid 81000  
set_zone_user_field gecos "Tim Jackson, Accounting"  
save_zone_user  
list_zone_users  
quit

Executing an ADEdit Script using ADEdit

You can execute ADEdit script by invoking ADEdit on the command line or by making the script an executable file and invoking the script itself directly from the command line.

To execute an ADEdit script by invoking ADEdit on the command line

1. Open a shell.

2. Type adedit followed by the name of the script

   For example, if the name of the script is my_adedit_scipt and it is the current working directory, type:

   adedit my_adedit_script

   If the script isn’t in the current working directory, specify the path to the script and any arguments if the script requires any.

Running an ADEdit Script as an Executable from the Command Line

You can run an ADEdit script without invoking ADEdit first by making the script an executable file.

To run an ADEdit script as a UNIX-executable file

1. Verify the script begins with the following lines:

     #!/bin/env adedit  
     package require ade_lib

   The script reads it as a comment, however UNIX or Linux will use it to find and execute ADEdit and then execute the rest of the script.

2. Use chmod to make the file executable.

   For example, if the name of the script is my_adedit_scipt and it is the current working directory, type:

   chmod +x my_adedit_script

3. Make sure the file’s directory is listed in your PATH environment variable if you want to be able to execute the file from any directory.

   Alternatively, modify the script to include the full path to adedit. For example:

   #!/bin/env /usr/bin/adedit

   Once set up this way, you can simply enter the script’s file name in a shell and have the script execute as a command.

   /my_adedit_script

Running an ADEdit Script as a Shell Script

You can also run the script as a shell script. In this case, the script file would have the .sh suffix and would contain the following lines at the beginning of the file:

#!/bin/sh  
# \  
exec adedit "$0" ${1+"$@"}  
package require ade_lib