You inadvertently stopped the HTTP Service or the Web Console and cannot access the system any longer. Or, your repository crashed and the Web Console just does not let you easily fix the repository. Or, you are looking for the CRX Console from earlier versions of CRX.
This document explains how you can install a text based command line shell helping you recover from these and maybe other problems.
The key to the solution is to use the command line interface to the OSGi framework which is provided by the Apache Felix Gogo Shell. As is custom in the OSGi world, the Gogo Shell comes along as a collection of bundles:
More information on the Gogo Shell is available from the Apache Felix site.
The core bundles -- Runtime, Command, and Shell -- are essential and are always required.
Web Console Access
If access to the Web Console is still possible, using the Web Console Gogo Shell Plugin is recommended for remote shell access.
If access to the Web Console is not possible any longer -- e.g. the Http Service is dead or the Web Console itself does not work any more -- you may install the Remote Shell bundle.
Unlike the Web Console Gogo Shell Plugin, the Remote Shell bundle does *not* allow for true remote access. For security reasons, the Remote Shell bundle by default listens to port 6666 on localhost (127.0.0.1) only. That, access is only possible from the same box.
Access to the Web Console Gogo Shell Plugin is guarded as everything in the Web Console, through simple authentication and basic access control. For example the Sling Web Console Security provider out of the box only allows for the admin user to access the Web Console.
As such, the Web Console should, of course, also not be exposed through the Dispatcher to the public internet.
The Remote Shell bundle does not implement any access control whatsoever. The only basic security implemented is, that by default only access to localhost (127.0.0.1) is possible. This means, A remote shell to the host (e.g. an SSH session) is required before being able to telnet into the Remote Shell.
Also, the Remote Shell bundle is not intended to be active by default and over time. The bundle should be installed in case of emergency and should be uninstalled after solving the emergency problem to prevent potential issues. No regular functionality should be based on the Remote Shell bundle alone.
Content Package Installation
If the JCR repository is still operable and is accessible over HTTP, the easiest thing to do is to install the attached Gogo Shell Content Package. This content packages provides the Gogo Runtime, Command, and Shell bundles as well as the Web Console Gogo Shell Plugin.
It does not include the Remote Shell because of security concerns and because it is not really needed in this situation.
Web Console Installation
If the JCR Repository is not available any more but the Web Console is accessible, you can download and unpack the attached Gogo Shell Content Package and upload the contained bundles through the Web Console.
Again, the Remote Shell bundle should not be installed in this case because of security concerns and because it is not really needed.
In case of solving emergency problems where neither the JCR Repository nor the Web Console are operable and accessible, you will have to fall back to local installation of the Gogo Shell. This installation requires access to the filesystem and shell access.
The basic installation steps are as follows:
The OSGi Installer running in the Granite based application will automatically pick up the bundles from the crx-quickstart/install folder and install and start them. You might have to wait a few seconds for this to happen.
After the installation, you can telnet in to the Gogo Shell which listens on port 6666 by default:
$ telnet localhost 6666
Connected to localhost.
Escape character is '^]'.
Welcome to Apache Felix Gogo
If all goes well, you get the command prompt -- g! -- from the Gogo Shell where you can start running commands like help (to get a list of commands available) and lb (to list running bundles).
See the the Apache Felix site for more information on the Gogo Shell.
To recover from inadvertedly stopping the Http Service bundle follow these steps:
You should now be able to access the application with your browser.
Starting with CRX 2.3.18 (included in CQ 5.5 Update 1) the repository can be accessed using the gogo shell. This can be done by using the telnet command described above or using a webbrowser (http://localhost:4502/system/console/gogo). All CRX related commands have a crx: prefix. You can list these by typing crx:help
add Adds a new node or child node entry.
bundlecheck Checks node bundles
cd Changes the current work node.
check Checks the repository
checkin Does a checkin on a node.
checkout Does a checkout on a node.
clone Clones a node.
connect Connects to a CRXRepository.
cp Copies a node.
echo Prints the arguments to the console
help Prints this help
login Perform a login on the repository.
logout Perform a logout on the repository.
ls Prints the list of nodes of properties.
mixin Manipulates the set of mixin nodetypes of a node.
mv Moves a node.
patch Patch lowlevel data of an item state.
print Prints the definition of a node or a property.
pwd Prints the current path.
refresh Refreshs a node, property or session
rm Removes a node or property.
save Saves a node, property or session
spool Spools (copies) a workspace.
stat Prints the lowlevel (persistence) information of a node or a property.
workspace Manages workspaces
Paths can be specified either
- relative to the cwd (i.e. './foo/bar')
- absolute (i.e. '/foo/bar')
- or uuid-relative (i.e. '[cafebabe-cafe-babe-cafe-babecafebabe]/foo/bar')
Use 'help -d' to list the details for all commands or
use 'help <cmd>' for a specific command.
If you want to fix repository inconsistencies you can try: