Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun ONE Directory Server Resource Kit 5.2 Tools Reference 

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.


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.

Code Example 32-1  Simple Navigation with ilash

[People, Example,com]% dpwd

ou=People, dc=Example, dc=com

[People, Example,com]% dcd ..

[Example,com]% dshow "uid=bjensen, ou=People," -type cn

dn: uid=bjensen, ou=People, dc=Example,dc=com

cn: Barbara Jensen

cn: Babs Jensen

[Example,com]% dls

2 ou=Groups,

3 ou=People,

4 ou=Special Users,

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:

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:

Tcl Resources

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

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


The syntax of the ilash command on the command-line takes the following forms:

ilash -noconnect

ilash [-file TclScript] ...

ilash dbindOptions

Where:

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


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

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

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     


Copyright 2004 Sun Microsystems, Inc. All rights reserved.