Chapter 31
ilash Overview
The iPlanet LDAP Administrative Shell, called ilash, is an LDAP client that provides a scriptable command-line interface to a directory. It provides commands for performing LDAP operations, navigating the directory, and importing and exporting data. It allows directory administrators to access configuration information and develop scripts for managing the directory.
The ilash tool is based on Tcl (Tool Command Language), and includes a complete Tcl interpreter, which has been extended to include commands for accessing the directory. The current version of ilash is based on Tcl 8.2.
The ilash tool provides an interface similar to that provided by a UNIX shell or Windows NT command prompt. Using ilash, you can navigate the directory hierarchy in much the same way as you can change the current directory in a file system. Similarly, directory locations in ilash can be specified as a relative or absolute DN in the same way that pathnames are specified.
This chapter contains the following sections:
Starting the Shell
This section describes how to launch the ilash shell and provides details about its command interpreter. The directory commands available in the shell and in ilash scripts are described in detail in Chapter 32 "ilash Command Reference."
Syntax
The syntax of the ilash command line has three 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
are the command-line options described in the next section. 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 (see "Configuring ilash").
Options
The ilash command-line options are exactly those of the dbind command. Only those needed during startup are listed in the following table. The complete description of all options is given in "dbind".
Table 31-1 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.
|
|
Caution
|
You should never specify the -password option on the command line because this exposes the password
to other users through the list of processes (the ps command) on UNIX systems.
Specify the password in protected configuration files or give the password interactively when prompted by the ilash tool.
|
The initial binding and run-time behavior of the tool is fully customizable through configuration files, as described in "Configuration Files".
The commands for interacting with the directory server are listed in "Summary of Commands" and are fully described in Chapter 32 "ilash Command Reference." While running ilash, you also have access to all Tcl commands that allow you to navigate the file system as well (see "The tclsh Shell").
To exit ilash, type quit or use the dunbind command.
Directory Server Dependencies
When binding to a server, ilash will attempt to discover the capabilities of the server as published in the supportedControl and supportedExtension attributes in the root DSE of the server. Use the dstatus -controls -extensions command to view the supported controls and extensions that were discovered.
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 they are unable to obtain a result by any other means.
Directory Schema
The ilash interpreter is able to detect, import, and interpret the directory schema. It uses this information to format attributes for display and to generate templates for adding entries of any given object class.
By default, the schema is not imported, but 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.
Parallel Operations
Many ilash commands, such as dshow, accept multiple targets. When possible, ilash will attempt to issue multiple operation requests in parallel to the server. By default, ilash will limit itself to 10 simultaneous requests to a server.
The degree of parallelism can be set by the maxconns parameter in the 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.
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
The current location is an entry in the directory tree. The ilash interpreter always displays this entry's DN in abbreviated form in the command prompt. The current location is always the default target entry for a command. As in a file system, the current location is abbreviated "." (a dot).
You may also specify an entry relative to the current location. The parent entry is abbreviated ".." (two dots), and children may be referred to by their RDNs (relative distinguished names). However, the parent notation may not be combined with any other; you must use absolute DNs to specify grandparents or siblings relative to the current location.
The following screen output shows simple navigation through the directory:
-
[People, Siroe,com]% dpwd
ou=People, dc=Siroe, dc=com
[People, Siroe,com]% dcd ..
[Siroe,com]% dshow "uid=bjensen, ou=People," -type cn
dn: uid=bjensen, ou=People, dc=Siroe,dc=com
cn: Barbara Jensen
cn: Babs Jensen
[siroe,com]% dls
2 ou=Groups,
3 ou=People,
4 ou=Special Users,
The Location Stack
Normally, the ilash interpreter does not remember previous locations as you move from one entry to another in the directory. However, it provides a location stack that allows you to store a location and return to it at any time.
You 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.
`The World'
A directory server may have several naming contexts that are entire directory trees. The root DSE is a special entry that represents the server itself and that lists the DN of each of its naming contexts. The ilash tool refers to the root DSE entry as The World. The attributes of this virtual entry are the server configuration parameters that may also be viewed with the dstatus command.
The root DSE 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. Also, the move -pop command on an empty stack will move to the root DSE.
There are other server configuration entries, for example cn=schema, which contains schema definitions. These may be accessed through their DN as any other entry.
Sequences
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.
Sequence numbers may 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. For more information, see the reference for "dsequence".
All of these features make sequences useful in scripts for managing the output and performing complex operations.
The tclsh Shell
The ilash tool is built on top of the Tcl interpreter tclsh which means 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 edit and replay previous commands. You may also write Tcl scripts that use ilash commands and execute them with the ilash interpreter. See "The .lashrc File" and "Scripting Example".
However, you do not need to know Tcl to use ilash. Chapter 32 "ilash Command Reference," and the following section on quoting rules give you all the information you need to navigate through a directory and view its entries.
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=Siroe,dc=com}
"ou=Human Resources,dc=Siroe,dc=com"
Within braces, commas that do not separate DN components must be escaped with a single backslash \ character:
-
{o=Siroe.com\, SARL,c=fr}
Within double-quoted strings, the same commas must be escaped with double backslash \\ characters:
-
"o=Siroe.com\\, SARL,c=fr"
The backslash is the escape character in Tcl, so pathnames on Windows NT will also require double backslashes. They will also require quoting if they contain spaces:
-
"C:\\Program Files\\iPlanet"
-
The Tcl interpreter also recognizes Windows NT pathnames containing forward slashes for which no escape character is necessary:
-
"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.
Summary of Commands
The following sections give a summary of the ilash commands grouped by task categories. The tables also show synonyms for commands, which are simply alternate command names for the same functionality. All commands and their options are described in detail in Chapter 32 "ilash Command Reference."
LDAP Commands
The LDAP commands are the ilash commands for standard directory operations.
Table 31-2 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 the commands for accessing the directory configuration information such as the schema and the supported controls.
Table 31-3 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
There are two ilash commands that provide facilities for managing bulk data in the directory. The dbulkclean command is actually a synonym for ddelete.
Table 31-4 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.
|
Configuring ilash
There are three files that control the operation of ilash:
The system-wide configuration file.
A user's configuration file.
A user's .lshrc initialization script.
The configuration files allow you to set up global and personal defaults. The files contain configuration parameters to define aliases, set preferences and specify default command options. The initialization script contains ilash and Tcl commands that will be executed as the first commands of the ilash interpreter.
None of the files are mandatory; all functionality of the ilash commands is available through their command-line options.
Configuration Files
The system and user configuration files contain default information concerning remote servers, authentication and other general configuration options. The configuration files must have the following names:
The installDir
is the location of your iPlanet Directory Server Resource Kit installation, which is /opt/iPlanet by default.
These files contain simple parameter definitions that are loaded into the ilash interpreter. They may also contain comments on lines beginning with a hash (#). The exact syntax of these files is given in the following section, "Configuration Parameters."
On startup, ilash will first read the system configuration file, if it exists, and then the user's configuration file, if it exits. Parameters and aliases that are redefined in the user's configuration file will override their definition in the system configuration file. User specifications and server specifications in a user's configuration will take precedence over those of 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.
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.
Configuration Parameters
The configuration files contain five types of parameters: global parameters, aliases, command defaults, server specifications, and user specifications.
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 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. The parameters are listed in the following table.
Table 31-5 Configuration File Parameters for the ilash Interpreter
|
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=Siroe,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=Siroe,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. 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.
The 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.
The following table shows the command specifiers (in bold) and the ilash commands to which the default will apply.
|
add
|
dadd
|
modifyrdn
|
dmodifyrdn dmodrdn
|
|
bind
|
dbind
|
moveto
|
dmoveto dcd
|
|
bulkclean
|
dbulkclean
|
search
|
dsearch
|
|
bulkload
|
dbulkload
|
showentry
|
dshow dshowentry
|
|
compare
|
dcompare
|
showname
|
dshowname dpwd
|
|
delete
|
ddelete drm
|
status
|
dstatus
|
|
list
|
dlist dls
|
unbind
|
dunbind dquit quit
|
|
modify
|
dmodify dmod
|
|
|
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.Siroe.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 defaultserver parameter 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=Siroe,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 Tcl script file 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, for example setting variables or defining procedures. This file may also contain the following 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.
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=Siroe,dc=com. This 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".
For further help with Tcl scripting, see the references in "Tcl Resources".
|
#!/opt/iPlanet/bin/idsrk51/ilash -file
|
|
# allow username or other bind flags to be specified
|
# on the command line
|
eval [concat dbind $argv]
|
|
set base "dc=Siroe,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]]"
|
|