Htaccess

From DreamHost
Jump to: navigation, search

.htaccess is the name of the Apache file used for per-directory configuration.

Using .htaccess Files With Windows

If you are developing on a Windows machine and uploading to a Linux or UNIX server, you may have noticed that the filename .htaccess is not well supported in Windows, because to Windows it appears to be a blank name (an extension, but no name). It is analagous to a file called ".txt" or ".doc": valid and usable filenames in Windows, but ones that demonstrate the dubious meaning of the name.

Windows is rather reluctant to deal with names of this form as it contradicts Windows naming convention. However, in practice it is relatively easy. There are only two points to note.

Firstly, check how your text editor handles files with an extension that differs from the file type. For example, Notepad will append the extension ".txt" to any name that does not already possess it. Enclose the filename in quotation marks to request Notepad not alter the filename. This works for files with a different extension (e.g. "foo.c") and files with no extension (e.g. "hosts").

This is not a Windows limitation. For example, the JujuEdit lightweight text editor leaves the filename intact if it contains an alternative extension (e.g. ".c" or ".htaccess") but enclosing the name in quotes does not prevent an extension being added to a filename that doesn't take one, e.g. "hosts". Every editor is liable to behave differently and you will need to learn how to work with it.

Secondly, you cannot create such a file by File > New > Text Document, because Windows Explorer will not accept a bare extension as a filename. To create a file with no name in this manner, give it a dummy name such as "foo.htaccess" and then remove "foo" afterwards, leaving only ".htaccess". This is a Windows Explorer limitation that conflicts with UNIX naming convention.

Associating .htaccess files with an editor

With a few simple steps, you can make .htaccess files accessible as plain text files in your favorite editor so that you can double-click them in Explorer to edit them.

  1. Open the Folder Options control panel, or select Tools > Folder Options from an Explorer window.
  2. Switch to the File Types tab
  3. Click New to create a new file type
  4. Enter ".htaccess" as the file extension
  5. Click Advanced >> button to enable advanced mode
  6. Select Text Document from Associated File Type drop-down list. This important step links this new file type to the existing text file type on the system. All defined contextual actions will apply as with regular text files, and the icon and program association will be set for you.
  7. Click OK

You may now double-click .htaccess files to open them in your favorite editor (Notepad2, Dreamweaver, notepad++). You may need to log out and back in again, or restart Explorer, to have the file type gain its new icon; this is normal. Forcing an icon cache refresh (such as with Microsoft's TweakUI tool) will also work if you simply cannot bear to log out.

Follow the same steps for any other filename that Windows treats as an extension, e.g. ".htpasswd".

Using .htaccess Files With Mac OS X

Because Mac OS X is based on BSD UNIX, it follows UNIX convention of hiding all files whose names begin with '.' from view. While listing, creating and editing such files is possible from Terminal (e.g. ls -a) as you would expect, such files and folders don't usually show up in the Mac GUI, including the Finder and Open dialog boxes.

You can set the Finder to show invisible files in Terminal:

defaults write com.apple.Finder AppleShowAllFiles YES

Then restart the Finder, either by forcing a quit or just logging out and in again. This is easy to reverse, just change the argument from "YES" to "NO".

Alternatively, you could just use your FTP client (e.g. Transmit) as a Finder substitute for your coding work and set it to show the invisibles.

Finally, you can edit and upload .htaccess files via UNIX software in Terminal, or use a different name such as "htaccess", and rename the file to ".htaccess" after it has been uploaded to the site.

Finding .htaccess Files

Your FTP client may suddenly refuse to display the file once you renamed it to .htaccess. To see these files, you will have to use the list command with the -a option:

  • This can be done in CuteFTP with "server side filtering."
  • In WS_FTP, you can add the remote file mask -a in the Session Properties, or just type -a into the text box below the MKDIR button. This way all files are listed, even the ones starting with a period. You can enable server side filtering by right clicking on one of the file lists and choosing Filter.
  • When using RBrowser Lite on a Mac, go to Preferences and then select Show Hidden Files.
  • Dreamhost's WebFTP service cannot currently show hidden files, but their developers are hard at work on a solution.
  • Filezilla, a free FTP client, select from menu Server > Force showing hidden files.
  • Fetch states that it will display filenames beginning in a period unless this option is changed on the Miscellaneous in Preferences, but it appears to be mistaken. The Upload dialog includes a "show hidden files" option.
  • Dreamweaver 8 First Open up the website that you would like to see the hidden files for, and then connect to the remote server. Then click on "drop down menu" button in the top right of the Files sidebar. Then select View > Show Hidden Files.

The "WebFTP" utillity available in the DreamHost control panel does not support the display of hidden files, so cannot be used to locate them or work on them (referring to "Ajax Explorer", as of September, 2012).

There is more information on how to display these files in different FTP clients here.

Authentication examples

If you want to protect using Basic authentication, place a .htaccess file in the directory containing the protected file/s:

Protect Directory

AuthName "Dialog prompt"
AuthType Basic
AuthUserFile /home/username/.htpasswd
Require valid-user

Protect single file

<Files admin.php>
AuthName "Dialog prompt"
AuthType Basic
AuthUserFile /home/username/.htpasswd
Require valid-user
</Files>

Protect multiple files

<FilesMatch "^(admin|staff).php$">
AuthName "Dialog prompt"
AuthType Basic
AuthUserFile /home/username/.htpasswd
Require valid-user
</FilesMatch>

Give .htaccess and .htpasswd files permissions of 644.

You will then need to create the .htpasswd file mentioned in the .htaccess above. You can create this file using the htpasswd utility. For the first user, say user1, run it as follows:

htpasswd -c /home/username/.htpasswd user1

Enter the password for the user and then run it again, without the -c option, for however many users you want to allow access to your directory.

For additional information:


Add a content-type=UTF-8 header to your pages without using a meta tag

AddDefaultCharset UTF-8   
AddDefaultCharset ISO-8859-1


Add a language header to your pages without using a meta tag

DefaultLanguage en-us

Providing error pages

You can use .htaccess for creating and using your own and custom error pages. The most known error page is probably the 404 page (page not found). All you have to do is place a line with following syntax in your .htaccess:

ErrorDocument <error number> <path/to/file>

So for the 404 error you have to use this:

ErrorDocument 404 /404.php

You can also use folder specific error pages by placing a .htaccess in the folder you want and use

ErrorDocument 404 404.php

The link to the error page doesn't have to be on your site but can also be on another site

ErrorDocument 404 http://example.com/404.php

Instead of a link you can also give a message as errorpage by using

ErrorDocument 404 "This page was not found on this server"

Other error codes are:

  • 400: Bad request
  • 401: Authorization Required
  • 403: Forbidden
  • 404: Wrong page
  • 500: Internal Server Error


Deny access to "hidden" files

Filenames beginning with a dot, or dot-files are considered "hidden" by UNIX. Usually, you don't want to serve those to visitors to your website. Dreamhost already disallows retrieving '.htaccess' and '.htpassword', but you can recursively deny all access to all hidden files by placing into a top-level .htaccess:

RedirectMatch 403 /\..*$

This is useful when, e.g. your website is a Subversion "working copy." For more information see the Subversion#Automatic_Post-commit_Checkout.

PHP CGI Workarounds

PHP as a CGI may ignore php_flag and family commands in the htaccess file. If this is the case for your site, use PHP's ini_set() function within your PHP scripts. Note that ini_set() only allows you to change certain settings. For the list of settings that you can alter using this function, see: PHP config changeable settings.

See also

External Links