Modifying the directory


ou 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.

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.

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:

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.

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 "The LDIF format" ). The format is:

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

Deleting entries with changetype: delete

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

dn: distinguished name
changetype: delete

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.

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:

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
...

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

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 can not 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.

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

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.

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

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

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

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.

Note
In order for users to successfully authenticate to the administration server, a unique uid attribute must be placed on their directory entries. The Users and Groups area of the administration server automatically creates a uid when it creates an entry, and the administration server ensures that the uid is unique. ldapmodify, however, does none of these things. Make sure that when you are creating use entries using ldapmodify, that you place a unique uid on each new user entry.

Using quotation marks

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"
Note
Depending on which command-line interpreter you are using, you should use either single or double quotation marks for this purpose. Refer to your operating system documentation for more information.

Providing input from the command line

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 almost always control-D (^D) under Unix, and usually control-z followed by <return> (^z<return>) under Windows NT.

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>

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.

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.

ldapmodify example with local directory

Suppose:

ldapmodify example with directory server

Suppose:


Copyright 1997 Netscape Communications Corporation. All rights reserved.