URL Rewrite Rules

Last Updated: May 20, 2019
documentation for the dotCMS Content Management System

dotCMS ships with a Java implemention of mod_rewrite called tuckey. This allows you to set up rewrite rules which can both forward and redirect, using sophisticated rewrite rules and conditions.


The Vanity URLs feature provides almost all the functionality available via Tuckey, through a simple, codeless user interface which support Push Publishing and other rich dotCMS content features. It is recommended that you use Vanity URLs instead of Tuckey, unless you have a need for sophisticated rewrite rules or conditions which are not supported by Vanity URLs.

For more information on the different methods you can use to implement rewrites in dotCMS, please see the Redirects, Rewrites, and Forwards documentation.

Rule Types

You can create rules to either forward or redirect URLs.


Forwards rewrite the URL according to the rewrite rule, and change the URL displayed in the user's browser to display the new URL. For example, if you forward from the URL /en/about-us to /about-us?language-id=1, the URL displayed in the user's browser will change to display the rewritten URL (/about-us?language-id=1).


Requests URLs which match the “from” property will be HTTP redirected as specified in the rule. Redirects rewrite the URL according to the rewrite rule, but leave the URL displayed in the user's browser the same as it was typed in by the user. For example, if you redirect from the URL /en/about-us to /about-us?language-id=1, the URL displayed in the user's browser will remain as it was typed (/en/about-us), but the page displayed will be based on the rewritten URL (/about-us?language-id=1).

This allows you, for example, to create rewrite rules that add parameters to the end of the URL without displaying those parameters in the user's browser, or to create rules that allow the same folder on your site to be accessed with multiple different names.


There are two different ways to implement rewrite rules in dotCMS:

  • Using XML patterns via a static plugin using the urlrewrite.xml file.
    • This method is simpler to implement, but all changes require you to shut down dotCMS, re-deploy plugins, and restart dotCMS.
  • Using Java code via an OSGI plugin.
    • This method is more technically demanding, but enables you to make changes dynamically, without the need to restart dotCMS.

The urlrewrite.xml File

The rewrite filter will search for rewrite rules in a urlrewrite.xml file in your WEB-INF folder within your dotCMS installation (/dotserver/tomcat-X.x.xx/webapps/ROOT/WEB-INF/urlrewrite.xml), and perform all rules found in the file. This file should be created using a ROOT folder plugin to ease upgrades and ensure backward compatibility.

Rules in the urlrewrite.xml file use an XML format which allows you to create rules to match different URL patterns, rewrite them in different ways, and set request and session headers to provide additional information to the page that ultimately is displayed. For information on how to create the rewrite rules, please see the Tuckey manual.


The following rule redirects the URL /es/about-us to display the Spanish language version of about-us,

    <to type="redirect">/denver/</to>

OSGI Plugin

Rewrite rules may also be implemented via an OSGI plugin. The following example code implements the same rewrite rules as in the example above, using a Java class. This Java class can be implemented and loaded dynamically as an OSGI plugin, without the need to restart dotCMS.


package com.dotmarketing.osgi.tuckey;

import com.dotcms.repackage.org.osgi.framework.BundleContext;
import com.dotmarketing.osgi.GenericBundleActivator;
import com.dotcms.repackage.org.tuckey.web.filters.urlrewrite.NormalRule;
import com.dotcms.repackage.org.tuckey.web.filters.urlrewrite.SetAttribute;

public class Activator extends GenericBundleActivator {

    @SuppressWarnings ("unchecked")
    public void start ( BundleContext context ) throws Exception {

        initializeServices( context );

        // Create the rewrite rule with the specified request prefix "es"
        NormalRule esLangRewriteRule = new NormalRule();
        esLangRewriteRule.setFrom( "^/es/(.*)" );

        // Set the target page language ID request attribute
        SetAttribute langIdRequestAttribute = new SetAttribute();
        langIdRequestAttribute.setName( "com.dotmarketing.htmlpage.language" );
        langIdRequestAttribute.setValue( "2" );
        esLangRewriteRule.addSetAttribute( langIdRequestAttribute );

        // Set the target page language ID session attribute
        SetAttribute langIdSessionAttribute = new SetAttribute();
        langIdSessionAttribute.setType( "session" );
        langIdSessionAttribute.setName( "com.dotmarketing.htmlpage.language" );
        langIdSessionAttribute.setValue( "2" );
        esLangRewriteRule.addSetAttribute( langIdSessionAttribute );

        // Set the target page URL attribute
        SetAttribute cmsFilterUrlMapOverrideAttribute = new SetAttribute();
        cmsFilterUrlMapOverrideAttribute.setName( "CMS_FILTER_URLMAP_OVERRIDE" );
        cmsFilterUrlMapOverrideAttribute.setValue( "/$1" );
        esLangRewriteRule.addSetAttribute( cmsFilterUrlMapOverrideAttribute );

        addRewriteRule( esLangRewriteRule );


    public void stop ( BundleContext context ) throws Exception {
        unregisterServices( context );

For more information on creating and deploying OSGI Plugins, please see the OSGI / Dynamic Plugins documentation.

web.xml file Configuration

The rewrite filter is enabled by default. To ensure the rewrite filter is enabled, verify that the following lines exist in your web.xml file (/dotserver/tomcat-X.x.xx/webapps/ROOT/WEB-INF/web.xml):



On this page