.htaccess, MIME Types and Handlers
An .htaccess file is a special file that can be used to tweak the web server configuration, so that the server behaves differently for the directory it is in (i.e your web site) and all directories below it. Mime Types (Multipurpose Internet Mail Extensions) represent file types as presented to your web browser. If you are using a file format, encoding type, or language that is not already included in your server's configuration, you can use directives in your .htaccess file to enable them for your files. Finally, Handlers perform preprocessing on requested files and may also be modified in your .htaccess file.
Introduction - .htaccess
Your Web directory and its sub directories can contain per-directory configuration files called .htaccess files. Whenever your Web server receives a request for a file, it first looks for a file called .htaccess in that directory and its parent directories. If one is present, the server considers the configuration directives within it before responding to the request.
An .htaccess file works like this:
- An .htaccess file must be a plain text file and contain no special formatting elements. Use a text editor to create your .htaccess file. If you create it with a word processor, be sure to save it as plain text. The file starts with a " . " so it can be hidden in standard directory listings of most UNIX/Linux setups, and so that a web server will not display it.
- An .htaccess file contains a list of configuration directives and nothing else.
- If an .htaccess file contains any other information, it must be commented out in order to prevent errors
- You should edit this file like any other and upload it via FTP. An .htaccess file must be saved in the top directory to which you want it to apply. The directives apply to that directory and its sub directories.
- If a subdirectory contains a .htaccess file, it overrides the .htaccess files of its parent directories.
Mime Types and Handlers
Mime Types and Handlers instruct you web server how to behave under certain conditions. For example, you can develop customized error pages and redirect users to them when neccessary. Or you can allow your web server (or a directory within it) to "serve up" customized or specialized files / file extensions, or you can password protect a specific directory.
For example, perhaps you want to change the mime type your xsl pages are being sent as. Right now your server probably sends them as text/plain, and you need them to be served as text/xml. The ultimate answer is to get the hosting provider to fix the mime-types on the parent server, but that may not always be possible or feasible. Depending on your provider's settings however, you may be able to configure your own mime-types or handlers on a per-directory basis on your web site, using .htaccess entries.
The MIME-type allows you to add a custom encoding, add a second (or third) language setting, or instruct the end user's browser how to handle a non-standard file extension. These 3 modifications are achieved using:
Syntax: AddEncoding encoding-type file-suffix
AddEncoding matches filename suffixes to encoding types. When the web server sends an encoded file to a client, it includes a Content-Encoding header that gives the encoding type based on the filename's suffix. The client can then determine the type of pre-processing required to decode the file for the user.
Syntax: AddLanguage language-type filename-suffix
When a client requests a document, it should include the Accept-Language: field in its request. The value is a two-letter abbreviation such as en, it, fr, or jp. AddLanguage maps these language types to filename suffixes. For example, if you have files named readme.html.fr and readme.html.en, your server would know which one to send to a French client and which to send to a English client when each sends a request for readme.htm
Syntax: AddType MIME-type file-suffix
With AddType, you can map MIME types to filename suffixes without editing the mime.types file.
Handlers perform preprocessing on requested files. You can also use the ErrorDocument directive to customize the error messages that your server sends when a request fails. These modifications are achieved using:
Syntax: ErrorDocument error-code document
In the event of a problem or error, most servers do one of four things,
- behave like NCSA HTTPD 1.3
- output a customized message
- redirect to a local URL to handle the problem or error
- redirect to an external URL to handle the problem or error (except when the error code is 401)
All except the first are configured using ErrorDocument, which is followed by the HTTP response code and a message or URL. Messages in this context begin with a double quote ("), which does not form part of the message itself.
- ErrorDocument 403 "Sorry can't allow you access today
- ErrorDocument 404 /error/404.html
- ErrorDocument 500 http://wats.ca/error/500.html
URLs should begin with a slash (/) for referencing local URLs, or a full URL which the client can resolve.
Syntax: AddHandler handler-name filename-suffix
This directive matches handlers to filename suffixes, and is often used in conjunction with Action. Handler-name can be the name of an existing handler or one that you create using the web server's API. For example, you can use the as-is module by un commenting this line in httpd.conf:
- AddHandler send-as-is asis
With this handle enabled, the server sends any file ending in .asis without adding an HTTP header. Your .asis files must include their own HTTP headers, followed by two carriage returns. This means that you can attach custom headers to your files without creating special CGI scripts to manage them. You can also use this directive to create special handlers specifically for the Action directive, as described below. Note: Not all servers have the asis module installed.
Syntax: SetHandler handler
SetHandler specifies a handler to be used for all files in a directory or location. There are six built-in values for handler:
Handler Description Handler Description cgi-script All files are treated as CGI scripts and processed by mod_cgi. imap-file All files are treated as imagemap files and processed by mod_imap. server-info All files are sent with server configuration information. server-status All files are sent with server status information. server-parsed All files are treated as server-parsed HTML, for server-side includes by mod_ssi. type-map All files are treated as type maps for content negotiation by mod_negotiation. send-as-is Server will send all files without appending HTTP headers. (See note above.)
Handler can also be a third-party or custom handler that you add with AddHandler.
Syntax: Action handler|media-type script
Action maps handlers or media types to the CGI scripts that process them. For example, if you do not want to use your server's internal imagemap feature, you could include:
- AddHandler imap-file .map
- Action imap-file /cgi-bin/imap.cgi
This causes the server to send all files ending in .map directly to the imap.cgi script. Thus, if the server receives a request for http://www.wats.ca/nav.map, it behaves as if it received a request for http://www.wats.ca/cgi-bin/imap.cgi/nav.map instead. Action can be used with AddType in the same way.
Modifying your .htaccess file
Generally, an .htaccess file will accept the vast majority of standard Apache webserver configuration options, and will probably look something like this:
# Ensure my XSL pages are being served up as XML
AddEncoding text/xml xsl
# Define the location of my error documents
ErrorDocument 403 http://wats.ca/error/403.html
ErrorDocument 404 http://wats.ca/error/404.html
ErrorDocument 500 http://wats.ca/error/500.html
# Password protect directory /private
AuthName "private files"
# Tell the webservers what to do with a .doc file
AddType application/msword .doc
In the example above, we have done four things.
- We have set files with the file extension of .xsl to be served up as xml documents, not plain text.
- Custom error documents have been defined, and their locations given. The numbers are the HTTP status code, which is what the web server sends back when it is given a request. A 500 [Internal Server Error], for example, will bring up a customized error page when someone clicks on a broken link. (For example, a bilingual error page.)
- The directory http://www.wats.ca/secret/ has become password protected. The file containing the username and password is in the home directory ["/htdocs"] of the site, and is called .passwd . To generate the encrypted password and username pair this file uses, use the encrypting tool in our tool box.
- The web server knows what to do with a file ending with .doc - it will ask the user of your site whether they want Microsoft Word to open these files [if they have it installed]. See the MIME Types section for more information on this.
The "#" in the lines above just comment out the rest of a line. This means that it is ignored by the web server, so that you can add commentary to your file to remind yourself what the configuration lines do should you forget! Blank [or "white"] space in these files is irrelevant and is ignored. The indentation above just helps you follow what configuration applies to which directory.
Your file must be called .htaccess -- this is what the web server is set up to look for. The choice of the file name is unusual so that you are unlikely to create a file with the same name and cause a clash. The file can go anywhere in your site tree [remember that your site tree starts at /htdocs]. Be sure to FTP the document as a plain text document.
The hierarchy of .htaccess files is also important. If you have a file in your root /htdocs directory, the characteristics of this file are inherited by all sub directories unless there is another .htaccess file in them to negate the settings of the original one. You may wish to get around this by having just one site wide .htaccess file with each of your directories explicitly set as to their behaviour in that file. It is up to you.