Chapter 33 ilash Command Reference

This chapter contains detailed reference for each command of the ilash LDAP Administrative Shell that is provided with the Sun™ ONE Directory Server Resource Kit (DSRK). It contains the following sections:

Overview

Each reference section gives the command-line syntax, a list of options and description of the command. In many cases, an example shows a typical usage of the command. Some commands are synonyms of others; in other words, they are aliases to other commands that are fully referenced. Synonyms have identical command-line options and all of the same functionality. For a quick overview of all ilash commands, see Summary of Commands in Chapter 32, "ilash: The LDAP Administrative Shell."

Common Options

This section describes the options common to many commands. These options are not repeated in the syntax or description of each command reference, unless their meaning or usage is different in a particular command. It is best to specify default values for these options in the service configuration parameter so that they always apply to all directory access commands. For more information on configuration parameters, see Configuration Files in Chapter 32, "ilash: The LDAP Administrative Shell."

Online Help


Note	Full option names are used in descriptions and examples for this chapter although, the ilash interpreter will recognize the shortest unique prefix of an option name. This abbreviation is sufficient to select that option on that tool. Prefixes for the same option may be different for each command due to ambiguities with other option names.

All of the commands support the -help option that lists all possible options for that command. Full option names are given in the help message. For example:

[Example,com]% dshowname -help
dshowname - show the name of an entry,
[<object>] [-ufn] [-ldap] [-help]

LDAP-Specific Options

The ilash commands that perform directory access operations have set options for specifying LDAP functionality. The LDAP-specific options include limits and controls that may apply to an LDAP request. The following commands support the LDAP-specific options:

LDAP-specific options either have a default value or values that are not mandatory (in most cases, they are not needed). When they are needed, it is best to specify them in the service configuration parameter so that they always apply to all directory access commands.


Note	Any of these options may still be given on the command-line, to override either the default behavior or the configuration file settings.

Table 33-1 LDAP-Specific Options
Parameter	Purpose
-timelimit seconds -notimelimit	Set a time limit in seconds for the LDAP request to complete. The -notimelimit option is the default. These options determine how long the ilash client will wait for a response to its request. The directory server may impose its own time limit for operations in either case. A directory search that reaches the time limit may return incomplete results.
-sizelimit entries -nosizelimit	Set the maximum number of entries that search requests will return. The -nosizelimit option is the default. The directory sever may also impose its own size limit for results. A directory search that reaches the size limit will return incomplete results.
-attributesizelimit bytes -noattributesizelimit	Set the maximum size in bytes for individual attributes in entries returned from a search operation. The size of an attribute includes its name and all of its values. The -noattributesizelimit option is the default. These options will have an effect only if the server supports the attribute sizelimit control (OID 1.3.6.1.4.1.1466.29539.1).
-dereferencealias -dontdereferencealias	Determine the action to take when encountering an alias in the target of an operation. By default, aliases will be dereferenced and their target will be returned. Commands will not notify the user when an alias is dereferenced.
-chaining -nochaining	Allow or prohibit the use of chaining. These options will have an effect only if the server supports the no-chaining control (OID 1.3.6.1.4.1.1466.29539.5). The default behavior is then determined by the server configuration.
-refer -norefer	Determine whether or not to follow referrals. The default behavior is determined by the server configuration.
-usecopy -dontusecopy	Allow or prohibit the use of a shadowed copy of the data. These options will have an effect only if the server supports the no-copy control (OID 1.3.6.1.4.1.1466.29539.2). The default behavior is determined by the server configuration.
-managedsait	Allow an administrator to operate on server configuration entries in the directory. This option can be used only when bound as the directory manager. It will take effect only if the server supports the manage-DSAIT control (OID 2.16.840.1.113730.3.4.2).

Display Options

The commands that display entries have common options for formatting their output. The display options control how entries are read from the directory and displayed in the output of the command. The following commands support display options:

Again, you may wish to set these options as defaults for the commands in a configuration file.

Table 33-2 Entry Display Options
Parameter	Purpose
-type attribute ...	Specify that only the listed attributes are read from the directory and displayed in the results. This option may also be used to explicitly request operational attributes such as the subschemsubentry attribute for schema references. The default behavior is that specified by the -all option below.
-notype attribute ...	Display all attributes except those listed. This option does not prevent the attributes from being read from the directory, it only filters them out of the display. The default behavior is that specified by the -all option below.
-all	This flag requests that all normal attributes of an entry be read from the directory and displayed in the output. This is the default behavior when the -type and -notype options are not used. However, operational attributes used by the directory server, such as the subschemasubentry attribute for schema references, are never displayed unless specifically requested using the -type option.
-noall	This option currently has no effect.
-value -novalue	These options determine whether or not attribute values are displayed. When -novalue is given, only attribute names are displayed under the DN for each entry, without any trailing punctuation. The -value option is the default behavior.
-key -nokey	These options determine whether or not attribute names, also known as keys, are displayed. When -nokey is given, only attribute values are displayed under the DN for each entry. The -key option is the default behavior.
-show -noshow	These options control the overall display of attributes under each DN in the output. The -noshow option will suppress all attribute display. With the -show option, attributes will be displayed according to the other display options above. -show is the default for the dshowentry command. -noshow is the default for the dsearch command.

Modifying Default Behavior

The default behavior listed for each command option in this reference chapter may be modified by configuration files. (See Command Defaults in Chapter 32, "ilash: The LDAP Administrative Shell.") Options usually exist in pairs to allow either the command default or the configured default to be overridden. For example, the dshow command might be configured to not show attribute names. It is still possible to display the attribute names, but you must specify dshow -key on the command-line.

Command Reference

dadd

DESCRIPTION

The dadd command creates an entry in LDIF, allows you to edit it, and then adds it to the directory. The credentials used to bind to the current directory must have permission to add the given entry. There are two scenarios for creating an LDIF entry interactively:

If an add operation fails, the draft will not be renamed, and you may run dadd again with the same command-line. It will detect the draft and ask if you want to edit it. If yes, it will open the text editor, allowing you to modify and resubmit the entry. If not, it will create a new draft file using the DN and object class names or the template on the command-line and overwrite the failed draft file.


Note	The text editor is defined by the EDITOR variable in your environment. If this variable is not defined, you will be prompted for the name of a text editor application.

You may also use the dadd command to add an entry without interaction. Use the -noedit and -template options, specify the DN as the target object, and specify a complete valid LDIF entry, without the DN, in the template file.

SYNTAX

dadd
  [object] [-objectclass objectclass ...]
  [-draft draftLocation] [-newdraft]
  [LDAP-specificOptions]

dadd
[object] [-template templateFile]
[-[no]edit]] [LDAP-specificOptions]

OPTIONS

Table 33-3 dadd Options
Option	Parameter	Purpose
	object	Specify the DN of the entry to be added. The DN will be used in the new draft of an LDIF entry to which you add attributes and values before the command can add it to the directory. If you specify a relative DN, it will be expanded to its full value. The default value is the DN of the current location.
-objectclass	objectclass ...	Specify the one or more object classes to which the new entry will belong. The tool will generate a new draft that, if the directory schema is loaded, will contain all parent object classes and all required and possible attributes. The default object class is person, which also implies top.
-template	templateFile	Specify a file location that contains your template for creating new entries. This template file may contain any text you wish for creating a single entry, except for its DN. You should always specify the object parameter with the -template option. The -objectclass option is ignored when using a template file. The template file will be copied to the draft location, and the DN determined by the object option (or its default value) will be appended as the first line of the file. Then, you will have the opportunity to edit its contents before it is used to add a new entry. The template file is never modified.
-draft	draftLocation	Specify the location of the draft file. This is where the tool will generate an LDIF text file containing the entry to add. The default location is the .lashdraft file in the user’s home directory. If a file exists at that location, the tool will ask you whether or not to use it as the draft. If you choose to use the existing draft file, the object and objectclass options will be ignored. If you choose not to use an existing draft file, if you specify a template file, or if you specify the -newdraft option, any file at the draft location will be overwritten.
-newdraft		Force the tool to generate a new draft file using the values of the object and objectclass options. Any file at the draft location will be overwritten without the choice to edit it instead. You must edit this new draft file to specify all necessary attribute values.
-edit -noedit		Specify whether or not you want to edit the draft file interactively before it is used to add an entry. The default is the -edit option. Use the -noedit, -template, and object options to add entries without any interaction. The template file and object must specify a complete and valid LDIF entry. This option is not compatible with -newdraft.
	LDAP-specificOptions	See options in LDAP-Specific Options.

EXAMPLES

Code Example 33-1 is the new draft (edited for brevity). It will contain the parent object classes and all possible attributes for you to fill in.

Code Example 33-1 Editable Draft for dadd Command


dn: uid=bslater, ou=People, dc=Example, dc=com
objectClass: organizationalperson
objectClass: person
objectClass: top
#destinationIndicator:
#facsimileTelephoneNumber:
#internationaliSDNNumber:
#l:
#ou:
...
#sn:
#cn:
#description:
#seeAlso:
#telephoneNumber:
#userPassword:

This second example uses the template file reproduced in Code Example 33-2 which has no DN. Because the template contains all required information, we may add the entry, without editing the intermediate draft file, using the following command:

[People,Example,com]% dadd "uid=tmorris," -template morris.ldif \
-noedit

Code Example 33-2 Template File for dadd Command


objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Ted Morris
sn: Morris
givenname: Ted
uid: tmorris
mail: tmorris@Example.com
telephonenumber: +1 555 058 4282

SEE ALSO

dbind

DESCRIPTION

The dbind command connects the ilash tool to a directory server so that you can access its contents. On startup, the tool will bind to the server using this command and you may specify dbind options on the ilash command-line. You may also invoke the dbind command at any time to change servers or modify the bind parameters, such as the bind DN. Any existing connections will first be automatically unbound.

Many of the options such as the server URL and bind DN may be set as parameters in the configuration files to simplify the command-line. The configuration files may also enforce an authentication mechanism that requires you to provide user and password credentials when using this command. The possible authentication mechanisms are:

SYNTAX


Note	When using TLS authentication and encryption, you must define the SSL options, such as ssl_key and ssl_cert, in the configuration files.

dbind
  [-call URL-alias] [-noconnect] [-[no]move]
  [-v2|-v3] [-[no]schema] [-[no]rebind]
  [[-user] bindDN] [-password password]
  [-noauthentication] [-simple] [-hd]
  [-tls] [-tlsauth] [-[no]verify]

OPTIONS

Table 33-4 dbind Options
Option	Parameter	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 Configuration Files.) If the defaultserver option is not specified in the configuration files, the default server is ldap://localhost/ on port 389.
-rebind -norebind		With the -rebind option, the dbind command will connect to the last server to which it was bound. It will also use the same connection parameters, unless they are overridden by options on this command-line. The -norebind option is the default: the dbind command will connect to the default server. These options have no effect during the first connection of the ilash tool.
-noconnect		Prevents any binding so that the dbind command effectively does nothing. This option is used only when launching the ilash tool. (See Command Usage.)
[-user]	bindDN	Specify the bind DN for authentication. The -user keyword is optional. The bindDN itself is optional even for strong authentication if the username parameter is defined in configuration files.
-password	password	Specify the password for the given username DN. The password is optional because it may be specified in the configuration files for the given username. If this option is not specified and there is no password configured, the command will prompt the user for a password. This avoids ever having to store the password in a file.
-noauthentication		Perform anonymous binding, if allowed by the server. This option is the default if no username is not given.
-simple		Perform simple, non-encrypted and non-certificate based authentication with a username and a visible password. This is the default if a username is given.
-md5		Perform CRAM-MD5 SASL authentication to encrypt the password over the network.
-hd		Perform HTTP digest-MD5 authentication to encrypt the password over the network.
-tlsauth		Specify that the authentication process use the credentials presented by the user’s certificate. The -tlsauth option will also set the -tls option for using encryption during the connection.
-v2 -v3		Perform an LDAP v2 bind. Use this options for servers that do not support LDAP v3. The default is -v3: perform an LDAP v3 bind.
-tls		Specify that the connection initiate a Start TLS operation with the server immediately after binding signifying all communication to and from the server will be encrypted.
-verify -noverify		The -verify option will also set the -tls option. It will cause the ilash client to attempt to verify the certificate presented by the server for the TLS encryption. If the certificate cannot be verified, the connection will not be established. The default is -noverify: do not attempt to verify the server certificate.
-schema -noschema		Specify whether or not the ilash interpreter should import the directory’s schema upon connecting to the server. (See dschema -import.) Some commands such as dadd offer functionality that relies on the imported schema. The default is -schema.
-move -nomove		The -move option specifies that the initial location in the directory should be the server’s default naming context. The -nomove option specifies that the initial location should be the root DSE. The value of the local_dit option in the configuration files takes precedence over both, if it is defined. Otherwise, the default is -move.

EXAMPLES

SEE ALSO

dbulkclean

dbulkdump

Export entries from the directory as LDIF text to a file or the standard output.

DESCRIPTION

The dbulkdump command writes entries in LDIF format to a file or to the standard output. Along with the dbulkload, this command provides the ability to back up your directory data or to move entries and entire subtrees to a different directory. By default the tool will export all entries in the subtree rooted at the target object. The order of entries in the LDIF output will preserve the structure of the subtree hierarchy. Specifying multiple target objects or using the -nobase option may not preserve the structure, in which case the output cannot be bulk-loaded into another directory.

The output of dbulkdump is subject to the limit on the number of entries that may be retrieved at one time from the directory. This limit may be set on the client side by the -sizelimit option as described in LDAP-Specific Options. On the server side, the number is limited by the nsslapd-sizelimit attribute whose default is 2,000 entries. (See “nsslapd-sizelimit (Size Limit)” in Chapter 4 of the Sun ONE Directory Server Reference Manual.) If either limit is reached, not all entries will be exported, and an error will be logged in the output.

SYNTAX


Note	Export to the comma-separated value (CSV) format is not supported.

dbulkdump
  [object ...] [-file filename] [-[no]header]
  [-[no]base] [-[no]below]
  [LDAP-specificOptions]

OPTIONS

Table 33-5 dbulkdump Options
Option	Parameter	Purpose
	object ...	Specify the root entry of the directory subtree to be exported. You may specify multiple objects: each of their subtrees will be output in the order specified.
-file	filename	Specify the name of a file to contain the LDIF output. When this option is omitted, the command will use the standard output.
-header -noheader		Specify whether or not LDIF header information appears in the output. The header is a single line with a version identifier. The default is -header.
-base -nobase		Specify whether or not the root entries of the target subtrees are included in the output. The default is -base. With the -nobase option, the target objects on the command-line will not appear in the output, only their subtrees will.
-below -nobelow		Specify whether or not subtree entries are included in the output. The default is -below. With the -nobelow option, only the target entries on the command-line will appear in the output.
	LDAP-specificOptions	See options in LDAP-Specific Options.

SYNONYMS

SEE ALSO

dbulkload

Import entries into the directory from either an LDIF text file or a comma-separated value (CSV) format file.

DESCRIPTION

The dbulkload command loads multiple entries from a data file into the directory. The command has two distinct uses, one for each of the file types it can import: LDIF and CSV.

should contain complete entry records, including the DN that determines the absolute location in the directory. LDIF files may contain a hierarchy of entries that form an entire subtree. Entries are imported in the order they appear, so parent entries must be given before their children. Also, the DNs of the new entries must fit into the existing directory hierarchy.

require a template that defines how the values in the CSV data file are assigned to attributes. CSV is not a standard LDAP format, but many products such as spreadsheets can export columns or fields as comma-separated values. The target object given on the command-line will be the parent of all new entries, meaning they may be loaded anywhere in the directory. However, all entries created from CSV data must have the same RDN structure, meaning that they must all be imported at the same level in the directory hierarchy.

SYNTAX


Note	The dbulkdump command and many other tools in the DSRK output LDIF files that can be imported into the directory using dbulkload. It does not though support LDIF change records. It supports only LDIF attribute specification records that define all necessary attributes of an entry.


Caution	Any errors in the format of an entry or when adding it to the directory will only prevent the entry in question from being loaded. The tool will output an error message and continue loading other entries. In addition, the credentials used to bind to the current directory must have permission to add all given entries.

dbulkload
  [object] [-[no]overwrite]
  [-dereferencealias] [LDAP-specificOptions]
  -ldif filename

dbulkload
  [object] [-[no]overwrite]
  -csvdata filename -template filename
  [-rdn attributeName ...] [-[no]usefirst]
  [LDAP-specificOptions]

OPTIONS

Table 33-6 dbulkload Options
Option	Parameter	Purpose
-ldif	filename	Define the path and filename of a file containing the LDIF entry records to import. This option is incompatible with all of the CSV-specific attributes.
-overwrite -nooverwrite		Specify whether or not existing entries will be overwritten if the imported data contains the DN of an existing entry. The default is -overwrite. The -nooverwrite option will report an error but not stop the import operation when attempting to add an entry that already exists. -nooverwrite involves fewer directory operations per entry. Therefore, if efficiency is a concern, specify this option when you know the imported DNs are unique. If you wish to replace entire subtrees, running ddelete then dbulkload with the -nooverwrite option will be faster.
-dereferencealias		Specify that the server should dereference any aliases in the imported entries. The default is -dontdereferencealias, unlike most other commands that have LDAP-specific options.
	LDAP-specificOptions	The dbulkload command uses the LDAP-specific options for all of the search, delete, and add operations it performs internally. See LDAP-Specific Options.
	object	Specify a single directory location under which the data is to be loaded. The DN of this location will be used to create the DN of new entries specified by the CSV data. The default value is the current location in the directory.
-csvdata	filename	Define the path and filename of a CSV file that contains attribute values for entries to be added. You must also specify a template file, and in most cases, you will need to specify -rdn attributes.
-template	filename	Define the path and filename of a template file to translate CSV data into a valid entry. A template contains LDIF-like text and placeholders for attributes in the CSV data file.
-rdn	attributeName ...	Specify any number of attributes that will form the relative DN of the entries to be added from a CSV file. The values for these attributes will be used in the order given and appended to the front of the target object to create the DN of each entry. If no attribute names are specified using this option, cn is selected by default.
-usefirst -nousefirst		Specify whether or not to allow attributes given by the -rdn option to have multiple values in the new entry. Setting the -usefirst option allows RDN attributes to be multivalued and selects the first value defined in the CSV data or the template to figure in the RDN. The default is -nousefirst, which will report an error for an entry when one of its RDN attributes has more than one value.

EXAMPLE

This example demonstrates importing from a CSV file. data.csv, reproduced in Code Example 33-3, is the CSV text file where each line is an entry with fields separated by commas.

[Example,com]% dbulkload "ou=People," -csvdata path/data.csv \
-template path/template -rdn cn uid

Added cn=Adam Alder + uid=aa, ou=People, dc=Example, dc=com
Added cn=Bob Brown + uid=bb, ou=People, dc=Example, dc=com
Added cn=Carl Cade + uid=cc, ou=People, dc=Example, dc=com
path/data.csv:4 error processing record: entry doesn’t have the
rdn attribute uid
Added cn=Eric Elmar + uid=ee, ou=People, dc=Example, dc=com


Caution	A value containing whitespace, a comma, or a quote character should be surrounded by quotes. A quote is specified by two quotes in a row. For example, employee,’Fred ‘’Ford’’’,’3rd floor, room 12’,0449

A template file contains an LDIF entry with placeholders for field values and no DN. The DN is generated from the target object and the -rdn option specified on the command-line. The placeholders are replaced with their corresponding field number. Code Example 33-4 is the sample template, referred to in the command example, for the CSV data defined in Code Example 33-3.

Placeholders must appear as attribute values at the end of a template line and must refer to a valid field number. However, field numbers may be repeated and not all fields need to be used in the template. (The Bulk Data Scripting Example in Chapter 32, "ilash: The LDAP Administrative Shell" also uses the dbulkload command to automate a bulk loading operation.)

SYNONYMS

SEE ALSO

dcd

dcompare

DESCRIPTION

The dcompare command checks to see whether or not the target entry holds a particular attribute value. It returns TRUE if the entry contains an attribute with the given name and value, FALSE otherwise. Use the -noprint option to return a numeric value of 1 or 0, respectively, which is easier to test programmatically in a script.

The LDAP-specific options are used as parameters to the internal directory access operation needed to read the attribute value.

SYNTAX

dcompare
[object] -attribute name=value
[-[no]print] [LDAP-specificOptions]

OPTIONS

Table 33-7 dcompare Options
Option	Parameter	Purpose
	object	Specify the DN of the entry in which to compare the given attribute value. The default is the entry at the current location.
-print -noprint		Specify the format of the output. The default -print will return the value TRUE or FALSE. -noprint will return the value 1 or 0, respectively.
-attribute	name=value	Specify the name of the attribute to verify and the value to which it should be compared. Multivalued attributes will compare positively if any one of their values equals the given value.
	LDAP-specificOptions	See options in LDAP-Specific Options.

ddelete

DESCRIPTION

The ddelete command removes entries from the directory, with the option to delete entire subtrees. When deleting a single entry, it must not have any children. When deleting a subtree, you specify a non-leaf entry and you have the choice of deleting only those entries below it. In all cases, the credentials used to bind to the current directory must have permission to delete entries.

SYNTAX


Note	The command will use the subtree delete control (OID 1.2.840.113556.1.4.805) when the server supports it. When the control is not available, the command will delete subtrees by recursively descending the directory tree to remove entries.

ddelete
[object ...] [-base] [-below] [-subtree]
[-[no]prompt] [LDAP-specificOptions]

OPTIONS

Table 33-8 ddelete Options
Option	Parameter	Purpose
	object ...	Specify the target objects to be deleted. Unless you specify either the -below or -subtree option, the target must be a leaf entry.
-base		Specify that only the target objects should be deleted. This is the default behavior.
-below		Specify that all entries in the subtree below each target object should be deleted. Target entries are not deleted.
-subtree		Specify that the entire subtree rooted at each target object, including the targets themselves, be deleted.
-prompt -noprompt		Specify whether or not the command should ask the user for confirmation before performing the delete operation The default is -prompt.
	LDAP-specificOptions	See options in LDAP-Specific Options.

SYNONYMS

ddump

dextension

DESCRIPTION

The dextension command invokes extensions on the directory server. Extensions are server-dependent operations that may perform non-LDAP operations or modify the functionality of the server. The tool will check whether or not the server supports the extension before sending it. The directory server may send a reply to the extension request, in which case the dextension command will display the OID and data contained in the response.

SYNTAX

dextension
  [-oid OID] [-data data] [-[no]force]
  [-stop] [-reset]
  [LDAP-specificOptions]

OPTIONS

Table 33-9 dextension Options
Option	Parameter	Purpose
-oid	OID	Specify the OID (object identifier) of the extension in dotted decimal format, for example: 1.2.840.113556.1.4.805 .
-data	data	Give additional data as a string that will be sent with the extension request. Some extensions require additional parameters that can be entered here.
-stop		This option is a shortcut for invoking a shutdown extension (OID 1.3.6.1.4.1.1466.20001) recognized by some servers.
-reset		This option is a shortcut for invoking a reset extension (OID 1.3.6.1.4.1.1466.20002) recognized by some servers.
-force -noforce		The -force option specifies that the extension should be invoked without checking whether the server supports it. The default is -noforce.
	LDAP-specificOptions	See options in LDAP-Specific Options.

dhelp

Displays a list of all ilash commands and their brief description. This list does not include synonyms for commands.

SYNONYMS

dinfo

dlist

DESCRIPTION

The dlist command searches the directory and displays the list of all entries that are immediate children of the target object. The output of the command is a list of RDNs that are relative to the target object, not to the current location.

In the output, the number to the left of each RDNs is its number in the sequence. If the corresponding DN already exists in the current or the named sequence, the numbers may not begin at 1 or even be numbered sequentially. The number of RDNs returned can be limited by using the -sizelimit option described in LDAP-Specific Options.

SYNTAX


Note	This command may be considered the equivalent of the ls or dir command, although it doesn’t support filtering on the DN. To search for specific DNs, you must use the dsearch command. To display the contents of an entry, use the dshowentry command.

dlist
[object] [-[no]move] [-[no]push]
[-sequence name] [LDAP-specificOptions]

OPTIONS

Table 33-10 dlist Options
Option	Parameter	Purpose
	object	Specify a single target object. The default is the current location.
-move -nomove		Specify whether or not the command should also change the current location to that of the target object. The -move option is not compatible with -push. The default is -nomove.
-push -nopush		Specify whether or not the command should also push the current location onto the location stack and change to the location of the target object. The default is -nopush. The -push option is overridden by -move and -nomove when they occur after it on the command-line.
-sequence	name	Save the DNs of entries from the output under the given sequence name and do not modify the current sequence. Sequence names may contain only alphabetical characters. If the sequence does not exist, it will be created. If the sequence exists, new DNs will be appended to the end of it. When this option is omitted, the DNs are appended to the current sequence.
	LDAP-specificOptions	See options in LDAP-Specific Options.

SYNONYMS

SEE ALSO

dload

dls

dmod

dmodify

DESCRIPTION

The dmodify command has two usage scenarios: interactive and batch. To modify entries interactively, the command generates the LDIF text for all target entries in a draft file and opens it in a text editor. You may then edit this file to modify attribute values, remove attributes or add new ones. You may also add or remove entire entries. The tool will then compare this file with the existing entries and perform all necessary LDAP operations to update the directory. When you close the editor, the tool will display the number of added, modified, and deleted entries and ask for confirmation before committing all changes. If you change your mind, the directory will not be modified. Once you have edited the LDIF entries in the draft file, the following choices apply:

In a batch scenario, you specify modifications on the command-line and the command performs them on all target entries. By using sequence numbers to specify targets, you may add, modify, or delete an attribute across the entire directory. You may specify any number of attribute modifications on the command-line, allowing you to perform global updates.

In both scenarios, the credentials used to bind to the current directory must have permission to modify all given entries. Finally, the server may also reject modifications that do not follow the schema of the directory.

SYNTAX


Note	The text editor is defined by the EDITOR variable in your environment. If this variable is not defined, you will be prompted for the name of a text editor application.

dmodify
[object ...] [-draft draft [-[no]edit]] [-newdraft]
[LDAP-specificOptions]

dmodify
  [object ...] [-add attribute=value] ...
  [-remove attribute=value] ... [-remove attribute] ...
  [LDAP-specificOptions]

OPTIONS

Table 33-11 dmodify Options
Option	Parameter	Purpose
	object ...	Specify the target objects to modify. The default is the current location. When using a draft file, you will be able to edit the target entries as LDIF in a text editor. When adding or removing only attributes, all target entries will be modified in same way.
-draft	draftLocation	Specify the location of the draft file. This is where the tool will generate an LDIF text file containing the entries to modify. The default location is the .lashdraft file in the user’s home directory.
-edit -noedit		Specify whether or not you want to edit the draft file interactively before it is used to modify entries. The default is -edit.
-newdraft		If a file exists at the draft location, the tool will ask you whether or not to use it as the draft. Use this option to suppress the query and force the tool to generate a new draft file from the target entries. Any file at the draft location will be overwritten. This option is overridden by the -noedit option.
-add	attribute=value	Specify the name and initial value of an attribute to add. If the attribute is already present in the target, it becomes a multivalued attribute. This option may be repeated to add multiple attributes or multiple values to the same attribute.
-remove	attribute=value attribute	Specify the name of an attribute to remove. If you also specify a value, the attribute is assumed to be multivalued and only that value will be removed. When you specify the attribute name only, all values will be removed. This option may be repeated to remove multiple attributes or multiple values.
	LDAP-specificOptions	See options in LDAP-Specific Options.

SYNONYMS

dmodifyrdn

DESCRIPTION

The dmodifyrdn command modifies the RDN of an entry. The effect of this command is to rename the target entry by replacing the first component in its distinguished name. Use the -nodelete option if you wish to keep the old RDN as an attribute in the entry.

After modifying an RDN, any sequence number referring to the target entry will still refer to the old RDN. If you use this old sequence number, the old RDN will no longer be recognized by the directory.

SYNTAX


Note	Most directory servers allow this operation on leaf entries only. Modifying the RDN of a non-leaf entry is equivalent to renaming the entire subtree below that entry. Use the drelocate command to modify entire subtrees.

dmodifyrdn
  [object] -name name=value
  [-[no]delete]
  [LDAP-specificOptions]

OPTIONS

Table 33-12 dmodifyrdn Options
Option	Parameter	Purpose
	object	Specify a single target object. The default is the current location.
-name	name=value	Define the new RDN of the target entry. The named attribute and its value will also be added to the entry.
-delete -nodelete		Specify whether or not the attribute and value corresponding to the old RDN component should be removed from the entry. The default is -delete.
	LDAP-specificOptions	See options in LDAP-Specific Options.

SYNONYMS

SEE ALSO

dmodrdn

dmove

dmoveto

DESCRIPTION

The dmoveto command changes the current directory location to the given target DN, much like the cd command of a standard shell. You may also push the old location onto the location stack. The -pop option will return to the location specified by the DN taken from the top of the location stack. Specifying an empty string ("") as the target object or using the -pop option when the location stack is empty will change to ‘The World’ (the root DSE, a virtual entry representing the directory server itself) as discussed in Chapter 32, "ilash: The LDAP Administrative Shell." Specifying a target DN will check the validity of the new location with the server. (The LDAP-specific options are used during this directory access only.) It will not change the current location if the target DN is not valid. If you use the -nocheck option and specify an invalid target location, all further commands that rely on the current location will return errors. The current position can also be changed with the -move option of dlist and dshowentry.

SYNTAX

dmoveto
  object
  [-[no]pwd] [-[no]pop] [-[no]push] [-[no]check]
  [LDAP-specificOptions]

OPTIONS

Table 33-13 dmoveto Options
Option	Parameter	Purpose
	object	Specify a single target object to become the new location. If you omit the target object, the default value is the current location. Changing to the current location has no effect unless you use the -push option to place it on the stack. Specifying a target has no effect when using -pop option.
-pwd -nopwd		Specify whether or not to display the DN of the new location. The default is -nopwd, which will suppress all output. When using either -push or -pop, the -pwd option will also display the new contents of the location stack beneath the current location. Regardless of any command options, the current location is always displayed in abbreviated form in the ilash command prompt.
-pop -nopop		The -pop option changes the current location to that of the DN at the top of the location stack and removes that DN from the stack. The -pop option will override all other options except when -nopop occurs after it on the command-line.
-push -nopush		The -push option will place the current location on the location stack before changing to the new location. This option is not compatible with -pop. The default behavior is -nopush: the location stack is not modified, and only the current location changes.
-check -nocheck		Specify whether or not to check the validity of the target location before making it the current location. The default is -check. This option has no effect when using the -pop option; locations popped from the stack are not checked.
	LDAP-specificOptions	See options in LDAP-Specific Options.

SYNONYMS

SEE ALSO

dpwd

dquit

drebind

drelocate

Move entries from one subtree to another (“reparent”) or move entire subtrees.

DESCRIPTION

The drelocate command performs either the LDAP rename operation with the newparent option or adds and deletes entries to perform the equivalent operation. Many servers have limitations on relocating entries such as allowing only leaf entries to be moved and allowing them to be moved only within their original naming context. Some servers may not even support the rename operation, in which case you must use the -copy option to perform the operation by copying entries. Most servers will not allow you to move subtrees with the rename operation, so use -copy as well. Even with this option, the drelocate command has its own limitations, and not all subtree configurations can be moved. In all cases, the tool preserves all original entries if an operation cannot be completed correctly, either by the server or by the -copy option.

SYNTAX

OPTIONS

Table 33-14 drelocate Options
Option	Parameter	Purpose
	object ...	Specify the objects to be moved. Only one object may be specified when using the -target option.
-parent	object	Specify the parent entry under which all objects should be moved. The parent object must be the DN, relative DN or sequence number of an existing entry.
-copy -nocopy		Specify whether or not the drelocate command should perform the operation internally or call the LDAP rename operation. The default is -nocopy, which calls the LDAP rename operation. If the server is unwilling to perform the rename operation, use the -copy option to reparent the entries or move a subtree. The tool will do this internally by retrieving the entries to be moved, editing their RDN, adding them as new entries under the given parent or with the given target DN, and if all goes well, deleting the original entries.
-target	object	Specify the new DN of the object to be moved. The object to be moved will effectively be renamed to this target DN. Therefore, the DN must not designate an existing entry, but its parent, given by the second DN component, must exist.

drm

dschema

DESCRIPTION

The dschema command handles the special attribute values used to reference and define the schema in the directory. There are two forms to this command. The default behavior is to display the DN of schema entries that are referenced by the target entries. To view these schema definitions, use the dshowentry command on the DNs of schema entries in the output.


Note	Schema entries are referenced by the values of the subschemaSubentry attribute in the target entries. This attribute is available only in LDAPv3 directories, and dschema will report an error on LDAPv2 directories.

When you specify the -import option, the dschema command will import any schema definitions found in the target objects. The target must be an entry of the objectclass subschema, whose ldapSchemas, objectClasses, attributeTypes, ldapSyntaxes, and matchingRules attributes define the schema. Importing the schema entries into the ilash interpreter allows some commands to offer functionality that relies on the directory schema. For example, the dadd -objectclass command uses the schema to generate a template file containing all parent classes and attributes of the given object class. The LDAP-specific options are used in both cases when the command accesses the directory to read attribute values from the given entries.

SYNTAX

OPTIONS

Table 33-15 dschema Options
Option	Parameter	Purpose
	object ...	Specify all objects for which to list the associated schema entries. When using the -import option, specify the subschema entries to import. The default is the current location.
-import -noimport		Specify whether or not the target objects are schema entries with definitions to import. When -import is used, all object class and attribute definitions in the target entries will be loaded into the ilash interpreter. The default is -noimport.
-overwrite -nooverwrite		Specify whether or not existing definitions should be overwritten when importing new definitions with the same OID. The default is -nooverwrite. These options are used only when -import is specified.
-sequence	name	Save the DNs of schema entries in the output under the given sequence name and do not modify the current sequence. Sequence names may contain alphabetical characters only. If the sequence does not exist, it will be created. If the sequence exists, new DNs will be appended to the end of it. When this option is omitted, the DNs are added to the current sequence. This option is ignored when -import is specified.
	LDAP-specificOptions	See options in LDAP-Specific Options.

SEE ALSO

dsearch

DESCRIPTION

The dsearch command searches the directory for entries whose attributes match the filter in the given scope under the base DN. By default, only the DN or the relative DN of matching entries are displayed. Use -show along with the other options listed in Display Options to view selected attributes.

SYNTAX

dsearch
  [object]
  [-baseobject | -onelevel | -subtree]
  [-filter filter] [-[no]relative]
  [-matchedvaluesonly]
  [-[no]searchaliases] [-sequence name]
  [displayOptions] [LDAP-specificOptions]

OPTIONS

Table 33-16 dsearch Options
Option	Parameter	Purpose
	object	Specify the DN of the base entry for the search. The default is the current location.
-baseobject -onelevel -subtree		Specify the scope of the search: either the base entry itself, only the immediate children of the base entry, or the entire subtree rooted at the base entry. The three scope options are mutually exclusive. The default is -subtree.
-filter	filter	Specify an RFC 2254-compliant LDAP search filter, usually in double quotes ("") for the interpreter (see “LDAP Search Filters” in Chapter 4 of the Sun ONE Directory Server Getting Started Guide).
-relative -norelative		Specify whether or not the DNs in the output are shown in their relative or full format. Relative DNs are relative to the base entry of the search, not to the current location. The default is -relative.
-matchedvaluesonly		Specify that only attributes being matched by the search filter should be returned in matching entries. This functionality depends on a control that the directory server must support. By default, this option is not active.
-searchaliases -nosearchaliases		Specify whether or not aliases in the search scope are dereferenced before applying the filter. The default is -nosearchaliases. These options are different from the -[dont]dereference options listed in LDAP-Specific Options. The latter apply only to aliases encountered when determining the base entry given by the target object, as opposed to the entries being searched in the scope.
-sequence	name	Save the DNs of entries from the output under the given sequence name and do not modify the current sequence. Sequence names may contain alphabetical characters only. If the sequence does not exist, it will be created. If the sequence exists, new DNs will be appended to the end of it. When this option is omitted, the DNs are appended to the current sequence.
	displayOptions	See options in Display Options.
	LDAP-specificOptions	See options in LDAP-Specific Options.

EXAMPLE

The following search returns the full name and telephone number of all entries with a last name (surname sn) that starts with J. It stores the reference to the corresponding DNs in the sequence also named J as in Code Example 33-5.

[The World]% dsearch "dc=Example,dc=com" -filter "sn=J*" \
-show -type cn telephonenumber \
-sequence J

Code Example 33-5 dsearch Results


J.1 uid=bjablons, ou=People,
cn: Barbara Jablonski
telephoneNumber: +1 408 555 8815
J.2 uid=ejohnson, ou=People,
cn: Emanuel Johnson
telephoneNumber: +1 408 555 3287
J.3 uid=kjensen, ou=People,
cn: Kurt Jensen
telephoneNumber: +1 408 555 6127
J.4 uid=bjensen, ou=People,
cn: Barbara Jensen
cn: Babs Jensen
telephoneNumber: +1 408 555 1862

dseq

dsequence

DESCRIPTION

The dsequence command manages sequences and their contents, allowing you to swap the current sequence for another. The current sequence is the one to which dlist, dschema and dsearch results will be appended by default. You may refer to entries in the current sequence simply by giving their number on a command-line. Entries are not duplicated in any one sequence, so an entry will always have the same number.


Note	An introduction to sequences can be found in The Sequence in Chapter 32, "ilash: The LDAP Administrative Shell."

When the ilash interpreter is launched, the name of the current sequence is default. The dlist, dschema and dsearch commands may create new sequences with their -sequence name option. Sequence names may contain only alphabetical characters. The command:

will make the named sequence the current one. If the named sequence does not exist, it will be created empty and still become the current sequence. The command by itself will display the name of the current sequence:

[Example,com]% dsequence
default
[Example,com]% dsequence mysearch
[Example,com]% dsequence
mysearch

The contents of the previously current sequence are still available under its name. You may refer to any sequence contents at any time with the following notation:

Use the -status option to view the number of entries in each sequence. Sequences without any entries are not listed by this option. Use the -reset option to delete a sequence:

[Example,com]% dsequence -status -all
47    entries in sequence <mysearch>
34    entries in sequence <default>
4     entries in sequence <J>

[Example,com]% dsequence -reset default
[Example,com]% dsequence -status -all
47 entries in sequence <mysearch>
4 entries in sequence <J>

Use the -iterate option to run the given Tcl code in the context of each entry. This command will change the current location to each of the entries in the sequence and interpret the code. The Tcl code may be a simple command or it may be a complete script that uses Tcl commands, ilash commands, or both.

SYNTAX

OPTIONS

Table 33-17 dsearch Options
Option	Parameter	Purpose
[-sequence]	name	The name of the target sequence for the chosen option. The default is the current sequence.
-all		Specify that the -reset or -status option apply to all sequences. This option is not compatible with -iterate.
-reset		Remove all entries from the specified sequence. After a sequence is reset, referring to any of its entries will return an error. However, the name may be reused to create another sequence.
-status		List the number of entries, if any, in the specified list.
-iterate	TclCode	Interpret the TclCode in the context of every entry in the list. The command will set the current location to each of the entry locations in turn and interpret the TclCode in that context.

SYNONYMS

dshow

dshowentry

DESCRIPTION

The dshowentry command will show the attributes contained in the given entry and optionally change the current location. Use this command along with dlist, dshowname, and dmoveto, or their synonyms dls, dpwd, and dcd respectively, to navigate through the directory and view its contents.

The displayOptions will control the output by allowing you to select the set of attributes to display. The LDAP-specific options will control how internal operations access the directory, such as dereferencing aliases or not when accessing the target entry.

SYNTAX

dshowentry
  [object ...] [-[no]name]
  [-[no]move] [-[no]push]
  [displayOptions] [LDAP-specificOptions]

OPTIONS

Table 33-18 dshowentry Options
Option	Parameter	Purpose
	object ...	Specify one or more objects to display. The default is the entry at the current location.
-name -noname		Specify whether or not to display the DN (distinguished name) of the entry before its contents. The default is -name.
-move -nomove		Specify whether or not the command should also change the current location to that of the target object. The -nomove option overrides -move and -push when it occurs after them on the command-line. The default behavior is -nomove.
-push -nopush		Specify whether or not the command should push the current location onto the location stack and change to the location of the target object. When showing multiple entries, they will be pushed onto the stack in the order given. The -push option is overridden by -move and -nomove when they occur after it on the command-line. The default is -nopush.
	displayOptions	See other options in Display Options.
	LDAP-specificOptions	See options in LDAP-Specific Options.

SYNONYMS

SEE ALSO

dshown

dshowname

DESCRIPTION

The dshowname command will display the full distinguished name of the target entry. Use this command on a sequence number to see the DN of the corresponding entry in the sequence. The “user-friendly” display of the -ufn option is equivalent to the format used in the ilash command prompt.

SYNTAX

OPTIONS

EXAMPLE

SYNONYMS

Table 33-19 dshowname
Option	Parameter	Purpose
	object	Specify the object whose DN you wish to display. The default is the current location.
-ufn -ldap		Display the name in the “user-friendly” format defined by RFC 1781 or in full DN format specified by LDAP. The user-friendly format removes the attribute names from the DN to leave the values separated by commas. The default is -ldap.

dstatus

DESCRIPTION

The dstatus command displays information about the connection and the configuration of the currently bound directory server. When used without any options, it shows the status of the ilash interpreter, such as the current location and the current sequence. You may specify any number of options to list all of the configuration information at one time.

SYNTAX

dstatus
  [-user] [-[no]stats] [-[no]session]
  [-[no]controls] [-[no]extensions] [-[no]config]
  [-[no]syntax]

OPTIONS

Table 33-20 dstatus Options
Option	Parameter	Purpose
-user		Display the bind DN used for the current connection.
-session		Display the status of the ilash interpreter. This includes the directory URL, the bind DN, the authentication level, the current location and the current sequence name. This is the default output when no option is specified.
-stats		Display the directory usage statistics if supported by the server.
-controls		List the OIDs of controls supported by the server. The list includes brief description of each control, if known.
-extensions		List the OIDs of extensions supported by the server. The list includes a brief description of each extension, if known.
-config		Display the configuration information published by the server. This includes schema entry DN and information about naming contexts on the server. Information not supported is left blank.
-syntax		Displays the list of OIDs for all attribute syntaxes used in the schema of the current directory.

EXAMPLE

[Example,com]% dstatus
Connected to : ldap://ldap.Example.com:389/
Current position : dc=Example,dc=com
User name : cn=directory manager
Current sequence : mysearch
Authentication level : simple

SYNONYMS

dunbind

Close the connection to the current directory and optionally exit the ilash tool.

DESCRIPTION

The dunbind command closes the current connection. If you do not use the -quit option, the ilash tool will be in the unbound state. Call the dbind command to bind to another server or to rebind to the same server as a different user.

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