From ef8cef438c4e8e95090d15f9c2bc265d00e8223a Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Tue, 14 Jul 2015 08:52:10 +0000
Subject: [PATCH] CR-7532 OPENDJ-2188 Merge install chapters
---
/dev/null | 315 ---------
opendj-server-legacy/src/main/docbkx/shared/para-when-you-unzip.xml | 37 +
opendj-server-legacy/src/main/docbkx/install-guide/preface.xml | 18
opendj-server-legacy/src/main/docbkx/install-guide/index.xml | 3
opendj-server-legacy/src/main/docbkx/install-guide/chap-install.xml | 1567 +++++++++++++++++++++++++++++++++++++++++++++++
5 files changed, 1,618 insertions(+), 322 deletions(-)
diff --git a/opendj-server-legacy/src/main/docbkx/install-guide/chap-install-cli.xml b/opendj-server-legacy/src/main/docbkx/install-guide/chap-install-cli.xml
deleted file mode 100644
index d5f19da..0000000
--- a/opendj-server-legacy/src/main/docbkx/install-guide/chap-install-cli.xml
+++ /dev/null
@@ -1,982 +0,0 @@
-<?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-cli'
- 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 From the Command Line</title>
-
- <para>This chapter covers command-line installation with additional
- information on setup options.</para>
-
- <itemizedlist>
- <listitem><para><xref linkend="before-you-install" /></para></listitem>
- <listitem><para><xref linkend="command-line-install" /></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 the correct Java environment installed, as
- described in the <citetitle>Release Notes</citetitle> section on <link
- xlink:href="release-notes#prerequisites-java" xlink:show="new"
- xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Java
- Environment</citetitle></link> requirements.</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 latter environment variable is
- useful for example 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 server software is available.</para>
-
- <varlistentry>
- <term>OpenDJ-<?eval ${docTargetVersion}?>.zip</term>
- <listitem>
- <para>Cross-platform OpenDJ directory server installation files</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>opendj_<?eval ${docTargetVersion}?>-1_all.deb</term>
- <listitem>
- <para>OpenDJ directory server native package for Debian and related
- Linux distributions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>opendj-<?eval ${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-<?eval ${docTargetVersion}?>-DSML.war</term>
- <listitem>
- <para>Cross-platform OpenDJ DSML gateway web archive</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>opendj-rest2ldap-servlet-<?eval ${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>
-
- <para>If you plan to install OpenDJ DSML gateway or OpenDJ REST LDAP gateway,
- make sure you have an appropriate application server installed.</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,
- you can use the Java <command>keytool</command> command.</para>
-
- <para>See <link xlink:href="admin-guide#setup-server-cert"
- xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Preparing For
- Secure Communications</citetitle></link> in the <citetitle>Administration
- Guide</citetitle> for examples.</para>
- </step>
- </procedure>
-
- <procedure xml:id="command-line-install">
- <title>To Install OpenDJ Directory Server</title>
- <indexterm><primary>Command-line installation</primary></indexterm>
- <step>
- <para>Unzip <filename>OpenDJ-<?eval ${docTargetVersion}?>.zip</filename>
- in the file system directory where you want to install the server.</para>
-
- <para>
- Unlike the web-based Quick Setup install, 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>
-
- <para>When you unzip <filename>OpenDJ-<?eval ${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-<?eval ${docTargetVersion}?>.zip</filename>,
- and then selecting Extract All from the context menu, be sure to remove the
- trailing <filename>OpenDJ-<?eval ${docTargetVersion}?></filename> directory
- from the folder you specify.</para>
- </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 <literal>-n</literal>
- or <literal>--no-prompt</literal> option.</para>
-
- <para>The <command>setup</command> command without the
- <literal>--cli</literal> option runs the Quick Start
- GUI installer with your local version of software.</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>Some 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 administrative and other operations
- allowed for the server, called root user due to the similarity
- to the UNIX root. The default, <literal>cn=Directory Manager</literal>,
- is a well-known name. If you have reason to be paranoid, you might
- opt for 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. 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>.
- 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. 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>This is the service entrance used to configure the server,
- run tasks, and so forth. The default is 4444.</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 is the standard text format for
- expressing LDAP data. 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 huge data set to import, you no doubt should
- 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. The
- default port for LDAPS is 636. 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. Self-signed certificates 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.
- </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 <?eval ${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>
- </step>
- </procedure>
-
- <note>
- <para>You can install OpenDJ in unattended and silent fashion, too. See
- the procedure, <xref linkend="install-properties-file" />.</para>
- </note>
-
- <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_<?eval ${docTargetVersion}?>-1_all.deb</userinput>
-<computeroutput>Selecting previously unselected package opendj.
-(Reading database ... 185569 files and directories currently installed.)
-Unpacking opendj (from opendj_<?eval ${docTargetVersion}?>-1_all.deb) ...
-
-Setting up opendj (<?eval ${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 .deb 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 <?eval ${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 it 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-<?eval ${docTargetVersion}?>-1.noarch.rpm</userinput>
-<computeroutput>Pre Install - initial install
-Post Install - initial install</computeroutput>
-
-#
- </screen>
-
- <para>
- The .rpm installs OpenDJ directory server
- in the <filename>/opt/opendj</filename> directory,
- generates service management scripts,
- adds documentation files under
- <filename>/usr/share/doc/opendj-<replaceable>version</replaceable></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>/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 <?eval ${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>
-
- <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>), as 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-<?eval ${docTargetVersion}?>.zip && 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 allow you to further configure OpenDJ directory server.
- 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 <<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-<?eval ${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. See the
- procedure, <link xlink:href="admin-guide#setup-rest2ldap-connection-handler"
- xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Set Up REST
- Access to OpenDJ Directory Server</citetitle></link>, for instructions.</para>
-
- <para>You configure the gateway to access your directory service by editing
- <filename>opendj-rest2ldap-servlet.json</filename> where you deploy the
- gateway web application.</para>
-
- <step>
- <para>Deploy
- <filename>opendj-rest2ldap-servlet-<?eval ${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 your
- 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>
-
- <para>At minimum, make sure that the host name and port numbers for
- <literal>primaryLDAPServers</literal> are properly configured, that
- <literal>authentication</literal> reflects the correct simple bind
- credentials, and that the <literal>mappings</literal> for the endpoints
- correctly match your directory data.</para>
-
- <para>For details on the configuration, see <link
- xlink:href="reference#appendix-rest2ldap" xlink:show="new"
- xlink:role="http://docbook.org/xlink/role/olink"><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 <link xlink:show="new"
- xlink:href="admin-guide#setup-server-cert"
- xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Preparing For
- Secure Communications</citetitle></link> for an example showing how to use
- the <command>keytool</command> command to support 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 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 the backend 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.
- Try a URL such as
- <literal>http://user.0:password@opendj.example.com:8080/rest2ldap/users/user.0</literal>
- instead.</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 located 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 <filename>WEB-INF/web.xml</filename> configuration
- file.</para>
-
- <step>
- <para>Deploy <filename>OpenDJ-<?eval ${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>
diff --git a/opendj-server-legacy/src/main/docbkx/install-guide/chap-install-gui.xml b/opendj-server-legacy/src/main/docbkx/install-guide/chap-install-gui.xml
deleted file mode 100644
index 172aa85..0000000
--- a/opendj-server-legacy/src/main/docbkx/install-guide/chap-install-gui.xml
+++ /dev/null
@@ -1,315 +0,0 @@
-<?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-gui'
- 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 With a Graphical Installer</title>
- <indexterm><primary>Downloading OpenDJ</primary></indexterm>
- <indexterm><primary>Quick install</primary></indexterm>
-
- <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 read only this
- chapter, or just try out installation without reading any further.</para>
-
- <xinclude:include href="../shared/itemizedlist-download.xml" />
-
- <section xml:id="install-gui-quick-setup">
- <title>Installing OpenDJ With the QuickSetup Wizard</title>
-
- <para>
- The OpenDJ QuickSetup wizard provides a graphical user interface
- for installing OpenDJ directory server.
- </para>
-
- <para>
- To begin installation, download OpenDJ-${docTargetVersion}.zip,
- unzip the file,
- 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,
- <command>opendj/setup</command> (UNIX),
- <command>opendj\setup.bat</command> (Windows),
- or <command>opendj/QuickSetup.app</command> (Mac OS X).
- </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>
-
- <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 latter environment variable is useful for example
- 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>
- </note>
-
- <itemizedlist>
- <para>
- The QuickSetup 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>
- </section>
-
- <section xml:id="install-gui-windows-msi">
- <title>Installing OpenDJ From the Windows Installer Package</title>
-
- <para>
- You can start installing OpenDJ directory server on Windows systems
- from the Windows installer package,
- <filename>OpenDJ-${docTargetVersion}.msi</filename>.
- </para>
-
- <indexterm><primary>Windows installer (.msi) package</primary></indexterm>
-
- <procedure xml:id="install-gui-windows-msi-steps">
- <title>To Install OpenDJ From the Windows Installer Package</title>
-
- <para>
- Installing OpenDJ directory server by using 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 QuickSetup wizard
- and following the instructions on screen
- as described in <xref linkend="install-gui-quick-setup" />.
- </para>
- </step>
- </procedure>
- </section>
-
- <section xml:id="install-launch-control-panel">
- <title>Starting OpenDJ Control Panel</title>
-
- <para>
- You might close OpenDJ Control Panel,
- or decide to start it later after closing the QuickSetup wizard.
- </para>
-
- <itemizedlist>
- <para>
- To launch OpenDJ Control Panel again later, 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.
- Depending on your host system, this command is one of the following.
- </para>
-
- <listitem>
- <para>(Mac OS X) <command>/path/to/opendj/bin/ControlPanel.app</command></para>
- </listitem>
- <listitem>
- <para>(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>
- </section>
-</chapter>
diff --git a/opendj-server-legacy/src/main/docbkx/install-guide/chap-install.xml b/opendj-server-legacy/src/main/docbkx/install-guide/chap-install.xml
new file mode 100644
index 0000000..4740262
--- /dev/null
+++ b/opendj-server-legacy/src/main/docbkx/install-guide/chap-install.xml
@@ -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 && 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 <<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>
diff --git a/opendj-server-legacy/src/main/docbkx/install-guide/index.xml b/opendj-server-legacy/src/main/docbkx/install-guide/index.xml
index d2cdd01..e125b5b 100644
--- a/opendj-server-legacy/src/main/docbkx/install-guide/index.xml
+++ b/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' />
diff --git a/opendj-server-legacy/src/main/docbkx/install-guide/preface.xml b/opendj-server-legacy/src/main/docbkx/install-guide/preface.xml
index 8c5ac10..eb873f1 100644
--- a/opendj-server-legacy/src/main/docbkx/install-guide/preface.xml
+++ b/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>
diff --git a/opendj-server-legacy/src/main/docbkx/shared/para-when-you-unzip.xml b/opendj-server-legacy/src/main/docbkx/shared/para-when-you-unzip.xml
new file mode 100644
index 0000000..ff22594
--- /dev/null
+++ b/opendj-server-legacy/src/main/docbkx/shared/para-when-you-unzip.xml
@@ -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>
--
Gitblit v1.10.0