Upgrading to AEM 6.1

You are reading the AEM 6.1 version of Upgrading to AEM 6.1.

This documentation is also available for the following versions: AEM 6.3 AEM 6.2 AEM 6.0

Note

AEM 6.1 introduces the next generation Java Content Repository that the documentation refers to as Apache Jackrabbit Oak or CRX3. It comes with many significant improvements, mainly with regards to scalability, performance and optimizations for AEM capabilities. For more info, please see Introduction to the AEM Platform.

Adobe removes the CRX2 compatibility option in the 6.1 release of Adobe Experience Manager. The upgrade process of AEM 6.1 contains the requirement to switch to the Oak-based repository during the update, that can be used for customers that want to update from AEM 5.x or AEM 6.0 using the compatibility option.

Learn more about the available persistence options of Oak. Current info for AEM 6.0 is available on Recommended Deployments.

In this section we cover upgrading an AEM installation to AEM 6.1:

You can also find detailed information on the options and parameters available for the CRX2Oak migration tool at this location:

Using the CRX2Oak Migration Tool

For easier reference to the AEM instances involved in the procedures, the following terms are used throughout this article:

The source instance is the CQ/AEM instance that you are upgrading from.
The target instance is the one that you are upgrading to.

Note

After you perform the upgrade, you need to recover your ContextHub configurations.

Upgrading Steps for JAR Based Installations

Preparing the source instance

Even though the upgrade process has been designed to be as simple as possible, any upgrade of a production environment is a significant task. For this reason, we recommend that you invest time in preparing your upgrade thoroughly. More specifically, make sure you perform the items in this checklist:

Create a full backup on the instance that is going to be upgraded. For info on how to do this, consult the Backup and Restore documentation.

Cleanup any content that is not needed, like archive workflows. For specific info on deleting workflows, see Workflow purge.

Check the consistency of the source content repository, and fix any inconsistencies you might find. For guidance on how to perform these consistency checks, please read the following articles:

It is also recommended you perform data store consistency check at the following location: http://<serveraddress:serverport>/system/console/repositorycheck

Run a test suite that validates your instance, including any custom applications. After the instance and the test suite have been validated, you can reuse the test suite later on in the process to validate the upgrade.

Make sure that any hostname based mappings under /etc/map (or any other similar configurations) are compatible with the environment in which you will be testing the upgraded instance.

Disable any custom authentication mechanisms. See the section under Disabling Custom Login Modules for guidance on how to achieve this.

Prepare any upgrade customizations that might be required for your custom applications.

Stop the instance.

Archive then delete the log files found under crx-quickstart/logs in order to get a clean set of logs for the upgrade.

Cleanup the crx-quickstart/install folder, leaving only packages that you want to install on the next startup.

Disabling Custom Login Modules

The way custom LoginModules are configured for authentication at the repository level has fundamentally changed in Apache Oak.

In AEM versions that used CRX2 configuration was placed in the repository.xml file, while from AEM 6.1 onwards it is done in the Apache Felix JAAS Configuration Factory service via the Web Console.

Therefore, any existing configurations will have to be disabled and re-created for Apache Oak after the upgrade.

To disable the custom modules defined in the JAAS configuration of repository.xml, you need to modify the configuration to make use of default LoginModule, as in this example:

<Security>
            ....
         <!--
                Use LoginModule authenticating against repository itself
                -->
                <LoginModule class="com.day.crx.core.CRXLoginModule">
                    <param name="anonymousId" value="anonymous"/>
                    <param name="adminId" value="admin"/>
                    <param name="disableNTLMAuth" value="true"/>
                    <param name="tokenExpiration" value="43200000"/>
                    <!-- param name="trust_credentials_attribute" value="d5b9167e95dad6e7d3b5d6fa8df48af8"/ -->
                </LoginModule>
        </Security>

Code samples are intended for illustration purposes only.

Note

For more information, see Authentication with the External Login Module.

For an example of LoginModule configuration in AEM 6, see Configuring LDAP with AEM 6.

Preparation of the AEM Quickstart jar file

Get the appropriate AEM quickstart jar file and place it next to the crx-quickstart folder of the source instance.

Next, verify that your Java Virtual Machine (JVM) and its parameters are appropriate for this new quickstart jar. Depending on your requirements or the deployment type, you will need to run a different version of the JVM that you used for your old CQ or AEM version, or use different JVM parameters.

Content repository migration

Since AEM 6.1 removes support for CRX2, you must first migrate the repository to Apache Oak before upgrading if you are using an AEM 5.x or AEM 6.0 with a CRX2 backend installation.

Adobe provides a tool that can be used to migrate the repository to the new OAK implementation. It is provided as part of the quickstart package.

The actual migration is performed using the standard AEM 6.1 quickstart jar file, executed with a new -x crx2oak option which executes the crx2oak tool in order to simplify the upgrade and make it more robust.

There are some prerequisites that need to be satisfied before running the migration:

Note

If the source instance already is already running Oak, this section can be skipped.

Migration Prerequistes

Minimum Required Java version: The migration tool only works with Java versions 7 and up.
Upgraded Instance: If you are upgrading from a version older than 5.4, make sure you have performed an in-place upgrade to AEM 6.0 by following the procedure described above.
CRX2Oak Version: Make sure you are using at least version 1.3.4 or newer (1.4.2 recommended) of the CRX2Oak Migration Tool.

SNS Nodes

The migration does not currently support migrations from CQ 5.x repositories that contain SNS (same name sibling) nodes. To work around this, make sure you remove all the SNS nodes before migration.

Please refer to this helpx article for more information on how to detect and remove the SNS nodes.

Once these conditions are met, the exact procedure you need to follow is:

Unpack the quickstart jar by running:

java -jar aem-quickstart-6.1.0.jar -unpack

Code samples are intended for illustration purposes only.

Run the quickstart with the following parameters to prepare for the migration:

java -jar aem-quickstart-6.1.0.jar -v -x crx2oak

Code samples are intended for illustration purposes only.

This step will call a helper utility called crx2oak-quickstart-extension.jar and will generate a file called crx2oak.properties under crx-quickstart/crx2oak/.

Review the newly generated file and edit its properties in case different values are needed for your migration requirements.

After the file has been reviewed, run the jar with the same parameters a second time to generate the OSGi configurations needed for the data migration:

java -jar aem-quickstart-6.1.0.jar -v -x crx2oak

Code samples are intended for illustration purposes only.

On Windows deployments that use the File DataStore, the OSGi configuration needs to be edited at this point so that the path parameter uses forward slashes ("/") as a file separator.

In order to do this, you need to edit the org.apache.jackrabbit.oak.plugins.blob.datastore.FileDataStore.cfg file that has been generated under crx-quickstart/install. A properly formatted path should look like this:

path=./crx-quickstart/repository/repository/datastore

Code samples are intended for illustration purposes only.

Note

If the source instance is already using or is required to use an Amazon S3 Data Store you need to perform additional steps described before running the migrate operation. For more information on the steps that need to be perfomed, please consult these pages:

Run the migrate operation which will migrate your data from CRX2 to CRX3:

java -Xmx4096m -XX:MaxPermSize=2048M -jar aem-quickstart-6.1.0.jar -v -x crx2oak -xargs -- -o migrate

Code samples are intended for illustration purposes only.

However, if you want to use the additional options that CRX2Oak offers, you need to run the tool directly like this:

java -Xmx4096m -XX:MaxPermSize=2048M -jar crx-quickstart/opt/helpers/crx2oak/crx2oak.jar [OPTIONS] crx-quickstart/repository [target repository]

Code samples are intended for illustration purposes only.

The target repository depends on the node store implementation:

For TarMK, the target repository can be omitted;
For MongoMK repositories you need to use the URI referencing the Mongo database instance. A typical example is mongodb://localhost:27017/aem-author

It is also highly recommended you use the tool with memory mapped operations support by using the --mmap parameter. This will greatly improve migration performance.

Note

For the full list of options and parameters supported by crx2oak, see Using the CRX2Oak Migration Tool.

Note

Make sure you tune the JVM memory options according to the size of the repository you are migrating.

This command will output explanatory instructions. Make sure you monitor them during the migration.

When the migration is finished, depending on your setup, the crx2oak-quickstart-extension will indicate which storage-related run modes you need to use to start the new AEM instance to perform the upgrade (like -r crx3,crx3tar for Tar based storage or -r crx3,crx3mongo for Mongo storage). Do note that these are only the storage-related run modes. In general you need to specify more run modes on the new instance.

Also note that the crx2oak quickstart extension renames the sling.options.file which stores the Sling run modes. Because of this, you need to specify any custom run modes again at the next startup.

The OSGi configurations prepared by crx2oak are placed in the crx-quickstart/install folder where the quickstart will make use of them. If required, they can be modified there before starting the new AEM instance.

Note

To identify the exact version of the crx2oak tools used for the migration, running the quickstart with the -x crx2oak option will output their SHA1 checksums. These should be mentioned in support requests to identify the exact versions used.

If you are migrating from an AEM 5.6.1 or 6.0 with a CRX2 backend, you need to clean up the repository folder by deleting redundant data that is left over after the migration.

You can do this by deleting everything under crx-quickstart/repository, except for these particular folders:

crx-quickstart/repository/index
crx-quickstart/repository/segmentstore
crx-quickstart/repository/repository/datastore

Note

In case your migration configuration is set to migrate the binary data to an external Data Store such as MongoDB, you can safely delete the crx-quickstart/repository/repository/datastore folder as well.

Performing the AEM Upgrade

At this point, the actual AEM upgrade can happen. In order to perform the upgrade, you need to:

Start the AEM 6.1 quickstart jar with the appropiate runmodes. These are designated by adding the -r option to the quickstart command.

The runmodes you can use are:

author or publish, to designate the purpose of the instance.
The storage related run modes, indicated by crx2oak as shown above. In case you are upgrading from a 6.0 instance and you did not perform a content migration, you can use the same run modes you used on the old instance. The runmodes you can use are:
- -r crx3,crx3tar for TarMK
- -r crx3,crx3mongo for MongoMK
The nosamplecontent runmode in order to make sure the instance is production ready and starts without the demo geometrixx apps.
Any other custom run modes that the old instance was using or that the new instance needs.

Caution

Take notice of nosamplecontent when starting the instance. Omitting this run mode will install the geometrixx demo apps even if they were not installed prior to the upgrade.

Because of this, make sure you also edit any startup scripts that may be running in your production environment to make use of this run mode.

A typical quickstart launch command should look like this:

java -jar aem-quickstart-6.1.0.jar -r author,crx3,crx3mongo,nosamplecontent -Doak.mongo.uri=mongodb://remoteserver:27017 -Doak.mongo.db=aem-author

Code samples are intended for illustration purposes only.

Caution

Setting the run modes is also possible by setting the sling.run.modes property in the crx-quickstart/conf/sling.properties file. As this overrides command line options you need avoid having both in place.

Note

Make sure you perform the upgrade by manually running the quickstart.jar as described above. Running any of the startup scripts under crx-quickstart\bin\ will trigger a new installation instead of an upgrade.

Note

The above command shows the quickstart being started with MongoDB persistence. AEM uses a MongoDB connection string to specify the location, the port and the name of the database that needs to be used. For more information on the syntax, see Connection String URI Format.

Watch the upgrade.log and error.log under crx-quickstart/logs to monitor the process of the upgrade.

Once the upgrade is finished, the AEM homepage will be shown.

Note

During the upgrade, AEM returns an HTTP 503 status for all requests except for those under http://<serveraddress:port>/system/console.

The OSGi console is available early at /system/console in the AEM 6.1 startup phase. You can use it for monitoring or troubleshooting.

Once the upgrade is finished, run the same test suite that you used on the source instance, to validate the upgrade.

Note

Packages in the install folder in the repository will be reinstalled after the upgrade.

Because of this, make sure to not make any changes to the instance that might overlap with packages in that folder before the upgrade.

Manually updating the helper JARs

These files can be manually upgraded, if needed, by manually replacing them with newer versions after unpacking the quickstart. Their location in the AEM installation folder is:

<aem-install>/crx-quickstart/opt/extensions/crx2oak-quickstart-extension.jar
<aem-install>/crx-quickstart/opt/helpers/crx2oak/crx2oak.jar

When run, the crx2oak-quickstart-extension.jar will display its version and the SHA-1 checksum, together with the same information for the crx2oak.jar. If you manually upgrade these JARs and want to report bugs related to repository migration please provide the versions and SHA-1 checksums of the files that you used to support.

The newest version of crx2oak can be downloaded from the public Adobe repository at this location:

https://repo.adobe.com/nexus/content/groups/public/com/adobe/granite/crx2oak/

The list of changes and fixes for the newest version can be found in the CRX2Oak Release Notes.

Upgrading Steps for Application Server Installations

This section describes the procedure that needs to be followed in order to update AEM for Application Server installations.

All the examples in this procedure use JBoss as the Application Server and imply that you have a working version of AEM already deployed. The procedure is meant to document upgrades performed from AEM version 5.6 to 6.1

First, start JBoss. In most situations, you can do this by running the standalone.sh startup script, by running this command from the terminal:

jboss-install-folder/bin/standalone.sh

Code samples are intended for illustration purposes only.

Note

For more information on JBoss tasks, see the documentation page.

If AEM 5.6 is already deployed, check that the bundles are functioning correctly by running:

wget http://<serveraddress:port>/cq/system/console/bundles

Code samples are intended for illustration purposes only.

Next, undeploy AEM 5.6:

rm jboss-install-folder/standalone/deployments/cq.war

Code samples are intended for illustration purposes only.

Stop JBoss.

Now, migrate the repository using the crx2oak migration tool:

java -jar crx2oak.jar crx-quickstart/repository/ crx-quickstart/oak-repository

Code samples are intended for illustration purposes only.

Note

In this example, oak-repository is the temporary directory where the newly converted repository will reside.

Before perfroming this step, make sure you have the latest crx2oak.jar version.

Delete the necessary properties in the sling.properties file by doing the following:

Open the file located at crx-quickstart/launchpad/sling.properties;
Remove the following properties and save the file:

sling.installer.dir
felix.cm.dir
granite.product.version
org.osgi.framework.system.packages
osgi-core-packages
osgi-compendium-services
jre-*
sling.run.mode.install.options

Code samples are intended for illustration purposes only.

Remove the files and folders that are no longer necessary. The items you need to specifically remove are:

The launchpad/startup folder. You can delete it by running the following command in the terminal:

rm -rf crx-quickstart/launchpad/startup

Code samples are intended for illustration purposes only.

The base.jar file:

find crx-quickstart/launchpad -type f -name "org.apache.sling.launchpad.base.jar*" -exec rm -f {} \;

Code samples are intended for illustration purposes only.

The BootstrapCommandFile_timestamp.txt file:

rm -f crx-quickstart/launchpad/felix/bundle0/BootstrapCommandFile_timestamp.txt

Code samples are intended for illustration purposes only.

Copy the newly migrated segmentstore to its proper location:

mv crx-quickstart/oak-repository/segmentstore crx-quickstart/repository/segmentstore

Code samples are intended for illustration purposes only.

Copy the datastore as well:

mv crx-quickstart/repository/repository/datastore crx-quickstart/repository/datastore

Code samples are intended for illustration purposes only.

Next, you need to create the folder that will contain the OSGi configurations that will be used with the new upgraded instance.

More specifically, a folder named install needs to be created under crx-quickstart.

Now, create the node store and data store that will be used with AEM 6.1.

You can do this by creating two files with the following names under crx-quickstart\install:

org.apache.jackrabbit.oak.plugins.segment.SegmentNodeStoreService.cfg
org.apache.jackrabbit.oak.plugins.blob.datastore.FileDataStore.cfg

These two files will set AEM to use a TarMK node store and a File data store.

Edit the configuration files to make them ready for use. More specifically:

Add the following line to org.apache.jackrabbit.oak.plugins.segment.SegmentNodeStoreService.config:

customBlobStore=true

Code samples are intended for illustration purposes only.

Then add the following lines to org.apache.jackrabbit.oak.plugins.blob.datastore.FileDataStore.config:

path=./crx-quickstart/repository/datastore
minRecordLength=4096

Code samples are intended for illustration purposes only.

Remove the crx2 runmode by running:

find crx-quickstart/launchpad -type f -name "sling.options.file" -exec rm -rf {} \;

Code samples are intended for illustration purposes only.

You now need to change the run modes in the AEM 6.1 war file. In order to do that, first create a temporary folder that will be housing the AEM 6.1 war. The name of the folder in this example will be temp.

Once the war file has been copied over, extract its contents by running from inside the temp folder:

jar xvf aem-quickstart-6.1.0.war

Code samples are intended for illustration purposes only.

Once the contents have been extracted, go to the WEB-INF folder and edit the web.xml file to change the run modes.

To find the location where they are set in the XML, look for the sling.run.modes string. Once you find it, change the run modes in the next line of code, which by default is set to author:

<param-value>author</param-value>

Code samples are intended for illustration purposes only.

Change the above author value and set the run modes to:

author,crx3,crx3tar

The final block of code should look like this:

<init-param>
<param-name>sling.run.modes</param-name>
<param-value>author,crx3,crx3tar</param-value>
</init-param>
<load-on-startup>100</load-on-startup>
</servlet>

Code samples are intended for illustration purposes only.

Recreate the jar with the modified contents:

jar cvf aem61.war

Code samples are intended for illustration purposes only.

Finally, deploy the new war file:

cp temp/aem61.war jboss-install-folder/standalone/deployments/aem61.war

Code samples are intended for illustration purposes only.

Upgrading AEM Communities

If the site being upgraded used the social communities capability, then visit Upgrading to AEM Communities 6.1 for additional upgrade information.

Upgrading ContextHub

If you were using ContextHub under 6.0 you will need to carry out some additional steps after completing your 6.1 AEM upgrade in order to complete the upgrade of ContxHub and recover ContextHub configurations after upgrading.

Please see the ContextHub documentation for more details.

Analyzing Issues With The Upgrade

This section contains some issue scenarios one might face along the upgrade procedure to AEM 6.1.

These scenarios should help to track down the root cause of issues related to ugprade and should help to identify project or product specific issues.

Repository Migration Failing

The data migration from CRX2 to Oak should be feasible for any scenario starting with source instances based on CQ 5.4. Make sure that you exactly follow the upgrade instructions in this document which include the preparation of the repository.xml, making sure no custom custom authenticator is started via JAAS and the instance has been checked for inconsistencies before starting the migration.

If the migration still fails you can figure out what is the root cause by inspecting the upgrade.log. If the issue is not yet known, please report it to Customer Support.

The Migration Fails If The Installation Path Contain Spaces

If the installation path of the source AEM instance contains a space, the migration will fail. Therefore, make sure that you do not use space in the installation folders or subfolders.

Packages and Bundles Fail to Update

In case packages fail to install during the upgrade, the bundles they contain will not be updated either.

This category of issues is usually caused by data store misconfiguration. They will also appear as ERROR and WARN messages in the error.log.

Since in most of these cases the default login may fail to work, you can use CRXDE directly in order to inspect and find the configuration problems.

Some AEM Bundles are not switching to the active state

In case of bundles not starting up you should check for any unsatisfied dependencies.

In case this problem is present but it is based on a failed package installation which led to bundles not being upgrade they will be deemed incompatible for the new version. For more info on how to troubleshoot this, see Packages and Bundles Fail to Update above.

It is also recommended to compare the bundle list of a fresh AEM 6.1 instance with the upgraded one to detect the bundles that where not upgraded. This will provide a closer scope of what to search for in the error.log.

Custom Bundles not switching to the active state

In case your custom bundles are not switching to the active state it is most likely that there is code that is not importing change API. This will most often lead to unsatisfied dependencies.

API that was removed should be marked as deprecated in one of the pervious releases. You might find instructions about a direct migration of your code in this deprecation notice. Adobe aims for semantic versioning where possible so the versions can indicate breaking changes.

It is also best to check if the change that has caused the problem was absolutely necesarry necessary and revert it if it is not. Also check if the version increase of the package export was increased more than necessary, following strict semantic versioning.

Malfunctioning Platform UI

In case of certain UI functionality that is not working properly after the upgrade, you should first check for custom overlays of the interface. Some structures might have changed and the overlay might need an update or is obsolete.

Next, check for any Javascript errors that can be tracked down to custom added extensions that are hooked to clientlibs. The same can apply for custom CSS that might be causing problems to the AEM layout.

Finally, check for misconfiguration that Javascript might not be able to deal with. This is usually the case with improperly deactivated extensions.

Malfunctioning custom components, templates or UI extensions

In most cases, the root causes for these issues are the same as for bundles that are not started or packages not being installed with the only difference that the issues start occurng when first using the components.

The way to deal with erroneous custom code is to first perfom smoke tests in order to identify the cause. Once you find it, look at the recommendations in this section of the article for ways of fixing them.

Analyzing the error.log and upgrade.log

In most situations the logs need to be consulted for errors in order to find the cause of a problem. However, in case of upgrades it is also necessary to monitor dependency issues as old bundles might not be upgraded properly.

The best way to do this is to strip down the error.log by removing of all messages that are expected to be unrelated to the issue you are facing. You can do this via tool like grep, by using:

grep -v UnrelatedErrorString

Code samples are intended for illustration purposes only.

Some error messages might not be immediately explicative. In this case, looking at the context in which they occur can also help understand where the error was created. You can separate the error using:

grep -B for adding lines before the error;

grep -A for adding lines after.

In a few cases errors can also be found WARN messages as there can be valid cases leading to this state and the application is not always able to decide if this is an actual error. Make sure you consult these messages as well.

Upgrading to AEM 6.1

Upgrading Steps for JAR Based Installations

Preparing the source instance

Disabling Custom Login Modules

Preparation of the AEM Quickstart jar file

Content repository migration

Migration Prerequistes

SNS Nodes

Performing the AEM Upgrade

Manually updating the helper JARs

Upgrading Steps for Application Server Installations

Upgrading AEM Communities

Upgrading ContextHub

Analyzing Issues With The Upgrade

Repository Migration Failing

The Migration Fails If The Installation Path Contain Spaces

Packages and Bundles Fail to Update

Some AEM Bundles are not switching to the active state

Custom Bundles not switching to the active state

Malfunctioning Platform UI

Malfunctioning custom components, templates or UI extensions

Analyzing the error.log and upgrade.log

Search our Website

On this page

Was this helpful?

Any questions?