Guide to htaccess

This page is a basic guide to how to use htaccess files. There are some useful tips here that will get you out of trouble, and several common htaccess scripts that will solve various problems for you.

Please bear in mind that, in direct contrast to other material on this site, we are just recycling the work of others who know a lot more about this than we do. All we do is make it easy to find.

Using an htaccess file

An htaccess file is one of the configuration files for a LAMP server - a Linux or Unix operating system computer, with the Apache server program installed, that is used to serve websites to visitors and is the basis of the Internet. It is also one of the many reasons why a LAMP server is superior to a Windows IIS server: the local website operational configs on a LAMP server can be set up in minutes by the webmaster; but an IIS server normally needs tech support from the hosts for the smallest task, for every website on the server.

To repeat: a Windows server, aka an IIS server, has no htaccess file facility. All webmaster operations for all sites on the server must be done by the web hosts, in the IIS Manager console, to which only they have access. This includes all basic tasks such as duplicate domain fixes, duplicate index page fixes, page redirects, and so on.

It means that a Windows server is more appropriate for a dedicated server than shared hosting, as normal webmastering tasks have to be done by the site hosting tech support, and cannot be done by the site manager.

The main configuration files on a LAMP server are:

• The httpd.conf file (accessible to the hosts only)
• The top-level htaccess file (accessible to the hosts only)
• The main php.ini config file (accessible to the hosts only)
• The local htaccess file, which can be organised to override many of the server-level configs and is accessible to each website owner
• An optional local-level php.ini file, which again can be used to override some of the server settings at a local level
  

So there are some things to note about htaccess files:

1. If it doesn't work, whatever you do - are you sure you're on a Linux / Unix (LAMP) server? It won't work on a Windows server, you have to get your site hosts to do everything. Frequently they charge for this, since their workload is much higher than on a LAMP server. IIS servers are more suited to dedicated server use, where the owner has access to the main server configurations (the IIS Manager).

2. There are a lot of differences between various LAMP servers. Therefore various htaccess configurations must be tried, to get a satisfactory result. It is quite common to have 4 or 5 variations of a simple line of script, only one of which works on any given server. There is no such thing as a line of script in an htaccess file that works on every server, apart from the most simple and basic commands.

3. Learn to comment-out and/or uncomment lines in an htaccess file - this will be a major work tool for helping you out. Just place a hash / gate / number symbol like this: # ...at the start of a line, and the server will ignore it. If you put two in like this ## it can help to differentiate your own 'commentary'.

How to create an htaccess file

It is difficult to create an htaccess file on a Windows PC for two reasons:

• This is a Linux operating system filename, and Windows doesn't like such names: it won't let you start a filename with a stop [.]
• Windows wants to see a file extension, eg .html - so you need to use a workaround.
  

It's not impossible of course, but rather than trying to be clever we'll create the file as a simple text file, then change its name once it's on the server.

1. Open Notepad or any other simple text editor (not Word), and create a blank file called 1.htaccess.txt, and save it. The file opens in a text editor as it is a text file. Now remove the .txt file extension, to give 1.htaccess - you can still open it as normal because the file has not changed at all. Removing or changing the extension has no effect on a file, only its appearance in Windows. You may have to choose what app to open the file with - choose Notepad. However it is better and easier to use a real text editor such as NoteTab, which has a free version. With this, you can go to its Options and associate htaccess files with NoteTab, and they will always open in it. Text editors like this produce 'clean' text, that is they are like Notepad, and unlike Word, do not insert junk metadata into the text that wrecks it when used in another file or application.

2. Scripts (any line or lines of code instructions) are then placed in this file, and it is uploaded to the server. When it is on the server, the filename can be changed from 1.htaccess to .htaccess simply by removing the 1. That can be done either in the File Manager, in the Control Panel (cPanel, Ensim etc), or via FTP. Because it is named '1' it will appear first in all file lists. You can upload the file via the Control Panel or FTP.

Comments in an htaccess file

After learning how to make an htaccess file, getting it onto the server, and renaming it - the next thing is to look at the content. The first thing that strikes you is the commenting system.

Text-based code of any kind is normally commented. That means:

• You add your own instructions, before important lines
• You 'install' or 'uninstall' lines of script by placing or removing a symbol at the start of the line - called commenting-out
• You don't delete lines, you comment them out
  

When you put a line of script in, you should place a description of its purpose above it. That description is commented-out. The symbol used in an htaccess file (all file types use different comment symbols) is a hash, #, and you can use two for your reminders, one only for code lines that need to be disabled. If you look at the example htaccess file just below, you'll see that convention used there. This system is called 'commenting the code' and the lines that are preceded by symbols are 'commented-out' and are not used by the system. All good code is commented, because it means that (1) you can instantly see what your code is designed to do, after time has passed and you have forgotten the workings of the file; (2) others can also interpret your code easily.

Things to know about htaccess files

There are some points you need to remember here.

• Only basic commands are guaranteed to work. All other commands may need to have variations tried, to find one that works on your server. All LAMP servers are different and it sometimes takes several versions of any one command to find one that works, for your site, on your server.
• Always give a brief explanation of scripts (lines) or groups of scripts you insert. Comment-out this explanation.
• Additional lines that may or not be needed can be commented-out.
• Always comment-out lines that need to be disabled - don't delete them.
• An htaccess file needs to be written so that commands are processed in a logical order. If you get the order wrong, there can be problems.
• You can have a very large htaccess file - but remember that the server must parse each and every line in the file, for every page request it gets - so this could add up to a lot of overhead on a shared server. Caching can help minimise this, if set up correctly. If your htaccess file is large, and you run a dynamic site like a CMS or ecommerce application, then it is up to you to arrange suitable caching within your website application.

An example htaccess file

Here is an example of a simple, basic htaccess file.

-------------------------------------------
RewriteEngine On

## uncomment the following line if necessary
# Options +FollowSymLinks

## uncomment the following line if necessary
# RewriteBase /

## force www version
RewriteCond %{HTTP_HOST} ^a3webtech.com [NC]
RewriteRule ^(.*)$ http://www.a3webtech.com/$1 [L,R=301]

-------------------------------------------


This is an example of the simplest htaccess file that is used. There are several points to note here:

1. The first line, RewriteEngine On, is always used whether or not it is required - it can't do any harm. It just tells the server to execute rewrites, in case that option is not switched on by default. If it's on anyway, it doesn't conflict.

2. Your own instructions receive a double comment, for clarity.

3. After the first command, the next two lines of script, or commands, are commented-out. These can be uncommented, to test them, if the htaccess file doesn't work at first.

4. The only command which is always used in every htaccess file is to force the www version of the domain (or occasionally the non-www version). Note carefully - as per usual - that this version of this particular command will only work on some servers and not others. A range of variations are needed, in order to find one that works on your server, for your application, on your host.

Now let's explain all that!

Optional lines in an htaccess file

All servers are different. One LAMP server is not the same as another; and different versions of an htaccess file must be used. The scripts need changing, and the optional lines are switched in or out. You can only find what works by experimenting, or by getting a list of working htaccess file examples for your server from your host. And if you ever find a host that provides you with such a list, I'd say you've struck gold.

If your htaccess file doesn't work, the first thing to do is to switch the optional lines in, by turn. If you get an Error 403 (Forbidden) or an Error 500 (Internal Server Error) when you then access the site, then the line you just changed in the file is wrong for your server. Also of course, if no positive change results, you'll need to experiment further. If there is an error, then comment-out the line you just enabled, and FTP up the file again, so that the new version overwrites the old.

Create a backup htaccess file

Never, ever, work on anything without a backup. Create sequential backups, so that you can go back to the last good, working version. If you don't do this, you will be lost when there is an error. Never overwrite any original file: copy it first and file it away, then load up your new file as the working copy - DO NOT work on the original. You can rename files and  create backup versions quite easily.

Here's how to do this. Firstly, let's look at how to create a backup file.

1. Copy the original file. You'll get a file called 'copy of htaccess.txt'.

2. Rename the original to 'htacess.txt.orig' - the icon will change to something different and your system won't know how to open it now, but don't worry. That renaming was done by simply placing '.orig' after the filename. Easy. Now you know which was the first, original file. Place it safely in another folder called 'original files'. To get it back, just delete the '.orig' off the filename.

3. Rename the copy as '1.htaccess.txt'. Place it in your working folder, and this is the one you will work with.

4. FTP to the server and rename the current htaccess file from .htaccess to .htaccess.bak - you now have a backup file on the server, and it is the original file. Just remove the .bak to return it tits original state.

5. FTP your new file (1.htaccess.txt or 1.htaccess either filename is good) up to the site and see if it works. You'll have to rename it on the server, to '.htaccess' - it will be the first file in the list and therefore very easy to spot. Just delete the '1' off the front to make it .htaccess , as per usual.

5. When it doesn't work (which is usually), then rename it on the server to '.htaccess.bak1'. This will:

• Negate it so the server can't see it
• Name it clearly as a backup file
• Name it as the next backup
• Start a sequential list of backup files: .htaccess.bak, .htaccess.bak1, .htaccess.bak2, etc.
  

You can create a backup file at any time, anywhere, by adding '.bak' on the end of a file. So, 'funny.jpg', a picture of your cat playing, can become 'funny.jpg.bak', which allows you to alter a copy in your image processing application without worrying if the original will be destroyed. And if you place an increment of 1, 2 etc at the end, you can see where you are in the series.

How to find an htaccess file in cPanel

Log in to cPanel, go to File Manager, go to the /public_html/ directory - if the File Manager does not open straight off in that directory. The first items will be folders (called directories when on a server), followed by the files. The .htaccess file is normally the first file listed.

How to find an htaccess file by FTP

Login to your site using your FTP client such as FileZilla. In the left pane you should have your local HTML folder, in the right pane is the website. It's best to have it arranged this way round, for logic purposes, if your language is LTR (written left-to-right) such as European-based languages. Arabic though is an RTL language, right-to-left.

In the right pane, then, you will see all the directories on the server (the folders) listed first, then the files, with the htaccess file first.

Cannot see htaccess

If you can't see the htaccess file, note that files with a name that starts with a full stop / period are designated as non-visible files, i.e. system files, on a server. Your FTP client may not show these, by default. You need to find the options menu item that says "Show hidden files" or similar, and check that item, in order to see files such as the .htaccess one. This option might be on a right-click menu and be named something obscure like Directory Commands >> List Mode >> Advanced, or similar.

htaccess on IIS

htaccess on a Windows server
An IIS server does not use an htaccess file. You cannot use an htaccess file on a Windows server because of this. What you need to do is ask your webhost to make the changes you need. Some htaccess functions will not be available, because this file is specifically for a normal webserver (a LAMP server). There is often an IIS equivalent - but of course if you are trying to get a PHP CMS or ecommerce application to work on a Windows server, you will be out of luck at some point. It may work, but it cannot function 100% since the htaccess functionality - which is often crucial to a PHP-based webapp - is not there.

If you have a dedicated Windows server then you can access the IIS Manager yourself and make the changes needed. This normally requires a knowledge of server support because running a server is not the same as running a website or using a PC. Probably the most important factor is security, and if you have no experience of webserver security then you definitely need expert advice.

htaccess for WordPress

For WP htaccess issues, see this page:
WordPress Guide

Odd htaccess facts

Note that an htaccess file cannot be read from the web, by a browser or by a searchbot - it is an instruction to the server that is read internally. Even though it is in the webroot, where all files are accessible from the web, the server will not (normally) serve it on a request (test yours by simply requesting it). However, it is possible to bypass the safety lock and view it by using a scripting attack; so we should use a specific command in the htaccess file that prevents this.

An htaccess file has to be uploaded as ASCII, not binary. This is normally the default, so nothing to worry about; but if your file crashes then check this.

Upper and lower case in htaccess

An htaccess file does recognise case, i.e. capital letters. This because the server does. In general it is always best to use lower case whenever possible for anything related to websites or web use. For example URLs should not use upper case letters since that will sometimes cause problems. In order to handle URLs and commands that may include upper case letters, the suffix [NC] is added to the end of a line of script, meaning 'no case' or ignore upper / lower case. It can also be written [nc], but is clearer in UC.

Common command suffixes

At the end of many lines you will see a suffix within square brackets. These instructions modify the main command of that line.

[301] = permanent redirect
[302] = the wrong command code for a temporary redirect
[NC] = no case (ignore upper / lower case)
[L] = last - if this direction is met, then quit

A redirect should always be a 301 (Permanent) and never a 302 (incorrectly used for a temporary redirect). I cannot think of any case in which the use of a 302 is valid. It should never be used for any purpose on a server, for anything. Even if you know that it will be changed tomorrow - don't use a 302. There are a bunch of search engine related issues here. Using a 302 is a bug in the Apache code: an Apache code team fault that has never been fixed.

Unfortunately, a server may default to issuing a 302 if you don't specify a 301 permanent redirect; therefore you should always specify a 301. A major problem here is that hosts in general (a) do not know that a server defaults to 302 if you don't specify otherwise; and (b) they wouldn't know in any case that this is absolutely verboten. Their actions in many cases get you an automatic search penalty.

These modifiers can be written in upper or lower case, it doesn't matter. You can use [NC] or [nc], it's the same thing. However, it may be clearer in upper case. [NC] means 'no case', or ignore the use of upper / lower case in this command line.

[L] - last - is used to terminate a sequence.

Useful blocking scripts

Here are some handy ways to block attackers. The first blocks a scripting attack to view your htaccess file:
<Files .htaccess>
order allow,deny
deny from all
</Files>

I like to test my htaccess scripts for validity and for lack of impact on correct server function. However, to test this defensive script you would need an attack script and we can't provide that.

We hope these basic htaccess FAQs have helped you to understand how to use the most important user-level file on a standard server.