How to use the mod_speling Apache module

This article describes how to enable and configure the mod_speling Apache module on an unmanaged server. The mod_speling module enables your web site to process filenames that vary in their case.

These types of issues can occur with files created on an operating system that uses a case-insensitive file system, such as Microsoft Windows.

About filename case sensitivity

A2 Hosting servers run Linux, which has a case-sensitive file system. In other words, file.html and File.html are not the same file. This is different from Microsoft Windows, which does not have a case-sensitive file system. On Microsoft Windows, file.html, File.html, FILE.HTML, and FiLe.Html all refer to the same file.

These file handling differences can cause problems, particularly when:

• You migrate a web site from Microsoft IIS (Internet Information Services) to Linux.
• You use an application to design a web site on Microsoft Windows, and then publish the files to a Linux web server.

You can use the Apache web server's mod_speling module to work around these issues. (The module's name is intentionally misspelled with only one 'l'.)  With the mod_speling module, you can instruct Apache to ignore filename case. This saves you the effort of having to manually rename files and edit HTML hyperlinks so they all use the correct case.

To set up the mod_speling module, follow the appropriate procedure below for your server's Linux distribution.

Debian and Ubuntu

To enable the mod_speling module on Debian or Ubuntu, follow these steps:

1. Log in to your server using SSH.
2. As the root user, type the following command to enable the mod_speling module:

   a2enmod speling

3. Type the following command to restart Apache:
   

   service apache2 restart

The mod_speling module is now enabled. You can use .htaccess directives to control which directories use it to process filenames. To do this, follow these steps:

1. Type the following command:

   cd /etc/apache2/sites-available

2. Open your web site configuration file in a text editor, and then make sure that the AllowOverride directive is set to All or Options for the directory or directories that you want.

3. To load the new site configuration, type the following command. Replace sitename with the name of your own site configuration file:
   

   a2ensite sitename

4. Change to the web site directory (for example, /var/www) where you want to use mod_speling processing.

5. Create an .htaccess file that includes the following lines:
   

   <IfModule mod_speling.c>
       CheckCaseOnly on
       CheckSpelling on
   </IfModule>

6. Test the configuration. For example, if you have a file named test.html, you should now be able to view it in your web browser by specifying Test.html, TEST.html, test.HTML, or any other case combination in the URL.

AlmaLinux and Fedora

To enable the mod_speling module on AlmaLinux or Fedora, follow these steps:

1. Log in to your server using SSH.
2. The mod_speling module may be already loaded by default. To verify if this is the case, type the following command as the root user:

   httpd -M | grep speling

   • If the mod_speling module is enabled, you see the following output:

      speling_module (shared)

   • If you do not see this output, add the following line to the /etc/httpd/conf/httpd.conf file:
     

     LoadModule speling_module modules/mod_speling.so

     Then type the following command:

     service httpd restart

When the mod_speling module is enabled, you can use .htaccess directives to control which directories use it to process filenames. To do this, follow these steps:

1. Open the /etc/httpd/conf/httpd.conf file in a text editor, and then make sure that the AllowOverride directive is set to All or Options for the directory or directories that you want.
   If the AllowOverride directive is not set to All or Options, make the change, save the httpd.conf file, and then type the following command to restart the server:

   service httpd restart

2. Change to the web site directory (for example, /var/www/html) where you want to use mod_speling processing.

3. Create an .htaccess file that includes the following lines:
   

   <IfModule mod_speling.c>
       CheckCaseOnly on
       CheckSpelling on
   </IfModule>

4. Test the configuration. For example, if you have a file named test.html, you should now be able to view it in your web browser by specifying Test.html, TEST.html, test.HTML, or any other case combination in the URL.

Other Linux distributions

For other Linux distributions, consult its documentation for the steps to enable and configure the mod_speling module.

More Information

To view the official Apache documentation for the mod_speling module, please visit https://httpd.apache.org/docs/2.2/mod/mod_speling.html.