Sun ONE Directory Server Resource Kit 5.2 Tools Reference |
Chapter 32
ilash: The LDAP Administrative ShellThe Lightweight Directory Access Protocol (LDAP) Administrative Shell is a client that provides a scriptable command-line interface to access to a LDAP directory. This chapter provides background on the tool and instructions on how to use it. It contains the following sections:
OverviewThe LDAP Administrative Shell, called ilash, provides commands for performing LDAP operations, navigating a LDAP directory, and importing and exporting data. It allows directory administrators to access server configuration information and develop scripts for managing the directory. The ilash tool is a command-line interface similar to the one provided by a UNIX® shell or the Windows® command prompt. Using ilash, you can navigate the directory hierarchy in much the same way as you navigate the directories in a file system. Similarly, directory locations in ilash can be specified as relative or absolute DNs in the same way that path names are specified.
Note
ilash is based on Tcl (Tool Command Language), an open source scripting language. It includes a complete Tcl interpreter, extended to include commands for accessing the directory. This version of ilash is based on Tcl 8.2. More information on this affinity can be found in The tclsh Shell.
The ilash Environment
The ilash interpreter allows you to conceptually navigate through the directory structure. Like a standard shell, it maintains a record of your current location in the directory and allows you to specify relative locations.
Note
The following sections introduce some of the commands available through ilash. More detailed information can be found in Summary of Commands or in Chapter 33, "ilash Command Reference."
Navigation
The current location is an entry in the directory tree. The ilash interpreter displays this entry’s DN in abbreviated form at the command prompt. As in a file system, the current location is always the default target entry for a command and is abbreviated with a dot ("."). You may also specify an entry relative to the current location. The parent entry of the current location is abbreviated with two dots (".."), and children are referred to by their RDNs (relative distinguished names). However, you must use absolute DNs (distinguished names) to specify siblings or grandparents relative to the current location. Code Example 32-1 shows a simple navigation through the directory. dpwd displays the current working directory as ou=People, dc=Example, dc=com. (Note the abbreviated form at the command prompt.) dcd changes to the parent directory, dshow displays the cn attributes of the entry, and dls displays a list of the RDNs of all first-level children of dc=Example, dc=com.
Specifying Target Objects
Nearly every ilash command requires you to specify the DN of the entry that is the target of the command. Some commands will accept more than one entry as the target. There are several methods available for specifying a target object:
- A fully qualified DN may specify a target anywhere in the directory.
- When an explicit target is not specified, the current directory position is the default target for all ilash commands.
- The "".."" object refers to the parent of the current directory location, and "." refers to the current directory location.
- A relative DN specifies a target in the subtree rooted at the current directory position, and contains a trailing comma (,). For example "uid=bjensen,ou=People," is valid when the current location is "dc=Example,dc=com".
- An abbreviation defined in the user’s .lashconfig file can be used as a target; the command will operate on the entry to which it refers. More information on the .lashconfig file can be found in Configuration Files.
- A valid sequence number will designate its corresponding entry in the current sequence as the target. Specify the sequence name and a dot separator (.) in front of the sequence to refer to an entry in another sequence. Ranges of sequence numbers may be used with commands that accept multiple targets such as dshow. These commands will also accept a mix of ranges and named sequence identifiers, for example:
dshow 1-10 12 mysearch.3-7
Note
More information on sequences can be found in The Sequence.
The Location Stack
The ilash interpreter does not remember previous locations as you move from one entry to another in the directory. However, it does provide a location stack that allows you to store a location and return to it at any time. You can store a location by pushing it onto the stack with the -push option of the dmoveto, dcd, dlist, dls, dshow, and dshowentry commands. You may push any number of locations onto the stack, but you will have to visit them all in reverse order to return to the desired location. (The -pop option of the dmoveto and dcd commands will change the current location to that of the last location pushed onto the stack.) The location stack can be used to create navigational shortcuts back to often visited locations. You may also use the location stack in scripts as a simple way to navigate through the entire directory. More information on the location stack can be found in the option descriptions in Chapter 33, "ilash Command Reference."
‘The World’
A directory server may have several naming contexts that are entire directory trees. The root DSE (directory server entry) is a special entry that represents the server itself and lists the DN of each of its naming contexts. It may be referenced by an empty DN (""). You may change the location to the root DSE and view its contents, but it has no children. The move -pop command on an empty location stack will move to the root DSE. The ilash tool refers to the root DSE entry as The World. The attributes of this virtual entry are the server configuration parameters; they may be viewed with the dstatus command.
Note
There are other directory server configuration entries, for example cn=schema, which contains schema definitions. These may be accessed through their DN as any other entry.
The Sequence
Another navigational aid is called a sequence; it stores the results of directory operations to be used as targets for other commands. Both the dlist and the dsearch command return lists of DNs, all of which are stored in a sequence for later reference. The output from these commands shows the sequence number to the left of the DN for each result. These sequence numbers can then be used as targets of other operations. You may also specify ranges of sequence numbers (for example, 1-10) for commands that operate on multiple entries. The results of several commands may be appended to the same sequence, and duplicate entries will appear only once.
Sequences may be named and kept intact while performing other operations. Entries may be accessed by sequence name and number (for example, myresults.1-10) or you may refer to all entries by giving the sequence name. All of these features make sequences useful in scripts for managing the output and performing complex operations. For more information, see Chapter 33, "ilash Command Reference" and its section dsequence.
The tclsh Shell
The ilash tool is built on top of the Tcl interpreter tclsh, thus it has the full functionality of this command shell. Through the tclsh commands, you have full access to your file system and the resources of your machine. This shell also offers useful functionality for interacting with ilash commands. For example, the history command of the tclsh shell can be used to edit and replay previous commands. However, you do not need to know Tcl to use ilash. Chapter 33, "ilash Command Reference," and the section on Tcl Quoting give you all the information needed to navigate through a directory and view its entries. You can also write Tcl scripts that use ilash commands and execute them with the ilash interpreter. More information on this can be found in The .lashrc File and Bulk Data Scripting Example.
Note
If you find bugs in the ilash scripts or customize them for added functionality, we encourage you to share your work with other users. Please post a message to the iplanet.server.idsrk public newsgroup with your ideas or your code.
Tcl Quoting
The ilash tool uses the quoting rules of the underlying tclsh shell. Like most shell interpreters, you must quote strings and parameters that contain spaces. However, you should be aware of the following rules for Tcl quoting:
- Both braces {} and double quotes "" are used to enclose literal strings that contain spaces, for example:
{ou=Human Resources,dc=Example,dc=com}
"ou=Human Resources,dc=Example,dc=com"- Within braces, commas that do not separate DN components must be escaped with a single backslash \ character:
{o=Example.com\, SARL,c=fr}
- Within double-quoted strings, the same commas must be escaped with double backslash \\ characters:
"o=Example.com\\, SARL,c=fr"
- The backslash is the escape character in Tcl, so pathnames on Windows NT will require double backslashes. They will also require quoting if they contain spaces:
"C:\\Program Files\\iPlanet"
Tcl Resources
The following sources provide more information for learning to use the tclsh shell and programming in the Tcl language.
- “Tcl Developer Xchange” - www.tcl.tk
- “Tcl/Tk Documentation” - www.tcl.tk/doc
- Practical Programming in Tcl and Tk, by Brent Welch (Prentice Hall; ISBN 0130220280).
- Tcl and the Tk Toolkit, by John Ousterhout (Addison-Wesley; ISBN 020163337X).
Directory Server Dependencies
When binding to a server, ilash will attempt to discover the capabilities of the server as defined in the supportedControl and supportedExtension attributes in the root directory server entry (an entry containing server-specific information). When possible, ilash will attempt to make use of these controls and extensions, and some command functionality will not work without them. However, the ilash commands will not use a control or extension unless it is supported. They will return an error if unable to obtain a result by any other means. Use the dstatus -controls -extensions command to view the supported controls and extensions that were discovered.
Importing the Directory Schema
The ilash interpreter is able to detect, import, and interpret the directory schema, using it’s information to format attributes for display and to generate templates for adding entries to any given object class. By default, the schema is not imported, although the bind process will list the schema entries that were detected. Importing the schema is not required; the ilash tool will function normally without it. You may want to import the schema with the following command if you use the dadd command to compose new entries:
dschema "cn=schema" -import
You may also import any other sub-schema definitions as needed.
Multithreading
Many ilash commands, such as dshow, accept multiple targets. When possible, ilash will attempt to issue multiple operation requests in parallel to the server. The degree of parallelism can be set by the maxconns parameter in the configuration files. (See Configuration Files.) Because simultaneous requests need separate connections, the ilash tool will rebind multiple times to achieve the parallelism. If sequential operation or single binding is required, the maxconns parameter should be set to 1. By default, ilash will limit itself to 10 simultaneous requests to a server.
Command UsageThis section describes how to launch the ilash shell as well as providing details about its startup commands. Other directory commands available from the shell and in ilash scripts are described in detail in Chapter 33, "ilash Command Reference."
Caution
You should never specify the -password option on the command-line because it exposes the password itself to other users through the ps command (list of processes) on UNIX systems. Specify the password in protected configuration files or give the password interactively when prompted by the ilash tool.
The syntax of the ilash command on the command-line takes the following forms:
ilash -noconnect
ilash [-file TclScript] ...
ilash dbindOptions
Where:
- -noconnect launches the command interpreter without binding to a directory server. You should then use the dbind command to connect and bind to a server interactively.
- -file TclScript will interpret the given file as an ilash Tcl script. This script must also use the dbind command to establish a connection before being able to access the directory with other ilash commands.
- dbindOptions refers to the start-up options described in Table 32-1. They are the same options as those of the dbind command, as the ilash tool attempts to establish a connection as soon as it is launched. You may omit any of the dbindOptions needed to connect and bind to a directory if they are defined in the configuration files. (The initial binding and run-time behavior of the tool is fully customizable through configuration files, as described in Configuration Files.)
Table 32-1 Start-up Options for the ilash Tool
Option
Purpose
-call URL-alias
Specify the URL or alias name of the directory server target for the connection. Alias names are defined in the ilash configuration files. (See Configuring ilash.) The default server is: ldap://localhost:389/.
-user bindDN
Specify a bind DN for accessing your directory, usually in double quotes ("") for the shell. If the bind DN and its password are omitted, the tool will use anonymous binding. The access permissions of the bind DN determine what entries are visible.
-v2
Perform an LDAP v2 bind. Use this options for servers that do not support LDAP v3. The default is to perform an LDAP v3 bind.
-noschema
Specify that the ilash interpreter should not import the schema from the directory server. Some commands offer functionality that depends on the imported schema. By default, the ilash tool will import the schema when it binds to a directory.
-nomove
Specify that the initial location in the directory should be the root DSE. Otherwise, it will be the default naming context defined by the server.
Other Commands
The commands for interacting with the directory server are listed in Summary of Commands and are fully described in Chapter 33, "ilash Command Reference." While running ilash, you also have access to Tcl commands that allow you to navigate the file system as well. This is discussed in The tclsh Shell.
Exiting ilash
To exit ilash, type quit or use the dunbind command.
Configuring ilashThere are three files that control the operation of ilash. The files contain configuration parameters to define aliases, set preferences and specify default command options. They allow you to set up global and personal defaults. None of the files are mandatory; all functionality of the ilash commands is available through their command-line options. The files discussed in the following sections are:
Configuration Files
The system and user configuration files contain default information concerning remote servers, authentication and other general configuration options. The system configuration is located in the DSRK_base/etc/ directory and is named system.lashconfig. The user’s configuration file is located in their home directory and is named .lashconfig.
Both files contain simple parameter definitions that are loaded into the ilash interpreter. [They may also contain comments on lines beginning with a hash (#).] On startup, ilash will first read the system configuration file, if it exists, and then the user’s configuration file, if it exists. User specifications and server specifications defined in a user’s configuration will take precedence over those same parameter definitions in the system configuration.
In general, information about servers and usage restrictions should be configured in the system configuration file. For example, a system administrator could set the system configuration file so that passwords are never sent openly during authentication. Certain security parameters such as password protection may not be overridden by users. Bind credentials and personal preferences for command defaults are more appropriate in the user’s configuration file.
Caution
Both system and user configuration files might contain passwords in plain text and should be protected appropriately. For example, on UNIX platforms, you should make these files unreadable to others.
The configuration files contain five types of parameters discussed in the following sections:
Global Parameters
Most of the global parameters define a default value for bind operations. Each parameter is given as a pair on a separate line:
parameterName value
The parameterName is case insensitive, and the value should be quoted according to the rules described in Tcl Quoting. Some configuration parameters do not require a value; they take effect simply when they appear in a configuration file. Table 32-2 is a listing of the global parameters.
Table 32-2 Global Parameters for ilash Configuration Files
Parameter
Effect on the ilash Environment
defaultserver URL-alias
Specify the URL or alias name of the default directory server for all connections. When giving an alias name, it must be defined later in the same file.
authentication method
Define the default authentication method to use when binding. The recognized methods are none, simple, md5 (CRAM-md5), hd (http digest-md5), and tls (transport layer security). You must specify this parameter with a value other than none to automatically bind with the username and password values.
username DN
Specify the full distinguished name to use for authentication. This username will be presented only if the authentication method is defined with a value of simple, md5, or tls.
password password
Give the password to be presented when authenticating using methods that require a password.
protect-password
Force binds to use encryption so that passwords will never be sent in the clear. The dbind command will refuse to perform any connection with simple or no authentication. This flag has no counterpart, so setting it in the system configuration will enforce the policy for all users.
protect-data
Force binds to use encryption and authentication so that passwords and data transferred during LDAP operations are secure. The dbind command will refuse to perform any connection without TLS authentication. This flag has no counterpart, so setting it in the system configuration will enforce the policy for all users.
use-tls
Specify that the dbind command should establish a TLS connection by default. This flag has no counterpart, so setting it in the system configuration will enforce the policy for all users.
tls-verify
Force the ilash client to check the server's TLS credentials and abort the connection if the server cannot be verified. This flag has no counterpart, so setting it in the system configuration will enforce the policy for all users.
ssl_key filename
Specify the absolute path of the file containing a user’s SSL private key. This and all other SSL parameters may be set in the system configuration if all users share a common identity for secure operations.
ssl_cert filename
Specify the absolute path of the file containing the user's SSL certificate.
ssl_cafile filename
Specify the filename of the SSL CA certificate file for verification of the LDAP server's certificate.
ssl_capath filename
Specify the absolute path of the SSL CA certificate directory for verification of the LDAP server's certificate.
ldapversion version
Specify the default LDAP version to use for connections. The version should be either 2 or 3.
local_dit DN
Specify the default location in the directory from which navigation should begin after all connections.
maxconns number
Specify the maximum number of simultaneous operations to be issued to a server. When possible, the ilash tool will create multiple connections and perform operations in parallel.
notype attributeName ...
Give a list of attributes that should not be displayed unless explicitly requested.
service LDAP-specificOptions ...
Give a list default options for controlling LDAP operations. This parameter defines global default options for all commands listed in LDAP-Specific Options. These defaults may be overridden by individual command defaults.
DN Aliases
DN aliases define an abbreviation for a directory entry. Each alias is given on a separate line with the following format:
alias distinguishedName
The distinguished name should be the full DN of the entry, for example:
employees ou=People,dc=Example,dc=com
The DN alias may then be used as the target entry or target location for ilash commands. For example, the following command will display the DN of all entries that are immediate children of the ou=People,dc=Example,dc=com entry:
dlist employees
Command Defaults
All ilash commands may be given default parameters to override their built in defaults. A command default has the effect of specifying the given options every time the command is invoked. Each command default is given on a separate line with the following format:
commandSpecifier option ...
A commandSpecifier identifies the ilash command and its synonyms to which these options will apply. Table 32-3 lists the available command specifiers and the corresponding ilash command to which it refers. Options include any values that they require and should be enclosed in double quotes (""). There can be any number of options, for example:
search "-filter objectclass=*" "-norelative" "-type cn" "-show"
This command default will make all search results contain the full DN and the single cn attribute. By specifying a default filter, the dsearch command may be invoked without any options within the ilash interpreter.
Note
Command defaults override the notype and service parameters that also define default option for most commands. They can in turn be overridden by any option that the user specifies on the command-line.
Table 32-3 Command Specifiers for use with Command Default Parameters
Command Specifier
ilash Command
add
dadd
bind
dbind
bulkclean
dbulkclean
bulkload
dbulkload
compare
dcompare
delete
ddelete drm
list
dlist dls
modify
dmodify dmod
modifyrdn
dmodifyrdn dmodrdn
moveto
dmoveto dcd
search
dsearch
showentry
dshow dshowentry
showname
dshowname dpwd
status
dstatus
unbind
dunbind dquit quit
Server Specifications
A server specification contains default values that are specific to a connection to the given server. Whereas global parameters apply to any connection, the parameters in a server specification will take precedence only when binding and interacting with the named server. Server specifications have the following format:
server URL {
alias name
parameter value
...
}All of the lines within server specification are optional, although you should specify either an alias or local parameters. When the alias is defined, the name may then be used instead of the URL when invoking the dbind command. The parameter value pairs may be configuration parameters, DN aliases, or command defaults. For example:
server ldap://test.example.com:5150/ {
alias test
authentication simple
username "cn=directory manager"
password testtest
add "-template /usr/tools/template"
}This server specification will simplify binding by allowing you to connect with the following command:
dbind -call test
The server alias may also be used in the global parameter defaultserver to further simplify the dbind command-line.
User Specifications
A user specification contains default values for parameters when authenticating and later bound as the given DN. User defaults override server defaults and global defaults for the same parameter, DN alias name, or command specifier. User specifications have the following format in the configuration files:
user DN {
parameter value
...
}User specifications are more common in personal configuration files so that users may set up their preferences. For example:
user "uid=bjensen,ou=People,dc=example,dc=com" {
password zyG3dw13
protect-password
add "-draft /home/bj/.draft" "-template /usr/tools/template"
}This specification gives a password to be used when binding as bjensen and also specifies that the password should never be sent in the clear. User specifications are not cumulative with server specifications so the command default for the dadd command must redefine the -template option value, if desired.
The .lashrc File
If you wish to further initialize the environment of the ilash interpreter, you may create a .lashrc file in your home directory. This initialization script contains ilash and Tcl commands that will be executed as the first commands of the ilash interpreter. It is a Tcl script file that will be sourced after the tool has read the configuration files and before performing the initial bind. Any valid Tcl commands may appear in the .lashrc file in order to, for example, set variables or define procedures. This file may also contain the line:
set auto_noexec {}
The effect of this line is to prevent the ilash interpreter from invoking commands it doesn’t recognize. By default, ilash relies on the Tcl shell program, tclsh, to invoke any unrecognized command as a system command. This default behavior allows you to access the file system and other resources through the usual commands.
Summary of CommandsThe following sections summarize the ilash commands grouped by task categories. The tables also list alternate command names. All commands and their options are described in more detail in Chapter 33, "ilash Command Reference."
LDAP Commands
The LDAP commands are the ilash commands for standard directory operations.
Table 32-4 LDAP Command Equivalents of the ilash Tool
Command
Effect on the Directory
Perform an LDAP bind operation.
Alias for the dbind -nomove -rebind command.
Invoke an extension, given by its OID, on the server.
Perform an LDAP search operation using a filter.
Perform an LDAP compare operation on an attribute value.
Compose an entry in LDIF and perform an LDAP add operation.
Perform an LDAP modify operation to add, modify or remove attributes.
Perform an LDAP modify-RDN (relative distinguished name) operation.
Move entries from one subtree to another (“reparent”) or move entire subtrees.
Perform an LDAP delete operation with the option to delete subtrees.
Close the connection to the current directory and optionally exit the ilash tool.
Directory Navigation
The navigation commands allow you to view the contents of a directory in the same way that standard shells or command interpreters allow you to navigate through a file system. The navigational aids also include commands for accessing directory configuration information such as the schema and supported controls.
Table 32-5 Directory Navigation Commands of the ilash Tool
Command
Effect on the ilash Environment
Display the full DN of the current location or of the specified target object.
List the attributes of the entry at the given location.
List the RDNs of all first-level children of a given entry.
Change the current directory location of the ilash interpreter.
Give information about the connection to the current directory server.
List the schema entries associated with an object or import schema definitions.
Manage the existing sequences and run commands using their entries.
Display the list of all ilash commands and their brief description.
Bulk Data Commands
The bulk data commands provide facilities for managing bulk data in the directory. The dbulkclean command is actually a synonym for ddelete.
Table 32-6 Bulk Data Commands of the ilash Tool
Command
Action
Import entries into the directory from either an LDIF text file or a CSV (comma-separated values) format file.
Export entries from the directory as LDIF text to a file or the standard output.
Bulk Data Scripting ExampleThe Bulk Data Commands of the ilash tool can be used interactively or automated through a simple script. The following code example gives a sample ilash script that bulk-loads data from a CSV data file into the directory location at ou=People,dc=Example,dc=com. This section shows how to perform simple file manipulation, call ilash commands, and output the result.
To customize the file, you would set the base and ou variables to the directory location where the data is to be loaded, and the csvdata and template variables to the correct paths for the data and template files. This script uses the template and data file given as an example in dbulkload of Chapter 33, "ilash Command Reference."
Note
For further help with Tcl scripting, see the references in Tcl Resources.
Code Example 32-2 Sample ilash Script for Bulk-Loading
#!/opt/iPlanet/bin/dsrk52/ilash -file
# allow username or other bind flags to be specified
# on the command-line
eval [concat dbind $argv]
set base "dc=Example,dc=com"
set ou "ou=People,"
set csvdata "/usr/tools/data.csv"
set template "/usr/tools/template"
proc bulkload_ou {base ou csvdata template} {
# move to the level where we want to create the ou
puts "Moving to $base"
dmoveto $base
# create a draft for the ou
set filename [file join [glob ~] .scriptdraft]
set fd [open $filename w]
puts $fd "objectclass: top"
puts $fd "objectclass: organizationalUnit"
close $fd
# add the ou entry and move there
puts "Creating $ou"
dadd $ou -draft $filename -noedit
dmoveto $ou
# perform the bulkload
puts "Bulkloading entries into [dshowname -ufn]"
puts [dbulkload -csvdata $csvdata -template $template
-overwrite]
}
puts "Script started at [clock format [clock seconds]]"
puts "-------------------------------------------------"
catch {bulkload_ou $BASE $OU $CSVDATA $TEMPLATE} result
puts $result
puts "-------------------------------------------------"
puts "Script ended at [clock format [clock seconds]]"