source: trunk/doc/src/docbook/appendix/web.xml.xml

Last change on this file was 7982, checked in by Nicklas Nordborg, 6 months ago

Merge BASE 3.18.2 to the trunk

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 10.3 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE appendix PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: web.xml.xml 7982 2021-06-14 08:01:21Z nicklas $
7 
8  Copyright (C) 2007 Nicklas Nordborg
9  Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg
10 
11  This file is part of BASE - BioArray Software Environment.
12  Available at http://base.thep.lu.se/
13 
14  BASE is free software; you can redistribute it and/or
15  modify it under the terms of the GNU General Public License
16  as published by the Free Software Foundation; either version 3
17  of the License, or (at your option) any later version.
18 
19  BASE is distributed in the hope that it will be useful,
20  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
22  GNU General Public License for more details.
23 
24  You should have received a copy of the GNU General Public License
25  along with BASE. If not, see <http://www.gnu.org/licenses/>.
26-->
27
28<appendix id="appendix.web.xml">
29  <?dbhtml filename="web.xml.html" ?>
30  <title>web.xml reference</title>
31  <para>
32    The <filename>web.xml</filename> file is one step up from the main configuration
33    directory. It is located in the <filename>&lt;basedir&gt;/www/WEB-INF</filename>
34    directory. This configuration file contains settings that are related to the web
35    application only. Most settings in this file should not be changed because they
36    are vital for the functionality of BASE.
37  </para>
38 
39  <variablelist>
40    <varlistentry>
41      <term><sgmltag class="starttag">error-page</sgmltag></term>
42      <listitem>
43        <para>
44        If an error occurs during a page request, the execution is
45        forwarded to the specified JSP which will display information
46        about the error.
47        </para>
48      </listitem>
49    </varlistentry>
50   
51    <varlistentry>
52      <term><sgmltag class="starttag">context-param</sgmltag>: max-url-length</term>
53      <listitem>
54        <para>
55        This setting is here to resolve a potential problem with too long
56        generated URL:s. This may happen when BASE needs to open a
57        pop-up window and a user has selected a lot of items
58        (<emphasis>e.g.</emphasis>, several hundred). Typically the
59        generated URL contains all selected ID:s. Some web servers
60        have limitations on the length of an URL (<emphasis>e.g.</emphasis>,
61        Apache has a default max of 8190 bytes). If the generated URL is
62        longer that this setting, BASE will re-write the request to make
63        the URL shorter and supply the rest of the parameters as part
64        of a POST request instead. This functionality can disabled by
65        setting this value to 0. For more information see
66        <ulink url="https://base.thep.lu.se/ticket/1032">https://base.thep.lu.se/ticket/1032</ulink>.
67        </para>
68      </listitem>
69    </varlistentry>
70 
71    <varlistentry>
72      <term><sgmltag class="starttag">servlet</sgmltag>: BASE</term>
73      <listitem>
74        <para>
75        A servlet that starts BASE when Tomcat starts, and stops BASE
76        when Tomcat stops. Do not modify.
77        </para>
78      </listitem>
79    </varlistentry>
80   
81    <varlistentry>
82      <term><sgmltag class="starttag">servlet</sgmltag>: view/download</term>
83      <listitem>
84        <para>
85        File view/download servlet. It is possible to change the default
86        MIME type for use with files of unknown type.
87        </para>
88      </listitem>
89    </varlistentry>
90   
91    <varlistentry>
92      <term><sgmltag class="starttag">servlet</sgmltag>: upload</term>
93      <listitem>
94        <para>
95        Servlet for handling file uploads. Do not modify.
96        </para>
97      </listitem>
98    </varlistentry>
99   
100    <varlistentry>
101      <term><sgmltag class="starttag">servlet</sgmltag>: spotimage</term>
102      <listitem>
103        <para>
104        Servlet for displaying spot images. Do not modify.
105        </para>
106      </listitem>
107    </varlistentry>
108   
109    <varlistentry>
110      <term><sgmltag class="starttag">servlet</sgmltag>: plotter</term>
111      <listitem>
112        <para>
113        Servlet for the plot tool in the analysis section. You may
114        specify max and default values for the width and height for the
115        generated images. The supported image formats are "png" and "jpeg".
116        </para>
117      </listitem>
118    </varlistentry>
119   
120    <varlistentry>
121      <term><sgmltag class="starttag">servlet</sgmltag>: eeplotter</term>
122      <listitem>
123        <para>
124        Servlet for the plot tool in the experiment explorer section. It
125        can use the same configuration properties for size and image format
126        as the plotter servlet.
127        </para>
128      </listitem>
129    </varlistentry>
130
131    <varlistentry>
132      <term><sgmltag class="starttag">servlet</sgmltag>: news-feed</term>
133      <listitem>
134        <para>
135        Servlet for generating a RSS feed for the news on the front page.
136        Comment out this servlet if you do not want to use the RSS feed.
137        </para>
138      </listitem>
139    </varlistentry>
140
141    <varlistentry>
142      <term><sgmltag class="starttag">servlet</sgmltag>: ExtensionsServlet</term>
143      <listitem>
144        <para>
145        Servlet for handling startup/shutdown of the extensions system as well
146        as requests to extension servlets. Do not modify. Do not disable even if
147        extensions are not used.
148        </para>
149      </listitem>
150    </varlistentry>
151 
152    <varlistentry>
153      <term><sgmltag class="starttag">servlet</sgmltag>: jsp</term>
154      <listitem>
155        <para>
156        Overrides the default JSP servlet defined by Tomcat. The parameters included
157        with the distribution are required, but it may be customized if desired.
158        </para>
159      </listitem>
160    </varlistentry>
161   
162    <varlistentry>
163      <term><sgmltag class="starttag">servlet</sgmltag>: xjsp</term>
164      <listitem>
165        <para>
166        Experimental servlet for compiling *.xjsp files used by
167        extensions. The servlet redirects the compilation of *.xjsp
168        files to a compiler that includes the extension supplied JAR file(s)
169        in the class path. Can be disabled if no extensions use this feature.
170        See also <xref linkend="plugins.installation.xjspcompiler" /> for more information
171        about how to enable this feature.
172        </para>
173      </listitem>
174    </varlistentry>
175   
176    <varlistentry>
177      <term><sgmltag class="starttag">servlet</sgmltag>: compile</term>
178      <listitem>
179        <para>
180        Experimental servlet for compiling all JSP files. This is
181        mostly useful for developers who want to make sure that
182        no compilation error exists in any JSP file. Can also be
183        used to pre-compile all JSP files to avoid delays during
184        browsing. This servlet is disabled by default.
185        </para>
186      </listitem>
187    </varlistentry>
188   
189    <varlistentry>
190      <term><sgmltag class="starttag">filter</sgmltag>: characterEncoding</term>
191      <listitem>
192        <para>
193        A filter that sets the character encoding for the JSP
194        generated HTML. We recommend leaving this at the default UTF-8
195        encoding, this default should work with most language in all
196        modern browsers.
197        </para>
198      </listitem>
199    </varlistentry>
200    </variablelist>
201   
202    <sect1 id="appendix.web.xml.csp-filter">
203      <title>Content security policy</title>
204      <para>
205        Support for <emphasis>Content Security Policy</emphasis> was added in BASE 3.3.
206        This is a technology that is used to prevent web browsers from accessing and
207        executing content that is considered unsafe. This includes JavaScript, style sheets,
208        images, browser plug-ins, etc. The policy is implemented by white-listing what is
209        allowed, everything else is blocked.
210      </para>
211     
212      <para>
213        In BASE, we have choosen a relatively restrictive policy which only allow resources
214        to be lodaded from the BASE server. Browser plug-ins are always blocked. This should
215        work well for a standard BASE installation. But some (older) extensions to BASE
216        doesn't adhere to the restrictions implied by the policy and may not work unless it
217        is relaxed a bit. Typically, the problem is that the extensions uses inline javascript
218        code to handle mouse clicks and other events, which is forbidden by the default policy
219        settings. In this case, the policy must be relaxed a bit. Typically,
220        adding <code>script-src 'self' 'unsafe-inline';</code>
221        to the policy setting should take care of most issues. If this is not
222        enough to make the extension work the following link is a good starting point
223        for reading more about this:
224        <ulink url="http://www.html5rocks.com/en/tutorials/security/content-security-policy/">
225        http://www.html5rocks.com/en/tutorials/security/content-security-policy/</ulink>
226      </para>
227   
228      <variablelist>
229      <varlistentry>
230        <term><sgmltag class="starttag">filter</sgmltag>: csp-filter</term>
231        <listitem>
232          <para>
233          A filter that sets the <emphasis>Content security policy</emphasis>
234          header in all responses from the BASE web server. This filter can be removed
235          to disable content security policy, but use this only as a last resort if
236          nothing else works.
237          </para>
238         
239          <para>
240          The following parameters can be specified for the filter:
241          </para>
242         
243          <itemizedlist>
244            <listitem>
245              <para><varname>policy</varname>: The policy string that is sent in the response. The default value
246              is: <code>default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; object-src 'none';</code>
247              </para>
248            </listitem>
249            <listitem>
250              <para><varname>report-only</varname>: If set, policy violations are only reported and not blocked</para>
251            </listitem>
252            <listitem>
253              <para><varname>unsafe-resources-policy</varname>:
254                An alternate policy string that is used for extensions that set
255                <code><sgmltag class="starttag">about safe-resources="0"</sgmltag></code>
256                in their definition. The default value is:
257                <code>default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; object-src 'none'; script-src 'self' 'unsafe-inline';</code>
258              </para>
259            </listitem>
260          </itemizedlist>
261         
262        </listitem>
263      </varlistentry>
264     
265      <varlistentry>
266        <term><sgmltag class="starttag">servlet</sgmltag>: csp-report</term>
267        <listitem>
268          <para>
269          This servlet is for logging violations to the content security policy. It is disabled by
270          default. To enable logging, this servlet must be enabled and the <varname>policy</varname>
271          setting for the <varname>csp-filter</varname> need to be updated with a <code>report-uri</code>
272          statement. For example: <code>report-uri /{context}/csp-report;</code> where <code>{context}</code>
273          is replaced with the path under which your BASE installation is installed.
274          </para>
275        </listitem>
276      </varlistentry>
277     
278    </variablelist>
279  </sect1>
280
281</appendix>
282
Note: See TracBrowser for help on using the repository browser.