Wiki source code of Tomcat Installation
Version 28.3 by Jesse Bright on 2017/02/28
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
13.4 | 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} |
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
 |
11.1 | 4 | |
| |
5.2 | 5 | = Installation Steps = |
| |
1.1 | 6 | |
| |
26.1 | 7 | {{error}} |
| |
28.1 | 8 | The Tomcat project has brought a change in the [[way they handle ##RequestDispatcher##>>https://bz.apache.org/bugzilla/show_bug.cgi?id=59317]] which has caused [[regressions in XWiki>>http://jira.xwiki.org/browse/XWIKI-13556]] for some versions of Tomcat. Thus you should **not** use the following Tomcat versions: |
| 9 | * >= 9.0.0.M5 and < 9.0.0.M10 for the 9.0.x branch (fixed in 9.0.0.M10) | ||
| 10 | * >= 8.5.1 and < 8.5.5 for the 8.5.x branch (fixed in 8.5.5) | ||
| 11 | * >= 8.0.34 and < 8.0.37 for the 8.0.x branch (fixed in 8.0.37) | ||
| 12 | * >= 7.0.70 and < 7.0.71 for the 7.0.x branch (fixed in 7.0.71) | ||
| |
26.1 | 13 | {{/error}} |
| 14 | |||
| |
5.2 | 15 | * Download and install [[Tomcat>>http://tomcat.apache.org/]]. It's usually as simple as unzipping it in a directory. Let's call this directory //##TOMCAT_HOME##//. |
| 16 | * Extract the [[XWiki WAR>>xwiki:Main.Download]] into a directory named ##xwiki## in ##//TOMCAT_HOME///webapps/##. The reason you're expanding the WAR is because you'll need to modify one configuration file from inside the WAR later on when you configure the database access. | ||
| |
6.1 | 17 | * Edit your //conf/server.xml// to set UTF-8 encoding: {{code}}<Connector port="8080" ... URIEncoding="UTF-8"/>{{/code}} |
| |
28.2 | 18 | * Make sure you [[give enough memory to Java>>#HOutOfMemoryError]] since by default Tomcat is configured with not enough memory for XWiki. |
| |
1.4 | 19 | |
| |
11.1 | 20 | == Activate headless mode == |
| |
10.1 | 21 | |
| 22 | If you're operating XWiki on a Linux server with no X11 libraries installed you have to enable headless mode for your Tomcat installation. Sometimes this is also needed on Windows platforms. Typical exceptions are: | ||
| 23 | |||
| |
24.6 | 24 | * ##Exception: Could not initialize class sun.awt.X11.XToolkit## |
| 25 | * ##java.lang.InternalError: Can't connect to X11 window server using 'localhost:10.0' as the value of the DISPLAY variable## | ||
| |
9.1 | 26 | |
| |
24.6 | 27 | * On Linux create a file ##///TOMCAT_HOME///bin/setenv.sh## and insert the following code:((( |
| 28 | {{code}} | ||
| 29 | #!/bin/sh | ||
| 30 | export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true" | ||
| |
24.7 | 31 | {{/code}} |
| |
24.6 | 32 | ))) |
| 33 | * On Windows create a file ##///TOMCAT_HOME///bin/setenv.bat## and insert the following code:((( | ||
| |
27.1 | 34 | {{code}} |
| 35 | set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true | ||
| 36 | {{/code}} | ||
| |
24.6 | 37 | ))) |
 |
16.2 | 38 | * When running as a Windows service the ##setenv.bat## is not working. See registry ##HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun 2.0\//FOOBAR//\Parameters\Java## for similar settings. |
| |
9.1 | 39 | |
| |
11.1 | 40 | == Optional configuration == |
| |
9.1 | 41 | |
| |
24.6 | 42 | * Edit your ##conf/server.xml## to enable gzip compression: {{code}}<Connector port="8080" ... compression="on" compressionMinSize="2048" compressableMimeType="text/html,text/xml,text/css,text/javascript,application/x-javascript"/>{{/code}} |
| |
9.1 | 43 | * If you want to modify the port on which Tomcat will run, edit ##//TOMCAT_HOME///conf/server.xml/##. Search for ##8080## (sometimes ##8180## if you are under Linux) and replace with the port value you wish to use. |
| |
16.2 | 44 | * It is possible to setup a Tomcat Java Server as a UNIX Daemon - JSVC. Just follow [[these instructions>>http://www.malisphoto.com/tips/tomcatonosx.html?#Anchor-JSVC||target="new"]]. The only reason to make Tomcat a daemon is to make it runnable on the 80th port, which can be replaced by using NginX as a proxy on the 80th port and then forwarding to Tomcat to the 8080th port. |
| |
9.1 | 45 | |
| |
19.1 | 46 | == Policy configuration == |
| 47 | |||
| |
24.6 | 48 | For those who activate the security manager for Tomcat, add this portion of code to the end of your ##conf/catalina.policy## file from your Tomcat installation. You can adapt the code for the available installations of OpenOffice/LibreOffice on your server and for different databases : |
| |
19.1 | 49 | |
| 50 | {{code}} | ||
| 51 | grant codeBase "file:${catalina.base}/webapps/xwiki/WEB-INF/lib/-" { | ||
| 52 | // for mySQL connection | ||
| 53 | permission java.net.SocketPermission "127.0.0.1:3306", "connect,resolve"; | ||
| 54 | |||
| 55 | // XWiki must have access to all properties in read/write | ||
| 56 | permission java.util.PropertyPermission "*", "read, write"; | ||
| 57 | |||
| 58 | // Generic detected permissions | ||
| 59 | permission java.lang.reflect.ReflectPermission "suppressAccessChecks"; | ||
| 60 | permission java.lang.RuntimePermission "createClassLoader"; | ||
| 61 | permission java.lang.RuntimePermission "setContextClassLoader"; | ||
| 62 | permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.loader"; | ||
| 63 | permission java.lang.RuntimePermission "accessDeclaredMembers"; | ||
| 64 | permission java.lang.RuntimePermission "getenv.ProgramFiles"; | ||
| 65 | permission java.lang.RuntimePermission "getenv.APPDATA"; | ||
| 66 | permission java.lang.RuntimePermission "accessClassInPackage.sun.reflect"; | ||
| 67 | permission java.lang.RuntimePermission "getClassLoader"; | ||
| 68 | permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.connector"; | ||
| |
20.1 | 69 | permission java.lang.RuntimePermission "accessClassInPackage.org.apache.tomcat.util.threads"; |
| |
19.1 | 70 | permission java.lang.RuntimePermission "reflectionFactoryAccess"; |
| 71 | permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.interceptor"; | ||
| 72 | permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.mbeanserver"; | ||
| 73 | permission java.lang.RuntimePermission "modifyThread"; | ||
| 74 | permission java.lang.RuntimePermission "getProtectionDomain"; | ||
| 75 | |||
| 76 | // JAXB permissions | ||
| 77 | permission javax.xml.bind.JAXBPermission "setDatatypeConverter"; | ||
| 78 | |||
| 79 | // Serialization related permissions | ||
| 80 | permission java.io.SerializablePermission "allowSerializationReflection"; | ||
| 81 | permission java.io.SerializablePermission "creator"; | ||
| 82 | permission java.io.SerializablePermission "enableSubclassImplementation"; | ||
| 83 | |||
| 84 | // Internal resources access permissions | ||
| 85 | permission java.io.FilePermission "synonyms.txt", "read"; | ||
| 86 | permission java.io.FilePermission "lang/synonyms_en.txt", "read"; | ||
| 87 | permission java.io.FilePermission "quartz.properties", "read"; | ||
| 88 | permission java.io.FilePermission "/templates/-", "read"; | ||
| 89 | permission java.io.FilePermission "/skins/-", "read"; | ||
| 90 | permission java.io.FilePermission "/resources/-", "read"; | ||
| 91 | |||
| 92 | // MBean related permissions | ||
| 93 | permission javax.management.MBeanServerPermission "createMBeanServer"; | ||
| 94 | permission javax.management.MBeanPermission "*", "registerMBean"; | ||
| 95 | permission javax.management.MBeanPermission "*", "unregisterMBean"; | ||
| 96 | permission javax.management.MBeanTrustPermission "register"; | ||
| 97 | permission javax.management.MBeanPermission "-#-[-]", "queryNames"; | ||
| 98 | permission javax.management.MBeanServerPermission "findMBeanServer"; | ||
| 99 | |||
| 100 | // LibreOffice/OpenOffice related permissions | ||
| 101 | permission java.io.FilePermission "/opt/openoffice.org3/program/soffice.bin", "read"; | ||
| 102 | permission java.io.FilePermission "/opt/libreoffice/program/soffice.bin", "read"; | ||
| 103 | permission java.io.FilePermission "/usr/lib/openoffice/program/soffice.bin", "read"; | ||
| 104 | permission java.io.FilePermission "/usr/lib/libreoffice/program/soffice.bin", "read"; | ||
| 105 | |||
| 106 | // Allow file storage directory reading - for directory and everything underneath | ||
| 107 | // This is dependent on the setting of environment.permanentDirectory in xwiki.properties | ||
| 108 | permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}", "read,write,delete"; | ||
| 109 | permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}-", "read,write,delete"; | ||
| 110 | |||
| 111 | // Allow file storage directory reading - temporary directory and everything underneath | ||
| 112 | // This is dependent on the setting of environment.temporaryDirectory in xwiki.properties. | ||
| 113 | permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}", "read,write,delete"; | ||
| 114 | permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}-", "read,write,delete"; | ||
| 115 | }; | ||
| 116 | {{/code}} | ||
| 117 | |||
| 118 | Please note that this policy configuration file have been tested on CentOS 5.9 with Sun JDK 1.7.0u21 on Tomcat 7.0.40 with XWiki 5.0.1 installed. | ||
| 119 | |||
| |
27.1 | 120 | == Nginx proxying for Tomcat applications == |
| |
13.4 | 121 | |
| |
15.1 | 122 | As Tomcat is not a true web server, it's worth to use it as backend. [[Nginx>>http://wiki.nginx.org/Main||rel="__blank"]] is one of the best solutions for the frontend web server. |
| |
13.4 | 123 | |
| |
16.2 | 124 | So, after a typical XWiki installation we have XWiki running on ##http:~/~/localhost:8080/xwiki##. Most probably, we want to access XWiki via ##http:~/~/mydomain.com## on standard 80 port. Tuning Nginx will give us the desired result: |
| |
13.4 | 125 | |
| |
16.2 | 126 | * create this file ##/etc/nginx/conf.d/tomcat.conf## |
| 127 | * put the following code inside:((( | ||
| |
14.1 | 128 | {{code}} |
| 129 | server { | ||
| 130 | listen 80; | ||
| 131 | server_name mydomain.com; | ||
| |
27.1 | 132 | # Root to the XWiki application |
| 133 | root /opt/tomcat/webapps/xwiki; | ||
| |
13.4 | 134 | |
| |
14.1 | 135 | location / { |
| |
27.1 | 136 | #All "root" requests will have /xwiki appended AND redirected to mydomain.com again |
| |
14.1 | 137 | rewrite ^ $scheme://$server_name/xwiki$request_uri? permanent; |
| 138 | } | ||
| |
13.4 | 139 | |
| |
14.1 | 140 | location ^~ /xwiki { |
| |
27.1 | 141 | # If path starts with /xwiki - then redirect to backend: XWiki application in Tomcat |
| 142 | # Read more about proxy_pass: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass | ||
| 143 | proxy_pass http://localhost:8080; | ||
| |
28.3 | 144 | proxy_set_header X-Real-IP $remote_addr; |
| 145 | proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; | ||
| 146 | proxy_set_header Host $http_host; | ||
| 147 | proxy_set_header X-Forwarded-Proto $scheme; | ||
| |
14.1 | 148 | } |
| 149 | } | ||
| 150 | {{/code}} | ||
| |
15.2 | 151 | ))) |
| |
14.1 | 152 | * restart nginx |
| 153 | |||
| |
27.1 | 154 | Now all ##http:~/~/mydomain.com/*## requests will lead to the XWiki application. Please note that these settings are basic. For more flexible solutions please refer to [[the Nginx documentation>>http://wiki.nginx.org/Main||rel="__blank"]]. |
| |
14.1 | 155 | |
| |
23.1 | 156 | == HTTPS setting == |
| 157 | |||
| |
24.1 | 158 | * If using HTTPS for accessing XWiki, several modifications have to be made to ensure flawless functionality. Since urls are generated from relative path (##/xwiki/bin/show/Space/Page##), Tomcat has to know which protocol to use, otherwise JSON requests with redirect fails (attachment uploads, extension updating, etc.) |
| 159 | * Modify connector (in ##server.xml##) to {{code}}<Connector port="8080" ... secure="true" scheme="https" />{{/code}} | ||
| 160 | * Modify host (in ##server.xml##) and add Remote Ip Valve {{code}}<Valve className="org.apache.catalina.valves.RemoteIpValve" remoteIpHeader="x-forwarded-for" protocolHeader="x-forwarded-proto" />{{/code}} (only needed if using another server for HTTPS) | ||
| |
23.1 | 161 | |
| |
27.1 | 162 | {{info}} |
| 163 | If using another server as a HTTPS proxy (such as Nginx or Apache httpd), ##X-Forwarded-For## and ##X-Forwarded-Proto## headers have to be set! | ||
| 164 | {{/info}} | ||
| |
23.1 | 165 | |
| |
12.1 | 166 | = Troubleshooting = |
| |
1.16 | 167 | |
| |
5.2 | 168 | == Out Of Memory Error == |
| |
1.16 | 169 | |
| |
22.1 | 170 | When you run XWiki in Tomcat with the default settings, you'll probably get an ##Out Of Memory## error (##java.lang.OutOfMemoryError: Java heap space## or ##java.lang.OutOfMemoryError: PermGen space##) since the default Tomcat memory settings are not enough for [[XWiki Memory Requirements>>platform:AdminGuide.Performances#HMemory]]. You'll need to allocate more memory to the JVM. |
| |
1.16 | 171 | |
| |
24.8 | 172 | One easy solution to configure Tomcat's memory is to create a ##setenv.sh## file (or ##setenv.bat## on Windows) in ##[TOMCAT_HOME]/bin/## (where ##[TOMCAT_HOME]## is where you've installed Tomcat) and inside this file add the following (adjust the memory values according to the [[XWiki Memory Requirements>>platform:AdminGuide.Performances#HMemory]]). For example: |
 |
17.1 | 173 | |
| 174 | {{code language="none"}} | ||
| |
24.8 | 175 | CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=192m" |
| |
17.1 | 176 | {{/code}} |
| 177 | |||
| |
22.1 | 178 | On most Linux distributions, this can also be achieved in ##/etc/tomcat//X///tomcat//X//.conf## or ##/etc/conf.d/tomcat//X//.conf## (where //X// is the version of Tomcat installed). |
| |
17.1 | 179 | |
| |
22.1 | 180 | On Windows, if you are running Tomcat as a service then defining ##CATALINA_OPTS## will not help. There is an utility provided in the ##bin## folder of your Tomcat installation (for example for Tomcat 5.x on Windows it's called tomcat5w.exe). It's a GUI tool which can be used to set various options including the heap size. |
| 181 | |||
| |
5.2 | 182 | == Java Security Manager == |
| |
1.16 | 183 | |
 |
16.1 | 184 | By default Tomcat is configured to have the Java Security Manager turned on. See the [[sample policy file>>AdminGuide.InstallationWAR#HInstallandconfigureaServletContainer]] for more details. |
| |
1.16 | 185 | |
| |
16.2 | 186 | If you want to turn off the Java Security Manager for Tomcat, edit the Tomcat startup script. You might also want to check your ##/etc/init.d/tomcat## file or ##/etc/default/tomcat5.5##. You should see the following code: |
| |
5.1 | 187 | |
| 188 | {{code}} | ||
| |
1.16 | 189 | # Use the Java security manager? (yes/no) |
| 190 | TOMCAT5_SECURITY= | ||
| |
5.1 | 191 | {{/code}} |
| |
1.16 | 192 | |
| |
5.2 | 193 | Set it to ##no## to turn off the Security Manager. |
| |
11.1 | 194 | |
| 195 | == Allowing "/" in page names == | ||
| 196 | |||
| |
16.2 | 197 | Tomcat completely freaks out when there's a ##%2F## in URLs and it's not something that can be changed in XWiki. See [[this note>>http://tomcat.apache.org/security-6.html#Fixed_in_Apache_Tomcat_6.0.10]] for more information. |
| |
11.1 | 198 | |
| 199 | You can configure Tomcat to allow this, by enabling : | ||
| 200 | |||
| 201 | {{code}} | ||
| 202 | org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH | ||
| 203 | {{/code}} | ||
| |
12.1 | 204 | |
| |
25.1 | 205 | Note that if you're using Apache you also need to [[configure Apache to allow encoded / and \>>https://httpd.apache.org/docs/current/mod/core.html#allowencodedslashes]]. |
| 206 | |||
| |
21.1 | 207 | == NotSerializableException == |
| 208 | |||
| 209 | If you get the following: | ||
| 210 | |||
| 211 | {{code}} | ||
| 212 | SEVERE: IOException while loading persisted sessions: java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer | ||
| 213 | java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer | ||
| 214 | at java.io.ObjectInputStream.readObject0(Unknown Source) | ||
| 215 | at java.io.ObjectInputStream.defaultReadFields(Unknown Source) | ||
| 216 | {{/code}} | ||
| 217 | |||
| 218 | This means that on startup Tomcat tries to load saved Sessions and fails to do so. In this case it fails because some non-serializable object was put in the Servlet Session. To work around the issue [[you can tell Tomcat to not save sessions>>http://dev-answers.blogspot.fr/2007/03/how-to-turn-off-tomcat-session.html]]. | ||
| 219 | |||
| |
12.1 | 220 | == SEVERE: Error listenerStart == |
| 221 | |||
| |
24.2 | 222 | If you get this error in your Tomcat logs then you'll need to enable finer-grained logging configuration to see what's the problem. For Tomcat 6.x/7.x this involves copying the following content in a ##WEB-INF/classes/logging.properties## file: |
| |
12.1 | 223 | |
| 224 | {{code}} | ||
| 225 | org.apache.catalina.core.ContainerBase.[Catalina].level = INFO | ||
| 226 | org.apache.catalina.core.ContainerBase.[Catalina].handlers = java.util.logging.ConsoleHandler | ||
| 227 | {{/code}} |
