CMS Shell

Latest revision as of 13:24, 11 November 2011

What is it for? (purpose)

Shell script for Linux/Windows to start a shell prompt which gives you access to OpenCms.

This allows to perform a certain group of operations without logging into the OpenCms Workplace, useful for damaged workplaces or administrative tasks to be perfomed automatically through shell scripts.

Some possible actions are

• creating folders
• creating groups and users
• exporting/importing resources or modules
• purging jsp cache repository
• rebuilding indexes

Running the Shell

You'll need to start the shell before you can use it and this is slightly different depending on the operating system you're using. In this section, steps to access the shell are describe for different operating systems.

Windows

To run the shell, Windows users should enter the following commands at a Windows Command Prompt:

1. Change you current path to the WEB-INF folder of your OpenCms installation using the cd command
2. Run cmsshell.bat by typing the filename

There has been no trouble accessing the shell running these commands; if you find problems check troubleshooting in the next section for possible .jar issues. The Linux section below might be helpful in general if you need more information.

Linux

To run the shell, a Linux user will need to type the following commands in a terminal.

Change directory to the WEB-INF folder of the OpenCms web application. For a normal installation of Tomcat 6, the command would be:

cd /var/lib/tomcat6/webapps/opencms/WEB-INF/

Now run cmsshell.sh (located in this directory):

./cmsshell.sh

Troubleshooting & Other Notes

This section describes solutions for for common errors when trying to execute cmsshell.sh as well as ways to make the shell easier to access.

Permision Denied

If you got an error Permission Denied or similar, you might not have permission to execute the file. You can check whether belongs to you or not. If the following command returns no output then you do not own the file:

ls -l cmsshell.sh | grep $USERNAME

Usually this error occurs because you do not have permission to execute the file. Executable permission will need to be granted by the file owner with the following command:

chmod +x cmsshell.sh

Or if you would like to allow the file to only be executed by the file owner, use:

chmod u+x cmsshell.sh

Class Not Found

The comments in cmsshell.sh mention that it needs to know where servlet-api.jar and jsp-api.jar are. If you get error messages while starting the shell, saying that these files were not found, you can follow these instructions to add them to the classpath for the shell. For this you will be editing the cmsshell.sh file itself. My favourite editor is vim but you might prefer something else like nano, in which case, type that instead.

vim cmsshell.sh

Near the top add variables for the locations of the 2 JAR files. They are usually located in /usr/share/java/. It's a good idea to make variables for them in case you would like to refer to them again elsewhere in the file and/or be able to change all references from one place.

SERVLET_API=/usr/share/java/servlet-api.jar
JSP_API=/usr/share/java/jsp-api.jar

Now, near the end of the file, there is a line beginning with java -classpath. This is the line that starts the shell and we're going to add our previously defined variables to the classpath, seperated by colons (not semicolons as in Windows) so that the line reads:

java -classpath "${SERVLET_API}:${JSP_API}:${OPENCMS_CLASSPATH}:${TOMCAT_CLASSPATH}:classes" org.opencms.main.CmsShell -base="${OPENCMS_BASE}" "$@"

Bad Interpreter

If you cannot run the file because you get an error "bash: ./cmsshell.sh: /bin/bash^M: bad interpreter: No such file or directory" it is because the file was created on a different filesystem such as that of Windows or Mac that uses different characters to mark the end of a line. You can use VIM to change the file format to UNIX so that it can be understood by Linux like this:

ex '+set fileformat=unix' '+wq!' cmsshell.sh

Removing Unnecessary Files

Windows .bat files won't run on Linux and, as such, are redundant and can be removed if you so wish:

rm *.bat

If you would prefer to hide the files instead so that you still have them without them bothering you, you can prepend a . to each file's filename:

for i in `ls | grep \.bat$`
do
  mv $i .$i
done

Wrapper Script to run CmsShell from Anywhere

The current set-up requires you to change directory and then run the the file from that directory. It also requires you to be logged on as someone who has permission to create files in the WEB-INF directory, otherwise you can't create log files. It may be more convenient to have a script that does this when you type cmsshell anywhere.

To do this, type the following code as the root user, or somebody who has permission to create and modify files in /usr/bin:

echo 'cd /var/lib/tomcat6/webapps/opencms/WEB-INF/
sudo ./cmsshell.sh' > /usr/bin/cmsshell
chmod +x /usr/bin/cmsshell

What do you get? (usage)

Guest@Online:|/>

The basic commands are displayed when you start the shell, being:

• help - Displays this brief abstract of possible commands
• help * - Shows the signature of all available methods
• help {string} - Shows the signature of all methods containing this string
• exit or quit - Leaves the OpenCms Shell

Available Commands

Under the shell you can execute commands like the following:

login "Admin" "password"
createDefaultProject "Offline" "The Offline Project"

These are two samples of the long list of possible commands. The available commands are public methods in the classes:

• org.opencms.main.CmsShellCommands (see all available methods)
• org.opencms.file.CmsRequestContext (see all available methods)
• org.opencms.file.CmsObject (see all available methods)

For obvious reasons only certain parameter types can be used in a command line, so only public methods in the mentioned classes that use supported data types can be called. Supported data types are:

• String
• CmsUUID
• boolean
• int
• long
• double
• float

To know more about a certain method you should look at your version's OpenCms Javadoc (at OpenCms's Official Javadoc or even more complete at JavaDoc APIs provided by Synyx GmbH & Co. KG) (by the way I do not work for Synyx nor do I have any hidden interest in this company, it's just the best OpenCms Javadoc reference I know and that I use all the time - they have the 'Use' link active on top of each class and for me that makes a big deal of difference).

Simple Example

This example will set the title and description tags for a given resource. This type of scripting can be a useful way to apply properties to CMS files programmatically.

login "Admin" "password" 
setCurrentProject "Offline" 
lockResource "/sites/default/index.html"
writeProperty "/sites/default/index.html" "Title" "META TITLE / HEADER TAG (1)"
writeProperty "/sites/default/index.html" "Description" "META Description (4)" 
unlockResource "/sites/default/index.html"

In order to see changes made through the CMS shell in the web browser Explorer interface, you will need to either restart the OpenCMS instance or go to Administration -> cache and flush the core caches. You may need to flush the JSP cache as well, depending on your implementation. Flushing these caches will have a brief performance penalty, so heavily loaded sites should postpone it until off-hours.

Complete method list

A complete available methods list is provided with command help * .

In order to invoke these methods, omit the parenthesis and quote the information. In other words, cd(String) below becomes cd "/sites/default/"

As of OpenCms 6.2.3 - 7.0.5, the available methods are:

Available methods in org.opencms.main.CmsShellCommands

• addWebUser(String, String, String, String) - 6.2.3
• cd(String)
• chacc(String, String, String, String)
• clearCaches()
• copyright()
• createDefaultProject(String, String)
• createFolder(String, String)
• createGroup(String, String)
• createPropertydefinition(String)
• createUser(String, String, String)
• createUser(String, String, String, String, String, String)
• deleteBackups(int)
• deleteHistoricalVersions(String, int, int, long) - 7.0.5
• deleteModule(String)
• deleteProject(String)
• deletepropertydefinition(String)
• echo(String)
• exit()
• exportAllResources(String)
• exportModule(String)
• exportResources(String, String)
• exportResourcesAndUserdata(String, String)
• getAcl(String)
• getLocales()
• help()
• help(String)
• importModule(String)
• importModuleFromDefault(String)
• importModulesFromSetupBean()
• importResources(String, String)
• importResourcesWithTempProject(String)
• listModules()
• login(String, String)
• ls()
• lsacc(String)
• lsacc(String, String)
• perf()
• prompt(String)
• purgeJspRepository()
• pwd()
• quit()
• readFileContent(String)
• readGroupOfProject(CmsUUID) - 7.0.5
• readGroupOfProject(int) - 6.2.3
• readManagerGroup(CmsUUID) - 7.0.5
• readManagerGroup(int) - 6.2.3
• readOwnerOfProject(CmsUUID) - 7.0.5
• readOwnerOfProject(int) - 6.2.3
• rebuildAllIndexes()
• rebuildIndex(String)
• replaceModule(String, String)
• replaceModuleFromDefault(String, String)
• setCurrentProject(int)
• setCurrentProject(CmsUUID) - 7.0.5
• setCurrentProject(String) - 6.2.3
• setLocale(String)
• shellExit()
• shellStart()
• unlockCurrentProject()
• uploadFile(String, String, String, String)
• version()
• whoami()

Available methods in org.opencms.file.CmsRequestContext

• addSiteRoot(String)
• addSiteRoot(String, String)
• currentProject()
• currentUser()
• getAdjustedSiteRoot(String)
• getAttribute(String)
• getDirectoryTranslator()
• getEncoding()
• getFileTranslator()
• getFolderUri()
• getLocale()
• getOuFqn() - 7.0.5
• getRemoteAddress()
• getRequestTime()
• getSiteRoot()
• getUri()
• isUpdateSessionEnabled()
• removeAttribute(String) - 7.0.5
• removeSiteRoot(String)
• restoreSiteRoot()
• saveSiteRoot()
• setEncoding(String)
• setOuFqn(String) - 7.0.5
• setRequestTime(long)
• setSiteRoot(String)
• setUpdateSessionEnabled(boolean)
• setUri(String)

Available methods in org.opencms.file.CmsObject

• addRelationToResource(String, String, String) - 7.0.5
• addUserToGroup(String, String)
• backupProject(int, long)
• chacc(String, String, String, String)
• chacc(String, String, String, int, int, int)
• changeLastModifiedProjectId(String) - 6.2.3
• changeLock(String)
• changeResourcesInFolderWithProperty(String, String, String, String, boolean)
• changeUserType(String, int) - 6.2.3
• changeUserType(CmsUUID, int) - 6.2.3
• chflags(String, int)
• chtype(String, int)
• copyResource(String, String)
• copyResource(String, String, int)
• copyResourceToProject(String)
• countLockedResources(String)
• countLockedResources(int)
• cpacc(String, String)
• createGroup(String, String, int, String)
• createProject(String, String, String, String)
• createProject(String, String, String, String, int)
• createPropertyDefinition(String)
• createResource(String, int)
• createTempfileProject()
• deleteAllStaticExportPublishedResources(int)
• deleteGroup(String)
• deleteGroup(CmsUUID, CmsUUID)
• deleteProject(int)
• deleteProject(CmsUUID) - 7.0.5
• deleteProperty(String, String)
• deletePropertyDefinition(String)
• deleteResource(String, int)
• deleteStaticExportPublishedResource(String, int, String)
• deleteUser(CmsUUID)
• deleteUser(String)
• deleteUser(CmsUUID, CmsUUID)
• deleteWebUser(CmsUUID)
• existsResource(String)
• getAccessControlEntries(String)
• getAccessControlEntries(String, boolean)
• getAccessControlList(String)
• getAccessControlList(String, boolean)
• getAllAccessibleProjects()
• getAllBackupProjects()
• getAllHistoricalProjects() - 7.0.5
• getAllManageableProjects()
• getBackupTagId()
• getChild(String)
• getChildren(String, boolean) - 7.0.5
• getChilds(String)
• getConfigurations()
• getDirectGroupsOfUser(String)
• getFilesInFolder(String)
• getGroups()
• getGroupsOfUser(String)
• getGroupsOfUser(String, String)
• getGroupsOfUser(String, boolean, String) - 7.0.5
• getGroupsOfUser(String, boolean, boolean, String) - 7.0.5
• getLock(String)
• getLostAndFoundName(String)
• getParent(String)
• getPermissions(String)
• getPermissions(String, String)
• getPublishList()
• getRequestContext()
• getResourcesInTimeRange(String, long, long)
• getSubFolders(String)
• getTaskService() - 6.2.3
• getUsers()
• getUsers(int) - 6.2.3
• getUsersOfGroup(String)
• getUsersOfGroup(String, boolean) - 7.0.5
• hasPublishPermissions(String)
• isAdmin()
• isInsideCurrentProject(String)
• isManagerOfProject()
• lockResource(String)
• lockResource(String, int)
• lockResourceTemporary(String) - 7.0.5
• loginUser(String, String)
• loginUser(String, String, String)
• loginUser(String, String, String, int) - 6.2.3
• loginWebUser(String, String)
• lookupPrincipal(String)
• lookupPrincipal(CmsUUID)
• moveResource(String, String)
• moveToLostAndFound(String)
• publishProject()
• publishResource(String)
• readAllAvailableVersions(String) - 7.0.5
• readAllBackupFileHeaders(String)
• readAllPropertyDefinitions()
• readAncestor(String, int)
• readBackupFile(CmsUUID, int) - 7.0.5
• readBackupFile(String, int)
• readBackupProject(int)
• readDefaultFile(String) - 7.0.5
• readFile(String)
• readFileHeader(String)
• readFolder(String)
• readGroup(CmsUUID)
• readGroup(String)
• readHistoryPrincipal(CmsUUID) - 7.0.5
• readHistoryProject(CmsUUID) - 7.0.5
• readHistoryProject(int) - 7.0.5
• readProject(String)
• readProject(CmsUUID) - 7.0.5
• readProject(int)
• readProjectView(int, int)
• readProperties(String)
• readProperties(String, boolean)
• readProperty(String, String)
• readProperty(String, String, boolean)
• readProperty(String, String, boolean, String)
• readPropertyDefinition(String)
• readPropertyObject(String, String, boolean)
• readPropertyObjects(String, boolean)
• readPublishedResources(CmsUUID)
• readResource(CmsUUID) - 7.0.5
• readResource(String)
• readResourcesWithProperty(String)
• readResourcesWithProperty(String, String)
• readResourcesWithProperty(String, String, String)
• readStaticExportPublishedResourceParameters(String)
• readStaticExportResources(int, long)
• readUser(String)
• readUser(CmsUUID)
• readUser(String, String)
• readUser(String, int) - 6.2.3
• readWebUser(String)
• readWebUser(String, String)
• removeResourceFromProject(String)
• removeUserFromGroup(String, String)
• renameResource(String, String)
• restoreDeletedResource(CmsUUID) - 7.0.5
• restoreResourceBackup(String, int)
• restoreResourceVersion(CmsUUID, int)- 7.0.5
• rmacc(String, String, String)
• setDateExpired(String, long, boolean)
• setDateLastModified(String, long, boolean)
• setDateReleased(String, long, boolean)
• setParentGroup(String, String)
• setPassword(String, String)
• setPassword(String, String, String)
• touch(String, long, long, long, boolean)
• undeleteResource(String)
• undeleteResource(String, boolean) - 7.0.5
• undoChanges(String, boolean)
• unlockProject(int)
• unlockProject(CmsUUID) - 7.0.5
• unlockResource(String)
• userInGroup(String, String)
• validatePassword(String)
• writeProperty(String, String, String)
• writeProperty(String, String, String, boolean)
• writeStaticExportPublishedResource(String, int, String, long)