Apache .htaccess Files

This article is part of an archive of articles that were formerly on the web site of Poplar ProductivityWare LLC, Jennifer's freelance software development business (which closed for business in April 2022).
Author: Jennifer Hodgdon
Date Written: 23 March, 2010
Type: Article
Subject: Web Development

Introduction

If your web site is hosted using an Apache web server, and your web host allows it, you can set up a custom configuration for the whole site and/or sub-directories (also known as "sub-folders", to Windows users) of the site, using what are called ".htaccess files" (pronounced H-T-access). The most common configurations you can make with an .htaccess file are (a) password-protecting certain files and/or sub-directories of your site, and (b) creating customized error pages, so that people who access non-existent files on your site get a page that has the look and feel of your site, rather than the generic "404 error" page. This tutorial explains how to do make these configuration changes, assuming that you know how to create and upload files to your web site.

Here are the basic steps for creating an .htaccess file:

  1. Create a text file, using any plain-text editor (such as Notepad, Emacs, etc., but NOT Word or any other word processing program).
  2. Name the file ".htaccess" (no quotes).
  3. Upload the file to the top-most directory of your site that you want to configure. The .htaccess commands you put in that file will apply to that folder, as well as all levels of sub-folders below it.

The sections below explain what exactly to put into the .htaccess text file. The sections are independent -- if you don't care about password protection, you can skip the password protection section, and so on.

If you have any suggestions, comments, or corrections, please contact Poplar ProductivityWare.

Table of Contents:

Setting up Password Protection

If your web site is hosted on an Apache web server, and the server is configured to allow it, you can set up password protection for files and/or directories through the use of an .htaccess file. The introduction section above outlines the basic steps for creating and using an .htaccess file; this section will help you figure out what to put in the .htaccess file, in order to have password protection. When you do this, if a user tries to access a protected file, their browser will pop up a small window asking for their user name and password, and if they don't provide valid entries, the Apache web server will deny them access to the file.

Please note that the password protection offered through .htaccess files should not be considered a strong security program for your web site. If you need to protect sensitive data, such as social security numbers or financial data, you should consult with an Internet security expert (which I am not). However, if you have some not-too-sensitive information that you would like to protect with passwords, read on: an .htaccess file is probably an appropriate way to do it. Here are the steps in setting it up:

  1. Define user names and (encrypted) passwords in an .htpasswd file. An .htpasswd file consists of one or more lines, where each line contains a user name, a colon, and an encrypted password (example: joesmith:lsfeXXYEnvds). You can generate the lines to go into the file directly on your web server by using the Unix htpasswd command, if you have access to a Unix command line on your web server, and know how to use the command. If you don't, you can probably use the password-protection section of your web management console, if your web host provides one. Create a new directory on your site, and tell the console to password protect it, and it should create both an .htaccess file in the directory (which you can then modify), and an .htpasswd file in your top-level directory.
  2. Figure out what's called the "full path" to the directory where you put the .htpasswd file, or where it was created. If you don't know what that means, contact the tech support person at your web host, and ask them for the full path -- it should look something like "/full/path/to/username/.htpasswd" (no quotes). If you used a password-protection utility on your web host to set up password protection, the full path will already be in the .htaccess file it created. If you used shell access to create the .htpasswd file, you can use the Unix "pwd" command to print out the full directory path where the file is.
  3. Once you have your .htpasswd file, you need to edit the .htaccess file in the directory you want to protect. The simplest case is if you want to password-protect an entire directory, in which case your .htaccess file should contain the following lines:
    AuthUserFile /full/path/to/username/.htpasswd
    AuthName "Message to go on user's login screen"
    AuthType Basic
    Allow from all
    Require valid-user
    Here is an explanation of what the individual lines do:
    • AuthUserFile /full/path/to/username/.htpasswd - tells Apache where to find the .htpasswd file containing the user names and passwords you have defined -- substitute the actual full path to your .htpasswd file. If you used a password protection utility to get started, then this line will tell you the actual, full path to the directory where the .htpasswd file was placed.
    • AuthName "Message to go on user's login screen" - you can put your own message here, and when the user is asked to log in, they will see your message at the top of the dialog box asking for their user name and password. A typical message would be "Enter your ABC Club user name and password".
    • AuthType Basic - this tells Apache to use the standard "Basic" password prompting to decide whether users are authorized.
    • Allow from all - this tells Apache to allow users browsing from any computer around the world to log into the site. Note that while it is possible to use an "Allow from" statement that is more restrictive (e.g. only users on computers directly on your corporate network could view the page), it is not too common (you should probably put the files on an intranet, behind a firewall, rather than using .htaccess to restrict access).
    • Require valid-user - this tells Apache to restrict access to the users in your .htpasswd file. Alternatively, you can be more specific, and list individual users who should have access. For example, if you have defined users "joesmith" and "maryjones" in your .htpasswd file, among others, but only want those two people to have access to this directory, you could substitute:
      Require user joesmith maryjones
  4. Now, you can refine your .htaccess file for each directory, to allow for more complicated password-protection schemes -- protection for subsets of files rather than a whole directory, and the possibility of denying all access to certain files. For example, if you wanted to allow full access to most files, but password protect the file abc.html, and completely deny access to pwd.inc, you would put these lines into your .htaccess file:

    AuthUserFile /full/path/to/username/.htpasswd
    AuthName "Message to go on user's login screen"
    AuthType Basic
    Allow from all
    <Files abc.html>

    Allow from all
    Require valid-user

    </Files>
    <Files pwd.inc>

    Deny from all

    </Files>

    It is also possible to define access to files using matching criteria, by substituting the FilesMatch directive for Files. For instance, if you want to deny access to all files that have a ".inc" extension, rather than specifically listing pwd.inc as in the example above, you would substitute these three lines:

    <FilesMatch "\.inc$">

    Deny from all

    </FilesMatch>

    More complicated patterns can be specified if you are conversant with what are called "regular expressions", which I'm not going to describe in more detail, but you can probably guess that to define access to .html files, you would use <FilesMatch "\.html$">; for .gif image files, you would use <FilesMatch "\.gif$">; and so on.

Back to top

Setting up Custom Error Pages

When a user types in a URL that leads them to a page on your site that doesn't exist, the Apache web server normally sends back a standard "404 not found error" web page, which, in a not very friendly or pretty way, tells the user that the page doesn't exist. If you prefer, you can tell the Apache web server to use an HTML page that you create, which can have your site's general look-and-feel, and a more pleasant error message.

Setting up this type of custom error page is actually fairly simple. All you have to do is:

  1. Create your custom (HTML) error page, and upload it to your web site. Note the URL that will take you to that file -- for example, it could be http://example.com/errorpage.html.
  2. Edit the .htaccess file in the top-level directory of your web site (see introduction section), adding the following line (substitute your URL and page name):
    ErrorDocument 404 http://example.com/errorpage.html
  3. Save and upload the .htaccess file (see introduction section).

You can also add similar lines for other error codes, to tell Apache to use the same or other custom error pages for other errors that a user might encounter. You might consider the following codes:

  • 400 - Bad or malformed HTTP request
  • 403 - User is forbidden from accessing the page
  • 408 - The request took too long to fulfill (time-out)
  • 500 - Internal server error
  • 503 - Service unavailable (if the web server is too busy or is down)

A full list of error codes and their definitions can be found in the official HTTP specifications -- use your browser's search function to search for 404 to get to the error code section. Error codes are numbered in the 400s and 500s.

Back to top

Further Reading

For topics not covered here, and more advanced options, the official Apache documentation on .htaccess files is the most accurate source. You may also wish to consult their page on configuration files, which covers the syntax of <Files> and other directives.

There are also other tutorials on .htaccess files: here's one .htaccess tuturial I've found useful, and a second useful .htaccess tutorial.