15.3 Using LDAP Tools on Linux

eDirectory includes the following LDAP tools, stored in /opt/novell/eDirectory/bin, to help you manage the LDAP directory server.

Tool

Description

ice

Imports entries from a file to an LDAP directory, modifies the entries in a directory from a file, exports the entries to a file, and adds attribute and class definitions from a file.

ldapadd

Adds new entries to an LDAP directory.

ldapdelete

Deletes entries from an LDAP directory server. The ldapdelete tool opens a connection to an LDAP server, binds, and deletes one or more entries.

ldapmodify

Opens a connection to an LDAP server, binds, and modifies or adds entries.

ldapmodrdn

Modifies the relative distinguished name (RDN) of entries in an LDAP directory server. Opens a connection to an LDAP server, binds, and modifies the RDN of entries.

ldapsearch

Searches entries in an LDAP directory server. Opens a connection to an LDAP server, binds, and performs a search using the specified filter. The filter should conform to the string representation for LDAP filters as defined in RFC 2254.

ndsindex

Creates, lists, suspends, resumes, or deletes indexes.

For more information, see “LDAP Tools” in the LDAP Libraries for C Doc.

To perform secure LDAP tools operations, refer to Ensuring Secure eDirectory Operations on Linux Computers and include the DER file in all command line LDAP operations that establish secure LDAP connections to eDirectory.

15.3.1 LDAP Tools

The LDAP utilities can be used to delete entries, modify entries, add entries, extend the schema, modify relative distinguished names, move entries to new containers, create search indexes, or perform searches.

NOTE:In compliance with RFC 2256, the LDAP interface of eDirectory only allows binds to occur with passwords up to 128 characters in length. Also, passwords can only be set to have up to 128 characters when set through LDAP.

ldapadd

The ldapadd utility adds new entries. It has the following syntax:

ldapadd [-c] [-C] [-l] [-M] [-P] [-r] [-n] [-v] [-F] [-l limit] [-M[M]] [-d  debuglevel] [-e key filename] [-D  binddn] [[-W]| [-w passwd]] [-h  ldaphost] [-p ldapport] [-P version] [-Z[Z]] [-f file]

If the -f option is specified, ldapadd reads the modifications from a file. If the -f option is not specified, ldapadd reads the modifications from stdin.

HINT:Output from the LDAP utilities is sent to stdout. If the utility exits before you can view the output, redirect the output to a file. For example, ldapadd [options] > out.txt.

Option

Description

-a

Adds new entries. The default for ldapmodify is to modify existing entries. If invoked as ldapadd, this flag is always set.

-r

Replaces existing values by default.

-c

Continuous operation mode. Errors are reported, but ldapmodify will continue with modifications. The default is to exit after reporting an error.

-f file

Reads the entry modification information from an LDIF file instead of from standard input. The maximum length of a record is 4096 lines.

-F

Forces the application of all changes regardless of the contents of input lines that begin with replica:. By default, replica: lines are compared against the LDAP server host and port in use to decide if a replog record should actually be applied.

Common Options for All LDAP Tools

There are some options that are common to all LDAP tools. These are listed in the following table:

Option

Description

-C

Enables referral following (anonymous bind).

-d debuglevel

Sets the LDAP debugging level to debuglevel. The ldapmodify tool must be compiled with LDAP_DEBUG defined for this option to have any effect.

-D binddn

Uses binddn to bind to the LDAP directory. binddn should be a string-represented DN as defined in RFC 1779.

-e key filename

Files the certificate filename for SSL bind.

-f file

Reads a series of lines from file, performing one LDAP search for each line. In this case, the filter given on the command line is treated as a pattern, where the first occurrence of %s is replaced with a line from the file. If the file is a single hyphen (-) character, then the lines are read from standard input.

-h ldaphost

Specifies an alternate host on which the LDAP server is running.

-l limit

Specifies the connection timeout (in seconds).

-M

Enables Manage DSA IT control (non-critical).

-MM

Enables Manage DSA IT control (critical).

-n

Shows what would be done, but does not actually modify entries. Useful for debugging in conjunction with -v.

-p ldapport

Specifies an alternate TCP™ port where the LDAP server is listening.

-P version

Specifies the LDAP version (2 or 3).

-v

Uses verbose mode with many diagnostics written to standard output.

-w passwd

Uses passwd as the password for simple authentication.

-W

Prompts for simple authentication. This option is used instead of specifying the password on the command line.

-Z

Starts TLS before binding to perform the operation. If an error occurs during the Start TLS operation the error is ignored and the operation continues. It is recommended that the -ZZ option be used in place of this option to cause the operation to abort if an error occurs.

If a port is specified with this option, it must accept clear text connections.

To verify the server identity, this option should be used in conjunction with the -e option to specify a server certificate file. This validates the server trusted root certificate when TLS is started. If the -e option is not specified, any certificate from the server is accepted.

-ZZ

Starts TLS before binding to perform the operation. If an error occurs during the Start TLS operation, the operation is aborted.

If a port is specified with this option, it must accept clear text connections.

To verify server identity, this option should be used in conjunction with the -e option to specify a server certificate file. This validates the server trusted root certificate when TLS is started. If the -e option is not specified, any certificate from the server is accepted.

Examples

Assume that the file /tmp/entrymods exists and has the following contents:

dn: cn=Modify Me, o=University of Michigan, c=US
changetype: modify
replace: mail
mail: modme@terminator.rs.itd.umich.edu
-
add: title
title: Manager
-
add: jpegPhoto
jpegPhoto: /tmp/modme.jpeg
-
delete: description
-

In this case, the command ldapmodify -b -r -f /tmp/entrymods will replace the contents of the Modify Me entry’s mail attribute with the value modme@terminator.rs.itd.umich.edu, add a title of Manager, add the contents of the file /tmp/modme.jpeg as a jpegPhoto, and completely remove the description attribute.

The same modifications as above can be performed using the older ldapmodify input format:

cn=Modify Me, o=University of Michigan, c=US
mail=modme@terminator.rs.itd.umich.edu
+title=Manager
+jpegPhoto=/tmp/modme.jpeg
-description

and the command:

ldapmodify -b -r -f /tmp/entrymods

Assume that the file /tmp/newentry exists and has the following contents:

dn: cn=Barbara Jensen, o=University of Michigan, c=US
objectClass: person
cn: Barbara Jensen
cn: B Jensen
sn: Jensen
title: Manager
mail: bjensen@terminator.rs.itd.umich.edu
uid: bjensen

In this case, the command ldapadd -f /tmp/entrymods will add a new entry for B Jensen, using the values from the file /tmp/newentry.

Assume that the file /tmp/newentry exists and has the following contents:

dn: cn=Barbara Jensen, o=University of Michigan, c=US
changetype: delete

In this case, the command ldapmodify -f /tmp/entrymods will remove B Jensen’s entry.

ldapdelete

The ldapdelete utility deletes the specified entry. It opens a connection to an LDAP server, binds, and then deletes. It has the following syntax:

ldapdelete [-n] [-v] [-c] [-r] [-l] [-C] [-M] [-d debuglevel] [-e key filename] [-f file] [-D binddn] [[-W]| [-w passwd]] [-h ldaphost] [-p ldapport] [-Z[Z]] [dn]...

The dn parameter is a list of distinguished names of the entries to be deleted.

It interacts with the -f option in the following ways:

  • If the -f option is missing from the command line, and DNs are specified on the command line, the utility deletes the specified entries.

  • If both dn and the -f option are in the command line, the utility reads the file for the DNs to delete and ignores any DNs in the command line.

  • If both dn and the -f option are missing in the command line, the utility reads the DN from stdin.

HINT:Output from the LDAP utilities is sent to stdout. If the utility exits before you can view the output, redirect the output to a file, for example, ldapdelete [options] > out.txt.

Option

Description

-c

Continuous operation mode. Errors are reported, but ldapdelete will continue with deletions. The default is to exit after reporting an error.

-f file

Reads a series of lines from the file, performing one LDAP search for each line. In this case, the filter given on the command line is treated as a pattern, where the first occurrence of %s is replaced with a line from the file.

-r

Delete recursively.

NOTE:Refer to Common Options for All LDAP Tools for more details on common options.

Example

The command ldapdelete "cn=Delete Me, o=University of Michigan, c=US" will attempt to delete the entry named with the commonName Delete Me directly below the University of Michigan organizational entry. In this case, it would be necessary to supply a binddn and passwd for the deletion to be allowed (see the -D and -w options).

ldapmodify

The ldapmodify utility modifies the attributes of an existing entry or adds new entries. It has the following syntax:

ldapmodify [-a] [-c] [-C] [-M] [-P] [-r] [-n] [-v] [-F] [-l limit] [-M[M]] [-d debuglevel] [-e key filename] [-D binddn] [[-W]|[-w passwd]] [-h ldaphost] [-p ldap-port] [-P version] [-Z[Z]] [-f file]

If the -f option is specified, ldapmodify reads the modifications from a file. If the -f option is not specified, ldapmodify reads the modifications from stdin.

HINT:Output from the LDAP utilities is sent to stdout. If the utility exits before you can view the output, redirect the output to a file. For example, ldapmodify [options] > out.txt.

Option

Description

-a

Adds new entries. The default for ldapmodify is to modify existing entries. If invoked as ldapadd, this flag is always set.

-r

Replaces existing values by default.

-c

Continuous operation mode. Errors are reported, but ldapmodify will continue with modifications. The default is to exit after reporting an error.

-f file

Reads the entry modification information from an LDIF file instead of from standard input. The maximum length of a record is 4096 lines.

-F

Forces the application of all changes regardless of the contents of input lines that begin with replica:. By default, replica: lines are compared against the LDAP server host and port in use to decide if a replog record should actually be applied.

NOTE:Refer to Common Options for All LDAP Tools for more details on common options.

ldapmodrdn

The ldapmodrdn modifies the relative distinguished name of an entry. It can also move the entry to a new container. It has the following syntax:

ldapmodrdn [-r] [-n] [-v] [-c] [-C] [-l] [-M] [-s newsuperior] [-d debuglevel] [-e key filename] [-D binddn] [[-W]|[-w  passwd]]  [-h ldaphost] [-p ldapport] [-Z[Z]] [-f file] [dn newrdn]

NOTE:Output from the LDAP utilities is sent to stdout. If the utility exits before you can view the output, redirect the output to a file. For example, ldapmodrdn [options] > out.txt.

Option

Description

-c

Continuous operation mode. Errors are reported, but ldapmodify will continue with modifications. The default is to exit after reporting an error.

-f file

Reads the entry modification information from the file instead of from standard input or the command line. Make sure that there are no blank lines between the old RDN and new RDN, or the -f option will fail.

-r

Removes old RDN values from the entry. The default is to keep old values.

-s newsuperior

Specifies the distinguished name of the container to which the entry is moving.

NOTE:Refer to Common Options for All LDAP Tools for more details on common options.

Example

Assume that the file /tmp/entrymods exists and has the following contents:

cn=Modify Me, o=University of Michigan, c=US
cn=The New Me

ldapsearch

The ldapsearch utility searches the directory for specified attributes and object classes. It has the following syntax:

ldapsearch [-n] [-u] [-v] [-t] [-A] [-T] [-C] [-V] [-M] [-P] [-L] [-d debuglevel] [-e key filename] [-f file] [-D binddn] [[-W]| [-w bindpasswd]] [-h ldaphost] [-p ldapport] [-b searchbase] [-s scope] [-a deref] [-l time limit] [-z size limit] [-Z[Z]] filter [attrs....]

The ldapsearch tool opens a connection to an LDAP server, binds, and performs a search using the filter. The filter should conform to the string representation for LDAP filters as defined in RFC 2254.

If ldapsearch finds one or more entries, the attributes specified by attrs are retrieved and the entries and values are printed to standard output. If no attributes are listed, all attributes are returned.

HINT:Output from the LDAP utilities is sent to stdout. If the utility exits before you can view the output, redirect the output to a file. For example, ldapsearch [options] filter [attribute list] > out.txt.

Option

Description

-a deref

Specifies how to handle the dereferencing of an alias. It uses the following values:

  • Never: Aliases are never dereferenced while locating the base object or searching.

  • Always: Aliases are always dereferenced when locating the base object and searching.

  • Search: Aliases are dereferenced when searching subordinates of the base object but not when locating the base object.

  • Find: Aliases are dereferenced when locating the base object but not when searching for the subordinates of the base object.

-A

Retrieves attributes only (no values). This is useful when you want to see if an attribute is present in an entry and when you are not interested in the specific values.

-CC

Enables referral following (authenticated bind with same bind DN and password).

-b searchbase

Use searchbase as the starting point for the search.

-L

Prints entries in the LDIF format.

-LL

Prints entries in the LDIF format without comments.

-LLL

Prints entries in the LDIF format without comments and version.

-s scope

Specifies the scope of the search. Scope should be base, one, or sub to specify a base object, one-level, or subtree search. The default is sub.

-S attribute

Sorts the entries returned, based on attribute. The default is not to sort entries returned. If an attribute is a zero-length string (" "), the entries are sorted by the components of their distinguished name. See ldap_sort for more details. ldapsearch normally prints out entries as it receives them. The use of the -S option defeats this behavior, causing all entries to be retrieved, sorted, and then printed.

-t

Writes retrieved binary values to a set of temporary files. This is useful for dealing with non-ASCII values such as jpegPhoto or audio.

-tt

Writes all values to temporary files.

-T path

Writes files to directory specified by path (default: /tmp).

-u

Includes the user-friendly form of the distinguished name (DN) in the output.

-V

URL prefix for files.

-V prefix

Specifies the URL prefix for files (default: file://tmp/).

-z sizelimit

Waits at most sizelimit entries for a search to complete.

NOTE:Refer to Common Options for All LDAP Tools for more details on common options.

Examples

The following command:

ldapsearch "cn=mark smith" cn telephoneNumber

will perform a subtree search (using the default search base) for entries with a commonName of mark smith. The commonName and telephoneNumber values will be retrieved and printed to standard output. The output might look like the following if two entries are found:

cn=Mark D Smith, ou="College of Literature, Science, and the Arts", ou=Students, ou=People, o=University of Michigan, c=US
cn=Mark Smith
cn=Mark David Smith
cn=Mark D Smith 1
cn=Mark D Smith
telephoneNumber=+1 313 930-9489
cn=Mark C Smith, ou=Information Technology Division, ou=Faculty and Staff, ou=People,o=University of Michigan, c=US
cn=Mark Smith
cn=Mark C Smith 1
cn=Mark C Smith
telephoneNumber=+1 313 764-2277

The command:

ldapsearch -u -t "uid=mcs" jpegPhoto audio

will perform a subtree search using the default search base for entries with user IDs of mcs. The user-friendly form of the entry’s DN will be output after the line that contains the DN itself, and the jpegPhoto and audio values will be retrieved and written to temporary files. The output might look like the following if one entry with one value for each of the requested attributes is found:

cn=Mark C Smith, ou=Information Technology Division, ou=Faculty and Staff, ou=People, o=University of Michigan, c=US
Mark C Smith, Information Technology Division, Faculty and Staff, People, University of Michigan, US
audio=/tmp/ldapsearch-audio-a19924
jpegPhoto=/tmp/ldapsearch-jpegPhoto-a19924

The following command will perform a one-level search at the c=US level for all organizations whose organizationName begins with university.:

ldapsearch -L -s one -b "c=US" "o=university*" o description

Search results will be displayed in the LDIF format. The organizationName and description attribute values will be retrieved and printed to standard output, resulting in output similar to the following:

dn: o=University of Alaska Fairbanks, c=US
o: University of Alaska Fairbanks
description: Preparing Alaska for a brave new yesterday.
description: leaf node only
dn: o=University of Colorado at Boulder, c=US
o: University of Colorado at Boulder
description: No personnel information
description: Institution of education and research
dn: o=University of Colorado at Denver, c=US
o: University of Colorado at D

ndsindex

The ndsindex utility creates, lists, suspends, resumes, or deletes indexes and compound indexes. You can specify multiple attributes separated by $ sign in the ndsindex utility for compound index. It has the following syntax:

NOTE:You can specify up to 10 attributes for compound index. NetIQ recommends you to enter up to 3 attributes for better performance.

ndsindex list [-h <hostname>] [-p <port>] -D <bind DN> -W|[-w <password>] [-l limit] -s <eDirectory Server DN> [-Z[Z]] [<indexName1>, <indexName2>.....]
ndsindex add [-h <hostname>] [-p <port>] -D <bind DN> -W|[-w <password>] [-l limit] -s <eDirectory Server DN> [-Z[Z]] <indexDefinintion1> [<indexDefinintion2>.....]
ndsindex delete [-h <hostname>] [-p <port>] -D <bind DN> -W|[-w <password>] [-l limit] -s <eDirectory Server DN> [-Z[Z]] <indexName1> [<indexName2>.....]
ndsindex resume [-h <hostname>] [-p <port>] -D <bind DN> -W|[-w <password>] [-l limit] -s <eDirectory Server DN> [-Z[Z]] <indexName1> [<indexName2>.....]
ndsindex suspend [-h <hostname>] [-p <port>] -D <bind DN> -W|[-w <password>] [-l limit] -s <eDirectory Server DN> [-Z[Z]] <indexName1> [<indexName2>.....]

Option

Description

list

Lists the specified indexes. If the index is not specified, ndsindex lists all existing indexes on the server.

add

Creates new indexes.

delete

Deletes the specified indexes.

resume

Resumes the specified indexes from an off-line state.

suspend

Suspends the specified indexes to an off-line state.

-s eDirectory Server DN

Specifies the eDirectory Server DN.

NOTE:Refer to Common Options for All LDAP Tools for more details on common options.

Examples

To list the indexes on the server MyHost, enter the following command:

ndsindex list -h MyHost -D cn=admin,o=mycompany -w password -s cn=MyHost,o=novell

To create a substring index with the name MyIndex on the email address attribute, enter the following command:

ndsindex add -h myhost -D cn=admin, o=mycompany -w password -s cn=myhost, o=novell "MyIndex;email address;substring"

To create a value index with the name MyIndex on the city attribute, enter the following command:

ndsindex add -h myhost -D cn=admin,o=mycompany -w password -s cn=myhost,o=novell "MyIndex;city;value"

To create a presence index with the name MyIndex on the homephone attribute, enter the following command:

ndsindex add -h myhost -D cn=admin,o=mycompany -w password -s cn=myhost,o=novell "MyIndex;homephone;presence"

To delete the index named MyIndex, enter the following command:

ndsindex delete -h myhost -D cn=admin,o=mycompany -w password -s cn=myhost,o=novell MyIndex

To suspend the index named MyIndex, enter the following command:

ndsindex suspend -h myhost -D cn=admin,o=mycompany -w password -s cn=myhost,o=novell MyIndex

To resume the index named MyIndex, enter the following command:

ndsindex resume -h myhost -D cn=admin,o=mycompany -w password -s cn=myhost,o=novell MyIndex

Examples for Compound Indexes

To create a value index with the name MyIndex on the email address and surname attribute, enter the following command:

ndsindex add –h myhost –D cn=admin, o=mycompany –w password –s cn=myhost, o=netiq “MyIndex;email address$surname;value