CR-2609 Fix for OPENDJ-1182: Admin guide tuning chapter does not recap basi...

Mark Craig

19.16.2013 be489d013a521d6b80dd8b33f7aadf1bfc9a5700

CR-2609 Fix for OPENDJ-1182: Admin guide tuning chapter does not recap basic tuning from the release notes

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

@@ -151,7 +151,14 @@
   of failure. Be sure to list the resources you expect to have, when and how
   long you expect to have them, and why you need them. Also make note of
   what is missing and why.</para>
   

   <para>
    In addition to the suggestions in this section, also read the section on
    <link xlink:href="release-notes#prerequisites-hardware" xlink:show="new"
    xlink:role="http://docbook.org/xlink/role/olink"><citetitle
    >Hardware</citetitle></link> in the <citetitle>Release Notes</citetitle>.
   </para>

   <section xml:id="perf-hardware">
    <title>Server Hardware Recommendations</title>
   
@@ -182,6 +189,8 @@
    then the database grows to about twice its initial size on disk. This is
    normal, and due to the way the database manages its logs. The size on disk
    does not impact the DB cache size requirements.</para>

    <xinclude:include href="../shared/para-write-barriers.xml" />
   </section>
  </section>
 </section>
@@ -258,7 +267,9 @@
  you have the right underlying network, hardware, storage, and system
  resources in place, you can tweak OpenDJ performance in a number of ways.
  This section mentions the most common tweaks.</para>
  

  <xinclude:include href="../shared/sec-prerequisites-file-descriptors.xml" />

  <section xml:id="perf-java">
   <title>Java Settings</title>
   

 opends/src/main/docbkx/release-notes/chap-before-you-install.xml

@@ -26,7 +26,8 @@
<chapter xml:id='chap-before-you-install'
         xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
         xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
         xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
         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>Before You Install OpenDJ Software</title>
@@ -62,33 +63,7 @@
  corresponding Java SDK.</para>
 </section>

 <section xml:id="prerequisites-file-descriptors">
  <title>Maximum Open Files</title>
  <indexterm>
   <primary>File descriptors</primary>
   <secondary>Requirements</secondary>
  </indexterm>

  <para>OpenDJ needs to be able to open many files, especially when handling
  many client connections. Linux systems in particular often set a limit of
  1024 per user, which is too low for OpenDJ.</para>

  <para>When setting up OpenDJ for production use, make sure OpenDJ can use
  at least use at least 64K (65536) file descriptors. For example when running
  OpenDJ as user <literal>opendj</literal> on a Linux system that uses
  <filename>/etc/security/limits.conf</filename> to set user level limits,
  you can set soft and hard limits by adding these lines to the file.</para>

  <programlisting language="none">opendj soft nofile 65536
opendj hard nofile 131072</programlisting>

  <para>The example above assumes the system has enough file descriptors
  available overall. You can check the Linux system overall maximum as
  follows.</para>

  <screen>$ cat /proc/sys/fs/file-max
204252</screen>
 </section>
 <xinclude:include href="../shared/sec-prerequisites-file-descriptors.xml" />

 <section xml:id="prerequisites-operating-systems">
  <title>Operating System</title>
@@ -117,12 +92,7 @@
   </listitem>
  </itemizedlist>

  <para>In order to avoid directory database file corruption after crashes or
  power failures on Linux systems, enable file system write barriers and make
  sure that the file system journaling mode is ordered. For details on how to
  enable write barriers and how to set the journaling mode for data, see the
  options for your file system in the <command>mount</command> command manual
  page.</para>
  <xinclude:include href="../shared/para-write-barriers.xml" />
 </section>

 <section xml:id="prerequisites-virtualization">

 opends/src/main/docbkx/shared/para-write-barriers.xml

New file
@@ -0,0 +1,39 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
  ! CCPL HEADER START
  !
  ! This work is licensed under the Creative Commons
  ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
  ! To view a copy of this license, visit
  ! http://creativecommons.org/licenses/by-nc-nd/3.0/
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at
  ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
  ! If applicable, add the following below this CCPL HEADER, with the fields
  ! enclosed by brackets "[]" replaced with your own identifying information:
  !      Portions Copyright [yyyy] [name of copyright owner]
  !
  ! CCPL HEADER END
  !
  !      Copyright 2013 ForgeRock AS
  !
-->
<para xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
      xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
      xsi:schemaLocation='http://docbook.org/ns/docbook
                          http://docbook.org/xml/5.0/xsd/docbook.xsd'>
 In order to avoid directory database file corruption
 after crashes or power failures on Linux systems,
 enable file system write barriers
 and make sure that the file system journaling mode is ordered.

 For details on how to enable write barriers
 and how to set the journaling mode for data,
 see the options for your file system
 in the <command>mount</command> command manual page.
</para>

 opends/src/main/docbkx/shared/sec-prerequisites-file-descriptors.xml

New file
@@ -0,0 +1,68 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
  ! CCPL HEADER START
  !
  ! This work is licensed under the Creative Commons
  ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
  ! To view a copy of this license, visit
  ! http://creativecommons.org/licenses/by-nc-nd/3.0/
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at
  ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
  ! If applicable, add the following below this CCPL HEADER, with the fields
  ! enclosed by brackets "[]" replaced with your own identifying information:
  !      Portions Copyright [yyyy] [name of copyright owner]
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2013 ForgeRock AS
  !
-->
<section xml:id="prerequisites-file-descriptors"
         xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
         xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
         xsi:schemaLocation='http://docbook.org/ns/docbook
                             http://docbook.org/xml/5.0/xsd/docbook.xsd'>
 <title>Maximum Open Files</title>

 <indexterm>
  <primary>File descriptors</primary>
  <secondary>Requirements</secondary>
 </indexterm>

 <para>
  OpenDJ needs to be able to open many file descriptors,
  especially when handling thousands of client connections.

  Linux systems in particular often set a limit of 1024 per user,
  which is too low to handle many client connections to OpenDJ.
 </para>

 <para>
  When setting up OpenDJ for production use,
  make sure OpenDJ can use at least 64K (65536) file descriptors.

  For example when running OpenDJ as user <literal>opendj</literal>
  on a Linux system that uses
  <filename>/etc/security/limits.conf</filename> to set user level limits,
  you can set soft and hard limits by adding these lines to the file:
 </para>

 <programlisting language="none">opendj soft nofile 65536
opendj hard nofile 131072</programlisting>

 <para>
  The example above assumes the system has
  enough file descriptors available overall.

  You can check the Linux system overall maximum as follows.
 </para>

 <screen>$ cat /proc/sys/fs/file-max
204252</screen>
</section>