How to use .htaccess

introduction to .htaccess

There’s a good reason why you won’t see .htaccess files on the web; almost every web server in the world is configured to ignore them, by default. Same goes for most operating systems. Mainly it’s the dot “.” at the start, you see?

If you don’t see, you’ll need to disable your operating system’s invisible file functions, or use a text editor that allows you to open hidden files, something like bbedit on the Mac platform. On windows, showing invisibles in explorer should allow any text editor to open them, and most decent editors to save them too**. Linux dudes know how to find them without any help from me.
Mac Finder view with invisible files
that same folder, as seen from Mac OS X

In both images, the operating system has been instructed to display invisible files. ugly, but necessary sometimes. You will also need to instruct your ftp client to do the same.

By the way; the windows screencap is more recent than the mac one, moved files are likely being handled by my clever 404 script.

** even notepad can save files beginning with a dot, if you put double-quotes around the name when you save it; i.e.. “.htaccess”. You can also use your ftp client to rename files beginning with a dot, even on your local filesystem; works great in FileZilla.

What are .htaccess files anyway?
Simply put, they are invisible plain text files where one can store server directives. Server directives are anything you might put in an Apache config file (httpd.conf) or even a php.ini**, but unlike those “master” directive files, these .htaccess directives apply only to the folder in which the .htaccess file resides, and all the folders inside.

This ability to plant .htaccess files in any directory of our site allows us to set up a finely-grained tree of server directives, each subfolder inheriting properties from its parent, whilst at the same time adding to, or over-riding certain directives with its own .htaccess file. For instance, you could use .htacces to enable indexes all over your site, and then deny indexing in only certain subdirectories, or deny index listings site-wide, and allow indexing in certain subdirectories. One line in the .htaccess file in your root and your whole site is altered. From here on, I’ll probably refer to the main .htaccess in the root of your website as “the master .htaccess file”, or “main” .htaccess file.

There’s a small performance penalty for all this .htaccess file checking, but not noticeable, and you’ll find most of the time it’s just on and there’s nothing you can do about it anyway, so let’s make the most of it..

** Your main php.ini, that is, unless you are running under phpsuexec, in which case the directives would go inside individual php.ini files

What can I do with .htaccess files?
Almost any directive that you can put inside an httpd.conf file will also function perfectly inside an .htaccess file. Unsurprisingly, the most common use of .htaccess is to..

control access
.htaccess is most often used to restrict or deny access to individual files and folders. A typical example would be an “includes” folder. Your site’s pages can call these included scripts all they like, but you don’t want users accessing these files directly. In that case you would drop an .htaccess file in the includes folder with content something like this..

NO ENTRY!
# no one gets in here!
deny from all

which would deny ALL direct access to ANY files in that folder. You can be more specific with your conditions, for instance limiting access to a particular IP range, here’s a handy top-level rule for a local test server..

NO ENTRY outside of the LAN!
# no nasty crackers in here!
order deny,allow
deny from all
allow from 192.168.0.0/24
# this would do the same thing..
#allow from 192.168.0

Generally these sorts of requests would bounce off your firewall anyway, but on a live server (like my dev mirror sometimes is) they become useful for filtering out undesirable IP blocks, known risks, lots of things. By the way, in case you hadn’t spotted; lines beginning with “#” are ignored by Apache; handy for comments.

Sometimes, you will only want to ban one IP, perhaps some persistent robot that doesn’t play by the rules..

post user agent every fifth request only. hmmm. ban IP..
# someone else giving the ruskies a bad name..
order allow,deny
deny from 83.222.23.219
allow from all

The usual rules for IP addresses apply, so you can use partial matches, ranges, and so on. Whatever, the user gets a 403 “access denied” error page in their client software (browser, usually), which certainly gets the message across. This is probably fine for most situations, but in part two I’ll demonstrate some cooler ways to deny access.

custom error documents
I guess I should briefly mention that .htaccess is where most folk configure their error documents. Usually with sommething like this..

the usual method. the “err” folder (with the custom pages) is in the root
# custom error documents
ErrorDocument 401 /err/401.php
ErrorDocument 403 /err/403.php
ErrorDocument 404 /err/404.php
ErrorDocument 500 /err/500.php

You can also specify external URLs, though this can be problematic, and is best avoided. One quick and simple method is to specify the text in the directive itself, you can even use HTML (though there is probably a limit to how much HTML you can squeeze onto one line). Remember to begin with a “, but DO NOT end with one.

measure twice, quote once..
# quick custom error “document”..
NO! ErrorDocument 404 “
There is nothing here.. go away quickly!

Using a custom error document is a Very Good Idea, and will give you a second chance at your almost-lost visitors. I recommend you download mine. But then, I would.

password protected directories
The next most obvious use for our .htaccess files is to allow access to only specific users, or user groups, in other words; password protected folders. a simple authorisation mechanism might look something like this..

a simple sample .htaccess file for password protection:
AuthType Basic
AuthName “restricted area”
AuthUserFile /usr/local/var/www/html/.htpasses
require valid-user

You can use this same mechanism to limit only certain kinds of requests, too..

only valid users can POST in here, anyone can GET, PUT, etc:
AuthType Basic
AuthName “restricted area”
AuthUserFile /usr/local/var/www/html/.htpasses

require valid-user

You can find loads of online examples of how to setup authorization using .htaccess, and so long as you have a real user (or create one, in this case, ‘jimmy’) with a real password (you will be prompted for this, twice) in a real password file (the -c switch will create it)..

htpasswd -c /usr/local/var/www/html/.htpasses jimmy

..the above will work just fine. htpasswd is a tool that comes free with Apache, specifically for making and updating password files, check it out. The windows version is the same; only the file path needs to be changed; to wherever you want to put the password file.

Note: if the Apache bin/ folder isn’t in your PATH, you will need to cd into that directory before performing the command. Also note: You can use forward and back-slashes interchangeably with Apache/php on Windows, so this would work just fine..

htpasswd -c c:/unix/usr/local/Apache2/conf/.htpasses jimmy

Relative paths are fine too; assuming you were inside the bin/ directory of our fictional Apache install, the following would do exactly the same as the above..

htpasswd -c ../conf/.htpasses jimmy

Naming the password file .htpasses is a habit from when I had to keep that file inside the web site itself, and as web servers are configured to ignore files beginning with .ht, they too, remain hidden. If you keep your password file outside the web root (a better idea), then you can call it whatever you like, but the .ht_something habit is a good one to keep, even inside the web tree, it is secure enough for our basic purpose..

Once they are logged in, you can access the remote_user environmental variable, and do stuff with it..

the remote_user variable is now available..
RewriteEngine on
RewriteCond %{remote_user} !^$ [nc]
RewriteRule ^(.*)$ /users/%{remote_user}/$1

Which is a handy directive, utilizing mod_rewrite; a subject I delve into far more deeply, in part two.

get better protection..
The authentication examples above assume that your web server supports “Basic” http authorisation, as far as I know they all do (it’s in the Apache core). Trouble is, some browsers aren’t sending password this way any more, personally I’m looking to php to cover my authorization needs. Basic auth works okay though, even if it isn’t actually very secure - your password travels in plain text over the wire, not clever.

If you have php, and are looking for a more secure login facility, check out pajamas. It’s free. If you are looking for a password-protected download facility (and much more, besides), check out my distro machine, also free.

500 error
If you add something that the server doesn’t understand or support, you will get a 500 error page, aka.. “the server did a boo-boo”. Even directives that work perfectly on your test server at home may fail dramatically at your real site. In fact this is a great way to find out if .htaccess files are enabled on your site; create one, put some gibberish in it, and load a page in that folder, wait for the 500 error. if there isn’t one, probably they are not enabled.

If they are, we need a way to safely do live-testing without bringing the whole site to a 500 standstill.

Fortunately, in much the same way as we used the
tag above, we can create conditional directives, things which will only come into effect if certain conditions are true. The most useful of these is the “ifModule” condition, which goes something like this..

only if PHP is loaded, will this directive have any effect

php_value default_charset utf-8

..which placed in your master .htaccess file, that would set the default character encoding of your entire site to utf-8 (a good idea!), at least, anything output by PHP. If the PHP4 module isn’t running on the server, the above .htaccess directive will do exactly nothing; Apache just ignores it. As well as proofing us against knocking the server into 500 mode, this also makes our .htaccess directives that wee bit more portable. Of course, if your syntax is messed-up, no amount of if-module-ing is going to prevent a error of some kind, all the more reason to practice this stuff on a local test server.

groovy things to do with .htaccess
So far we’ve only scratched the surface. aside from authorisation, the humble .htaccess file can be put to all kinds of uses. If you’ve ever had a look in my public archives you will have noticed that that the directories are fully browsable, just like in the old days before adult web hosts realized how to turn that feature off! a line like this..

bring back the directories!
Options +Indexes +MultiViews +FollowSymlinks

will almost certainly turn it back on again. And if you have mod_autoindex.c installed on your server (probably, yes), you can get nice fancy indexing, too..

show me those files!

IndexOptions FancyIndexing

..which, as well as being neater, allows users to click the titles and, for instance, order the listing by date, or file size, or whatever. It’s all for free too, built-in to the server, we’re just switching it on. You can control certain parameters too..

let’s go all the way!

IndexOptions FancyIndexing IconHeight=16 IconWidth=16

Other parameters you could add include..

NameWidth=30
DescriptionWidth=30
IconsAreLinks SuppressHTMLPreamble (handy!)

I’m not mentioning the “XHTML” parameter in Apache2, because it still isn’t! Anyways, I’ve chucked one of my old fancy indexing .htaccess file onsite for you to have some fun with. Just add readme.html and away you go! note: these days I use a single header files for all the indexes, and only drop in local “readme” files. Check out the example, and my public archives for more details.

custom directory index files
While I’m here, it’s worth mentioning that .htaccess is where you can specify which files you want to use as your indexes, that is, if a user requests /foo/, Apache will serve up /foo/index.html, or whatever file you specify.

You can also specify multiple files, and Apache will look for each in order, and present the first one it finds. It’s generally setup something like..

DirectoryIndex index.html index.php index.htm

It really is worth scouting around the Apache documentation, often you will find controls for things you imagined were uncontrollable, thereby creating new possibilities, better options for your website. My experience of the magic “LAMP” (Linux-Apache-MySQL-PHP) has been.. “If you can imagine that it can be done, it can be done”. Swap “Linux” for any decent operating system, the “AMP” part runs on most of them.

Okay, so now we have nice fancy directories, and some of them password protected, if you don’t watch out, you’re site will get popular, and that means bandwidth..

save bandwidth with .htaccess!
If you pay for your bandwidth, this wee line could save you hard cash..

save me hard cash! and help the internet!

php_value zlib.output_compression 16386

All it does is enables PHP’s built-in transparent zlib compression. This will half your bandwidth usage in one stroke, more than that, in fact. Of course it only works with data being output by the PHP module, but if you design your pages with this in mind, you can use php echo statements, or better yet, php “includes” for your plain html output and just compress everything! Remember, if you run phpsuexec, you’ll need to put php directives in a local php.ini file, not .htaccess. See here for more details.

hide and deny files
Do you remember I mentioned that any file beginning with .ht is invisible? ..”almost every web server in the world is configured to ignore them, by default” and that is, of course, because .ht_anything files generally have server directives and passwords and stuff in them, most servers will have something like this in their main configuration..

Standard setting..

Order allow,deny
Deny from all
Satisfy All

which instructs the server to deny access to any file beginning with .ht, effectively protecting our .htaccess and other files. The “.” at the start prevents them being displayed in an index, and the .ht prevents them being accessed. This version..

ignore what you want

Order allow,deny
Deny from all
Satisfy All

tells the server to deny access to *.log files. You can insert multiple file types into each rule, separating them with a pipe “|”, and you can insert multiple blocks into your .htaccess file, too. I find it convenient to put all the files starting with a dot into one, and the files with denied extensions into another, something like this..

the whole lot
# deny all .htaccess, .DS_Store $hî†é and ._* (resource fork) files

Order allow,deny
Deny from all
Satisfy All

# deny access to all .log and .comment files

Order allow,deny
Deny from all
Satisfy All

would cover all ._* resource fork files, .DS_Store files (which the Mac Finder creates all over the place) *.log files, *.comment files and of course, our .ht* files. You can add whatever file types you need to protect from direct access. I think it’s clear now why the file is called “.htaccess”.
These days, using is preferred over , mainly because you can use regular expression in the conditions (very handy), produce clean, more readable code. Here’s an example. which I use for my php-generated style sheets..

parse file.css and file.style with the php machine..
# handler for phpsuexec..

SetHandler application/x-httpd-php

Any files matching the regular expression statement, that is files with a *.css or *.style extension, will now be handled by php, rather than simply served up by Apache. Any statements you come across can be advantageously replaced by statements. Good to know.