Upgrading to AEM 6.2

You are reading the AEM 6.2 version of Upgrading to AEM 6.2.
This documentation is also available for the following versions:  AEM 6.1  AEM 6.0 

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

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.

Upgrade Planning

Upgrading AEM is an extensive task. Depending on the size of your deployment, planning needs to be undertaken in order to ensure the success of the upgrade. For more information, see Planning Your Upgrade.

Upgrading Steps for JAR Based Installations

Note

Before starting the preparation steps, make sure you run the source instance first by executing it with the java -jar aem-quickstart.jar command. This is required in order to make sure that the quickstart.properties file is generated properly. If it is missing, the upgrade will not work.

Alternatively, you can check whether the file is present by looking under crx-quickstart/conf in the installation folder of the source instance.

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:

  1. 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.

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

  3. 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 article:

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

  4. Check the list of obsolete bundles that will be uninstalled during the upgrade. If your custom applications depend on any of these bundles, contact Adobe Support and ask for compatibility packages for the affected area.

  5. 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.

  6. 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.

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

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

    Note

    In case you have customized Assets content, see Preparing Assets Customizations for Upgrade.

  9. Stop the instance.

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

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

Note

If the source instance is already running Oak, skip the following sections and continue from Performing the AEM Upgrade.

Since the latest versions of AEM 6 remove 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.2 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:

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. For more information, see the 6.0 version of the Upgrade documentation.

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

  1. Unpack the quickstart jar by running:

    java -jar aem-quickstart-6.2.0.jar -unpack
            

    Code samples are intended for illustration purposes only.

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

    java -jar aem-quickstart-6.2.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.

  3. 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.2.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:

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

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

    Code samples are intended for illustration purposes only.

    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.

  5. 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:

  1. Start the AEM 6.2 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.2.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.

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

  3. 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.2 startup phase. You can use it for monitoring or troubleshooting.

  4. 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

The newest version of the CRX2Oak migration tool is available for download from the Adobe Repository at this location:

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.

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.2

  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.

  2. 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.

  3. Next, undeploy AEM 5.6:

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

    Code samples are intended for illustration purposes only.

  4. Stop JBoss.

  5. 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.

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

    1. Open the file located at crx-quickstart/launchpad/sling.properties;
    2. 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.

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

  8. 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.

  9. Copy the datastore as well:

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

    Code samples are intended for illustration purposes only.

  10. 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.

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

    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.

  12. 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.

  13. 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.

  14. You now need to change the run modes in the AEM 6.2 war file. In order to do that, first create a temporary folder that will be housing the AEM 6.2 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.2.0.war
            

    Code samples are intended for illustration purposes only.

  15. 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.

  16. Recreate the jar with the modified contents:

    jar cvf aem62.war
            

    Code samples are intended for illustration purposes only.

  17. Finally, deploy the new war file:

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

    Code samples are intended for illustration purposes only.

Upgrading Assets

Preparing Assets Customizations for Upgrade

Instances that have customized Assets deployments need to be prepared for the upgrade. This is needed to ensure that all customized content is compatible with the new 6.2 node structure.

You can prepare the Assets content by doing the following:

  1. On the instance that needs to be upgraded, open CRXDE Lite by going to http://server:port/crx/de/index.jsp

  2. Go to the following node:

    • /apps/dam/content
  3. Rename the content node to content_backup. You can do this by right clicking the explorer pane in the left hand side of the window and choosing Rename.

  4. Once the node has been renamed, create a new node named content under /apps/dam named content and set its node type to sling:Folder.

  5. Move all the children nodes of content_backup to the newly created content node. You can do this by right clicking each children node in the explorer pane and selecting Move.

  6. Delete the content_backup node.

To generate asset IDs for existing assets, upgrade the assets when you upgrade your AEM instance to run AEM 6.2. This is required to enable the Assets Insights feature. For more details, see Adding Embed code.

To upgrade assets, configure the Associate Asset IDs package in the JMX console. Depending on the number of assets in the repository, migrateAllAssets may take a long time (roughly an hour for 125k assets on TarMK).

file

If you require asset IDs for a subset of your entire assets, use the migrateAssetsAtPath API.

For all other purposes, use the migrateAllAssets() API.

Upgrading AEM Communities

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

Upgrading Custom Search Forms

Custom Search Facets require some manual adjustments after the upgrade in order to function properly. For more details, see Upgrading Custom Search Forms.

Analyzing Issues With The Upgrade

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

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.

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.2 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;

      or

  • 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.

Any questions?

Have a question about this or any other AEM topic? Ask our Community.
Learn more about AEM topics on our help hub.
Was this helpful?

By submitting your feedback, you accept the Adobe Terms of Use.

Thank you for submitting your feedback.