CMS Shell

(Difference between revisions)
Jump to: navigation, search
(→Linux)
(Re-wrote Linux instructions, minor spelling/grammar/structure fixes on the rest of the page)
Line 1: Line 1:
−
==What is it for? Purpose.==
+
==What is it for? (purpose)==
  
 
Shell script for Linux/Windows to start a shell prompt which gives you access to OpenCms.
 
Shell script for Linux/Windows to start a shell prompt which gives you access to OpenCms.
Line 12: Line 12:
 
*rebuilding indexes
 
*rebuilding indexes
  
−
==Linux==
+
==Running the Shell==
  
−
Under Linux I used the following commands to run 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.
  
−
"'''cd'''" to the WEB-INF folder of the OpenCms web application. In that folder you will see the cmsshell.sh. "''chmod 755''" it if it's not an executable.
+
===Windows===
−
Then copy the "''servlet-api.jar''" and "''jsp-api.jar''" to the "''./lib/''" folder. Using the following command you should now be able to start the shell.
+
  
−
<code lang="bash">java -Djava.ext.dirs=./lib/ org.opencms.main.CmsShell</code>
+
To run the shell, Windows users should enter the following commands at a Windows Command Prompt:
  
−
Note: I had trouble getting the ''-classpath'' to work with my JDK 1.6, so I used the "''-Djava.ext.dirs=''" instead. That's why I copy the two jars above into that folder. If someone has a method that works better please post the update here.
+
# Change you current path to the WEB-INF folder of your OpenCms installation using the '''cd''' command
 +
# Run cmsshell.bat by typing the filename
  
−
Note: I had the same classpath issues. I changed the line ''java -classpath "${OPENCMS_CLASSPATH}:${TOMCAT_CLASSPATH}:classes" org.opencms.main.CmsShell -base="${OPENCMS_BASE}" "$@"'' in cmsshell.sh to ''java -classpath "/usr/share/java/servlet.jar:/usr/share/java/jsp.jar:${OPENCMS_CLASSPATH}:${TOMCAT_CLASSPATH}:classes" org.opencms.main.CmsShell -base="${OPENCMS_BASE}" "$@"''. It works for me.
+
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.
−
By the way: "''chmod +x''" is the way to mark a file executable.
+
  
−
==Windows==
+
===Linux===
  
−
Under Windows, use the following simple steps:
+
To run the shell, a Linux user will need to type the following commands in a terminal.
  
−
# Change you current path to the WEB-INF folder of your OpenCms installation
+
Change directory to the ''WEB-INF'' folder of the OpenCms web application. For a normal installation of Tomcat 6, the command would be:
−
# Run cmsshell.bat from the command line
+
  
−
I have had no trouble accesing the shell running these commands, if you find problems check the preceding section for possible .jar issues.
+
<code lang="bash">cd /var/lib/tomcat6/webapps/opencms/WEB-INF/</code>
  
−
==What do you get? Usage.==
+
Now run ''cmsshell.sh'' (located in this directory):
 +
 
 +
<code lang="bash">./cmsshell.sh</code>
 +
 
 +
====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:
 +
 
 +
<code lang="bash">ls -l cmsshell.sh | grep $USERNAME</code>
 +
 
 +
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:
 +
 
 +
<code lang="bash">chmod +x cmsshell.sh</code>
 +
 
 +
Or if you would like to allow the file to only be executed by the file owner, use:
 +
 
 +
<code lang="bash">chmod u+x cmsshell.sh</code>
 +
 
 +
=====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.
 +
 
 +
<code lang="bash">vim cmsshell.sh</code>
 +
 
 +
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.
 +
 
 +
<code lang="bash">
 +
SERVLET_API=/usr/share/java/servlet-api.jar
 +
JSP_API=/usr/share/java/jsp-api.jar
 +
</code>
 +
 
 +
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:
 +
 
 +
<code lang="java">java -classpath "${SERVLET_API}:${JSP_API}:${OPENCMS_CLASSPATH}:${TOMCAT_CLASSPATH}:classes" org.opencms.main.CmsShell -base="${OPENCMS_BASE}" "$@"</code>
 +
 
 +
=====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:
 +
 
 +
<code lang="bash">ex '+set fileformat=unix' '+wq!' cmsshell.sh</code>
 +
 
 +
=====Removing Unnecessary Files=====
 +
 
 +
Windows .bat files won't run on Linux and, as such, are redundant and can be removed if you so wish:
 +
 
 +
<code lang="bash">rm *.bat</code>
 +
 
 +
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:
 +
 
 +
<code lang="bash">
 +
for i in `ls | grep \.bat$`
 +
do
 +
  mv $i .$i
 +
done
 +
</code>
 +
 
 +
==What do you get? (usage)==
  
 
Once the shell is correctly run, you get something like <code lang="bash">Guest@Online:|/></code>, that is, the command line for the shell. This means you are not authenticated and therefore at project Online with Guest user (you can authenticate to get administrative credentials as requiered for certaing tasks with the "login" command.)
 
Once the shell is correctly run, you get something like <code lang="bash">Guest@Online:|/></code>, that is, the command line for the shell. This means you are not authenticated and therefore at project Online with Guest user (you can authenticate to get administrative credentials as requiered for certaing tasks with the "login" command.)
Line 46: Line 104:
 
*exit or quit - Leaves the OpenCms Shell
 
*exit or quit - Leaves the OpenCms Shell
  
−
==Available commands==
+
==Available Commands==
 
Under the shell you can execute commands like the following:
 
Under the shell you can execute commands like the following:
  

Revision as of 21:35, 19 September 2011

Contents

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.

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

What do you get? (usage)

Once the shell is correctly run, you get something like 
Guest@Online:|/>
, that is, the command line for the shell. This means you are not authenticated and therefore at project Online with Guest user (you can authenticate to get administrative credentials as requiered for certaing tasks with the "login" command.)

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:

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, the available methods are:


Available methods in org.opencms.main.CmsShellCommands

  • addWebUser(String, String, String, String)
  • 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)
  • 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(int)
  • readManagerGroup(int)
  • readOwnerOfProject(int)
  • rebuildAllIndexes()
  • rebuildIndex(String)
  • replaceModule(String, String)
  • replaceModuleFromDefault(String, String)
  • setCurrentProject(int)
  • setCurrentProject(String)
  • 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()
  • getRemoteAddress()
  • getRequestTime()
  • getSiteRoot()
  • getUri()
  • isUpdateSessionEnabled()
  • removeSiteRoot(String)
  • restoreSiteRoot()
  • saveSiteRoot()
  • setEncoding(String)
  • setRequestTime(long)
  • setSiteRoot(String)
  • setUpdateSessionEnabled(boolean)
  • setUri(String)

Available methods in org.opencms.file.CmsObject

  • addUserToGroup(String, String)
  • backupProject(int, long)
  • chacc(String, String, String, String)
  • chacc(String, String, String, int, int, int)
  • changeLastModifiedProjectId(String)
  • changeLock(String)
  • changeResourcesInFolderWithProperty(String, String, String, St
  • changeUserType(String, int)
  • changeUserType(CmsUUID, int)
  • 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)
  • 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()
  • getAllManageableProjects()
  • getBackupTagId()
  • getChild(String)
  • getChilds(String)
  • getConfigurations()
  • getDirectGroupsOfUser(String)
  • getFilesInFolder(String)
  • getGroups()
  • getGroupsOfUser(String)
  • getGroupsOfUser(String, String)
  • getLock(String)
  • getLostAndFoundName(String)
  • getParent(String)
  • getPermissions(String)
  • getPermissions(String, String)
  • getPublishList()
  • getRequestContext()
  • getResourcesInTimeRange(String, long, long)
  • getSubFolders(String)
  • getTaskService()
  • getUsers()
  • getUsers(int)
  • getUsersOfGroup(String)
  • hasPublishPermissions(String)
  • isAdmin()
  • isInsideCurrentProject(String)
  • isManagerOfProject()
  • lockResource(String)
  • lockResource(String, int)
  • loginUser(String, String)
  • loginUser(String, String, String)
  • loginUser(String, String, String, int)
  • loginWebUser(String, String)
  • lookupPrincipal(String)
  • lookupPrincipal(CmsUUID)
  • moveResource(String, String)
  • moveToLostAndFound(String)
  • publishProject()
  • publishResource(String)
  • readAllBackupFileHeaders(String)
  • readAllPropertyDefinitions()
  • readAncestor(String, int)
  • readBackupFile(String, int)
  • readBackupProject(int)
  • readFile(String)
  • readFileHeader(String)
  • readFolder(String)
  • readGroup(CmsUUID)
  • readGroup(String)
  • readProject(String)
  • 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(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)
  • readWebUser(String)
  • readWebUser(String, String)
  • removeResourceFromProject(String)
  • removeUserFromGroup(String, String)
  • renameResource(String, String)
  • restoreResourceBackup(String, int)
  • 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)
  • undoChanges(String, boolean)
  • unlockProject(int)
  • unlockResource(String)
  • userInGroup(String, String)
  • validatePassword(String)
  • writeProperty(String, String, String)
  • writeProperty(String, String, String, boolean)
  • writeStaticExportPublishedResource(String, int, String, long)
Retrieved from "http://www.opencms-wiki.org/index.php?title=CMS_Shell&oldid=5538"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox