The title of this article should be .htaccess. The initial letter is capitalized due to technical restrictions.
.htaccess (Hypertext Access) is the default name of Apache’s directory-level configuration file. It provides the ability to customize configuration directives defined in the main configuration file. The configuration directives need to be in .htaccess context and the user needs appropriate permissions.
General information
A .htaccess file controls the directory it is in, plus all subdirectories. However, by placing additional .htaccess files in the subdirectories, this can be overruled.
As a configuration file, .htaccess is very powerful. Even the slightest syntax error (like a missing space) can result in severe server malfunction. Thus it is crucial to make backup copies of everything related to your site (including any original .htaccess files) before working with your Hypertext Access file(s). It is also important to check your entire website thoroughly after making any changes to your .htaccess file. In many cases, it is preferable to use cPanel to make these changes for you.
Common usage
There’s an almost endless list of things you can do with .htaccess files, but they are not for the faint-hearted. One small error can make your entire site inaccessible. Some of the most useful functions can be done from cPanel, which writes the .htaccess file for you and is generally a safer option than directly editing .htaccess files yourself.
Custom error pages
For more information, see Error pages (cPanel) and List of error pages
The ErrorDocument directive is used to determine what page is shown when a server error occurs.
ErrorDocument 404 my404page.html ErrorDocument 403 forbidden.html
This code can be used to create any custom page. Certain pages are more complicated to modify – if you create a custom “403 Forbidden” page, then a viewer will not see the custom page. Here is a way to get around this:
ErrorDocument 403 /errors/forbidden.html
In the /errors directory, you may need another .htaccess file, ie:
Order allow,deny Allow from all
This would allow all users, even those forbidden at /, to access the /errors directory, where the custom 403 page is kept in this example.
Password protection
For more information see Password Protect Directories (cPanel)
Make the user enter a name and password before viewing a directory.
AuthUserFile /home/newuser/www/stash/.htpasswd AuthGroupFile /dev/null AuthName "Protected Directory" AuthType Basic <Limit GET POST> require user newuser </Limit>
Now run this command to create a new password for the user ‘newuser’.
htpasswd /home/newuser/www/stash/.htpasswd newuser
To unprotect a directory inside an otherwise protected structure:
Satisfy any
Enable SSI
AddType text/html .shtml AddHandler server-parsed .shtml Options Indexes FollowSymLinks Includes
Deny users by IP address
Order allow,deny Deny from 123.45.67.8 Deny from 123.123.7 Allow from all
This would ban anyone with an IP address of 123.45.67.8 and would also ban anyone with an IP address starting in 123.123.7: for example, 123.123.74.42 would not gain access.
Directory Listing
If there is no default document (eg index.html) you can have the web server produce a list of files:
Options +Indexes
To stop this behavior and create an error if there’s no default document:
Options -Indexes
To show a fancy list including icon, file size, etc:
Options +Indexes IndexOptions +FancyIndexing
or to turn of fancy listing:
IndexOptions -FancyIndexing
To stop some files (eg gif and jpg images) from being listed:
IndexIgnore *.gif *.jpg
Change the default directory page
DirectoryIndex homepage.html
Here, anyone visiting http://www.yourdomain.com/ would see the homepage.html page, rather than the default index.html.
Redirects
For more information see Redirects (cPanel) or mod_rewrite
Standard temporary redirect
Redirect page1.html page2.html
If someone was to visit http://www.yourdomain.com/page1.html, they would be sent (with a status code of 302) to http://www.yourdomain.com/page2.html
Redirect visitors to a temporary site during site development
During web development, maintenance, or repair, send your visitors to an alternate site while retaining full access for yourself. This is a very useful technique for preventing visitor confusion or dismay during those awkward, web-development moments.
ErrorDocument 403 http://www.alternate-site.com Order deny,allow Deny from all Allow from 99.88.77.66
Redirect individual files
To redirect individual files, like example.com/oldfile.htm to newfile.htm you can use a 301 redirect like this:
Redirect 301 /oldfile.htm /newfile.htm
To redirect one specific file to another domain such as example.com/oldfile.htm to example.net/newfile.htm:
Redirect 301 /oldfile.htm http://example.net/newfile.htm
Redirect an old domain to a new domain
If you had an old domain such as example.com, and now you decided you actually want to use example.net for the website. You could set up a 301 redirect for the entire domain, so that old links to example.com carry over.
RewriteEngine on
RewriteCond %{HTTP_HOST} ^example.com [NC,OR]
RewriteCond %{HTTP_HOST} ^www.example.com [NC]
RewriteRule ^(.*)$ http://example.net/$1 [L,R=301,NC]Force www. version of domain to be used
A search engine like Google would see example.com and www.example.com as essentially two separate websites. They recommend you pick one version you’d like search engines to display and using a 301 redirect is a possible option.
If you have a lot of links on the web where people are linking to your site as example.com, but you would like your visitors to instead end up at www.example.com you can force this version of your domain with these rules:
RewriteEngine on
RewriteCond %{HTTP_HOST} ^example.com [NC]
RewriteRule ^(.*)$ http://www.example.com/$1 [L,R=301,NC]Force non www. version of domain to be used
If you have a lot of links on the web where people are linking to your site as www.example.com, but you would like your visitors to instead end up at example.com you can force this version of your domain with these rules:
RewriteEngine on
RewriteCond %{HTTP_HOST} ^www.example.com [NC]
RewriteRule ^(.*)$ http://example.com/$1 [L,R=301,NC]Redirect all files with a certain extension
To re-direct all of one type of file to another, such as example.com/file.php to example.com/file.htm
RewriteEngine On
RewriteCond %{REQUEST_URI} .php$
RewriteRule ^(.*).php$ /$1.htm [R=301,L]Send visitors to a subdomain
This rule will ensure that all visitors are viewing pages via the subdomain of your choice:
RewriteCond %{HTTP_HOST} !^$
RewriteCond %{HTTP_HOST} !^subdomain\.domain\.com$ [NC]
RewriteRule ^/(.*)$ http://subdomain.domain.tld/$1 [L,R=301] Prevent hotlinking of images
For more information see HotLink Protection (cPanel)
The following .htaccess rules use mod_rewrite. You only need to include RewriteEngine on once in an .htaccess file, and it may not be required at all if set in the server config file.
To prevent hotlinking from a specific domain:
RewriteEngine on
RewriteCond %{HTTP_REFERER} ^http://([^/]+.)?baddomain1.com [NC,OR]
RewriteCond %{HTTP_REFERER} ^http://([^/]+.)?baddomain2.com [NC,OR]
RewriteCond %{HTTP_REFERER} ^http://([^/]+.)?baddomain3.com [NC]
RewriteRule .(gif|jpg)$ http://www.example.com/hotlink.gif [R,L]To prevent hotlinking from anywhere except specific domains:
RewriteEngine on
RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !^http://(www.)?example.com/.*$ [NC]
RewriteRule .(gif|jpg)$ http://www.example.com/hotlink.gif [R,L]Unless the image is displayed on example.com, browsers would see the image hotlink.gif.
Note: Hotlink protection using .htaccess relies on the client sending the correct “Referer” value in the http GET request. Programs such as Windows Media Player send a blank referrer, so attempts to use .htaccess to protect movie files for example are ineffective.
Force file download
You can use the AddType directive to force a file download instead of showing in the user’s browser. In your HTML directly link to the file. The user will get a pop-up box asking whether they want to save the file or open it:
AddType application/octet-stream .avi AddType application/octet-stream .mpg AddType application/octet-stream .mov AddType application/octet-stream .pdf
Prevent files from being cached
This is similar to how google ads employ the header Cache-Control: private, x-gzip-ok=”” to prevent caching of ads by proxies and clients.
<FilesMatch ".(html|htm|js|css)$"> Header set Cache-Control "max-age=0, no-cache, no-store, private" Header set Pragma "no-cache" Header set Expires "0" </FilesMatch>
Remove IE imagetoolbar
<FilesMatch ".(html|htm)$"> Header set imagetoolbar "no" </FilesMatch>
Show source code instead of executing
If you’d rather have .pl, .py, or .cgi files displayed in the browser as sources rather than be executed as scripts. Be very careful with this one!
RemoveHandler cgi-script .pl .py .cgi
Other uses
Some web developers have modified .htaccess to perform custom tasks server-side before serving content to the browser. Developer Shaun Inman shows it is possible to edit .htaccess to allow for server-side constants within CSS.
