| Skip Navigation Links | |
| Exit Print View | |
|
Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory 11g Release 1 (11.1.1) |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory 11g Release 1 (11.1.1) |
1. Server Administration Commands
2. Data Administration Commands
The ldapmodify command modifies directory entries.
ldapmodify [options] [filter] [attributes]
The ldapmodify command can be used to perform LDAP modify, add, delete, and modify DN operations in the directory server. The operations to perform in the directory server should be specified in LDIF change format, as described in RFC 2849. This change syntax uses the changetype keyword to indicate the type of change.
An add change record is straightforward, because it is a complete entry in LDIF form with a changetype value of add. For example:
dn: uid=john.doe,ou=People,dc=example,dc=com changetype: add objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson uid: john.doe givenName: John sn: Doe cn: John Doe mail: john.doe@example.com userPassword: password
A delete change record is even simpler than an add change record. The add record consists of a line with the entry DN followed by another line with a changetype of delete. For example:
dn: uid=john.doe,ou=People,dc=example,dc=com changetype: delete
The modify change record is the most complex operation, because of the number of variants. The modify change records all start with the entry DN followed by a changetype of modify. The next line consists of either add, delete, or replace followed by an attribute name indicating what modification will be and to which attribute. The change record may optionally be followed by one or more lines containing the attribute name followed by a value to use for the modification (that is, a value to add to that attribute, remove from that attribute, or use to replace the existing set of values). Multiple attribute changes can be made to an entry in the same modify operation by separating changes with a line containing only a dash, starting the next line with a new add, delete, or replace tag followed by a colon and the next attribute name, and then setting of values for that attribute. For example:
dn: uid=john.doe,ou=People,dc=example,dc=com changetype: modify replace: description description: This is the new description for John Doe - add: mailAlternateAddress mailAlternateAddress: jdoe@example.com
Modify DN change records should always contain the newRDN and deleteOldRDN elements and can optionally contain the newSuperior component to specify a new parent for the target entry. For example:
dn: uid=john.doe,ou=People,dc=example,dc=com changetype: moddn newRDN: uid=jdoe deleteOldRDN: 1
If no arguments are provided to the ldapmodify command, it attempts to interact with a Directory Server instance using an unauthenticated connection using the loopback address on port 389, and information about the changes to request will be read from standard input. This is unlikely to succeed, as it will almost certainly be necessary to at least provide arguments that will be used to specify how to authenticate to the server.
Many UNIX and Linux operating systems provide an installed version of common LDAP client commands, such as ldapsearch, ldapmodify, and ldapdelete in the /usr/bin directory. You can check if a version is on your system by entering the command: which ldapmodify. If the command returns a value (seen below), you will need to update your $PATH to install-dir/bin or create an alias to the directory server instance.
$ which ldapmodify (Unix/Linux) /usr/bin/ldapmodify
The ldapmodify command accepts an option in either its short form (for example, -D bindDN) or its long form equivalent (for example, --bindDN bindDN).
Add entries. Treat records with no changetype element as an add request. This option can be used to add entries from a standard LDIF file that does not contain information in the LDIF change format.
Perform a search using the LDAP assertion control (as defined in RFC 4528) to indicate that the operation should only be processed if the assertion contained in the provided filter is true.
Continue processing even if an error occurs. Use this option when using multiple search filters in a file --filename. If an error occurs during processing, the directory server will continue processing the next search filter. Otherwise the command will exit before all searches have been completed.
Read modifications from the specified file containing one or more filters to use during the modify operation. The records in the LDIF file should be in the LDIF change format (that is, including the changetype element). If the LDIF file only contains entries that should be added to the directory server, then the file can be used with the --defaultAdd option even if the entries do not have a changetype element. The provided file can contain multiple changes as long as there is at least one blank line between change records.
If this option is not provided, then the ldapmodify command will attempt to read change information from standard input. This makes it possible to have the change records either provided interactively by the target user on the command line or piped into the command from some other source.
Perform a search with the specified control in search requests sent to the directory server. This option makes it possible to include arbitrary request controls that the client cannot directly support. The value for this option must be in the form:
oid[: criticality[:value|::b64value|:<fileurl]]
The elements of this value include:
Use the OID for the control. For certain types of controls, a text name may be used instead of the numeric OID (for search operations, this includes managedsait for the manage DSA IT control). This element is required. Human-readable names can be used in place of the OID to reference controls that do not require values using the -J or control option. These OID names are the following:
Use in place of the Account Usability Request Control OID 1.3.6.1.4.1.42.2.27.9.5.8 (no value)
Use in place of the Authorization Identity Request Control OID: 2.16.840.1.113730.3.4.16 (no value)
Use in place of the Get Effective Rights Control OID: 1.3.6.1.4.1.42.2.27.9.5.2 (value = authorization ID)
Use in place of the Manage DSA IT Control OID: 2.16.840.1.113730.3.4.2 (no value)
Use in place of the LDAP No-op Control OID: 1.3.6.1.4.1.4203.1.10.2 (no value)
Use in place of the Password Policy Request OID: 1.3.6.1.4.1.42.2.27.8.5.1 (no value)
Use in place of the Subtree Delete Request Control OID: 1.2.840.113556.1.4.805 (no value)
If true, the control should be marked critical (meaning that the directory server should not process the operation unless it can meet the requirements of this control). If false, the control should not be marked critical. If this subcommand is not provided, then the control is not marked critical.
Specifies the value for the control. This form should only be used if the value can be expressed as a string. It must not be used in conjunction with either the ::b64value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
Specifies the value for the control in base64-encoded form. This subcommand must not be used in conjunction with either the :value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
Specifies a URL that references a file from which the value of the control should be taken. It must not be used in conjunction with either the :value or ::b64value forms. If none of these subcommands is present, then the control will not have a value.
For example, the value 1.3.6.1.4.1.42.2.27.9.5.2:true:dn:uid=dmiller,ou=people,dc=example,dc=com will include a critical control with an OID of 1.3.6.1.4.1.42.2.27.9.5.2, marked as critical (true), and with a string value for the authorization ID dn:uid=dmiller,ou=people,dc=example,dc=com. Or, you can use the OID names: effectiverights:true:dn:uid=dmiller,ou=people,dc=example,dc=com.
Run in no-op mode. That is, report what should happen but do not actually perform any searches or communicate with the server in any way.
Use the LDAP ReadEntry Post-read Control (as defined in RFC 4527) to indicate that the directory server should return a copy of the target entry as it was immediately after the update. This is only applicable for add, modify, and modify DN operations. The value for this option should be a comma-separated list of the attributes to include in the representation of the pre-read entry. The same conventions apply to this list as for the list of attributes to return in the ldapsearch command (that is, it is possible to use * for all user attributes, + for all operational attributes, @ocname for all attributes in the specified objectclass, and so on). If no attributes are specified (signified with empty quotes), then all user attributes will be returned.
Use the LDAP ReadEntry Pre-read Control (as defined in RFC 4527) to indicate that the directory server should return a copy of the target entry as it was immediately before the update. This is only applicable for delete, modify, and modify DN operations. The value for this option should be a comma-separated list of the attributes to include in the representation of the pre-read entry. The same conventions apply to this list as for the list of attributes to return in the ldapsearch command (that is, it is possible to use * for all user attributes, + for all operational attributes, @ocname for all attributes in the specified objectclass, and so on). If no attributes are specified (signified with empty quotes), then all user attributes will be returned.
Use the Proxied Authorization Control to specify the identity of the user for whom the operations should be performed. This will use version 2 of the Proxied Authorization Control as defined in RFC 4370. The value of the option should be an authorization ID in the form dn: followed by the DN of the target user (for example, dn:uid=john.doe,ou=People,dc=example,dc=com), or u: followed by the user name (for example, u:john.doe). If this option is not provided, then proxied authorization will not be used.
Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication. The default value for this option is cn=Directory Manager. It is not required when using SASL authentication or if no authentication is to be performed.
Use the authorization identity request control (as defined in RFC 3829) in the bind request so that the directory server returns the corresponding authorization ID to the client when authentication has completed. (The line containing the authorization ID will be prefixed with a # character, making it a comment if the output is to be interpreted as an LDIF.)
Contact the directory server on the specified host name or IP address. If it is not provided, then a default address of localhost will be used.
Use the bind password in the specified file when authenticating to the directory server. The option is used for simple authentication, as well as for password-based SASL mechanisms such as CRAM-MD5, DIGEST-MD5, and PLAIN. It is not required if no authentication is to be performed. This option must not be used in conjunction with --bindPassword.
SASL is not supported for Oracle Unified Directory proxy.
Use the client keystore certificate in the specified path for secure communication when using the SSL or the StartTLS extended operation. This option should only be necessary if the client needs to present a certificate to the directory server, for example, when using SASL EXTERNAL authentication.
SASL is not supported for Oracle Unified Directory proxy.
Use the specified certificate for certificate-based client authentication.
Use the specified option when performing SASL authentication. Multiple SASL options can be provided by using this option multiple times, once for each option. For information about using SASL authentication in clients, see Configuring SASL Authentication in Oracle Fusion Middleware Administration Guide for Oracle Unified Directory.
SASL is not supported for Oracle Unified Directory proxy.
Contact the directory server at the specified port. If this option is not provided, then a default port of 389 will be used.
Use the client trust store certificate in the specified path for secure communication when using the SSL or the StartTLS extended operation. This option is not needed if --trustAll is used, although a trust store should be used when working in a production environment.
Use the StartTLS extended operation when communicating with the directory server. This option must not be used in conjunction with --useSSL.
Use the SASL EXTERNAL mechanism for authentication, which attempts to identify the client by using an SSL certificate that it presents to the directory server. If this option is used, then the --keyStorePath option must also be provided to specify the path to the client keystore and either the --useSSL or the --useStartTLS option must be used to establish a secure communication channel with the server.
SASL is not supported for Oracle Unified Directory proxy.
Use the password needed to access the certificates in the client trust store. This option is only required if --trustStorePath is used and the specified trust store requires a password in order to access its contents (which most trust stores do not require). This option must not be used in conjunction with --trustStorePasswordFile.
Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used. This option must not be used in conjunction with --keyStorePassword.
Use the password in the specified file to access the certificates in the client trust store. This option is only required if --trustStorePath is used and the specified trust store requires a password in order to access its contents (most trust stores do not require this). This option must not be used in conjunction with --trustStorePassword.
Set the LDAP protocol version that the client should use when communicating with the directory server. The value must be either 2 (for LDAPv2 communication) or 3 (for LDAPv3). If this option is not provided, then the client will use LDAPv3.
Use the bind password when authenticating to the directory server. This option can be used for simple authentication as well as password-based SASL mechanisms. This option must not be used in conjunction with --bindPasswordFile. To prompt for the password, type -w -.
SASL is not supported for Oracle Unified Directory proxy.
Use the password needed to access the certificates in the client keystore. This option is only required if --keyStorePath is used. This option must not be used in conjunction with --keyStorePasswordFile.
Trust any certificate that the directory server might present during SSL or StartTLS negotiation. This option can be used for convenience and testing purposes, but for security reasons a trust store should be used to determine whether the client should accept the server certificate.
Use SSL when communicating with the directory server. If SSL is to be used, then the --port option should be used to specify the server's secure port.
Indicate that a properties file will not be used to get the default command-line options.
Specify the path to the properties file that contains the default command-line options.
Run in verbose mode, displaying process and diagnostic information on standard output.
Display command-line usage information for the command and exit without making any attempt to run the command.
Display the version information for the directory server.
The following examples show how to use the directory server commands. See System Requirements and Certification in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory for more information.
Example 3-9 Adding an Entry
The following LDIF file contains an entry for an employee:
dn: uid=Marcia Garza,ou=People,dc=example,dc=com cn: Marcia Garza sn: Garza givenName: Marcia objectClass: person objectClass: inetOrgPerson objectClass: top objectClass: organizationalPerson ou: Accounting ou: People
The following command specifies the host name (-h), port (-p), bind DN (-D), bind password (-w), reads the modifications from the file (-f) and adds the entry (-a) to the database. For Windows platforms, specify the path to your LDIF file (for example, -f \temp\add_entry.ldif).
$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -w password \ -a -f /usr/local/add_entry.ldif
Example 3-10 Adding an Attribute to an Entry
The following LDIF file modifies an entry by adding a telephonenumber attribute:
dn: uid=Marcia Garza,ou=People,dc=example,dc=com changetype: modify add: telephonenumber telephonenumber: +1 408 555 8283
The following command specifies the host name (-h), port (-p), bind DN (-D), bind password (-w), reads the modifications from the file (-f) and adds an attribute to the entry. For Windows platforms, specify the path to your LDIF file (for example,
-f \temp\add_attribute.ldif).
$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -w password \ -f /usr/local/add_attribute.ldif
Example 3-11 Modifying the Value of an Attribute
The following LDIF file modifies the value of the telephonenumber attribute:
dn: uid=Marcia Garza,ou=People,dc=example,dc=com changetype: modify replace: telephonenumber telephonenumber: +1 408 555 6456
The following command specifies the hostname (-h), port (-p), bind DN (-D),
bind password (-w), reads the modifications from the file (-f) and modifies the attribute's value. For Windows-platforms, specify the path to your LDIF file (for example, -f \temp\modify_attribute.ldif).
$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -w password \ -f /usr/local/modify_attribute.ldif
Example 3-12 Modifying Multiple Attributes
The following LDIF file contains multiple modifications to an entry:
dn: uid=Marcia Garza,ou=People,dc=example,dc=com changetype: modify replace: telephonenumber telephonenumber: +1 408 555 6465 - add: facsimiletelephonenumber facsimiletelephonenumber: +1 408 222 4444 - add: l l: Sunnyvale
The following command specifies the host name (-h), port (-p), bind DN (-D), bind password (-w), reads the modifications from the file (-f) and processes the changes to the database. For Windows platforms, specify the path to your LDIF file (for example,-f \temp\mod_attribute.ldif):
$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -w password \ -f /usr/local/mod_attribute.ldif
Example 3-13 Deleting an Attribute from the Command Line
The following command specifies the host name (-h), port (-p), bind DN (-D), bind password (-w), and deletes the facsimiletelephonenumber attribute for an entry. Because the command is run from the command line, enter the dn, changetype, modification operation, and then press Control-D (UNIX, Linux) or Control-Z (Windows) to process it:
$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -w password dn: uid=Marcia Garza,ou=People,dc=example,dc=com changetype: modify delete: facsimiletelephonenumber (Press Control-D for Unix, Linux) (Press Control-Z for Windows)
Example 3-14 Deleting an Entry from the Command Line
The following command specifies the hostname (-h), port (-p), bind DN (-D), bind password (-w), and deletes the entry. Because the command is run from the command line, enter the dn, changetype, and then press Control-D (UNIX, Linux) or Control-Z (Windows) to process it:
$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -w password dn: uid=Marcia Garza,ou=People,dc=example,dc=com changetype: delete (Press Control-D for Unix, Linux) (Press Control-Z for Windows)
Example 3-15 Using ldapmodify with Server Authentication
The following command uses the -P SSL option to perform a modify with server authentication. The command specifies the host name (-h), SSL port (-p), base DN (-b), the bind DN (-D), the bind password (-w), trust store file path (-P), and LDIF file (-f) that contains the changes. For Windows platforms, specify the paths for the modification file (for example, -f \temp\myldif.ldif) and trust store file (for example, -P \temp\certs\cert.db):
$ ldapmodify -h hostname -p 1636 -f /home/local/myldif.ldif \ -D "cn=Directory Manager" -w password \ -P /home/scarter/certs/cert.db
Example 3-16 Using ldapmodify with Client Authentication
The following command uses the -P SSL option to perform a modify using client authentication. The command uses SSL (-Z) with the SSL port (-p) and specifies the trust store file path (-P), the certificate nickname (-N), the keystore file path (-K), the keystore password (-W) and the LDIF file (-f) that contains the changes. For Windows platforms, specify the paths for the modification file (for example, -f \temp\myldif.ldif), trust store file (for example, -P \certs\cert.db), and the keystore file (for example, -K \security\key.db):
$ ldapmodify -h hostname -p 1636 -f /home/local/myldif.ldif \ -Z -P /home/scarter/security/cert.db -N "sccert" \ -K /home/scarter/security/key.db -W keypassword
An exit code of 0 indicates that the operation completed successfully. A nonzero exit code indicates that an error occurred during processing.
The directory server supports the use of a properties file that passes in any default option values used with the ldapmodify command. The properties file is convenient when working in different configuration environments, especially in scripted or embedded applications. See Using a Properties File With Server Commands for more information.
The following options can be stored in a properties file:
assertionFilter
bindDN
bindPassword
bindPasswordFile
certNickname
continueOnError
control
dry-run
filename
hostname
keyStorePassword
keyStorePasswordFile
keyStorePath
ldapVersion
port
postReadAttributes
preReadAttributes
proxyAs
reportAuthzID
saslOption
SASL is not supported for Oracle Unified Directory proxy.
trustAll
trustStorePassword
trustStorePasswordFile
trustStorePath
useSASLExternal
SASL is not supported for Oracle Unified Directory proxy.
useSSL
useStartTLS
verbose
Entries in the properties file have the following format:
toolname.propertyname=propertyvalue
For example:
ldapmodify.ldapport=12345
UNIX and Linux: instance-dir/OUD/bin/ldapmodify
Windows: instance-dir\OUD\bat\ldapmodify.bat
|