Sun ONE Directory Server 5.2 Getting Started Guide: Chapter 4 A Quick Look at Directory Server Command-Line Utilities

Sun ONE Directory Server 5.2 Getting Started Guide

Chapter 4 A Quick Look at Directory Server Command-Line Utilities

This chapter provides practical examples of the features described in Chapter 2 "Introduction to Sun ONE Directory Server", using the command-line utilities. It also contains basic information on some of the files installed with Sun ONE Directory Server that will help you understand where default directory data is located and how it can be accessed and modified.

This chapter covers the following topics:

Examining the Configuration

Examining the Data

Adding, Changing and Deleting Entries

Working With the Schema

Working With Groups and Roles

Working With Class of Service (CoS)

Working With ACIs

Examining the Log Information

Searching an Internationalized Directory

Note
This chapter assumes that you have successfully installed Sun ONE Directory Server. For more information on how to do this, see "Installing and Configuring Directory Server".

Examining the Configuration

Directory Server configuration information is held in the file dse.ldif, located in the ServerRoot/slapd-serverID/config directory. In our sample installation performed in the previous chapter, the configuration file is slapd-myServer/config/dse.ldif. Directory Server requires this file at startup.

Locate the configuration file in your installation and open the file in a text editor. (On Windows systems, use an editor other than Notepad.)

The following is an extract of the dse.ldif file from the sample installation performed in the previous chapter.

Code Example 4-1    Extract From Sample dse.ldif File

dn:
objectClass: top
aci: (targetattr != "aci")(version 3.0; aci "rootdse anon read access"; allow(read,search,compare) userdn="ldap:///anyone";)
creatorsName: cn=server,cn=plugins,cn=config
modifiersName: cn=server,cn=plugins,cn=config
createTimestamp: 20020428110553Z
modifyTimestamp: 20020428110553Z

dn: cn=config
cn: config
objectClass: top
objectClass: extensibleObject
objectClass: nsslapdConfig
nsslapd-accesslog-logging-enabled: on
nsslapd-accesslog: ServerRoot/slapd-myServer/logs/access
nsslapd-accesslog-maxlogsperdir: 10
nsslapd-accesslog-maxlogsize: 100
nsslapd-accesslog-logrotationtime: 1
nsslapd-accesslog-logrotationtimeunit: day
nsslapd-enquote-sup-oc: off
nsslapd-localhost: myServer.example.COM

Examine the dse.ldif file from your own installation. Note the default configuration attributes and their values.

Note
To change attribute values, do not modify the dse.ldif file directly. Instead, use the ldapmodify client utility, described in this section, then restart Directory Server to force it to reread the dse.ldif file.

Examining the Data

As described in Chapter 2, Sun ONE Directory Server is installed with two default databases:

userRoot, the default database you selected at installation.

NetscapeRoot, a database that contains the configuration information of other Sun ONE servers, such as Sun ONE Administration Server.

Both databases are located in the slapd-serverID/db directory. In our installation, these files are located in slapd-myServer/db. Locate the database directory in your installation and check that the two default databases are there.

LDIF File Format

Directory Server uses the LDAP Data Interchange Format (LDIF) to describe a directory and directory entries in text format. LDIF is commonly used to build the initial directory database or to add large numbers of entries to the directory all at once. In addition, LDIF is also used to describe changes to directory entries. For this reason, most of Directory Server's command-line utilities rely on LDIF for either input or output. For more information on the LDIF file format, see LDIF File Format in the Sun ONE Directory Server Reference Manual.

LDIF consists of one or more directory entries separated by a blank line. Each LDIF entry consists of an optional entry ID, a required distinguished name, one or more object classes, and multiple attribute definitions.

The basic form of a directory entry represented in LDIF is as follows:

dn: distinguished_name
objectClass: object_class
objectClass: object_class
...
attribute_type[;subtype]:attribute_value
attribute_type[;subtype]:attribute_value
...

Note
Do not leave white space unintentionally at the end of an LDIF attribute value string. When Directory Server reads an attribute value ending in white space, it base 64 encodes the value.

Sample ldif File

The following is a small sample ldif file, data.ldif. This file will be used to create a database in the next section. Note that this sample file contains the following:

One organization (MyCorp)

One group (Administrators)

Three people (Aaron Brown, Brian Crane and Charlene Daniels)

dn: dc=example,dc=com
objectclass: top
objectclass: domain
dc: example

dn: o=MyCorp,dc=example,dc=com
objectclass: top
objectclass: organization
o: MyCorp

dn: ou=Groups,o=MyCorp,dc=example,dc=com
objectclass: top
objectclass: organizationalUnit
ou: Groups

dn: cn=Administrators,ou=Groups,o=MyCorp,dc=example,dc=com
objectclass: top
objectclass: groupOfUniqueNames
cn: Administrators
uniqueMember: uid=abrown,ou=People,o=MyCorp,dc=example,dc=com
uniqueMember: uid=bcrane,ou=People,o=MyCorp,dc=example,dc=com

dn: ou=People,o=MyCorp,dc=example,dc=com
objectclass: top
objectclass: organizationalUnit
ou: People

dn: uid=abrown,ou=People,o=MyCorp,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
uid: abrown
givenName: Aaron
sn: Brown
cn: Aaron Brown
mail: abrown@mycorp.com
userPassword: abrown
facsimiletelephonenumber: 666

dn: uid=bcrane,ou=People,o=MyCorp,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
uid: bcrane
givenName: Brian
sn: Crane
cn: Brian Crane
mail: bcrane@mycorp.com
userPassword: bcrane
secretary: uid=abrown,ou=People,o=MyCorp,dc=example,dc=com

dn: uid=cdaniels,ou=People,o=MyCorp,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
uid: cdaniels
givenName: Charlene
sn: Daniels
cn: Charlene Daniels
mail: cdaniels@mycorp.com
userPassword: cdaniels
secretary: uid=abrown,ou=People,o=MyCorp,dc=example,dc=com

Creating a New Suffix

Before you can import data into a new database, you must set up the database configuration by creating a new suffix. In the following example, we will create a new suffix called example. Creating a new suffix at the command-line involves using the ldapmodify command to add an LDIF entry to the directory.

To create a new backend and suffix for the sample database:

At the command-line type:

ldapmodify -a -p 5201 -D "cn=directory manager" -w password
dn: cn="dc=example,dc-com",cn=mapping tree,cn=config
objectClass: top
objectClass: extensibleObject
objectClass: nsMappingTree
cn: example
nsslapd-state: backend
nsslapd-backend: example

Remember that 5201 was the port specified at installation and password was the password specified for the directory manager. If you used alternative values at installation, replace these with the values you used.

After the last line, hit Return and Ctrl-D (on UNIX platforms) or Ctrl-Z (on Windows platforms) to indicate the end the file.

At the command-line type:

ldapmodify -a -p 5201 -D "cn=directory manager" -w password
dn: cn=example,cn=ldbm database,cn=plugins,cn=config
objectClass: top
objectClass: extensibleObject
objectClass: nsBackendInstance
cn: example
nsslapd-suffix: dc=example,dc=com

After the last line, hit Return and Ctrl-D (on UNIX platforms) or Ctrl-Z (on Windows platforms) to indicate the end the file.

NOTE

The ldapmodify command is explained in detail later in this chapter. For now, it is sufficient to understand that the above command adds a suffix entry to the directory.

Populating a New Database Using ldif2db

Data that is contained in an LDIF file can be imported into the directory as a new database. In this exercise, we will use the ldif2db utility to load a sample database. For a complete description of ldif2db, refer to Chapter 4, "Populating Directory Databases" in the Sun ONE Directory Server Administration Guide.

The ldif2db utility is located in the slapd-serverID/ directory. In our installation it is located in slapd-myServer/.

Create the data.ldif file from the sample file above. ( In a text editor other than Notepad, copy the sample file and save it as /path/data.ldif, where path can be any location to which you have read and write access).

Change to ServerRoot/slapd-myServer/.

Before running the ldif2db conversion, you must stop the server, as follows:

% stop-slapd

When the server is stopped, type the following to import the new data:

% ldif2db -s dc=example,dc=com -i /path/data.ldif

The progress of the import is displayed. The message "Import complete" is displayed when the conversion is complete. For the sample database above, you should see a message indicating that 8 entries were processed.

Restart the server as follows:

% start-slapd

Searching the Directory

You can locate entries in a directory using any LDAP client. Most clients provide some form of search interface that enables you to search the directory and retrieve entry information.

Note
The access control that has been set in your directory determines the results of your searches. Common users typically do not "see" much of the directory, and directory administrators have full access to all data, including configuration.

Searching the Directory With ldapsearch

You can use the ldapsearch command-line utility to locate and retrieve directory entries. Note that the ldapsearch utility described in this section is not the utility provided with the Solaris platform, but is part of the Sun ONE Directory Server Resource Kit. For more information on this utility, refer to the Sun ONE Directory Server Resource Kit Tools Reference.

This utility opens a connection to the server using the specified distinguished name and password, and locates entries based on a specified search filter. Search scopes can include a single entry, an entry's immediate subentries, or an entire tree or subtree.

Search results are returned in LDIF format.

ldapsearch Command-Line Format

When you use ldapsearch, you must enter the command using the following format:

ldapsearch [optional_options] [optional_search_filter] [optional_list_of_attributes]

where

optional_options represents a series of command-line options. These must be specified before the search filter, if any.

optional_search_filter represents an LDAP search filter as described in "LDAP Search Filters". Do not specify a search filter if you are supplying search filters in a file using the -f option.

optional_list_of_attributes represents a list of attributes separated by a space. Specifying a list of attributes reduces the number of attributes returned in the search results. This list of attributes must appear after the search filter. For an example, see "Displaying Subsets of Attributes". If you do not specify a list of attributes, the search returns values for all attributes permitted by the access control set in the directory (with the exception of operational attributes).

Note
If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command. To retrieve regular attributes in addition to explicitly specified operational attributes, use an asterisk (*) in the list of attributes in the ldapsearch command.

Using Special Characters

When using the ldapsearch 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 you specify special characters, enclose the value in quotation marks (""). For example:

-D "cn=Charlene Daniels,ou=People,dc=example,dc=com"

Depending on your command-line interpreter, use either single or double quotation marks for this purpose. Refer to your shell documentation for more information.

Commonly Used ldapsearch options

The following lists the most commonly used ldapsearch command-line options. If you specify a value that contains a space [ ], the value should be surrounded by double quotation marks, for example, -b "ou=groups, dc=example,dc=com".

-b

Specifies the starting point for the search. The value specified here must be a distinguished name that currently exists in the database. This option is optional if the LDAP_BASEDN environment variable has been set to a base DN.

The value specified in this option should be provided in double quotation marks. For example:

-b "cn=Charlene Daniels, ou=People, dc=example,dc=com"

-D

Specifies the distinguished name with which to authenticate to the server. This option is optional if anonymous access is supported by your server. If specified, this value must be a DN recognized by the Directory Server, and it must also have the authority to search for the entries. For example:

-D "uid=cdaniels, dc=example,dc=com"

-h

Specifies the hostname or IP address of the machine on which the Directory Server is installed. If you do not specify a host, ldapsearch uses the localhost. For example, -h myServer.

-l

Specifies the maximum number of seconds to wait for a search request to complete. Regardless of the value specified here, ldapsearch will never wait longer than is allowed by the server's nsslapd-timelimit attribute (except in the case of a persistent search.) For more information on persistent searches, see Chapter 3 "ldapsearch" in the Sun ONE Directory Server Resource Kit Tools Reference.

For example, -l 300. The default value for the nsslapd-timelimit attribute is 3,600 seconds (1 hour.)

-p

Specifies the TCP port number that the Directory Server uses. For example, -p 5201. The default is 389. If -Z is used, the default is 636.

-s

Specifies the scope of the search. The scope can be one of the following:

base—Search only the entry specified in the -b option or defined by the LDAP_BASEDN environment variable.

one—Search only the immediate children of the entry specified in the -b option. Only the children are searched; the actual entry specified in the -b option is not searched.

sub—Search the entry specified in the -b option and all of its descendants. That is, perform a subtree search starting at the point identified in the -b option. This is the default.

-w

Specifies the password associated with the distinguished name that is specified in the -D option. If you do not specify this option, anonymous access is used. For example, -w diner892.

-x

Specifies that the search results are sorted on the server rather than on the client. This is useful if you want to sort according to a matching rule, as with an international search. In general, it is faster to sort on the server rather than on the client, although server-side sorting uses server resources.

-z

Specifies the maximum number of entries to return in response to a search request. For example, -z 1000.

Normally, regardless of the value specified here, ldapsearch never returns more entries than the number allowed by the server's nsslapd-sizelimit attribute. However, you can override this limitation by binding as the root DN when using this command-line argument. When you bind as the root DN, this option defaults to zero (0). The default value for the nsslapd-sizelimit attribute is 2,000 entries.

For detailed information on all ldapsearch utility options, refer to the Sun ONE Directory Server Resource Kit Tools Reference.

ldapsearch Examples

In the next set of examples, the following assumptions are made:

You want to perform a search of all entries in the directory.

The server is located on hostname myServer.

The server uses port number 5201.

You are binding to the directory as Directory Manager, with a password of password.

SSL is enabled for the server on port 636 (the default SSL port number).

The suffix under which all data is stored is dc=example,dc=com.

Returning All Entries

Given the previous information, the following call will return all entries in the directory:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password -b "dc=example,dc=com" -s sub "objectclass=*"

"objectclass=*" is a search filter that matches any entry in the directory.

Specifying Search Filters on the Command Line

You can specify a search filter directly on the command line. If you do this, be sure to enclose your filter in quotation marks ("filter"). Also, do not specify the -f option. For example:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password -b "dc=example,dc=com" "cn=Charlene Daniels"

Searching the Root DSE Entry

The root DSE, is a special entry that contains a list of all the suffixes supported by the local directory server. You can search this entry by supplying a search base of "". You must also specify a search scope of base and a filter of "objectclass=*". For example:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password -b "" -s base "objectclass=*"

Searching the Schema Entry

Sun ONE Directory Server stores all directory server schema in the special cn=schema entry. This entry contains information on every object class and attribute defined for your directory server.

You can examine the contents of this entry as follows:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password -b "cn=schema" -s base "objectclass=*"

Using LDAP_BASEDN

To make searching easier, you can set your search base using the LDAP_BASEDN environment variable. Doing this allows you to skip specifying the search base with the -b option (for information on how to set environment variables, see the documentation for your operating system).

Typically, you set LDAP_BASEDN to your directory's suffix value. Since your directory suffix is equal to the root, or topmost, entry in your directory, this causes all searches to begin from your directory's root entry.

For example, if you have set LDAP_BASEDN to dc=example,dc=com, you can search for cn=Charlene Daniels in your directory using the following command-line call:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password "cn=Charlene Daniels"

In this example, the default scope of sub is used because the -s option was not used to specify the scope.

Displaying Subsets of Attributes

The ldapsearch command returns all search results in LDIF format. By default, ldapsearch returns the entry's distinguished name and all of the attributes that you are allowed to read. You can set up the directory access control such that you are allowed to read only a subset of the attributes on any given directory entry.) Only operational attributes are not returned. If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command. For more information on operational attributes, refer to Chapter 12, "Operational Attributes" in the Sun ONE Directory Server Reference Manual.

Suppose you do not want to see all of the attributes returned in the search results. You can limit the returned attributes to just a few specific attributes by specifying the ones you want on the command line immediately after the search filter. For example, to show the cn and sn attributes for every entry in the directory, use the following command:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password "objectclass=*" sn cn

This example assumes you set your search base with LDAP_BASEDN.

LDAP Search Filters

Search filters select the entries to be returned for a search operation. They are most commonly used with the ldapsearch command-line utility. When you use ldapsearch, you can place multiple search filters in a file, with each filter on a separate line in the file, or you can specify a search filter directly on the command line.

For example, the following filter specifies a search for the common name Charlene Daniels:

cn=Charlene Daniels

This search filter returns all entries that contain the common name Charlene Daniels. Searches for common name values are not case sensitive.

When the common name attribute has values associated with a language tag, all of the values are returned. Thus, the following two attribute values both match this filter:

cn: Monique Le Chat

cn;lang-fr: Monique Le Chat

Search Filter Syntax

The basic syntax of a search filter is:

attribute operator value

For example:

buildingname>=alpha

In this example, buildingname is the attribute, >= is the operator, and alpha is the value. You can also define filters that use different attributes combined together with Boolean operators.

Search filters are described in detail in the following sections:

Using Attributes in Search Filters

Using Operators in Search Filters

Using Compound Search Filters

Search Filter Examples

Using Attributes in Search Filters

When searching for an entry, you can specify attributes associated with that type of entry. For example, when you search for people entries, you can use the cn attribute to search for people with a specific common name.

Examples of attributes that people entries might include:

cn (the person's common name)

sn (the person's surname, or last name, or family name)

telephoneNumber (the person's telephone number)

buildingName (the name of the building in which the person resides)

l (the locality in which you can find the person)

For a listing of the attributes associated with types of entries, see the Sun ONE Directory Server Reference Manual.

Using Operators in Search Filters

The operators that you can use in search filters are listed in Table 4-1:

Table 4-1    Search Filter Operators

Search type

Operator

Description

Equality

=

Returns entries containing attribute values that exactly match the specified value. For example, cn=Bob Johnson

Substring

=string* string

Returns entries containing attributes containing the specified substring. For example,

cn=Bob*

cn=*Johnson

cn=*John*

cn=B*John

(The asterisk (*) indicates zero (0) or more characters.)

Greater than or equal to

>=

Returns entries containing attributes that are greater than or equal to the specified value. For example,

buildingname >= alpha

Less than or equal to

<=

Returns entries containing attributes that are less than or equal to the specified value. For example,

buildingname <= alpha

Presence

=*

Returns entries containing one or more values for the specified attribute. For example,

cn=*

telephonenumber=*

manager=*

Approximate

~=

Returns entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example,

cn~=suret

l~=san fransico

could return

cn=sarette

l=san francisco

Note
In addition to these search filters, you can specify special filters to work with a preferred language collation order. For information on how to search a directory with international character sets, see "Searching an Internationalized Directory".

Using Compound Search Filters

Multiple search filter components can be combined using Boolean operators expressed in prefix notation as follows:

(Boolean-operator(filter)(filter)(filter)...)

where Boolean-operator is any one of the Boolean operators listed in Table 4-2.

Boolean operators can be combined and nested together to form complex expressions, such as:

(Boolean-operator(filter)(Boolean-operator(filter)(filter)))

The Boolean operators available for use with search filters include the following:

Table 4-2    Search Filter Boolean Operators

Operator

Symbol

Description

AND

&

All specified filters must be true for the statement to be true.
For example,

(&(filter)(filter)(filter)...)

OR

|

At least one specified filter must be true for the statement to be true. For example,

(|(filter)(filter)(filter)...)

NOT

!

The specified statement must not be true for the statement to be true. Only one filter is affected by the NOT operator. For example,

(!(filter))

Boolean expressions are evaluated in the following order:

Innermost to outermost parenthetical expressions first

All expressions from left to right

Specifying Search Filters Using a File

You can enter search filters into a file instead of entering them on the command line. When you do this, specify each search filter on a separate line in the file. The ldapsearch command runs each search in the order in which it appears in the file.

For example, if the file contains:

sn=Daniels
givenname=Charlene

then ldapsearch first finds all the entries with the surname Daniels, and then all the entries with the givenname Charlene. If an entry is found that matches both search criteria, the entry is returned twice.

For example, suppose you specified the previous search filters in a file named searchdb, and you set your search base using LDAP_BASEDN. The following returns all the entries that match either search filter:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password -f searchdb

You can limit the set of attributes returned here by specifying the attribute names that you want at the end of the search line. For example, the following ldapsearch command performs both searches, but returns only the DN and the givenname and sn attributes of each entry:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password -f searchdb sn givenname

Specifying DNs that Contain Commas in Search Filters

When a DN within a search filter contains a comma as part of its value, you must escape the comma with a backslash (\). For example, to find everyone in the example.com Bolivia, S.A. subtree, use the following command:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password -s base -b "o=example.com Bolivia\, S.A.,dc=example,dc=com" "objectclass=*"

Using Client Authentication When Searching

This example shows user cdaniels searching the directory using client authentication:

ldapsearch -h myServer -p 636 -b "dc=example,dc=com" -N "cdanielsscertname" -Z -W certdbpassword -P /home/cdaniels/certdb/cert.db "givenname=Richard"

Note
The ldapsearch utility described in this section is not the utility provided with the Solaris platform, but is part of the Sun ONE Directory Server Resource Kit. For more information on this utility, refer to the Sun ONE Directory Server Resource Kit Tools Reference.

Search Filter Examples

The following filter searches for entries containing one or more values for the manager attribute. This is also known as a presence search:

manager=*

The following filter searches for entries containing the common name Ray Kultgen. This is also known as an equality search:

cn=Ray Kultgen

The following filter returns all entries that do not contain the common name Ray Kultgen:

(!(cn=Ray Kultgen))

The following filter returns all entries that contain a description attribute that contains the substring X.500:

description=*X.500*

The following filter returns all entries whose organizational unit is Marketing and whose description field does not contain the substring X.500:

(&(ou=Marketing)(!(description=*X.500*)))

The following filter returns all entries whose organizational unit is Marketing and that have Julie Fulmer or Cindy Zwaska as a manager:

(&(ou=Marketing)(|(manager=cn=Julie Fulmer,ou=Marketing,dc=example, dc=com)(manager=cn=Cindy Zwaska,ou=Marketing,dc=example,dc=com)))

The following filter returns all entries that do not represent a person:

(!(objectClass=person))

The following filter returns all entries that do not represent a person and whose common name is similar to printer3b:

(&(!(objectClass=person))(cn~=printer3b))

Searching for Operational Attributes

If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command.

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password aci=accounts

To retrieve regular attributes in addition to explicitly specified operational attributes, specify "*" in addition to the operational attributes. For example:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password "objectclass=*" aci=accounts

Adding, Changing and Deleting Entries

The ldapmodify and ldapdelete utilities enable you to provide LDIF input to the directory to add, change and delete entries. These utilities read any number of update statements from the standard input or from a file, and modify the corresponding entries according to the LDIF instructions.

An update statement contains the DN of the target entry for the update, the operation to perform, and any data for the entry's attributes. The kind of operation that will be performed is specified by the changetype keyword.

ldapmodify and ldapdelete read the statements that you enter in exactly the same way as if they were read from a file. When you finish providing input, enter the character that your shell recognizes as the end of file (EOF) escape sequence. The utility then begins operations based on the input you supplied.

Typically, the EOF escape sequence is one of the following, depending upon the underlying operating system:

UNIX—Almost always Ctrl-D (^D)

Windows—Usually Ctrl-Z followed by a carriage return (^Z<return>)

Adding and Changing Entries Using ldapmodify

The ldapmodify command-line utility enables you to add and change directory entries. ldapmodify opens a connection to the specified server using the distinguished name and password you supply, and modifies the entries based on LDIF update statements contained in a specified file, or in standard input.

Adding an Entry

The following ldapmodify command and LDIF update statement add a user called Sylvia Garcia to the example.com database:

ldapmodify -h myServer -p 5201 -D "cn=directory manager" -w password

dn: cn=Sylvia Garcia,ou=People,o=MyCorp,dc=example,dc=com
changetype: add
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Sylvia Garcia
givenName: Sylvia
sn: Garcia
ou: People
o: MyCorp
uid: sgarcia

Once you have added the entry, use the ldapsearch command to check that the entry exists.

Adding an Attribute to an Entry

The following ldapmodify command and LDIF update statement change Sylvia Garcia's entry to include a new attribute, telephonenumber.

ldapmodify -h myServer -p 5201 -D "cn=directory manager" -w password

dn: cn=Sylvia Garcia,ou=People,o=MyCorp,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: 5552714

Once you have changed the entry, use the ldapsearch command to check that the new attribute has been added.

Changing the Value of an Attribute

The following ldapmodify command and LDIF update statement change Sylvia Garcia's telephone number by changing the value of the telephonenumber attribute.

ldapmodify -h myServer -p 5201 -D "cn=directory manager" -w password

dn: cn=Sylvia Garcia,ou=People,o=MyCorp,dc=example,dc=com
changetype: modify
replace: telephonenumber
telephonenumber: 555-1214

Once you have changed the entry, use the ldapsearch command to check that the attribute value has been changed.

Note
If you add a value that has a trailing space, ldapsearch base-64 encodes the value, in order to represent the value including the space. This is particularly problematic with configuration entries.

In the preceding example, change the value of the telephonenumber attribute to 555-1215[] (where [ ] represents a blank space):

ldapmodify -h myServer -p 5201 -D "cn=directory manager" -w password

dn: cn=Sylvia Garcia,ou=People,o=MyCorp,dc=example,dc=com
changetype: modify
replace: telephonenumber
telephonenumber: 555-1215[]

Now, use the ldapsearch command to check the value of the attribute:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password -b "dc=example,dc=com" "givenname=Sylvia"

dn: cn=Sylvia Garcia,ou=People,o=MyCorp,dc=example,dc=com
uid: SGarcia
givenName: Sylvia
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: Garcia
cn: Sylvia Garcia
userPassword: {SSHA}2YpgER/oquWQfyd/vsEnxYmK0BVBO+Bx8U12QA==
telephoneNumber:: NTU1LTQxMjcg

Note that the value of the telephoneNumber attribute has been base-64 encoded.

Deleting Entries Using ldapdelete

Use the ldapdelete command-line utility to delete entries from the directory. This utility opens a connection to the specified server using the distinguished name and password you provide, and deletes the entry or entries.

Deleting a User Entry

The following ldapdelete command deletes the user, Sylvia Garcia from the example.com database:

ldapdelete -h myServer -p 5201 -D "cn=directory manager" -w password "cn=Sylvia Garcia,ou=People,o=MyCorp,dc=example,dc=com"

Working With the Schema

As stated previously, the schema defines the size, range and format of entries that are stored in the directory. The schema is stored as a number of LDIF files in the slapd-machine name/config/schema/ directory. In our sample installation, the schema is located in slapd-myServer/config/schema. Have a look at this directory and note the various LDIF files that define the schema.

Looking at the Schema Entry

Use the following ldapsearch command to look at the entry cn=schema.

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password -b cn=schema "objectclass=*"

This entry determines the valid object classes, the required attributes for these object classes, and the optional attributes, of every entry in the directory.

Schema Violation

If you attempt to add an entry that does not conform to the schema, the directory issues an Object Class Violation error.

Try to execute the following ldapmodify command to add an entry for a new user, Frank:

ldapmodify -h myServer -p 5201 -D "cn=directory manager" -w password

dn: cn=Frank,ou=People,o=MyCorp,dc=example,dc=com
changetype: add
objectclass: top
objectclass: person
givenName: Frank
cn: Frank
mail: frank@mycorp.com
userPassword: myPassword

Note that the directory responds with an Object Class Violation error. Can you see why this entry violates the schema?

The reason for the violation can be found in the errors log, described later in this chapter. For now it is sufficient to know that the person objectclass requires the surname (sn) attribute.

Use the same ldapmodify command to add the entry again, with an sn attribute. Once you have added the entry, use the ldapsearch command to check that it has been added.

Working With Groups and Roles

Group definitions are special entries that either name their members in a static list (static groups) or provide a filter which defines a dynamic set of entries (dynamic groups). The scope of possible members of a group is the entire directory, regardless of where the group definition entries are located.

Roles are defined and administered like groups, but in addition, member entries also have a generated attribute that indicates the roles in which they participate. This means that you can search a member entry to obtain a list of the roles in which it participates. As described in the previous chapter, roles can be managed, filtered or nested.

Adding a Static Group

The entry that defines a static group inherits from the groupOfUniqueNames object class. The group members are listed by their DN as multiple values of the uniqueMember attribute.

In "Populating a New Database Using ldif2db", we created a database for example.com. This database had one group called Administrators, with two members. Use the following ldapmodify command to add a second static group called HR Managers, with one member, Charlene Daniels:

ldapmodify -h myServer -p 5201 -D "cn=directory manager" -w password

dn: cn=HR Managers,ou=Groups,o=MyCorp,dc=example,dc=com
changetype: add
objectclass: top
objectclass: groupOfUniqueNames
cn: HR Managers
uniqueMember: uid=cdaniels,ou=People,o=MyCorp,dc=example,dc=com

Once you have added the group, use the ldapsearch command to check that it has been added.

Adding a Dynamic Group

The entry that defines a dynamic group inherits from the groupOfUniqueNames and groupOfURLs object classes. Group membership is defined by the filter given in the memberURL attribute. The members in a dynamic group are the entries that match the filter whenever it is evaluated.

The following example adds a dynamic group called "Smith Team". The members of this group include all include all employees whose manager is ASmith.

ldapmodify -h myServer -p 5201 -D "cn=directory manager" -w password

dn: cn=Smith Team,ou=Groups, dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfUniquenames
objectClass: groupOfUrls
cn: Smith Team
memberURL: ldap:///dc=example,dc=com??sub?(&(|(objectclass=person)
(objectclass=groupofuniquenames))(manager=ASmith))

Adding a Managed Role Definition

All role definitions inherit from the ldapsubentry and nsRoleDefinition object classes. In addition, managed roles inherit from the nsSimpleRoleDefinition and nsManagedRoleDefinition object classes. Managed roles have a role definition entry and members are designated adding the nsRoleDN attribute to each member entry.

The following example adds a managed role called "myCorpAdminRole".

ldapmodify -h myServer -p 5201 -D "cn=directory manager" -w password

dn: cn=myCorpAdminRole,o=myCorp,dc=example,dc=com
changetype: add
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsSimpleRoleDefinition
objectclass: nsManagedRoleDefinition
cn: myCorpAdminRole
description: managed role for administrators

Members of a managed role have the nsRoleDN attribute in their entry. Assign the role created above to the user Aaron Brown by updating his entry with the following ldapmodify command:

ldapmodify -h myServer -p 5201 -D "cn=directory manager" -w password

dn: uid=abrown,ou=People,o=MyCorp,dc=example,dc=com
changetype: modify
add: nsRoleDN
nsRoleDN: cn=myCorpAdminRole,o=myCorp,dc=example,dc=com

Searching for Role Definitions

Roles are ldapSubEntry objects. Entries of the ldapsubentry object class are not returned in response to normal search requests. You must specify that you are searching for a subentry in the search filter.

Use the following ldapsearch command to locate the managed role definition created previously:

ldapsearch -h myServer -p 5201 -D "cn=directory manager" -w password -b "dc=example,dc=com" "(&(objectclass=nsManagedRoleDefinition)(objectclass=ldapSubEntry))"

Working With Class of Service (CoS)

Revise the instructions for using the Console in "Working With Class of Service (CoS)". The following example sets up the same CoS entries, using the command line.

Adding a Pointer CoS Entry

All CoS definition entries inherit from the ldapsubentry object class and the cosSuperDefinition object class. In addition, pointer CoS entries require the following object classes and attributes:

objectclass: cosPointerDefinition
cosTemplateDN: DN_string
cosAttribute: list_of_attributes qualifier

When using pointer CoS, the template entry inherits from the ldapsubentry object class and is also an instance of the cosTemplate object class. This entry must be created specifically for the CoS definition.

The following ldapmodify command creates a pointer CoS that shares a common postal code with all entries in the dc=example,dc=com tree:

ldapmodify -h myServer -p 5201 -a -D "cn=directory manager" /
-w password

dn: cn=pointerCoS,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=cosTemplateForPostalCode,cn=data,dc=example,dc=com
cosAttribute: postalCode

dn: cn=cosTemplateForPostalCode,cn=data,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 44438

Working With ACIs

ACIs enable you to control access to the entire directory, a subtree of the directory, specific entries in the directory (including entries defining configuration tasks), or a specific set of entry attributes. You can create ACIs manually using LDIF statements, and add them to the directory tree using ldapmodify.

The aci attribute uses the following syntax:

aci: (target)(version 3.0;acl "name";permission bind_rules;)

where:

target specifies the entry, attributes, or set of entries and attributes for which you want to control access. The target can be a distinguished name, one or more attributes, or a single LDAP filter. The target is an optional part of the ACI.

version 3.0 is a required string that identifies the ACI version.

"name" is a name for the ACI. The name can be any string that identifies the ACI. The ACI name is required.

permission specifically outlines what rights you are either allowing or denying (for example, read or search rights).

bind_rules specify the credentials and bind parameters that a user has to provide to be granted access. Bind rules can also specifically deny access to certain users or groups of users.

Looking at Access Restrictions

Use the following ldapsearch command to search the directory as user Charlene Daniels:

ldapsearch -h myServer -p 5201 -D "uid=cdaniels,ou=People,o=MyCorp,dc=example,dc=com" -w cdaniels -b "dc=example,dc=com" "objectclass=*"

Note that no entries are returned. This is because user Charlene Daniels does not have the appropriate access rights to search the directory.

Adding an ACI at the Command-Line

Use the following ldapmodify command to give Charlene Daniels full rights to the directory:

ldapmodify -h myServer -p 5201 -D "cn=directory manager" -w password
dn: o=MyCorp,dc=example,dc=com
changetype: modify
add: aci
aci: (targetattr=*)(version 3.0; aci "give charlene full rights"; allow(all) userdn = "ldap:///uid=cdaniels,ou=People,o=MyCorp,dc=example,dc=com";)

Once you have added the ACI, attempt the previous ldapsearch again. Note that all entries in the example.com database are now returned.

Examining the Log Information

Sun ONE Directory Server has several log files that contain detailed log information. The log files are stored in the the slapd-serverID/logs directory. In our installation it is located in slapd-myServer/logs.

Looking at the Access Log

The access log contains detailed information about client connections to the directory. To view the access log:

Change to ServerRoot/slapd-myServer/logs.

On UNIX systems, you can view the latest changes to the access log using the following command:

tail -f access

Perform the following simple search and note the entry in the access log.

ldapsearch -p 5201 -h myserver -D "cn=directory manager"
-w password -b "dc=example,dc=com" "objectclass=*"

Enhancing the Error Log Information

You can specify the amount of log information that you want to display in the log files.

Change to ServerRoot/slapd-myServer/logs.

On UNIX systems, you can view the latest changes to the error log using the following command:

tail -f errors

Use the following command to increase the error log level:

ldapmodify -h myserver -p 5201 -D "cn=directory manager" -w password
dn: cn=config
changetype: modify
replace: nsslapd-errorlog-level
nsslapd-errorlog-level: 65573

On UNIX sytems, you can use the following command to view the level of information now being generated in the error log:

tail -f errors

Searching an Internationalized Directory

When you perform search operations, you can request that the directory sort the results based on any language for which the server has a supporting collation order. For a list of the collation orders supported by the directory, see "Identifying Supported Locales" in the Sun ONE Directory Server Reference Manual.

This section focuses on the matching rule filter portion of the ldapsearch syntax. For more information on general ldapsearch syntax, see "LDAP Search Filters". For information on searching internationalized directories using the Users and Groups portion of the Sun ONE Server Console, refer to the online help or Sun ONE Server Console Server Management Guide.

This section covers the following topics:

Matching Rule Filter Syntax

Supported Search Types

International Search Examples

Matching Rule Filter Syntax

A matching rule provides special guidelines for how the directory compares strings during a search operation. In an international search, the matching rule tells the system what collation order and operator to use when performing the search operation. The syntax of the matching rule filter is as follows:

attr:matchingRule:=value

where:

attr is an attribute belonging to entries you're searching for, such as cn or mail

matchingRule is a string that identifies either the collation order or the collation order and a relational operator, depending on the format you prefer. For a discussion of matching rule formats, see "Matching Rule Formats".

value is either the attribute value for which you want to search or a relational operator plus the attribute value for which you want to search. The syntax of the value portion of the filter depends on the matching rule format you use.

Matching Rule Formats

The matching rule portion of a search filter can be represented in the following ways:

As the OID of the collation order for the locale on which you want to base your search.

As the language tag associated with the collation order on which you want to base your search.

As the OID of the collation order and a suffix that represents a relational operator.

As the language tag associated with the collation order and a suffix that represents a relational operator.

The syntax for each of these options is discussed in the following sections:

Using an OID for the Matching Rule

Using a Language Tag for the Matching Rule

Using an OID and Suffix for the Matching Rule

Using a Language Tag and Suffix for the Matching Rule

Using an OID for the Matching Rule

Each locale supported by Directory Server has an associated collation order OID. For a list of supported locales and their associated OIDs, see "Identifying Supported Locales" in the Sun ONE Directory Server Reference Manual.

You can use the collation order OID in the matching rule portion of the matching rule filter as follows:

attr:OID:=(relational_operator value)

The relational operator is included in the value portion of the string, separated from the value by a single space. For example, to search for all departmentNumber attributes that are at or after N4709 in the Swedish collation order, use the following filter:

departmentNumber:2.16.840.1.113730.3.3.2.46.1:=>= N4709

Using a Language Tag for the Matching Rule

Each locale supported by Directory Server has an associated language tag. For a list supported locales and their associated language tags, see "Identifying Supported Locales" in the Sun ONE Directory Server Reference Manual.

You can use the language tag in the matching rule portion of the matching rule filter as follows:

attr:language-tag:=(relational_operator value)

The relational operator is included in the value portion of the string, separated from the value by a single space. For example, to search the directory for all description attributes with a value of estudiante using the Spanish collation order, use the following filter:

cn:es:== estudiante

Using an OID and Suffix for the Matching Rule

As an alternative to using a relational operator-value pair, you can append a suffix that represents a specific operator to the OID in the matching rule portion of the filter. Combine the OID and suffix as follows:

attr:OID+suffix:=value

For example, to search for businessCategory attributes with the value Softwareprodukte in the German collation order, use the following filter:

businessCategory:2.16.840.1.113730.3.3.2.7.1.3:=Softwareprodukte

The .3 in the previous example is the equality suffix.

Using a Language Tag and Suffix for the Matching Rule

As an alternative to using a relational operator-value pair, you can append a suffix that represents a specific operator to the language tag in the matching rule portion of the filter. Combine the language tag and suffix as follows:

attr:language-tag+suffix:=value

For example, to search for all surnames that come at or after La Salle in the French collation order, use the following filter:

sn:fr.4:=La Salle

Using Wildcards in Matching Rule Filters

When performing a substring search using a matching rule filter, you can use the asterisk (*) character as a wildcard to represent zero or more characters.

For example, to search for an attribute value that starts with the letter k and ends with the letter n, you would enter a k*n in the value portion of the search filter. Similarly, to search for all attribute values beginning with the letter u, you would enter a value of u* in the value portion of the search filter.

To search for a value that contains the asterisk (*) character, you must escape the * with the designated escape sequence, \5c2a. For example, to search for all employees with businessCategory attribute values of Example*Net product line, enter the following value in the search filter:

Example \2a*Net product line

Supported Search Types

The directory server supports the following types of international searches:

equality (=)

substring (*)

greater than (>)

greater than or equal to (>=)

less than (<)

less than or equal to (<=)

Approximate, or phonetic, and presence searches are supported only in English.

As with a regular ldapsearch search operation, an international search uses operators to define the type of search. However, when invoking an international search, you can either use the standard operators (=, >=, >, <, <=) in the value portion of the search string, or you can use a special type of operator, called a suffix (not to be confused with the directory suffix), in the matching rule portion of the filter. Table 4-3 summarizes each type of search, the operator, and the equivalent suffix.

Table 4-3    Search Types, Operators, and Suffixes

Search Type

Operator

Suffix

Less than

<

.1

Less than or equal to

<=

.2

Equality

=

.3

Greater than or equal to

>=

.4

Greater than

>

.5

Substring

*

.6

International Search Examples

The following sections show examples of how to perform international searches on directory data. Each example gives all the possible matching rule filter formats so that you can become familiar with the formats and select the one that works best for you.

Less Than Example

When you perform a locale-specific search using the less than operator (<) or suffix (.1), you search for all attribute values that come before the given attribute in a specific collation order.

For example, to search for all surnames that come before the surname Marquez in the Spanish collation order, you could use any of the following matching rule filters:

sn:2.16.840.1.113730.3.3.2.15.1:=< Marquez
sn:es:=< Marquez
sn:2.16.840.1.113730.3.3.2.15.1.1:=Marquez
sn:es.1:=Marquez

Less Than or Equal to Example

When you perform a locale-specific search using the less than or equal to operator (<=) or suffix (.2), you search for all attribute values that come at or before the given attribute in a specific collation order.

For example, to search for all room numbers that come at or before room number CZ422 in the Hungarian collation order, you could use any of the following matching rule filters:

roomNumber:2.16.840.1.113730.3.3.2.23.1:=<= CZ422
roomNumber:hu:=<= CZ422
roomNumber:2.16.840.1.113730.3.3.2.23.1.2:=CZ422
roomNumber:hu.2:=CZ422

Equality Example

When you perform a locale-specific search using the equal to operator (=) or suffix (.3), you search for all attribute values that match the given attribute in a specific collation order.

For example, to search for all businessCategory attributes with the value Softwareprodukte in the German collation order, you could use any of the following matching rule filters:

businessCategory:2.16.840.1.113730.3.3.2.7.1:== Softwareprodukte
businessCategory:de:== Softwareprodukte
businessCategory:2.16.840.1.113730.3.3.2.7.1.3:=Softwareprodukte
businessCategory:de.3:=Softwareprodukte

Greater Than or Equal to Example

When you perform a locale-specific search using the greater than or equal to operator (>=) or suffix (.4), you search for all attribute values that come at or after the given attribute in a specific collation order.

For example, to search for all localities that come at or after Québec in the French collation order, you could use any of the following matching rule filters:

locality:2.16.840.1.113730.3.3.2.18.1:=>= Québec
locality:fr:=>= Québec
locality:2.16.840.1.113730.3.3.2.18.1.4:=Québec
locality:fr.4:=Québec

Greater Than Example

When you perform a locale-specific search using the greater than operator (>) or suffix (.5), you search for all attribute values that come at or before the given attribute in a specific collation order.

For example, to search for all mail hosts that come after host schranka4 in the Czech collation order, you could use any of the following matching rule filters:

mailHost:2.16.840.1.113730.3.3.2.5.1:=> schranka4
mailHost:cs:=> schranka4
mailHost:2.16.840.1.113730.3.3.2.5.1.5:=schranka4
mailHost:cs.5:=schranka4

Substring Example

When you perform an international substring search, you search for all values that match the given pattern in the specified collation order.

For example, to search for all user IDs that end in ming in the Chinese collation order, you could use any of the following matching rule filters:

uid:2.16.840.1.113730.3.3.2.49.1:=* *ming
uid:zh:=* *ming
uid:2.16.840.1.113730.3.3.2.49.1.6:=* *ming
uid:zh.6:=* *ming

Search type	Operator	Description
Equality	=	Returns entries containing attribute values that exactly match the specified value. For example, cn=Bob Johnson
Substring	=string* string	Returns entries containing attributes containing the specified substring. For example, cn=Bob* cn=Johnson cn=John* cn=BJohn (The asterisk () indicates zero (0) or more characters.)
Greater than or equal to	>=	Returns entries containing attributes that are greater than or equal to the specified value. For example, buildingname >= alpha
Less than or equal to	<=	Returns entries containing attributes that are less than or equal to the specified value. For example, buildingname <= alpha
Presence	=*	Returns entries containing one or more values for the specified attribute. For example, cn=* telephonenumber=* manager=*
Approximate	~=	Returns entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example, cn~=suret l~=san fransico could return cn=sarette l=san francisco

Operator	Symbol	Description
AND	&	All specified filters must be true for the statement to be true. For example, (&(filter)(filter)(filter)...)
OR	\|	At least one specified filter must be true for the statement to be true. For example, (\|(filter)(filter)(filter)...)
NOT	!	The specified statement must not be true for the statement to be true. Only one filter is affected by the NOT operator. For example, (!(filter))

Search Type	Operator	Suffix
Less than	<	.1
Less than or equal to	<=	.2
Equality	=	.3
Greater than or equal to	>=	.4
Greater than	>	.5
Substring	*	.6

Previous Contents Index Next
Copyright 2003 Sun Microsystems, Inc. All rights reserved.

-b	Specifies the starting point for the search. The value specified here must be a distinguished name that currently exists in the database. This option is optional if the LDAP_BASEDN environment variable has been set to a base DN. The value specified in this option should be provided in double quotation marks. For example: -b "cn=Charlene Daniels, ou=People, dc=example,dc=com"
-D	Specifies the distinguished name with which to authenticate to the server. This option is optional if anonymous access is supported by your server. If specified, this value must be a DN recognized by the Directory Server, and it must also have the authority to search for the entries. For example: -D "uid=cdaniels, dc=example,dc=com"
-h	Specifies the hostname or IP address of the machine on which the Directory Server is installed. If you do not specify a host, ldapsearch uses the localhost. For example, -h myServer.
-l	Specifies the maximum number of seconds to wait for a search request to complete. Regardless of the value specified here, ldapsearch will never wait longer than is allowed by the server's nsslapd-timelimit attribute (except in the case of a persistent search.) For more information on persistent searches, see Chapter 3 "ldapsearch" in the Sun ONE Directory Server Resource Kit Tools Reference. For example, -l 300. The default value for the nsslapd-timelimit attribute is 3,600 seconds (1 hour.)
-p	Specifies the TCP port number that the Directory Server uses. For example, -p 5201. The default is 389. If -Z is used, the default is 636.
-s	Specifies the scope of the search. The scope can be one of the following: base—Search only the entry specified in the -b option or defined by the LDAP_BASEDN environment variable. one—Search only the immediate children of the entry specified in the -b option. Only the children are searched; the actual entry specified in the -b option is not searched. sub—Search the entry specified in the -b option and all of its descendants. That is, perform a subtree search starting at the point identified in the -b option. This is the default.
-w	Specifies the password associated with the distinguished name that is specified in the -D option. If you do not specify this option, anonymous access is used. For example, -w diner892.
-x	Specifies that the search results are sorted on the server rather than on the client. This is useful if you want to sort according to a matching rule, as with an international search. In general, it is faster to sort on the server rather than on the client, although server-side sorting uses server resources.
-z	Specifies the maximum number of entries to return in response to a search request. For example, -z 1000. Normally, regardless of the value specified here, ldapsearch never returns more entries than the number allowed by the server's nsslapd-sizelimit attribute. However, you can override this limitation by binding as the root DN when using this command-line argument. When you bind as the root DN, this option defaults to zero (0). The default value for the nsslapd-sizelimit attribute is 2,000 entries.