OPENDJ-2255 Initial self-edit of the admin guide

Mark Craig

28.56.2015 1995c9abe63e16ae4ed2a2446c09c12c8e4aa944

OPENDJ-2255 Initial self-edit of the admin guide

This patch is based on what I learned from the checklist and Lori's suggestions for OpenIG.

 docs/src/main/docbkx/admin-guide/chap-account-lockout.xml

@@ -28,28 +28,61 @@
 xsi:schemaLocation='http://docbook.org/ns/docbook
                     http://docbook.org/xml/5.0/xsd/docbook.xsd'
 xmlns:xlink='http://www.w3.org/1999/xlink'>
 <title>Implementing Account Lockout &amp; Notification</title>
 <title>Implementing Account Lockout and Notification</title>

 <para>OpenDJ directory server supports automatic account lockout.
 The aim of account lockout is not to punish users who mistype their
 passwords, but instead to protect the directory against attacks
 in which the attacker attempts to guess a user password, repeatedly
 attempting to bind until success is achieved.</para>
 <itemizedlist>
  <para>
   This chapter covers configuration of account lockout and account status notification.
   In this chapter you will learn to:
  </para>

 <para>Account lockout disables a user account after a specified
 number of successive authentication failures. When you implement account
 lockout, you can opt to have OpenDJ directory server unlock the account
 again after a specified interval, or you can leave the account locked
 until the password is reset.</para>
  <listitem>
   <para>
    Configure password policies to manage account lockout automatically
   </para>
  </listitem>

  <listitem>
   <para>
    Manage lockout with the <command>manage-account</command> command
   </para>
  </listitem>

  <listitem>
   <para>
    Set up email notification of account status
   </para>
  </listitem>
 </itemizedlist>

 <para>
  OpenDJ directory server supports automatic account lockout.
  The aim of account lockout is not to punish users who mistype their passwords,
  but instead to protect the directory against attacks
  in which the attacker attempts to guess a user password,
  repeatedly attempting to bind until success is achieved.
 </para>

 <para>
  Account lockout disables a user account after
  a specified number of successive authentication failures.
  When you implement account lockout, you can opt
  to have OpenDJ directory server unlock the account after a specified interval,
  or you can leave the account locked until the password is reset.
 </para>

 <note>
  <para>When you configure account lockout as part of password policy, OpenDJ
  locks an account after the specified number of consecutive authentication
  failures. Account lockout is not transactional across a replication topology,
  however. Under normal circumstances, replication nevertheless propagates
  lockout quickly. If ever replication is delayed, an attacker with direct
  access to multiple replicas could try to authenticate up to the specified
  number of times on each replica before being locked out on all replicas.</para>
  <para>
   You configure account lockout as part of password policy.
   OpenDJ locks an account after the specified number
   of consecutive authentication failures.
   Account lockout is not transactional across a replication topology.
   Under normal circumstances, replication propagates lockout quickly.
   If ever replication is delayed,
   an attacker with direct access to multiple replicas
   could try to authenticate up to the specified number of times on each replica
   before being locked out on all replicas.
  </para>
 </note>

 <para>

 docs/src/main/docbkx/admin-guide/chap-admin-tools.xml

@@ -29,7 +29,26 @@
                             http://docbook.org/xml/5.0/xsd/docbook.xsd'
         xmlns:xlink='http://www.w3.org/1999/xlink'
         xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>Administration Interfaces &amp; Tools</title>
 <title>Administration Interfaces and Tools</title>

 <itemizedlist>
  <para>
   This chapter covers OpenDJ administration tools.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Find and run OpenDJ control panel
   </para>
  </listitem>

  <listitem>
   <para>
    Find and run OpenDJ command line tools
   </para>
  </listitem>
 </itemizedlist>

 <para>OpenDJ server software installs with a cross-platform, Java Swing-based
 Control Panel for many day-to-day tasks. OpenDJ server software also installs

 docs/src/main/docbkx/admin-guide/chap-attribute-uniqueness.xml

@@ -29,6 +29,34 @@
                     http://docbook.org/xml/5.0/xsd/docbook.xsd'
 xmlns:xlink='http://www.w3.org/1999/xlink'>
 <title>Implementing Attribute Value Uniqueness</title>

 <itemizedlist>
  <para>
   This chapter shows you how to enforce that specified attributes
   do not have repeated values in different directory entries.
   You can use attribute uniqueness for example to prevent two user entries
   sharing the same email address.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Enforce uniqueness for user IDs and other attributes
   </para>
  </listitem>

  <listitem>
   <para>
    Limit the scope of attribute value uniqueness
   </para>
  </listitem>

  <listitem>
   <para>
    Deal with attribute value uniqueness across replicated directory servers
   </para>
  </listitem>
 </itemizedlist>

 <para>Some attribute values ought to remain unique. If you are using
 <literal>uid</literal> values as RDNs to distinguish between millions of

 docs/src/main/docbkx/admin-guide/chap-backup-restore.xml

@@ -28,7 +28,29 @@
         xsi:schemaLocation='http://docbook.org/ns/docbook
                             http://docbook.org/xml/5.0/xsd/docbook.xsd'
         xmlns:xlink='http://www.w3.org/1999/xlink'>
 <title>Backing Up &amp; Restoring Data</title>
 <title>Backing Up and Restoring Data</title>

 <itemizedlist>
  <para>
   This chapter deals with management of directory data backup archives.
   For information on managing directory data in an interoperable format
   that is portable between directory server products,
   see <xref linkend="chap-import-export" /> instead.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Create backup archives
   </para>
  </listitem>

  <listitem>
   <para>
    Restore data from backup archives
   </para>
  </listitem>
 </itemizedlist>

 <para>OpenDJ lets you backup and restore your data either in compressed,
 binary format, or in LDAP Data Interchange Format. This chapter shows you how

 docs/src/main/docbkx/admin-guide/chap-change-certs.xml

@@ -31,6 +31,25 @@
 <title>Changing Server Certificates</title>
 <indexterm><primary>Certificates</primary></indexterm>

 <itemizedlist>
  <para>
   This chapter covers how to replace OpenDJ key pairs and public key certificates.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Replace a key pair for securing a connection handler
   </para>
  </listitem>

  <listitem>
   <para>
    Replace a key pair used for replication
   </para>
  </listitem>
 </itemizedlist>

 <para>OpenDJ uses key stores (for private keys) and trust stores (for
 public, signed certificates). Up to three sets of key stores are used,
 as shown in the following illustration.</para>

 docs/src/main/docbkx/admin-guide/chap-connection-handlers.xml

@@ -42,6 +42,54 @@
  ><command>dsconfig</command></link> command.
 </para>
 
 <itemizedlist>
  <para>
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Enable client applications to access the directory
    over Lightweight Directory Access Protocol (LDAP) and secure LDAP (LDAPS)
   </para>
  </listitem>

  <listitem>
   <para>
    Enable client applications to access the directory
    over Hypertext Transfer Protocol (HTTP)
    whether using Directory Services Markup Language (DSML)
    or the Representational State Transfer (REST) style
   </para>
  </listitem>

  <listitem>
   <para>
    Enable monitoring using Java Management Extensions (JMX)
    or over Simple Network Management Protocol (SNMP)
   </para>
  </listitem>

  <listitem>
   <para>
    Enable automated processing of LDAP Data Interchange Format (LDIF) files
   </para>
  </listitem>

  <listitem>
   <para>
    Configure restrictions for client access such as requiring authentication
    or limiting the maximum number of concurrent connections
   </para>
  </listitem>

  <listitem>
   <para>
    Configure transport layer security for all relevant protocols
   </para>
  </listitem>
 </itemizedlist>
 
 <section xml:id="configure-ldap-port">
  <title>LDAP Client Access</title>
  
@@ -609,7 +657,7 @@
  </procedure>

  <procedure xml:id="new-self-signed-cert">
   <title>To Create &amp; Install a Self-Signed Certificate</title>
   <title>To Create and Install a Self-Signed Certificate</title>

   <para>If you choose to configure LDAP Secure Access when setting up OpenDJ
   directory server, the setup program generates a key pair in the Java Key
@@ -965,7 +1013,7 @@
  instructions that OpenDJ supports, see the chapter on <link
  xlink:href="admin-guide#chap-privileges-acis"
  xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
  Privileges &amp; Access Control</citetitle></link>.</para>
  Privileges and Access Control</citetitle></link>.</para>

  <variablelist>
   <para>Consider the following global configuration settings.</para>
@@ -1058,7 +1106,7 @@
 </section>

 <section xml:id="tls-protocols-cipher-suites">
  <title>TLS Protocols &amp; Cipher Suites</title>
  <title>TLS Protocols and Cipher Suites</title>
  <indexterm>
   <primary>TLS</primary>
  </indexterm>
@@ -1268,7 +1316,7 @@
    certificate). If you did not generate a default, self-signed certificate
    when installing OpenDJ directory server see the instructions, <link
    xlink:show="new" xlink:href="admin-guide#new-self-signed-cert"
    xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Create &amp;
    xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Create and
    Install a Self-Signed Certificate</citetitle></link>, and more generally the
    section on <link xlink:show="new"
    xlink:href="admin-guide#setup-server-cert"

 docs/src/main/docbkx/admin-guide/chap-failover.xml

@@ -28,7 +28,7 @@
  xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
  xmlns:xlink='http://www.w3.org/1999/xlink'
  xmlns:xinclude='http://www.w3.org/2001/XInclude'>
  <title>Configuring Health Checks &amp; Failover Policies</title>
  <title>Configuring Health Checks and Failover Policies</title>

  <para>Directory proxy servers use health checks and failover policies
  to switch from one directory server to another when something goes wrong

 docs/src/main/docbkx/admin-guide/chap-import-export.xml

@@ -29,7 +29,7 @@
                             http://docbook.org/xml/5.0/xsd/docbook.xsd'
         xmlns:xlink='http://www.w3.org/1999/xlink'
         xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>Importing &amp; Exporting LDIF Data</title>
 <title>Importing and Exporting LDIF Data</title>
 <indexterm><primary>Provisioning</primary></indexterm>
 <indexterm><primary>Importing data</primary></indexterm>
 <indexterm>
@@ -47,7 +47,44 @@
  <secondary>Export</secondary>
 </indexterm>
 
 <para>LDAP Data Interchange Format provides a mechanism for representing
 <itemizedlist>
  <para>
   This chapter deals with management of LDAP Data Interchange Format (LDIF) data.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Generate test LDIF data
   </para>
  </listitem>

  <listitem>
   <para>
    Import and export LDIF data
   </para>
  </listitem>

  <listitem>
   <para>
    Perform searches and modifications on LDIF files with command-line tools
   </para>
  </listitem>

  <listitem>
   <para>
    Create and manage database backends to house directory data imported from LDIF
   </para>
  </listitem>

  <listitem>
   <para>
    Delete database backends
   </para>
  </listitem>
 </itemizedlist>

 <para>LDIF provides a mechanism for representing
 directory data in text format. LDIF data is typically used to initialize
 directory databases, but also may be used to move data between different
 directories that cannot replicate directly, or even as an alternative
@@ -135,7 +172,7 @@
 </section>
 
 <section xml:id="importing-exporting-ldif">
  <title>Importing &amp; Exporting Data</title>
  <title>Importing and Exporting Data</title>
  
  <para>
   You can use OpenDJ Control Panel
@@ -721,7 +758,7 @@
  the mistake by creating the backend again, reconfiguring the indexes that
  were removed, and rebuilding the indexes as described in the section on <link
  xlink:href="admin-guide#configure-indexes"
  xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring &amp;
  xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring and
  Rebuilding Indexes</citetitle></link>.</para>
 </section>
</chapter>

 docs/src/main/docbkx/admin-guide/chap-indexing.xml

@@ -34,7 +34,31 @@
  <primary>Indexes</primary>
 </indexterm>

 <para>OpenDJ provides several indexing schemes to speed up searches.</para>
 <itemizedlist>
  <para>
   This chapter covers OpenDJ indexing features used to speed up searches,
   and to limit the impact of searches on directory server resources.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Determine which attributes to index and what types of indexes to configure
   </para>
  </listitem>

  <listitem>
   <para>
    Configure, build, and rebuild indexes
   </para>
  </listitem>

  <listitem>
   <para>
    Check that indexes are valid
   </para>
  </listitem>
 </itemizedlist>

 <para>When a client requests a directory search operation, the client sends
 the server a filter expression such as
@@ -58,7 +82,7 @@
 configuration for OpenDJ directory server.</para>

 <section xml:id="indexes-overview">
  <title>Index Types &amp; What Each Does</title>
  <title>Index Types and What Each Does</title>

  <para>OpenDJ provides several different index types, each corresponding
  to a different type of search.</para>
@@ -540,7 +564,7 @@
 </section>

 <section xml:id="configure-indexes">
  <title>Configuring &amp; Rebuilding Indexes</title>
  <title>Configuring and Rebuilding Indexes</title>
  <indexterm>
   <primary>Indexes</primary>
   <secondary>Configuring</secondary>

 docs/src/main/docbkx/admin-guide/chap-monitoring.xml

@@ -28,13 +28,44 @@
         xsi:schemaLocation='http://docbook.org/ns/docbook
                             http://docbook.org/xml/5.0/xsd/docbook.xsd'
         xmlns:xlink='http://www.w3.org/1999/xlink'>
 <title>Monitoring, Logging, &amp; Alerts</title>

 <para>This chapter describes the monitoring capabilities that OpenDJ
 implements, and shows how to configure them.</para>
 <title>Monitoring, Logging, and Alerts</title>

 <indexterm><primary>Monitoring</primary></indexterm>

 <itemizedlist>
  <para>
   This chapter covers OpenDJ monitoring capabilities.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Access monitoring information
    over Lightweight Directory Access Protocol (LDAP),
    over Simple Network Monitoring Protocol (SNMP),
    and though use of Java Management Extensions (JMX)
   </para>
  </listitem>

  <listitem>
   <para>
    Monitor directory server status, including status of directory server tasks
   </para>
  </listitem>

  <listitem>
   <para>
    Configure directory server logs and interpret the messages they contain
   </para>
  </listitem>

  <listitem>
   <para>
    Configure email settings for administrative alert notifications
   </para>
  </listitem>
 </itemizedlist>

 <para>OpenDJ Control Panel provides basic monitoring capabilities under
 Monitoring &gt; General Information, Monitoring &gt; Connection Handler, and
 Monitoring &gt; Manage Tasks. This chapter covers the other options for
@@ -249,7 +280,7 @@
 </section>

 <section xml:id="monitoring-status-and-tasks">
  <title>Server Operation &amp; Tasks</title>
  <title>Server Operation and Tasks</title>

  <para>
   OpenDJ comes with two commands for monitoring server processes and tasks.
@@ -589,7 +620,7 @@
  to control what gets logged.</para>

  <section xml:id="log-rotation">
   <title>Log Rotation &amp; Retention</title>
   <title>Log Rotation and Retention</title>

   <para>Each file-based log can be associated with a <firstterm>log rotation
   policy</firstterm>, and a <firstterm>log retention policy</firstterm>. The

 docs/src/main/docbkx/admin-guide/chap-mv-servers.xml

@@ -30,6 +30,26 @@
 xmlns:xlink='http://www.w3.org/1999/xlink'>
 <title>Moving Servers</title>
 <indexterm><primary>Moving servers</primary></indexterm>

 <itemizedlist>
  <para>
   This chapter explains how to move OpenDJ directory servers.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Prepare for the move, especially when the server is replicated,
    and when the directory service remains available during the move
   </para>
  </listitem>

  <listitem>
   <para>
    Perform the configuration needed to move the directory server
   </para>
  </listitem>
 </itemizedlist>

 <para>When you change where OpenDJ is deployed, you must take host names,
 port numbers, and certificates into account. The changes can also affect

 docs/src/main/docbkx/admin-guide/chap-privileges-acis.xml

@@ -29,26 +29,56 @@
                             http://docbook.org/xml/5.0/xsd/docbook.xsd'
         xmlns:xlink='http://www.w3.org/1999/xlink'
         xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>Configuring Privileges &amp; Access Control</title>
 <title>Configuring Privileges and Access Control</title>

 <para>OpenDJ supports two mechanisms to protect access to the directory,
 <firstterm>access control instructions</firstterm> and
 <firstterm>privileges</firstterm>.</para>
 <itemizedlist>
  <para>
   OpenDJ supports two mechanisms to protect access to the directory,
   <firstterm>access control instructions</firstterm>
   and administrative <firstterm>privileges</firstterm>.
   Access control instructions apply to directory data, providing fine-grained control
   over what a user or group member is authorized to do
   in terms of Lightweight Directory Access Protocol (LDAP) operations.
   Most access control instructions specify scopes (targets) to which they apply
   such that an administrative user
   who has all access to <literal>dc=example,dc=com</literal>
   need not have any access to <literal>dc=example,dc=org</literal>.
   Privileges control the administrative tasks that users can perform,
   such as bypassing the access control mechanism,
   performing backup and restore operations,
   making changes to the configuration, and so forth.
   Privileges are implemented independently from access control.
   By default, privileges restrict administrative access to directory root users,
   though any user can be assigned a privilege.
   Privileges apply to a directory server, and do not have a scope.
   This chapter covers both access control and privileges.
   In this chapter you will learn to:
  </para>

 <para>Access control instructions apply to directory data, providing
 fine-grained control over what a user or group member is authorized to do in
 terms of LDAP operations. Most access control instructions specify scopes
 (targets) to which they apply such that an administrative user who has all
 access to <literal>dc=example,dc=com</literal> need not have any access to
 <literal>dc=example,dc=org</literal>.</para>
  <listitem>
   <para>
    Configure privileges for directory administration
   </para>
  </listitem>

 <para>Privileges control the administrative tasks that users can perform,
 such as bypassing the access control mechanism, performing backup and restore
 operations, making changes to the configuration, and so forth. Privileges are
 implemented independently from access control. By default, privileges restrict
 administrative access to directory root users, though any user can be assigned
 a privilege. Privileges apply to a directory server, and do not have a
 scope.</para>
  <listitem>
   <para>
    Read and write access control instructions
   </para>
  </listitem>

  <listitem>
   <para>
    Configure access rights by setting access control instructions
   </para>
  </listitem>

  <listitem>
   <para>
    Evaluate effective access rights for a particular user
   </para>
  </listitem>
 </itemizedlist>

 <para>Some operations require both privileges and also access control
 instructions. For example, in order to reset user's passwords, an administrator
@@ -58,9 +88,6 @@
 effectively restrict the scope of that privilege to a particular branch of
 the Directory Information Tree.</para>

 <para>This chapter covers both access control instructions and privileges,
 demonstrating how to configure both.</para>
 
 <section xml:id="about-acis">
  <title>About Access Control Instructions</title>
  <indexterm><primary>Access control</primary></indexterm>
@@ -1274,7 +1301,7 @@
  follow.</para>

  <example xml:id="access-control-anonymous-reads">
   <title>ACI: Anonymous Reads &amp; Searches</title>
   <title>ACI: Anonymous Reads and Searches</title>
   
   <para>This works when the only attributes you do not want world-readable
   are password attributes.</para>

 docs/src/main/docbkx/admin-guide/chap-production.xml

@@ -30,14 +30,61 @@
         xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Securing and Hardening OpenDJ Directory Server</title>

 <itemizedlist>
 <para>
  By default OpenDJ directory server is set up
  for ease of evaluation and deployment.
  When you deploy OpenDJ in production,
  there are specific precautions you should take to minimize risks.
  This chapter recommends the key precautions to take.
   In this chapter you will learn to:
 </para>

  <listitem>
   <para>
    Set up a special system account for OpenDJ directory server,
    and appropriately protect access to directory server files
   </para>
  </listitem>

  <listitem>
   <para>
    Enforce use of the latest Java security updates
   </para>
  </listitem>

  <listitem>
   <para>
    Enable only directory services that are actually used
   </para>
  </listitem>

  <listitem>
   <para>
    Use appropriate log configuration, global access control,
    password storage, and password policy settings
   </para>
  </listitem>

  <listitem>
   <para>
    Avoid overuse of the default directory root user account
   </para>
  </listitem>

  <listitem>
   <para>
    Use appropriate global access control settings
   </para>
  </listitem>

  <listitem>
   <para>
    Secure connections to the directory
   </para>
  </listitem>
 </itemizedlist>

 <para>
  After following the recommendations in this chapter,
  make sure that you test your installation

 docs/src/main/docbkx/admin-guide/chap-pta.xml

@@ -30,11 +30,29 @@
 <title>Configuring Pass Through Authentication</title>
 <indexterm><primary>Pass through authentication</primary></indexterm>

 <para>This chapter focuses on pass through authentication (PTA), whereby you
 configure another server to determine the response to an authentication
 request. A typical use case for pass through authentication involves
 passing authentication through to Active Directory for users coming
 from Microsoft Windows systems.</para>
 <itemizedlist>
  <para>
   This chapter focuses on pass through authentication (PTA),
   whereby you configure another server
   to determine the response to an authentication request.
   A typical use case for pass through authentication involves
   passing authentication through to Active Directory
   for users coming from Microsoft Windows systems.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Configure password policies to use pass through authentication
   </para>
  </listitem>

  <listitem>
   <para>
    Assign pass through authentication policies to users and to groups
   </para>
  </listitem>
 </itemizedlist>

 <section xml:id="about-pta">
  <title>About Pass Through Authentication</title>

 docs/src/main/docbkx/admin-guide/chap-pwd-policy.xml

@@ -31,6 +31,44 @@
 <title>Configuring Password Policy</title>
 <indexterm><primary>Password policy</primary></indexterm>
 
 <itemizedlist>
  <para>
   This chapter covers password policy including examples for common use cases.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Decide what type of password policy is needed
   </para>
  </listitem>

  <listitem>
   <para>
    Discover which password policy applies for a given user
   </para>
  </listitem>

  <listitem>
   <para>
    Configure server-based and subentry-based password policies
   </para>
  </listitem>

  <listitem>
   <para>
    Assign password policies to users and to groups
   </para>
  </listitem>

  <listitem>
   <para>
    Configure automated password generation, password storage schemes,
    and validation of new passwords to reject invalid passwords before they are set
   </para>
  </listitem>
 </itemizedlist>

 <para>If you want to synchronize password policy across your organization
 and your applications go to the directory for authentication, then the
 directory can be a good place to enforce your password policy uniformly.
@@ -38,9 +76,6 @@
 you no doubt still want to consider directory password policy if only to
 choose the appropriate password storage scheme.</para>
 
 <para>This chapter covers password policy, including examples of how
 to configure password policies for common use cases.</para>

 <section xml:id="pwp-overview">
  <title>About OpenDJ Password Policies</title>
  

 docs/src/main/docbkx/admin-guide/chap-replication.xml

@@ -30,12 +30,62 @@
         xmlns:xlink='http://www.w3.org/1999/xlink'>
 <title>Managing Data Replication</title>

 <para>OpenDJ uses advanced data replication with automated conflict
 resolution to help ensure your directory services remain available in the
 event a server crashes or a network goes down, and also as you backup or
 upgrade your directory service. You can configure data replication as part
 of OpenDJ installation, and in many cases let replication do its work in
 the background.</para>
 <itemizedlist>
  <para>
   OpenDJ uses advanced data replication with automated conflict resolution
   to help ensure your directory services remain available
   during administrative operations that take an individual server offline,
   or in the event a server crashes or a network goes down.
   This chapter explains how to manage OpenDJ directory data replication.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Set up replication as part of initial installation using OpenDJ control panel,
    or at any time using command-line tools
   </para>
  </listitem>

  <listitem>
   <para>
    Understand how replication operates in order to configure it appropriately
   </para>
  </listitem>

  <listitem>
   <para>
    Enable, initialize, and stop data replication
   </para>
  </listitem>

  <listitem>
   <para>
    Configure stand-alone directory servers and replication servers,
    or break a server that plays both roles into two stand-alone servers
   </para>
  </listitem>

  <listitem>
   <para>
    Configure replication groups, read-only replicas, assured replication,
    subtree replication, and fractional replication for complex deployments
   </para>
  </listitem>

  <listitem>
   <para>
    Configure and use change notification to synchronize external applications
    with changes to directory data
   </para>
  </listitem>

  <listitem>
   <para>
    Recover from situations where a user error has been applied to all replicas
   </para>
  </listitem>
 </itemizedlist>

 <section xml:id="repl-quick-setup">
  <title>Replication Quick Setup</title>

 docs/src/main/docbkx/admin-guide/chap-resource-limits.xml

@@ -30,8 +30,31 @@
 <title>Setting Resource Limits</title>
 <indexterm><primary>Resource limits</primary></indexterm>
 
 <para>This chapter shows you how to set resource limits that prevent
 directory clients from using an unfair share of system resources.</para>
 <itemizedlist>
  <para>
   This chapter shows you how to set resource limits
   that prevent directory clients from using an unfair share of system resources.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Limit the resources used when a user searches the diretory
   </para>
  </listitem>

  <listitem>
   <para>
    Limit how long connections can remain idle before they are dropped
   </para>
  </listitem>

  <listitem>
   <para>
    Limit the size of directory server requests
   </para>
  </listitem>
 </itemizedlist>
 
 <section xml:id="limit-search-resources">
  <title>Limiting Search Resources</title>

 docs/src/main/docbkx/admin-guide/chap-samba.xml

@@ -31,6 +31,25 @@
 <title>Samba Password Synchronization</title>
 <indexterm><primary>Samba</primary></indexterm>
 
 <itemizedlist>
  <para>
   This chapter covers synchronization between directory passwords and Samba passwords.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Configure Samba for use with OpenDJ directory server
   </para>
  </listitem>

  <listitem>
   <para>
    Set up the OpenDJ directory sever Samba password plugin for synchronization
   </para>
  </listitem>
 </itemizedlist>

 <para><link xlink:href="http://www.samba.org/" xlink:show="new">Samba</link>,
 the Windows interoperability suite for Linux and UNIX, stores accounts because
 UNIX and Windows password storage management is not interoperable. The default

 docs/src/main/docbkx/admin-guide/chap-schema.xml

@@ -32,6 +32,34 @@
 <title>Managing Schema</title>
 <indexterm><primary>Schema</primary></indexterm>
 
 <itemizedlist>
  <para>
   This chapter describes how to manage
   Lightweight Directory Access Protocol (LDAP) schema definitions for directory data.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Understand LDAP schemas including the schema definitions delivered
    with OpenDJ directory server
   </para>
  </listitem>

  <listitem>
   <para>
    Change and extend OpenDJ LDAP schemas
   </para>
  </listitem>

  <listitem>
   <para>
    Relax schema checking when troubleshooting data
    that do not conform to schema definitions
   </para>
  </listitem>
 </itemizedlist>

 <para>Schema definitions describe the data, and especially the object classes
 and attribute types that can be stored in the directory. By default OpenDJ
 conforms strictly to LDAPv3 standards pertaining to schema definitions and
@@ -45,10 +73,6 @@
 is online. As a result you can add new applications requiring additional
 data without stopping your directory service.</para>
 
 <para>This chapter demonstrates how to change and to extend OpenDJ schema.
 This chapter also identifies the standard schema definitions available when
 you install OpenDJ.</para>
 
 <section xml:id="about-schema">
  <title>About Directory Schema</title>
  

 docs/src/main/docbkx/admin-guide/chap-server-process.xml

@@ -30,16 +30,28 @@
                             http://docbook.org/xml/5.0/xsd/docbook.xsd'
         xmlns:xlink='http://www.w3.org/1999/xlink'>
 <title>Managing Server Processes</title>
 <para>Using the OpenDJ Control Panel, you can start and stop local servers.
 You can also start and stop OpenDJ using command-line tools, and use the
 operating system's capabilities for starting OpenDJ at boot time.</para>
 
 <para>This chapter demonstrates how to start and stop server processes
 with command line tools and using operating system capabilities. This
 chapter also describes what OpenDJ directory server does during startup
 and shutdown, and how it recovers following an abrupt shutdown such as
 happens during a system crash or when you kill the server process using
 system tools.</para>
 <itemizedlist>
  <para>
   This chapter covers starting and stopping OpenDJ directory server.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Start, restart, and stop OpenDJ directory server
    using OpenDJ command-line tools, OpenDJ control panel,
    or system service integration on Linux and Windows systems
   </para>
  </listitem>

  <listitem>
   <para>
    Understand and configure what happens when OpenDJ directory server
    recovers from a crash or abrupt shutdown
   </para>
  </listitem>
 </itemizedlist>
  
 <section xml:id="start-server">
  <title>Starting a Server</title>

 docs/src/main/docbkx/admin-guide/chap-troubleshooting.xml

@@ -33,8 +33,56 @@
 <title>Troubleshooting Server Problems</title>
 <indexterm><primary>Troubleshooting</primary></indexterm>
 
 <para>This chapter describes how to troubleshoot common server problems,
 and how to collect information necessary when seeking support help.</para>
 <itemizedlist>
  <para>
   This chapter describes how to troubleshoot common server problems,
   and how to collect information necessary when seeking support help.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Identify directory server problems systematically as a first troubleshooting step
   </para>
  </listitem>

  <listitem>
   <para>
    Troubleshoot problems with installation and upgrade procedures,
    directory data import, data replication, and secure connections
   </para>
  </listitem>

  <listitem>
   <para>
    Reset lost administrator passwords
   </para>
  </listitem>

  <listitem>
   <para>
    Enable debug logging judiciously when solving problems
   </para>
  </listitem>

  <listitem>
   <para>
    Prevent applications from accessing the directory server when solving problems
   </para>
  </listitem>

  <listitem>
   <para>
    Troubleshoot problems with the way client applications access the directory
   </para>
  </listitem>

  <listitem>
   <para>
    Prepare evidence when asking a directory expert for help
   </para>
  </listitem>
 </itemizedlist>
 
 <section xml:id="troubleshoot-identify-problem">
  <title>Identifying the Problem</title>
@@ -74,7 +122,7 @@
 </section>
 
 <section xml:id="troubleshoot-installation">
  <title>Troubleshooting Installation &amp; Upgrade</title>
  <title>Troubleshooting Installation and Upgrade</title>

  <para>Installation and upgrade procedures result in a log file tracing
  the operation. The log location differs by operating system, but look for
@@ -490,7 +538,7 @@
  </screen>
  
  <section xml:id="troubleshoot-certificate-authentication">
   <title>Troubleshooting Certificates &amp; SSL Authentication</title>
   <title>Troubleshooting Certificates and SSL Authentication</title>
   
   <para>Replication uses SSL to protect directory data on the network.
   In some configurations, replica can fail to connect to each other due

 docs/src/main/docbkx/admin-guide/chap-tuning.xml

@@ -32,6 +32,39 @@
 <title>Tuning Servers For Performance</title>
 <indexterm><primary>Performance tuning</primary></indexterm>

 <itemizedlist>
  <para>
   This chapter suggests ways to measure and improve directory service performance.
   In this chapter you will learn to:
  </para>

  <listitem>
   <para>
    Define directory server performance goals operationally
    in accordance with the needs of client applications
   </para>
  </listitem>

  <listitem>
   <para>
    Identify constraints that might limit achievable performance goals
   </para>
  </listitem>

  <listitem>
   <para>
    Design and execute appropriate performance tests with the help of
    OpenDJ command-line tools
   </para>
  </listitem>

  <listitem>
   <para>
    Adjust OpenDJ and system settings to achieve performance goals
   </para>
  </listitem>
 </itemizedlist>

 <para>Server tuning refers to the art of adjusting server, JVM, and system
 configuration to meet the service level performance requirements of directory
 clients. In the optimal case you achieve service level performance
@@ -41,11 +74,10 @@
 <para>If you are reading this chapter, however, you are probably not
 facing an optimal situation. Instead you are looking for trade offs that
 maximize performance for clients given the constraints of your deployment.
 This chapter therefore aims to provide suggestions on how to measure and
 to improve directory service performance for better trade offs.</para>
 </para>

 <section xml:id="perf-define-starting-points">
  <title>Defining Performance Requirements &amp; Constraints</title>
  <title>Defining Performance Requirements and Constraints</title>

  <para>Your key performance requirement is most likely to satisfy your
  users or customers with the resources available to you. Before you can

 docs/src/main/docbkx/admin-guide/chap-understanding-ldap.xml

@@ -38,6 +38,76 @@
  <secondary>About</secondary>
 </indexterm>

 <itemizedlist>
  <para>
   This chapter introduces directory concepts and directory server features.
   In this chapter you will learn:
  </para>

  <listitem>
   <para>
    Why directory services exist and what they do well
   </para>
  </listitem>

  <listitem>
   <para>
    How data is arranged in directories that support
    Lightweight Directory Access Protocol (LDAP)
   </para>
  </listitem>

  <listitem>
   <para>
    How clients and servers communicate in LDAP
   </para>
  </listitem>

  <listitem>
   <para>
    What operations are standard according to LDAP
    and how standard extensions to the protocol work
   </para>
  </listitem>

  <listitem>
   <para>
    Why directory servers index directory data
   </para>
  </listitem>

  <listitem>
   <para>
    What LDAP schemas are for
   </para>
  </listitem>

  <listitem>
   <para>
    What LDAP directories provide to control access to directory data
   </para>
  </listitem>

  <listitem>
   <para>
    Why LDAP directory data is replicated and what replication does
   </para>
  </listitem>

  <listitem>
   <para>
    What Directory Services Markup Language (DSML) is for
   </para>
  </listitem>

  <listitem>
   <para>
    How HTTP applications can access directory data
    in the Representation State Transfer (REST) style
   </para>
  </listitem>
 </itemizedlist>

 <para>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
@@ -62,7 +132,7 @@
 rather than LDAP.</para>

 <section xml:id="ldap-directory-history">
  <title>How Directories &amp; LDAP Evolved</title>
  <title>How Directories and LDAP Evolved</title>
  
  <para>Phone companies have been managing directories for many decades. The
  Internet itself has relied on distributed directory services like DNS since
@@ -245,7 +315,7 @@
 </section>
 
 <section xml:id="ldap-client-server-communication">
  <title>About LDAP Client &amp; Server Communication</title>
  <title>About LDAP Client and Server Communication</title>

  <para>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
@@ -329,7 +399,7 @@
 </section>
 
 <section xml:id="standard-ldap-controls-extensions">
  <title>About LDAP Controls &amp; Extensions</title>
  <title>About LDAP Controls and Extensions</title>
  <para>LDAP has standardized two mechanisms for extending what directory
  servers can do beyond the basic operations listed above. One mechanism
  involves using LDAP controls. The other mechanism involves using LDAP extended
@@ -465,7 +535,7 @@
  <para>For more, read <link xlink:show="new"
  xlink:href="admin-guide#chap-privileges-acis"
  xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
  Privileges &amp; Access Control</citetitle></link>.</para>
  Privileges and Access Control</citetitle></link>.</para>
 </section>

 <section xml:id="about-replication">

 docs/src/main/docbkx/admin-guide/preface.xml

@@ -30,31 +30,201 @@
         xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>Preface</title>

 <para>This guide shows you how to configure, maintain, and troubleshoot
 OpenDJ directory services. This guide also describes file layouts, ports
 used, and standards, controls, extended operations, and languages supported
 for OpenDJ installations.</para>
 <para>
  This guide shows you how to configure, maintain, and troubleshoot
  OpenDJ directory services.
  OpenDJ directory services allow applications to access directory data
  using Lightweight Directory Access Protocol (LDAP),
  using Directory Services Markup Language (DSML)
  over Hypertext Transfer Protocol (HTTP),
  or using HTTP methods in the Representational State Transfer (REST) style.
 </para>

 <itemizedlist>
  <para>
   In reading and following the instructions in this guide, you will learn how to:
  </para>

  <listitem>
   <para>
    Use OpenDJ administration tools
   </para>
  </listitem>

  <listitem>
   <para>
    Manage OpenDJ server processes
   </para>
  </listitem>

  <listitem>
   <para>
    Import, export, backup, and restore directory data
   </para>
  </listitem>

  <listitem>
   <para>
    Configure OpenDJ server connection handlers for all supported protocols
   </para>
  </listitem>

  <listitem>
   <para>
    Configure administrative privileges and fine-grained access control
   </para>
  </listitem>

  <listitem>
   <para>
    Index directory data, manage schemas for directory data,
    and enforce uniqueness of directory data attribute values
   </para>
  </listitem>

  <listitem>
   <para>
    Configure data replication between OpenDJ directory servers
   </para>
  </listitem>

  <listitem>
   <para>
    Implement password policies, pass through authentication to another directory,
    password synchronization with Samba, account lockout, and account status notification
   </para>
  </listitem>

  <listitem>
   <para>
    Set resource limits to prevent unfair use of directory server resources
   </para>
  </listitem>

  <listitem>
   <para>
    Monitor directory servers through logs and alerts and over JMX
   </para>
  </listitem>

  <listitem>
   <para>
    Tune directory servers for best performance
   </para>
  </listitem>

  <listitem>
   <para>
    Secure directory server deployments
   </para>
  </listitem>

  <listitem>
   <para>
    Change directory server key pairs and public key certificates
   </para>
  </listitem>

  <listitem>
   <para>
    Move a directory server to a different system
   </para>
  </listitem>

  <listitem>
   <para>
    Troubleshoot directory server issues
   </para>
  </listitem>
 </itemizedlist>

 <section>
  <title>Who Should Read this Guide</title>
  <title>Using This Guide</title>

  <para>This guide is written for directory integrators and administrators who
  build, deploy, and maintain OpenDJ directory services for your
  organizations.</para>
  <para>
   This guide is intended for system administrators
   who build, deploy, and maintain OpenDJ directory services
   for their organizations.
  </para>

  <para>This guide starts by introducing the OpenDJ administrative interfaces
  and tools, and by showing how to manage OpenDJ server processes. It also
  demonstrates how to import and export directory data. This guide continues
  by showing how to configure and monitor the principle features of individual
  OpenDJ servers, and how to configure and monitor replicated server
  topologies for distributed high availability. It then demonstrates how to
  tune, troubleshoot, and move servers.</para>
  <itemizedlist>
   <para>
    This guide starts with an introduction to directory services.
    The rest of this guide is written with the assumption
    that you have basic familiarity with the following topics:
   </para>

  <para>You do not need to be an LDAP wizard to learn something from this
  guide, though a background in directory services and maintaining server
  software can help. You do need some background in managing servers and
  services on your operating system of choice. You can nevertheless get
  started with this guide, and then learn more as you go along.</para>
   <listitem>
    <para>
     The client-server model of distributed computing
    </para>
   </listitem>

   <listitem>
    <para>
     Lightweight Directory Access Protocol (LDAP),
     including how clients and servers exchange messages
    </para>
   </listitem>

   <listitem>
    <para>
     Managing Java-based services on operating systems and application servers
    </para>
   </listitem>

   <listitem>
    <para>
     Using command-line tools and reading command-line examples
     written for UNIX/Linux systems
    </para>
   </listitem>

   <listitem>
    <para>
     Configuring network connections on operating systems
    </para>
   </listitem>

   <listitem>
    <para>
     Managing Public Key Infrastructure (PKI) used to establish secure connections
    </para>
   </listitem>
  </itemizedlist>

  <itemizedlist>
   <para>
    Depending on the features you use, you should also have basic familiarity
    with the following topics:
   </para>

   <listitem>
    <para>
     Directory Services Markup Language (DSML),
     including how clients and servers exchange messages
    </para>
   </listitem>

   <listitem>
    <para>
     Hypertext Transfer Protocol (HTTP),
     including how clients and servers exchange messages
    </para>
   </listitem>

   <listitem>
    <para>
     Java Management Extensions (JMX) for monitoring services
    </para>
   </listitem>

   <listitem>
    <para>
     Simple Network Management Protocol (SNMP) for monitoring services
    </para>
   </listitem>
  </itemizedlist>
 </section>

 <xinclude:include href="../shared/sec-formatting-conventions.xml" />