.htaccess Guide

Overview

An .htaccess file contains directives that the web server will apply to a collection of resources before a page is displayed. For example, a .htaccess file may change PHP configuration, deny access, change the page displayed, and even redirect a resource to another URL. These are denoted by a directive. A directive consists of a directive name and value, such as DirectoryOptions +Indexes or php_flag display_errors on.

Directive precedence

Before changing how the web server works, it’s important to know how these rules are applied. Before a request is processed, the server looks for a file called .htaccess in the directory in which content is served. Any directives in this file are applied. The server will then backtrack down each directory until it reaches /var/www applying whatever directives are present in whatever .htaccess files it finds along the way.

Example

A page is served from /var/www/mydomain.com. .htaccess files are located present as /var/www/mydomain.com/.htaccess and /var/www/.htaccess. First, rules in /var/www/mydomain.com/.htaccess are applied. Then, any rules in /var/www/.htaccess are applied overriding any rules present under mydomain.com/.

Be careful with addon domain locations! .htaccess can be located under /var/www to apply global configuration to any subdomain or domain located under /var/www.

Setting directives

Create a plain-text file named .htaccess that will be uploaded in the document root for the subdomain or domain whose behavior you would like to modify.

You may also create an empty plain-text file within the control panel under Files > File Manager. You may then edit the file by clicking on the Edit action in the Actions column to make changes from your browser.

Each directive is one-line long and placed on a separate line. For example, these are all valid directives:

• Options +Indexes
• RewriteCond %{HTTPS} ^ON$
• php_value error_reporting 99999
• PassengerEnabled On

These are all invalid:

• Options
  • Reason: missing option values
• php_value error_reporting display_errors on
  • Reason: extraneous PHP configuration directives
• RewriteCond %{HTTPS} ^ON$ RewriteRule ^(.*)$ https://mydomain.com/$1 [R,L]
  • Reason: each directive (RewriteCond, RewriteRule) must reside on its own line
• PassengerEnabled yes
  • Reason: “yes” is not an acceptable value for PassengerEnabled

Handling Errors

Sometimes a directive may be improperly entered into your .htaccess file. In such cases, the web site will fail to display and an Internal Server Error will be generated. You can refer to error_log for a detailed explanation of what directive was rejected and for what particular reason.

Common Directives