Htaccess file overview

From DreamHost
(Redirected from KB / Unix / .htaccess files)
Jump to: navigation, search

Various .htaccess samples and tutorials


Many people have only taken the .htaccess file as far as using it for password protection and custom error documents. There is a lot more to what can be done with an .htaccess than just these two features. The .htaccess file is a normal file that you can edit in programs such as Notepad, just as simple as editing your everyday documents.

File names starting with '.' are not common in Windows. But on UNIX-like operating systems (including Linux and BSD), file names starting with '.' indicate that the file should normally be hidden. Don't think of .htaccess as having an empty name with a long extension. Instead .htaccess is the name, with no extension. (This is common in UNIX-like operating systems, for example filename.tar.gz)


Although using .htaccess on your virtual server hosting account is extremely unlikely to cause you any problems (if something is wrong it simply won't work), you should be wary if you are using Microsoft FrontPage Extensions. The FrontPage extensions use the .htaccess file so you should not really edit it to add your own information. If you do want to (this is not recommended, but possible) you should download the .htaccess file from your server first (if it exists) and then add your code at the top of the file.

Can I use .htaccess files?


All DreamHost hosting packages come with the ability to password protect directories using .htaccess. Click here to find out how!

Creating Password Protected Directories

If you have shell access turned on for your user account, you can also use telnet to create and manage your .htaccess files.

Creating the .htaccess File

To create a .htaccess file on Windows, just open a new document in Notepad and save it as .htaccess and make sure All files is selected in the Save as type drop-down menu so it doesn't save it as .htaccess.txt. When you go to upload an .htaccess file to your account, make sure that the data transfer mode is set to ASCII, never BINARY since it is a text file. While .htaccess files will work just by uploading them, we recommend that you CHMOD the .htaccess file to 644 (RW-R--R--). This makes the file readable by your web server, but at the same time, disables browsers from reading it. If your .htaccess file can be read by anyone, your security is in big trouble.

When you create an .htaccess file, make sure that your text editor has word wrap disabled. If you don't, your text editor might add characters to the file that will cause problems with the Web server which will result in a non-functional .htaccess file and a 500 server error on your website's home page. Also make sure that all of your commands in an .htaccess file are on a separate line. If you don't you will end up with an .htaccess file that will cause problems on your account.

When you use a .htaccess file on your web server, the file affects the current directory and any of its sub-directories. If you place an .htaccess file in the root directory of your website, it will affect every directory on your website.

Custom Error Pages

Custom error pages enable you to customize the pages that are displayed when an error occurs. Not only will they make your website seem a lot more professional, but they can also save you some visitors. If a visitor sees a generic error page, they are likely to leave your site. However, if they see a helpful error page, they might just stay at your site because they can just click on a link to go to another page within your site. You can create error pages for all error codes, however many webmasters only make error pages for the 4 most common errors, which are:

  • Error 401 - Authorization Required
  • Error 403 - Forbidden
  • Error 404 - Not Found
  • Error 500 - Internal Server Error

To specify what the server should do when an error is found on your website, enter the following into an .htaccess file:

ErrorDocument <ErrorCode> /home/LOGIN/DOMAIN/error-document.html

Change <ErrorCode> to the code of the error. Also, change the path to the error document. LOGIN represents your user name (the name you use to login through SSH or Telnet) and DOMAIN is the website domain in question. Simply repeat the above line of code for all other errors. Once the file is uploaded, your visitors will be directed to the page that you specified.

Here's a sample .htaccess file with ErrorDocument enabled:

ErrorDocument 401 /401.html
ErrorDocument 403 /403.html
ErrorDocument 404 /404.html
ErrorDocument 500 /500.html

You can use full URL's for the path to your error documents on all error codes except 401, which must use a local path. Also, instead of specifying a URL for an error code, you can display a message too. Here's an example:

 ErrorDocument 404 "<p><strong>Sorry, the document you requested could not be found.</strong></p>"

This is quite useful if you only need to display a short message because it saves you having to create additional files. As you can see, you can use normal HTML code.

Here's another .htaccess file with ErrorDocument enabled. This time, we are displaying messages instead of going to a different URL:

ErrorDocument 401 "<p>Error 401</p><p>Authorization Required.</p>"
ErrorDocument 403 "<p>Error 403</p><p>Forbidden.</p>"
ErrorDocument 404 "<p>Error 404</p><p>Not Found.</p>"
ErrorDocument 500 "<p>Error 500</p><p>Internal Server Error.</p>"

Limit the Number of Concurrent Visitors to your Website

this no longer works on our servers

If you need to limit the amount of concurrent visitors to your website, this can be easily set up. Open a program such as Notepad and insert the following line of code:

MaxClients <Number of max clients>

Change <Number of max clients> to the maximum number of clients you want to allow access to your website.

Disable Directory Listings

Occasionally, you may not have a default index document in a directory. If a default document is not found, whenever a visitor types in the directory name in their browser, a full listing of all the files in that directory will be displayed. This could be a security risk for your site. To prevent without having to add a default index document to every folder, you can enter the following line in your .htaccess file to disable a directory's contents from being shown:

Options -Indexes

Deny/Allow Certain IP Addresses

If you have problems with certain visitors to your website, you can easily ban them. There are two different ways to ban visitors. This can be done using their IP address or with the domain name which they came from.

Here's an example showing you how to deny a user by their IP address:

order allow,deny
deny from
allow from all

The above code will deny the IP address and allow everyone else to enter. If you want to deny a block of IP addresses, use this code:

order allow,deny
deny from 201.68.101.
allow from all

The above code will deny the IP address, the IP address and all the way up to or 255 IP addresses. Here's an example showing you how to deny a user by the domain name from which they came from:

order allow,deny
deny from
allow from all

The above code will deny anyone coming from and allow everyone else to enter. Here's an example showing you how to deny a user from a domain name and all subdomains within the domain name:

order allow,deny
deny from
allow from all

The above code will deny anyone coming from, all sub-domains within the domain and allow everyone else to enter.

order deny,allow
deny from all
allow from YOUR_IP_ADDRESS

The above code will block all visitors from accessing your site except for yourself if you replace youripaddress with the IP address that was assigned to you by your ISP.

Deny Access To a Folder During a Specific Time

If for some reason you would like to block access to files in a directory during a specific time of day, you can do so by adding the following code to an .htaccess file.

RewriteEngine On
# If the hour is 16 (4 PM)
RewriteCond %{TIME_HOUR} ^16$
# Then deny all access
RewriteRule ^.*$ - [F,L]
# Multiple hour blocks
# If the hour is 4 PM or 5 PM or 8 AM
RewriteCond %{TIME_HOUR} ^16|17|08$

Alternative Index Files

When a visitor accesses your website, the server checks the folder for an index file. Some examples of common index files are: index.htm, index.html, index.php, index.cgi, The supported index files depend on the how the server is set up.

DreamHost's servers are set to:
DirectoryIndex index.html index.shtml index.htm Index.html Index.htm Index.shtml default.htm Default.htm default.html Default.html default.shtml Default.shtml page1.html index.cgi index.php index.php3 index.phtml home.htm home.html home.shtml index.wml quickstart.html

As long as you name your "index" file any one of those things, it will work! Note that when you add a new domain or sub-domain to your account, if you add no index file, DreamHost creates quickstart.html for you and places it in your directory so that will show up by default unless you delete it or add your own index file.

If you have two files with names from that list, Apache will show the one that shows up first (e.g. index.html will show up, even if you have an index.php file in the same directory).

You can change your own DirectoryIndex setting to be anything you'd like via an .htaccess file too!

If the server cannot find an index file, it will try to display an index of all the files within the current directory, however if this is disabled, the server will end up displaying a 403 forbidden error. Using .htaccess, you can use a completely different index file instead of the defaults listed above. To do this, insert the following line into an .htaccess file:

DirectoryIndex pagename.html

Change pagename.html to the page that you would like to use as the index file.


Using Redirect in an .htaccess file will enable you to redirect users from an old page to a new page without having to keep the old page. For example if you use index.html as your index file and one day rename index.html to home.html, you could set up a redirect to redirect users from index.html to home.html. Redirect works by typing:

Redirect /path/to/old/file/old.html

The first path to the old file must be a local UNIX path, NOT the full path; if the .htaccess file is in the directory, then you would not include home/USERNAME/ in the local UNIX path. The first / would represent the directory, so if the old file was in that directory, you would follow the / with the old file name. The second path to the new file can be a local UNIX path, but can also be a full URL to link to a page on a different server or the same server.

Here are a few examples of some redirects:

Redirect /index.html /new/
Redirect /index.html /default.html
Redirect /private/
Redirect /img/logo.gif

Another form of redirection uses the RedirectMatch command:

RedirectMatch "^/oldfile\.html/?$" ""

Protect Your .htaccess File

When a visitor tries to obtain access to your .htaccess or .htpasswd file, the server automatically generates a 403 forbidden error, even with the file permissions at their default settings. However, you can apply a bit more security to your .htaccess files by adding the following code:

<Files .htaccess>
order allow,deny
deny from all

If you would like to redirect anything from to (so the www is always in the URL), you can accomplish this by using the code below. This is helpful in search engine optimization and will help give your site a higher page rank.

RewriteEngine On
RewriteCond %{HTTP_HOST} !^www\..* [NC]
RewriteRule ^(.*) http://www.%{HTTP_HOST}/$1 [R=301] 

Prevent Image Hot Linking

Hot linking or bandwidth stealing is a common problem. It happens when people link to files and images on a different server, display them on their website and the bandwidth is at the other person's expense. By entering the lines below, you can prevent hot linking to your website:

RewriteEngine On
RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !^http://(www\.)?*$ [NC] 
RewriteRule \.(gif|jpg)$ [R,L]

Change to your domain name. On the last line of code, change hotlink.gif to the path to an image file that explains that hot linking is disabled on your server or display a spacer image.

Force Text Files to Download and Not Show in Your Browser

By default, if a text file (.txt) is requested, the contents of the file is shown in the browser and is not downloaded. This is because the default MIME type for .txt files specifies to show the files and not download them. You can however change this by adding the line below:

AddType application/octet-stream txt

Be warned though, every .txt file in the current directory and any subdirectories will be affected.

Specify a Custom Error Log

The ErrorLog feature allows you to specify the local UNIX path to store your server error logs. These logs contain errors that visitors have encountered on your website. To specify a custom error log on your account, insert the following code:

ErrorLog /logs/error_log.log

You can change the path and filename of the error log, but your path must start with a forward slash.

Enable Password Protection

Password protection is probably the most popular feature of htaccess and is used all over the Internet. The reason why it is so popular is because it is very simple to set up and is the strongest form of protection which cannot be bypassed. When you set up password protection, you need to set up the password protection options in a .htaccess file and you need to set up usernames and passwords inside a .htpasswd file.

First, we are going to set up the usernames and passwords inside the .htpasswd file. The passwords inside a .htpasswd file are encrypted for added security, so you will need to use the htpasswd generator utility to create your usernames and passwords.

Once you have created the required usernames and passwords, you need to place them inside a .htpasswd file. Open a program such as Notepad and copy the username and password combinations that you generated using the htpasswd generator utility and place each username/password combination on it's own line. Here's a sample .htpasswd file with 3 username/password combinations specified:


Once your .htpasswd contains all of the username and passwords required, save the file as .htpasswd (be sure to select All files in the Save as type if you are using Notepad). Leave the file where it is for now, as we now need to set up the .htaccess file.

Setting up the .htaccess file is quite simple, all you need to do is specify the path to the .htpasswd file, the name of the restricted area, what user(s) to require and the authorization type.

The first thing to configure is the path to the .htpasswd file:

AuthUserFile /home/LOGIN/public_html/path/to/.htpasswd

Next up, what the restricted area is called.

AuthName "Password Protected"

Then, the authorization type:

AuthType basic

Finally, you need to specify what users are allowed to enter the restricted area. Even if you have for example 10 users in your .htpasswd file, you can allow only some users:

require user admin

Or, to allow all users that are listed in the .htpasswd file to access the restricted area:

require valid-user

Here's a sample .htaccess file setup for password protection. Copy the code below and change the path to the .htpasswd file, the name of the restricted area and what users to require. Leave the AuthType as it is:

AuthUserFile /pub/home/htdocs/.htpasswd
AuthName "Password Protected"
AuthType Basic
require valid-user

Open a program such as Notepad, insert the code, and save the file as .htaccess. Then upload .htpasswd and .htaccess to your account. Remember that you have to upload the .htpasswd to the directory specified in the AuthUserFile part of the .htaccess file. Also, remember that wherever you place the .htaccess file, that directory and any sub-directories will now be password protected. Attempt to access the protected directory and you will be prompted to enter a username and password.

The features that have been covered in this tutorial are the most commonly used features within a .htaccess file. There are many more different features that can be used. To learn more, check out Apache's website on Apache Directives.

Force Scripts to Use Specific Default Timezone

If you want your scripts (PHP, Perl, etc.) to automatically use a particular timezone by default when working with date and time values, you can set this in your .htaccess file. See the article Running_web_scripts_in_your_Timezone.

How do I force a domain to be served securely?

Add lines like these to your .htaccess file to force any http accesses to be rewritten using https:

 RewriteEngine On
 RewriteCond %{HTTPS} !=on
 RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

If this isn't working for you, first check your line endings. Copy/Pasting from your web browser into a text editor may not work right, so after pasting into your text editor you should delete each line break and add it back in (line break = return key).

Extra secure method to force a domain to only use SSL and fix double login problem

If you really want to be sure that your server is only serving documents over an encrypted SSL channel (you wouldn't want visitors to submit a htaccess password prompt on an unencrypted connection) then you need to use the SSLRequireSSL directive with the +StrictRequire Option turned on.

 SSLOptions +StrictRequire
 SSLRequire %{HTTP_HOST} eq "" #or
 ErrorDocument 403 

How do I stop "hotlinking" to my files?

"Hotlinking" is when somebody displays an image (or any type of file actually) on somebody else's web site directly inline on their site!

There's nothing particularly wrong with that, it's a big part of how the WWW was designed to work. However, it does "steal" the bandwidth of the original site, and could possibly infringe on a copyright.

To block sites from hotlinking to specific files of yours, you just need to make a .htaccess file with certain commands in it! Here's a great page with a more detailed explanation, but basically the file should look more or less like this:

RewriteEngine on
RewriteCond %{HTTP_REFERER} !^*$ [NC] 
RewriteCond %{HTTP_REFERER} !^*$ [NC] 
RewriteRule .*\.(gif|jpg|jpeg|bmp)$ [R,NC] 

NOTE: If you're forcing HTTPS make sure the 3 lines above are adjusted to https. Otherwise it's possible the images on your site may not load.

How can I turn off the default directory listing in a directory?

Easy! There are two ways:

  1. You can just put a blank file named index.html in that directory.
  2. A "more correct" way is to put a file named .htaccess in that directory consisting of only this line:
Options -Indexes 

What's especially nice about doing it this way is all sub-directories of that directory will also get their directory listings turned off. You could then turn on indexes for one of those sub-directories just by making a .htaccess file in that directory with:

Options +Indexes

How do I use .htaccess files?

Implementation of .htaccess files is universal across the Internet. Many manuals are available online. You can visit your favorite search engine and search for 'htaccess', and you'll probably find a nice tutorial. You can also visit the Custom Apache Documentation Google Search Engine! Once you have grasped the basic concepts, it would definately help you to refer to the many examples available here on the wiki.

If you'd just like to know how to password-protect directories within your site hosted by us, one of these two articles will probably do the trick:

  1. Creating Password Protected Directories with the web panel.
  2. Creating Password Protected Directories with the shell.

Does the main domain htaccess file protect it's sub-domains?

If you create a .htaccess file to protect a domain , (by password protecting it's root directory), this will not protect any sub-domains that are created based on that domain name. They are completely separate services.

How come this feature of .htaccess won't work?

If you are sure you are using the syntax correctly, it might be that that particular feature of .htaccess is disabled (for example turning on your own cgi access!) Please contact tech support via the Account Control Panel, if you think that the feature you want to use is turned off but shouldn't be.

How can I create a plain text file for .htaccess?

You can do it by sshing in to and using pico, a user-friendly text editor. All the commands for its use appear at the bottom of the page (^ means press the Control key.) Just change to the directory in which you want to use .htaccess, and type "pico .htaccess" to get started with a blank .htaccess file.

How do I block certain IPs from accessing my site or directory?

You can use the *Block IP Abuse shell script to locate bad IP's and generate the correct .htaccess code.

All you have to do is create an .htaccess file in the directory you'd like to restrict (your main directory to restrict the entire site) and then put the following in it:

Order Allow,Deny
Allow from All
Deny from
Deny from 124.24.
Deny from

Read this Access Control by Host tutorial to view more Apache .htaccess examples.

When somebody's ip is banned, they will get a 403 error (access forbidden) when trying to visit your site.

How do I block people coming from a certain website or URL from visiting my site or directory?

It's actually very similar to blocking people by IP! Again, you need to add some lines to an .htaccess text file that you create in the home directory of your web site.

Here is some example code for giving everybody who comes to you from or a 403 error (access denied):

SetEnvIfNoCase Referer "^" BadReferrer
SetEnvIfNoCase Referer "^" BadReferrer
order deny,allow
deny from env=BadReferrer

Another way to block people where you end up just redirecting them to a different url involves using the "mod_rewrite" functionality of our web server. Here's how to block everybody from and again (put this in your .htaccess file):

RewriteEngine On
RewriteCond %{HTTP_REFERER} ^
RewriteRule /* [R,L]
RewriteCond %{HTTP_REFERER} ^
RewriteRule /* [R,L]

We hope this helps keep those annoying people out of your site!

How can I use ssi on files with .html extensions?

Our server is configured by default to only parse files with a .shtml extension with server-side includes. If you make sure all your files that include other files (using SSI) are named "something.shtml" you won't have to do anything to get them to work!

We realize that some people however have transferred a site from a different server configuration where any .html file was parsed for SSI. It can be a big pain to rename all the files in a website, as well as fix any links between them. Because of this, we allow users to turn on parsing of ANY sort of file they'd like.

To do this, simply create a plain text file named ".htaccess" in the directory in which you'd like all files with a different extension to be parsed for SSI. Inside the .htaccess file, put this one line:

AddHandler server-parsed .html 

That's it! Now any file ending in .html will have SSI run on it! We really don't recommend doing this unless absolutely necessary. It adds some overhead to the web serving to parse in SSI, and so each and every request for a .html file (even ones that don't have any SSI in them) will be a little bit slower when you turn on this option. It's much better to just name the appropriate files with the .shtml extension if you can!

Another, cheaper, way to accomplish this is to enable "XBitHack" via your .htaccess file by adding the line:

 XBitHack on

and then setting the user execute bit on the .html file using the unix command-line command

 chmod u+x yourfile.html

Note that SSI doesn't normally work when you're running Phusion Passenger (Rails and other Rack applications). This is because when the server receives a URL ending in a / it passes to Phusion. If you need to serve index files statically (including through SSI), your Phusion app must return a redirect to the appropriate file for such URLs, replacing ".../" with ".../index.shtml". The browser will then request the index file explicitly and SSI will function correctly.