某些 Creative Cloud 应用程序、服务和功能在中国不可用。
Вы находитесь на странице справочной информации о версии:
- 6.5
- 6.4
- 6.3
- 6.2
- Предыдущие версии
In this section we cover upgrading an AEM installation to AEM 6.2:
- Upgrade Planning
- Upgrading Steps for JAR Based Installations
- Upgrading Steps for Application Server Installations
- Analyzing Issues with the Upgrade
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.
Примечание.
After you perform the upgrade, you need to recover your ContextHub configurations.
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.
Примечание.
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.
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 article:
It is also recommended you perform data store consistency check at the following location: http://<serveraddress:serverport>/system/console/repositorycheck
-
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.
-
Disable any custom authentication mechanisms. See the section under Disabling Custom Login Modules for guidance on how to achieve this.
-
Примечание.
In case you have customized Assets content, see Preparing Assets Customizations for Upgrade.
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>
Примечание.
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.
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.
Примечание.
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:
- 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.
-
java -jar aem-quickstart-6.2.0.jar -v -x crx2oak
-
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
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.config file that has been generated under crx-quickstart/install. A properly formatted path should look like this:
path=./crx-quickstart/repository/repository/datastore
Примечание.
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:
-
java -Xmx4096m -XX:MaxPermSize=2048M -jar aem-quickstart-6.2.0.jar -v -x crx2oak -xargs -- -o migrate
Примечание.
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.
Примечание.
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
Примечание.
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.
-
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.
Внимание.
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.
java -jar aem-quickstart-6.2.0.jar -r author,crx3,crx3mongo,nosamplecontent -Doak.mongo.uri=mongodb://remoteserver:27017 -Doak.mongo.db=aem-author
Внимание.
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.
Примечание.
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.
Примечание.
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.
-
Примечание.
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.
-
Once the upgrade is finished, run the same test suite that you used on the source instance, to validate the upgrade.
Примечание.
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.
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.
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
-
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
Примечание.
For more information on JBoss tasks, see the documentation page.
-
java -jar crx2oak.jar crx-quickstart/repository/ crx-quickstart/oak-repository
Примечание.
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
-
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
find crx-quickstart/launchpad -type f -name "org.apache.sling.launchpad.base.jar*" -exec rm -f {} \;rm -f crx-quickstart/launchpad/felix/bundle0/BootstrapCommandFile_timestamp.txt
- The launchpad/startup folder. You can delete it by running the following command in the terminal:
-
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.config
- org.apache.jackrabbit.oak.plugins.blob.datastore.FileDataStore.config
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
Then add the following lines to org.apache.jackrabbit.oak.plugins.blob.datastore.FileDataStore.config:
path=./crx-quickstart/repository/datastore minRecordLength=4096
-
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
-
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>
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>
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:
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).
If you require asset IDs for a subset of your entire assets, use the migrateAssetsAtPath API.
For all other purposes, use the migrateAllAssets() API.
If the site being upgraded used the social communities capability, then visit Upgrading to AEM Communities 6.2 for additional upgrade information.
Custom Search Facets require some manual adjustments after the upgrade in order to function properly. For more details, see Upgrading Custom Search Forms.
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.
Service Pack 1 upgrades fail for AEM 6.2 instances that are integrated with Adobe Campaign.
For Adobe Campaign integration, the campaign-remote user will receive a rep:password as part of that configuration process. After this password is set, installing cq-mcm-content or any service pack or cumulative fix pack containing cq-mcm-content will lead to an error due to the the authorizable property rep:password may not be removed, and will cause the 6.2 Service Pack 1 upgrade to fail. To work around this issue, remove the campaign-remote user in the user administration console before installing the content package.
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.
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.
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.
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.
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.
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.
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
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.