Configuring the Directory Server
Configuring Security in the Directory Server
Populating a Stand-Alone Directory Server With Data
Importing Data Using import-ldif
To Import Data in Offline Mode
To Replace Existing Data During an Offline Import
To Append Imported Data to Existing Data
To Import Fractional Files by Using Filters
To Include or Exclude Attributes During Import
To Import a Compressed LDIF File
To Record Rejected or Skipped Entries During Import
To Import Data From a MakeLDIF Template
To Run an Import in Online Mode
Exporting Data Using export-ldif
To Export Part of a Back End by Using Filters
To Include or Exclude Attributes During Export
To Export to LDIF and Then Compress the File
To Run an Export in Online Mode
Importing and Exporting Entries With the Control Panel
To Import Entries With the Control Panel
To Export Entries to an LDIF File With the Control Panel
Creating MakeLDIF Template Files
Overview of the Backup and Restore Process
To Back Up All Back Ends with Encryption and Signed Hashes
To Perform an Incremental Backup on All Back Ends
To Back Up a Specific Back End
To Perform an Incremental Backup on a Specific Back End
To Schedule a Backup as a Task
Backing Up the Server Configuration
Backing Up for Disaster Recovery
To Back Up the Directory Server For Disaster Recovery
To Restore a Back End From Incremental Backups
To Schedule a Restore as a Task
To Restore the Configuration File
To Restore a Directory Server During Disaster Recovery
Restoring Replicated Directory Servers
Backing Up and Restoring Directory Data With the Control Panel
To Back Up Data With the Control Panel
To Restore Data With the Control Panel
Overview of the ldapsearch Command
ldapsearch Location and Format
To Search for Specific User Attributes
To Perform a Search With Base Scope
To Perform a Search With One-Level Scope
To Perform a Search With Subtree Scope
To Return Attribute Names Only
To Return User Attributes Only
To Search For Specific Object Classes
To Return a Count of All Entries in the Directory
To Perform a Search With a Compound Filter
To Perform a Search Using a Filter File
To Limit the Number of Entries Returned in a Search
Using Advanced Search Features
Searching for Special Entries and Attributes
To Search for Operational Attributes
To Search the Configuration Entry
To Search the Monitoring Entry
To Search Over SSL With Blind Trust
To Search Over SSL Using a Trust Store
To Search Over SSL With No Trust Store
To Search Over SSL Using a Keystore
To Search Using SASL With DIGEST-MD5 Client Authentication
To Search Using SASL With the GSSAPI Mechanism
To Search Using SASL With the PLAIN Mechanism
To View the Available Controls
To Search Using the Account Usability Request Control
To Search Using the Authorization Identity Request Control
To Search Using the Get Effective Rights Control
To Search Using the LDAP Assertion Control
To Search Using the LDAP Subentry Control
To Search Using the Manage DSA IT Control
To Search Using the Matched Values Filter Control
To Search Using the Password Policy Control
To Search Using the Persistent Search Control
To Search Using the Proxied Authorization Control
Searching Using the Virtual List View Control
To Search Using the Virtual List View Control
To Search Using Virtual List View With a Specific Target
To Search Using Virtual List View With a Known Total
Searching in Verbose Mode and With a Properties File
To Search Using a Properties File
Searching Internationalized Entries
Adding, Modifying, and Deleting Directory Data
To Add an Entry Using the --defaultAdd Option With ldapmodify
To Add Entries Using an LDIF Update Statement With ldapmodify
To Add an Attribute to an Entry
To Add an International Attribute
To Modify an Attribute With Before and After Snapshots
To Delete an Entry With ldapmodify
To Delete an Entry With ldapdelete
To Delete Multiple Entries by Using a DN File
Configuring Indexes on the Local DB Back End
To Create a New Local DB Index
Managing Indexes With the Control Panel
To Enable or Disable Compact Encoding
To Enable or Disable Entry Compression
Managing Directory Data With the Control Panel
Managing Entries With the Control Panel
To Display A List of All Directory Entries
To Add a New Entry With the Control Panel
To Add a New Entry From an LDIF Specification With the Control Panel
To Change the Values of an Entry's Attributes With the Control Panel
To Delete an Entry With the Control Panel
Managing Base DNs With the Control Panel
Copying an Entry's DN to the Clipboard
Deleting a Back End With the Control Panel
To Delete a Back End With the Control Panel
Selecting a View of Entry Data
To Select a View of Entry Data
Ensuring Attribute Value Uniqueness
Overview of the Unique Attribute Plug-In
Configuring the Unique Attribute Plug-In Using dsconfig
To Ensure Uniqueness of the Value of the uid Attribute
To Ensure Uniqueness of the Value of Any Other Attribute
Replication and the Unique Attribute Plug-In
Configuring Virtual Attributes
To List the Existing Virtual Attributes
To Create a New Virtual Attribute
To Enable or Disable a Virtual Attribute
To Display the Configuration of a Virtual Attribute
LDAP controls extend the functionality of LDAP commands, such as ldapsearch, to carry out additional operations on top of the search. Each control is defined as an object identifier (OID) that uniquely identifies the control, a criticality flag, and any associated values. If the client sets the criticality flag when sending the control to the directory server, the directory server must either perform the operation with the control or not process it. If the flag is not set by the client, the directory server is free to ignore the control if it cannot process it.
You can use multiple controls in a single operation, such as the virtual list view with server-side sorting. The virtual list view control requires additional explanation and is therefore described in its own section, following this one.
You can view the current list of controls for your directory server by searching the Root DSE entry for the supportedControl attribute.
$ ldapsearch -h localhost -p 1389 -b "" --searchScope base \ "(objectclass=*)" supportedControl dn: supportedControl: 1.2.826.0.1.3344810.2.3 supportedControl: 1.2.840.113556.1.4.319 supportedControl: 1.2.840.113556.1.4.473 supportedControl: 1.2.840.113556.1.4.805 supportedControl: 1.3.6.1.1.12 supportedControl: 1.3.6.1.1.13.1 supportedControl: 1.3.6.1.1.13.2 supportedControl: 1.3.6.1.4.1.26027.1.5.2 supportedControl: 1.3.6.1.4.1.42.2.27.8.5.1 supportedControl: 1.3.6.1.4.1.42.2.27.9.5.2 supportedControl: 1.3.6.1.4.1.42.2.27.9.5.8 supportedControl: 1.3.6.1.4.1.4203.1.10.2 supportedControl: 1.3.6.1.4.1.7628.5.101.1 supportedControl: 2.16.840.1.113730.3.4.12 supportedControl: 2.16.840.1.113730.3.4.16 supportedControl: 2.16.840.1.113730.3.4.17 supportedControl: 2.16.840.1.113730.3.4.18 supportedControl: 2.16.840.1.113730.3.4.19 supportedControl: 2.16.840.1.113730.3.4.2 supportedControl: 2.16.840.1.113730.3.4.3 supportedControl: 2.16.840.1.113730.3.4.9
The controls are returned as a list of OIDs. See the following table for a description of the control that corresponds to each OID. Note that not all of these controls can be used with the ldapsearch command.
|
The Account Usability Request Control determines if a user account can be used to authenticate to a server. If the user account is available, the control adds a message before any entry about whether the account is usable.
You can specify the Account Usability Request Control with ldapsearch in the following ways:
OID. Use the --control or -J option with the Account Usability Request Control OID: 1.3.6.1.4.1.42.2.27.9.5.8 with no value.
Named constant. Use a named constant, accountusable or accountusability, with the --control or -J option, instead of using the Account Usability Request Control OID. For example, use -J accountusable or -J accountusability with the ldapsearch command.
$ ldapsearch -h localhost -p 1389 -b "dc=example,dc=com" \ --searchScope sub -J "accountusability:true" "(objectclass=*)" # Account Usability Response Control # The account is usable dn: dc=example,dc=com objectClass: domain objectClass: top dc: example ...
The Authorization Identity Request Control allows the client to obtain the authorization identity for the client connection during the LDAP bind request. The authorization ID returned by the server is displayed to the client as soon as authentication has completed. The line containing the authorization ID is prefixed with a # character, making it a comment if the output is to be interpreted as an LDIF.
You can specify the Authorization Identity Request Control with ldapsearch in a number of ways:
OID. Use the --control or -J option with the Authorization Identity Request Control OID: 2.16.840.1.113730.3.4.16 with no value.
Named constant. Use a named constant, authzid or authorizationidentity with the -control or -J option instead of using the Authorization Identity Request Control OID. For example, use -J authzid or -J authorizationidentity with the ldapsearch command.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" \ -w password -b dc=example,dc=com --searchScope base \ --reportAuthzID "(objectclass=*)" # Bound with authorization ID dn:cn=Directory Manager,cn=Root DNs,cn=config dn: dc=example,dc=com objectClass: domain objectClass: top dc: example
The Get Effective Rights Control enables you to evaluate existing or new ACIs and to see the effective rights that they grant for a user on a specified entry.
The response to this control is to return the effective rights information about the entries and attributes in the search results. This extra information includes read and write permissions for each entry and for each attribute in each entry. The permissions can be requested for the bind DN used for the search or for an arbitrary DN, allowing administrators to test the permissions of directory users.
The ldapsearch command provides two ways to use the Get Effective Rights Control:
Use -J effectiverights or the OID -J "1.3.6.1.4.1.42.2.27.9.5.2". The request only takes an authorization ID (authzid). If you specify a NULL value for the authorization ID (authzid), the bind user is used as the authzid.
Use -g dn:"dn". The command option shows the effective rights of the user binding with the given DN. You can use this option together with the -e option to include the effective rights on the named attributes. You can use the option to determine if a user has permission to add an attribute that does not currently exist in an entry.
Note - You cannot use the -g option with the -J option.
To view effective rights, you should specify the virtual attributes aclRights and aclRightsInfo, which are generated by the server in response to the effective rights request. Thus, you should not use these attributes in search commands of any kind.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -b dc=example,dc=com -J effectiverights "(objectclass=*)" aclRights dn: dc=example,dc=com aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0 dn: ou=Groups, dc=example,dc=com aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0 dn: ou=People, dc=example,dc=com aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0 dn: cn=Accounting Managers,ou=groups,dc=example,dc=com aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0 dn: cn=HR Managers,ou=groups,dc=example,dc=com aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0 ...
This example uses the --getEffectiveRightsAuthzid option. You can also use the --control or -J option, such as -J geteffectiverights.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -b dc=example,dc=com \ --getEffectiveRightsAuthzid "dn:uid=scarter,ou=People,dc=example,dc=com" \ "(uid=scarter)" aclRights dn: uid=scarter,ou=People,dc=example,dc=com aclRights;entryLevel: add:0,delete:0,read:1,write:1,proxy:0
The aclRightsInfo attribute provides more detailed logging information that explains how effective rights are granted or denied.
ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -b dc=example,dc=com \ --getEffectiveRightsAuthzid "dn:uid=scarter,ou=People,dc=example,dc=com"\ "(uid=scarter)" aclRightsInfo dn: uid=scarter,ou=People,dc=example,dc=com aclRightsInfo;logs;entryLevel;add: acl_summary(main): access not allowed(add) on entry/attr(uid=scarter,ou=People,dc=example,dc=com, NULL) to (uid=scarter,ou=People,dc=example,dc=com) (not proxied) ( reason: no acis matched the subject ) aclRightsInfo;logs;entryLevel;proxy: acl_summary(main): access not allowed(proxy ) on entry/attr(uid=scarter,ou=People,dc=example,dc=com, NULL) to (uid=scarter, ou=People,dc=example,dc=com) (not proxied) ( reason: no acis matched the subject ) aclRightsInfo;logs;entryLevel;write: acl_summary(main): access allowed(write) on entry/attr(uid=scarter,ou=People,dc=example,dc=com, NULL) to (uid=scarter,ou=People,dc=example,dc=com) (not proxied) ( reason: evaluated allow , deciding_aci : Allow self entry modification) aclRightsInfo;logs;entryLevel;read: acl_summary(main): access allowed(read) on entry/attr(uid=scarter,ou=People,dc=example,dc=com, NULL) to (uid=scarter,ou=People,dc=example,dc=com) (not proxied) ( reason: evaluated allow , deciding_aci: Anonymous extended operation access) aclRightsInfo;logs;entryLevel;delete: acl_summary(main): access not allowed(delete) on entry/attr(uid=scarter,ou=People,dc=example,dc=com, NULL) to (uid=scarter,ou=People,dc=example,dc=com) (not proxied) ( reason: no acis matched the subject )
The LDAP Assertion Control allows you to specify a condition that must evaluate to true for the searching operation to process. The value of the control should be in the form of an LDAP search filter. The server tests the base object before searching for entries that match the search scope and filter. If the assertion fails, no entries are returned.
This example determines first if the assertion is met, and returns the entry if it matches the search filter.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -b "cn=HR Managers,ou=Groups,dc=example,dc=com" \ -s sub \ --assertionFilter "(objectclass=top)" "(objectclass=*)" dn: cn=HR Managers,ou=groups,dc=example,dc=com objectClass: groupOfUniqueNames objectClass: top ou: groups description: People who can manage HR entries uniqueMember: uid=kvaughan, ou=People, dc=example,dc=com uniqueMember: uid=cschmith, ou=People, dc=example,dc=com cn: HR Managers
The LDAP Subentry Control allows the client to request that the server return only entries with the ldapSubEntry object class during a search operation. LDAP subentries are operational objects, similar to operational attributes, that are returned only if explicitly requested. Typically, you can use the control when searching the schema.
You can specify the LDAP Subentry Control with ldapsearch with base-level scope (that is, --searchScope base) in a number of ways:
Equality filters. Use the equality filter, (objectclass=ldapSubentry).
OID. Use the --control or -J option with the LDAP Subentry Control OID: 1.3.6.1.4.1.7628.5.101.1 with no value.
Named constant. Use the named constant, subentries, with the --control or -J option instead of using the LDAP Subentry Control OID. For example, use -J subentries with the ldapsearch command.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -b "cn=schema" -s base -J subentries "(objectclass=*)"
The Manage DSA IT Control allows the client to request that the server treat smart referrals as regular entries during the search. A smart referral is an entry that references another server or location in the directory information tree DIT and contains the referral object class with one or more attributes containing the LDAP URLs that specify the referral.
You can specify the Manage DSA IT Control with ldapsearch in a number of ways:
OID. Use the --control or -J option with the Manage DSA IT Control OID: 2.16.840.1.113730.3.4.2 with no value.
Named constant. Use the named constant, managedsait with the --control or -J option instead of the Manage DSA IT Control OID. For example, use -J managedsait with the ldapsearch command.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -b dc=example,dc=com -J managedsait "(uid=president)" ref dn: uid=president,ou=People,dc=example,dc=com ref: ldap://example.com:389/dc=example,dc=com??sub?(uid=bjensen)
Note - Without the -J managedsait argument, the command returns the referred entry.
The Matched Values Filter Control allows clients to request a subset of attribute values from an entry that evaluate to TRUE. This control allows the user to selectively read a subset of attribute values without retrieving all values, and then scan for the desired set locally.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -b ou=groups,dc=example,dc=com --matchedValuesFilter "(uniquemember=uid=kvaughan*)" "(objectclass=*)" dn: ou=Groups,dc=example,dc=com dn: cn=Directory Administrators,ou=Groups,dc=example,dc=com uniqueMember: uid=kvaughan, ou=People, dc=example,dc=com dn: cn=Accounting Managers,ou=groups,dc=example,dc=com dn: cn=HR Managers,ou=groups,dc=example,dc=com uniqueMember: uid=kvaughan, ou=People, dc=example,dc=com dn: cn=QA Managers,ou=groups,dc=example,dc=com dn: cn=PD Managers,ou=groups,dc=example,dc=com
The Password Policy Control allows a client to request information about the current password policy information for a user entry.
You can specify the Password Policy Control with ldapsearch in a number of ways:
OID. Use the --control or -J option with the Password Policy Control OID: 1.3.6.1.4.1.42.2.27.8.5.1 with no value.
Named constant. Use the named constants, pwpolicy or passwordpolicy with the --control or -J option instead of the Password Policy Control OID. For example, use -J pwpolicy or -J passwordpolicy with ldapsearch.
Option. Use the --usePasswordPolicyControl option.
Note - The -J or --control option is used to specify which controls to use in a search request. The --usePasswordPolicyControl option is used for bind requests.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -b dc=example,dc=com -s base --usePasswordPolicyControl "(objectclass=*)"
The Persistent Search Control allows a client to receive notification when entries in the directory are changed by an add, delete, or modify operation. When a change occurs, the server sends the updated entry to the client if the entry matches the search criteria that was used by the Entry Change Notification Control.
The ldapsearch command provides an option to run a persistent search (-C) that keeps the connection open and displays the entries that match the scope and filter whenever any changes (add, delete, modify, or all) occur. You can quit the search by pressing Control-C.
The value for this argument must be in the form: ps[[:''changetype''[[:''changesonly''[[:''entrychangecontrols'']]]
The elements of this value include the following:
ps — Required operator.
changetype — Indicates the types of changes for which the client wants to receive notification. This element can be any of add, del, mod, or moddn, or it can be all to register for all change types. It can also be a comma-separated list to register for multiple specific change types. If this element is not provided, it defaults to including all change types.
changesonly — If True, the client should only be notified of changes that occur to matching entries after the search is registered. If False, the server should also send all existing entries in the server that match the provided search criteria. If this element is not provided, then it will default to only returning entries for updates that have occurred since the search was registered.
entrychangecontrols — If True, the server should include the Entry Change Notification Control in entries sent to the client as a result of changes. If False, the Entry Change Notification Control should not be included. If this element is not provided, then it will default to including the Entry Change Notification Controls.
$ ldapsearch -h localhost -p 1389 -D "cn=admin,cn=Administrators,cn=config" \ -w password -b dc=example,dc=com --persistentSearch ps:add:true:true \ "(objectclass=*)"
Note - When you use this command, the server waits for any changes made using add, delete, modify or all to return values.
$ ldapmodify -h localhost -p 1389 -b dc=example,dc=com \ --defaultAdd --filename new_add.ldif Processing ADD request for uid=Marcia Garza,ou=People,dc=example,dc=com ADD operation successful for DN uid=Marcia Garza,ou=People,dc=example,dc=com
To end the session, press Control-Z (Unix/Linux) or Control-C (Windows).
# Persistent search change type: add dn: uid=Marcia Garza,ou=People,dc=example,dc=com objectClass: person objectClass: inetOrgPerson objectClass: organizationalPerson objectClass: top givenName: Marcia uid: mgarza uid: Marcia Garza cn: Marcia Garza sn: Garza userpassword: {SSHA}SNfL1RUm5uvTnLK+G0K3oz+Peb1i5/+YsylfBg== roomnumber: 5484 l: Santa Clara ou: Accounting ou: People mail: mgarza@example.com
Terminate batch job (Y/N)?
The Proxied Authorization Control allows a client to impersonate another entry for a specific operation. This control can be useful in trusted applications that need to perform on behalf of many different users, so that the application does not need to re-authenticate for each operation.
Here, clientApp must have the appropriate ACI permissions within the subtree to use the Proxied Authorization Control. If not granted, LDAP error 50 insufficient access rights will be returned to the client.
$ ldapsearch -h localhost -p 1389 \ -D "uid=clientApp,ou=Applications,dc=example,dc=com" -w password \ -s sub -b dc=example,dc=com \ --proxyAs "dn:uid=acctgAdmin,ou=Administrators,ou=People,dc=example,dc=com" \ "(uid=kvaughan)" mail
The Server-Side Sort Control allows the client to request that the server sort the search results before sending them to the client. This is convenient when the server has indexes that can satisfy the sort order requested by the client faster than the client can.
You can sort the number of entries returned by using the --sortorder option. If you do not specify + (a plus sign) for ascending or - (a minus sign) for descending, then the default option is to sort in ascending order.
Use the --sortorder option sorted on the attributes sn and givenName.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ --s sub -b dc=example,dc=com --sortorder sn,givenName "(objectclass)" dn: uid=dakers,ou=People,dc=example,dc=com objectClass: person objectClass: organizationalPerson ...<search results>...
Use the --sortorder option sorted on the attribute sn.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -s sub -b dc=example,dc=com --sortorder -sn "(objectclass)" dn: uid=pworrell,ou=People,dc=example,dc=com objectClass: person objectClass: organizationalPerson ...<search results>...
The Simple Paged Results Control allows a search operation to return only a subset of the results at a time. It can be used to iterate through the search results a page at a time. It is similar to the Virtual List View Control with the exception that it does not require the results to be sorted and can only be used to iterate sequentially through the search results.
The following command also uses the --countEntries option to mark each page.
$ ldapsearch --hostname localhost --port 1389 \ --bindDN "cn=Directory Manager" --bindPassword password \ --searchScope sub --baseDN dc=example,dc=com \ --simplePageSize 2 --countEntries "(objectclass=*)" dn: ou=Groups,dc=example,dc=com objectClass: organizationalunit objectClass: top ou: Groups dn: ou=People,dc=example,dc=com objectClass: organizationalunit objectClass: top ou: People # Total number of matching entries: 2 dn: ou=Special Users,dc=example,dc=com objectClass: organizationalUnit objectClass: top description: Special Administrative Accounts ou: Special Users dn: ou=Company Servers,dc=example,dc=com objectClass: organizationalUnit objectClass: top description: Standard branch for Company Server registration ou: Company Servers # Total number of matching entries: 2 dn: ou=Contractors,dc=example,dc=com objectClass: organizationalUnit objectClass: top ou: Contractors ou: Product Testing ou: Product Development ou: Accounting # Total number of matching entries: 1