Tomcat Installation (XWiki.org)

= Installation Steps =

* 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

|12.x to 16.x|8|9

|17.x and more|10|-

* Tomcat 9.0.70 has some bugs that make it fail with XWiki. See:

16

** -- https://jira.xwiki.org/browse/XWIKI-20470 -- (A Tomcat regression now fixed in Tomcat 9.0.71+)

17

18

)))

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.

20

* Extract the [[XWiki WAR>>xwiki:Main.Download]] into a directory named ##xwiki## in ##TOMCAT_HOME/webapps/##

21

* Open ##TOMCAT_HOME/webapps/xwiki/WEB-INF/xwiki.properties## files and [[configure a permanent directory>>Documentation.AdminGuide.Configuration#HConfiguringDirectories]]

22

* Start Tomcat

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/]]

24

* NOTE - if you have issues with maximum cache size - In your ##$CATALINA_BASE/conf/context.xml## add the following content before ##</Context>##:(((

)))

== Activate headless mode ==

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

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##

36

* ##Error number 0 in 11: Uncaught exception##

37

* ##java.lang.NoClassDefFoundError: Could not initialize class java.awt.GraphicsEnvironment$LocalGE##

38

39

* On Linux create a file ##///TOMCAT_HOME///bin/setenv.sh## and insert the following code:(((

40

41

#!/bin/sh

42

export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"

43

44

)))

45

* On Windows create a file ##///TOMCAT_HOME///bin/setenv.bat## and insert the following code:(((

46

47

set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true

48

49

)))

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.

51

52

== Optional configuration ==

53

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##

56

- On Windows: ##//TOMCAT_HOME///conf/server.xml##(((

57

58

<Connector port="8080"

59

...

60

compression="on"

61

compressionMinSize="2048"

62

compressibleMimeType="text/html,text/xml,text/css,text/javascript,application/x-javascript">

</Connector>

)))

* 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"]].

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.

69

70

== Policy configuration ==

71

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 :

73

74

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";

93

permission java.lang.RuntimePermission "accessClassInPackage.org.apache.tomcat.util.threads";

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";

};

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.

143

144

== HTTP reverse proxy ==

145

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.

147

148

=== Using Apache HTTP Server ===

149

150

For setup example with Apache HTTP Server, in production : [[Documentation.AdminGuide.Installation.ApacheHTTPD]].

=== Using Nginx ===

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.

155

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.

157

158

==== Http (unsecure) ====

159

160

* create this file ##/etc/nginx/conf.d/tomcat.conf##

161

* put the following code inside:(((

server {

listen 80;

server_name mydomain.com;

166

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

170

# Configuration to avoid Request Entity too large error 413

171

client_max_body_size 0;

172

173

location / {

174

# All "root" requests will have /xwiki appended AND redirected to mydomain.com

175

rewrite ^ $scheme://$server_name/xwiki$request_uri? permanent;

}

location ^~ /xwiki {

# 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;

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;

}

}

)))

* restart nginx

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"]].

193

194

==== Https (secure) ====

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

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.

202

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.

(((

<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"

213

protocolHeaderHttpsValue="https"></Valve>

)))

Next, add the following nginx config file to your nginx config folder, replacing ##wiki.yourdomain.com## with your actual domain info:

(((

server {

listen 80;

server_name wiki.yourdomain.com;

224

225

location ~ /.well-known {

allow all;

}

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;

}

server {

listen 443;

server_name wiki.yourdomain.com;

root /var/www/html;

# Configuration to avoid Request Entity too large error 413

243

client_max_body_size 0;

244

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;

break;

}

}

location ~ /.well-known {

allow all;

}

}

)))

For more background on this config, see the discussion on this ticket: [[XWIKI-13963>>http://jira.xwiki.org/browse/XWIKI-13963||rel="__blank"]].

273

274

==== Proxying and tunnels ====

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

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:##

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.

= Recommendations =

== Default encoding ==

286

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.

= Troubleshooting =

== Out Of Memory Error ==

292

293

=== General Memory Settings ===

294

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.

296

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:

298

299

300

CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=192m"

301

302

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).

304

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

307

=== NullPointerExceptions in catalina.log during startup on Ubuntu 23.x ===

308

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.

310

311

A possible workaround is to use the tomcat9 package coming for Ubuntu jammy (22.04) repository (9.0.58).

312

313

=== Max number of threads ===

314

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##)

316

317

If you have such messages in the ##catalina.out## check your default limitations of the ##systemd## with the command

318

319

320

> systemctl show --property DefaultTasksMax

321

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

327

328

> systemctl daemon-reload

329

> systemctl restart tomcat9

330

331

332

If the problem is not fixed with these changes, check the number of currently used threads by tomcat9 with the command

333

334

335

> ps -elfT | grep tomcat9| wc -l

336

337

338

If the value is very near to the configured ##DefaultTasksMax##, you can try to increase it to an appropriate value.

339

340

== Java Security Manager ==

341

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.

343

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:

345

346

347

# Use the Java security manager? (yes/no)

TOMCAT5_SECURITY=

Set it to ##no## to turn off the Security Manager.

352

353

== Allowing "/" and "\" in page names ==

354

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.

356

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:

358

359

360

-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

361

362

363

And by setting the ##org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH## system property to ##true## to allow "\", as in:

364

365

366

-Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true

367

368

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.

370

371

372

-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

373

-Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true

374

375

376

=== Apache front-end server ===

377

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]].

379

380

== NotSerializableException ==

381

382

If you get the following:

383

384

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

387

at java.io.ObjectInputStream.readObject0(Unknown Source)

388

at java.io.ObjectInputStream.defaultReadFields(Unknown Source)

389

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

393

== SEVERE: Error listenerStart ==

394

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:

396

397

398

org.apache.catalina.core.ContainerBase.[Catalina].level = INFO

399

org.apache.catalina.core.ContainerBase.[Catalina].handlers = java.util.logging.ConsoleHandler

400

401

402

== Parameter count exceeded allowed maximum ==

403

404

If you get an error such as the following it means you reached the limit of parameters you can send in a form.

405

406

407

java.lang.IllegalStateException: Parameter count exceeded allowed maximum: 512

408

409

410

You can set the value you want by setting the following in your Tomcat ##server.xml## file:

== ThreadLocal Errors ==

417

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.

419

420

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

423

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

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

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]].

= Old Instructions =

Note that [[Tomat 7 is no longer supported>>dev:Community.SupportStrategy.ServletContainerSupportStrategy.WebHome]].

451

452

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

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+

465

* Tomcat 7 is not using URF-8 by default. Edit the ##conf/server.xml## file to set the UTF-8 encoding:(((

466

467

<Connector port="8080"

468