Getting started with .htaccess files

• Applies to: Grid
  • Difficulty: Medium
  • Time Needed: 20
  • Tools Required: FTP, plain text editor
• Applies to: All DV
  • Difficulty: Medium
  • Time Needed: 20
  • Tools Required: FTP, plain text editor

Introduction

The .htaccess file is a powerful tool for modifying your Apache configuration on a per-domain and even a per-directory level. Many content management systems rely on .htaccess files for configuring your site. You can also create your own .htaccess file manually.

Requirements

Before you start, be sure to have handy:

• Familiarity with the use of FTP and an FTP client.
• Your FTP login credentials and an FTP client.
• Plain text editor

READ ME FIRST

This article is provided as a courtesy. Installing, configuring, and troubleshooting third-party applications is outside the scope of support provided by (mt) Media Temple. Please take a moment to review the Statement of Support.

READ ME FIRST

The publishing of this information does not imply support of this article. This article is provided solely as a courtesy to our customers. Please take a moment to review the Statement of Support.

Video

Watch this video to learn more about creating and editing .htaccess files.

Creating the .htaccess file

Your .htaccess file needs to be a plain text file. This means you need to make it in a text editing program capable of producing plain text files.

• On a Windows machine, you can use Notepad, which is one of your built-in accessories.
• On a Mac, you can use TextEdit. You must first open the TextEdit "Preferences" menu and, in the "New Document" section, select "Plain text." Then, you can start a new document in TextEdit for your .htaccess file.

When you save your document, make sure you name it htaccess.txt, or something similar. If you save it as .htaccess, your computer will hide the file. This is because files that start with "." are considered to be system files.

Uploading your .htaccess file

You should upload your file to the exact directory you want it to modify. Typically, this will be your html directory (/home/00000/domains/example.com/html/), (/var/www/vhosts/example.com/httpdocs/), although you can upload it to any subdirectory on your server as well. See Using FTP and SFTP Using FTP and SFTP for assistance with uploading.

Once the file is uploaded, rename it to .htaccess exactly.

At this point, the file may disappear from your FTP display, because it now has the format of a system file. Many FTP clients allow you to view hidden files and folders if you enable that feature. Check your FTP client documentation for instructions.

.htaccess file priorities

A lower-level .htaccess file will override the settings in a higher-level one. For example, if you want to forbid directory indexing for most of your site but enable it for a specific directory, you can upload your .htaccess file to just that directory.

Similarly, .htaccess files override PHP settings from your higher-level vhost.conf and/or php.ini files, unless overriding is disallowed in these higher-level files. This means that you can set a PHP upload limit for one of your domains higher than it is on the rest of the server.

Finally, the order of directives within a file can matter for certain types of directives. Directives at the top are processed first.

Tips

PHP values

Most PHP values can be set in your .htaccess file as well as in your php.ini file. To use them in your .htaccess file, preface them with the following line:

Filename: .htaccess

php_value

For example, you could set:

Filename: .htaccess

php_value upload_max_filesize 16M

To check that your new PHP values have been implemented, use a PHP info page, and check the Local Value column.

Filename: phpinfo.php

<?php

// Show all information, defaults to INFO_ALL
phpinfo();

?>

Error Reporting

Put the following lines in your .htaccess file to enable complete error reporting. You can change the value from E_ALL to any desired type of error reporting:

Filename: .htaccess

php_flag display_errors on
php_value error_reporting E_ALL

Be sure to turn off this high level of error reporting once you've identified your issue, otherwise you may be displaying server information to your site visitors. 

Change default directory index

Occasionally, you might want to use a custom directory index page; such scenarios might involve only using "index.php", or bucking tradition and making "home.html" the index for your site. This handy rule will give you this effect:

DirectoryIndex filename.extension

For example, to set "home.html" as the default index page, instead of "index.html", you would place the following in your .htaccess file:

Directory Index home.html

Additional .htaccess functions and tips

• Making directories browsable, solving 403 errors
• Making directories browsable, solving 403 errors
• Creating custom error pages
• Creating custom error pages
• http://www.askapache.com/htaccess/apache-htaccess.html
• Guide for Apache directives that can be included in .htaccess: http://httpd.apache.org/docs/mod/core.html

Troubleshooting

If you're not sure about a certain line in your .htaccess file, comment it out by putting the # symbol in front of it. Save the file, then upload it and test your site without the rule.

Documentation

NOTE:

Please see Apache.org for the official .htaccess documentation from Apache.