This chapter introduces directory concepts and server features. In this chapter you will learn:
Why directory services exist and what they do well
How data is arranged in directories that support Lightweight Directory Access Protocol (LDAP)
How clients and servers communicate in LDAP
What operations are standard according to LDAP and how standard extensions to the protocol work
Why directory servers index directory data
What LDAP schemas are for
What LDAP directories provide to control access to directory data
Why LDAP directory data is replicated and what replication does
What Directory Services Markup Language (DSML) is for
How HTTP applications can access directory data in the Representation State Transfer (REST) style
A directory resembles a dictionary or a phone book. If you know a word, you can look it up its entry in the dictionary to learn its definition or its pronunciation. If you know a name, you can look it up its entry in the phone book to find the telephone number and street address associated with the name. If you are bored, curious, or have lots of time, you can also read through the dictionary, phone book, or directory, entry after entry.
Where a directory differs from a paper dictionary or phone book is in how entries are indexed. Dictionaries typically have one index—words in alphabetical order. Phone books, too—names in alphabetical order. Directories' entries on the other hand are often indexed for multiple attributes, names, user identifiers, email addresses, and telephone numbers. This means you can look up a directory entry by the name of the user the entry belongs to, but also by their user identifier, their email address, or their telephone number, for example.
ForgeRock Directory Services are based on the Lightweight Directory Access Protocol (LDAP). Much of this chapter serves therefore as an introduction to LDAP. ForgeRock Directory Services also provide RESTful access to directory data, yet, as directory administrator, you will find it useful to understand the underlying model even if most users are accessing the directory over HTTP rather than LDAP.
Phone companies have been managing directories for many decades. The Internet itself has relied on distributed directory services like DNS since the mid 1980s.
It was not until the late 1980s, however, that experts from what is now the International Telecommunications Union published the X.500 set of international standards, including Directory Access Protocol. The X.500 standards specify Open Systems Interconnect (OSI) protocols and data definitions for general purpose directory services. The X.500 standards were designed to meet the needs of systems built according to the X.400 standards, covering electronic mail services.
Lightweight Directory Access Protocol has been around since the early 1990s. LDAP was originally developed as an alternative protocol that would allow directory access over Internet protocols rather than OSI protocols, and be lightweight enough for desktop implementations. By the mid-1990s, LDAP directory servers became generally available and widely used.
Until the late 1990s, LDAP directory servers were designed primarily with quick lookups and high availability for lookups in mind. LDAP directory servers replicate data, so when an update is made, that update is applied to other peer directory servers. Thus, if one directory server goes down, lookups can continue on other servers. Furthermore, if a directory service needs to support more lookups, the administrator can simply add another directory server to replicate with its peers.
As organizations rolled out larger and larger directories serving more and more applications, they discovered that they needed high availability not only for lookups, but also for updates. Around the year 2000, directories began to support multi-master replication; that is, replication with multiple read-write servers. Soon thereafter, the organizations with the very largest directories started to need higher update performance as well as availability.
The OpenDJ code base began in the mid-2000s, when engineers solving the update performance issue decided the cost of adapting the existing C-based directory technology for high-performance updates would be higher than the cost of building a next generation, high performance directory using Java technology.
1.1. How Directories and LDAP Evolved
LDAP directory data is organized into entries, similar to the entries for words in the dictionary, or for subscriber names in the phone book. A sample entry follows:dn: uid=bjensen,ou=People,dc=example,dc=com uid: bjensen cn: Babs Jensen cn: Barbara Jensen facsimileTelephoneNumber: +1 408 555 1992 gidNumber: 1000 givenName: Barbara homeDirectory: /home/bjensen l: San Francisco mail: email@example.com objectClass: inetOrgPerson objectClass: organizationalPerson objectClass: person objectClass: posixAccount objectClass: top ou: People ou: Product Development roomNumber: 0209 sn: Jensen telephoneNumber: +1 408 555 1862 uidNumber: 1076
Barbara Jensen's entry has a number of attributes, such as , , and . (The attribute type indicates which types of attributes are required and allowed for the entry. As the entries object classes can be updated online, and even the definitions of object classes and attributes are expressed as entries that can be updated online, directory data is extensible on the fly.) When you look up her entry in the directory, you specify one or more attributes and values to match. The directory server then returns entries with attribute values that match what you specified.
The attributes you search for are indexed in the directory, so the directory server can retrieve them more quickly. (Attribute values do not have to be strings. Some attribute values, like certificates and photos, are binary.
The entry also has a unique identifier, shown at the top of the entry, . DN is an acronym for distinguished name. No two entries in the directory have the same distinguished name. Yet, DNs are typically composed of case-insensitive attributes.
Sometimes distinguished names include characters that you must escape. The following example shows an entry that includes escaped characters in the DN:$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=escape)"dn: cn=DN Escape Characters \" # \+ \, \; \< = \> \\,dc=example,dc=com objectClass: person objectClass: inetOrgPerson objectClass: organizationalPerson objectClass: top givenName: DN Escape Characters uid: escape cn: DN Escape Characters " # + , ; < = > \ sn: " # + , ; < = > \ mail: firstname.lastname@example.org
LDAP entries are arranged hierarchically in the directory. The hierarchical organization resembles a file system on a PC or a web server, often imagined as an upside-down tree structure, or a pyramid. The distinguished name consists of components separated by commas, . The names are little-endian. The components reflect the hierarchy of directory entries.
Figure 1.1, "Directory Data" shows the hierarchy as seen in the control panel.
Figure 1.1. Directory Data
Barbara Jensen's entry is located under an entry with DN , an organization unit and parent entry for the people at Example.com. The entry is located under the entry with DN , the base entry for Example.com. DC is an acronym for domain component. The directory has other base entries, such as , under which the configuration is accessible through LDAP. A directory can serve multiple organizations, too. You might find , , and in the same LDAP directory. Therefore, when you look up entries, you specify the base DN to look under in the same way you need to know whether to look in the New York, Paris, or Tokyo phone book to find a telephone number. (The root entry for the directory, technically the entry with DN (the empty string), is called the root DSE. It contains information about what the server supports, including the other base DNs it serves.
A directory server stores two kinds of attributes in a directory entry: user attributes and operational attributes. User attributes hold the information for users of the directory. All of the attributes shown in the entry at the outset of this section are user attributes. Operational attributes hold information used by the directory itself. Examples of operational attributes include , , and . When an LDAP search operation finds an entry in the directory, the directory server returns all the visible user attributes unless the search request restricts the list of attributes by specifying those attributes explicitly. The directory server does not, however, return any operational attributes unless the search request specifically asks for them. Generally speaking, applications should change only user attributes, and leave updates of operational attributes to the server, relying on public directory server interfaces to change server behavior. An exception is access control instruction () attributes, which are operational attributes used to control access to directory data.
1.2. About Data In LDAP Directories
In some client server communication, like web browsing, a connection is set up and then torn down for each client request to the server. LDAP has a different model. In LDAP the client application connects to the server and authenticates, then requests any number of operations, perhaps processing results in between requests, and finally disconnects when done.
The standard operations are as follows:
Bind (authenticate). The first operation in an LDAP session usually involves the client binding to the LDAP server with the server authenticating the client. Authentication identifies the client's identity in LDAP terms, the identity which is later used by the server to authorize (or not) access to directory data that the client wants to lookup or change.
If the client does not bind explicitly, the server treats the client as an anonymous client. An anonymous client is allowed to do anything that can be done anonymously. What can be done anonymously depends on access control and configuration settings. The client can also bind again on the same connection.
Search (lookup). After binding, the client can request that the server return entries based on an LDAP filter, which is an expression that the server uses to find entries that match the request, and a base DN under which to search. For example, to look up all entries for people with the email address in data for Example.com, you would specify a base DN such as and the filter .
Compare. After binding, the client can request that the server compare an attribute value the client specifies with the value stored on an entry in the directory.
Modify. After binding, the client can request that the server change one or more attribute values on an entry. Often administrators do not allow clients to change directory data, so allow appropriate access for client application if they have the right to update data.
Add. After binding, the client can request to add one or more new LDAP entries to the server.
Delete. After binding, the client can request that the server delete one or more entries. To delete an entry with other entries underneath, first delete the children, then the parent.
Modify DN. After binding, the client can request that the server change the distinguished name of the entry. In other words, this renames the entry or moves it to another location. For example, if Barbara changes her unique identifier from to something else, her DN would have to change. For another example, if you decide to consolidate and under instead, all the entries underneath must change distinguished names.
Renaming entire branches of entries can be a major operation for the directory, so avoid moving entire branches if you can.
Unbind. When done making requests, the client can request an unbind operation to end the LDAP session.
Abandon. When a request seems to be taking too long to complete, or when a search request returns many more matches than desired, the client can send an abandon request to the server to drop the operation in progress.
For practical examples showing how to perform the key operations using the command-line tools delivered with OpenDJ servers, read Chapter 4, "Performing LDAP Operations" in the Developer's Guide.
1.3. About LDAP Client and Server Communication
LDAP has standardized two mechanisms for extending the operations directory servers can perform beyond the basic operations listed above. One mechanism involves using LDAP controls. The other mechanism involves using LDAP extended operations.
LDAP controls are information added to an LDAP message to further specify how an LDAP operation should be processed. For example, the Server-Side Sort request control modifies a search to request that the directory server return entries to the client in sorted order. The Subtree Delete request control modifies a delete to request that the server also remove child entries of the entry targeted for deletion.
One special search operation that OpenDJ servers support is Persistent Search. The client application sets up a Persistent Search to continue receiving new results whenever changes are made to data that is in the scope of the search, thus using the search as a form of change notification. Persistent Searches are intended to remain connected permanently, though they can be idle for long periods of time.
The directory server can also send response controls in some cases to indicate that the response contains special information. Examples include responses for entry change notification, password policy, and paged results.
For the list of supported LDAP controls, see Appendix F, "LDAP Controls" in the Reference.
LDAP extended operations are additional LDAP operations not included in the original standard list. For example, the Cancel Extended Operation works like an abandon operation, but finishes with a response from the server after the cancel is complete. The StartTLS Extended Operation allows a client to connect to a server on an unsecure port, but then starts Transport Layer Security negotiations to protect communications.
For the list of supported LDAP extended operations, see Appendix G, "LDAP Extended Operations" in the Reference.
1.4. About LDAP Controls and Extensions
As mentioned early in this chapter, directories have indexes for multiple attributes. In fact, by default OpenDJ does not let normal users perform searches that are not indexed, because such searches mean OpenDJ has to scan the entire directory looking for matches.
As directory administrator, part of your responsibility is making sure directory data is properly indexed. OpenDJ provides tools for building and rebuilding indexes, for verifying indexes, and also for evaluating how well they are working.
For help better understanding and managing indexes, read Chapter 7, "Indexing Attribute Values".
Some databases are designed to hold huge amounts of data for a particular application. Although such databases might support multiple applications, how their data is organized depends a lot on the particular applications served.
In contrast, directories are designed for shared, centralized services. Although the first guides to deploying directory services suggested taking inventory of all the applications that would access the directory, many current directory administrators do not even know how many applications use their services. The shared, centralized nature of directory services fosters interoperability in practice, and has helped directory services be successful in the long term.
Part of what makes this possible is the shared model of directory user information, and in particular the LDAP schema. LDAP schema defines what the directory can contain. This means that directory entries are not arbitrary data, but instead tightly codified objects whose attributes are completely predictable from publicly readable definitions. Many schema definitions are in fact standard. They are the same not just across a directory service but across different directory services.
At the same time, unlike some databases, LDAP schema and the data it defines can be extended on the fly while the service is running. LDAP schema is also accessible over LDAP. One attribute of every entry is its set of values. This gives you as administrator great flexibility in adapting your directory service to store new data without losing or changing the structure of existing data, and also without ever stopping your directory service.
For a closer look, see Chapter 14, "Managing Schema".
1.6. About LDAP Schema
In addition to directory schema, another feature of directory services that enables sharing is fine-grained access control.
As directory administrator, you can control who has access to what data when, how, where and under what conditions by using access control instructions (ACI). You can allow some directory operations and not others. You can scope access control from the whole directory service down to individual attributes on directory entries. You can specify when, from what host or IP address, and what strength of encryption is needed in order to perform a particular operation.
As ACIs are stored on entries in the directory, you can furthermore update access controls while the service is running, and even delegate that control to client applications. OpenDJ combines the strengths of ACIs with separate administrative privileges to help you secure access to directory data.
For more information, read Chapter 6, "Configuring Privileges and Access Control".
1.7. About Access Control
Replication in OpenDJ consists of copying each update to the directory service to multiple directory servers. This brings both redundancy, in the case of network partitions or of crashes, and also scalability for read operations. Most directory deployments involve multiple servers replicating together.
When you have replicated servers, all of which are writable, you can have replication conflicts. What if, for example, there is a network outage between two replicas, and meanwhile two different values are written to the same attribute on the same entry on the two replicas? In nearly all cases, OpenDJ replication can resolve these situations automatically without involving you, the directory administrator. This makes your directory service resilient and safe even in the unpredictable real world.
One perhaps counterintuitive aspect of replication is that although you do add directory read capacity by adding replicas to your deployment, you do not add directory write capacity by adding replicas. As each write operation must be replayed everywhere, the result is that if you have N servers, you have N write operations to replay.
Another aspect of replication to keep in mind is that it is "loosely consistent." Loosely consistent means that directory data will eventually converge to be the same everywhere, but it will not necessarily be the same everywhere right away. Client applications sometimes get this wrong when they write to a pool of load balanced directory servers, immediately read back what they wrote, and are surprised that it is not the same. If your users are complaining about this, either make sure their application always gets sent to the same server, or else ask that they adapt their application to work in a more realistic manner.
To get started with replication, see Chapter 8, "Managing Data Replication".
1.8. About Replication
Directory Services Markup Language (DSMLv2) v2.0 became a standard in 2001. DSMLv2 describes directory data and basic directory operations in XML format, so they can be carried in Simple Object Access Protocol (SOAP) messages. DSMLv2 further allows clients to batch multiple operations together in a single request, to be processed either in sequential order or in parallel.
OpenDJ provides support for DSMLv2 as a DSML gateway, which is a Servlet that connects to any standard LDAPv3 directory. DSMLv2 opens basic directory services to SOAP-based web services and service oriented architectures.
To set up DSMLv2 access, see Section 5.9, "DSML Client Access".
OpenDJ can expose directory data as JSON resources over HTTP to REST clients, providing easy access to directory data for developers who are not familiar with LDAP. RESTful access depends on a configuration that describes how the JSON representation maps to LDAP entries.
Although client applications have no need to understand LDAP, OpenDJ's underlying implementation still uses the LDAP model for its operations. The mapping adds some overhead. Furthermore, depending on the configuration, individual JSON resources can require multiple LDAP operations. For example, an LDAP user entry represents as a DN (of the manager's entry). The same manager might be represented in JSON as an object holding the manager's user ID and full name, in which case OpenDJ must look up the manager's entry to resolve the mapping for the manager portion of the JSON resource, in addition to looking up the user's entry. As another example, suppose a large group is represented in LDAP as a set of 100,000 DNs. If the JSON resource is configured so that a member is represented by its name, then listing that resource would involve 100,000 LDAP searches to translate DNs to names.
A primary distinction between LDAP entries and JSON resources is that LDAP entries hold sets of attributes and their values, whereas JSON resources are documents containing arbitrarily nested objects. As LDAP data is governed by schema, almost no LDAP objects are arbitrary collections of data. (LDAP has the object class , but its use should be the exception rather than the rule.) Furthermore, JSON resources can hold arrays, ordered collections that can contain duplicates, whereas LDAP attributes are sets, unordered collections without duplicates. For most directory and identity data, these distinctions do not matter. You are likely to run into them, however, if you try to turn your directory into a document store for arbitrary JSON resources.
Despite some extra cost in terms of system resources, exposing directory data over HTTP can unlock directory services for a new generation of applications. The configuration provides flexible mapping, so that you can configure views that correspond to how client applications need to see directory data.
OpenDJ software also give you a deployment choice for HTTP access. You can deploy the REST to LDAP gateway, which is a Servlet that connects to any standard LDAPv3 directory, or you can activate the HTTP connection handler on an OpenDJ server to allow direct and more efficient HTTP and HTTPS access.
For examples showing how to use RESTful access, see Chapter 3, "Performing RESTful Operations" in the Developer's Guide.
1.10. About RESTful Access to Directory Services
This chapter is meant to serve as an introduction, and so does not even cover everything in this guide, let alone everything you might want to know about directory services.
When you have understood enough of the concepts to build the directory services that you want to deploy, you must still build a prototype and test it before you roll out shared, centralized services for your organization. Read Chapter 19, "Tuning Servers For Performance" for a look at how to meet the service levels that directory clients expect.
1.11. About Building Directory Services
Chapter 1. Understanding Directory Services
This chapter covers OpenDJ administration tools. In this chapter you will learn to:
Find and run OpenDJ control panel
Find and run OpenDJ command-line tools
Understand how command-line tools trust server certificates
Use expressions in the server configuration file
OpenDJ server software installs with a cross-platform, Java Swing-based control panel for many day-to-day tasks. OpenDJ server software also installs command-line tools for configuration and management tasks.
This chapter is one of the few to include screen shots of the control panel. Most examples make use of the command-line tools. Once you understand the concepts and how to use the command-line tools, you only need to know where to start in the control panel to accomplish what you set out to do.
At a protocol level, administration tools and interfaces connect to servers through a different network port than that used to listen for traffic from other client applications.
This chapter takes a quick look at the tools for managing directory services.
OpenDJ control panel offers a GUI for managing both local and remote servers. You choose the server to manage when you start the control panel. The control panel connects to the administration server port, making a secure LDAPS connection.
The version of OpenDJ control panel must be the same as the target version of the OpenDJ server.
Start OpenDJ control panel by running the control-panel command, described in control-panel(1) in the Reference:
(Linux, Solaris) Run /path/to/opendj/bin/control-panel.
(Windows) Double-click .
(Mac OS X) Double-click .
When you log in to OpenDJ control panel, you authenticate over LDAP. This means that if users can run the control panel, they can use it to manage a running server. Yet, to start and stop the server process through OpenDJ control panel, you must start the control panel on the system where OpenDJ runs, as the user who owns the OpenDJ server files (such as the user who installed OpenDJ). In other words, the OpenDJ control panel does not do remote process management.
Figure 2.1. OpenDJ Control Panel
Down the left side of OpenDJ control panel shown in Figure 2.1, "OpenDJ Control Panel", notice what you can configure:
- Directory Data
Directory data provisioning is typically not something you do by hand in most deployments. Usually entries are created, modified, and deleted through specific directory client applications. The Manage Entries window shown in Figure 2.2, "Manage Entries Window" can be useful in the lab as you design and test directory data, and if you modify individual ACIs or debug issues with particular entries.
Figure 2.2. Manage Entries Window
Additionally, the Directory Data list makes it easy to create a new base DN, and then import user data for the new base DN from LDAP Data Interchange Format (LDIF) files. You can also use the tools in the list to export user data to LDIF, and to backup and restore user data.
The Manage Schema window lets you browse and modify the rules that define how data is stored in the directory. You can add new schema definitions such as new attribute types and new object classes while the server is running, and the changes you make take effect immediately.
The Manage Indexes window gives you a quick overview of all the indexes currently maintained for directory attributes. To protect your directory resources from being absorbed by costly searches on unindexed attributes, you may choose to keep the default behavior that prevents unindexed searches, and add only those indexes required by specific applications.
If the number of user data entries is smaller than the default resource limits, you can still perform what appear to be unindexed searches, meaning searches with filters for which no index appears to exist. That is because the index returns all user data entries without hitting a resource limit that would make the search unindexed.
OpenDJ control panel also allows you to verify and rebuild indexes, which you may have to do after an upgrade operation, or if you have reason to suspect index corruption.
The Monitoring list gives you windows to observe information about the system, the Java Virtual Machine (JVM) used, and indications about how the cache is used, whether the work queue has been filling up, as well as details about the database. You can also view the numbers and types of requests arriving over the connection handlers, and the current tasks in progress as well.
- Runtime Options
This indicates where to change the runtime options for the server.
This section covers the tools installed with server software.
Before you try the examples in this guide, set your PATH to include the OpenDJ server tools. The location of the tools depends on the operating environment and on the packages used to install server software. Table 2.1, "Paths To Administration Tools" indicates where to find the tools.
Table 2.1. Paths To Administration Tools
|OpenDJ running on...||OpenDJ installed from...||Default path to tools...|
|Apple Mac OS X, Linux distributions, Oracle Solaris||.zip|
|Linux distributions||.deb, .rpm|
You find the installation and upgrade tools, setup, and upgrade, in the parent directory of the other tools, as these tools are not used for everyday administration. For example, if the path to most tools is you can find these tools in . For instructions on how to use the installation and upgrade tools, see the Installation Guide.
All OpenDJ command-line tools take the option.
All commands call Java programs and therefore involve starting a JVM.
Table 2.2, "Tools and Server Constraints" indicates the constraints, if any, that apply when using a command-line tool with a server.
Table 2.2. Tools and Server Constraints
These commands must be used with the local OpenDJ server in the same installation as the tools.
These commands are not useful with non-OpenDJ directory servers.
These commands must be used with an OpenDJ server having the same version as the command.
These commands are not useful with non-OpenDJ directory servers.
With one exception, this command can be used with current and previous OpenDJ server versions. The one exception is the dsreplication reset-change-number subcommand, which requires OpenDJ server version 3.0.0 or later.
This commands is not useful with other types of directory servers.
This command depends on template files. The template files can make use of configuration files installed with an OpenDJ server under .
The LDIF output can be used with any directory server.
These commands can be used independently of an OpenDJ server, and so are not tied to a specific version.
The following list uses the UNIX names for the commands. On Windows all command-line tools have the extension .bat:
Measure add and delete throughput and response time.
For details, see addrate(1) in the Reference.
Measure bind throughput and response time.
For details, see authrate(1) in the Reference.
Debug databases for pluggable backends.
For details, see backendstat(1) in the Reference.
Back up or schedule backup of directory data.
For details, see backup(1) in the Reference.
Encode and decode data in base64 format.
Base64-encoding represents binary data in ASCII, and can be used to encode character strings in LDIF, for example.
For details, see base64(1) in the Reference.
Start OpenDJ Control Panel from the command-line.
- create-rc-script (UNIX)
Generate a script you can use to start, stop, and restart the server either directly or at system boot and shutdown. Use create-rc-script -f script-file.
This allows you to register and manage an OpenDJ server as a service on UNIX and Linux systems.
For details, see create-rc-script(1) in the Reference.
The dsconfig command is the primary command-line tool for viewing and editing an OpenDJ configuration. When started without arguments, dsconfig prompts you for administration connection information. Once connected it presents you with a menu-driven interface to the server configuration.
Some advanced properties are not visible by default when you run the dsconfig command interactively. Use the option to access advanced properties.
When you pass connection information, subcommands, and additional options to dsconfig, the command runs in script mode and so is not interactive.
You can prepare dsconfig batch scripts by running the command with the option in interactive mode, then reading from the batch file with the option in script mode. Batch files can be useful when you have many dsconfig commands to run and want to avoid starting the JVM for each command.
Alternatively, you can read commands from standard input by using the option.
For details, see dsconfig(1) in the Reference.
Configure data replication between directory servers to keep their contents in sync.
For details, see dsreplication(1) in the Reference.
Encode a cleartext password according to one of the available storage schemes.
For details, see encode-password(1) in the Reference.
Export directory data to LDIF, the standard, portable, text-based representation of directory content.
For details, see export-ldif(1) in the Reference.
Load LDIF content into the directory, overwriting existing data. It cannot be used to append data to the backend database.
For details, see import-ldif(1) in the Reference.
Compare the attribute values you specify with those stored on entries in the directory.
For details, see ldapcompare(1) in the Reference.
Delete one entry or an entire branch of subordinate entries in the directory.
For details, see ldapdelete(1) in the Reference.
Modify the specified attribute values for the specified entries.
For details, see ldapmodify(1) in the Reference.
Modify user passwords.
For details, see ldappasswordmodify(1) in the Reference.
Search a branch of directory data for entries that match the LDAP filter you specify.
For details, see ldapsearch(1) in the Reference.
Display differences between two LDIF files, with the resulting output having LDIF format.
For details, see ldifdiff(1) in the Reference.
Similar to the ldapmodify command, modify specified attribute values for specified entries in an LDIF file.
For details, see ldifmodify(1) in the Reference.
Similar to the ldapsearch command, search a branch of data in LDIF for entries matching the LDAP filter you specify.
For details, see ldifsearch(1) in the Reference.
Generate directory data in LDIF based on templates that define how the data should appear.
The makeldif command is designed to help generate test data that mimics data expected in production, but without compromising real, potentially private information.
For details, see makeldif(1) in the Reference.
Lock and unlock user accounts, and view and manipulate password policy state information.
For details, see manage-account(1) in the Reference.
View information about tasks scheduled to run in the server, and cancel specified tasks.
For details, see manage-tasks(1) in the Reference.
Measure modification throughput and response time.
For details, see modrate(1) in the Reference.
Rebuild an index stored in an indexed backend.
For details, see rebuild-index(1) in the Reference.
Restore data from backup.
For details, see restore(1) in the Reference.
Measure search throughput and response time.
For details, see searchrate(1) in the Reference.
Start an OpenDJ server.
For details, see start-ds(1) in the Reference.
Display information about the server.
For details, see status(1) in the Reference.
Stop an OpenDJ server.
For details, see stop-ds(1) in the Reference.
Verify that an index stored in an indexed backend is not corrupt.
For details, see verify-index(1) in the Reference.
- windows-service (Windows)
Register and manage an OpenDJ server as a Windows Service.
For details, see windows-service(1) in the Reference.
2.2. Server-Side Command-Line Tools
This section describes how OpenDJ command-line tools determine whether to trust server certificates.
When an OpenDJ command-line tool connects securely to a server, the server presents its digital certificate. The tool must then determine whether to trust the server certificate and continue negotiating the secure connection, or not to trust the server certificate and drop the connection.
An important part of trusting a server certificate is trusting the signing certificate of the party who signed the server certificate. The process is described in more detail in Section 7.1, "About Certificates, Private Keys, and Secret Keys" in the Security Guide.
Put simply, a tool can automatically trust the server certificate if the tool's truststore contains the signing certificate. Table 2.3, "Command-Line Tools and Truststores" indicates where to find the truststore. The signing certificate could be a CA certificate, or the server certificate itself if the certificate was self-signed.
When run in interactive mode, OpenDJ command-line tools can prompt you to decide whether to trust a server certificate not found in the truststore. When run in non-interactive mode, the tools must rely on the truststore.
Table 2.3. Command-Line Tools and Truststores
|Truststore Option||Truststore Used|
The default truststore, , where is the home directory of the user running the command-line tool.
When you choose interactively to permanently trust a server certificate, the certificate is stored in this truststore.
Only the specified truststore is used.
In this case, the tool does not allow you to choose interactively to permanently trust an unrecognized server certificate.
2.3. How Command-Line Tools Trust Server Certificates
In the server configuration file, , you can use Universal Expression Language (EL) expressions, to include variables values in configuration attributes.
Interface stability: Evolving
Configuration expressions introduce variables into the server configuration file, where you can use them in the values of configuration attributes. The server configuration framework evaluates expressions when it reads them.
To distinguish them from static values, expressions are preceded by a dollar sign and enclosed in braces, . An expression can be a value, a function call, or a complex expression with arithmetic, logical, relational, and conditional operators.
You can mix expressions and static values in configuration attributes. Inside the form, you can embed expressions. These capabilities are described below.
When evaluated, an expression must return the appropriate type for the configuration attribute, just like a static value. For example, takes an integer, so if it is set using an expression, the attribute value resulting when the expression is evaluated must be an integer. If the type is wrong, the server fails to start due to a syntax error.
The file is not generally supported as a public interface to configure the server. The capability to use expressions in the configuration file is intended to make it easier to use the server in environments where the configuration is managed as a file, and some configuration attribute values must be determined dynamically.
To use expressions, configure the server using the setup and dsconfig commands, then stop the server and edit the configuration file to replace attribute values with expressions.
After that, if you use the dsconfig command to view or edit the server configuration, you do not see the expressions from the configuration file. Instead, when viewing the configuration you see the actual values. When editing the configuration, expressions are retained in the file unless you edit the attribute containing an expression. If you edit an attribute containing an expression, the your static value replaces the expression.
Configuration attributes that can be replaced by expressions have names that start with . Some attributes in the configuration file are not strictly configuration attributes. For example, attributes like CN and must have concrete attribute values, rather than expressions.
2.4.1. About Configuration Expressions
EL supports the following operators, in order of precedence:
Index property value: ,
Change precedence of operation:
Logical operations: , ,
Arithmetic operations: , , , ,
Binary arithmetic operations: ,
Relational operations: , , , , , , , , , , ,
Logical operations: , , ,
Conditional operations: ,
2.4.2. Using Operators
Expressions can include Java system properties and environment variables.
For system properties, returns the value of property, or to an empty string if property is not set. For example, returns the home directory of the user running the server.
2.4.3. Reading System Properties and Environment Variables
2.4. Using Configuration Expressions
Chapter 2. Administration Interfaces and Tools
A single controller at a centralized location can act as a backup for mesh access points when they lose connectivity with the primary controller in the local region. Centralized and regional controllers need not be in the same mobility group. Using the controller GUI or CLI, you can specify the IP addresses of the backup controllers, which allows the mesh access points to fail over to controllers outside of the mobility group.
You can also configure primary and secondary backup controllers (which are used if primary, secondary, or tertiary controllers are not specified or are not responsive) for all access points connected to the controller as well as various timers, including the heartbeat timer and discovery request timers.
The fast heartbeat timer is not supported on access points in bridge mode. The fast heartbeat timer is configured only on access points in local and FlexConnect modes.
The mesh access point maintains a list of backup controllers and periodically sends primary discovery requests to each entry on the list. When the mesh access point receives a new discovery response from a controller, the backup controller list is updated. Any controller that fails to respond to two consecutive primary discovery requests is removed from the list. If the mesh access point’s local controller fails, it chooses an available controller from the backup controller list in this order: primary, secondary, tertiary, primary backup, and secondary backup. The mesh access point waits for a discovery response from the first available controller in the backup list and joins the controller if it receives a response within the time configured for the primary discovery request timer. If the time limit is reached, the mesh access point assumes that the controller cannot be joined and waits for a discovery response from the next available controller in the list.
When a mesh access point’s primary controller comes back online, the mesh access point disassociates from the backup controller and reconnects to its primary controller. The mesh access point falls back to its primary controller and not to any secondary controller for which it is configured. For example, if a mesh access point is configured with primary, secondary, and tertiary controllers, it fails over to the tertiary controller when the primary and secondary controllers become unresponsive and waits for the primary controller to come back online so that it can fall back to the primary controller. The mesh access point does not fall back from the tertiary controller to the secondary controller if the secondary controller comes back online; it stays connected to the tertiary controller until the primary controller comes back up.