1. Ingeniería

Upgrading to AEM 6.0
Upgrading to AEM 6.0
Overview / Adobe Experience Manager / Adobe Experience Manager 6.0 / Deploying and Maintaining /
In this section we cover upgrading an AEM 5.x installation to AEM 6.0:
• Upgrade Overview
• In-Place Upgrade
• Migrating the Repository to Oak
• Troubleshooting
For more information about upgrading and about the new Oak repository see the following subpages:
UPGRADE OVERVIEW
There are two distinct steps to doing a full upgrade:
1. In-Place Upgrade: Drop in the new jar file in place of the original one in your <aem-install> directory,
right next to your existing crx-quickstart directory) and launch it. This upgrades the system, but leaves
the existing CRX 2 repository as-is.
2. Migrating the Repository to Oak: Once the in place upgrade is complete, you can optionally migrate
the existing CRX 2 repository to the new Jackrabbit Oak-based CRX 3 repository.
IN-PLACE UPGRADE
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 planning
your upgrade throroughly. For guidance on this, see Planning Your Upgrade.
1.
Enable INFO logging for the error and upgrade logs. This can be done by:
2.
1. Going to AEM Configuration Manager located at http://localhost:4502/system/console/configMgr
2. Pressing the + button under Apache Sling Logging Logger Configuration
3. Creating new factory configuration that will log INFO events for upgrade.log and error.log. For more
info, see Logging.
Run the following maintenance tasks:
• Workflow purge
• Consistency check
• Traversal check
This step is not mandatory but is recommended in order to ensure repository consistency before the
upgrade.
3.
4.
5.
Remove the Geometrixx sample packages and users. For a complete list of all the Geometrixx
packages, see Removing the Geometrixx Sites.
In case this step is carried out, the error.log file will show messages related to the deleted Geometrixx
users. These messages have no impact on the upgrade and should be ignored.
Shutdown the AEM 5 instance.
Replace the quickstart with the AEM 6 jar.
6.
Run the jar and wait for the upgrade to finish.
CAUTION
If you plan on running AEM 6 with a CRX 2 backend, you can simply run the jar at this
point. However, note that for all upgrades from versions up to and including AEM 5.5
this needs to be explicitly stated via the "crx2" runmode option when the AEM 6.0 jar is
first started. To do this, run the quickstart with the following command:
java -jar aem-quickstart.jar -r crx2
If the runmode is not specified, the AEM 6.0 instance will start with a new CRX 3
repository instead of the existing CRX 2 one.
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 1
Created on 2015-02-06
Upgrading to AEM 6.0
7.
Check that the upgrade was successful by confirming that:
• The upgrade.log shows that the process was finished:
*INFO* [FelixStartLevel] com.adobe.cq.upgradesexecutor.Activator UPGRADE FINISHED: 6
CodeUpgradeTasks executed (out of 6), total time about 32 seconds
• error.log shows an "FrameworkEvent STARTED" event:
*INFO* [FelixDispatchQueue] org.apache.felix.framework FrameworkEvent STARTED
• Check that the value for System Start Level is 30 in the System Information console. The console
can be reached at http://localhost:4502/system/console/vmstat
• All the bundles and workflows are in place.
CAUTION
Before proceeding to migrate, note that the way custom LoginModules are configured for
authentication at the repository level has fundamentally changed in Apache Oak.
In AEM 5.6.1 configuration was placed in the repository.xml file, while from AEM 6.0 onwards it is
done in the Apache Felix JAAS Configuration Factory service via the Web Console.
Therefore, any existing configurations will have to be re-created for Apache Oak after the
migration.
For more information, see Authentication with the External Login Module.
For an example of LoginModule configuration in AEM 6.0, see Configuring LDAP with AEM 6.0.
MIGRATING THE REPOSITORY TO OAK
Since AEM 6.0, the backend has moved to OAK in an effort to enhance scalability and performance of the
content repository. For more info on the architectural concepts of Apache OAK, see Introduction to OAK.
Adobe provides a tool that can be used to migrate the repository to the new OAK implementation. It can be
downloaded here:
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 2
Created on 2015-02-06
Upgrading to AEM 6.0
There are two options for the storage backend used by Oak:
• TarMK: A microkernel that uses the Tar persistence system for storage.
• MongoMK: A microkernel that uses MongoDB for storage.
Migration Prerequistes
•
•
Minimum Required Java version: The migration tool only works with Java versions 7 and up.
Upgraded Instance: Before migrating, make sure you have performed an in-place upgrade to AEM 6.0
by following the procedure described above.
Migrating to TarMK
1.
First, go to the Web Bundles console at http://localhost:4502/system/console/bundles, then search for
and delete the com.day.crx.sling.server bundle.
Once the bundle has been deleted, shutdown the AEM instance.
2.
Place the migration tool in the <aem-install> folder and run it with the following parameters:
java -jar crx2oak.jar [source repository] [target repository]
Where:
• The source is the CRX repository that needs to be migrated. If you are running it from within the
<aem-install> folder, this would be crx-quickstart/repository.
• The target is the resulting TarMK repository to be created.
During the migration, the source repository should not be accessed by another client. The
configuration is read from the repository.xml file within the source directory.
The target repository is the filesystem path to the new TarMK repository folder which will be created
automatically if it does not exist.
The command should look like this:
java -jar crx2oak.jar crx-quickstart/repository oak-repository
In this example, the migrated TarMK repository will be created in a folder called oak-repository.
3.
4.
5.
After the migration has finished, backup the AEM 5 data store and the newly created AEM 6 node store
by copying them outside the installation folder. The folders that need to be copied are:
1. crx-quickstart/repository/repository/datastore
2. oak-repository/segmentstore
Delete the entire crx-quickstart folder.
Re-create the crx-quickstart folder with additional configuration for setting the data store and node store
for AEM 6:
• Create the crx-quickstart/install folder.
• In the install folder, create a file called
org.apache.jackrabbit.oak.plugins.blob.datastore.FileDataStore.cfg
• Edit the file and add these configuration options:
path=./crx-quickstart/repository/datastore
minRecordLength=4096
• In the same folder, create a file called
org.apache.jackrabbit.oak.plugins.segment.SegmentNodeStoreService.cfg
• Add the following configuration option:
customBlobStore=true
NOTE
The above configuration example is valid for configuring AEM 6 with a File Data Store.
For more info on other data store options and configurations, see Configuring Node
Stores and Data Stores in AEM 6.
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 3
Created on 2015-02-06
Upgrading to AEM 6.0
6.
Run the quickstart jar and stop it again after it has started.
7.
Move the data store and segment store to the new installation. In order to do this, you need to:
1. Delete all the contents of <aem-install>/crx-quickstart/repository
2. Copy the migrated datastore and segmentstore folders from the folder you've used for the target
repository in step 2 to <aem-install>/crx-quickstart/repository
Start AEM.
8.
Migrating to MongoDB
1.
Make sure that MongoDB is installed and an instance of mongod is running. For more info, see
Installing MongoDB.
2.
Copy the AEM 6 jar into a separate folder.
3.
In the new location, create the Data Store and Node Store configuration needed for the MongoDB
migration:
• Create the crx-quickstart/install folder.
• In the install folder, create a file called
org.apache.jackrabbit.oak.plugins.blob.datastore.FileDataStore.cfg
• Edit the file and add these configuration options:
path=./crx-quickstart/repository/datastore
minRecordLength=4096
• In the same folder, create a file
called org.apache.jackrabbit.oak.plugins.document.DocumentNodeStoreService.cfg
• Add the following configuration option:
customBlobStore=true
Start the AEM 6 jar with a MongoMK backend by running:
4.
java -jar cq-quickstart-6.0.0.jar -r crx3,crx3mongo -Doak.mongo.uri=mongodb://
remoteserver:27017 -Doak.mongo.db=aem-author
Where:
• -r is the backend runmode. In this example, it will start with Mongo support.
• -Doak.mongo.uri is used to specify the location of the Mongo server and the database name.
NOTE
Both AEM and the repository migration tool use 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 synthax, see Connection String URI Format.
5.
6.
Wait for the instance to start up, and then shut it down. After it has been shut down, prepare the
migration by:
• Deleting the contents of the crx-quickstart/repository folder
• Deleting the aem-author Mongo database. This can be done from the Mongo shell, by running:
use aem-author
db.dropDatabase()
• Moving the crx-quickstart/repository/repository/datastore folder from the AEM 5 installation to the
AEM 6 folder.
Run the crx2oak upgrade tool and wait for the process to complete:
java -jar crx2oak.jar [source CRX 2 repository] mongodb://remoteserver:27017/aem-author
7.
8.
Restart AEM.
Test your new installation.
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 4
Created on 2015-02-06
Upgrading to AEM 6.0
Using the helper script to migrate the repository
A helper script is also provided in the quickstart package in order to facilitate the use of the migration tool. It
can be found in the archive provided above under the name crx2oak.sh
• Usage for migrating to TarMK:
crx2oak.sh [repository location]
The repository location is the file system path to the CRX2 repository that needs to be converted to Oak.
Thus, a correct form to invoke the script would be:
crx2oak.sh /srv/cq/crx-quickstart/repository
• Usage for migrating to MongoMK:
crx2oak.sh -m [location of Mongo database]
The location of the Mongo database must be specified in Connection String URI format.
Again, a correct way to invoke the script for a MongoMK migration is:
crx2oak.sh -m mongodb://serverhost:27017/aem-author
The script can be run with several optional parameters:
-s
Starts a CQ instance after the migration.
-j
Specifies a custom crx2oak.jar to use for the
migration.
-q
Specifies a custon quickstart.jar to use when
building the initial crx-quickstart folder.
-p
The port to use for CQ startup detection. Useful
for instance when the quickstart is configured to
start on a different port due to its name, e.g. cqauthor-8080.jar.
-i
Backs up the previous crx-quickstart folder by
renaming it to crx2-quickstart and replaces it with
the newly generated instance.
-l
Indicates from where to copy a license.properties
file into the current working directory in order to
automatically start the instance used for migration;
if a license.properties file exists in the current folder
this option is not needed.
-h
Shows usage information for the script.
NOTE
The script will not work for setups with custom Data Store configurations. For such cases, please
run crx2oak.jar manually, as described above.
TROUBLESHOOTING ISSUES AFTER THE UPGRADE
•
•
Issues with starting and shutting down AEM after the upgrade: After upgrading to the CRX 3
backend, AEM sometimes fails to start or shut down properly on systems with Java 6 installed. To work
around this, add the following parameters to the JVM when starting AEM:
-XX:+UnlockDiagnosticVMOptions -XX:+UnsyncloadClass
Error messages: The following error messages will appear in the error.log file after the upgrade and can
be safely ignored:
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 5
Created on 2015-02-06
Upgrading to AEM 6.0
*ERROR* [OsgiInstallerImpl] org.apache.jackrabbit.vault.fs.impl.io.DocViewSAXImporter Error while
applying access control content. javax.jcr.security.AccessControlException: Principal operators
does not exist.
*ERROR* [OsgiInstallerImpl] com.adobe.granite.installer.factory.packages.impl.PackageTransformer
Error while processing uninstall task.
com.day.jcr.vault.packaging.PackageException:
org.apache.jackrabbit.vault.packaging.PackageException: Unable to uninstall package. No snapshot
present.
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 6
Created on 2015-02-06