CR-7532 OPENDJ-2188 Merge install chapters

Mark Craig

14.52.2015 ef8cef438c4e8e95090d15f9c2bc265d00e8223a

CR-7532 OPENDJ-2188 Merge install chapters

This patch merges the GUI and CLI install chapters into one.

 opendj-server-legacy/src/main/docbkx/install-guide/chap-install-cli.xml

File was deleted

 opendj-server-legacy/src/main/docbkx/install-guide/chap-install-gui.xml

File was deleted

 opendj-server-legacy/src/main/docbkx/install-guide/chap-install.xml

New file
@@ -0,0 +1,1567 @@
<?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 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-2015 ForgeRock AS.
  !
-->
<chapter xml:id="chap-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"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xinclude="http://www.w3.org/2001/XInclude">
 <title>Installing OpenDJ Servers</title>

 <indexterm>
  <primary>Installing</primary>
 </indexterm>

 <para>
  This chapter covers installation of OpenDJ server software.
 </para>

 <itemizedlist>
  <para>
   This chapter includes the following procedures.
  </para>

  <listitem><para><xref linkend="before-you-install" /></para></listitem>
  <listitem><para><xref linkend="gui-install" /></para></listitem>
  <listitem><para><xref linkend="install-launch-control-panel" /></para></listitem>
  <listitem><para><xref linkend="command-line-install" /></para></listitem>
  <listitem><para><xref linkend="install-gui-windows-msi" /></para></listitem>
  <listitem><para><xref linkend="install-deb" /></para></listitem>
  <listitem><para><xref linkend="install-rpm" /></para></listitem>
  <listitem><para><xref linkend="install-properties-file" /></para></listitem>
  <listitem><para><xref linkend="install-rest2ldap-servlet" /></para></listitem>
  <listitem><para><xref linkend="install-dsml-gateway" /></para></listitem>
 </itemizedlist>

 <procedure xml:id="before-you-install">
  <title>To Prepare For Installation</title>

  <step xml:id="check-for-java">
   <para>
    Make sure you have a required Java environment installed
    as described in the <citetitle>Release Notes</citetitle> section,
    <link 
     xlink:href="release-notes#prerequisites-java" 
     xlink:role="http://docbook.org/xlink/role/olink"
     xlink:show="new"
    ><citetitle>Java Environment</citetitle></link>.
   </para>

   <para>
    If your default Java environment is not appropriate,
    set <literal>OPENDJ_JAVA_HOME</literal>
    to the path to the correct Java environment,
    or set <literal>OPENDJ_JAVA_BIN</literal>
    to the absolute path of the <command>java</command> command.
    The <literal>OPENDJ_JAVA_BIN</literal> environment variable is useful
    if you have both 32-bit and 64-bit versions of the Java environment installed, 
    and want to make sure you use the 64-bit version.
   </para>
  </step>

  <step>
   <para>
    Prevent anti-virus and intrusion detection systems from interfering
    with OpenDJ directory server.
   </para>

   <xinclude:include href="../shared/para-disable-anti-virus.xml" />
  </step>

  <step xml:id="download-opendj">
   <indexterm><primary>Downloading OpenDJ</primary></indexterm>
   
   <xinclude:include href="../shared/itemizedlist-download.xml" />

   <variablelist>
    <para>
     The following OpenDJ server software is available.
    </para>

    <varlistentry>
     <term>OpenDJ-${docTargetVersion}.zip</term>
     <listitem>
      <para>
       Cross-platform OpenDJ directory server installation files.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>OpenDJ-${docTargetVersion}.msi</term>
     <listitem>
      <para>
       Microsoft Windows native installer for OpenDJ directory server.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>opendj_${docTargetVersion}-1_all.deb</term>
     <listitem>
      <para>
       OpenDJ directory server native package for Debian 
       and related Linux distributions.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>opendj-${docTargetVersion}-1.noarch.rpm</term>
     <listitem>
      <para>
       OpenDJ directory server native package for Red Hat
       and related Linux distributions.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>OpenDJ-${docTargetVersion}-DSML.war</term>
     <listitem>
      <para>
       Cross-platform OpenDJ DSML gateway web archive.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>opendj-rest2ldap-servlet-${docTargetVersion}-servlet.war</term>
     <listitem>
      <para>
       Cross-platform OpenDJ REST LDAP gateway web archive.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </step>

  <step xml:id="app-server-needed-for-dsml">
   <indexterm><primary>DSML gateway</primary></indexterm>
   <indexterm><primary>REST LDAP gateway</primary></indexterm>

   <para>
    If you plan to install OpenDJ DSML gateway or OpenDJ REST LDAP gateway,
    make sure you have an appropriate application server installed.
   </para>

   <para>
    For a list of supported application servers,
    see the <citetitle>Release Notes</citetitle> section,
    <link
     xlink:href="release-notes#prerequisites-application-servers"
     xlink:role="http://docbook.org/xlink/role/olink"
     xlink:show="new"
    ><citetitle>Application Servers</citetitle></link>.
   </para>
  </step>

  <step>
   <para>
    If you plan to configure SSL or TLS to secure network communications
    between the server and client applications,
    get a properly signed digital certificate
    that your client applications recognize,
    such as one that fits with your organization's PKI
    or one provided by a recognized certificate authority.
   </para>

   <para>
    To use the certificate during installation,
    the certificate must be located
    in a key store provided with Java (JKS, JCEKS, PKCS#12),
    or on a PKCS#11 token.
    To import a signed certificate into a key store,
    use the Java <command>keytool</command> command.
   </para>

   <para>
    For details see the <citetitle>Administration Guide</citetitle> section,
    <link
     xlink:href="admin-guide#setup-server-cert"
     xlink:role="http://docbook.org/xlink/role/olink"
     xlink:show="new"
    ><citetitle>Preparing For Secure Communications</citetitle></link>.
   </para>
  </step>
 </procedure>

 <procedure xml:id="gui-install">
  <title>To Install OpenDJ Directory Server (Graphical User Interface)</title>

  <indexterm>
   <primary>Graphical user interface installation</primary>
  </indexterm>

  <para>
   The OpenDJ <command>setup</command> command launches a wizard
   that lets you install OpenDJ directory server
   through a graphical user interface.
  </para>

  <note>
   <para>
    If your environment picks up an old installation of Java,
    installation can fail.
    You might see an application error due to an old Java version.
   </para>
  </note>

  <para>
   After completing the steps in <xref linkend="before-you-install" />,
   follow these steps:
  </para>

  <step>
   <para>
    Unzip OpenDJ-${docTargetVersion}.zip, and then run the
    <link
     xlink:show="new"
     xlink:href="reference#setup-1"
     xlink:role="http://docbook.org/xlink/role/olink"
    ><command>setup</command></link> command.
   </para>

   <xinclude:include href="../shared/para-when-you-unzip.xml" />

   <itemizedlist>
    <para>
     Find the <command>setup</command> command in the following locations:
    </para>

    <listitem>
     <para>
      (UNIX|Linux) <command>opendj/setup</command>
     </para>
    </listitem>

    <listitem>
     <para>
      (Windows) <command>opendj\setup.bat</command>
     </para>
    </listitem>
   </itemizedlist>
  </step>

  <step>
   <para>
    Follow the instructions in the wizard.
   </para>

   <itemizedlist>
    <para>
     The wizard presents the following screens:
    </para>

    <listitem>
     <para>
      <emphasis>Welcome</emphasis>: summarizes the setup process
      and indicates the minimum required Java version
     </para>
    </listitem>

    <listitem>
     <para>
      <emphasis>License</emphasis>: presents the license agreement to accept
      before installing OpenDJ software
     </para>
    </listitem>

    <listitem>
     <para>
      <emphasis>Server Settings</emphasis>: prompts for basic server settings
      including installation path, host name, port numbers, secure connections,
      and credentials for the directory superuser
      (default bind DN: <literal>cn=Directory Manager</literal>)
     </para>
    </listitem>

    <listitem>
     <para>
      <emphasis>Topology Options</emphasis>: prompts for data replication options
      including whether this server is part of a replication topology,
      and if so the port number and security settings for this server,
      as well as the connection settings for a remote replica if available
     </para>
    </listitem>

    <listitem>
     <para>
      <emphasis>Directory Data</emphasis>: allows you to import or to generate
      LDAP directory data as part of the setup process
     </para>

     <para>
      This screen also allows you to select the backend type for data storage.
     </para>
    </listitem>

    <listitem>
     <para>
      <emphasis>Runtime Options</emphasis>: allows you to adjust
      JVM settings as part of the setup process,
      for example to allow OpenDJ to use more memory if necessary
     </para>
    </listitem>

    <listitem>
     <para>
      <emphasis>Review</emphasis>: presents current selections
      so that you can check everything is correct before running setup,
      with the option to start OpenDJ directory server after setup completes
     </para>
    </listitem>

    <listitem>
     <para>
      <emphasis>Finished</emphasis>: summarizes how setup completed,
      with the option to launch the OpenDJ Control Panel
     </para>
    </listitem>
   </itemizedlist>

   <para>
    <xref linkend="figure-quicksetup-control-panel" />
    shows the top-level window with status information.
    OpenDJ Control Panel helps to manage directory data, LDAP schema, indexes,
    monitoring, and JVM runtime options through a graphical user interface.
   </para>

   <figure xml:id="figure-quicksetup-control-panel">
    <title>OpenDJ Control Panel</title>

    <mediaobject>
     <imageobject>
      <imagedata fileref="images/OpenDJ-Control-Panel.png" format="PNG" />
     </imageobject>
      <textobject>
       <para>
        OpenDJ Control Panel offers basic administration capabilities.
       </para>
      </textobject>
    </mediaobject>
   </figure>
  </step>
 </procedure>

 <procedure xml:id="command-line-install">
  <title>To Install OpenDJ Directory Server (Command Line)</title>

  <indexterm>
   <primary>Command-line installation</primary>
  </indexterm>

  <para>
   The OpenDJ <command>setup --cli</command> command launches
   a command-line installation that is interactive by default.
   After completing the steps in <xref linkend="before-you-install" />,
   follow these steps:
  </para>

  <step>
   <para>Unzip <filename>OpenDJ-${docTargetVersion}.zip</filename>
   in the file system directory where you want to install the server.
   </para>

   <para>
    The
    <link
     xlink:show="new"
     xlink:href="reference#setup-1"
     xlink:role="http://docbook.org/xlink/role/olink"
    ><command>setup</command></link> command uses
    the directory where you unzipped the files as the installation directory,
    and does not ask you where to install OpenDJ.
    Therefore, if you want to install elsewhere on the file system,
    unzip the files in that location.
   </para>

   <xinclude:include href="../shared/para-when-you-unzip.xml" />
  </step>
  
  <step>
   <para>
    Run the <command>setup --cli</command> command
    found in the <filename>/path/to/opendj</filename> directory.
   </para>

   <para>
    This command starts the setup program in interactive mode on the command line,
    prompting you for each option.
    Alternatively, use additional <command>setup</command> options
    to specify values for the options you choose during interactive mode,
    thus scripting the installation process.
    See <command>setup --help</command> and the notes below.
   </para>
   
   <indexterm>
    <primary>Silent installation</primary>
   </indexterm>

   <para>
    To perform a non-interactive, silent installation,
    provide all the options to configure OpenDJ,
    and then also use the <option>-n</option>
    or <option>--no-prompt</option> option.
   </para>
   
   <para>
    The <command>setup</command> command without the <option>--cli</option> option
    runs the graphical user interface installer.
   </para>

   <para>
    The following example shows interactive installation of OpenDJ directory server.
   </para>

   <screen>
$ <userinput>/path/to/opendj/setup --cli</userinput>
<computeroutput>READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING
THE FORGEROCK SOFTWARE, YOU, ON BEHALF OF YOURSELF AND YOUR COMPANY, AGREE TO
BE BOUND BY THIS SOFTWARE LICENSE AGREEMENT. IF YOU DO NOT AGREE TO THESE
TERMS, DO NOT DOWNLOAD OR INSTALL THE FORGEROCK SOFTWARE.

...

Please read the License Agreement above.
You must accept the terms of the agreement before continuing with the
installation.
Accept the license (Yes/No) [No]:</computeroutput><userinput>Yes</userinput>

<computeroutput>What would you like to use as the initial root user DN for the Directory
Server? [cn=Directory Manager]:
Please provide the password to use for the initial root user:
Please re-enter the password for confirmation:

Provide the fully-qualified directory server host name that will be used when
generating self-signed certificates for LDAP SSL/StartTLS, the administration
connector, and replication [opendj.example.com]:

On which port would you like the Directory Server to accept connections from
LDAP clients? [1389]: 

On which port would you like the Administration Connector to accept
connections? [4444]: 

Do you want to create base DNs in the server? (yes / no) [yes]:</computeroutput>
<computeroutput condition="local-db">
Provide the backend type:

    1)  local-db
    2)  pdb

Enter choice [1]:</computeroutput> <userinput condition="local-db">2</userinput>

<computeroutput>Provide the base DN for the directory data: [dc=example,dc=com]:

Options for populating the database:

    1)  Only create the base entry
    2)  Leave the database empty
    3)  Import data from an LDIF file
    4)  Load automatically-generated sample data

Enter choice [1]:</computeroutput> <userinput>3</userinput>

<computeroutput>Please specify the path to the LDIF file containing the data to import:</computeroutput>
<userinput>/path/to/Example.ldif</userinput>

<computeroutput>Do you want to enable SSL? (yes / no) [no]:

Do you want to enable Start TLS? (yes / no) [no]:

Do you want to start the server when the configuration is completed? (yes /
no) [yes]:


Setup Summary
=============
LDAP Listener Port:            1389
Administration Connector Port: 4444
JMX Listener Port:
LDAP Secure Access:            disabled
Root User DN:                  cn=Directory Manager
Directory Data:                Create New Base DN dc=example,dc=com.
Base DN Data: Import Data from LDIF File (/path/to/Example.ldif)

Start Server when the configuration is completed


What would you like to do?

    1)  Set up the server with the parameters above
    2)  Provide the setup parameters again
    3)  Print equivalent non-interactive command-line
    4)  Cancel and exit

Enter choice [1]:

See /var/.../opendj-setup...log for a detailed log of this operation.

Configuring Directory Server ..... Done.
Importing LDIF file /path/to/Example.ldif ........... Done.
Starting Directory Server ........... Done.

To see basic server configuration status and configuration you can launch \
/path/to/opendj/bin/status</computeroutput>
   </screen>

   <variablelist>
    <para>
     Notes on the options follow.
    </para>

    <varlistentry>
      <term>Initial root user DN</term>
      <listitem>
        <para>
         The root user Distinguished Name identifies a user
         who can perform all operations allowed for the server,
         called root user due to the similarity to the UNIX root user.
        </para>

        <para>
         The default, <literal>cn=Directory Manager</literal>,
         is a well-known name.
         For additional protection, use a different name.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Initial root user password</term>
      <listitem>
        <para>
         The root user will use simple, password-based authentication.
         Later you can limit clear text access to avoid snooping,
         but for now use a strong password here unless this is a throwaway server.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Fully-qualified directory server host name</term>
      <listitem>
        <para>
         OpenDJ uses fully-qualified host name in self-signed certificates
         and for identification when you use replication.
        </para>

        <para>
         If you are installing a single server temporarily for evaluation,
         and are not concerned about replication
         and whether self-signed certificates can be trusted,
         then you can use an FQDN such as <literal>localhost.localdomain</literal>.
        </para>

        <para>
         Otherwise, use an FQDN that other hosts can resolve to reach your server.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>LDAP port</term>
      <listitem>
        <para>
         The default for LDAP is 389.
        </para>

        <para>
         If you are working as a user who cannot open port 389,
         setup suggests 1389 by default.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Administration port</term>
      <listitem>
        <para>
         The default is 4444.
        </para>

        <para>
         This is the service port used to configure the server and to run tasks.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Create base DNs</term>
      <listitem>
        <para>
         You need a base Distinguished Name,
         such as <literal>dc=example,dc=com</literal>,
         to add directory data.
         If you already have LDIF,
         the base DN you want is the distinguished name suffix
         common to all entries in your LDIF.
        </para>

        <para>
         When you choose to create a base DN,
         the <command>setup</command> command also
         prompts you for a backend type,
         which identifies the implementation of the repository
         that holds your data.
        </para>

        <para>
         Later you can add more base DNs
         if your data belongs in more than one suffix.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Import LDIF</term>
      <listitem>
       <para>
        LDAP data interchange format (LDIF) is the standard text format
        for expressing LDAP data.
       </para>

       <para>
        If you have LDIF already,
        one reason you might not want to import the data
        at the same time you install is
        because your data uses attributes not defined in the default schema,
        and so you will wait to add schema definitions before you import.
       </para>

       <para>
        If you have a large data set to import,
        also increase the import cache size,
        which you can do by passing a Java properties file.
        You might also prefer to perform data import offline.
       </para>
      </listitem>
    </varlistentry>

    <varlistentry>
     <term>Enable SSL and TLS</term>
     <listitem>
      <para>
       Enabling Secure Sockets Layer or Transport Layer Security
       lets you protect the network traffic between directory clients
       and your server.
      </para>

      <variablelist>
       <varlistentry>
        <term>SSL</term>
        <listitem>
         <para>
          SSL requires its own, separate port for LDAPS traffic.
         </para>

         <para>
          The default port for LDAPS is 636.
         </para>

         <para>
          If you are working as a user who cannot open port 636,
          setup suggests 1636 by default.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term>TLS</term>
        <listitem>
         <para>
          TLS lets you use StartTLS to negotiate a secure connection
          between a client and server,
          starting from the same server port you configured for LDAP.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term>X.509 certificates</term>
         <listitem>
          <para>
           The digital certificate you need for SSL and TLS can be self-signed
           and created on the fly.
           Trouble is, client applications view self-signed certificates like fake IDs,
           and so do not trust them.
         </para>

         <para>
           Self-signed certificates for externally facing ports facilitate testing,
           but are not intended for production use.
          </para>
         </listitem>
       </varlistentry>
      </variablelist>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>Start the server</term>
     <listitem>
      <para>
       If you do not start the server during installation,
       you can use the <command>/path/to/opendj/bin/start-ds</command> command later.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </step>

  <step>
   <para>
    Run the
    <link
     xlink:show="new"
     xlink:href="reference#status-1"
     xlink:role="http://docbook.org/xlink/role/olink"
    ><command>status</command></link> command
    to make sure your OpenDJ server is working as expected
    as shown in the following example.
   </para>

   <screen>
$ <userinput>/path/to/opendj/bin/status</userinput>
<computeroutput>
>>>> Specify OpenDJ LDAP connection parameters

Administrator user bind DN [cn=Directory Manager]:

Password for user 'cn=Directory Manager':

          --- Server Status ---
Server Run Status:        Started
Open Connections:         1

          --- Server Details ---
Host Name:                opendj.example.com
Administrative Users:     cn=Directory Manager
Installation Path:        /path/to/opendj
Version:                  OpenDJ ${docTargetVersion}
Java Version:             <replaceable>version</replaceable>
Administration Connector: Port 4444 (LDAPS)

          --- Connection Handlers ---
Address:Port : Protocol : State
-------------:----------:---------
--           : LDIF     : Disabled
0.0.0.0:161  : SNMP     : Disabled
0.0.0.0:636  : LDAPS    : Disabled
0.0.0.0:1389 : LDAP     : Enabled
0.0.0.0:1689 : JMX      : Disabled

          --- Data Sources ---
Base DN:     dc=example,dc=com
Backend ID:  userRoot
Entries:     160
Replication: Disabled</computeroutput>
   </screen>

   <note>
    <para>
     You can install OpenDJ in unattended and silent fashion, too.
     See the procedure, <xref linkend="install-properties-file" />.
    </para>
   </note>
  </step>
 </procedure>

 <procedure xml:id="install-launch-control-panel">
  <title>To Start OpenDJ Control Panel</title>

  <para>
   You might close OpenDJ Control Panel,
   or decide to start it later after closing the setup wizard.
  </para>

  <step>
  <itemizedlist>
   <para>
    To launch OpenDJ Control Panel, run the
    <link
     xlink:show="new"
     xlink:href="reference#control-panel-1"
     xlink:role="http://docbook.org/xlink/role/olink"
    ><command>control-panel</command></link> command.
   </para>

   <para>
    Depending on your host system, this command is one of the following.
   </para>

   <listitem>
    <para>
     (Linux|UNIX) <command>/path/to/opendj/bin/control-panel</command>
    </para>
   </listitem>

   <listitem>
    <para>
     (Windows) <command>C:\path\to\opendj\bat\control-panel.bat</command>
    </para>
   </listitem>
  </itemizedlist>
  </step>
 </procedure>

 <procedure xml:id="install-gui-windows-msi">
  <title>To Install OpenDJ From the Windows Installer Package</title>

  <indexterm>
   <primary>
    Windows installer (.msi) package
   </primary>
  </indexterm>

  <para>
   You can install OpenDJ directory server on Windows systems
   by using the Windows installer package,
   <filename>OpenDJ-${docTargetVersion}.msi</filename>.
  </para>

  <para>
   Installing OpenDJ directory server from the Windows installer package
   is a two-stage process.
   First, you install the files by using the Windows installer package wizard.
   Second, you configure OpenDJ by using the <command>setup</command> command.
  </para>

  <step>
   <para>
    Prevent anti-virus and intrusion detection systems from interfering
    with OpenDJ directory server.
   </para>

   <xinclude:include href="../shared/para-disable-anti-virus.xml" />
  </step>

  <step>
   <para>
    Install OpenDJ files in one of the following ways.
   </para>

   <stepalternatives>
    <step>
     <substeps>
      <step>
       <para>
        Double-click the Windows installer package,
        <filename>OpenDJ-${docTargetVersion}.msi</filename>,
        to start the install wizard.
       </para>
      </step>

      <step>
       <para>
        In the Destination Folder screen, set the folder
        where the wizard installs OpenDJ directory server files.
       </para>

       <para>
        The default location is under Program Files on the system drive.
        For example if the system drive is C:, the default location is
        <filename>C:\Program Files (x86)\OpenDJ\</filename>,
        as the native executable is a 32-bit application,
        though you can run OpenDJ directory server
        with a 64-bit Java environment.
       </para>
      </step>
     </substeps>
    </step>

    <step>
     <para>
      Use the Microsoft <command>msiexec.exe</command> command
      to install the files.
     </para>

     <para>
      The following example installs OpenDJ directory server files under
      <filename>C:\OpenDJ-${docTargetVersion}</filename>,
      writing an installation log file, <filename>install.log</filename>,
      in the current folder.
     </para>

     <screen>
C:\><userinput>msiexec /i OpenDJ-${docTargetVersion}.msi /l* install.log /q OPENDJ=C:\OpenDJ-${docTargetVersion}</userinput>
     </screen>
    </step>
   </stepalternatives>
  </step>

  <step>
   <para>
    Start the installation.
   </para>

   <para>
    When installation is finished, OpenDJ directory server files
    are found in the location you specified as Destination Folder.
    You must still run the <command>setup</command> command
    before you can use OpenDJ directory server.
   </para>
  </step>

  <step>
   <para>
    Browse to the Destination Folder,
    and double-click the <command>setup</command> command
    to start the OpenDJ setup wizard,
    and then follow the instructions on screen
    as described in <xref linkend="gui-install" />.
   </para>
  </step>
 </procedure>

 <procedure xml:id="install-deb">
  <title>To Install From the Debian Package</title>

  <indexterm>
   <primary>Debian (.deb) package</primary>
  </indexterm>

  <para>
   On Debian and related Linux distributions such as Ubuntu,
   you can install OpenDJ directory server from the Debian package.
  </para>

  <step performance="optional">
   <para>
    Before you install OpenDJ,
    install a Java runtime environment if none is installed yet.
   </para>

   <screen>
$ <userinput>sudo apt-get install default-jre</userinput>
   </screen>
  </step>

  <step>
   <para>
    Install the OpenDJ directory server package.
   </para>

   <screen>
$ <userinput>sudo dpkg -i opendj_${docTargetVersion}-1_all.deb</userinput>
<computeroutput>Selecting previously unselected package opendj.
(Reading database ... 185569 files and directories currently installed.)
Unpacking opendj (from opendj_${docTargetVersion}-1_all.deb) ...

Setting up opendj (${docTargetVersion}) ...
 Adding system startup for /etc/init.d/opendj ...
   /etc/rc0.d/K20opendj -> ../init.d/opendj
   /etc/rc1.d/K20opendj -> ../init.d/opendj
   /etc/rc6.d/K20opendj -> ../init.d/opendj
   /etc/rc2.d/S20opendj -> ../init.d/opendj
   /etc/rc3.d/S20opendj -> ../init.d/opendj
   /etc/rc4.d/S20opendj -> ../init.d/opendj
   /etc/rc5.d/S20opendj -> ../init.d/opendj

Processing triggers for ureadahead ...
ureadahead will be reprofiled on next reboot</computeroutput>
   </screen>

   <para>
    The Debian package installs OpenDJ directory server
    in the <filename>/opt/opendj</filename> directory,
    generates service management scripts,
    adds documentation files under <filename>/usr/share/doc/opendj</filename>,
    and adds man pages under <filename>/opt/opendj/share/man</filename>.
   </para>

   <para>
    The files are owned by root by default,
    making it easier to have OpenDJ listen on ports 389 and 636.
   </para>
  </step>

  <step>
   <para>
    Configure OpenDJ directory server by using the command
    <command>sudo /opt/opendj/setup</command>.
   </para>

   <screen>
$ <userinput>sudo /opt/opendj/setup --cli</userinput>
<computeroutput>...
To see basic server configuration status and configuration you can launch
 /opt/opendj/bin/status</computeroutput>
   </screen>
  </step>

  <step performance="optional">
   <para>
    Check OpenDJ directory server status.
   </para>

   <screen>
$ <userinput>service opendj status</userinput>
<computeroutput>$opendj status: > Running.</computeroutput>
$ <userinput>sudo /opt/opendj/bin/status</userinput>

<computeroutput>
>>>> Specify OpenDJ LDAP connection parameters

Administrator user bind DN [cn=Directory Manager]:

Password for user 'cn=Directory Manager':

          --- Server Status ---
Server Run Status:        Started
Open Connections:         1

          --- Server Details ---
Host Name:                ubuntu.example.com
Administrative Users:     cn=Directory Manager
Installation Path:        /opt/opendj
Version:                  OpenDJ ${docTargetVersion}
Java Version:             <replaceable>version</replaceable>
Administration Connector: Port 4444 (LDAPS)

          --- Connection Handlers ---
Address:Port : Protocol               : State
-------------:------------------------:---------
--           : LDIF                   : Disabled
0.0.0.0:161  : SNMP                   : Disabled
0.0.0.0:389  : LDAP (allows StartTLS) : Enabled
0.0.0.0:636  : LDAPS                  : Enabled
0.0.0.0:1689 : JMX                    : Disabled
0.0.0.0:8080 : HTTP                   : Disabled

          --- Data Sources ---
Base DN:     dc=example,dc=com
Backend ID:  userRoot
Entries:     2002
Replication: </computeroutput>
   </screen>
  </step>
 </procedure>

 <procedure xml:id="install-rpm">
  <title>To Install From the RPM Package</title>

  <indexterm>
   <primary>Red Hat (.rpm) package</primary>
  </indexterm>

  <para>
   On Red Hat and related Linux distributions such as Fedora and CentOS,
   you can install OpenDJ directory server from the RPM package.
  </para>

  <step>
   <para>
    Log in as superuser to install the software.
   </para>

   <screen>
$ <userinput>su</userinput>
<computeroutput>Password:</computeroutput>
#
   </screen>
  </step>

  <step performance="optional">
   <para>
    Before you install OpenDJ,
    install a Java runtime environment if none is installed yet.
   </para>

   <para>
    You might need to download an RPM to install the Java runtime environment,
    and then install the RPM by using the <command>rpm</command> command.
   </para>

   <screen>
# <userinput>rpm -ivh jre-*.rpm</userinput>
   </screen>
  </step>

  <step>
   <para>
    Install the OpenDJ directory server package.
   </para>

   <screen>
# <userinput>rpm -i opendj-${docTargetVersion}-1.noarch.rpm</userinput>
<computeroutput>Pre Install - initial install
Post Install - initial install</computeroutput>

#
   </screen>

   <para>
    The RPM package installs OpenDJ directory server
    in the <filename>/opt/opendj</filename> directory,
    generates service management scripts,
    and adds man pages under <filename>/opt/opendj/share/man</filename>.
   </para>

   <para>
    The files are owned by root by default,
    making it easier to have OpenDJ listen on ports 389 and 636.
   </para>
  </step>

  <step>
   <para>
    Configure OpenDJ directory server by using the command
    <command>/opt/opendj/setup</command>.
   </para>

   <screen>
# <userinput>/opt/opendj/setup --cli</userinput>
<computeroutput>...
To see basic server configuration status and configuration you can launch
 /opt/opendj/bin/status</computeroutput>
   </screen>
  </step>

  <step performance="optional">
   <para>
    Check OpenDJ directory server status.
   </para>

   <screen>
# <userinput>service opendj status</userinput>
<computeroutput>opendj status: > Running.</computeroutput>
# <userinput>/opt/opendj/bin/status</userinput>

<computeroutput>
>>>> Specify OpenDJ LDAP connection parameters

Administrator user bind DN [cn=Directory Manager]:

Password for user 'cn=Directory Manager':

          --- Server Status ---
Server Run Status:        Started
Open Connections:         1

          --- Server Details ---
Host Name:                fedora.example.com
Administrative Users:     cn=Directory Manager
Installation Path:        /opt/opendj
Version:                  OpenDJ ${docTargetVersion}
Java Version:             <replaceable>version</replaceable>
Administration Connector: Port 4444 (LDAPS)

          --- Connection Handlers ---
Address:Port : Protocol               : State
-------------:------------------------:---------
--           : LDIF                   : Disabled
0.0.0.0:161  : SNMP                   : Disabled
0.0.0.0:389  : LDAP (allows StartTLS) : Enabled
0.0.0.0:636  : LDAPS                  : Enabled
0.0.0.0:1689 : JMX                    : Disabled
0.0.0.0:8080 : HTTP                   : Disabled

          --- Data Sources ---
Base DN:     dc=example,dc=com
Backend ID:  userRoot
Entries:     2002
Replication: </computeroutput>
   </screen>

   <para>
    By default OpenDJ starts in run levels 2, 3, 4, and 5.
   </para>

   <screen>
# <userinput>chkconfig --list | grep opendj</userinput>
<computeroutput>...
opendj         0:off    1:off    2:on    3:on    4:on    5:on    6:off</computeroutput>
   </screen>
  </step>
 </procedure>

 <procedure xml:id="install-properties-file">
  <title>To Install OpenDJ Directory Server With a Properties File</title>

  <indexterm>
   <primary>Silent installation</primary>
  </indexterm>

  <para>
   You can install OpenDJ directory server
   by using the <command>setup</command> command with a properties file.
  </para>

  <para>
   Property names correspond to the option names, but without leading dashes.
   Options that take no arguments become boolean properties
   as in the following example:
  </para>

  <programlisting language="ini">enableStartTLS=true</programlisting>

  <para>
   If you use a properties file with multiple tools,
   prefix the property name with the tool name
   followed by a dot (<literal>.</literal>),
   in the following example:
  </para>

  <programlisting language="ini">setup.rootUserPasswordFile=/tmp/pwd.txt</programlisting>

  <para>
   The following steps demonstrate use of a properties file
   as part of a scripted installation process.
  </para>

  <step>
   <para>
    Prepare your properties file.
   </para>

   <para>
    This procedure uses the following example properties file.
   </para>

   <programlisting language="ini">
#
# Sample properties file to set up OpenDJ directory server
#
hostname                        =opendj.example.com
ldapPort                        =1389
generateSelfSignedCertificate   =true
enableStartTLS                  =true
ldapsPort                       =1636
jmxPort                         =1689
adminConnectorPort              =4444
rootUserDN                      =cn=Directory Manager
rootUserPassword                =password
baseDN                          =dc=example,dc=com
ldifFile                        =/net/install/dj/Example.ldif
#sampleData                     =2000
   </programlisting>

   <para>
    If you have multiple servers to install,
    consider scripting creation of the properties files.
   </para>
  </step>

  <step>
   <para>
    Prepare an installation script.
   </para>

   <screen>
$ <userinput>cat /net/install/dj/1/setup.sh</userinput>
<computeroutput>#!/bin/sh

unzip -d /path/to /net/install/dj/OpenDJ-${docTargetVersion}.zip &amp;&amp; cd /path/to/opendj
./setup --cli --propertiesFilePath /net/install/dj/1/setup.props \
  --acceptLicense --no-prompt</computeroutput>
   </screen>

   <para>
    The properties file contains only installation options,
    and does not fully configure OpenDJ directory server.
   </para>

   <para>
    If you also want your script to configure OpenDJ directory server,
    follow a successful run of the <command>setup</command> command
    with <command>dsconfig</command> commands to configure the server.
    To run a series of configuration commands as a batch
    using the <command>dsconfig</command> command,
    use either
    the <option>--batchFilePath <replaceable>file</replaceable></option> option,
    where <replaceable>file</replaceable> contains the configuration commands,
    or the <option>--batch</option> option to read from standard input
    as in the following example that creates a backend and sets up indexes.
   </para>

   <screen>
<userinput>/path/to/opendj/bin/dsconfig \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --no-prompt \
 --trustAll \
 --batch &lt;&lt;END_OF_COMMAND_INPUT
 create-backend        --backend-name newBackend \
                       --type pdb \
                       --set base-dn:"dc=example,dc=org" \
                       --set db-cache-percent:20 \
                       --set enabled:true
 create-backend-index  --backend-name newBackend \
                       --type generic \
                       --set index-type:equality \
                       --set index-type:substring \
                       --index-name cn
 create-backend-index  --backend-name newBackend \
                       --type generic \
                       --set index-type:equality \
                       --set index-type:substring \
                       --index-name sn
 create-backend-index  --backend-name newBackend \
                       --type generic \
                       --set index-type:equality \
                       --index-name uid
 create-backend-index  --backend-name newBackend \
                       --type generic \
                       --set index-type:equality \
                       --set index-type:substring \
                       --index-name mail
END_OF_COMMAND_INPUT</userinput>
   </screen>
  </step>

  <step>
   <para>Run your installation script.</para>

   <screen>
$ <userinput>/net/install/dj/1/setup.sh</userinput>
<computeroutput>Archive:  /net/install/dj/OpenDJ-${docTargetVersion}.zip
   creating: /path/to/opendj
...
  inflating: /path/to/opendj/setup
  inflating: /path/to/opendj/uninstall
  inflating: /path/to/opendj/upgrade

READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING
THE FORGEROCK SOFTWARE, YOU, ON BEHALF OF YOURSELF AND YOUR COMPANY, AGREE TO
BE BOUND BY THIS SOFTWARE LICENSE AGREEMENT. IF YOU DO NOT AGREE TO THESE
TERMS, DO NOT DOWNLOAD OR INSTALL THE FORGEROCK SOFTWARE.

...

Do you accept the License Agreement?yes
See /var/folders/.../opendj-setup-....log for a detailed log of this operation.

Configuring Directory Server ..... Done.
Configuring Certificates ..... Done.
Importing LDIF file /net/install/dj/Example.ldif ....... Done.
Starting Directory Server ....... Done.

To see basic server configuration status and configuration you can launch
 /path/to/opendj/bin/status</computeroutput>
   </screen>

   <para>
    At this point you can use OpenDJ directory server,
    or you can perform additional configuration.
   </para>
  </step>
 </procedure>

 <procedure xml:id="install-rest2ldap-servlet">
  <title>To Install OpenDJ REST LDAP Gateway</title>

  <indexterm>
   <primary>REST LDAP gateway</primary>
  </indexterm>

  <para>
   The OpenDJ REST LDAP gateway functions as a web application
   in a web application container, running independently of OpenDJ.
   Alternatively, you can use the HTTP connection handler
   in OpenDJ directory server.
   For instructions see the <citetitle>Administration Guide</citetitle> procedure,
   <link
    xlink:href="admin-guide#setup-rest2ldap-connection-handler"
    xlink:role="http://docbook.org/xlink/role/olink"
    xlink:show="new"
   ><citetitle>To Set Up REST Access to OpenDJ Directory Server</citetitle></link>.
  </para>

  <para>
   You configure the gateway to access your directory service
   by editing the configuration file
   <filename>opendj-rest2ldap-servlet.json</filename>
   in the deployed OpenDJ REST LDAP gateway web application.
  </para>

  <step>
   <para>
    Deploy <filename>opendj-rest2ldap-servlet-${sdkDocTargetVersion}-servlet.war</filename>
    according to the instructions for your application server.
   </para>
  </step>

  <step>
   <para>
    Edit <filename>opendj-rest2ldap-servlet.json</filename>
    where you deployed the gateway web application.
   </para>

   <para>
    The default JSON resource for the configuration
    includes both connection and authentication information,
    and also <literal>mappings</literal>.
    The <literal>mappings</literal> describe how the gateway translates
    between JSON and LDAP representations of directory data.
    The default <literal>mappings</literal> are built
    to work with generated example data and also the sample content in
    <link xlink:show="new" xlink:href="../resources/Example.ldif">Example.ldif</link>.
   </para>

   <itemizedlist>
    <para>
     At minimum adjust the following gateway configuration settings:
    </para>

    <listitem>
     <para>
      <literal>primaryLDAPServers</literal>:
      Set to the correct directory server host names and port numbers.
     </para>
    </listitem>

    <listitem>
     <para>
      <literal>authentication</literal>:
      Set to the correct simple bind credentials.
     </para>
    </listitem>

    <listitem>
     <para>
      <literal>mappings</literal>:
      Make sure these match the directory data.
     </para>
    </listitem>
   </itemizedlist>

   <para>
    For details on the configuration see the <citetitle>Reference</citetitle> topic,
    <link
     xlink:href="reference#appendix-rest2ldap"
     xlink:role="http://docbook.org/xlink/role/olink"
     xlink:show="new"
    ><citetitle>REST LDAP Configuration</citetitle></link>.
   </para>

   <para>
    When connecting to directory servers over LDAPS or LDAP and StartTLS,
    you can configure the trust manager to use a file-based trust store
    for server certificates that the gateway should trust.
    This allows the gateway to validate server certificates signed
    for example by a Certificate Authority not recognized
    by the Java environment when setting up LDAPS or StartTLS connections.
    See the <citetitle>Administration Guide</citetitle> section,
    <link
     xlink:href="admin-guide#setup-server-cert"
     xlink:role="http://docbook.org/xlink/role/olink"
     xlink:show="new"
    ><citetitle>Preparing For Secure Communications</citetitle></link>
    for an example showing how to use the Java <command>keytool</command> command
    to import a server certificate into a trust store file.
   </para>
  </step>

  <step>
   <para>
    Restart the REST LDAP gateway or the application server
    to make sure the configuration changes are taken into account.
   </para>
  </step>

  <step>
   <para>
    Make sure that your directory server is running,
    and then check that the gateway is connecting correctly.
   </para>

   <para>
    The following command reads Babs Jensen's entry through the gateway
    to a directory server holding data from <filename>Example.ldif</filename>.
   </para>

   <screen>
$ <userinput>curl http://bjensen:hifalutin@opendj.example.com:8080/rest2ldap/users/bjensen</userinput>
<computeroutput>{
  "_rev" : "000000002ee3b764",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1862",
    "emailAddress" : "bjensen@example.com"
  },
  "_id" : "bjensen",
  "name" : {
    "familyName" : "Jensen",
    "givenName" : "Barbara"
  },
  "userName" : "bjensen@example.com",
  "displayName" : "Barbara Jensen",
  "manager" : [ {
    "_id" : "trigden",
    "displayName" : "Torrey Rigden"
  } ]
}</computeroutput>
   </screen>

   <para>
    If you generated example data, Babs Jensen's entry is not included.
    Instead, try a URL such as
    <literal>http://user.0:password@opendj.example.com:8080/rest2ldap/users/user.0</literal>.
   </para>
  </step>
 </procedure>

 <procedure xml:id="install-dsml-gateway">
  <title>To Install OpenDJ DSML gateway</title>

  <indexterm>
   <primary>DSML gateway</primary>
  </indexterm>
  
  <para>
   The OpenDJ DSML gateway functions as a web application in a web application container.
   The DSML gateway runs independently of OpenDJ directory server.
   You configure the gateway to access your directory service by editing
   the <literal>ldap.host</literal> and <literal>ldap.port</literal> parameters
   in the gateway <filename>WEB-INF/web.xml</filename> configuration file.
  </para>

  <step>
   <para>
    Deploy <filename>OpenDJ-${docTargetVersion}-DSML.war</filename>
    according to the instructions for your application server.
   </para>
  </step>

  <step>
   <para>
    Edit <filename>WEB-INF/web.xml</filename> to ensure the values for
    <literal>ldap.host</literal> and <literal>ldap.port</literal> are correct.
   </para>
  </step>

  <step>
   <para>
    Restart the web application container according to the instructions
    for your application server.
   </para>
  </step>
 </procedure>
</chapter>

 opendj-server-legacy/src/main/docbkx/install-guide/index.xml

@@ -56,8 +56,7 @@

 <xinclude:include href="preface.xml" />

 <xinclude:include href='chap-install-gui.xml' />
 <xinclude:include href='chap-install-cli.xml' />
 <xinclude:include href='chap-install.xml' />
 <xinclude:include href='chap-jvm-opts.xml' />
 <xinclude:include href='chap-upgrade.xml' />
 <xinclude:include href='chap-uninstall.xml' />

 opendj-server-legacy/src/main/docbkx/install-guide/preface.xml

@@ -36,14 +36,22 @@
 xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Release
 Notes</citetitle></link> before you get started.</para>

 <para>If you want only to try OpenDJ server software, and you
 do not plan to store any real or important data that you want to keep,
 then you need not read this entire guide. Instead try
 <para>
  If you want only to try OpenDJ server software,
  and you do not plan to store any real or important data that you want to keep,
  then you need not read this entire guide.
  Instead read the procedures
  <link
   xlink:show="new"
   xlink:href="install-guide#chap-install-gui"
   xlink:href="install-guide#before-you-install"
   xlink:role="http://docbook.org/xlink/role/olink"
  ><citetitle>Installing OpenDJ With a Graphical Installer</citetitle></link>.
  ><citetitle>To Prepare For Installation</citetitle></link>
  and
  <link
   xlink:show="new"
   xlink:href="install-guide#gui-install"
   xlink:role="http://docbook.org/xlink/role/olink"
  ><citetitle>To Install OpenDJ Directory Server (Graphical User Interface)</citetitle></link>.
 </para>

 <section>

 opendj-server-legacy/src/main/docbkx/shared/para-when-you-unzip.xml

New file
@@ -0,0 +1,37 @@
<?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 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 2015 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'>
 When you unzip <filename>OpenDJ-${docTargetVersion}.zip</filename>,
 a top-level <filename>opendj</filename> directory
 is created in the directory where you unzip the file.
 On Windows systems if you unzip the file by right-clicking
 <filename>OpenDJ-${docTargetVersion}.zip</filename>,
 and then selecting Extract All from the context menu,
 be sure to remove the trailing <filename>OpenDJ-${docTargetVersion}</filename> directory
 from the folder you specify.
</para>