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

Get Connected