Previous PageNext Page

Chapter 4 - LDAP Command Line Tools

This chapter describes how to use LDAP for StreetTalk command line tools to manage entries in the LDAP database. Generally, you use LDAP Configuration Manager to manage your LDAP for StreetTalk service and you use the command line tools to manage the LDAP database.

The command line tools let you use batch file command processing to perform repeated operations programmatically, such as deleting, modifying, or adding multiple entries, or comparing an attribute value against many entries.

LDAP for StreetTalk includes five command line tools (if you choose to install them):

ldsearch -- Searches the LDAP directory.

ldapdel - Deletes one or more LDAP entries.

ldapmod -- Modifies one or more LDAP entries. Can also be used to add entries to the LDAP directory.

ldmodrdn -- Changes the Relative Distinguished Name (RDN) of a distinguished name.

ldcomp - Tests an asserted attribute value against the attribute value in an LDAP entry.

When you install LDAP for StreetTalk software on your server, the installation program stores the command line tools in the folder \Program Files\Banyan\Support\LDAP on your default hard disk drive, or in the folder you chose while installing LDAP for StreetTalk. The storage location is the same when you install the LDAP command line tools during a custom installation of LDAP for StreetTalk.

LDAP Data Interchange Format

In many cases you may want to represent LDAP information in a text file format. LDAP Data Interchange Format (LDIF) was created to provide a common, all-around file format for directory information to be transferred between LDAP applications and platforms. LDAP command line tools support the LDIF format:

ldsearch outputs results in LDIF
ldapmod accepts input data in LDIF
ldapdel accepts input data in LDIF
ldmodrdn accepts input data in LDIF
ldcomp accepts input data in LDIF

LDIF files consist of entries, separated by empty lines. Each entry in an LDIF file is:

[id]

dn: entryDN

attributetype: attribute value

...

attributetype: attribute value

where

id is an optional LDAP entry numerical identifier that is not used by LDAP tools

entryDN is the LDAP Distinguished Name of the directory entry

attributetype is an LDAP attribute, such as cn or person or mail

attributevalue is the value or string for attributetype

You can include as many attributetype: attributevalue lines as you need to represent the attribute values in an entry. To continue a line on to the next line, use a single space or tab character to start the next line. For example, the following lines present an LDIF file that contains Mary Dawes' entry that comprises 6 attributes:

dn: cn=Mary Dawes, ou=Finance, o=WCTUS2, l=Boston, o=WCT, c=US

cn: Mary Dawes

sn: Dawes

title: Account Rep

mail: mdawes@wctus2.com

homepostaladdress: Mary Dawes Apartment 3G 123 Main Street Any
town AnyState 01234

objectclass: top

The value for homepostaladdress is extended across two lines by inserting a single space character to start the line that begins "town...."

For further details about LDIF, refer to Internet draft draft-good-ldap-ldif03.txt or any textbook about LDAP.

ldsearch

The ldsearch command opens a connection to the LDAP for StreetTalk server and performs a search operation in the LDAP database. The syntax for ldsearch is:

ldsearch [options] filter [attributes]

where

options include zero or more command line options as listed in "ldsearch Command Switches."

filter is an LDAP search filter as defined in "Defining a Search Operation" that follows.

attributes is an optional list of the attributes to return during the search.

For example:

ldsearch -v -s scope -b searchbase -h servername -D "cn=common_name,
ou=organizational_unit, o=organization, l=locality, c=country" -w "password"
"(filter)" return values

The ldsearch command is intended primarily for administrators to test their databases.

ldsearch Command Switches

The ldsearch command uses the following switches:

-v specifies verbose mode; comments and dialogue display.
-s specifies the scope of the search. Used in conjunction with the -b switch. Values for scope are:

— base - Searches only the level (or searchbase) specified with the -b switch.

— onelevel -- Searches one level below the searchbase specified.

— subtree -- Searches all levels below the searchbase specified. This search ends at the leaf node. Refer to Appendix B for details about leaf nodes and directory trees.

-b specifies the searchbase to use for a starting point. Searchbase is the Distinguished Name (DN) at which to begin the desired search. You can specify the entire LDAP directory tree that resides on the server you are searching, or you can specify a portion of it.
-h specifies the name of the server. This can be either the server name or the TCP/IP address.
-D specifies the distinguished name of an account to connect to an LDAP service. You do not need an account to search the LDAP for StreetTalk database. Use -D to specify a NULL string for anonymous searches.

You can search any remote system that can communicate, using TCP\IP, with the server you use to enter the ldsearch command.

-w specifies the StreetTalk password. Specifying a null password validates an anonymous user. Anonymous users are granted read-only access to the LDAP database. If you do not specify -w, LDAP for StreetTalk uses an anonymous account.
filter specifies the criteria for the search. Refer to "Search Filters" below.
return values specifies the list of attributes, arranged one attribute per line, to return. If you do not specify a list of attributes, ldsearch returns all user attributes.

Enter the command ldsearch with no switches to see a list of available switches.

Defining a Search Operation

To define a search operation, specify the search filter and the list of attributes to return. You can put the ldsearch command line in a batch file and direct output to a file. Use the -C option to do this, for example, -C filename.

Search Filters

The search filter is a qualifier that you enter as part of the ldsearch command. The search filter controls which items are matched from the directory search. Search filters conform to the following format:

attribute operator value

For example, the following filter uses the cn attribute and the = operator to search the directory tree for the value Doug (cn=Doug) and return the common name (cn), description, and objectClass attributes associated with each matching directory entry:

ldsearch -v -s subtree -b "ou=Finance, o=WCTUS1, l=Boston, o=WCT, c=US"
-h mkt_server -D "cn=anomynous, ou=Finance, o=WCTUS1 l=Boston, o=WCT c=US"
-w "" "(cn=doug)" cn description objectClass

cn=Doug Ross, ou= Finance, o= WCTUS1, l= Boston, o= WCT, c=US
Doug Ross, Finance, WCTUS1, Boston, WCT, US
description=Accountant
objectClass=person

List of Attributes to Return

The list of attributes to return is a list of attributes that you specify, after the search filter, as part of the ldsearch command. The return values specify which attributes, returned from the directory search, display for the end user.

In the following example, the filter locates all directory entries that match cn=doug. The attributes returned include cn (common name), title, and objectClass.

ldsearch -v -s subtree -b "ou=Finance, o=Division 1, l=Boston, o=Acme HQ, c=US"
-h mkt_server -D "" -w "" "(cn=doug)" cn title objectClass

cn: Doug Ross
title: Accountant
objectClass: person

Simple Search Operations

LDAP for StreetTalk service supports the following simple operations:

Equal to (=)
Presence (=*)
Greater than or equal to (>=)
Less than or equal to (<=)
Approximately equal to (~=)

Equal To Operations

An equality operation returns all directory entries that contain an attribute set to a specific value. For example, the filter cn = Doug Ross returns all directory entries containing the cn attribute with a value of Doug Ross. Filters can also specify a matching substring. The filter cn=D*R* returns a wider range of entries, for example, Doug Ross, Dave Reynolds, and Dee Richards.

Presence Operations

A presence operation returns all directory entries that contain the attribute. For example, the filter cn=* returns every entry in the database that contains the common name (cn) attribute.

Greater Than or Equal To Operations

A greater than or equal to operation returns all directory entries that contain an attribute greater than or equal to a specific value. For example, the filter income >= 50000 returns every directory entry that contains an attribute, income, set to a value greater than or equal to 50000.

Less Than or Equal To Operations

A less than or equal to operation returns all directory entries that contain an attribute less than or equal to a specific value. For example, the filter income<=50000 returns every directory entry that contains an attribute, income, set to a value less than or equal to 50000.

Approximately Equal To Operations

An approximate operation returns all directory entries containing an attribute with a value approximately equal to, or "sounds like," a specific value. For example, the filter cn~=Cindy Burns returns entries containing the common name (cn) attribute with values set to strings such as Cindy Burns, Syndee Burns, and Cindi Berns.

Using Complex Search Filters

LDAP for StreetTalk service supports searches using complex filters. Complex filters are search operations that include a Boolean operator and multiple search filters.

Boolean Operators

Three statements are available for Boolean operations:

AND or &
OR or |
NOT or !

You can use the Boolean operators alone or in combination, as described in the following sections.

Format

Multiple search operations conform to the following format:

(boolean_operator (filter1) (filter2) ...(filtern))

For example, the following filter returns all entries with an attribute of faxNumber that also include area code 508:

(&(faxNumber=*)(faxNumber=508*))

LDAP for StreetTalk service also supports filters that use complex Boolean expressions. Operations that use complex Boolean expressions conform to the following:

(boolean_operator(boolean_operator(filter)(filter)...))

For example, the following filter returns all directory entries that are not organizationalPersons with incomes less than 50000:

(&(!(objectClass=organizationalPerson))(income<=50000))

AND Operations

AND (&) statements are true if all specified filters are true. Directory entries that have attributes that match all filters specified by the AND statement are returned. For example, the following statement returns only directory entries with a cn attribute set to Doug Ross who have the title Engineer:

(&(cn=Doug Ross)(Title=Engineer))

OR Operations

OR (|) statements are true if only one of the specified filters is true. Directory entries that match one of the filters specified by the OR statement are returned. For example, the following statement returns all directory entries with an cn attribute Doug Ross, or all directory entries with a title attribute Engineer.

(|(cn=Doug Ross)(title=Engineer))

NOT Operations

NOT (!) statements are true if the specified statement is not true. For example, the following statement returns all directory entries with attributes that are not Doug Ross or Engineer:

(! (|(cn=Doug Ross) (title=Engineer)))

NOT applies to a single filter only, not to multiple filters. For example, the above is a single filter but in a statement such as the following, NOT (!) applies to filter1.

(! (filter1) (filter2) )

ldapmod

The ldapmod command opens a connection to the LDAP for StreetTalk server and performs a modify operation on entries in the LDAP directory. The syntax for ldapmod is:

ldapmod -[options] [-f file | <entryfile]

where

options includes zero or more command line options as listed below.

-f file perform the sequence of changes listed in file.

entryfile perform the sequence of changes listed in entryfile.

ldapmod Command Switches

The ldapmod command uses the following switches:

-a specifies that entries be added to the directory. Default is to modify entries.
-b specifies that values for binary attributes should be read from files .
-c specifies continuous operation mode. Report errors but continue to process the modification changes. If you do not specify this option, ldapmod exits when an error occurs.
-r specifies that the modification operation replaces attribute values rather than adding them.
-F forces all change records to be used.
-n specifies that LDAP show what would be done during the modify operation, but don't actually perform the modifications.
-v specifies verbose mode; comments and dialogue display.
-d level sets the LDAP debugging level to level. Levels range from 1 to 5, 1 being the least extensive and 5 the most comprehensive.
-D binddn specifies the distinguished name of an account to connect, or bind, to an LDAP service.
-w password specifies the password for simple authentication. Specifying a null password validates an anonymous user. Anonymous users are granted read-only access to the LDAP database. If you do not specify -w, LDAP for StreetTalk uses an anonymous account.
-h address specifies the name of the server. This can be either the server name or the TCPIP address.
-p ldapport connects to the LDAP server on the specified TCP/IP port ldapport. Unless specified otherwise, ldapmod connects to the standard LDAP port number 389.

Enter the command ldapmod with no switches to see a list of available switches.

Defining a Modification Operation

To define a modify operation, specify the command line options to use and the filename for the file that contains the modifications to perform. You can put the ldapmod command line in a batch file and direct output to a file.

Note
To add, modify, or delete an entry in the LDAP database, you must furnish a DN representation of a StreetTalk user name and password in the LDAP command. You must include the -D DN and -w password switches in the command line. Commands that do not include the -D and -w switch options are granted read-only access to the LDAP database.

For example, connect (bind) to the StreetTalk for LDAP service as Mary Dawes and delete the value "manager" from the attribute title in her entry, using an external file to specify the change desired.

ldapmod -v -w "password" -D "cn=mary dawes, o=WCTUS, l=Boston, c=US" -f change.in

where file change.in contains:

dn: cn=mary dawes, o=WCTUS, l=Boston, c=US
changetype: modify
delete: title
title: manager

You can use the ldapmod command to add entries to the LDAP database. By replacing the changetype: modify entry with changetype: add, and entering a DN that is not in the LDAP directory, LDAP for StreetTalk interprets the command as an "add" and uses the remainder of the command entry as the attributes and values for the new LDAP entry.

For example, bind as Mary Dawes and add an entry for Mike Marshall in Boston, using an external file to specify the additions desired.

ldapmod -v -w "password" -D "cn=mary dawes, o=WCTUS, l=Boston, c=US" -f add.in

where file add.in contains:

dn: cn=mike marshall, o=WCTUS, l=Boston, c=US
changetype: add
attribute:
value1
attribute:
value2
attribute:
value3

If you use the replace keyword (rather than delete or add as shown in the examples), and enter a DN that is in the LDAP directory, LDAP for StreetTalk replaces the specified attribute's value in the LDAP entry with the new value for the attribute. You can use "replace" when there is only one instance of the attribute to replace in the LDAP entry. To replace one instance of an attribute that has multiple values, delete the desired attribute value and add the new attribute value.

ldmodrdn

The ldmodrdn command opens a connection to the LDAP for StreetTalk server and performs a modify relative distinguished name operation, which results in changing the RDN of an entry. The syntax for ldmodrdn is:

ldmodrdn [options] [-f file | <entryfile] ][dn rdn]

where

options includes zero or more command line options as listed below.

-f file perform the sequence of searches listed in file.

entryfile perform the sequence of searches listed in entryfile.

dn is the distinguished name for the entry to be modified.

rdn is the new relative distinguished name for the entry.

The ldmodrdn command is intended primarily for administrators to test their databases.

ldmodrdn Command Switches

The ldmodrdn command uses the following switches:

-c specifies continuous operation mode. Report errors but continue to process the modification changes. If you do not specify this option, ldmodrdn exits when an error occurs.
-n specifies that LDAP show what would be done during the modify operation, but don't actually perform the modifications.
-v specifies verbose mode; comments and dialogue display.
-d level sets the LDAP debugging level to level. Levels range from 1 to 5, 1 being the least extensive and 5 the most comprehensive.
-D binddn specifies the distinguished name of an account to connect, or bind, to an LDAP service.
-w password specifies the password for simple authentication. Specifying a null password validates an anonymous user. Anonymous users are granted read-only access to the LDAP database. If you do not specify -w, LDAP for StreetTalk uses an anonymous account.
-h address specifies the name of the server. This can be either the server name or server TCP/IP address.
-p ldapport connects to the LDAP server on the specified TCP/IP port ldapport. Unless specified otherwise, ldmodrdn connects to the standard LDAP port number 389.

Enter the command ldmodrdn with no switches to see a list of available switches.

Defining a Modify RDN Operation

To define a modify RDN operation, specify the command line options to use, the distinguished name to change, and the new RDN for the DN. To make many changes at once, specify the filename for a file that contains the modifications to perform.

Note
To add, modify, or delete an entry in the LDAP database, you must furnish a DN representation of a StreetTalk user name and password in the LDAP command. You must include the -D DN and -w password switches in the command line. Commands that do not include the -D and -w switch options are granted read-only access to the LDAP database.

For example, bind as Mary Dawes and rename the entries for Jim Jones and Jennifer Jackson, using an external file to specify the change desired.

ldmodrdn -v -w "password" -D "cn=mary dawes, o=WCTUS, l=Boston, c=US" -f modrdn.in

where file modrdn.in contains:

cn=jim jones, o=WCTUS, l=Boston, c=US
cn=james jones
cn=jennifer jackson, o=WCTUS, l=Boston, c=US
cn=jenni jackson

You can put the ldmodrdn command line in a batch file and direct output to a file.

ldapdel

The ldapdel command opens a connection to the LDAP for StreetTalk server and performs a delete entry operation enabling the client to delete entries from the directory. The syntax for ldapdel is:

ldapdel [options] [dn...]

where

options includes zero or more command line options as listed below.

dn is one or more distinguished names for entries to be deleted.

The ldapdel command is intended primarily for administrators to test their databases.

ldapdel Command Switches

The ldapdel command uses the following switches:

-n specifies that LDAP show what would be done during the modify operation, but don't actually perform the modifications.
-v specifies verbose mode; comments and dialogue display.
-d level sets the LDAP debugging level to level. Levels range from 1 to 5, 1 being the least extensive and 5 the most comprehensive.
-D binddn specifies the distinguished name of an account to connect, or bind, to an LDAP service.
-f file performs the sequence of searches listed in file.
-w password specifies the password for simple authentication. Specifying a null password validates an anonymous user. Anonymous users are granted read-only access to the LDAP database. If you do not specify -w, LDAP for StreetTalk uses an anonymous account.
-h address specifies the name of the server. This can be either the server name or server TCP/IP address.
-p ldapport connects to the LDAP server on the specified TCP/IP port ldapport. Unless specified otherwise, ldapdel connects to the standard LDAP port number 389.

Enter the command ldapdel with no switches to see a list of available switches.

Defining a Delete Operation

To define an ldapdel operation, specify the command line options to use and the distinguished names to delete from the LDAP directory.

Note
To add, modify, or delete an entry in the LDAP database, you must furnish a DN representation of a StreetTalk user name and password in the LDAP command. You must include the -D DN and -w password switches in the command line. Commands that do not include the -D and -w switch options are granted read-only access to the LDAP database.

For example, bind as Mary Dawes and delete the entries for Jim Jones and Jennifer Jackson, using an external file to specify the change desired.

ldmodrdn -v -w "password" -D "cn=mary dawes, o=WCTUS, l=Boston, c=US" -f delete.in

where file delete.in contains:

cn=jim jones, o=WCTUS, l=Boston, c=US
dn=jennifer jackson, o=WCTUS, l=Boston, c=US

You can put the ldapdel command line in a batch file and direct output to a file.

ldcomp

The ldcomp command opens a connection to the LDAP for StreetTalk server and performs a compare operation to test the asserted value in the command against one or more LDAP entries. The syntax for ldcomp is:

ldcomp -[options] [dn] [value]

where

options includes zero or more command line options as listed below.

dn is the distinguished name of the entry to be compared against.

value is the attribute value to be compared.

The ldcomp command is intended primarily for administrators to test their databases.

ldcomp Command Switches

The ldcomp command uses the following switches:

-v specifies verbose mode; comments and dialogue display.
-R specifies that LDAP not follow referrals automatically.
-d level sets the LDAP debugging level to level. Levels range from 1 to 5, 1 being the least extensive and 5 the most comprehensive.
-D binddn specifies the distinguished name of an account to connect, or bind, to an LDAP service.
-f file performs the sequence of searches listed in file.
-w password specifies the password for simple authentication. Specifying a null password validates an anonymous user. Anonymous users are granted read-only access to the LDAP database. If you do not specify -w, LDAP for StreetTalk uses an anonymous account.
-h address specifies the name of the server. This can be either the server name or server TCP/IP address.
-p ldapport connects to the LDAP server on the specified TCP/IP port ldapport. Unless specified otherwise, ldcomp connects to the standard LDAP port number 389.

Enter the command ldcomp with no switches to see a list of available switches.

Defining a Compare Operation

To define a compare operation, specify command line options to use, the distinguished name to compare the attribute value against, and the attribute value to be compared.

For example, bind as Mary Dawes and compare the value of attribute title in the entries for James Jones and Jenni Jackson to the value "manager," using an external file to specify the desired comparison.

ldcomp -v -w "pasword" -D "cn=mary dawes, o=WCTUS, l=Boston, c=US" -f compare.in

where file compare.in contains:

cn=james jones, o=WCTUS, l=Boston, c=US
title: manager

cn=jenni jackson, o=WCTUS, l=Boston, c=US
title: manager

You can put the ldcomp command line in a batch file and direct output to a file.

Previous PageTop Of PageNext Page