This micro-howto will explore, in a rather compressed manner, the workings of a file named .htaccess. This file functions as a user-side mechanism, permitting the manipulation of various aspects of web server behaviour.

Scope

It is crucial to understand that the directives inside an .htaccess file apply not only to the directory in which the .htaccess file is placed, but also to its subdirectories.

Comments

Comments in .htaccess files begin with the pound sign '#'. All endline comments now generate errors and will fill up the error logs with pointless warnings. Do not place comments at the end of any directive or any line.

Password protection for directories

If properly edited and placed, .htaccess will bring up a password prompt, forcing authentication on a directory by directory (or file by file) basis. The following example will disclose the proper contents of the file.

  AuthName "restricted stuff"
  AuthType Basic
  AuthUserFile /home/myself/www/private/.htpasswd
  require valid-user

The AuthName directive establishes the realm over which the authorization operates, so the user knows which username/password to enter. AuthType chooses the variety of authentication for the webserver to use, currently "Basic" or "Digest".

The AuthUserFile directive designates the text file which will hold the username/password pairs, preferably inside the root of the user's $HOME. For security reasons, do not declare that this password file be created in the directory under protection or in any other space under your ~/www directory, and make sure the file is not world-readable (chmod 0600).

The AuthUserFile file is generated by htpasswd(1). You will be prompted for a password and for the confirmation of that password.

Run this, inside the directory over which protection is required -

  $ htpasswd -c .htpasswd username

Blocking requests from specific addresses

The .htaccess file will direct the webserver to refuse access from the specific IP address of 10.0.0.1, by merely inserting into it -

  Deny from 10.0.0.1

Alternatively -

  <Limit GET>
  order deny,allow
  10.0.0.1
  allow from all
  </Limit>

Entire networks can be denied access to your site by removing the last occurring digits (e.g., 10.0.0.).

Specifying error documents

You may create and use your own custom error documents, to display in response to errors such as requests to non-existant files, by using the ErrorDocument directive. Please craft these error documents, so as to occupy minimal hard drive space and without incorporating images, since computer worms may generate massive amounts of hits to ErrorDocuments quickly, and slow loading ErrorDocuments tend to be annoying to users as well. Never declare a URL as the destination for the ErrorDocument. Always set the location to the absolute or relative path of the file, as demonstrated below.

  ErrorDocument 404 errors/notfound.html
  ErrorDocument 403 errors/forbidden.html
  ErrorDocument 500 errors/servererror.html

Directory listings

A .htaccess file may be employed to prevent the listing of the contents of directories without index documents -

  Options -Indexes

To selectively block the listing of any README file and all .gif images, use the IndexIgnore directive -

  IndexIgnore README *.gif

File extension mappings

To override the default file associations and reorient the mapping of given file extensions to user-specificied handlers, the AddHandler directive can be invoked

Suppose it is desired that all files with the extension of .rat be recognized and processed by the server as a cgi program -

  AddHandler cgi-script .rat

It is possible with the AddType directive to project a given filename onto a specific MIME type. To force the mapping of all files with the '.rif' extension onto the 'image/gif' type, use -

  AddType image/gif .rif

Similarly, to assign a specific content-type to files ending in, .foo, use -

  AddType application/x-foo .foo

If you think a given MIME type is worthy of server-wide recognition, please let us know.

Content negotiation

HTTP/1.1 compliant browsers have the ability to request web pages and other resources in different languages and character encodings. The Apache mod_negotiation module provides an option called MultiViews to enable implicit filename pattern matching.

  Options +MultiViews

For example, if a browser requests index.html, there is no file named as such, the web server will look for index.html.en, index.html.fr and so on, depending on the user's language preferences.

Links

Apache resources

• Apache 1.3 - Documentation
• Apache 1.3 - Base directives
• Apache 2.0 - Documentation
• Apache 2.0 - Base directives
• Apache Week - Using User Authentication

PHP resources

• PHP - The configuration file

Select directives

• AddType
• AddHandler
• AuthUsersFile
• Deny
• ErrorDocument
• IndexIgnore
• Options