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:
- 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.
- Specify a series of attributes and their changed values. The general format of LDIF update statements is as follows:
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=UShas an RDN of
uid=ssarette.
dn: distinguished name
changetype identifier
change operation identifier
list of attributes
...
-
change operation identifier
list of attributes
...
-
...
Note
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=USIn addition, the line continuation operator is a single space. Therefore, the following two statements are identical:
changetype: modify
add: telephonenumber
telephonenumber: (408) 555-2468
-
add: manager
manager: cn=Harry Cruise, ou=Manufacturing, o=Ace Industry, c=US
dn: cn=Lisa Jangles, ou=Sales, o=Ace Industry, c=US
dn: cn=Lisa Jangles,The following sections describe the change types in detail.
ou=Sales,
o=Ace Industry,
c=US
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:
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.
dn: distinguished name new rdn
changetype: modrdn
newrdn:
deleteoldrdn: 0|1
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
-
...
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=USIf 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:
changetype: add
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Byron Zuraski
cn: Byron
sn: Zuraski
ou: Accounting
uid: bzuraski
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
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.
changetype: modrdn
newrdn: cn=Susan Jacobs
deleteoldrdn: 0
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=USchangetype: 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=USTo delete the 555-1212 telephone number from this entry, use the following LDIF update statement:
objectClass: inetOrgPerson
cn: Barney Fife
sn: Fife
telephonenumber: 555-1212
telephonenumber: 555-5678
dn: cn=Barney Fife, ou=Sales, o=Ace Industry, c=USBarney's entry then becomes:
changetype: modify
delete: telephonenumber
telephonenumber: 555-1212
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=USchangetype: 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=USchangetype: 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=USTo change 555-1212 to 555-4321, use the following LDIF update statement:
objectClass: inetOrgPerson
cn: Barney Fife
sn: Fife
telephonenumber: 555-1212
telephonenumber: 555-5678
dn: cn=Barney Fife, ou=Sales, o=Ace Industry, c=USBarney's entry now is now as follows:
changetype: modify
delete: telephonenumber
telephonenumber: 555-1212
-
add: telephonenumber
telephonenumber: 555-4321
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:
- 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
ldapmodify example with directory server
Suppose:
- You want to modify entries as specified in the file
modify_statements. - 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 modify the entries, first specify the appropriate LDIF update statements in the
modify_statements file, and then enter the following command:
Note
The following examples reference the ldapmodify utility that is bundled with the administration server. Netscape Directory Server also comes with the same utility. For information on locating this utility in the directory server distribution, see the Directory Server Administrator's Guide.You can find the ldapmodify command line utility 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 -f modify_statements
Note
For information on using SSL with this utility, refer to the Directory Server Administrator's Guide.