external-software/github_OpenIdentityPlatform_OpenDJ.git

			@@ -20,7 +20,7 @@
			!
			! CCPL HEADER END
			!
			! Copyright 2011-2012 ForgeRock AS
			! Copyright 2011-2013 ForgeRock AS
			!
			-->
			<refentry xml:id='upgrade-1'
			@@ -30,7 +30,7 @@
			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'>
			<info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
			<info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
			<refmeta>
			<refentrytitle>upgrade</refentrytitle><manvolnum>1</manvolnum>
			<refmiscinfo class="software">OpenDJ</refmiscinfo>
			@@ -38,7 +38,7 @@
			</refmeta>
			<refnamediv>
			<refname>upgrade</refname>
			<refpurpose>upgrade OpenDJ directory server</refpurpose>
			<refpurpose>upgrade OpenDJ configuration & application data</refpurpose>
			</refnamediv>
			<refsynopsisdiv>
			<cmdsynopsis>
			@@ -48,43 +48,78 @@
			</refsynopsisdiv>
			<refsect1>
			<title>Description</title>
			<para>This utility can be used to upgrade the directory server to a newer
			version or revert to a previous version.</para>
			<para>When using this tool to upgrade the server you should first downloaded
			an OpenDJ install package (.zip) file and specify its location using the
			-f/--file option. You can also upgrade your server using the Java Web Start
			version of this tool by visiting the OpenDJ web site at
			www.forgerock.org/opendj.html.</para>
			<para>When using the tool to revert to a previous version you must either
			indicate that you want to revert to the version before the most recent
			upgrade using the -r/--revertMostRecent option or specify the location of a
			reversion archive using the -a/--reversionArchive option.</para>

			<para>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>The <command>upgrade</command> command thus performs only part of the
			upgrade process, which includes the following phases for a single
			server.</para>

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

			<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>
			</refsect1>
			<refsect1>
			<title>Options</title>
			<para>The following options are supported.</para>
			<variablelist>
			<varlistentry>
			<term><option>-a, --reversionArchive {directory}</option></term>
			<term><option>--force</option></term>
			<listitem>
			<para>Directory where reversion files are stored. This should be one of
			the child directories of the 'history' directory that is created when the
			upgrade tool is run.</para>
			<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> option.</para>
			</listitem>
			</varlistentry>
			<varlistentry>
			<term><option>-f, --file {file}</option></term>
			<term><option>--ignoreErrors</option></term>
			<listitem>
			<para>Specifies an existing server package (.zip) file to which the
			current build will be upgraded using the command line version of this
			tool</para>
			</listitem>
			</varlistentry>
			<varlistentry>
			<term><option>-r, --revertMostRecent</option></term>
			<listitem>
			<para>The installation will be reverted to the state before the most
			recent upgrade</para>
			<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>
			@@ -94,21 +129,20 @@
			<varlistentry>
			<term><option>-n, --no-prompt</option></term>
			<listitem>
			<para>Use non-interactive mode. If data in the command is missing, the
			user is not prompted and the tool will fail</para>
			<para>Use non-interactive mode. Prompt for any required information
			rather than fail.</para>
			</listitem>
			</varlistentry>
			<varlistentry>
			<term><option>-Q, --quiet</option></term>
			<listitem>
			<para>Run setup in quiet mode. Quiet mode will not output progress
			information to standard output</para>
			<para>Use quiet mode.</para>
			</listitem>
			</varlistentry>
			<varlistentry>
			<term><option>-v, --verbose</option></term>
			<listitem>
			<para>Use verbose mode</para>
			<para>Use verbose mode.</para>
			</listitem>
			</varlistentry>
			</variablelist>
			@@ -119,13 +153,13 @@
			<varlistentry>
			<term><option>-V, --version</option></term>
			<listitem>
			<para>Display version information</para>
			<para>Display version information.</para>
			</listitem>
			</varlistentry>
			<varlistentry>
			<term><option>-?, -H, --help</option></term>
			<listitem>
			<para>Display usage information</para>
			<para>Display usage information.</para>
			</listitem>
			</varlistentry>
			</variablelist>
			@@ -141,7 +175,15 @@
			</listitem>
			</varlistentry>
			<varlistentry>
			<term>> 0</term>
			<term>2</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>
			<para>See the error message or the log for details.</para>
			</listitem>
			</varlistentry>
			<varlistentry>
			<term>Other</term>
			<listitem>
			<para>An error occurred.</para>
			</listitem>
			@@ -150,29 +192,77 @@
			</refsect1>
			<refsect1>
			<title>Examples</title>
			<para>The following example demonstrates upgrade without interaction.</para>
			<screen>$ ./OpenDJ/upgrade -f ~/Downloads/OpenDJ-<?eval ${docTargetVersion}?>.zip -n
			See
			/var/.../opends-upgrade-5650414945123366149.log
			for a detailed log of this operation.
			<para>The following example shows the upgrade process for OpenDJ directory
			server installed from the cross-platform (.zip) delivery.</para>

			Initializing Upgrade ..... Done.
			Calculating Schema Customizations ..... Done.
			Calculating Configuration Customizations ..... Done.
			Backing Up Files ..... Done.
			Upgrading Components ..... Done.
			Preparing Customizations ..... Done.
			Applying Configuration Customizations ..... Done.
			Verifying Upgrade ..... Done.
			Cleaning Up ..... Done.
			Recording Upgrade History ..... Done.
			See /path/to/OpenDJ/history/log for a detailed installation history.
			QuickUpgrade Completed Successfully. The OpenDJ installation at
			/path/to/OpenDJ has now been upgraded to version OpenDJ <?eval ${docTargetVersion}?> (Build ID:
			YYYYMMDDhhmmssZ).
			<!--
			Intentionally not using <?eval ${stableServerVersion}?> instead of 2.4.6:

			See /var/.../opends-upgrade-5650414945123366149.log
			for a detailed log of this operation.
			</screen>
			Once the ${stableServerVersion} has moved to the new file name,
			the directory names will change, so 2.4.6 is not a variable here,
			but instead an example that should be common for the first release
			with the new upgrade command.

			Perhaps people will forgive details missing in this upgrade that happened
			after the example was run.
			-->

			<screen>$ cd /path/to
			$ ls
			OpenDJ-2.4.6
			$ ./OpenDJ-2.4.6/bin/stop-ds --quiet
			... msg=The backend userRoot is now taken offline
			... msg=The Directory Server is now stopped
			$ zip -rq OpenDJ-backup.zip OpenDJ-2.4.6
			$ unzip -q ~/Downloads/OpenDJ-<?eval ${docTargetVersion}?>.zip
			$ cp -r opendj/* OpenDJ-2.4.6/
			$ rm -rf opendj
			$ mv OpenDJ-2.4.6 opendj
			$ ./opendj/upgrade --no-prompt

			>>>> OpenDJ Upgrade Utility

			* OpenDJ will be upgraded from version 2.4.6.8102 to <?eval ${docTargetVersion}?>.<replaceable>revision</replaceable>
			* See '/path/to/opendj/upgrade.log' for a detailed log of this operation

			>>>> Preparing to upgrade

			OpenDJ <?eval ${docTargetVersion}?> modified the default configuration of the 'isMemberOf' virtual
			attribute so that it is included with group entries. This was done in order
			to make it easier for users to determine which groups a 'nested' group
			belongs to.
			Do you want to make this configuration change? (yes/no) yes

			The upgrade is ready to proceed. Do you wish to continue? (yes/no) yes


			>>>> Performing upgrade

			Fixing de-DE collation matching rule OID............................ 100%
			Updating password policy configurations............................. 100%
			Updating audit log publisher configuration.......................... 100%
			Adding 'etag' virtual attribute schema.............................. 100%
			Configuring 'etag' virtual attribute................................ 100%
			Configuring 'ds-pwp-password-expiration-time' virtual attribute..... 100%
			Updating certificate syntax configuration........................... 100%
			Updating JPEG syntax configuration.................................. 100%
			Updating country string syntax configuration........................ 100%
			Modifying filter in 'isMemberOf' virtual attribute configuration.... 100%
			Updating dictionary password validator configuration................ 100%
			Updating attribute value password validator configuration........... 100%
			Adding PBKDF2 password storage scheme configuration................. 100%
			Replacing schema file '02-config.ldif'.............................. 100%
			Archiving concatenated schema....................................... 100%

			>>>> OpenDJ was successfully upgraded from version 2.4.6.8102 to <?eval ${docTargetVersion}?>.<replaceable>revision</replaceable>

			* See '/path/to/opendj/upgrade.log' for a detailed log of this operation
			$ ./opendj/bin/start-ds --quiet
			$ </screen>

			<para>Native packages (.deb, .rpm) perform more of the upgrade process,
			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>
			</refsect1>
			</refentry>