OpenCms documentation
OpenCms documentation

OpenCms shell

The OpenCms shell is an executable that allows one to interact with OpenCms from the command line. You can also pass a script to the shell that should be executed. Hence, it is the tool to automate tasks and, for example, execute them within the scope of a larger normal shell script.

The OpenCms shell is perfect for automating tasks. In particular, tasks that include not only OpenCms specific parts, but also "normal" shell commands. You can call the OpenCms shell from a shell script and paste it an OpenCms script that it should execute.

Particular use cases are

  • Automatically install extra modules when deploying OpenCms
  • Automatically export database data or modules, e.g., for moving the exported data to another server for backup.

The OpenCms shell also supports import and export in clusters.

Since OpenCms 11, you can start the shell either in stand-alone mode (as was before) or connect to your running OpenCms webapp via remote method invocation (RMI).

To avoid inconsistencies due to caches, you should always use the RMI connection for starting the shell while your OpenCms webapp is running.

The OpenCms shell is shipped with the standard OpenCms installation. It's the executable class org.opencms.main.CmsShell. To start the shell the scripts

  • cmsshell.bat (for Windows)
  • cmsshell.sh (for Linux)

that are placed in the folder {webapp home}/WEB-INF should be used. They set the correct extra parameters for excuting the Shell and start it.

The OpenCms shell takes several arguments on startup that can also be given to appropriate start scripts.

-base

Set the absolute path to the OpenCms installation's base directory, i.e., {absolute path to the webapp home}/WEB-INF. If not provided, the path is read from the system property user.dir. The start scripts set this argument automatically.

-script

Provide the path to a OpenCms shell script file. Such a file lists a series of OpenCms shell commands. The commands are all executed when handing the script to the shell on startup.

The last command in your OpenCms shell script should be quit or exit, because mixing batch mode and interactive mode is not supported.
-servletMapping

The servlet mapping defined in the web.xml of the OpenCms installation. If not given /opencms/* is used as the default.

-defaultWebApp

The webapp name of the default webapp as configured for your servlet container. The default value is ROOT, as it is in a standard Tomcat installation.

-additional

Add additional shell commands by providing the fully qualified name of a class that implements I_CmsShellCommands to make all commands defined in that class available in the shell.

Via RMI (remote method invocation) you connect directly to the running OpenCms instance. This is the way to go if you want to excute shell scripts while OpenCms is running as webapp.

To allow for connections via RMI, you need to configure the connection in the {webapp home}/WEB-INF/config/opencms-system.xml. If not present already, add the following line below <system> tag:

<shell-server enabled="true" port="1101" />

If present already, just change enabled="false" into enabled="true". The port can be changed. You need to know it when running the OpenCms shell. To run the shell execute:

java -cp $OPENCMS_WEBAPP_DIR/WEB-INF/lib/opencms.jar org.opencms.rmi.CmsRemoteShellClient [options]

where the following options are allowed:

-registryPort

The port to connect via RMI. This must be provided. The value is the port specified in the opencms-system.xml. E.g., for the configuration as examplified above, you must add -registryPort=1101.

-script

Takes an OpenCms shell script to execute. If provided the shell will run in batch mode. E.g., you could add the option -script=myscript.ocsh.

-additional

Provide an additional class with shell commands, e.g., when having OCEE cluster installed, you could put the option
-additional=org.opencms.ocee.cluster.CmsClusterShellCommands.

Note that the shell must be called from the machine where your OpenCms instance is running on.
The OpenCms shell on startup

We describe how to work with the OpenCms shell in interactive mode, i.e., without passing a script to the shell. But most information is also useful for writing scripts, because in batch mode, the shell starts exactly as in interactive mode - it's just that the commands you would type in interactive mode are all read from the given script.

When the shell starts it creates a new OpenCms instance and displays some information on the startup process plus help information. When startup is finished, you'll see a prompt where you can type commands.

The most important information is the help option on commands. You can get the signature of all available methods that make up commands, grouped by the classes that provide the methods, using help *. You can also search for signatures of methods whose name contains a special substring by typing help {string}. This search is not case-sensitive.

Signatures are shown as methodName(arg1,arg2,..,argn). To use the method as command type methodName arg1 arg2 ... argn.

Let's see a very simple use case of the help function. You want to log in to OpenCms, but don't know exactly how. Thus, you search for login commands via help login. The shell will tell you:

Guest@Online:|/>help login  

Available methods in org.opencms.main.CmsShellCommands:
* login(String, String)

Available methods in org.opencms.file.CmsObject:
* loginUser(String, String)
* loginUser(String, String, String)

You'll see three available methods that can be used as commands. To get further information on the methods, look up the JavaDoc of the classes that implement the methods. We assume we know already that the login method takes a username and a password. Thus we log in as follows:

Guest@Online:|/>login Admin admin
You are now logged in as user "Admin".
Admin@Online:|/>
Be careful with relative paths on your real file system used in OpenCms shell commands: When connecting via RMI, paths are relative to your servlet-containers (e.g., Tomcats) home folder. When running in stand-alone mode, they are relative to your current folder. To prevent confusion, absolute paths might be preferrable.

The available commands are public methods from various classes. But not all public methods make up a command. The methods must have sufficiently simple arguments. That means, all arguments must have a "simple" type.

The types that are supported for command arguments are the arguments parsable via org.opencms.util.CmsDataTypeUtil.isParseable.

By default commands are exposed for methods of the following classes:

You can look up descriptions of the methods available as commands in the JavaDoc.

Using the argument -additional when calling the OpenCms shell, you can add an extra class for exposing methods. The class must implement I_CmsShellCommands.

Typing help * in the shell, you can always get an overview of the available commands.

When you connect to the shell via RMI, there are three interesting commands available that do not make sense in stand-alone mode:

  • sendBroadcast message: Sends the message to all logged in users via the OpenCms broadcast mechanism.
  • setLoginMessage message loginDisabled: Sets a login message and disables/enables login. E.g., you could call setLoginMessage "Login disabled for maintenance" "true"
  • clearLoginMessage: Disables a formerly set login message.

When you call the OpenCms shell in stand-alone mode, a new instance of OpenCms is started. You do not need to have OpenCms already running in your Tomcat (or other servlet container). You do not even need to start the servlet container at all.

You should be aware that the shell starts a new OpenCms instance when executed in stand-alone mode. That may interfere with an already running instance started by Tomcat. So we strongly recommend not using the shell while OpenCms is already running.

When running the shell via RMI, you are connected to your OpenCms instance running in the serlvet-container (e.g. Tomcat).

Connect via RMI always when your OpenCms is normally running in the servlet container (e.g., Tomcat).