How to Revert a Non-Versioned CRX Instance

There’s one really big drawback to the CQ/CRX package manager…

Imagine you have a application code package with a filter of “/apps/myApp”, which has been built from a recently updated SVN working copy. You want to update your local CRX repository, but you also have current development under way which will be overwritten by the package. Well, in most cases you can remember to make a backup package singling out only your local changes, build that package, install the full code refresh from SVN, and then install your backup package immediately afterward, effectively overlaying your changes/additions on top of an updated code-base. This works, but what if for some reason you forget to back up your local changes in this manner? Once a full package has been installed, there’s no way to go back, right?

Wrong. Actually, CRX uses a data-store that keeps track of transactions within the repository, so it IS possible to revert this data-store to a specific point in time. The caveat is that there is no UI and no tool to do this built into the product, so you have to do it manually. Before you continue, note that this should only be attempted by someone who is EXTREMELY comfortable with the steps detailed below. Altering the data-store in the manner described in this post can terminally damage the instance of CRX on which the operation is being performed, so proceed with extreme caution because………THIS OPERATION IS NOT OFFICIALLY SUPPORTED – IF YOU MESS UP YOU WILL POTENTIALLY LOSE YOUR ENTIRE REPOSITORY!

NOTE: You won’t be able to roll back to the previous day…the default behavior of CRX is to truncate the data-store in a background process overnight for optimization, so act right away if you need to revert!

Prior to shutting down your repository, navigate to: http://{host}:{port}/crx/diagnostic/history.jsp
After logging in (if necessary), click on the link that says “Summary”. It may take a minute or two to load, but once it does, you can find the exact time-stamp of the package install from which you wish to revert. You’ll need to copy this time-stamp, and put it somewhere for reference (a txt file will do). Now you can shut down the repository.

Next, you need to convert the time-stamp to EPOCH format. There are web-apps that convert to this format online, the one I have used is: http://www.epochconverter.com/. Convert your time-stamp to EPOCH format, and save the converted time-stamp into your reference txt file.

Now you’ll need a hex editor application so that you can inspect the contents of the data-store file, which is a .tar file, and so it is pure binary. I used Hex Editor for Mac, but most likely any hex editor will do. You will need to open the hex editor and open the file located at /path/to/crx-quickstart/repository/workspace/crx.default/data_00000.tar (this may be named slightly differently, but it will be in format “data_xxxxx.tar”). This file holds all the data within your repository, so tread with caution! Use the hex editor’s “Find” option, and you should be able to locate the location of the first instance of your EPOCH formatted time-stamp. Make a note of the HEX value of the location of this (you can use your same txt file if you want), and you’re done with this step.

You’ll need to convert the HEX value you just found into a DECIMAL value. This converted value will be used to truncate your .tar file in the next step, so make sure you use an accurate converter…the difference of a byte can be the difference between a corrupt repository and a successful recovery. I used the following online converter: http://www.statman.info/conversions/hexadecimal.html, and it did the trick.

Next, you’ll need to run a Unix/Linux command that will truncate the data_00000.tar file:

dd if=/path/to/file/data_00000.tar of=/path/to/file/data_00000_copy.tar bs={convertedDecimalByteLocation} count=1

(note: the curly-braces should NOT be a part of the command itself…they are only there to indicate that this option is a variable specific to your scenario)

…”if” stands for “input file”, “of” for “output file”, “bs” (I believe) stands for “byte size”, and “count” is the number of partitions. After running this command, you should have a file called “data_00000_copy.tar” sitting next to the “data_00000.tar” file. Check the sizes of the files, the copy should be smaller than the original…the difference will depend on how far back you are trying to revert.

Now move the original “data_00000.tar” file somewhere safe OUTSIDE your “crx-quickstart” directory. This can be used to recover your instance if something went wrong with the truncation process. Once you’ve moved the original file, remove the “_copy” portion of the truncated file’s name.

We’re on the home stretch…next you just have to delete the event journal that resides in the “tarJournal” directory (simply “journal” if you’re running a previous version than CRX 2.2) under the “repository” directory.

Delete the index*.tar files so they are re-built (depending on size of your repository this may take some time at start-up).

Delete the Lucene index (the directories named “index”) so this is also re-built at start-up. Note that this can also take some time.

Now you’re ready to re-start…cross your fingers and go!

Leave a Reply

You must be logged in to post a comment.