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:
-
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.
-
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 usenew
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 explicitlyselect
objects that are created withcreate
commands. -
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.
-
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
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
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.
joined_*
use adclient
to retrieve data from Active Directory. Those commands are affected by the host computers’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.
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.
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:
-
Open a new file—for example,
my_adedit_script
—in a text editor. -
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
-
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.
-
Type the appropriate commands to create and select a new zone.
create_zone
tree “cn=sample,cn=zones,ou=acme,dc=acme,dc=com” stdselect_zone “cn=sample,cn=zones,ou=acme,dc=acme,dc=com”
-
Type the command to list the current zones to stdout to verify the new zone.
list_zones pistolas.org
-
Type the command to save the zone and quit.
save_zone
quit
-
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
-
Open a shell.
-
Type
adedit
followed by the name of the scriptFor 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
-
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.
-
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
-
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