chap-troubleshooting.xml revision 51607ea01068c9047391e4c8b46bc9dbd0edb7fd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER START
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! This work is licensed under the Creative Commons
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! To view a copy of this license, visit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! or send a letter to Creative Commons, 444 Castro Street,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Suite 900, Mountain View, California, 94041, USA.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! You can also obtain a copy of the license at
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! See the License for the specific language governing permissions
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! and limitations under the License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! If applicable, add the following below this CCPL HEADER, with the fields
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! enclosed by brackets "[]" replaced with your own identifying information:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Portions Copyright [yyyy] [name of copyright owner]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER END
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Copyright 2011-2013 ForgeRock AS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Troubleshooting</primary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This chapter describes how to troubleshoot common server problems,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and how to collect information necessary when seeking support help.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In order to solve your problem methodically, save time by defining the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark problem clearly up front. In a replicated environment with multiple directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers and many client applications, it can be particularly important to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark pin down not only the problem (difference in observed behavior compared to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark expected behavior), but also the circumstances and steps that lead to the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark problem occurring.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>What exactly is the problem? In other words, what is the behavior
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you expected? What is the behavior you observed?</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When did the problem start occurring? Under similar circumstances,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark when does the problem not occur?</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Is the problem permanent? Intermittent? Is it getting worse?
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Getting better? Staying the same?</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Pinpointing the problem can sometimes indicate where you should
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark start looking for solutions.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>Troubleshooting Installation & Upgrade</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Installation and upgrade procedures result in a log file tracing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the operation. The log location differs by operating system, but look for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark lines in the command output of the following form.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literallayout class="monospaced">See /var/....log for a detailed log of this operation.</literallayout>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This section describes what to do if you forgot the password for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Directory Manager or for the global (replication) administrator.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>Resetting the Directory Manager's Password</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ directory server stores the entry for Directory Manager in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the LDIF representation of its configuration. You must be able to edit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory server files in order to reset Directory Manager's password.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Generate the encoded version of the new password using the OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ /encode-password --storageScheme SSHA512 --clearPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEncoded Password: "{SSHA512}yWqHnYV4a5llPvE7WHLe5jzK27oZQWLIlVcs9gySu4TyZJMg
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark NQNRtnR/Xx2xces1wu1dVLI9jVVtl1W4BVsmOKjyjr0rWrHt"</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Stop OpenDJ directory server while you edit the configuration.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Find Directory Manager's entry, which has DN <literal>cn=Directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Manager,cn=Root DNs,cn=config</literal>, in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>/path/to/opendj/config/config.ldif</filename>, and carefully
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replace the <literal>userpassword</literal> attribute value with the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark encoded version of the new password, taking care not to leave any
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark whitespace at the end of the line.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark >dn: cn=Directory Manager,cn=Root DNs,cn=config
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: ds-cfg-root-dn-user
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserpassword: {SSHA512}yWqHnYV4a5llPvE7WHLe5jzK27oZQWLIlVcs9gySu4TyZJMg
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkgivenName: Directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Directory Manager
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-cfg-alternate-bind-dn: cn=Directory Manager
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksn: Manager
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-pwp-password-policy-dn: cn=Root Password Policy,cn=Password Policies
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ,cn=config
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-rlim-time-limit: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-rlim-lookthrough-limit: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-rlim-idle-time-limit: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-rlim-size-limit: 0</programlisting>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Verify that you can administer the server as Directory Manager using
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the new password.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ /dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark>>>> OpenDJ configuration console main menu
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkWhat do you want to configure?
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEnter choice: q</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Reset the Global Administrator's Password</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <secondary>Global (replication) administrator</secondary>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you enable replication, part of the process involves creating a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark global administrator and setting that user's password. This user is present
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark on all replicas. If you chose default values, this user has DN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>cn=admin,cn=Administrators,cn=admin data</literal>. You reset the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark password as you would for any other user, though you do so as Directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Manager.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Use the <command>ldappasswordmodify</command> command to reset the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark global administrator's password</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useStartTLS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --authzID "cn=admin,cn=Administrators,cn=admin data"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --newPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkThe LDAP password modify operation was successful</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Let replication copy the password change to other replicas.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ can write debug information and stack traces to the server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark debug log. What is logged depends both on debug targets that you create,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and also on the debug level that you choose.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Enable the debug log, <filename>opendj/logs/debug</filename>, which
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is not enabled by default.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-log-publisher-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --publisher-name "File-Based Debug Logger"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set enabled:true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set default-debug-level:all
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can set <literal>default-debug-level</literal> to a less verbose
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark level if necessary.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark list-debug-targets
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --publisher-name "File-Based Debug Logger"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkDebug Target : debug-level : debug-category
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark-------------:-------------:---------------
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ </screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>A debug target specifies a fully-qualified OpenDJ Java package,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark class, or method for which to log debug messages at the level you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark specify.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark create-debug-target
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --publisher-name "File-Based Debug Logger"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --type generic
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set debug-level:all
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Restart OpenDJ to see debug messages in the log.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark...</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you have set <literal>debug-level:all</literal>, OpenDJ generates
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a great deal of output in the debug log file. Use debug logging very
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark sparingly on production systems.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Lockdown mode</primary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Misconfiguration can potentially put OpenDJ in a state where you must
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark intervene, and where you need to prevent users and applications
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark from accessing the directory until you are done fixing the problem.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ provides a <firstterm>lockdown mode</firstterm> that allows
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connections only on the loopback address, and allows only operations
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark requested by root users, such as <literal>cn=Directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Manager</literal>. You can use lockdown mode to prevent all but
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark administrative access to OpenDJ in order to repair the server.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To put OpenDJ into lockdown mode, the server must be running. You
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark cause the server to enter lockdown mode by using a task. Notice that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the modify operation is performed over the loopback address (accessing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OpenDJ on the local host).</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --defaultAdd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: ds-task-id=Enter Lockdown Mode,cn=Scheduled Tasks,cn=tasks
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: ds-task
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-task-id: Enter Lockdown Mode
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-task-class-name: org.opends.server.tasks.EnterLockdownModeTask
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing ADD request for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ds-task-id=Enter Lockdown Mode,cn=Scheduled Tasks,cn=tasks
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkADD operation successful for DN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ds-task-id=Enter Lockdown Mode,cn=Scheduled Tasks,cn=tasks</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ logs a notice message in <filename>logs/errors</filename>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark when lockdown mode takes effect.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[30/Jan/2012:17:04:32 +0100] category=BACKEND severity=NOTICE msgID=9896350
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msg=Lockdown task Enter Lockdown Mode finished execution</literallayout>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Client applications that request operations get a message concerning
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark lockdown mode.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch --port 1389 --baseDN "" --searchScope base "(objectclass=*)" +
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSEARCH operation failed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkResult Code: 53 (Unwilling to Perform)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkAdditional Information: Rejecting the requested operation because the server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is in lockdown mode and will only accept requests from root users over
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark loopback connections</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You also leave lockdown mode by using a task.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --defaultAdd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: ds-task-id=Leave Lockdown Mode,cn=Scheduled Tasks,cn=tasks
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: ds-task
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-task-id: Leave Lockdown Mode
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-task-class-name: org.opends.server.tasks.LeaveLockdownModeTask
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing ADD request for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ds-task-id=Leave Lockdown Mode,cn=Scheduled Tasks,cn=tasks
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkADD operation successful for DN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ds-task-id=Leave Lockdown Mode,cn=Scheduled Tasks,cn=tasks</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ also logs a notice message when leaving lockdown.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[30/Jan/2012:17:13:05 +0100] category=BACKEND severity=NOTICE msgID=9896350
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msg=Leave Lockdown task Leave Lockdown Mode finished execution</literallayout>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>By default OpenDJ requires that LDIF data you import respect standards.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark In particular, OpenDJ is set to check that entries to import match the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark schema defined for the server. You can temporarily bypass this check by using
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ also ensures by default that entries have only one structural
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark object class. You can relax this behavior by using the advanced global
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark configuration property,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>single-structural-objectclass-behavior</literal>. This can be useful
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark when importing data exported from Sun Directory Server. For example, to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark warn when entries have more than one structural object class instead of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark reject such entries being added, set
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>single-structural-objectclass-behavior:warn</literal> as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark follows.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-global-configuration-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --hostname `hostname`
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set single-structural-objectclass-behavior:warn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>By default, OpenDJ also checks syntax for a number of attribute types.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark You can relax this behavior as well by using the <command>dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-attribute-syntax-prop</command> command. See the list of attribute
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark syntaxes and use the <option>--help</option> option for further
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark information.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When running <command>import-ldif</command>, you can use the <option>-R
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <replaceable>rejectFile</replaceable></option> option to capture entries that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark could not be imported, and the <option>--countRejects</option> option to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark return the number of rejected entries as the <command>import-ldif</command>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark exit code.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Once you work through the issues with your LDIF data, reinstate the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark default behavior to ensure automated checking.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In order to trust the server certificate, client applications usually
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark compare the signature on certificates with those of the Certificate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Authorities (CAs) whose certificates are distributed with the client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark software. For example, the Java environment is distributed with a key store
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark holding many CA certificates.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ keytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 334</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The self-signed server certificates that can be configured during
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OpenDJ setup are not recognized as being signed by any CAs. Your software
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark therefore is configured not to trust the self-signed certificates by
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark default. You must either configure the client applications to accept the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark self-signed certificates, or else use certificates signed by recognized
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark CAs.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can further debug the network traffic by collecting debug traces.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark To see the traffic going over TLS/SSL in debug mode, configure OpenDJ to dump
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark debug traces from <literal>javax.net.debug</literal> into the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>OPENDJ_JAVA_ARGS="-Djavax.net.debug=all" start-ds</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <section xml:id="troubleshoot-certificate-authentication">
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>Troubleshooting Certificates & SSL Authentication</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replication uses SSL to protect directory data on the network.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark In some configurations, replica can fail to connect to each other due
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to SSL handshake errors. This leads to error log messages such as the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark following.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>[21/Nov/2011:13:03:20 -0600] category=SYNC severity=NOTICE
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msgID=15138921 msg=SSL connection attempt from myserver (123.456.789.012)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark failed: Remote host closed connection during handshake</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Notice these problem characteristics in the message above.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The host name, <literal>myserver</literal>, is not fully
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark qualified.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You should not see non fully qualified host names in the error logs.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Non fully qualified host names are a sign that an OpenDJ server has not
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark been configured properly.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Always install and configure OpenDJ using fully-qualified host names.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark The OpenDJ administration connector, which is used by the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <command>dsconfig</command> command, and also replication depend upon SSL
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and, more specifically, self-signed certificates for establishing SSL
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connections. If the host name used for connection establishment does not
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark correspond to the host name stored in the SSL certificate then the SSL
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark handshake can fail. For the purposes of establishing the SSL connection,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a host name like <literal>myserver</literal> does not match
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>myserver.example.com</literal>, and vice versa.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The connection succeeded, but the SSL handshake failed, suggesting
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a problem with authentication or with the cipher or protocol negotiation.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark As most deployments use the same Java Virtual Machine, and the same JVM
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark configuration for each replica, the problem is likely not related to SSL
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark cipher or protocol negotiation, but instead lies with authentication.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Follow these steps on each OpenDJ server to check whether the problem
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark lies with the host name configuration.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Make sure each OpenDJ server uses only fully qualified host names in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the replication configuration. You can obtain a quick summary by running
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the following command against each server's configuration.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ grep ds-cfg-replication-server: config/config.ldif | sort | uniq</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Make sure that the host names in OpenDJ certificates also contain
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark fully qualified host names, and correspond to the host names found in the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark previous step.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen># Examine the certificates used for the administration connector.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -storepass `cat config/admin-keystore.pin` |grep "^Owner:"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark# Examine the certificates used for replication.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -storepass `cat config/ads-truststore.pin`| grep "^Owner:"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Sample output for a server on host <literal>opendj.example.com</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark follows.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ grep ds-cfg-replication-server: config/config.ldif |sort | uniq
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-cfg-replication-server: opendj.example.com:8989
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-cfg-replication-server: opendj.example.com:9989
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark-storepass `cat config/admin-keystore.pin` | grep "^Owner:"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkOwner: CN=opendj.example.com, O=Administration Connector Self-Signed Certificate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -storepass `cat config/ads-truststore.pin`| grep "^Owner:"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkOwner: CN=opendj.example.com, O=OpenDJ Certificate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkOwner: CN=opendj.example.com, O=OpenDJ Certificate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkOwner: CN=opendj.example.com, O=OpenDJ Certificate</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Unfortunately there is no easy solution to badly configured host
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark names. It is often easier and quicker simply to reinstall your OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers remembering to use fully qualified host names everywhere.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When using the <command>setup</command> tool to install and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark configure a server ensure that the <option>-h</option> option is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark included, and that it specifies the fully qualified host name. Make sure
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you include this option even if you are not enabling SSL/StartTLS LDAP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connections (see <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-363"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you are using the GUI installer, then make sure you specify the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark fully qualified host name on the first page of the wizard.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When using the <command>dsreplication</command> tool to enable
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication make sure that any <option>--host</option> options include the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark fully qualified host name.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you cannot reinstall the server, follow these steps.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --disableAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Stop and restart each server in order to clear the in-memory ADS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark trust store backend.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Enable replication making certain that fully qualified host names
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark are used throughout</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminUID admin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN1 "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --replicationPort1 <replaceable>replPort1</replaceable>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN2 "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --replicationPort2 <replaceable>replPort2</replaceable>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Repeat the previous step for each remaining replica. In other words,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark host1 with host2, host1 with host3, host1 with host4, ..., host1 with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark hostN.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Initialize all remaining replica with the data from host1.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark initialize-all
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminUID admin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Check that the host names are correct in the configuration and in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the key stores by following the steps you used to check for host name
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark problems. The only broken host name remaining should be in the key and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark trust stores for the administration connector.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ keytool -list -v -keystore config/admin-truststore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -storepass `cat config/admin-keystore.pin` |grep "^Owner:"</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Stop each server, and then fix the remaining admin connector
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate as described here in the procedure <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Replace a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>As explained in <link xlink:href="admin-guide#chap-change-certs"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink" xlink:show="new"><citetitle
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark >Changing Server Certificates</citetitle></link>, OpenDJ directory server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark has different keys and key stores for different purposes. The public keys
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark used for replication are also used to encrypt shared secret symmetric keys
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for example to encrypt and to sign back ups. This section looks at what to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark do if either a key pair or secret key is compromised.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>How you deal with the problem depends on which key was
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark compromised.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For a key pair used for a client connection handler and with a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate signed by a certificate authority (CA), contact the CA for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark help. The CA might choose to publish a certificate revocation list (CRL)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that identifies the certificate of the compromised key pair.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Also make sure you replace the key pair. See <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="admin-guide#replace-key-pair" xlink:show="new"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Replace a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Server Key Pair</citetitle></link> for specific steps.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For a key pair used for a client connection handler and that has
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a self-signed certificate, follow the steps in <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="admin-guide#replace-key-pair" xlink:show="new"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Replace a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Server Key Pair</citetitle></link>, and make sure the clients remove the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark compromised certificate from their trust stores, updating those trust
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark stores with the new certificate.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For a key pair that is used for replication, mark the key as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark compromised as described below, and replace the key pair. See <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="admin-guide#replace-ads-cert" xlink:show="new"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Replace a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Server Key Pair</citetitle></link> for specific steps.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To mark the key pair as compromised, follow these steps.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Identity the key entry by searching administrative data on the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server whose key was compromised.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The server in this example is installed on
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>opendj.example.com</literal> with administration port
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN "cn=admin data"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(cn=opendj.example.com:4444)" ds-cfg-key-id
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=opendj.example.com:4444,cn=Servers,cn=admin data
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-cfg-key-id: 4F2F97979A7C05162CF64C9F73AF66ED</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The key ID, <literal>4F2F97979A7C05162CF64C9F73AF66ED</literal>, is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the RDN of the key entry.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Mark the key as compromised by adding the attribute,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ds-cfg-key-compromised-time</literal>, to the key entry.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The attribute has generalized time syntax, and so takes as its
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark value the time at which the key was compromised expressed in generalized
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark time. In the following example, the key pair was compromised at 8:34 AM
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark UTC on March 21, 2013.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: ds-cfg-key-id=4F2F97979A7C05162CF64C9F73AF66ED,cn=instance keys,cn=admin data
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: ds-cfg-key-compromised-time
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-cfg-key-compromised-time: 201303210834Z
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for ds-cfg-key-id=4F2F97979A7C05162CF64C9F73AF66ED,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark cn=instance keys,cn=admin data
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN ds-cfg-key-id=4F2F97979A7C05162CF64C9F73AF66ED
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ,cn=instance keys,cn=admin data</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If the server uses encrypted or signed data, then the shared secret
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark keys used for encryption or signing and associated with the compromised
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark key pair should also be considered compromised. Therefore, mark all
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark shared secret keys encrypted with the instance key as compromised.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To identify the shared secret keys, find the list of secret keys
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the administrative data whose <literal>ds-cfg-symmetric-key</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark starts with the key ID of the compromised key.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN "cn=secret keys,cn=admin data"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(ds-cfg-symmetric-key=4F2F97979A7C05162CF64C9F73AF66ED*)" dn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: ds-cfg-key-id=fba16e59-2ce1-4619-96e7-8caf33f916c8,cn=secret keys,cn=admin d
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: ds-cfg-key-id=57bd8b8b-9cc6-4a29-b42f-fb7a9e48d713,cn=secret keys,cn=admin d
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: ds-cfg-key-id=f05e2e6a-5c4b-44d0-b2e8-67a36d304f3a,cn=secret keys,cn=admin d
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ata</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For each such key, mark the entry with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ds-cfg-key-compromised-time</literal> as shown above for the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark instance key.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Changes to administration data are replicated to other OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers in the replication topology.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For a shared secret key used for data encryption that has been
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark compromised, mark the key entry with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ds-cfg-key-compromised-time</literal> as shown in the example
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark above that demonstrates marking the instance key as compromised.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Again, changes to administration data are replicated to other OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers in the replication topology.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>By default OpenDJ logs information about all LDAP client operations in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>logs/access</filename>, and all HTTP client operations in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>logs/http-access</filename>. The following lines are wrapped for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark readability, showing a search for the entry with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>uid=bjensen</literal> as traced in the LDAP access log. In the access
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark log itself, each line starts with a time stamp.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>[27/Jun/2011:17:23:00 +0200] CONNECT conn=19 from=127.0.0.1:56641
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to=127.0.0.1:1389 protocol=LDAP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[27/Jun/2011:17:23:00 +0200] SEARCH REQ conn=19 op=0 msgID=1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark base="dc=example,dc=com" scope=wholeSubtree filter="(uid=bjensen)" attrs="ALL"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[27/Jun/2011:17:23:00 +0200] SEARCH RES conn=19 op=0 msgID=1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark result=0 nentries=1 etime=3
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[27/Jun/2011:17:23:00 +0200] UNBIND REQ conn=19 op=1 msgID=2
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[27/Jun/2011:17:23:00 +0200] DISCONNECT conn=19 reason="Client Unbind"</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>As you see, each client connection and set of LDAP operations are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark traced, starting with a time stamp and information about the operation
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark performed, then including information about the connection, the operation
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark number for the sequence of operations performed by the client, a message
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark identification number, and additional information about the operation.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To match HTTP client operations with related internal server operations,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark first prevent OpenDJ from suppressing internal operations from the LDAP access
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark log by using the <command>dsconfig</command> command to set the LDAP access
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark log publisher <literal>suppress-internal-operations</literal> advanced
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark property to <literal>false</literal>. Then match the values of the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>x-connection-id</literal> field in the HTTP access log with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>conn=<replaceable>id</replaceable></literal> values in the LDAP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark access log.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For example, consider an HTTP GET request for the <literal>_id</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark field of the user <literal>newuser</literal>, which is handled by connection 4
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark as shown in <filename>logs/http-access</filename>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>- 192.168.0.12 bjensen 22/May/2013:16:27:52 +0200
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With internal operations logged in <filename>logs/access</filename>,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark log lines for the related operations have <literal>conn=4</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark from=192.168.0.12:63593 to=192.168.0.12:8080 protocol=HTTP/1.1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark op=0 msgID=0 base="ou=people,dc=example,dc=com" scope=wholeSubtree
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark filter="(&(objectClass=inetOrgPerson)(uid=bjensen))" attrs="1.1"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark op=0 msgID=0 result=0 nentries=1 etime=5
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark op=1 msgID=1 version=3 type=SIMPLE
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark dn="uid=bjensen,ou=People,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark op=1 msgID=1 result=0 authDN="uid=bjensen,ou=People,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark op=2 msgID=2 base="uid=newuser,ou=people,dc=example,dc=com" scope=baseObject
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark filter="(objectClass=*)" attrs="uid,etag"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark op=2 msgID=2 result=0 nentries=1 etime=4
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark op=3 msgID=3
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark reason="Client Unbind"</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To help diagnose errors due to access permissions, OpenDJ supports the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark get effective rights control. The control OID,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>1.3.6.1.4.1.42.2.27.9.5.2</literal>, is not allowed by the default
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark global ACIs. You must therefore add access to use the get effective rights
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark control when not using it as Directory Manager.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>Clients Need Simple Paged Results Control</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For Solaris and some versions of Linux you might see a message in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the OpenDJ access logs such as the following.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkThe request control with Object Identifier (OID) "1.2.840.113556.1.4.319"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcannot be used due to insufficient access rights</literallayout>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This message means clients are trying to use the <link xlink:show="new"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="http://tools.ietf.org/html/rfc2696">simple paged results
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark control</link> without authenticating. By default, OpenDJ includes a global
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ACI to allow only authenticated users to use the control.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword "password"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark get-access-control-handler-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProperty : Value(s)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark-----------:-------------------------------------------------------------------
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkenabled : true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkglobal-aci : (extop="1.3.6.1.4.1.26027.1.6.1 || 1.3.6.1.4.1.26027.1.6.3 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark : (targetcontrol="1.3.6.1.1.12 || 1.3.6.1.1.13.1 || 1.3.6.1.1.13.2
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark : || <emphasis role="strong">1.2.840.113556.1.4.319</emphasis> || 1.2.826.0.1.3344810.2.3 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark : 2.16.840.1.113730.3.4.18 || 2.16.840.1.113730.3.4.9 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark : 1.2.840.113556.1.4.473 || 1.3.6.1.4.1.42.2.27.9.5.9") (version
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark : 3.0; acl "Authenticated users control access"; allow(read)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark : userdn="ldap:///all";), (targetcontrol="2.16.840.1.113730.3.4.2 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark : 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark : 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark : 2.16.840.1.113730.3.4.16") (version 3.0; acl "Anonymous control
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark : access"; allow(read) userdn="ldap:///anyone";)</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To grant anonymous (unauthenticated) user access to the control,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark add the OID for the simple paged results control to the list of those in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the <literal>Anonymous control access</literal> global ACI.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword "password"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-access-control-handler-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --remove global-aci:"(targetcontrol=\"2.16.840.1.113730.3.4.2 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 2.16.840.1.113730.3.4.16\") (version 3.0; acl \"Anonymous control access\";
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark allow(read) userdn=\"ldap:///anyone\";)"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --add global-aci:"(targetcontrol=\"2.16.840.1.113730.3.4.2 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 ||
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 2.16.840.1.113730.3.4.16 || <emphasis role="strong">1.2.840.113556.1.4.319</emphasis>\")
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (version 3.0; acl \"Anonymous control access\"; allow(read)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark userdn=\"ldap:///anyone\";)"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Alternatively, stop OpenDJ, edit the corresponding ACI carefully in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>/path/to/opendj/config/config.ldif</filename>, and restart OpenDJ.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <footnote><para>Unlike the <command>dsconfig</command> command, the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>config.ldif</filename> file is not a public interface, so this
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark alternative should not be used in production.</para></footnote></para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replication can generally recover from conflicts and transient issues.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Replication does, however, require that update operations be copied
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark from server to server. It is therefore possible to experience temporary
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark delays while replicas converge, especially when the write operation load is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark heavy. OpenDJ's tolerance for temporary divergence between replicas is what
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark allows OpenDJ to remain available to serve client applications even when
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark networks linking the replicas go down.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In other words, the fact that directory services are loosely convergent
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark rather than transactional is a feature, not a bug.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>That said, you may encounter errors. Replication uses its own error log
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark file, <filename>logs/replication</filename>. Error messages in the log file
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark have <literal>category=SYNC</literal>. The messages have the following form.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Here the line is folded for readability.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>[27/Jun/2011:14:37:48 +0200] category=SYNC severity=INFORMATION msgID=14680169
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msg=Replication server accepted a connection from 10.10.0.10/10.10.0.10:52859
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to local address 0.0.0.0/0.0.0.0:8989 but the SSL handshake failed. This is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark probably benign, but may indicate a transient network outage or a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark misconfigured client application connecting to this replication server.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark The error was: Remote host closed connection during handshake</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ maintains historical information about changes in order to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark bring replicas up to date, and to resolve replication conflicts. To prevent
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark historical information from growing without limit, OpenDJ purges historical
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark information after a configurable delay
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (<literal>replication-purge-delay</literal>, default: 3 days). A replica
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark can become irrevocably out of sync if you restore it from a backup archive
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark older than the purge delay, or if you stop it for longer than the purge
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark delay. If this happens to you, disable the replica, and then reinitialize it
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark from a recent backup or from a server that is up to date.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you cannot resolve a problem yourself, and want to ask for help,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark clearly identify the problem and how you reproduce it, and also the version
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of OpenDJ you use to reproduce the problem. The version includes both a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark version number and also a build time stamp.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig --version
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkBuild <replaceable>yyyymmddhhmmss</replaceable>Z</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Be ready to provide additional information, too.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The output from the <command>java -version</command> command.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para><filename>access</filename> and <filename>errors</filename> logs
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark showing what the server was doing when the problem started occurring</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>A copy of the server configuration file,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>config/config.ldif</filename>, in use when the problem started
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark occurring</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Other relevant logs or output, such as those from client applications
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark experiencing the problem</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>A description of the environment where OpenDJ is running, including
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark system characteristics, host names, IP addresses, Java versions, storage
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark characteristics, and network characteristics. This helps to understand
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the logs, and other information.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>