<?xml version="1.0" encoding="UTF-8"?>

<refentry xml:id="upgrade-1" 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:xi="http://www.w3.org/2001/XInclude">

<xi:include href="common.xml" xpointer='xpointer(//info[@name="info"])'/>

<refmeta>

<refentrytitle><application>upgrade</application></refentrytitle>

<xi:include href="common.xml" xpointer='xpointer(//manvolnum[@name="v1m"])'/>

</refmeta>

<refnamediv>

<refname><application>upgrade</application></refname>

<refpurpose>upgrade configuration &amp; application data</refpurpose>

</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>

<command>upgrade</command>

<arg>-n</arg>

<arg>--force</arg>

<arg>--acceptLicense</arg>

<arg>--ignoreErrors</arg>

<sbr/><sbr/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-misc"]/*[@name="sc-quiet"

or @name="sc-verbose"])'/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-general"]/*)'/>

</cmdsynopsis>

</refsynopsisdiv>

<refsection>

<title>Description</title>

<para os="bsd;linux;windows">

This utility upgrades OpenDJ configuration (schema, directory server

configuration, and other configuration files) and application data (primarily

directory data) so that it is compatible with the binary files and scripts that

are installed.

</para>

<para os="solaris">

This utility upgrades OpenDJ configuration (schema, directory server

configuration, and other configuration files) and application data (primarily

directory data) so that it is compatible with the binary files and scripts,

which come with the package containing this utility.

</para>

<para os="linux;bsd;windows">

The <command>upgrade</command> command thus performs only part of the upgrade

process, which includes the following phases for a single server.

</para>

<orderedlist os="linux;bsd;windows">

<listitem>

<para>

Get and unpack a newer version of OpenDJ directory server software.

</para>

</listitem>

<listitem>

<para>

Stop the current OpenDJ directory server.

</para>

</listitem>

<listitem>

<para>

Overwrite existing binary and script files with those of the newer version, and

then run this utility, the <command>upgrade</command> command, before restarting

OpenDJ.

</para>

</listitem>

<listitem>

<para>

Start the upgraded OpenDJ directory server.

</para>

</listitem>

</orderedlist>

<para os="linux;bsd;windows">

Native packages (.deb, .rpm) perform more of the upgrade process, like stopping

OpenDJ if it is running, overwriting older files with newer files, running this

utility, and starting OpenDJ if it was running when you upgraded the package(s).

</para>

<important>

<para>

The <command>upgrade</command> command <emphasis>does not back up OpenDJ before

you upgrade, nor does it restore OpenDJ if the <command>upgrade</command>

command fails</emphasis>. In order to revert a failed upgrade, make sure you

back up OpenDJ directory server before you overwrite existing binary and script

files.

</para>

</important>

<para>

By default, the <command>upgrade</command> command requests confirmation before

making important configuration changes. You can use the

<option>--no-prompt</option> option to run the command non-interactively.

</para>

<para>

When using the <option>--no-prompt</option> option, if the

<command>upgrade</command> command cannot complete because it requires

confirmation for a potentially very long or critical task, then it exits with

an error and a message about how to finish making the changes. You can add the

<option>--force</option> option to force a non-interactive upgrade to continue

in this case, also performing long running and critical tasks.

</para>

<para>

After upgrading, see the resulting <filename>upgrade.log</filename> file for a

full list of operations performed.

</para>

<para os="solaris">

The usual steps to upgrade to a new version should be executed as a

normal user which has the <systemitem>OpenDJ Admin</systemitem> execution

profile:

</para>

<orderedlist os="solaris">

<listitem>

<para>

Stop all OpenDJ server instances currently running. Use <citerefentry>

<refentrytitle>svcadm</refentrytitle><manvolnum>1M</manvolnum>

</citerefentry> to disable related services.

</para>

</listitem>

<listitem>

<para>

Just to be sure, create a backup of all OpenDJ instance data directories. If

you have them on a separate ZFS, just create a snapshot.

</para>

</listitem>

<listitem>

<para>

For a major upgrade (change in the first or second number of the version string)

just install the new package. Otherwise, i.e. for minor upgrades, for IPS

packages, unfreeze the current version of the OpenDJ package and call <command

>pkg update opendj</command>. For old SYSV package versions uninstall the

current version using <citerefentry><refentrytitle>pkgrm</refentrytitle><manvolnum

>1M</manvolnum></citerefentry> and install the new version using the <citerefentry

><refentrytitle>pkgadd</refentrytitle><manvolnum>1M</manvolnum></citerefentry>

command.

</para>

</listitem>

<listitem>

<para>

For major upgrades, update the properties of the related SMF service (see the

examples below, how to do that). (TBD: let the upgrade script handle this).

</para>

</listitem>

<listitem>

<para>

Execute this utility for each data directory of the OpenDJ server instance you

want to upgrade.

</para>

</listitem>

<listitem>

<para>

If everything went fine, re-enable the related SMF service(s) using <citerefentry>

<refentrytitle>svcadm</refentrytitle><manvolnum>1M</manvolnum>

</citerefentry>.

</para>

</listitem>

<listitem>

<para>

Test, whether your OpenDJ server instances still work as expected.

</para>

</listitem>

<listitem>

<para>

Finally, for major upgrades you may now uninstall the old OpenDJ package using

<command>pkg uninstall</command> for IPS or <command>pkgrm</command> for older

SYSV packages to free up some disk space.

</para>

</listitem>

</orderedlist>

</refsection>

<refsection>

<title>Options</title>

<para>The following options are supported.</para>

<variablelist>

<varlistentry>

<term><option>--acceptLicense</option></term>

<listitem>

<para>

Automatically accepts the product license if there is one in the delivery.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--force</option></term>

<listitem>

<para>

Forces a non-interactive upgrade to continue even if it requires user

interaction. In particular, long running or critical upgrade tasks, such as

re-indexing, which require user confirmation will be skipped. This option may

only be used with the <option>--no-prompt</option> aka <option>-n</option>

option.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--ignoreErrors</option></term>

<listitem>

<para>

Ignores any errors which occur during the upgrade. This option should be used

with caution and may be useful in automated deployments where potential errors

are known in advance and resolved after the upgrade has completed.

</para>

</listitem>

</varlistentry>

</variablelist>

<refsection>

<title>Utility Input/Output Options</title>

<variablelist>

<varlistentry>

<term><option>-n, --no-prompt</option></term>

<listitem>

<para>

Use non-interactive mode. Prompt for any required information rather than fail.

</para>

</listitem>

</varlistentry>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-misc"]/*[@name="lc-quiet"

or @name="lc-verbose"])'/>

</variablelist>

</refsection>

<refsection>

<title>General Options</title>

<variablelist>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-general"]/*)'/>

</variablelist>

</refsection>

</refsection>

<refsection>

<title>Examples</title>

<para>

See the <citetitle>Installation Guide</citetitle> for an example upgrade process

for OpenDJ directory server installed from the cross-platform (.zip) delivery

(<link

xlink:href="http://opendj.forgerock.org/doc/install-guide#upgrade-zip-example"

><citetitle>Upgrading From OpenDJ 2.4.5</citetitle></link>).

</para>

</refsection>

<xi:include href="common.xml" xpointer='xpointer(//refsection[@name="env"])'/>

<refsection name='exit-0-gt0'>

<title>Exit Status</title>

<variablelist>

<varlistentry>

<term><errorcode>0</errorcode></term>

<listitem>

<para>The command completed successfully.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><errorcode>2</errorcode></term>

<listitem>

<para>

The command was run in non-interactive mode, but could not complete because

confirmation was required to run a long or critical task.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><errorcode>other</errorcode></term>

<listitem>

<para>An error occurred.</para>

</listitem>

</varlistentry>

</variablelist>

</refsection>

<xi:include href="common.xml" xpointer='xpointer(//refsection[@name="seeAlso"])'/>

</refentry>