ou can modify directory entries using either the Users & Groups area of your administration server, which provides you with only essential modifications abilities, or you can use the ldapmodify command-line tool for more complex modifications that involve a wider range of attributes and attribute values.
If you are using the directory server to manage your users and groups, see the Administrator's Guide for more information on performing directory modifications.
ldapmodify
You use ldapmodify to add, delete, or modify entries in your directory. It can be used 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
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
-a option. If you specify the -a option, then an add operation (changetype: add) is assumed. However, any other change type will override the -a option.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 relative distinguished name (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 a 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
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 delete the entire entry. The format is
dn: distinguished name
changetype: delete
Renaming entries with changetype: modrdn
Use changetype:modrdn to change the 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 dn: distinguished name modrdn
changetype:
newrdn: new rdn
deleteoldrdn: 0|1
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 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 include the following:
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.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.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 dn: distinguished name
changetype: modrdn
newrdn: new rdn
deleteoldrdn: 0|1
attribute change operation.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
-
...
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. 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
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Byron Zuraski
cn: Byron
sn: Zuraski
ou: Accounting
uid: bzuraski
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. 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 leftmost 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
changetype: modrdn
newrdn: cn=Susan Jacobs
deleteoldrdn: 0
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.
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.
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
To 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=US
Barney'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=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
To 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=US
Barney'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 & 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 & 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 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), and from the command line. If you want to provide input from the command line, do not specify the -f option.
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, type 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 portnumber that the server uses. The default number 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
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
Specifies the file containing the LDIF update statements used to define the directory
modifications. This is an optional parameter. 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 each 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: /tmp/photo.jpeg
Ldapmodify will read the contents of into the jpegPhoto attribute that you are placing on the entry.
-c
Specifies that the utility runs 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
modify_statementscn=Directory Manager, o=Ace Industry, c=USKing~Pin.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:
Suppose
modify_statementscn=Directory Manager, o=Ace Industry, c=USKing~Pincyclopsmodify_statements file, and then enter the following command:
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
The previous example references 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 Administrator's Guide. You can find the ldapmodify command-line utility with your administration server installation in the
NSHOME/userdb/ldap/tools directory.
For information on using SSL with this utility, refer to the Administrator's Guide.