Chapter 32 ilash: The LDAP Administrative Shell

The 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:

Overview

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

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.

Navigation


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.


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

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



Tip	Relative DNs may not be combined with the parent ".." notation.

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.

The Sequence


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.

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.

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:

Tcl Resources

The following sources provide more information for learning to use the tclsh shell and programming in the Tcl language.

Directory Server Dependencies


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.

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:

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 Usage

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

-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

Configuring ilash

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

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:


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 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:

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:

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:

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:

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:

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:

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 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:

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 Commands

The 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

Table 32-4 LDAP Command Equivalents of the ilash Tool
Command	Effect on the Directory
dbind	Perform an LDAP bind operation.
drebind	Alias for the dbind -nomove -rebind command.
dextension	Invoke an extension, given by its OID, on the server.
dsearch	Perform an LDAP search operation using a filter.
dcompare	Perform an LDAP compare operation on an attribute value.
dadd	Compose an entry in LDIF and perform an LDAP add operation.
dmodify dmod	Perform an LDAP modify operation to add, modify or remove attributes.
dmodifyrdn dmodrdn	Perform an LDAP modify-RDN (relative distinguished name) operation.
drelocate	Move entries from one subtree to another (“reparent”) or move entire subtrees.
ddelete drm dbulkclean	Perform an LDAP delete operation with the option to delete subtrees.
dunbind dquit quit	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
dshowname dshown dpwd	Display the full DN of the current location or of the specified target object.
dshowentry dshow	List the attributes of the entry at the given location.
dlist dls	List the RDNs of all first-level children of a given entry.
dmoveto dmove dcd	Change the current directory location of the ilash interpreter.
dstatus dinfo	Give information about the connection to the current directory server.
dschema	List the schema entries associated with an object or import schema definitions.
dsequence dseq	Manage the existing sequences and run commands using their entries.
dhelp help ?	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
dbulkload dload	Import entries into the directory from either an LDIF text file or a CSV (comma-separated values) format file.
dbulkdump ddump	Export entries from the directory as LDIF text to a file or the standard output.

Bulk Data Scripting Example

The 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]]"

Previous Contents Index Next
Sun ONE Directory Server Resource Kit 5.2 Tools Reference