Using .htaccess files

Introduction

Although most server administrators will configure the Apache web server to run as they want, whether emphasing speed, security or some other factor, these options can often clash with the needs of users. For example, if you want to enable browsers to list directories (perhaps because you have a lot of files on offer to download), but the administrator has disabled this globally, then you'll need to use .htaccess files to re-enable this option for your site. There's also the possibility that you'd like to disable some options that are enabled by default.

A .htaccess file is a plain text file, just like HTML documents, that contains a number of directives for the server to follow. These files cascade downwards, so if you place a .htaccess file in your root directory, /, and another in a sub-directory called /downloads, then when a file is requested from the /downloads directory Apache will merge the two files and use all the directives. In the event of two directives conflicting with each other, the one closest to the file will be used, in this case /downloads/.htaccess.

An important point to note is that .htaccess files are, by default, called .htaccess. This may seem strange to those of you from a Windows background, but the file starts with a dot/period followed by 8 characters. To a Windows user this means that the file has no name, just an extension. Unix users will know that a filename beginning with a dot indicates a hidden file, since Apache has its roots in Unix (although, despite being a fan of Unix/Linux, I still run Apache on my Windows XP machine instead).

Creating/uploading the files

Before we start to plant .htaccess files all over the place, let's take a quick look at how we would create/upload the files. As mentioned before, .htaccess files are just plain text files and can therefore be created in any text editor that allows you to save files in plain text format. However, you should not use a word processor to create .htaccess files, as they will often add additional symbols into the file to control fonts, colours etc. and these will stop Apache from parsing the file.

Uploading the .htaccess files is relatively easy in comparison to creating them. Just upload the files in the same way you would any others - usually by FTP although some hosts provide a web-based interface to perform a similiar job. If you are using a dedicated FTP client, ensure that you upload the .htaccess file(s) in ASCII mode and not binary mode.

Error documents

One of the most common uses of .htaccess files is to configure customised error documents for your site. Usually, if a user makes a request for a page that does not exist, the server will return a default error document that, quite frankly, isn't very user-friendly and is unlikely to fit in with the design of your site. However, if .htaccess files are available to you, then you can create your own error documents and use these instead.

The first thing to do is to create the pages that will be used as your error documents. If you want to be organised, group all these files into their own directory and keep them separate from the rest of your site. On this site I store all my error documents under /errors, that way I can easily find and refer to them when required.

The error documents you create work just like any other page in your site, and if you have PHP, Perl, ASP or other server-side languages available then you can use them to create dynamic error documents that respond in a more helpful way. For example, on this site the 403 (access forbidden) error document tells you which document you were trying to access.

Once you've created your server side documents, the way to get them to display at the right time is to add the following line to your .htaccess file:

ErrorDocument ErrorCode /path/to/filename

The ErrorDocument part must be present and in the format given above, i.e. a capital 'E' and 'D' and one trailing space.

ErrorCode can be one of the many codes that can be returned by the server when a request is made for a file, but the most common ones are 403 (access forbidden) and 404 (document not found). /path/to/filename is the path to the error document, relative to the document root. So, for example, if I want to create a pointer to my custom 404 document, saved at http://www.rixort.com/errors/404.php, I'd enter the following line in my .htaccess file:

ErrorDocument 404 /errors/404.php

In a similiar vein, my custom 403 (access forbidden) error document would require the following line to be entered in my .htaccess file:

ErrorDocument 403 /errors/403.php

N.B. When creating error documents, make sure that all references to internal links, images, JavaScript files etc. are absolute rather than relative (i.e. I use /rixort/images/ rather than ../images/), because otherwise your browser will not be able to display them.

It is also possible to specify the HTML to display should a certain error occur, rather than an entire document. However, this isn't nearly as flexible as separate error documents, so I'm not going to cover it here.

As an aside, Internet Explorer will always use its own page for server errors, unless you specifically disable this option in your Internet Options. The only way to force IE to display the custom error page for your site is to use separate documents for your error pages and make sure that these files send at least 512 bytes (half a kilobyte) of data to the browser.

Indexes

Sometimes, when you request a directory with no index file (index.php, default.asp etc.), you will instead see a directory listing of all the public files in the current directory. For a lot of people, this can be a nuisance and they'd rather remove the ability of users to view these directory listings. To do this, simply insert the following line in your .htaccess file:

Options -Indexes

This will remove the directory listing option for all directories in and below the one in which the .htaccess file is placed. If someone requests a directory that does not contain any index files (which would be displayed by default), then a 403 error code will be sent to the browser and either a custom error document or a standard one for your server will be displayed.

If you want to enable directory listings for some directories on your server, just create a .htaccess file in those directories and place in it the line:

Options +Indexes

This works in exactly the same way as disabling indexes, except it will enable them instead. If directory listings are already enabled, either through a .htaccess file higher up in the directory structure or in the httpd.conf file, then this setting will have no effect.

Using .htaccess files

Introduction

Creating/uploading the files

Error documents

Indexes

Further reading