<?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>
|
