Skip to Content

Wiki source code of Tomcat Installation

Last modified by Thomas Mortagne on 2025/04/10
Hide last authors
Dmitry Bakbardin 13.4 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Vincent Massol 11.1 4
Vincent Massol 5.2 5 = Installation Steps =
vmassol 1.1 6
Thomas Mortagne 100.1 7 * Download and install [[Tomcat>>http://tomcat.apache.org/]]. There are plenty of ways to install Tomcat, refer to the Tomcat site for more information. Let's call ##TOMCAT_HOME## the directory where it's installed.(((
8 {{info title="But you will need to choose the right version of Tomcat"}}
9 |=XWiki versions|=Minimum Tomcat version|=Maximum Tomcat version
Thomas Mortagne 100.4 10 |12.x to 16.x|8|9
11 |17.x and more|10|-
Thomas Mortagne 100.1 12 {{/info}}
Thomas Mortagne 100.2 13
Thomas Mortagne 61.1 14 {{warning}}
Vincent Massol 84.4 15 * Tomcat 9.0.70 has some bugs that make it fail with XWiki. See:
Vincent Massol 84.7 16 ** -- https://jira.xwiki.org/browse/XWIKI-20470 -- (A Tomcat regression now fixed in Tomcat 9.0.71+)
Thomas Mortagne 61.1 17 {{/warning}}
18 )))
Thomas Mortagne 85.1 19 * Make sure you [[give enough memory to Java>>Documentation.AdminGuide.InstallationTomcat#HOutOfMemoryError]] since by default Tomcat is not configured with enough memory for XWiki.
Thomas Mortagne 38.1 20 * Extract the [[XWiki WAR>>xwiki:Main.Download]] into a directory named ##xwiki## in ##TOMCAT_HOME/webapps/##
Thomas Mortagne 85.1 21 * Open ##TOMCAT_HOME/webapps/xwiki/WEB-INF/xwiki.properties## files and [[configure a permanent directory>>Documentation.AdminGuide.Configuration#HConfiguringDirectories]]
Vincent Massol 36.3 22 * Start Tomcat
Simon Urli 48.1 23 * When Tomcat has opened go to your wiki by accessing [[http:~~/~~/localhost:8080/xwiki/bin/view/Main/>>http://localhost:8080/xwiki/bin/view/Main/]]
Vincent Massol 36.2 24 * NOTE - if you have issues with maximum cache size - In your ##$CATALINA_BASE/conf/context.xml## add the following content before ##</Context>##:(((
Jan-Paul Kleijn 75.1 25 {{code language="none"}}
逸恒 吴 57.1 26 <Resources cachingAllowed="true" cacheMaxSize="100000" ></Resources>
Vincent Massol 36.2 27 {{/code}}
28 )))
vmassol 1.4 29
Vincent Massol 11.1 30 == Activate headless mode ==
mawoki 10.1 31
32 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:
33
Vincent Massol 24.6 34 * ##Exception: Could not initialize class sun.awt.X11.XToolkit##
35 * ##java.lang.InternalError: Can't connect to X11 window server using 'localhost:10.0' as the value of the DISPLAY variable##
Christian 84.1 36 * ##Error number 0 in 11: Uncaught exception##
37 * ##java.lang.NoClassDefFoundError: Could not initialize class java.awt.GraphicsEnvironment$LocalGE##
38
Vincent Massol 24.6 39 * On Linux create a file ##///TOMCAT_HOME///bin/setenv.sh## and insert the following code:(((
Jan-Paul Kleijn 75.1 40 {{code language="none"}}
Vincent Massol 24.6 41 #!/bin/sh
42 export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"
Vincent Massol 24.7 43 {{/code}}
Vincent Massol 24.6 44 )))
45 * On Windows create a file ##///TOMCAT_HOME///bin/setenv.bat## and insert the following code:(((
Jan-Paul Kleijn 75.1 46 {{code language="none"}}
chuck_liu 27.1 47 set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true
48 {{/code}}
Vincent Massol 24.6 49 )))
Manuel Smeria 16.2 50 * 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.
mawoki 9.1 51
Vincent Massol 11.1 52 == Optional configuration ==
mawoki 9.1 53
Jan-Paul Kleijn 71.1 54 * To enable gzip compression the connector property in the ##server.xml## file needs to be modified. The location of the ##server.xml## file is found at:
55 - On Linux: ##/etc/tomcat[version]/server.xml##
Jan-Paul Kleijn 74.1 56 - On Windows: ##//TOMCAT_HOME///conf/server.xml##(((
57 {{code language="none"}}
58 <Connector port="8080"
59 ...
60 compression="on"
61 compressionMinSize="2048"
62 compressibleMimeType="text/html,text/xml,text/css,text/javascript,application/x-javascript">
63 </Connector>
64 {{/code}}
Jan-Paul Kleijn 73.1 65 )))
Jan-Paul Kleijn 71.1 66 * To modify the port on which Tomcat will run, search in ##server.xml## for all instances of {{code}}8080{{/code}} (in Linux this can also be {{code}}8180{{/code}}) and replace this with the port value you wish to use.
67 * 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||rel="noopener noreferrer" target="new"]].
Jan-Paul Kleijn 78.3 68 The only reason to make Tomcat a daemon is to make it runnable on port 80, which can be replaced by using a proxy server (such as NginX or Apache) on port 80 and then forwarding to Tomcat on port 8080.
mawoki 9.1 69
HoaniCross 19.1 70 == Policy configuration ==
71
Vincent Massol 24.6 72 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 :
HoaniCross 19.1 73
Jan-Paul Kleijn 75.1 74 {{code language="none"}}
HoaniCross 19.1 75 grant codeBase "file:${catalina.base}/webapps/xwiki/WEB-INF/lib/-" {
76 // for mySQL connection
77 permission java.net.SocketPermission "127.0.0.1:3306", "connect,resolve";
78
79 // XWiki must have access to all properties in read/write
80 permission java.util.PropertyPermission "*", "read, write";
81
82 // Generic detected permissions
83 permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
84 permission java.lang.RuntimePermission "createClassLoader";
85 permission java.lang.RuntimePermission "setContextClassLoader";
86 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.loader";
87 permission java.lang.RuntimePermission "accessDeclaredMembers";
88 permission java.lang.RuntimePermission "getenv.ProgramFiles";
89 permission java.lang.RuntimePermission "getenv.APPDATA";
90 permission java.lang.RuntimePermission "accessClassInPackage.sun.reflect";
91 permission java.lang.RuntimePermission "getClassLoader";
92 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.connector";
HoaniCross 20.1 93 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.tomcat.util.threads";
HoaniCross 19.1 94 permission java.lang.RuntimePermission "reflectionFactoryAccess";
95 permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.interceptor";
96 permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.mbeanserver";
97 permission java.lang.RuntimePermission "modifyThread";
98 permission java.lang.RuntimePermission "getProtectionDomain";
99
100 // JAXB permissions
101 permission javax.xml.bind.JAXBPermission "setDatatypeConverter";
102
103 // Serialization related permissions
104 permission java.io.SerializablePermission "allowSerializationReflection";
105 permission java.io.SerializablePermission "creator";
106 permission java.io.SerializablePermission "enableSubclassImplementation";
107
108 // Internal resources access permissions
109 permission java.io.FilePermission "synonyms.txt", "read";
110 permission java.io.FilePermission "lang/synonyms_en.txt", "read";
111 permission java.io.FilePermission "quartz.properties", "read";
112 permission java.io.FilePermission "/templates/-", "read";
113 permission java.io.FilePermission "/skins/-", "read";
114 permission java.io.FilePermission "/resources/-", "read";
115
116 // MBean related permissions
117 permission javax.management.MBeanServerPermission "createMBeanServer";
118 permission javax.management.MBeanPermission "*", "registerMBean";
119 permission javax.management.MBeanPermission "*", "unregisterMBean";
120 permission javax.management.MBeanTrustPermission "register";
121 permission javax.management.MBeanPermission "-#-[-]", "queryNames";
122 permission javax.management.MBeanServerPermission "findMBeanServer";
123
124 // LibreOffice/OpenOffice related permissions
125 permission java.io.FilePermission "/opt/openoffice.org3/program/soffice.bin", "read";
126 permission java.io.FilePermission "/opt/libreoffice/program/soffice.bin", "read";
127 permission java.io.FilePermission "/usr/lib/openoffice/program/soffice.bin", "read";
128 permission java.io.FilePermission "/usr/lib/libreoffice/program/soffice.bin", "read";
129
130 // Allow file storage directory reading - for directory and everything underneath
131 // This is dependent on the setting of environment.permanentDirectory in xwiki.properties
132 permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}", "read,write,delete";
133 permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}-", "read,write,delete";
134
135 // Allow file storage directory reading - temporary directory and everything underneath
136 // This is dependent on the setting of environment.temporaryDirectory in xwiki.properties.
137 permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}", "read,write,delete";
138 permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}-", "read,write,delete";
139 };
140 {{/code}}
141
Vincent Massol 54.1 142 Please note that this policy configuration file has been tested on CentOS 5.9 with Sun JDK 1.7.0u21 on Tomcat 7.0.40 with XWiki 5.0.1 installed.
HoaniCross 19.1 143
Thomas Mortagne 93.1 144 == HTTP reverse proxy ==
Dmitry Bakbardin 13.4 145
Thomas Mortagne 92.1 146 For a [[variety of reasons>>https://en.wikipedia.org/wiki/Reverse_proxy||rel="__blank"]], it is not ideal to allow users to connect directly to tomcat. So it's generally recommended to put an HTTP reverse proxy such as Apache HTTP Server or Nginx in front of it.
Thomas Mortagne 89.1 147
Thomas Mortagne 93.1 148 === Using Apache HTTP Server ===
Thomas Mortagne 89.1 149
Thomas Mortagne 97.1 150 For setup example with Apache HTTP Server, in production : [[Documentation.AdminGuide.Installation.ApacheHTTPD]].
Thomas Mortagne 89.1 151
Thomas Mortagne 93.1 152 === Using Nginx ===
Thomas Mortagne 89.1 153
Thomas Mortagne 91.1 154 Another popular choice for a reverse-proxy web server is [[Nginx>>http://wiki.nginx.org/Main||rel="__blank"]]. These instructions will walk through a very basic deployment of nginx acting as a reverse-proxy for the tomcat XWiki application.
Dmitry Bakbardin 13.4 155
Craig Wright 30.1 156 After a typical XWiki installation XWiki will be running on ##http:~/~/localhost:8080/xwiki##. Ultimately we will want to access XWiki via ##http:~/~/mydomain.com## on a standard http (80) or https (443) port. To accomplish this for unsecure http traffic, the following basic config file gets us started.
Dmitry Bakbardin 13.4 157
Thomas Mortagne 93.1 158 ==== Http (unsecure) ====
Craig Wright 30.1 159
Manuel Smeria 16.2 160 * create this file ##/etc/nginx/conf.d/tomcat.conf##
Christian 84.1 161 * put the following code inside:(((
162 {{code language="none"}}
163 server {
Dmitry Bakbardin 14.1 164 listen 80;
165 server_name mydomain.com;
Dmitry Bakbardin 13.4 166
Craig Wright 30.1 167 # Normally root should not be accessed, however, root should not serve files that might compromise the security of your server.
168 root /var/www/html;
169
Ludovic Dubost 62.1 170 # Configuration to avoid Request Entity too large error 413
171 client_max_body_size 0;
172
Dmitry Bakbardin 14.1 173 location / {
Craig Wright 30.1 174 # All "root" requests will have /xwiki appended AND redirected to mydomain.com
Dmitry Bakbardin 14.1 175 rewrite ^ $scheme://$server_name/xwiki$request_uri? permanent;
176 }
Dmitry Bakbardin 13.4 177
Dmitry Bakbardin 14.1 178 location ^~ /xwiki {
chuck_liu 27.1 179 # If path starts with /xwiki - then redirect to backend: XWiki application in Tomcat
180 # Read more about proxy_pass: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass
181 proxy_pass http://localhost:8080;
Jesse Bright 28.3 182 proxy_set_header X-Real-IP $remote_addr;
183 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
184 proxy_set_header Host $http_host;
185 proxy_set_header X-Forwarded-Proto $scheme;
Dmitry Bakbardin 14.1 186 }
Christian 84.1 187 }
188 {{/code}}
Jan-Paul Kleijn 82.1 189 )))
Dmitry Bakbardin 14.1 190 * restart nginx
191
chuck_liu 27.1 192 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"]].
Dmitry Bakbardin 14.1 193
Thomas Mortagne 93.1 194 ==== Https (secure) ====
Craig Wright 30.1 195
196 There are many guides on how to create a secure configuration of nginx. To get started:
197
198 * [[Strong SSL Security on nginx>>https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html||rel="__blank"]]
199 * [[How To Secure Nginx With LetsEncrypt on Ubuntu 16.04>>https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-16-04||rel="__blank"]]
200
Craig Wright 31.1 201 The following config assumes you are using LetsEncrypt and that your XWiki is hosted on ##http:~/~/localhost:8080/##. This config will redirect all unsecure requests to https:~/~/ and set the correct proxy headers for a secure nginx+tomcat setup.
Craig Wright 30.1 202
Jan-Paul Kleijn 78.1 203 First, you will need to add the following config to tomcat's ##server.xml##. The first line should already be in the file, I include it to give you something to search for (that line is located on line 108 in the Ubuntu 16.04 tomcat8 package). This will help tomcat find your proxy headers.
Craig Wright 30.1 204
205 (((
Jan-Paul Kleijn 75.1 206 {{code language="none"}}
Craig Wright 30.1 207 <Engine name="Catalina" defaultHost="localhost">
208 <Valve className="org.apache.catalina.valves.RemoteIpValve"
209 internalProxies="127\.0\.[0-1]\.1"
210 remoteIpHeader="x-forwarded-for"
211 requestAttributesEnabled="true"
212 protocolHeader="x-forwarded-proto"
逸恒 吴 57.1 213 protocolHeaderHttpsValue="https"></Valve>
Craig Wright 30.1 214 {{/code}}
215 )))
216
217 Next, add the following nginx config file to your nginx config folder, replacing ##wiki.yourdomain.com## with your actual domain info:
218
219 (((
Jan-Paul Kleijn 75.1 220 {{code language="none"}}
Craig Wright 30.1 221 server {
222 listen 80;
223 server_name wiki.yourdomain.com;
224
225 location ~ /.well-known {
226 allow all;
227 }
228
229 rewrite ^ https://$server_name$request_uri? permanent;
230
231 access_log /var/log/nginx-xwiki/access.log;
232 error_log /var/log/nginx-xwiki/error.log;
233
234 }
235
236 server {
237 listen 443;
238 server_name wiki.yourdomain.com;
239
240 root /var/www/html;
241
Ludovic Dubost 62.1 242 # Configuration to avoid Request Entity too large error 413
243 client_max_body_size 0;
244
Craig Wright 30.1 245 ssl on;
246 ssl_certificate /etc/letsencrypt/live/wiki.yourdomain.com/fullchain.pem;
247 ssl_certificate_key /etc/letsencrypt/live/wiki.yourdomain.com/privkey.pem;
248
249 access_log /var/log/nginx-xwiki/access_ssl.log;
250 error_log /var/log/nginx-xwiki/error_ssl.log;
251
252 location / {
253 proxy_set_header Host $http_host;
254 proxy_set_header X-Real-IP $remote_addr;
255 proxy_set_header X-Forward-For $proxy_add_x_forwarded_for;
256 proxy_set_header X-Forwarded-Proto $scheme;
257 proxy_set_header X-Scheme $scheme;
258 proxy_redirect off;
259 if (!-f $request_filename) {
260 proxy_pass http://127.0.0.1:8080;
261 break;
262 }
263 }
264
265 location ~ /.well-known {
266 allow all;
267 }
268 }
269 {{/code}}
270 )))
271
272 For more background on this config, see the discussion on this ticket: [[XWIKI-13963>>http://jira.xwiki.org/browse/XWIKI-13963||rel="__blank"]].
273
Thomas Mortagne 93.1 274 ==== Proxying and tunnels ====
Paul Libbrecht 51.1 275
276 This proxy methods brings remote connections to local connection. This is complementary to SSH-tunneling which is easily done on port 8080 and can be used to test development servers.
277
Jan-Paul Kleijn 76.1 278 For example, if you are running an XWiki on port 80 on your laptop while running the NGinx (or Apache) on a server where it is accessible as ##https://wiki.yourdomain.com##, you can make your XWiki acessible with this URL:##
Paul Libbrecht 51.1 279
280 * First make sure that the port 8080 is not in use: You can proof this with ##{{{ssh server wget -O - https://127.0.0.1:8080/}}}## which should display the error message //Connection refused//. If not, something is running there and it should be stopped.
281 * You can then create the tunnel with the following ##ssh -R8080:127.0.0.1:8080 server##. This tells the server that incoming ("R"emote) connections on port 8080 on the server are to be tunnelled to the local (laptop) port 8080. This method has the advantage that the laptop (typically using a dynamic address) invokes the SSH where as a proxy configured on the server to proxy to the laptop would need to know the address of the laptop.
282
Jan-Paul Kleijn 67.1 283 = Recommendations =
Thomas Mortagne 65.1 284
Jan-Paul Kleijn 67.1 285 == Default encoding ==
Thomas Mortagne 65.1 286
Thomas Mortagne 66.1 287 XWiki strives to not be impacted by the default encoding, but it's still possible to have bugs or simply mistakes in extensions or tools used by XWiki (database connectors, etc.) so it's highly recommended to make sure Tomcat is started with utf8 as default encoding. If you use a Linux package of Tomcat this is generally set by default, but it might not always be the case. For that, make sure you have ##-Dfile.encoding=utf8## in the Java command line which starts Tomcat.
Thomas Mortagne 65.1 288
Vincent Massol 12.1 289 = Troubleshooting =
Vincent Massol 1.16 290
Vincent Massol 5.2 291 == Out Of Memory Error ==
Vincent Massol 1.16 292
Vincent Massol 64.2 293 === General Memory Settings ===
294
Thomas Mortagne 96.1 295 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>>Documentation.AdminGuide.Performances#HMemory]]. You'll need to allocate more memory to the JVM.
Vincent Massol 1.16 296
Thomas Mortagne 85.1 297 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>>Documentation.AdminGuide.Performances#HMemory]]). For example:
Sergiu Dumitriu 17.1 298
299 {{code language="none"}}
Vincent Massol 24.8 300 CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=192m"
Sergiu Dumitriu 17.1 301 {{/code}}
302
Thomas Mortagne 96.1 303 On most Linux distributions, this can also be achieved in ##/etc/default/tomcat//X//##, ##/etc/tomcat//X///tomcat//X//.conf## or ##/etc/conf.d/tomcat//X//.conf## (where //X// is the version of Tomcat installed).
Sergiu Dumitriu 17.1 304
Vincent Massol 22.1 305 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.
306
Thomas Mortagne 93.1 307 === NullPointerExceptions in catalina.log during startup on Ubuntu 23.x ===
308
Thomas Mortagne 96.1 309 Tomcat 9.0.70 has [[a very serious regression>>https://bz.apache.org/bugzilla/show_bug.cgi?id=66388]]. Unfortunately this is the version Ubuntu chose to put in its repository so you will be impacted with Ubuntu 23.04 and 23.10 at time of writing.
Thomas Mortagne 93.1 310
311 A possible workaround is to use the tomcat9 package coming for Ubuntu jammy (22.04) repository (9.0.58).
312
Vincent Massol 64.2 313 === Max number of threads ===
314
Rainer Stransky 64.1 315 On some Debian 10 installations there can be a limitation of the max number of threads for services started with ##systemd## (and ##tomcat9## is such a service), what can force problems with OOM Errors: ##Out Of Memory## error (##java.lang.OutOfMemoryError: unable to create native thread##)
Rainer Stransky 63.1 316
Rainer Stransky 64.1 317 If you have such messages in the ##catalina.out## check your default limitations of the ##systemd## with the command
Rainer Stransky 63.1 318
Jan-Paul Kleijn 76.1 319 {{code language="none"}}
Rainer Stransky 63.1 320 > systemctl show --property DefaultTasksMax
321 {{/code}}
322
323 For XWiki a value of about 100 is too low. Depending on the number of parallel users and sub wikis, this value should be larger. A value of about 512 should be sufficient.
324
325 Changing the parameter ##DefaultTasksMax## in ##/etc/systemd/system.conf## to a larger value, restarting the ##system-daemon## and ##tomcat9##, should solve the problem.
326
Jan-Paul Kleijn 76.1 327 {{code language="none"}}
Rainer Stransky 63.1 328 > systemctl daemon-reload
329 > systemctl restart tomcat9
330 {{/code}}
331
332 If the problem is not fixed with these changes, check the number of currently used threads by tomcat9 with the command
333
Jan-Paul Kleijn 76.1 334 {{code language="none"}}
Rainer Stransky 63.1 335 > ps -elfT | grep tomcat9| wc -l
336 {{/code}}
337
338 If the value is very near to the configured ##DefaultTasksMax##, you can try to increase it to an appropriate value.
339
Vincent Massol 5.2 340 == Java Security Manager ==
Vincent Massol 1.16 341
Thomas Mortagne 85.1 342 By default Tomcat is configured to have the Java Security Manager turned on. See the [[sample policy file>>Documentation.AdminGuide.InstallationWAR#HInstallandconfigureaServletContainer]] for more details.
Vincent Massol 1.16 343
Manuel Smeria 16.2 344 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:
dkBrazz 5.1 345
Jan-Paul Kleijn 76.1 346 {{code language="none"}}
Vincent Massol 1.16 347 # Use the Java security manager? (yes/no)
348 TOMCAT5_SECURITY=
dkBrazz 5.1 349 {{/code}}
Vincent Massol 1.16 350
Vincent Massol 5.2 351 Set it to ##no## to turn off the Security Manager.
Vincent Massol 11.1 352
Vincent Massol 44.1 353 == Allowing "/" and "\" in page names ==
Vincent Massol 11.1 354
Vincent Massol 44.1 355 Tomcat completely freaks out when there's a ##%2F## or ##%5C## 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.
Vincent Massol 11.1 356
Vincent Massol 50.2 357 You can configure Tomcat to allow "/", by setting the ##org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH## system property to ##true##, as in:
Vincent Massol 11.1 358
Jan-Paul Kleijn 76.1 359 {{code language="none"}}
Vincent Massol 50.1 360 -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
Vincent Massol 11.1 361 {{/code}}
Vincent Massol 12.1 362
Vincent Massol 50.1 363 And by setting the ##org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH## system property to ##true## to allow "\", as in:
Vincent Massol 25.1 364
Jan-Paul Kleijn 76.1 365 {{code language="none"}}
Vincent Massol 50.1 366 -Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true
Vincent Massol 44.1 367 {{/code}}
368
Vincent Massol 50.1 369 To have both properties permanently enabled on your Tomcat instance, add the lines below to your ##CATALINA_OPTS## environment variable. How to achieve this depends on your operating system, Tomcat distribution and single/multi-instance setup.
Vincent Massol 44.1 370
Jan-Paul Kleijn 76.1 371 {{code language="none"}}
Vincent Massol 50.1 372 -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
Vincent Massol 44.1 373 -Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true
374 {{/code}}
375
Vincent Massol 56.2 376 === Apache front-end server ===
Ludovic Dubost 56.1 377
Vincent Massol 56.2 378 Note that if you're using the Apache web server as a front-end, you also need to [[configure Apache to allow encoded / and \>>https://httpd.apache.org/docs/current/mod/core.html#allowencodedslashes]] (##AllowEncodedSlashes NoDecode##) and also make sure to use ##nocanon## on the [[ProxyPass line used>>https://httpd.apache.org/docs/2.4/mod/mod_proxy.html]].
Vincent Massol 44.1 379
Vincent Massol 21.1 380 == NotSerializableException ==
381
382 If you get the following:
383
Jan-Paul Kleijn 76.1 384 {{code language="none"}}
Vincent Massol 21.1 385 SEVERE: IOException while loading persisted sessions: java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer
386 java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer
Gabriela Anechitoaei 34.1 387 at java.io.ObjectInputStream.readObject0(Unknown Source)
388 at java.io.ObjectInputStream.defaultReadFields(Unknown Source)
Vincent Massol 21.1 389 {{/code}}
390
391 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]].
392
Vincent Massol 12.1 393 == SEVERE: Error listenerStart ==
394
Vincent Massol 54.2 395 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. This involves copying the following content in a ##WEB-INF/classes/logging.properties## file:
Vincent Massol 12.1 396
Jan-Paul Kleijn 76.1 397 {{code language="none"}}
Vincent Massol 12.1 398 org.apache.catalina.core.ContainerBase.[Catalina].level = INFO
399 org.apache.catalina.core.ContainerBase.[Catalina].handlers = java.util.logging.ConsoleHandler
400 {{/code}}
Simon Urli 46.1 401
402 == Parameter count exceeded allowed maximum ==
403
Vincent Massol 46.2 404 If you get an error such as the following it means you reached the limit of parameters you can send in a form.
Simon Urli 46.1 405
Jan-Paul Kleijn 76.1 406 {{code language="none"}}
Simon Urli 46.1 407 java.lang.IllegalStateException: Parameter count exceeded allowed maximum: 512
408 {{/code}}
409
Vincent Massol 46.2 410 You can set the value you want by setting the following in your Tomcat ##server.xml## file:
Simon Urli 46.1 411
Jan-Paul Kleijn 76.1 412 {{code language="none"}}
逸恒 吴 57.1 413 <Connector port=... maxParameterCount="10000" ></Connector>
Vincent Massol 46.2 414 {{/code}}
Vincent Massol 54.1 415
Vincent Massol 59.1 416 == ThreadLocal Errors ==
Vincent Massol 58.1 417
Vincent Massol 60.1 418 When you stop XWiki you may see the following type of errors in the Tomcat logs. This is a [[known limitation of XWiki in cleaning up some ThreadLocal variables>>https://jira.xwiki.org/browse/XWIKI-9055]]. To be safe, we recommend that you stop XWiki by stopping Tomcat (i.e. stopping the Tomcat JVM). This ensures that there won't be any memory leak related to these ThreadLocal variables. If you use the Tomcat Manager to stop the XWiki webapp (by undeploying it), then we recommend to not do that and instead to stop Tomcat and restart it.
Vincent Massol 58.1 419
420 {{code language="none"}}
421 SEVERE [Thread-794] org.apache.catalina.loader.WebappClassLoaderBase.checkThreadLocalMapForLeaks The web application [...] created a ThreadLocal with key of type [java.lang.ThreadLocal] (value [java.lang.ThreadLocal@1125fc78]) and a value of type [...] (value [...]) but failed to remove it when the web application was stopped. Threads are going to be renewed over time to try and avoid a probable memory leak.
422 {{/code}}
423
Vincent Massol 98.1 424 == Request header is too large ==
425
426 If you happen to see the navigation tree of XWiki failing to load (or some LiveData failing to load), and you have something like the following in the XWiki logs:
427
428 {{code language="none"}}
429 java.lang.IllegalArgumentException: Request header is too large
430 org.apache.coyote.http11.Http11InputBuffer.fill(Http11InputBuffer.java:785)
431 org.apache.coyote.http11.Http11InputBuffer.parseHeader(Http11InputBuffer.java:940)
432 org.apache.coyote.http11.Http11InputBuffer.parseHeaders(Http11InputBuffer.java:607)
433 org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:525)
434 org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:65)
435 org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:818)
436 org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1626)
437 org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49)
438 java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
439 java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
440 org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
441 java.base/java.lang.Thread.run(Thread.java:834)
442 {{/code}}
443
444 This could be caused by a large number of cookies.
445
446 To fix it, you'll need to [[increase the ##maxHttpHeaderSize## value for Tomcat (default is 8192)>>https://tomcat.apache.org/tomcat-9.0-doc/config/http.html]].
447
Vincent Massol 54.1 448 = Old Instructions =
449
450 Note that [[Tomat 7 is no longer supported>>dev:Community.SupportStrategy.ServletContainerSupportStrategy.WebHome]].
451
452 {{error}}
453 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>>https://jira.xwiki.org/browse/XWIKI-13556]] for some versions of Tomcat. Thus you should **not** use the following Tomcat versions:
454
455 * >= 9.0.0.M5 and < 9.0.0.M10 for the 9.0.x branch (fixed in 9.0.0.M10)
456 * >= 8.5.1 and < 8.5.5 for the 8.5.x branch (fixed in 8.5.5)
457 * >= 8.0.34 and < 8.0.37 for the 8.0.x branch (fixed in 8.0.37)
458 * >= 7.0.70 and < 7.0.71 for the 7.0.x branch (fixed in 7.0.71)
459
460 There is an important Classloader related bug in 8.0.32 which makes impossible to use the code macro or write Python scripts so you should avoid this version if possible. See https://bz.apache.org/bugzilla/show_bug.cgi?id=58999.
461 {{/error}}
462
463 * XWiki 12.0+ requires a Tomcat version >= 8 since it requires Servlet 3.1+
464 * Older versions of XWiki require a Tomcat version >= 7 since it requires Servlet 3.0+
Jan-Paul Kleijn 77.1 465 * Tomcat 7 is not using URF-8 by default. Edit the ##conf/server.xml## file to set the UTF-8 encoding:(((
Jan-Paul Kleijn 76.1 466 {{code language="none"}}
467 <Connector port="8080"
468 ...
469 URIEncoding="UTF-8">
470 </Connector>
Vincent Massol 54.1 471 {{/code}}
472 )))

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected