source: branches/3.3-stable/doc/src/docbook/appendix/web.xml.xml @ 6494

Last change on this file since 6494 was 6494, checked in by Nicklas Nordborg, 7 years ago

References #1712: Implement a 'Content Security Policy'

Rearranged documentation about content security policy so that it appears in the table of contents and is easier to find.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 9.7 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 6494 2014-06-26 06:08:13Z 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="http://base.thep.lu.se/ticket/1032">http://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 
142    <varlistentry>
143      <term><sgmltag class="starttag">servlet</sgmltag>: AxisServlet/AxisRESTServlet</term>
144      <listitem>
145        <para>
146        Servlet handling web service requests. If you are not planning to access
147        your BASE installation using web services these servlets may be disabled.
148        </para>
149      </listitem>
150    </varlistentry>
151
152    <varlistentry>
153      <term><sgmltag class="starttag">servlet</sgmltag>: ExtensionsServlet</term>
154      <listitem>
155        <para>
156        Servlet for handling startup/shutdown of the extensions system as well
157        as requests to extension servlets. Do not modify. Do not disable even if
158        extensions are not used.
159        </para>
160      </listitem>
161    </varlistentry>
162   
163    <varlistentry>
164      <term><sgmltag class="starttag">servlet</sgmltag>: xjsp</term>
165      <listitem>
166        <para>
167        Experimental servlet for compiling *.xjsp files used by
168        extensions. The servlet redirects the compilation of *.xjsp
169        files to a compiler that includes the extension supplied JAR file(s)
170        in the class path. Can be disabled if no extensions use this feature.
171        See also <xref linkend="plugins.installation.xjspcompiler" /> for more information
172        about how to enable this feature.
173        </para>
174      </listitem>
175    </varlistentry>
176   
177    <varlistentry>
178      <term><sgmltag class="starttag">servlet</sgmltag>: compile</term>
179      <listitem>
180        <para>
181        Experimental servlet for compiling all JSP files. This is
182        mostly useful for developers who want to make sure that
183        no compilation error exists in any JSP file. Can also be
184        used to pre-compile all JSP files to avoid delays during
185        browsing. This servlet is disabled by default.
186        </para>
187      </listitem>
188    </varlistentry>
189   
190    <varlistentry>
191      <term><sgmltag class="starttag">filter</sgmltag>: characterEncoding</term>
192      <listitem>
193        <para>
194        A filter that sets the character encoding for the JSP
195        generated HTML. We recommend leaving this at the default UTF-8
196        encoding, this default should work with most language in all
197        modern browsers.
198        </para>
199      </listitem>
200    </varlistentry>
201    </variablelist>
202   
203    <sect1 id="appendix.web.xml.csp-filter">
204      <title>Content security policy</title>
205      <para>
206        Support for <emphasis>Content Security Policy</emphasis> was added in BASE 3.3.
207        This is a technology that is used to prevent web browsers from accessing and
208        executing content that is considered unsafe. This includes JavaScript, style sheets,
209        images, browser plug-ins, etc. The policy is implemented by white-listing what is
210        allowed, everything else is blocked.
211      </para>
212     
213      <para>
214        In BASE, we have choosen a relatively restrictive policy which only allow resources
215        to be lodaded from the BASE server. Browser plug-ins are always blocked. This should
216        work well for a standard BASE installation. But some (older) extensions to BASE
217        doesn't adhere to the restrictions implied by the policy and may not work unless it
218        is relaxed a bit. Typically, the problem is that the extensions uses inline javascript
219        code to handle mouse clicks and other events, which is forbidden by the default policy
220        settings. In this case, the policy must be relaxed a bit. Typically,
221        adding <code>script-src 'self' 'unsafe-inline';</code>
222        to the policy setting should take care of most issues. If this is not
223        enough to make the extension work the following link is a good starting point
224        for reading more about this:
225        <ulink url="http://www.html5rocks.com/en/tutorials/security/content-security-policy/">
226        http://www.html5rocks.com/en/tutorials/security/content-security-policy/</ulink>
227      </para>
228   
229      <variablelist>
230      <varlistentry>
231        <term><sgmltag class="starttag">filter</sgmltag>: csp-filter</term>
232        <listitem>
233          <para>
234          A filter that sets the <emphasis>Content security policy</emphasis>
235          header in all responses from the BASE web server. This filter can be removed
236          to disable content security policy, but use this only as a last resort if
237          nothing else works.
238          </para>
239         
240          <para>
241          The following parameters can be specified for the filter:
242          </para>
243         
244          <itemizedlist>
245            <listitem>
246              <para><varname>policy</varname>: The policy string that is sent in the response. The default value
247              is: <code>default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; object-src 'none';</code>
248              </para>
249            </listitem>
250            <listitem>
251              <para><varname>report-only</varname>: If set, policy violations are only reported and not blocked</para>
252            </listitem>
253            <listitem>
254              <para><varname>unsafe-resources-policy</varname>:
255                An alternate policy string that is used for extensions that set
256                <code><sgmltag class="starttag">about safe-resources="0"</sgmltag></code>
257                in their definition. The default value is:
258                <code>default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; object-src 'none'; script-src 'self' 'unsafe-inline';</code>
259              </para>
260            </listitem>
261          </itemizedlist>
262         
263        </listitem>
264      </varlistentry>
265    </variablelist>
266  </sect1>
267
268</appendix>
269
Note: See TracBrowser for help on using the repository browser.