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 61.1 7 * Download and install [[Tomcat 8+>>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 {{warning}}
9 Using Tomcat 10 is not recommended right now since it moved to the incompatible Jakarta EE 9 API. See [[Apache Tomcat migration tool for Jakarta EE>>https://github.com/apache/tomcat-jakartaee-migration]] for mode details.
10 {{/warning}}
11 )))
Vincent Massol 42.3 12 * Make sure you [[give enough memory to Java>>platform:AdminGuide.InstallationTomcat#HOutOfMemoryError]] since by default Tomcat is not configured with enough memory for XWiki.
Thomas Mortagne 38.1 13 * Extract the [[XWiki WAR>>xwiki:Main.Download]] into a directory named ##xwiki## in ##TOMCAT_HOME/webapps/##
Thomas Mortagne 45.1 14 * Open ##TOMCAT_HOME/webapps/xwiki/WEB-INF/xwiki.properties## files and [[configure a permanent directory>>platform:AdminGuide.Configuration#HConfiguringDirectories]]
Vincent Massol 36.3 15 * Start Tomcat
Simon Urli 48.1 16 * 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 17 * NOTE - if you have issues with maximum cache size - In your ##$CATALINA_BASE/conf/context.xml## add the following content before ##</Context>##:(((
Vincent Massol 36.4 18 {{code}}
逸恒 吴 57.1 19 <Resources cachingAllowed="true" cacheMaxSize="100000" ></Resources>
Vincent Massol 36.2 20 {{/code}}
21 )))
vmassol 1.4 22
Vincent Massol 11.1 23 == Activate headless mode ==
mawoki 10.1 24
25 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:
26
Vincent Massol 24.6 27 * ##Exception: Could not initialize class sun.awt.X11.XToolkit##
28 * ##java.lang.InternalError: Can't connect to X11 window server using 'localhost:10.0' as the value of the DISPLAY variable##
mawoki 9.1 29
Vincent Massol 24.6 30 * On Linux create a file ##///TOMCAT_HOME///bin/setenv.sh## and insert the following code:(((
31 {{code}}
32 #!/bin/sh
33 export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"
Vincent Massol 24.7 34 {{/code}}
Vincent Massol 24.6 35 )))
36 * On Windows create a file ##///TOMCAT_HOME///bin/setenv.bat## and insert the following code:(((
Chuck Liu 27.1 37 {{code}}
38 set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true
39 {{/code}}
Vincent Massol 24.6 40 )))
Manuel Smeria 16.2 41 * 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 42
Vincent Massol 11.1 43 == Optional configuration ==
mawoki 9.1 44
逸恒 吴 57.1 45 * Edit your ##conf/server.xml## to enable gzip compression: {{code}}<Connector port="8080" ... compression="on" compressionMinSize="2048" compressibleMimeType="text/html,text/xml,text/css,text/javascript,application/x-javascript"></Connector>{{/code}}
mawoki 9.1 46 * 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.
Gabriela Anechitoaei 34.1 47 * 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"]]. 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.
mawoki 9.1 48
HoaniCross 19.1 49 == Policy configuration ==
50
Vincent Massol 24.6 51 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 52
53 {{code}}
54 grant codeBase "file:${catalina.base}/webapps/xwiki/WEB-INF/lib/-" {
55 // for mySQL connection
56 permission java.net.SocketPermission "127.0.0.1:3306", "connect,resolve";
57
58 // XWiki must have access to all properties in read/write
59 permission java.util.PropertyPermission "*", "read, write";
60
61 // Generic detected permissions
62 permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
63 permission java.lang.RuntimePermission "createClassLoader";
64 permission java.lang.RuntimePermission "setContextClassLoader";
65 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.loader";
66 permission java.lang.RuntimePermission "accessDeclaredMembers";
67 permission java.lang.RuntimePermission "getenv.ProgramFiles";
68 permission java.lang.RuntimePermission "getenv.APPDATA";
69 permission java.lang.RuntimePermission "accessClassInPackage.sun.reflect";
70 permission java.lang.RuntimePermission "getClassLoader";
71 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.connector";
HoaniCross 20.1 72 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.tomcat.util.threads";
HoaniCross 19.1 73 permission java.lang.RuntimePermission "reflectionFactoryAccess";
74 permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.interceptor";
75 permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.mbeanserver";
76 permission java.lang.RuntimePermission "modifyThread";
77 permission java.lang.RuntimePermission "getProtectionDomain";
78
79 // JAXB permissions
80 permission javax.xml.bind.JAXBPermission "setDatatypeConverter";
81
82 // Serialization related permissions
83 permission java.io.SerializablePermission "allowSerializationReflection";
84 permission java.io.SerializablePermission "creator";
85 permission java.io.SerializablePermission "enableSubclassImplementation";
86
87 // Internal resources access permissions
88 permission java.io.FilePermission "synonyms.txt", "read";
89 permission java.io.FilePermission "lang/synonyms_en.txt", "read";
90 permission java.io.FilePermission "quartz.properties", "read";
91 permission java.io.FilePermission "/templates/-", "read";
92 permission java.io.FilePermission "/skins/-", "read";
93 permission java.io.FilePermission "/resources/-", "read";
94
95 // MBean related permissions
96 permission javax.management.MBeanServerPermission "createMBeanServer";
97 permission javax.management.MBeanPermission "*", "registerMBean";
98 permission javax.management.MBeanPermission "*", "unregisterMBean";
99 permission javax.management.MBeanTrustPermission "register";
100 permission javax.management.MBeanPermission "-#-[-]", "queryNames";
101 permission javax.management.MBeanServerPermission "findMBeanServer";
102
103 // LibreOffice/OpenOffice related permissions
104 permission java.io.FilePermission "/opt/openoffice.org3/program/soffice.bin", "read";
105 permission java.io.FilePermission "/opt/libreoffice/program/soffice.bin", "read";
106 permission java.io.FilePermission "/usr/lib/openoffice/program/soffice.bin", "read";
107 permission java.io.FilePermission "/usr/lib/libreoffice/program/soffice.bin", "read";
108
109 // Allow file storage directory reading - for directory and everything underneath
110 // This is dependent on the setting of environment.permanentDirectory in xwiki.properties
111 permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}", "read,write,delete";
112 permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}-", "read,write,delete";
113
114 // Allow file storage directory reading - temporary directory and everything underneath
115 // This is dependent on the setting of environment.temporaryDirectory in xwiki.properties.
116 permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}", "read,write,delete";
117 permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}-", "read,write,delete";
118 };
119 {{/code}}
120
Vincent Massol 54.1 121 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 122
Craig Wright 30.1 123 == Using Nginx as a reverse-proxy for Tomcat (http/https) ==
Dmitry Bakbardin 13.4 124
Craig Wright 30.1 125 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. A 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 126
Craig Wright 30.1 127 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 128
Craig Wright 30.1 129 === http (unsecure) ===
130
Manuel Smeria 16.2 131 * create this file ##/etc/nginx/conf.d/tomcat.conf##
132 * put the following code inside:(((
Dmitry Bakbardin 14.1 133 {{code}}
134 server {
135 listen 80;
136 server_name mydomain.com;
Dmitry Bakbardin 13.4 137
Craig Wright 30.1 138 # Normally root should not be accessed, however, root should not serve files that might compromise the security of your server.
139 root /var/www/html;
140
Ludovic Dubost 62.1 141 # Configuration to avoid Request Entity too large error 413
142 client_max_body_size 0;
143
Dmitry Bakbardin 14.1 144 location / {
Craig Wright 30.1 145 # All "root" requests will have /xwiki appended AND redirected to mydomain.com
Dmitry Bakbardin 14.1 146 rewrite ^ $scheme://$server_name/xwiki$request_uri? permanent;
147 }
Dmitry Bakbardin 13.4 148
Dmitry Bakbardin 14.1 149 location ^~ /xwiki {
Chuck Liu 27.1 150 # If path starts with /xwiki - then redirect to backend: XWiki application in Tomcat
151 # Read more about proxy_pass: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass
152 proxy_pass http://localhost:8080;
Jesse Bright 28.3 153 proxy_set_header X-Real-IP $remote_addr;
154 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
155 proxy_set_header Host $http_host;
156 proxy_set_header X-Forwarded-Proto $scheme;
Dmitry Bakbardin 14.1 157 }
158 }
159 {{/code}}
Vincent Massol 15.2 160 )))
Dmitry Bakbardin 14.1 161 * restart nginx
162
Chuck Liu 27.1 163 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 164
Craig Wright 30.1 165 === https (secure) ===
166
167 There are many guides on how to create a secure configuration of nginx. To get started:
168
169 * [[Strong SSL Security on nginx>>https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html||rel="__blank"]]
170 * [[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"]]
171
Craig Wright 31.1 172 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 173
174 First, you will need to add the following config to tomcat's ##server.xml## (located at ##/etc/tomcat8/server.xml## on Ubuntu 16.04). 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.
175
176 (((
177 {{code}}
178 <Engine name="Catalina" defaultHost="localhost">
179 <Valve className="org.apache.catalina.valves.RemoteIpValve"
180 internalProxies="127\.0\.[0-1]\.1"
181 remoteIpHeader="x-forwarded-for"
182 requestAttributesEnabled="true"
183 protocolHeader="x-forwarded-proto"
逸恒 吴 57.1 184 protocolHeaderHttpsValue="https"></Valve>
Craig Wright 30.1 185 {{/code}}
186 )))
187
188 Next, add the following nginx config file to your nginx config folder, replacing ##wiki.yourdomain.com## with your actual domain info:
189
190 (((
191 {{code}}
192 server {
193 listen 80;
194 server_name wiki.yourdomain.com;
195
196 location ~ /.well-known {
197 allow all;
198 }
199
200 rewrite ^ https://$server_name$request_uri? permanent;
201
202 access_log /var/log/nginx-xwiki/access.log;
203 error_log /var/log/nginx-xwiki/error.log;
204
205 }
206
207 server {
208 listen 443;
209 server_name wiki.yourdomain.com;
210
211 root /var/www/html;
212
Ludovic Dubost 62.1 213 # Configuration to avoid Request Entity too large error 413
214 client_max_body_size 0;
215
Craig Wright 30.1 216 ssl on;
217 ssl_certificate /etc/letsencrypt/live/wiki.yourdomain.com/fullchain.pem;
218 ssl_certificate_key /etc/letsencrypt/live/wiki.yourdomain.com/privkey.pem;
219
220 access_log /var/log/nginx-xwiki/access_ssl.log;
221 error_log /var/log/nginx-xwiki/error_ssl.log;
222
223 location / {
224 proxy_set_header Host $http_host;
225 proxy_set_header X-Real-IP $remote_addr;
226 proxy_set_header X-Forward-For $proxy_add_x_forwarded_for;
227 proxy_set_header X-Forwarded-Proto $scheme;
228 proxy_set_header X-Scheme $scheme;
229 proxy_redirect off;
230 if (!-f $request_filename) {
231 proxy_pass http://127.0.0.1:8080;
232 break;
233 }
234 }
235
236 location ~ /.well-known {
237 allow all;
238 }
239 }
240 {{/code}}
241 )))
242
243 For more background on this config, see the discussion on this ticket: [[XWIKI-13963>>http://jira.xwiki.org/browse/XWIKI-13963||rel="__blank"]].
244
Paul Libbrecht 51.1 245 === Proxying and tunnels ===
246
247 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.
248
249 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:
250
251 * 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.
252 * 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.
253
Craig Wright 32.1 254 == Configuring tomcat for https ==
Lukas Raska 23.1 255
逸恒 吴 57.1 256 Although allowing users to directly connect to tomcat is not recommended, for a variety of reasons it may be desirable to configure tomcat to serve pages over an https connection.If using another server as a HTTPS proxy (such as Nginx or Apache httpd), follow instruction below to avoid unexpected error (such as "failed to lock page").
Craig Wright 32.1 257
258 * If using HTTPS for accessing XWiki, several modifications have to be made to ensure proper 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.)
逸恒 吴 57.1 259 * Modify connector (in ##server.xml##) to {{code}}<Connector port="8080" ... secure="true" scheme="https" ></Connector>{{/code}}
260 * 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" ></Valve>{{/code}} (only needed if using another server for HTTPS)
Lukas Raska 23.1 261
Chuck Liu 27.1 262 {{info}}
逸恒 吴 57.1 263 Set X-Forwarded-For and X-Forwarded-Proto headers on HTTPS guard server(on which Apache httpd or Nginx runs)!
Chuck Liu 27.1 264 {{/info}}
Lukas Raska 23.1 265
Vincent Massol 12.1 266 = Troubleshooting =
Vincent Massol 1.16 267
Vincent Massol 5.2 268 == Out Of Memory Error ==
Vincent Massol 1.16 269
Vincent Massol 22.1 270 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.
Vincent Massol 1.16 271
Vincent Massol 24.8 272 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:
Sergiu Dumitriu 17.1 273
274 {{code language="none"}}
Vincent Massol 24.8 275 CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=192m"
Sergiu Dumitriu 17.1 276 {{/code}}
277
Vincent Massol 22.1 278 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).
Sergiu Dumitriu 17.1 279
Vincent Massol 22.1 280 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.
281
Vincent Massol 5.2 282 == Java Security Manager ==
Vincent Massol 1.16 283
Vincent Massol 42.3 284 By default Tomcat is configured to have the Java Security Manager turned on. See the [[sample policy file>>platform:AdminGuide.InstallationWAR#HInstallandconfigureaServletContainer]] for more details.
Vincent Massol 1.16 285
Manuel Smeria 16.2 286 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 287
288 {{code}}
Vincent Massol 1.16 289 # Use the Java security manager? (yes/no)
290 TOMCAT5_SECURITY=
dkBrazz 5.1 291 {{/code}}
Vincent Massol 1.16 292
Vincent Massol 5.2 293 Set it to ##no## to turn off the Security Manager.
Vincent Massol 11.1 294
Vincent Massol 44.1 295 == Allowing "/" and "\" in page names ==
Vincent Massol 11.1 296
Vincent Massol 44.1 297 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 298
Vincent Massol 50.2 299 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 300
301 {{code}}
Vincent Massol 50.1 302 -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
Vincent Massol 11.1 303 {{/code}}
Vincent Massol 12.1 304
Vincent Massol 50.1 305 And by setting the ##org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH## system property to ##true## to allow "\", as in:
Vincent Massol 25.1 306
Vincent Massol 44.1 307 {{code}}
Vincent Massol 50.1 308 -Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true
Vincent Massol 44.1 309 {{/code}}
310
Vincent Massol 50.1 311 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 312
313 {{code}}
Vincent Massol 50.1 314 -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
Vincent Massol 44.1 315 -Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true
316 {{/code}}
317
Vincent Massol 56.2 318 === Apache front-end server ===
Ludovic Dubost 56.1 319
Vincent Massol 56.2 320 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 321
Vincent Massol 21.1 322 == NotSerializableException ==
323
324 If you get the following:
325
326 {{code}}
327 SEVERE: IOException while loading persisted sessions: java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer
328 java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer
Gabriela Anechitoaei 34.1 329 at java.io.ObjectInputStream.readObject0(Unknown Source)
330 at java.io.ObjectInputStream.defaultReadFields(Unknown Source)
Vincent Massol 21.1 331 {{/code}}
332
333 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]].
334
Vincent Massol 12.1 335 == SEVERE: Error listenerStart ==
336
Vincent Massol 54.2 337 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 338
339 {{code}}
340 org.apache.catalina.core.ContainerBase.[Catalina].level = INFO
341 org.apache.catalina.core.ContainerBase.[Catalina].handlers = java.util.logging.ConsoleHandler
342 {{/code}}
Simon Urli 46.1 343
344 == Parameter count exceeded allowed maximum ==
345
Vincent Massol 46.2 346 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 347
348 {{code}}
349 java.lang.IllegalStateException: Parameter count exceeded allowed maximum: 512
350 {{/code}}
351
Vincent Massol 46.2 352 You can set the value you want by setting the following in your Tomcat ##server.xml## file:
Simon Urli 46.1 353
Vincent Massol 46.2 354 {{code}}
逸恒 吴 57.1 355 <Connector port=... maxParameterCount="10000" ></Connector>
Vincent Massol 46.2 356 {{/code}}
Vincent Massol 54.1 357
Vincent Massol 59.1 358 == ThreadLocal Errors ==
Vincent Massol 58.1 359
Vincent Massol 60.1 360 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 361
362 {{code language="none"}}
363 SEVERE [Thread-794] org.apache.catalina.loader.WebappClassLoaderBase.checkThreadLocalMapForLeaks The web application [...] created a ThreadLocal with key of type [java.lang.ThreadLocal] (value [[email protected]]) 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.
364 {{/code}}
365
Vincent Massol 54.1 366 = Old Instructions =
367
368 Note that [[Tomat 7 is no longer supported>>dev:Community.SupportStrategy.ServletContainerSupportStrategy.WebHome]].
369
370 {{error}}
371 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:
372
373 * >= 9.0.0.M5 and < 9.0.0.M10 for the 9.0.x branch (fixed in 9.0.0.M10)
374 * >= 8.5.1 and < 8.5.5 for the 8.5.x branch (fixed in 8.5.5)
375 * >= 8.0.34 and < 8.0.37 for the 8.0.x branch (fixed in 8.0.37)
376 * >= 7.0.70 and < 7.0.71 for the 7.0.x branch (fixed in 7.0.71)
377
378 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.
379 {{/error}}
380
381 * XWiki 12.0+ requires a Tomcat version >= 8 since it requires Servlet 3.1+
382 * Older versions of XWiki require a Tomcat version >= 7 since it requires Servlet 3.0+
383 * Tomcat 7 is not using URF-8 by default. Edit the ##conf/server.xml## file to set the UTF-8 encoding:(((
384 {{code}}
逸恒 吴 57.1 385 <Connector port="8080" ... URIEncoding="UTF-8"></Connector>
Vincent Massol 54.1 386 {{/code}}
387 )))

Get Connected