Note: the explanation below works for Apache 1.x, but apparently not for Apache 2, or at least not for the way it has been set up on this host. The examples below might not work because of this problem, I hope to be able to fix this soon.

HTAccess is a user-side configuration tool for Apache-based websites. It's useful to regulate for example access and errorpages (and lots more, but for that I would like to refer to This short howto relates to the two forementioned topics, also because they're implemented in this website.

As I said, and as the official howto specifies, HTAccess is user-side specific, meaning it is meant for control over your website when you do not have access to the main webserver configuration. As this is the case for many vhost-based websites, which are often reachable from colocated servers running Apache as webserver, HTAccess is an often used tool. It's also important to know that HTAccess is top-down directory recursive, with the lowest level having the highest priority (so your .htaccess in /home/www/site/test/ will apply to the directory /home/www/site/test/more/, but the .htaccess file in /home/www/site/test/more/ will override the .htaccess in /home/www/site/test/, and .htaccess files found higher up in the tree, up onto the server configuration (if allowed)).

I will address two HTAccess uses: username/password access control per directory, and the how to create your own errorpages (Error 401, 403, 404 and 500 are the most common).

Access Control

You might have parts of your website which you don't like to show others. Sometimes for testing, other times for privacy issues, or sometimes just to restrict access to a select group of people (selected by you, ofcourse). Three files are involved for this:

Note that I refer to these files with names preceded by a "." (dot), but the actual files I refer to are not preceded by a dot. The reason for this is that files preceded by a dot are not shown to the visitor by the webserver, so I had to omit the dots.

The contents of the files then. First .htaccess: AuthUserFile and AuthGroupFile speak for themselves. AuthName is the title of the popup that comes up when asking for the username/password combination. AuthType is the type of authorisation used (Basic or Digest; with Digest, the password is sent with MD5 encoding to the webserver, but this doesn't work in all browsers, so make sure you know what you're doing before you use that), <Limit GET> limits the users within that tag to only the GET action on the protected directory and it's contents, and Require user defines which users have access, when using the correct password. As you can see, only one person is included there, so, no matter how many users are included in .htpasswd or .htgroup, only this one will have access.

Then .htgroup. This file is really not necessary in many cases, but it can be useful when you want to define certain groups with different privileges; think of admins vs. users for example. Basically all there's in this .htgroup file is two group definition (users/admins) with the defined users behind it. You can see three users defined, but as long as not all of them are listed in both .htaccess and .htpasswd as well, the users won't have access anywhere.

The last file is .htpasswd. This file basically lists the passwords, encrypted, per user. If you want to manage these passwords, you could use 'htpasswd'. To create a new .htpasswd file you can execute 'htpasswd -c .htpasswd username'; it will ask for a password, a confirmation of the password, and then will tell you it created a .htpasswd file. If you're updating an existing file, just omit the '-c'. Then, if you are adding a new user, it will respond that the new user was added, and if you're changing a password for an already listed user, it will confirm the change. Here you see two users defined, the passwords are obviously fake.

Now, place .htgroup and .htpasswd in the root directory of your website. This is the most logical place for them, because you can define all your users, groups and passwords globally for your whole site here. To differentiate on which users have access where, you can use the .htaccess file per directory. So, place the .htaccess file in the directory that needs to be protected. Remember that the directories down in the tree from where your .htaccess is located, are also protected by the properties defined in that .htaccess configuration. If you want to change that, you explicitely need to state so by placing a .htaccess file which negates/overrides the one up in the tree.

Custom Error Pages

Errormessages on your website, like "404 - file not found" are displayed by regular html files. You can tell your webserver to use a custom page by creating a .htaccess file which you can find here. As you can see, all you really do is define which error shows which page. An example of these errors in action can be found when you go to this link which doesn't exist or to this link which you are not allowed to visit. Note that the location of the errorpage starts with a / - this does not mean that /xxx.html is in a root directory on the server, but the / means "relative to the directory where the .htaccess file is located". This is quite necessary, or otherwise the server will be looking for an errorpage relative to your current position; but that doesn't always exist. For example, in, I did not place an errormessage saying access is prohibited. So if the / wasn't there, you would generate a second error right away! :-) Also, since Apache has been upgraded to the latest version, it's no longer possible to have error pages in other directories than the rootdirectory. Why this is, is unknown to me, but as long as you put the errormessage in the root of your webdirectories, everything is fine.

Note: always remember to name your HTAccess files ".ht*". If the dot isn't there, it won't work, but worse, it might be visible to the world, which is not good, especially if it contains authorisation information. Files which have names preceded by a dot will never be made visible by the webserver (unless it has been quite misconfigured).

Talk to Kryz

(c) 2001 - 2005: Kryz for content, Anya for design