WWW FAQs: How do I make my site accept index.shtml or index.php as a folder home page?

2007-03-06: You have successfully configured your website to handle server side includes (.shtml or .shtm files), or perhaps PHP pages (.php files). But there's one little catch! When you try to make one of these files the home page of a website or a directory within the site, by naming it like this:


Your web server refuses to automatically use that file as an "index page" when you access the directory, with a URL like this one, for instance:


Ahrgh! Frustrating, isn't it. But don't worry, we can fix it!

The Fix For Apache

If you are using the Apache web server, it's easy to fix this problem. You can do it via your Apache server's httpd.conf file. Or, if you don't have access to that file, or you don't want this feature to work everywhere, you can solve it with a .htaccess file in the home directory of your website.

The key is to use Apache's DirectoryIndex option. This option decides what filenames are considered to be directory home pages. A reasonable choice for our purposes would look like this:

DirectoryIndex index.html index.htm index.php index.shtml index.shtm

In this case, the web server will recognize five different possible index file names.

Editing httpd.conf Directly

In most cases, your Apache configuration file (typically /etc/httpd/conf/httpd.conf on Red Hat Enterprise Linux, your server may vary) will already have one or more DirectoryIndex commands - one for the general case, and perhaps others for individual directories or virtual domains. If it ain't broke, don't fix it- don't just replace these settings with my example! Instead, add any missing filenames such as index.php or index.shtml to the end of each space-separated list.

Restarting Apache On Linux/Unix Systems

We could signal Apache to reload its configuration files right away... but if we've made a mistake, the web server won't restart. Ouch! Is there a way to make sure our settings are good before we reload them?

Yes! We can use Apache's -t option to test the configuration file:

/usr/sbin/httpd -t

If you don't see the message Syntax OK, pay attention to the message you did receive and fix any errors. When you no longer have any trouble with the -t option, you're ready to restart the web server:

/usr/sbin/httpd -k restart

The Apache commands I show here are correct for the standard Apache configuration on Red Hat Enterprise Linux. If you have your configuration files in a nonstandard place, you might need to specify -d directoryname to point to that directory. If you have the Apache binary in a nonstandard place, you might need to specify a different path or filename for it.

Restarting Apache On Windows Systems

Apache for Windows users can restart the Apache service from the Services control panel:

Start Menu -> Settings -> Control Panel -> Administrative Tools -> Services

These steps are correct for the Windows XP "Classic View." If you are using the standard view, the steps are slightly different:

Start -> Control Panel -> Performance and Maintenance -> Administrative Tools -> Services

We recommend the "Classic View" for those who are running websites on their PCs.

You can also test your configuration file first with Apache's -t option:

apache -t

This gives you a chance to correct errors before restarting your web server and discovering that the new configuration file is invalid.

Configuring Apache Via .htaccess Files

You can also configure Apache via a .htaccess file, either in your website's document root (where your home page lives) or in a subfolder (if you only want the changes to apply to that folder). This works on both Linux/Unix and Windows systems.

It's simple! Just create a text file called .htaccess containing this line:

DirectoryIndex index.html index.htm index.php index.shtml index.shtm

Just drop that file into your website's home directory ("document root").

You might already have a .htaccess file! If you do, be sure to add this command to the end of the file. Please don't crush your existing work.

Note that the filename must be .htaccess and not htaccess.txt or htaccess (without the dot).

Not every Apache server is configured to allow .htaccess files. If yours seems to ignore them, contact your administrator for help. If they won't let you use .htaccess or edit your httpd.conf file, they should make this change for you. If not - find a better web host! It's your money.

.htaccess files are a great solution for the webmaster who doesn't have write access to his Apache configuration files. However, those who do have write access to httpd.conf should always make configuration changes there, rather than in .htaccess. That's because the web server has to read the .htaccess file every single time a file on the website is accessed. That makes the web server work harder and potentially slows things down.

The Fix For Microsoft Internet Information Server

You can also fix this problem on Microsoft Internet Information Server (IIS). But you do need administrative control of the web server. That's because IIS has no equivalent to Apache's .htaccess files. So "ordinary users" usually can't make configuration changes. But don't be shy about showing this page to your administrator— it's entirely possible they just don't know how to help you.

Here's how to configure IIS to accept index.php, index.shtml and index.shtm as valid names for the "default document" of a folder:

1. Start Menu -> Settings -> Control Panel -> Administrative Tools

These steps are correct for the Windows XP "Classic View." If you are using the standard view, the steps are slightly different:

Start -> Control Panel -> Performance and Maintenance -> Administrative Tools

We recommend the "Classic View" for those who are running websites on their PCs.

2. Double-click "Internet Information Services"

3. In the "tree" at left, open up the folder for the web server computer, then locate the entry for the website you want to configure

4. Right-click that website and select "Properties"

5. Click the "Documents" tab

6. Make sure "Enable Default Document" is checked

7. Click "Add"

8. Enter index.php and click "OK"

9. Repeat the process for index.shtml, index.shtm and any other desired default document names.

10. Click "OK"

11. You may see an "Inheritance Overrides" dialog box. This lists specialized parts of your website that could be affected by your changes. In most cases you will not want to change the behavior of these parts of the site. So just leave any items in the list unselected and click "OK."

Testing Your New Directory Home Page

You've configured your Apache or IIS web server to recognize a new filename as the directory home page, or "default document," as Microsoft likes to call it. But how do you test it?

That's easy! Just create a new folder on your website, containing a index.php file (assuming index.php is one of the filenames you just set up, of course). Call the folder mytestfolder. Then access the folder on your website:


If you configured your web server correctly, you should see the contents of index.php, even though you didn't add index.php to the URL. Mission accomplished!

If It Doesn't Work

If you received an error message from Apache, check the error_log file of your web server. On Red Hat Enterprise Linux, you can do that with this command:

tail /var/log/httpd/error_log

Messages in that file should tell you exactly what went wrong.

If you received an error message from IIS, pay attention to the details of the message and make sure you correctly added the new default document filename according to the steps above.

If you see the "raw" PHP source code of index.php, you probably don't have PHP enabled on your web server in the first place! Take a big step back and install PHP first.

If you see a different home page, you probably have an index.html, default.htm or other default document in the same folder. Rename or delete that file.

If you see a directory listing, you probably didn't make the Apache configuration file or IIS settings change. If you are using Apache and .htaccess files, it's possible that your web server is not configured to allow them, in which case you'll need to ask your administrator to add the commmands to httpd.conf for you instead.

Legal Note: yes, you may use sample HTML, Javascript, PHP and other code presented above in your own projects. You may not reproduce large portions of the text of the article without our express permission.

Got a LiveJournal account? Keep up with the latest articles in this FAQ by adding our syndicated feed to your friends list!