.htaccess Guide

Overview

What is .htaccess?

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.

Directives

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 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: irrelevant 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 a 500 Internal Server Error will be generated. You can refer to the error_log file for a detailed explanation of what directive was rejected and for what particular reason.

Common Directives

Directive Name	Description	Example	Documentation
php_value	Sets PHP runtime configuration	php_value upload_max_filesize 32M	KT Docs: Changing PHP Settings
RewriteBase	Anchors a rewrite rule to the current directory	RewriteBase /	Apache Documentation: Apache mod_rewrite
Options	Sets directory-specific options	Options +Indexes	Apache Documentation: core
PassengerEnabled	Enable Rails, Node.js, and Python autoloading	PassengerEnabled On	Phusion Documentation