.htaccess, a primer…
Submitted by sandip on Thu, 09/04/2003 – 10:48. Scripting
The Apache web server has a number of configuration options that are available to the server administrator. In a shared hosting environment, you don’t have access to the main Apache configuration so you’re stuck with the default configuration. However, it is possible to override some of the default settings by creating (or editing) a file named “.htaccess”.
The .htaccess is a simple ASCII text file placed in your www directory or in a subdirectory of your www directory. You can create or edit this file in any text editor (such as NotePad) and then upload it to the directory for which you want to modify the settings. Be sure that the file is uploaded in ASCII (not BINARY) format, and be sure that the file permissions for the file are set to 644 (rw-r–r–). This allows the server to access the file, but prevents visitors from accessing the file through their web browser (a security risk.)
Commands in the .htaccess file affect the directory that it’s placed in and all subdirectories. If you place the .htaccess file in your www directory, it will affect your entire web site. If you place it in a subdirectory of your www directory, it will affect only that directory plus and subdirectories of that directory.
Most .htaccess commands are designed to be placed on one line. If your text editor wraps lines automatically, you should disable that function before saving and uploading your file. Also, note that .htaccess commands are case-sensitive.
The information presented here may work and it may not, or it may work today and not tomorrow. Use it at your own risk.
Some of the things you can do with .htaccess include:
Customize Error Messages
If you want to override the server’s error pages, you can use .htaccess to define your own messages. An example of the syntax is:
ErrorDocument 500 /error.html
Override SSI Settings
By default, only pages ending in the .shtml extension will parse server-side includes (SSI). You can override this restriction in your .htaccess file:
If you want to override the default server configuration so that SSI will work with .html documents, you can create a file named .htaccess and upload it (in ASCII mode) to your main www directory. Add the following lines to your .htaccess file:
AddType text/html .html
AddHandler server-parsed .html
If you want both .html and .htm documents to parse SSI, create your .htaccess file with these lines:
AddType text/html .html
AddHandler server-parsed .html
AddHandler server-parsed .htm
Change Your Default Home Page
In order to browse your site by specifying the domain name only (e.g., http://www.yourdomain.com) instead of having to specify an exact page filename (e.g., http://www.yourdomain.com/filename.html), you must have an index page in your www directory. Default acceptable file names for index pages include index.htm, index.html, index.cgi, index.shtml, index.php, etc. Note that they’re all named index.*.
There is also a default order of precedence for these names. So if you have both a file named index.cgi and a file named index.html in your directory, the server will display index.cgi because that name takes a higher precedence than index.html.
Using .htaccess, you can define additional index filenames and/or change the order of precedence. To define your index page as custom.html add the following line to your .htaccess file:
DirectoryIndex custom.html
This will cause the server to look for a file named custom.html. If it finds that file, it will display it. If it does not find that file, it will return a 404 Missing Page error.
To change the order of precedence, enter a DirectoryIndex command with multiple file names on the same line. The order in which the file names are listed (from left to right) determines the order of precedence. For example,
DirectoryIndex custom.html index.cgi index.php index.html
Enable Directory Browsing
This is the option that allows the contents of a directory to be displayed in the browser when the directory does not contain an index page.
For example, if you make an http call to a directory such as http://yourdomain.com/images/, it would list all the images in that directory without the need for an html page with links.
If you require this option on specific directories it is still available. You can reactivate it by adding the following line to your .htaccess file:
Options +Indexes
Once this is added, the directory will fully index again. (Note: Coversely “Options -Indexes” will prevent directory browsing.)
Preventing Directory Listing
Do you have a directory full of images or zips that you do not want people to be able to browse through? Typically a server is setup to prevent directory listing, but sometimes they are not. If not, become self-sufficient and fix it yourself:
IndexIgnore *
The * is a wildcard that matches all files, so if you stick that line into an htaccess file in your images directory, nothing in that directory will be allowed to be listed.
On the other hand, what if you did want the directory contents to be listed, but only if they were HTML pages and not images? Simple says I:
IndexIgnore *.gif *.jpg
This would return a list of all files not ending in .jpg or .gif, but would still list .txt, .html, etc.
Block Users from Accessing Your Web Site
If you want to deny access to a particular individual, and you know the IP address or domain name that the individual uses to connect to the Internet, you can use .htaccess to block that individual from your web site.
<Limit GET>
order deny,allow
deny from 123.456.789.000
deny from 456.78.90.
deny from .aol.com
allow from all
</Limit>
In the example above, a user from the exact IP number 123.456.789.000 would be blocked; all users within a range of IP numbers from 456.78.90.000 to 456.78.90.999 would be blocked; and all users connecting from America Online (aol.com) would be blocked. When they attempted to browse your web site, they would be presented with the 403 Forbidden (“You do not have permission to access this site”) error.
Redirect Visitors to a New Page or Directory
Let’s say you re-do your entire web site, renaming pages and directories. Visitors to the old pages will receive the 404 File Not Found error. You can solve this problem by redirecting calls to an old page to the new page. For example, if your old page was named oldpage.html and that page has been replaced by newpage.html, add this line to your .htaccess file:
Redirect permanent /oldpage.html http://www.mydomain.com/newpage.html
Of course, you want to replace mydomain.com with your actual domain name. Now, when the visitor types in http://www.mydomain.com/myoldpage.html, they will be automatically redirected to http://www.mydomain.com/mynewpage.html.
If you’ve renamed a directory, you can use one redirect line to affect all pages within the directory:
Redirect permanent /olddirectory http://www.mydomain.com/newdirectory/
Note that the old page or directory is specified using the system path relative to your www directory, while the new page or directory is specified by the absolute URL.
Prevent Hot Linking and Bandwidth Leeching
What if another web site owner is stealing your images and your bandwidth by linking directly to your image files from his/her web site? You can prevent this by adding this to your .htaccess file:
RewriteEngine on
RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !^http://(www\.)?mydomain.com/.*$ [NC]
RewriteRule \.(gif|jpg)$ - [F]
Replace mydomain.com with your actual domain name. With this code in place, your images will only display when the visitor is browsing http://mydomain.com. Images linked from other domains will appear as broken images.
If you’re feeling particularly nasty, you can even provide an alternative image to display on the hot linked pages — for example, an image that says “Stealing is Bad … visit http://mydomain.com to see the real picture that belongs here.” Use this code to accomplish that:
RewriteEngine on
RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !^http://(www\.)?mydomain.com/.*$ [NC]
RewriteRule \.(gif|jpg)$ http://www.mydomain.com/dontsteal.gif [R,L]
This time, replace mydomain.com with your domain name, and replace dontsteal.gif with the file name of the image you’ve created to discourage hot linking.
Prevent viewing of .htaccess or other files
To prevent visitors from seeing the contents of your .htaccess file, place the following code in the file:
<Files .htaccess>
order allow,deny
deny from all
</Files>
If you want to prevent visitors from seeing another file, just substitute that file’s name for .htaccess in the Files specification.
Eliminate Code Red and NIMDA Virus Attacks from your Access Log
Placing the below redirects in .htacess eliminates the logging problem without affecting your personalized error redirecting scripts.
redirect /scripts http://www.stoptheviruscold.invalid
redirect /MSADC http://www.stoptheviruscold.invalid
redirect /c http://www.stoptheviruscold.invalid
redirect /d http://www.stoptheviruscold.invalid
redirect /_mem_bin http://stoptheviruscold.invalid
redirect /msadc http://stoptheviruscold.invalid
RedirectMatch (.*)\cmd.exe$ http://stoptheviruscold.invalid$1
Access Control to your web files via .htaccess
Setting up access control using HTACCESS
There is an advantage to controlling access to certain parts of your domain. If, for instance, you wanted to make general information public, but only wanted to make specific information available to your customers you could use a feature of NCSA-based httpd servers commonly reffered to as HTACCESS.
Using this access control method you can limit access to certain branches of the directory tree. If you want to really understand how this works, nothing is better than reading the manual.
Basic Access Control
You can control access to your webpage two different ways, by host filtering or user authentication. But keep in mind that neither method is fullproof. This should be considered as secure as a courtesy lock on a restroom door; nice, but ultimately ineffective.
The default name of the access control file is .htaccess but that is not written in stone. In the server configuration overview we looked at a file called httpd.conf. This file had the following entry:
AccessFileName .htaccess
This is the default value, but any specified filename can be used. For the purposes of this tutorial I will refer to the .htaccess file by name, but your server may use a different file name.
The method of control is very simple. Place a correctly formated file called .htaccess in a directory and you can restrict access via the web to that directory. Here is a simple example of an .htacess file:
AuthUserFile /dev/null
AuthGroupFile /dev/null
AuthName "This is NOT a restricted directory"
AuthType Basic
<Limit GET>
order allow,deny
allow from all
</Limit>
The first two lines refer to files that contain lists of users and groups. I will cover the specific format of the files and their use later. The AuthName entry is displayed in the message box if the browser needs to request a username / password. AuthType is always Basic because the advanced authorization methods based on Kerberos or MD5 are detailed enough for books themselves.
The important parts for now are contained in the familiar looking
tag. GET is the only widely supported method. PUT was under developement to allow uploading and while POST is partially supported, its use is too complex for this document. Basically, to retrieve ANY document from this directory via the web, the web server will evaluate the .htaccess file and allow or deny access based on the outcome. The above example file is wide open and will allow anyone access. Let’s look at a more restrictive <Limit> rule.
<Limit GET>
order deny,allow
deny from all
allow from linuxweblog.com
</Limit>
This rule will cause everyone to be denied EXCEPT hosts from linuxweblog.com. The server processes the rules in order and the first exception case is returned. Here is another way to look at it.
<Limit GET>
order allow,deny
deny from linuxweblog.com
</Limit>
By changing the order to allow,deny and changing the allow entry to deny we have created a ban list. Everyone EXCEPT linuxweb.com hosts can get documents from the directory.
<Limit GET>
order deny,allow
allow from all
deny from linuxweblog.com 192.168.10.
</Limit>
This rule set is evaluated the same as the one above it, but includes an additional deny rule for the 192.168.10. domain. The drawback to using a DNS name can be illustrated if the web server can not resolve an IP address to a domain name. If you rely completely on DNS names and DNS ever fails, you may find yourself locked out of your own site!
Host access control is the simplest way to control access, but what if you have a different ip address every time you log in and you don’t want to allow everyone from your domain access to the directory tree? I’m glad I asked that.
User Based Access Control
The most effective method of access restriction is the use of a username and password. By using two additional files, people can be granted access either by username or group membership. These two files are conventionally called .htpasswd and .htgroup but they can be any name specified in the .htaccess file. I will refer to the conventional names, but feel free to change them on your site.
The .htpasswd file is a file that contains a list of usernames and encrypted passwords seperated by colons. Here is an example:
Bob:ZUvJgtVp77Vik
Ted:rBW8u1RJUr6eU
Carol:HwrJPys5u7NcM
Alice:UORwkyVbeWc6M
This is a list of a 4 user .htpasswd file. The format is similar to a standard Un*x /etc/passwd file and in fact the encryption method is compatible. So if you want, you can base the .htpasswd off of an actual modified Un*x /etc/passwd file. Here is an example of the .htgroup file:
Admin: Carol
Managers: Ted Carol
Staff: Bob Ted Carol Alice
The names of the groups are not special except as they are used. Using these files as examples, lets look at some new rule sets.
AuthUserFile /usr/local/etc/httpd/private/.htpasswd
AuthGroupFile /usr/local/etc/httpd/private/.htgroup
AuthName "This is a restricted directory"
AuthType Basic
<Limit GET>
order allow,deny
allow from all
require user Alice
require group Managers
satisfy any
</Limit>
In this case we have specified authorization user and group files and given a title to the message box. The rule will deny everyone EXCEPT Alice OR the group Managers. The satifisy element handles whether the rule is evalutated as a logical AND or OR. By default it is a logical AND. That means that without the “satisfy any” line it would assume “satisfy all” and require both user Alice and group Managers to access the directory. Since Alice is not a part of the Managers group NO ONE would have access to the directory. Let’s look at another one.
AuthUserFile /usr/local/etc/httpd/private/.htpasswd
AuthGroupFile /usr/local/etc/httpd/private/.htgroup
AuthName "This is a restricted directory"
AuthType Basic
<Limit GET>
order deny,allow
deny from all
allow from linuxweblog.com
require group Managers
satisfy all
</Limit>
This example combines both user and host validation. You have to supply a username that is in the Managers group AND be connecting from the linuxweblog.com domain.
Redirect browser to use SSL
You can redirect browser to use SSL secure port using .htaccess file with Rewrite Rules.
Create a .htaccess file with the below Rewrite rule.
Options +FollowSymLinks
RewriteEngine On
RewriteCond %{SERVER_PORT} !=443
RewriteRule ^ https://secure.yourdomain.com%{REQUEST_URI} [NS,R,L]
Redirecting Dynamic URL using mod_rewrite
What do you do when you need to move servers or web-files to a different domain or directory, especially if you need to be moving dynamic content. How would you prevent down-time? This is not an end all solution, but Apaches’ module mod_rewrite comes to the rescue of redirecting URLs.
Below are the steps that was taken to move web-files to a different servers.
1. Create a temporary unused sub-domain to point to the new servers IP address.
2. Allow for a day before you migrate your content to let the subdomain resolve.
3. Setup rewrite rule to redirect your current domain to the temporary domain after migrating content.
4. Change the Primary and Secondary NameServers for the domain to point to the new location.
5. Keep the redirection up for a while until the NameServers are fully resolved.
Below is an example of what was used:
# this tells the web server to allow rewriting for this directory
RewriteEngine On
# check the hostname to apply the redirection to
RewriteCond %{HTTP_HOST} domain.com [OR]
RewriteCond %{HTTP_HOST} http://www.domain.com
# describe the pattern to look for, and how to rewrite it
RewriteRule ^(.*)$ http://temp.domain.com/$1 [R]
All rewrite rules are contained in the .htaccess file. The rewrite rules cover all the files in the directory that contains the .htaccess file.
In general, each RewriteRule line specifies a pattern to look for, and a replacement text. The patterns can be very complicated — the rules have the full power of Unix Regular Expressions (ie. grep), but the example shown above will serve most people.
The “[R]” in the rewrite rule shown above tells the web server to redirect the user’s browser to the new URL. This is useful because the browser will show the new URL, and saving a bookmark will always lead to the new location.
Leaving the [R] off the line will also display the new URL, but a bookmark saved from the resulting page will continue to use the original (non-rewritten) URL. This would be useful if you want to preserve an easy-to-remember URL, but also want the ability to change it in the future.
Watermark images with mod_rewrite
Below is how I have watermarked images excluding thumbnails with the text “.thumb.” and “.highlight.” in the name of the image files.
Contents of “.htaccess” :
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !\.thumb\.|\.highlight\.
RewriteRule ^.*[Jj][Pp][Gg]$|.*[Gg][Ii][Ff]$|.*[Pp][Nn][Gg]$ watermark.php?%{REQUEST_FILENAME}
Contents of “watermark.php” :
<?php
// watermark.gif should have a transparent background.
$watermark = “watermark.gif”;
$image = $QUERY_STRING;
if (empty($image)) die();
if (!file_exists($image)) {
header(“404 Not Found”);
echo “File Not Found.”; die();
}
$outputType = getFileType($image);
watermark($image, $watermark, $outputType);
/**
Outputs the image $source with $watermark in the lower right corner.
@param $source the source image
@param $watermark the watermark to apply
@param $outputType the type to output as (png, jpg, gif, etc.)
defaults to the image type of $source if left blank
*/
function watermark($source, $watermark, $outputType=”") {
$sourceType = getFileType($source);
$watermarkType = getFileType($watermark);
if (empty($outputType)) $outputType = $sourceType;
if ($outputType == “gif”) $outputType = “png”; // Okay to remove
header(“Content-type:image/$outputType”);
// Derive function names
$createSource = “ImageCreateFrom”.strtoupper($sourceType);
$showImage = “Image”.strtoupper($outputType);
$createWatermark = “ImageCreateFrom”.strtoupper($watermarkType);
// Load original and watermark to memory
$output = $createSource($source);
$logo = $createWatermark($watermark);
ImageAlphaBlending($output, true);
// Find proper coordinates so watermark will be in the lower right corner
$x = ImageSX($output) – ImageSX($logo);
$y = ImageSY($output) – ImageSY($logo);
// Display
ImageCopy($output, $logo, $x, $y, 0, 0, ImageSX($logo), ImageSY($logo));
$showImage($output);
// Purge
ImageDestroy($output);
ImageDestroy($logo);
}
function getFileType($string) {
$type = strtolower(eregi_replace(“^(.*)\.”,”",$string));
if ($type == “jpg”) $type = “jpeg”;
return $type;
}
?>
