Document revision date: 28 June 1999

You can modify directory entries using either the Users and Groups area of your administration server, or you can use the ldapmodify command line tool.

The Users and Groups area provides you with only essential modifications abilities. For more complex modification actions that involve a wider range of attributes and attribute values, use the ldapmodify command line tool.

If you are using the directory server to manage your users and groups, see the Directory Server Administrator's Guide for more information on performing directory modifications.

8.1 ldapmodify

You use ldapmodify to add, delete, or modify entries in your directory. You can use ldapmodify either with the directory server, or with a Netscape local directory that is bundled with the Netscape Administration Server.

You direct ldapmodify's actions through LDIF update statements.

You can find ldapmodify at this location under the Netscape Administration Server:

NSHOME\userdb\ldap\tools\ldapmodify

where NSHOME is the directory where you installed your Netscape Administration Server.

8.2 LDIF update statements

You use LDIF update statements to define how ldapmodify should change your directory. In general, LDIF update statements are a series of statements that:

• Specify the distinguished name of the entry to be modified.
• Specify a change type that defines how a specific entry is to be modified (add, delete, modify, or modrdn). Note that a changetype is required unless you specify the -a option. If you specify the -a option, then an add operation (changetype: add) is assumed. However, any other changetype will override the -a option. If you specify a modify operation (changetype: modify), a change operation is required that indicates how the entry should be changed.
  If you specify changetype: modrdn, change operations are required that specify how the RDN is to be modified. A distinguished name's RDN is the left-most value in the DN. For example, the distinguished name:

  uid=ssarette, o=Ace Industry, c=US

  
  has an RDN of uid=ssarette.

• Specify a series of attributes and their changed values. The general format of LDIF update statements is as follows:

  dn: distinguished name changetype identifier change operation identifier list of attributes ... - change operation identifier list of attributes ... - ...

  
  A dash (-) must be used to denote the end of a change operation if subsequent change operations are specified. For example, the following statement adds the telephone number and manager attributes to the entry:

  dn: cn=Lisa Jangles, ou=Sales, o=Ace Industry, c=US changetype: modify add: telephonenumber telephonenumber: (408) 555-2468 - add: manager manager: cn=Harry Cruise, ou=Manufacturing, o=Ace Industry, c=US

  
  In addition, the line continuation operator is a single space. Therefore, the following two statements are identical:

  dn: cn=Lisa Jangles, ou=Sales, o=Ace Industry, c=US dn: cn=Lisa Jangles, ou=Sales, o=Ace Industry, c=US

The following sections describe the change types in detail.

8.2.1 Change types

There are four change types that you can use: add, delete, modify, and modrdn . Note that you can use the modify change type to add, replace, or remove attribute values.

8.2.1.1 Adding new entries with changetype: add

Use changetype:add to add entire new entries. The format of this type of change is essentially the same as an LDIF-formatted entry (LDIF is described in Section 10.1). The format is:

dn: distinguished name changetype: add objectClass: objectClass objectClass: objectClass ... attribute type: attribute value attribute type: attribute value ...

8.2.1.2 Deleting entries with changetype: delete

Use changetype: delete to deletes the entire entry. The format is:

dn: distinguished name changetype: delete

8.2.1.3 Renaming entries with changetype: modrdn

Use changetype: modrdn to change the relative distinguished name (RDN) of an entry. In essence, this renames the entry. An entry's RDN is the leftmost element in its distinguished name.

The format is:

dn: distinguished name changetype: modrdn newrdn: new rdn deleteoldrdn: 0 | 1

where deleteoldrdn indicates whether the old RDN is to be deleted (1). If 0 is specified, then the attribute values of the old RDN are included in the entry corresponding to the new RDN.

8.2.1.4 Modifying entries with changetype: modify

Use changetype: modify to add, replace, or remove attributes and/or attribute values to the entry. When you specify changetype: modify , you must also provide a change operation to indicate how the entry is to be modified. Change operations can be:

• add: attribute --adds the specified attribute or attribute value. If the attribute does not currently exist for the entry, then the attribute and its corresponding value are created. If the attribute already exists for the entry, then the specified attribute value is added to the existing value.
• replace: attribute --- the specified values are used to entirely replace the attribute's value. If the attribute does not already exist, it is created. If no replacement value is specified for the attribute, the attribute is deleted.
• delete: attribute ---the specified attribute is deleted. If more than one instance of an attribute exists for the entry, then all instances of the attribute are deleted in the entry. To delete just one of many attribute instances, specify the attribute and associated value on the line following the delete: attribute change operation.

The format is:

dn: distinguished name changetype: modify add: attribute type attribute type: attribute value attribute type: attribute value - ... replace: attribute type attribute type: attribute value attribute type: attribute value - ... delete: attribute type attribute type: attribute value attribute type: attribute value - ...

8.2.2 Adding an entry

You use changetype: add to add an entry to your directory. When you add an entry, make sure to create an entry representing a branch point before you try to create new entries under that branch. That is, if you want to place an entry in a Marketing and an Accounting subtree, then create the branch point for those subtrees before creating entries within the subtrees. For example:

dn: o=Ace Industry, c=US dn: ou=Marketing, o=Ace Industry, c=US ... Marketing subtree entries. ... dn: ou=Accounting, o=Ace Industry, c=US ... Accounting subtree entries. ...

The following LDIF update statements can be used to create the Marketing and the Accounting subtrees, and then create entries within those trees:

dn: o=Ace Industry, c=US changetype: add objectclass: organization organizationName:Ace Industry dn: ou=Maketing, o=Ace Industry, c=US changetype: add objectclass: organizationalUnit ou: Marketing dn: cn=Pete Minsky, ou=Marketing, o=Ace Industry, c=US changetype: add objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: Pete Minsky cn: Pete sn: Minsky ou: Marketing uid: pminsky dn: cn=Sue Jacobs, ou=Marketing, o=Ace Industry, c=US changetype: add objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: Sue Jacobs cn: Sue sn: Jacobs ou: Marketing uid: sjacobs dn: ou=Accounting, o=Ace Industry, c=US changetype: add objectclass: organizationalUnit ou: Accounting dn: cn=Lisa Nielson, ou=Accounting, o=Ace Industry, c=US changetype: add objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: Lisa Nielson cn: Lisa sn: Nielson ou: Accounting uid: lnielson dn: cn=Byron Zuraski, ou=Accounting, o=Ace Industry, c=US changetype: add objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: Byron Zuraski cn: Byron sn: Zuraski ou: Accounting uid: bzuraski

If you are simply adding entries to your directory, you can avoid the changetype: add statement by specifying the -a option on the call to ldapmodify. In this case, simply provide LDIF (as opposed to LDIF update statements) to ldapmodify. For example:

dn: o=Ace Industry, c=US objectclass: organization organizationName:Ace Industry dn: ou=Maketing, o=Ace Industry, c=US objectclass: organizationalUnit ou: Marketing dn: cn=Pete Minsky, ou=Marketing, o=Ace Industry, c=US objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: Pete Minsky cn: Pete sn: Minsky ou: Marketing ...

8.2.3 Deleting an entry

You use changetype: delete to delete an entry from your directory. When you delete an entry, make sure that no other entries exist under that entry in the directory tree. That is, you can not delete an organizational unit entry unless you have first deleted all the entries that belong to the organizational unit.

The following LDIF update statements can be used to delete the person entries:

dn: cn=Pete Minsky, ou=Marketing, o=Ace Industry, c=US changetype: delete dn: cn=Sue Jacobs, ou=Marketing, o=Ace Industry, c=US changetype: delete

8.2.4 Renaming an entry

You use changetype:modrdn to rename an entry. This rename operation allows you to change the left-most value in an entry's distinguished name. For example, the entry:

cn=Sue Jacobs, ou=Marketing, o=Ace Industry, c=US

can be modified to be:

cn=Susan Jacobs, ou=Marketing, o=Ace Industry, c=US

but it cannot be modified to be:

cn=Sue Jacobs, ou=Accounting, o=Ace Industry, c=US

The following example can be used to rename Sue Jacobs to Susan Jacobs:

dn: cn=Sue Jacobs, ou=Marketing, o=Ace Industry, c=US changetype: modrdn newrdn: cn=Susan Jacobs deleteoldrdn: 0

Because deleteoldrdn is 0, this example retains the existing RDN in the new entry. The resulting entry would therefore have a common name (cn) attribute set to both Sue Jacobs and Susan Jacobs in addition to all the other attributes included in the original entry.

8.2.5 Modifying an entry

In addition to adding, deleting, and renaming entire entries in your directory, you can use ldapmodify to modify attributes and their values.

This section contains the following topics:

• Deleting an attribute value ( Section 8.2.5.1)
• Adding attributes Section 8.2.5.2)
• Changing an attribute value (( Section 8.2.5.3)

You use changetype: modify with the delete operation to delete an attribute from an entry. If the entry has more than one instance of the attribute, you must indicate which of the attributes you want to delete.

For example, the following LDIF update statement deletes all instances of the telephonenumber attribute from the entry, regardless of how many times it appears in the entry:

dn: cn=Barney Fife, ou=Sales, o=Ace Industry, c=US changetype: modify delete: telephonenumber

If you want to delete just a specific instance of the telephonenumber attribute, then you simply delete that specific attribute value. The following section describes how to do this.

8.2.5.1 Deleting an attribute value

You use changetype: modify with the delete operation to delete an attribute value from an entry. You must then indicate which of the actual attributes you want to delete.

For example, consider the following entry:

cn=Barney Fife, ou=Sales, o=Ace Industry, c=US objectClass: inetOrgPerson cn: Barney Fife sn: Fife telephonenumber: 555-1212 telephonenumber: 555-5678

To delete the 555-1212 telephone number from this entry, use the following LDIF update statement:

dn: cn=Barney Fife, ou=Sales, o=Ace Industry, c=US changetype: modify delete: telephonenumber telephonenumber: 555-1212

Barney's entry then becomes:

cn=Barney Fife, ou=Sales, o=Ace Industry, c=US objectClass: inetOrgPerson cn: Barney Fife sn: Fife telephonenumber: 555-5678

8.2.5.2 Adding attributes

You use changetype: modify with the add operation to add an attribute and an attribute value to an entry.

For example, the following LDIF update statement adds a telephone number to the entry:

dn: cn=Barney Fife, ou=Sales, o=Ace Industry, c=US changetype: modify add: telephonenumber telephonenumber: 555-1212

The following example adds two telephone numbers to the entry:

dn: cn=Barney Fife, ou=Sales, o=Ace Industry, c=US changetype: modify add: telephonenumber telephonenumber: 555-1212 telephonenumber: 555-6789

The following example adds two telephone numbers and a manager attribute to the entry:

dn: cn=Barney Fife, ou=Sales, o=Ace Industry, c=US changetype: modify add: telephonenumber telephonenumber: 555-1212 telephonenumber: 555-6789 - add: manager manager: cn=Sally Nixon, ou=Sales, o=Ace Industry, c=US

8.2.5.3 Changing an attribute value

You use changetype: modify with the replace operation to change an attribute value when there is only a single instance of that attribute in the entry.

For example, the following LDIF update statement changes Barney's manager from Sally Nixon to Wally Hensford:

dn: cn=Barney Fife, ou=Sales, o=Ace Industry, c=US changetype: modify replace: manager manager: cn=Wally Hensford, ou=Sales, o=Ace Industry, c=US

If the entry has multiple instances of the attribute, then to change one of the attribute values, you must delete the attribute value that you want to change, and then add the replacement value. For example, consider the following entry:

cn=Barney Fife, ou=Sales, o=Ace Industry, c=US objectClass: inetOrgPerson cn: Barney Fife sn: Fife telephonenumber: 555-1212 telephonenumber: 555-5678

To change 555-1212 to 555-4321, use the following LDIF update statement:

dn: cn=Barney Fife, ou=Sales, o=Ace Industry, c=US changetype: modify delete: telephonenumber telephonenumber: 555-1212 - add: telephonenumber telephonenumber: 555-4321

Barney's entry now is now as follows:

cn=Barney Fife, ou=Sales, o=Ace Industry, c=US objectClass: inetOrgPerson cn: Barney Fife sn: Fife telephonenumber: 555-5678 telephonenumber: 555-4321

8.3 Using ldapmodify

You can perform minimal modifications to directory entries using the Users and Groups area of the administration server. To perform more complex modifications, use ldapmodify with LDIF update statements.

This section describes how to use ldapmodify.

When using the ldapmodify command line utility, you may need to specify values that contain characters that have special meaning to the command-line interpreter (such as space [ ], asterisk [*], backslash [\], and so forth). When this situation occurs, enclose the value in quotation marks (""). For example:

-D "cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US"

ldapmodify allows you to provide LDIF update statements both from an input file (using the -f option), as well as from the command line. If you want to provide input from the command line, do not specify the -f option when you call ldapmodify.

ldapmodify collects statements that you enter to the command line just as if it were reading the statements from a file. When you are done providing statements to the utility, enter the character that your command line processor recognizes as the end-of-file (EOF) marker. This causes the utility to begin operations based on the input you have supplied.

Although configurable, the EOF escape sequence is usually CTRL-Z followed by RETURN.

For example, suppose you wanted to specify some LDIF update statements to ldapmodify. Then you would do the following:

prompt> ldapmodify -D bindn -w password -h hostname > dn: "cn=Barry Nixon, ou=Manufacturing, o=Ace Industry, c=US" > changetype: modify > delete: telephonenumber > - > add: manager > manager: cn=Harry Cruise, ou=Manufacturing, o=Ace Industry, c=US > ^D prompt>

8.3.3 Commonly used ldapmodify parameters

To modify an entry or entries in an existing directory, use the ldapmodify command-line utility with the following parameters:

-D

Specifies the distinguished name with which to authenticate to the server. The value must be a DN recognized by the directory server or the local directory, and it must also have the authority to modify the entries.

-w

Specifies the password associated with the distinguished name specified in the -D option.

-h

Specifies the name of the host on which the server is running.

-p

Specifies the port number that the server uses. Default is 389.

-C

Specifies the location of the configuration file for the local directory in which to perform the search. By default, the location of this file is:

NSHOME\userdb\ldap\config\lcache.conf

where NSHOME is the directory where your administration server is installed. This parameter is required if you are using this tool with a Netscape local directory.

-f

Optional parameter that specifies the file containing the LDIF update statements used to define the directory modifications. For information on supplying LDIF update statements from the command line, refer to "Providing input from the command line" .

-a

Causes ldapmodify to operate in the same way as ldapadd. Note that ldapadd is available only with the Netscape Directory Server; it is not shipped with the administration server.

8.3.4 Additional ldapmodify parameters

The following parameters offer additional functionality:

-b

Causes the utility to check every attribute value to determine whether the value is a valid file reference. If the value is a valid file reference, then the contents of the referenced file is used as the attribute value. This is often used for specifying a path to a file containing binary data, such as jpeg. For example, if you wanted to add a jpegPhoto attribute, then specify the -b option on the ldapmodify call. In the LDIF you provide to ldapmodify, include something like the following:

jpegPhoto: c:/tmp/photo.jpeg

ldapmodify will read the contents of c:\tmp\photo.jpeg into the jpegPhoto attribute that you are placing on the entry.

-c

Specifies that the utility run in continuous operation mode. Errors are reported, but the utility will continue with modifications. The default is to quit after reporting an error.

-n

Specifies that the entries are not to be actually modified, but that ldapmodify is to show what it would do with the specified input.

-R

Specifies that referrals are not to be followed automatically.

-v

Specifies that the utility is to run in verbose mode.

8.3.5 ldapmodify example with local directory

Suppose:

• You want to modify entries as specified in the file modify_statements.
• Your database administrator has the distinguished name of cn=Directory Manager, o=Ace Industry, c=US.
• The database administrator's password is King~Pin. Then to modify the entries, first specify the appropriate LDIF update statements in the modify_statements file, and then enter the following command. Note that the local directory's configuration file is referenced on the -C option rather than an actual database location:

  c:\netscape\userdb\ldap\tools\ldapmodify -D "cn=Directory Manager, o=Ace Industry, c=US" -C c:\netscape\userdb\ldap\config\lcache.conf -f modify_statements

Suppose:

1. You want to modify entries as specified in the file modify_statements.
2. You have configured a special entry for the database administrator that has the authority to modify the entries, and that entry has the distinguished name of cn=Directory Manager, o=Ace Industry, c=US.
3. The database administrator's password is King~Pin.
4. The server is located on hostname cyclops.
5. The server uses port number 845. Then to modify the entries, first specify the appropriate LDIF update statements in the modify_statements file, and then enter the following command. (The ldapmodify command line utility is included with your administration server installation in the NSHOME/userdb/ldap/tools directory.)

   ldapmodify -D "cn=Directory Manager, o=Ace Industry, c=US" -w King~Pin -h cyclops -p 845 -C NSHOME/userdb/ldap/config/lcache.conf -modify_statements

You can find entries in your directory using either the Users and Groups area of your administration server, or you can use the ldapsearch command line utility. In either case, you can enter search filters to help locate entries.

If you are using the directory server to manage your users and groups, see the Directory Server Administrator's Guide for more information on performing searches.

9.1 ldapsearch

You use ldapsearch to locate entries in your directory. You can use ldapsearch either with the directory server, or with a Netscape local directory that is bundled with the Netscape Administration Server.

You direct ldapsearch's actions through search filters.

ldapsearch is can be located under the Netscape Administration Server at:

NSHOME\userdb\ldap\tools\ldapsearch

where NSHOME is the directory where you installed your Netscape Administration Server.

9.2 Search filters

Search filters select the entries to be returned search operation. They are most commonly used with the ldapsearch command line utility. When you are using ldapsearch, you can place multiple search filters in a file, with each filter on a separate line in the file, or you can specify a search filter directly on the command line call to ldapsearch.

For example, the following filter specifies a search for a common name equal to Babs Jensen:

cn=babs jensen

9.2.1 Search filter syntax

The basic syntax of a search filter is:

attribute operator value

For example:

employeenumber >= 100

In this example, employeenumber is the attribute, >= is the operator, and 100 is the value. You can also define filters that use different attributes combined together using boolean operators.

The following sections describe search filters in detail.

9.2.2 Using attributes in search filters

When searching for an entry, you can specify attributes associated with that type of entry. For example, when you search for entries about people, you can use the cn attribute to search for people with a specific common name.

Examples of attributes for entries about people might include:

1. cn (the person's common name)
2. sn (the person's surname, or last name, or family name)
3. telephonenumber (the person's telephone number)
4. employeenumber (the person's employeenumber)
5. l (the location where you can find the person) For a listing of the attributes associated with types of entries, see Appendix A, "Object classes and attributes."

A search filter operator can be one of the following:

Table 9-1 Search Filter Operators

Search type	Symbol	Description
Equality	=	Returns entries containing attributes set to the specified value. For example, cn=Bob Johnson
Substring	=<string>*<string>	Returns entries containing attributes containing the specified substring. For example, cn=Bob* cn=*Johnson cn=*John* cn=B*John
Greater than or equal to	>=	Returns entries containing attributes that are greater than or equal to the specified value. For example, employeenumber >= 100
Less than or equal to	<=	Returns entries containing attributes that are less than or equal to the specified value. For example, employeenumber <= 100
Presence	=*	Returns entries containing the specified attribute. For example, cn=* telephonenumber=* manager=*
Approximate	~=	Returns entries containing the specified attribute that is approximately equal to the specified value. For example, cn~=surette l~=san fransico

9.2.4 Using multiple search filters

Multiple search operations can be combined using boolean operators expressed in prefix notation as follows:

(boolean_operator((search operation)(search operation)(search operation)...))

where operator is any one of the boolean operators. In addition, multiple search operation boolean operators can be nested together to form complex expressions, such as:

(boolean_operator(search operation)((operator(search operation)(search operation)))

9.2.4.1 Boolean operators

The boolean operators available for use with search filters are:

Table 9-2 Boolean Operators

Operator	Symbol	Description
And	&	All specified filters must be true for the statement to be true. For example, (&(filter)(filter)(filter)...)
Or	|	At least one specified filter must be true for the statement to be true. For example, (| (filter)(filter)(filter)...)
Not	!	The specified statement must not be true for the statement to be true. Note that only one filter is affected by the not operator. For example, (!(filter))

9.2.4.2 Search filter examples

The following filter searches for entries containing the manager attribute. This is also known as a presence search:

manager=*

The following filter searches for entries containing the common name of Ray Kultgen. This is also known as an equality search:

cn=Ray Kultgen

The following filter returns any entries that do not contain the common name of Ray Kultgen:

(!(cn=Ray Kultgen))

The following filter returns any entries that contain a description attribute with a substring of X.500:

description=*X.500*

The following filter returns any entries whose organizational unit is Marketing and whose description field does not contain the substring X.500:

(&(ou=Marketing)(!(description=*X.500*)))

The following filter returns any entries whose organizational unit is Marketing and that have Julie Fulmer or Cindy Zwaska as a manager:

(&(ou=Marketing)( | (manager="cn=Julie Fulmer,ou=Marketing,o=Ace Industry,c=US")(manager="cn=Cindy Zwaska,ou=Marketing,o=Ace Industry,c=US")))

The following filter returns any entries that do not represent a person:

(!(objectClass=person))

The following filter returns any entries that do not represent a person and whose common name is similar to printer3b:

(&(!(objectClass=person))(cn~=printer3b))

9.3 Using ldapsearch

You use the ldapsearch command-line utility to locate and retrieve directory entries. This utility opens a connection to the specified server using the specified distinguished name and password, and locates entries based on a specified search filter. Alternatively, this utility can access a Netscape local directory and search it for entries. Search scopes can include a single entry, an entry's immediate subentries, or an entire tree or subtree.

Search results are returned in LDIF format.

When using the ldapsearch command-line utility, you may need to specify values that contain characters that have special meaning to the command-line interpreter (such as space [ ], asterisk [*], backslash [\], and so forth). When this situation occurs, enclose the value in quotation marks (""). For example:

-D "cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US"

To locate an entry in an existing database, use the ldapsearch command-line utility with the following parameters:

-D

Specifies the distinguished name with which to authenticate to the server. This parameter is optional if anonymous access is supported by your server. If specified, this value must be a DN recognized by the directory server or the local directory, and it must also have the authority to search for the entries.

-w

Specifies the password associated with the distinguished name that is specified in the -D option. This parameter is required if the -D option is specified.

-h

Specifies the name of the host on which the directory server is running.

-p

Specifies the port number that the directory server uses. Default is 389.

-C

Specifies the location of the configuration file for the local directory in which to perform the search. By default, the location of this file is:

NSHOME\userdb\ldap\config\lcache.conf

where NSHOME is the directory where your administration server is installed. This parameter is required if you are using this tool with a Netscape local directory.

This parameter is supported only if you are using a Netscape local directory bundled with the Netscape Administration Server.

-b

Specifies the starting point for the search. The value specified here must be a distinguished name that currently exists in the database. This parameter is optional if the LDAP_BASEDN environment variable has been set to a base DN.

The value specified in this parameter should be provided in double quotation marks. For example: -b "cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US".

-s

Specifies the scope of the search. The scope can be one of the following:

• base--search only the entry specified in the -b option.
• one--search only the most immediate children of the entry specified in the -b parameter. Note that only the children are searched; the actual entry specified in the -b parameter is not searched.
• sub--search the entry specified in the -b parameter and all of its descendants. That is, perform a subtree search starting at the point identified in the -b parameter. This is the default.

-l

Specifies the maximum number of seconds to wait for a search request to complete. Regardless of the value specified here, ldapsearch will never wait longer than is allowed by the server's Time Limit parameter.

-z

Specifies the maximum number of entries to return in response to a search request. Regardless of the value specified here, ldapsearch will never return more entries than is allowed by the server's Size Limit parameter.

9.3.3 Additional ldapsearch parameters

To further customize a search, use the following optional parameters:

-f

Specifies the file containing the search filter(s) to be used in the search. Search filters are described in Section 9.2. Omit this parameter if you want to supply a search filter directly to the command line.

-A

Specifies that the search retrieve the attributes only, not the attribute values. This parameter is useful if you just want to determine if an attribute is present for an entry and you are not interested in the value.

-a

Specifies how alias dereferencing is completed. Value can be "never," "'always," "search," or "find." Default value is 'never'.

-n

Specifies that the search is not to be actually performed, but that ldapsearch is to show what it would do with the specified input.

-R

Specifies that referrals are not to be followed automatically.

-S

Specifies the attribute to use as the sort criteria. The default is not to sort the returned entries. If the attribute is the zero-length string (""), the entries will be sorted by their distinguished name.

-t

Specifies that the results be written to a set of temporary files.

-u

Specifies that the user-friendly form of the distinguished name be used in the output.

-v

Specifies that the utility is to run in verbose mode.

-B

Legacy option. Not currently supported.

-F

Legacy option. Not currently supported.

-L

Legacy option. Not currently supported.

-o

Legacy option. Not currently supported.

9.3.4 ldapsearch example with local directory

Suppose:

1. You want to perform searches based on filters contained in the file searchdb.
2. You want to perform a search for all entries below the marketing subtree.
3. The database administrator's password is King~Pin. Then to perform the search, first specify the appropriate search filter(s) in the searchdb file, and then enter the following command. Note that the local directory's configuration file is referenced -C option rather than an actual database location:

   c:\netscape\userdb\ldap\tools\ldapsearch -b "cn=marketing, o=Ace Industry, c=US" -D "cn=Directory Manager, o=Ace Industry, c=US" -w King~Pin -C c:\netscape\userdb\ldap\config\lcache.conf -f searchdb

Suppose:

• You want to perform searches based on filters contained in the file searchdb.
• You want to perform a search for all entries below the marketing subtree.
• You have configured a special entry for the database administrator that has the authority to modify the entries, and that entry has the distinguished name of cn=Directory Manager, o=Ace Industry, c=US.
• The database administrator's password is King~Pin.
• The server is located on hostname cyclops.
• The server uses port number 845. Then to perform the search, first specify the appropriate search filter(s) in the searchdb file, and then enter the following command:

  ldapsearch -b "cn=marketing, o=Ace Industry, c=US" -D "cn=Directory Manager, o=Ace Industry, c=US" -w King~Pin -h cyclops -p 845 -C NSHOME/ userdb/ldap/config/lcache.conf -f searchdb

  
  You can also specify a search filter directly on the call to the command line. If you do this, be sure to enclose your filter in quotation marks ("filter"). Also, do not specify the -f option. For example:

  ldapsearch -b "cn=marketing, o=Ace Industry, c=US" -D "cn=Directory Manager, o=Ace Industry, c=US" -w King~Pin -C NSHOME/userdb/ldap/config/lcache.conf "cn=babs jensen"

You can use the LDAP Data Interchange Format (LDIF) to import and export entries into and out of your local directory. For example, when you perform a search of your directory using the ldapsearch command line utility, the resulting output is in LDIF format. When you create entries using ldapmodify, you use a form of LDIF called LDIF update statements.

If you are using a directory server to manage your users and groups, see the Directory Server Administrator's Guide for more complete information on using LDIF with the directory server.

10.1 The LDIF format

The LDAP Data Interchange Format (LDIF) is used to represent directory entries in text form. The basic form of an LDIF entry is:

[<id>] dn: <distinguished name> objectClass: <object class> objectClass: <object class> ... <attribute type>:<attribute value> <attribute type>:<attribute value> ...

The following table describes the LDIF fields shown in the previous definition:

.

Table 10-1 LDIF Fields

Field	Definition
[id]	Optional positive decimal number representing the entry ID. The database creation tools generate this ID for you. Never add or edit this value yourself.
dn: distinguished name	Specifies the distinguished name for the entry. For a complete description of distinguished names, refer to Section 6.4
objectClass: object class	Specifies an object class to use with this entry. The object class identifies the types of attributes allowed and required for the entry.
attribute type	Specifies a descriptive attribute to use with the entry. The attribute should be defined either in slapd.at.conf or with the attribute parameter in slapd.conf. A list of standard attributes can be found in the online documentation that comes with the server. See Appendix A.
attribute value	Specifies the attribute value to be used with the attribute type.

10.1.1 Continued lines

When you specify LDIF, you can break and continue a line by indenting the continued portion of the line by exactly one space. For example, the following two statements are identical:

dn: cn=Jake Lupinski, ou=Accounting, o=Ace Industry, c=US dn: cn=Jake Lup inski, ou=Accoun ting, o=Ace Industr y, c=US

10.2 Creating databases using LDIF

You can create a directory database using LDIF. This method is useful when you are creating an entire directory database, or when you are importing entries from another directory service application.

In general, to create a database using LDIF, you:

• Create an ASCII file containing the entries you want to add in LDIF format. See Section 10.2.1 for more information. Make sure each entry is separated from the next by an empty line.
• Begin each directory in the database with the topmost, or the root, entry. The root point of the directory must represent a suffix you have set for your server. For example, if your server has the suffix:

  o=Ace Industry, c=US

  
  then the very first entry in your directory must be:

  dn: o=Ace Industry, c=US

• As you proceed with your directory creation, make sure that you create an entry representing a branch point before you create new entries under that branch. For example, if you want to place an entry in a Marketing and an Accounting subtree, then create the branch point for those subtrees before creating entries within those subtrees:

  dn: o=Ace Industry, c=US <list of attributes and object classes> dn: ou=Marketing, o=Ace Industry, c=US <list of attributes and object classes> ... Marketing subtree entries. ... dn: ou=Accounting, o=Ace Industry, c=US <list of attributes and object classes> ... Accounting subtree entries. ...

• Create the database from the LDIF file using the procedure described in Section 7.6.6.

This section describes specifically how to create a series of entries using LDIF to describe the people in your organization. For the general format of the LDIF entry, refer to Section 10.1.

Note that you can, and will, create many more types of entries than are discussed here. However, organizational person entries are the most common type of entry that you will store in your directory, so this is the kind of entry used for these examples. For a look at the most common type of object classes used in a directory server, see the object class discussion in Appendix A.

You can import LDIF formatted files into your directory using the procedure described in Section 7.6.6. You can export your directory to LDIF by using the procedure described in Section 7.7.

10.2.1.1 Specifying entries for an organizational person

The most common type of entry that you will include in your directory will describe a person within your organization. The LDIF you specify to define an organizational person should appear as follows:

dn: distinguished name cn: common name sn: surname list of optional attributes ... objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson

The following defines each aspect of the LDIF-formatted entry:

dn: distinguished name

Specifies the DN for the entry. DNs are described in Section 6.4. A DN is required.

cn: common name

Specifies the common name for the person. That is, the full name commonly used by the person. For example, cn: Bill Anderson. A common name is required.

sn: surname

Specifies the person's surname, or last name. For example, sn: Anderson. A surname is required.

list of attributes

Specifies the list of optional attributes that you want to maintain for the entry. For a list of the attributes you can use with an object class, refer to reference>(Objectclassesappendix).

objectClass: top

Specifies the top object class. This object class specification is optional. Some older LDAP clients will require the existence of object class top during search operations.

objectClass: person

Specifies the person object class. This object class specification should be included because many LDAP clients will require the existence of object class person during search operations for a person or an organizational person.

bjectClass: organizationalPerson

Specifies the organizationalPerson object class. This object class specification should be included because some LDAP clients will require the existence of object class organizationalPerson during search operations for an organizational person.

bjectClass: inetOrgPerson

Specifies the inetOrgPerson object class. The inetOrgPerson object class is recommended for the creation of an organizational person entry because this object class includes the widest range of attributes. For a list of the attributes you can use with an object class, refer to Appendix A.

10.2.1.2 LDIF file example

The following example shows an LDIF file that contains three organizational person entries:

dn: cn=June Rossi, ou=accounting, o=Ace Industry, c=US cn: June Rossi sn: Rossi givenName: June mail: rossi@aceindustry.com userPassword: {sha}KDIE3AL9DK telephoneNumber: 2616 roomNumber: 220 objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson dn: cn=Marc Chambers, ou=manufacturing, o=Ace Industry, c=US cn: Marc Chambers sn: Chambers givenName: Marc mail: chambers@aceindustry.com userPassword: {sha}jdl2alem87dlacz1 telephoneNumber: 2652 roomNumber: 167 objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson dn: cn=Robert Wong, ou=manufacturing, o=Ace Industry, c=US cn: Robert Wong cn: Bob Wong sn: Wong givenName: Robert givenName: Bob mail: bwong@aceindustry.com userPassword: {sha}nn2msx761 telephoneNumber: 2881 roomNumber: 211 objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson

This appendix describes the schema elements most commonly used in the directory server. Most of the schema elements used in the directory server are part of the standard LDAP protocol, which is in turn based on the X.500 standard. However, some of the directory server's object classes and attributes are extensions created by Netscape for use with its implementation of LDAP. If an object class or attribute was created by Netscape and is not part of the standard LDAP schema, a note is made in the description of that object or attribute.

This appendix includes:

• Schema definition ( Section A.1)
• Object class definitions ( Section A.2)
• Attribute definitions ( Section A.3)

The directory server schema defines the type of information that can be stored on a directory server entry. This definition is provided by the following types of schema elements:

1. object classes---indicates what kind of information a directory entry contains (for example, does the entry represent a person, an organization, a country, and so forth).
2. attributes---contains information that is descriptive of the entry (for example, a person's phone number or an organization's mailing address).

It is important that you use a consistent schema within your directory server because LDAP clients locate entries in your directory by searching for object classes or attributes and their associated values. If you use an inconsistent schema, then it becomes virtually impossible to locate information in your directory tree.

Further, LDAP clients are designed to work with a specific, well- defined schema. For the most part, the schema that these LDAP clients are designed to work with is the standard LDAP schema which, itself, is based on the X.500 standard. For this reason, most LDAP-based directory services begin with the standard LDAP schema, but then they add to it as they discover site-specific needs that are not met by the standard schema.

The Netscape LDAP schema takes this approach as well. Most of the schema elements in this appendix are based on the LDAP standard. However, Netscape has extended the schema to allow for directory activities that are not otherwise supported by the standard LDAP implementation. All of these extensions are noted in the following schema description. In addition, Netscape ships LDAP clients that expect the schema as defined in this appendix.

You can enforce your directory server's schema by turning schema checking on. When schema checking is turned on, you cannot add an object class or attribute to your directory server that is not a recognized part of the schema. For more information on schema checking, see the Netscape Directory Server Administrator's Guide.

Note that schema checking is not supported for the Netscape local directory.

A.1.2 Customizing the schema

You do not have to use the schema that is described here. In fact, it is assumed that you will extend this schema to support your own site's requirements. This is perhaps one of the most common activities surrounding a new directory server installation.

For a discussion on how to extend your schema, see the web page at the following URL:

http://www.netscape.com/eng/server/directory/1.0/dsextension.htm l

A.1.3 Building custom clients

As you extend your schema, it is important to remember that will have to start building customized LDAP clients to manage and use your directory. This is because the standard LDAP clients will not know the names of your new schema elements or what type of information they expect to be stored on these new elements. This is a problem that only gets worse as the clients become more sophisticated and begin to offer a graphical look at your directory contents, or to perform sophisticated directory management capabilities.

To aid you in developing customized LDAP clients, Netscape ships several command line LDAP clients with the directory server. You can use the command line tools to build rudimentary tools such as shell scripts to help you perform batch operations on your directory tree. You can also use these same command line tools with cgi scripts that allow you to perform directory management activities using a web server and your web browser.

In addition, Netscape provides the LDAP client SDK to allow you to quickly build LDAP clients using the C or Java programming languages.

For more information, on the command line client tools, see the Netscape Directory Server Administrator's Guide. For more information on the LDAP client SDK, go to:

http://developer.netscape.com/library/documentation/index.html

A.1.4 A note about attribute values

Perhaps one of the more confusing aspects about an LDAP schema is that you can place any data that you want on any attribute value. LDAP and the directory server place no restrictions on the data format, length, or type that you associate with individual attributes (other than some minimal syntax definitions that are used strictly for searching and pattern matching purposes). For example, when you represent a telephone number in your directory tree, you can legally represent it in any of the following ways:

(408) 555-5555 408-555-5555 1-408-555-5555 1.408.555.5555 555-5555

This free form data model provides you with maximum flexibility when you design your data policy. However, the caveat to this data model is that while the directory server and the LDAP protocol do not care about your data format, your LDAP clients do care about the representation of the data in your directory tree. This is especially true of graphical user interface clients that must display directory data in rigid-length fields. The format of your directory data is also important to the user who is searching your directory tree for a particular value. For example, if the user is searching for a telephone number in the form:

(408) 555-5555

but you have stored telephone numbers in the format:

1.408.555.5555

then the user may have difficulty in locating the actual entry for which she is searching. For these two reasons, it is important that you be as consistent as possible when storing data in your directory tree. Pick a format and stick with it. When managing the data in your directory tree, keep in mind not so much what the directory server requires, but rather what your LDAP clients and the users of your directory expects to find there. Doing so will vastly improve the usability of your directory data.

A.1.5 Object classes

Object classes define the type of data an entry can contain. Each object class has a defined set of required and optional attributes. An object class may be a subclass of another object class, in which case the required attributes of the latter class are also required attributes of the former class.

Object classes are defined in the directory server NSHOME/slapd-server/config/slapd.oc.conf file, where NSHOME is the directory where you installed your server.

A.1.6 Attributes

Attributes hold information about a specific descriptive aspect of the entry. Each attribute consists of an attribute type and an attribute value. The attribute type identifies the class of information given by that attribute (for example, telephone number). The attribute value is the particular instance of information appearing in that entry (for example, 555-1999).

Originally, attributes were defined using long names, such as commonName. Over several year, the standards have changed to allow the use of abbreviations. For example:

cn

is the abbreviation for:

commonName

If an attribute has an abbreviation, the abbreviation is given in the description of the attribute and may be used interchangeably with the full name in the list of attributes for an object class.

A.1.7 Required versus optional attributes

Object classes usually contain at least one required attribute, and they always contain one or more optional attributes. When an attribute is required, then attempts to add an entry to the directory without the required attribute results in an object class violation; that is, the attempt to add the entry fails.

Optional attributes are attributes that you are allowed, but not required, to add to the directory entry. If you attempt to add an attribute to an entry that is neither required or allowed according to the entry's object class definition, then the directory server will return an object class violation.

Note that the concept of a required or allowed attribute is meaningful only if schema checking is turned on. If schema checking is turned off, then you can add (or fail to add) any attribute to your directory; the directory server will make no attempt to ensure that the data you are adding to your directory conforms to the schema.

It is strongly recommended that you run your directory server with schema checking turned on.

A.2 Object Class Definitions

The following sections describe the most common object classes that are used in the directory server. Most object classes are defined by the X.500 standard. In addition, Netscape provides some additional object classes for use with its LDAP implementation. Netscape also extends many of its object classes with new attribute definitions. The following types of object classes are described here:

• Groups ( Section A.2.1)
• Replication ( Section A.2.2)
• Locations ( Section A.2.3)
• Organizations ( Section A.2.4)
• People ( Section A.2.5)

The following two object classes describe entries representing an unordered set of names that represent individual objects or other groups of objects. Membership of a group is static: only administrative action can modify a group (such as adding a member), the membership is not determined dynamically each time a reference is made to the group. Each object class contains attributes that describe the group and its members. The two object classes described here are groupOfNames (Table A-1) and groupOfUniqueNames (Table A-2).

Table A-1 groupOfNames

Attributes	Attribute Description
cn	(Required) Defines the group's common name.
member	(Required) Defines a group member in distinguished name format.
businessCategory	Defines the type of business in which the group is engaged.
description	Defines the type of business in which the group is engaged.
o	Defines the organization in which the group resides.
ou	Defines the organizational unit in which the group resides.
owner	Defines the group's owner.
seeAlso	URL to information relevant to the group.

Table A-2 groupOfUniqueNames

Attributes	Attribute Description
cn	(Required) Defines the group's common name.
uniqueMember	(Required) Defines a unique group member in distinguished name format.
businessCategory	Defines the type of business in which the group is engaged.
description	Provides a text description of the group's purpose.
o	Defines the organization in which the group resides.
ou	Defines the organizational unit in which the group resides.
owner	Defines the group's owner.
seeAlso	URL to information relevant to the group.

A.2.2 Replication

The following two object classes define directory servers. The first object class identifies the master or supplier server. The second object class identifies consumer servers and the entries to be supplied to those consumers. The two object classes are LDAPServer (Table A-3) and LDAPReplica (Table A-4).

Table A-3 LDAPServer

Attributes	Attribute Description
cn	(Required) Defines the entry's common name.
changeLogMaximumAge	Identifies the maximum age that any change log entry is allowed to be.
changeLogMaximumSize	Identifies the maximum size of the server's change long.
description	Provides a text description of the server.
generation	Unique byte vector that identifies the server for replication purposes.
l	Identifies the locality in which the server resides.
ou	Defines the organizational unit in which the server resides.
seeAlso	URL to information relevant to the server.
subtreeACI	Defines access control information for the server's entry.

LDAPReplica (Table A-4) identifies entries in the local server that are replicated to a remote server, and identifies the remote server to which the entries are replicated. This object class is an extension to the standard LDAP schema.

Table A-4 LDAPReplica

cn	(Required) Defines the entry's common name.
description	Provides a text description of the server.
l	Identifies the locality in which the server resides.
ou	Defines the organizational unit in which the server resides.
replicaBinddn	Identifies the DN used by the local server to bind to the consumer server.
replicaBindMethod	Identifies the method used by the local server to bind to the consumer. Currently this attribute must be set to simple.
replicaCredentials	Password used by the local server to bind to the consumer.
replicaHost	Hostname of the consumer server.
replicaPort	Port used by the consumer server for LDAP communications.
replicaRoot	Distinguished name representing the subtree on the local server that is to be supplied to the consumer server.
replicaUpdateFailedAt	Time stamp when an update to the consumer server failed.
replicaUpdateReplayed	Change number of the last change supplied to the consumer server.
replicaUpdateSchedule	Identifies the schedule when the local server begins an update to the consumer server.
replicaUseSSL	ndicates whether SSL is to be used for communications with the consumer server.
seeAlso	URL to information relevant to the server.
subtreeACI	Defines access control information for the server's entry.

A.2.3 Locations

The following two object classes describe locations in the directory tree. Each object class contains attributes that describe a location, such as the country name and description. The two object classes described here are country and locality.

country (Table A-5) defines entries that represent countries. locality (Table A-6) defines entries that represent localities or geographic areas.

Table A-5 country

c	(Required) Defines the entry's country name.
description	Provides a text description of the country.

Table A-6 locality

description	Provides a text description of the locality.
l	Identifies the entry's locality.
seeAlso	URL to information relevant to the locality.
st	Identifies the state or province in which the locality resides.
streetaddress	Identifies a street address associated with the locality.

A.2.4 Organizations

The following two object classes describe entries representing organizations in the directory tree. Each object class contains attributes that describe an organization, such as its name and description. The two object classes described here are organization and organizationalUnit.

organization (Table A-7) defines entries that represent organizations. An organization is generally assumed to be a large, relatively static grouping within the larger corporation or enterprise. organizationalUnit

(Table A-8) defines entries that represent organizational units. An organizational unit is generally assumed to be a relatively static grouping within the larger organization

Table A-7 organization

o	(Required) Identifies the organization's name.
businessCategory	Identifies the business in which the organization is involved.
description	Provides a text description of the organization.
facsimileTelephoneNumbe	Identifies the fax number associated with the organization.
l	Identifies the organization's location.
physicalDeliveryOfficeName	Identifies a location where physical deliveries can be made.
postalAddress	Identifies the organization's mailing address.
postalCode	Identifies the organization's postal code (such as a United States zip code).
postOfficeBox	Identifies the organization's post office box.
preferredDeliveryMethod	Identifies the organization's preferred method of contact or delivery.
seeAlso	URL to information relevant to the organization.
st	Identifies the state or province in which the organization resides.
streetAddress	Identifies a street address at which the organization is located.
telephoneNumber	Identifies the telephone number associated with the organization.
userPassword	Identifies the password with which the entry can bind to the directory.

Table A-8 organizationalUnit

ou	(Required) Identifies the organizational unit's name.
businessCategory	Identifies the business in which the organizational unit is involved.
description	Provides a text description of the organizational unit.
facsimileTelephoneNumber	Identifies the fax number associated with the organizational unit.
l	Identifies the organizational unit's location
physicalDeliveryOfficeName	Identifies a location where physical deliveries can be made.
postalAddress	Identifies the organizational unit's mailing address.
postalCode	Identifies the organizational unit's postal code (such as a United States zip code).
postOfficeBox	Identifies the organizational unit's post office box.
preferredDeliveryMethod	Identifies the organizational unit's preferred method of contact or delivery.
seeAlso	URL to information relevant to the organizational unit.
st	Identifies the state or province in which the organizational unit resides.
streetAddress	Identifies a street address at which the organizational unit is located.
telephoneNumber	Identifies the telephone number associated with the organizational unit.
userPassword	Identifies the password with which the entry can bind to the directory.

A.2.5 People

The four object classes describe entries representing people in the directory. Each object class contains attributes that describe a person, such as name, telephone number, and address. The four object classes described here are person, organizationalPerson, inetOrgPerson, and NTUser.

person (Table A-9 ) defines entries that represent people generically. This object class is the base class for the organizationalPerson object class.

organizationalPerson Table A-10) defines entries for people employed by or in some other important way associated with an organization. The organizationalPerson object class is an extension of the person object class.

inetOrgPerson Table A-11 defines entries representing people organization's intranet. This object class is a Netscape extension to the standard LDAP schema.

Table A-9 person

cn	(Required) Defines the person's common name.
sn	(Required) Defines the person's surname, or last name.
description	Provides a text description of the person.
seeAlso	URL to information relevant to the person.
telephoneNumber	Identifies the person's telephone number.
userPassword	Identifies the password with which the person can bind to the directory.

Table A-10 organizationalPerson

cn	(Required) Defines the person's common name.
sn	(Required) Defines the person's surname, or last name.
description	Provides a text description of the person.
facsimileTelephoneNumber	Identifies the person's fax number.
l	Identifies the location in which the person resides.
ou	Identifies the organizational unit to which the person belongs.
physicalDeliveryOfficeName	Identifies a location where physical deliveries can be made.
postalAddress	Identifies the person's mailing address.
postalCode	Identifies the person's postal code (such as a United States zip code).
postOfficeBox	Identifies the person's post office box.
preferredDeliveryMethod	Identifies the person's preferred method of contact or delivery.
seeAlso	URL to information relevant to the person.
st	Identifies the state or province in which the person resides.
streetAddress	Identifies a street address at which the person is located.
telephoneNumber	Identifies the person's telephone number.
title	Identifies the person's title.
userPassword	Identifies the password with which the person can bind to the directory.

Table A-11 inetOrgPerson

cn	(Required) Defines the person's common name.
sn	(Required) Defines the person's surname, or last name.
businessCategory	Identifies the business in which the person is involved.
carLicense	Identifies the person's car license plate number.
departmentNumber	Identifies the department for which the person works.
description	Provides a text description of the person.
employeeNumber	Identifies the person's employee number.
employeeType	Identifies the person's type of employment (for example, full time).
facsimileTelephoneNumber	Identifies the person's fax number.
givenName	Identifies the person's given, or first, name.
homePhone	Identifies the person's home phone number.
homePostalAddress	Identifies the person's home mailing address.
initials	Identifies the person's initials.
jpegPhoto	Contains an image in jpeg format.
l	Identifies the location in which the person resides.
labeledURI	Specifies a universal resource locator that is relevant to the person.
mail	Identifies the person's electronic mailing address.
manager	Distinguished name representing the person's manager.
mobile	Identifies the person's mobile phone number.
ou	Identifies the organizational unit to which the person belongs.
pager	Identifies the person's pager number.
physicalDeliveryOfficeName	Identifies a location where physical deliveries can be made.
postalAddress	Identifies the person's mailing address.
postalCode	Identifies the person's postal code (such as a United States zip code).
postOfficeBox	Identifies the person's post office box.
preferredDeliveryMethod	Identifies the person's preferred method of contact or delivery.
roomNumber	Identifies the room number in which the person is located.
secretary	Identifies the person's secretary or administrator.
seeAlso	URL to information relevant to the person.
st	Identifies the state or province in which the person resides.
streetAddress	Identifies a street address at which the person is located.
subtreeACI	Identifies access control information for the person's entry.
telephoneNumber	Identifies the person's telephone number.
title	Identifies the person's title.
uid	Identifies the person's user ID.
userPassword	Identifies the password with which the person can bind to the directory.

	privacy and legal statement
6562PRO_003.HTML