A.4. Generating LDAP URLs

LDAP URLs are used in a variety of different configuration areas and operations: referrals and chaining, replication, synchronization, ACIs, and indexing, as a starting list. Constructing accurate LDAP URLs is critical, because incorrect URLs may connect to the wrong server or simply cause operations to fail. Additionally, all OpenLDAP tools allow the -H option to pass an LDAP URL instead of other connection information (like the host name, port, subtree, and search base).

Note

LDAP URLs are described in Appendix C, LDAP URLs.
The ldapurl command manages URL in two ways:
  • Deconstruct a given LDAP URL into its constituent element
  • Construct a new, valid LDAP URL from given elements
The parameters for working with URLs are listed in Table A.1, “ldapurl Parameters”; the full list of parameters are in the OpenLDAP manpages.

Table A.1. ldapurl Parameters

Option Description
For Deconstructing a URL
-H "URL" Passes the LDAP URL to break down into elements.
For Constructing a URL
-a attributes Gives a comma-separated attributes that are specifically returned in search results.
-b base Sets the search base or subtree for the URL.
-f filter Sets the search filter to use.
-h hostname Gives the Directory Server's host name.
-p port Gives the Directory Server's port.
-S ldap|ldaps|ldapi Gives the protocol to use to connect, such as ldap, ldaps, or ldapi.
-s scope Gives the search scope.

Example A.8. Deconstructing an LDAP URL

ldapurl uses the -H option to feed in an existing LDAP URL, and the tool returns the elements of the URL in a neat list:
# ldapurl -H "ldap://:389/dc=example,dc=com?cn,sn?sub?(objectclass=inetorgperson)"
scheme: ldap
port: 389
dn: dc=example,dc=com
selector: cn
selector: sn
scope: sub
filter: (objectclass=inetorgperson)

Example A.9. Constructing an LDAP URL

The most useful application of ldapurl is to construct a valid LDAP URL manually. The Directory Server Console has tools to develop valid URLs for areas like ACIs and referrals, but very complex configurations or scripted operations may require administrators to manually construct the URL. Using ldapurl ensures that the URL is valid.
ldapurl accepts the normal connection parameters of all LDAP client tools and additional ldapsearch arguments for search base, scope, and attributes, but this tool never connects to a Directory Server instance, so it does not require any bind information. It accepts the connection and search settings and feeds them in as elements to the URL.
ldapurl -a cn,sn -b dc=example,dc=com -s sub -f "(objectclass=inetorgperson)"

ldap://:389/dc=example,dc=com?cn,sn?sub?(objectclass=inetorgperson)