Jump to: navigation, search

Jetty/Howto/How to serve symbolically linked files

< Jetty‎ | Howto
Revision as of 23:13, 9 January 2013 by Gregw.intalio.com (Talk | contribs)


There are two parts to serving aliased files with Jetty: alias detection and then alias serving.

Alias Detection

By default Jetty runs in a mode where all file accesses are checked for aliases, such as case insensitivity, short names, symbolic links and extra characters (Eg %00).

Alias requests are a security problem because web application security constraints are applied with case sensitive URL patterns. For example, if a security constraint is place on a /mySecretFolder/* and alias checking was not implemented then on a win32 system the following requests could retrieve files from that URL:


File name aliases come in many forms including case insensitivity, VMS version numbers, Unix symbolic links, 8.3 short names, etc. While some of these aliases (eg symbolic links) are deliberate, there is no general way to tell this in portable 100% java.

Jetty detects aliases by comparing the file's absolutePath with its canonicalPath.

Alias detection can be turned off by calling the static method org.eclipse.jetty.util.resource.FileResource.setCheckAliases(false). If alias checking is not used, then greater care is needed when designing security constraints. It is recommended that a restrictive constraint be applied to a whole subtree of URL space and then selective constraints be applied to relax security only for specific URLs.

Alias Serving

By default, Jetty checks for alias and disallows the serving of aliased files. If instead you wish to allow aliased files (such as symbolic links) to be served, then you set the <init-param> called "aliases" to "true" for the org.eclipse.jetty.servlet.DefaultServlet. You can do this in a number of different ways, pick one of the following:

  • copy the setup of the DefaultServlet from $JETTY_HOME/etc/webdefault.xml into your webapp's WEB-INF/web.xml and add the aliases <init-param>
  • or if you're using the webapp deployer (ie $JETTY_HOME/etc/jetty-webapps.xml is being used) then edit the $JETTY_HOME/etc/webdefault.xml to add the aliases <init-param>
  • or if you have a context xml file which describes your webapp, then copy or edit the $JETTY_HOME/etc/webdefault.xml to add the aliases <init-param> and then ensure your context xml file references it as the defaultsDescriptor
  • or if you're programmatically configuring jetty, then add the aliases init-param to the DefaultServlet declaration

From jetty-7.6.9 and Jetty-8.1.9 Jetty also supports a pluggable interface called CheckAlias that can be used to selectively allows some aliases, such as symbolic links. This is done by adding instances of CheckAlias to the ContextHandler, typically in the context XML file. The following example is from the test.xml context file:

  <!-- Allow directory symbolic links  -->
  <Call name="addAliasCheck">
      <New class="org.eclipse.jetty.server.handler.ContextHandler$ApprovePathPrefixAliases"/>
  <!-- Allow file symbolic links  -->
  <Call name="addAliasCheck">
      <New class="org.eclipse.jetty.server.handler.ContextHandler$ApproveSameSuffixAliases"/>