Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 = Installation Steps =
6
7 {{error}}
8 The Tomcat project has brought a change in the [[way they handle ##RequestDispatcher##>>https://bz.apache.org/bugzilla/show_bug.cgi?id=59317]] which has caused [[regressions in XWiki>>https://jira.xwiki.org/browse/XWIKI-13556]] for some versions of Tomcat. Thus you should **not** use the following Tomcat versions:
9 * >= 9.0.0.M5 and < 9.0.0.M10 for the 9.0.x branch (fixed in 9.0.0.M10)
10 * >= 8.5.1 and < 8.5.5 for the 8.5.x branch (fixed in 8.5.5)
11 * >= 8.0.34 and < 8.0.37 for the 8.0.x branch (fixed in 8.0.37)
12 * >= 7.0.70 and < 7.0.71 for the 7.0.x branch (fixed in 7.0.71)
13 {{/error}}
14
15 * Download and install [[Tomcat>>http://tomcat.apache.org/]]. It's usually as simple as unzipping it in a directory. Let's call this directory //##TOMCAT_HOME##//.
16 * Extract the [[XWiki WAR>>xwiki:Main.Download]] into a directory named ##xwiki## in ##//TOMCAT_HOME///webapps/##. The reason you're expanding the WAR is because you'll need to modify one configuration file from inside the WAR later on when you configure the database access.
17 * Edit your //conf/server.xml// to set UTF-8 encoding: {{code}}<Connector port="8080" ... URIEncoding="UTF-8"/>{{/code}}
18 * Make sure you [[give enough memory to Java>>#HOutOfMemoryError]] since by default Tomcat is configured with not enough memory for XWiki.
19
20 == Activate headless mode ==
21
22 If you're operating XWiki on a Linux server with no X11 libraries installed you have to enable headless mode for your Tomcat installation. Sometimes this is also needed on Windows platforms. Typical exceptions are:
23
24 * ##Exception: Could not initialize class sun.awt.X11.XToolkit##
25 * ##java.lang.InternalError: Can't connect to X11 window server using 'localhost:10.0' as the value of the DISPLAY variable##
26
27 * On Linux create a file ##///TOMCAT_HOME///bin/setenv.sh## and insert the following code:(((
28 {{code}}
29 #!/bin/sh
30 export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"
31 {{/code}}
32 )))
33 * On Windows create a file ##///TOMCAT_HOME///bin/setenv.bat## and insert the following code:(((
34 {{code}}
35 set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true
36 {{/code}}
37 )))
38 * When running as a Windows service the ##setenv.bat## is not working. See registry ##HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun 2.0\//FOOBAR//\Parameters\Java## for similar settings.
39
40 == Optional configuration ==
41
42 * Edit your ##conf/server.xml## to enable gzip compression: {{code}}<Connector port="8080" ... compression="on" compressionMinSize="2048" compressableMimeType="text/html,text/xml,text/css,text/javascript,application/x-javascript"/>{{/code}}
43 * If you want to modify the port on which Tomcat will run, edit ##//TOMCAT_HOME///conf/server.xml/##. Search for ##8080## (sometimes ##8180## if you are under Linux) and replace with the port value you wish to use.
44 * It is possible to setup a Tomcat Java Server as a UNIX Daemon - JSVC. Just follow [[these instructions>>http://www.malisphoto.com/tips/tomcatonosx.html?#Anchor-JSVC||target="new"]]. The only reason to make Tomcat a daemon is to make it runnable on the 80th port, which can be replaced by using NginX as a proxy on the 80th port and then forwarding to Tomcat to the 8080th port.
45
46 == Policy configuration ==
47
48 For those who activate the security manager for Tomcat, add this portion of code to the end of your ##conf/catalina.policy## file from your Tomcat installation. You can adapt the code for the available installations of OpenOffice/LibreOffice on your server and for different databases :
49
50 {{code}}
51 grant codeBase "file:${catalina.base}/webapps/xwiki/WEB-INF/lib/-" {
52 // for mySQL connection
53 permission java.net.SocketPermission "127.0.0.1:3306", "connect,resolve";
54
55 // XWiki must have access to all properties in read/write
56 permission java.util.PropertyPermission "*", "read, write";
57
58 // Generic detected permissions
59 permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
60 permission java.lang.RuntimePermission "createClassLoader";
61 permission java.lang.RuntimePermission "setContextClassLoader";
62 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.loader";
63 permission java.lang.RuntimePermission "accessDeclaredMembers";
64 permission java.lang.RuntimePermission "getenv.ProgramFiles";
65 permission java.lang.RuntimePermission "getenv.APPDATA";
66 permission java.lang.RuntimePermission "accessClassInPackage.sun.reflect";
67 permission java.lang.RuntimePermission "getClassLoader";
68 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.connector";
69 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.tomcat.util.threads";
70 permission java.lang.RuntimePermission "reflectionFactoryAccess";
71 permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.interceptor";
72 permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.mbeanserver";
73 permission java.lang.RuntimePermission "modifyThread";
74 permission java.lang.RuntimePermission "getProtectionDomain";
75
76 // JAXB permissions
77 permission javax.xml.bind.JAXBPermission "setDatatypeConverter";
78
79 // Serialization related permissions
80 permission java.io.SerializablePermission "allowSerializationReflection";
81 permission java.io.SerializablePermission "creator";
82 permission java.io.SerializablePermission "enableSubclassImplementation";
83
84 // Internal resources access permissions
85 permission java.io.FilePermission "synonyms.txt", "read";
86 permission java.io.FilePermission "lang/synonyms_en.txt", "read";
87 permission java.io.FilePermission "quartz.properties", "read";
88 permission java.io.FilePermission "/templates/-", "read";
89 permission java.io.FilePermission "/skins/-", "read";
90 permission java.io.FilePermission "/resources/-", "read";
91
92 // MBean related permissions
93 permission javax.management.MBeanServerPermission "createMBeanServer";
94 permission javax.management.MBeanPermission "*", "registerMBean";
95 permission javax.management.MBeanPermission "*", "unregisterMBean";
96 permission javax.management.MBeanTrustPermission "register";
97 permission javax.management.MBeanPermission "-#-[-]", "queryNames";
98 permission javax.management.MBeanServerPermission "findMBeanServer";
99
100 // LibreOffice/OpenOffice related permissions
101 permission java.io.FilePermission "/opt/openoffice.org3/program/soffice.bin", "read";
102 permission java.io.FilePermission "/opt/libreoffice/program/soffice.bin", "read";
103 permission java.io.FilePermission "/usr/lib/openoffice/program/soffice.bin", "read";
104 permission java.io.FilePermission "/usr/lib/libreoffice/program/soffice.bin", "read";
105
106 // Allow file storage directory reading - for directory and everything underneath
107 // This is dependent on the setting of environment.permanentDirectory in xwiki.properties
108 permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}", "read,write,delete";
109 permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}-", "read,write,delete";
110
111 // Allow file storage directory reading - temporary directory and everything underneath
112 // This is dependent on the setting of environment.temporaryDirectory in xwiki.properties.
113 permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}", "read,write,delete";
114 permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}-", "read,write,delete";
115 };
116 {{/code}}
117
118 Please note that this policy configuration file have been tested on CentOS 5.9 with Sun JDK 1.7.0u21 on Tomcat 7.0.40 with XWiki 5.0.1 installed.
119
120 == Using Nginx as a reverse-proxy for Tomcat (http/https) ==
121
122 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.
123
124 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.
125
126 === http (unsecure) ===
127
128 * create this file ##/etc/nginx/conf.d/tomcat.conf##
129 * put the following code inside:(((
130 {{code}}
131 server {
132 listen 80;
133 server_name mydomain.com;
134
135 # Normally root should not be accessed, however, root should not serve files that might compromise the security of your server.
136 root /var/www/html;
137
138 location / {
139 # All "root" requests will have /xwiki appended AND redirected to mydomain.com
140 rewrite ^ $scheme://$server_name/xwiki$request_uri? permanent;
141 }
142
143 location ^~ /xwiki {
144 # If path starts with /xwiki - then redirect to backend: XWiki application in Tomcat
145 # Read more about proxy_pass: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass
146 proxy_pass http://localhost:8080;
147 proxy_set_header X-Real-IP $remote_addr;
148 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
149 proxy_set_header Host $http_host;
150 proxy_set_header X-Forwarded-Proto $scheme;
151 }
152 }
153 {{/code}}
154 )))
155 * restart nginx
156
157 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"]].
158
159 === https (secure) ===
160
161 There are many guides on how to create a secure configuration of nginx. To get started:
162
163 * [[Strong SSL Security on nginx>>https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html||rel="__blank"]]
164 * [[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"]]
165
166 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. ##
167
168 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.
169
170 (((
171 {{code}}
172 <Engine name="Catalina" defaultHost="localhost">
173 <Valve className="org.apache.catalina.valves.RemoteIpValve"
174 internalProxies="127\.0\.[0-1]\.1"
175 remoteIpHeader="x-forwarded-for"
176 requestAttributesEnabled="true"
177 protocolHeader="x-forwarded-proto"
178 protocolHeaderHttpsValue="https"/>
179 {{/code}}
180 )))
181
182 Next, add the following nginx config file to your nginx config folder, replacing ##wiki.yourdomain.com## with your actual domain info:
183
184 (((
185 {{code}}
186 server {
187 listen 80;
188 server_name wiki.yourdomain.com;
189
190 location ~ /.well-known {
191 allow all;
192 }
193
194 rewrite ^ https://$server_name$request_uri? permanent;
195
196 access_log /var/log/nginx-xwiki/access.log;
197 error_log /var/log/nginx-xwiki/error.log;
198
199 }
200
201 server {
202 listen 443;
203 server_name wiki.yourdomain.com;
204
205 root /var/www/html;
206
207 ssl on;
208 ssl_certificate /etc/letsencrypt/live/wiki.yourdomain.com/fullchain.pem;
209 ssl_certificate_key /etc/letsencrypt/live/wiki.yourdomain.com/privkey.pem;
210
211 access_log /var/log/nginx-xwiki/access_ssl.log;
212 error_log /var/log/nginx-xwiki/error_ssl.log;
213
214 location / {
215 proxy_set_header Host $http_host;
216 proxy_set_header X-Real-IP $remote_addr;
217 proxy_set_header X-Forward-For $proxy_add_x_forwarded_for;
218 proxy_set_header X-Forwarded-Proto $scheme;
219 proxy_set_header X-Scheme $scheme;
220 proxy_redirect off;
221 if (!-f $request_filename) {
222 proxy_pass http://127.0.0.1:8080;
223 break;
224 }
225 }
226
227 location ~ /.well-known {
228 allow all;
229 }
230 }
231 {{/code}}
232 )))
233
234 For more background on this config, see the discussion on this ticket: [[XWIKI-13963>>http://jira.xwiki.org/browse/XWIKI-13963||rel="__blank"]].
235
236 == HTTPS setting ==
237
238 * If using HTTPS for accessing XWiki, several modifications have to be made to ensure flawless functionality. Since urls are generated from relative path (##/xwiki/bin/show/Space/Page##), Tomcat has to know which protocol to use, otherwise JSON requests with redirect fails (attachment uploads, extension updating, etc.)
239 * Modify connector (in ##server.xml##) to {{code}}<Connector port="8080" ... secure="true" scheme="https" />{{/code}}
240 * 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)
241
242 {{info}}
243 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!
244 {{/info}}
245
246 = Troubleshooting =
247
248 == Out Of Memory Error ==
249
250 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.
251
252 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:
253
254 {{code language="none"}}
255 CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=192m"
256 {{/code}}
257
258 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).
259
260 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.
261
262 == Java Security Manager ==
263
264 By default Tomcat is configured to have the Java Security Manager turned on. See the [[sample policy file>>AdminGuide.InstallationWAR#HInstallandconfigureaServletContainer]] for more details.
265
266 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:
267
268 {{code}}
269 # Use the Java security manager? (yes/no)
270 TOMCAT5_SECURITY=
271 {{/code}}
272
273 Set it to ##no## to turn off the Security Manager.
274
275 == Allowing "/" in page names ==
276
277 Tomcat completely freaks out when there's a ##%2F## in URLs and it's not something that can be changed in XWiki. See [[this note>>http://tomcat.apache.org/security-6.html#Fixed_in_Apache_Tomcat_6.0.10]] for more information.
278
279 You can configure Tomcat to allow this, by enabling :
280
281 {{code}}
282 org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH
283 {{/code}}
284
285 Note that if you're using Apache you also need to [[configure Apache to allow encoded / and \>>https://httpd.apache.org/docs/current/mod/core.html#allowencodedslashes]].
286
287 == NotSerializableException ==
288
289 If you get the following:
290
291 {{code}}
292 SEVERE: IOException while loading persisted sessions: java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer
293 java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer
294 at java.io.ObjectInputStream.readObject0(Unknown Source)
295 at java.io.ObjectInputStream.defaultReadFields(Unknown Source)
296 {{/code}}
297
298 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]].
299
300 == SEVERE: Error listenerStart ==
301
302 If you get this error in your Tomcat logs then you'll need to enable finer-grained logging configuration to see what's the problem. For Tomcat 6.x/7.x this involves copying the following content in a ##WEB-INF/classes/logging.properties## file:
303
304 {{code}}
305 org.apache.catalina.core.ContainerBase.[Catalina].level = INFO
306 org.apache.catalina.core.ContainerBase.[Catalina].handlers = java.util.logging.ConsoleHandler
307 {{/code}}

Get Connected