Tutorial

How To Use the .htaccess File

Updated on July 11, 2022
How To Use the .htaccess File

Introduction

An .htaccess file is used for an Apache web server as a way to configure the details of your website without altering the server configuration files. This file begins with a period to signify that it’s hidden within the folder. An .htaccess file can be used to load customized error pages (such as 404 pages), create URL redirects, implement password-protected authentication for specific directories on your server, and more.

In this tutorial, you will learn how to enable, create, and use an .htaccess file, as well as some common uses and the impact on speed and security.

Prerequisites

If you want to practice using an .htaccess file by following the examples throughout this tutorial, you will need:

  • One Ubuntu 20.04 server set up with a non-root user with sudo privileges and firewall enabled. You can do this by following the Ubuntu 20.04 initial server setup guide.

  • The Apache web server installed on your Ubuntu server. Learn how to set it up with our tutorial on How To Install the Apache Web Server on Ubuntu 20.04. Be sure to complete Step 5 and have a virtual host file for your domain. This tutorial will refer to your_domain as an example throughout and use /etc/apache2/sites-available/your_domain.conf for the virtual host file.

  • If you would like to practice with a domain (optional), you can set one up by purchasing a domain name on Namecheap, get one free on Freenom, or use the domain registrar of your choice. You will also need both of the following DNS records set up for your server: two A records, one with your_domain and one with www.your_domain pointing to your server’s public IP address. Follow this introduction to DigitalOcean DNS for details on how to add them.

  • If you would also like to secure your virtual host, you can do so with a free trusted certificate, such as in our Let’s Encrypt guide for Apache. However, if you do not have a domain, you can use a self-signed certificate instead. This provides the same type of encryption, but without domain validation. Follow our self-signed SSL guide for Apache to set this up.

Once you’re done setting up, you can practice enabling and creating an .htaccess file in the next steps.

Enabling an .htaccess File

If you have access to the server settings you can edit the Apache configuration to allow the .htaccess file to override standard website configurations.

Begin by opening the apache2/sites-available/your_domain.conf virtual host file with your preferred text editor. Here, we’ll use nano:

  1. sudo nano /etc/apache2/sites-available/your_domain.conf

Assuming you followed Step 5 of the prerequisite Apache installation guide, this file will contain the following contents:

/etc/apache2/sites-available/your_domain.conf
    
<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    ServerName your_domain
    ServerAlias www.your_domain
    DocumentRoot /var/www/your_domain
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Add the following Directory content block within the VirtualHost block:

/etc/apache2/sites-available/your_domain.conf

<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    ServerName your_domain
    ServerAlias www.your_domain
    DocumentRoot /var/www/your_domain
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined


<Directory /var/www/your_domain>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride All
                Order allow,deny
                allow from all
</Directory> 
</VirtualHost>

The most important line of this Directory content block is the AllowOverride All, which enables the use of .htaccess files. After you’ve added this information, save and close the file. If you’re using nano you can do this by pressing CTRL + X then Y and ENTER.

Next, restart Apache:

  1. sudo service apache2 restart

Now that your configuration settings have been updated to allow for the use of .htaccess files, in the next step you will create one.

Creating the .htaccess File

To create an .htaccess file in your terminal, you need to navigate to your web root directory. Your web root directory is where to place the .htaccess file so that your configurations can be properly executed for your website. The .htaccess file’s proper placement is important since configurations in that file affect everything in its directory and the directories after it. This means that if you’re serving a couple of different websites on the same Apache server, your .htaccess file should be placed in the web root directory specific to that particular website.

If you followed the prerequisites, your web root directory will be in the following location: /var/www/your_domain/.htaccess.To create an .htaccess file for your website, run the following command:

  1. sudo nano /var/www/your_domain/.htaccess

Now that you’ve learned a couple of ways to create an .htaccess file, next we’ll review some common uses of an .htaccess page.

Common Uses for an .htaccess Page

There are five common uses for an .htaccess page on your site:

Mod_Rewrite

One of the most useful facets of the .htaccess file is mod_rewrite. You can use the .htaccess file to designate and alter how URLs and web pages on your sites are displayed to your users. Learn more about how you can do this with our tutorial on How To Set Up mod_rewrite.

Authentication

To set up security authentication with .htaccess, you can create a password file called .htpasswd to authenticate users. Making this change will create a password portal that prompts site visitors to enter a password if they want to access certain sections of the webpage. When creating this file, make sure to store it somewhere other than the web directory for security reasons.

To create the file, run the htpasswd command and include the -c option, and the username to create the specified htpasswd file. Once this happens, a prompt will ask you to provide a password. You can insert as many lines as needed into the htpasswd file, but be sure that every user gets their own respective line. The following example illustrates how to create a new entry in the file, in this case for the user sammy:

  1. sudo htpasswd -c /etc/apache2/.htpasswd sammy

You can check the contents of this file by running cat /etc/apache2/.htpasswd, and it will output the username and encrypted password for each record you added.

Once you’ve added your desired user(s), next open up the .htaccess file. If you followed the prerequisites guide, this will be located in the following location:

  1. sudo nano /var/www/your_domain/.htaccess

Keep in mind that in this example we’re restricting the entire document root based on /var/www/your_domain, but this can be placed in any directory to which you want to restrict access.

Once this file is open, add the following contents and save the changes to begin using the password function:

/var/www/your_domain/.htaccess
AuthType Basic
AuthName "Restricted Content"
AuthUserFile /etc/apache2/.htpasswd
Require valid-user

To learn more, read our tutorial on How To Set Up Password Authentication with Apache.

Custom Error Pages

An .htaccess file additionally allows you to create custom error pages for your site. Some of the most common errors are:

  • 400 Bad Request
  • 401 Authorization Required
  • 403 Forbidden Page
  • 404 File not Found
  • 500 Internal Error

To make a page user-friendly and provide more information to the site visitor than the default server error page offers, you can use the .htaccess file to create custom error pages. Read more in our tutorial on How to Configure Apache to Use Custom Error Pages.

MIME Types

In cases where your site features some application files that your server was not set up to deliver, you can add Multipurpose Internet Mail Extensions (MIME) types to your Apache server in the .htaccess file with the following code:

/var/www/your_domain/.htaccess
AddType audio/mp4a-latm .m4a

Be sure to replace the application and file extension with the MIME type that you want to support. For this example, we specified an audio file MIME type.

SSI

Server side includes (SSI) are a great time-saver on a website. One of the most common uses of SSI is to update a large number of pages with some specific data without having to update each page individually. For example, if you want to change a quotation at the bottom of a page.

To enable SSI, insert the following code into your .htaccess file:

/var/www/your_domain/.htaccess
AddType text/html .shtml
AddHandler server-parsed .shtml</pre>

These lines tell the .htaccess that .shtml files are valid, with the second line specifically making the server parse all files ending in .shtml for any SSI commands.

However, if you have many .html pages that you are not eager to rename with .shtml extensions, you can use another tactic to parse them for SSI commands, the XBitHack.

You can use this XBitHack tactic by adding the following line to the .htaccess file to make Apache check all the .html files with the appropriate permissions for SSI:

/var/www/your_domain/.htaccess
XBitHack on

To make a page eligible for the XBitHack, use the chmod command to change permissions:

  1. chmod +x pagename.html

Now that you have an understanding of a few common uses for an .htaccess page, next you will learn more about the impact an .htaccess file has on speed and security.

Speed and Security with .htaccess Files

Even though an .htaccess file can be used to improve a site, there are two things to be aware of that it can influence: speed and security.

Regarding speed, the .htaccess file may slow down your server, but for most servers, this will probably be an imperceptible change. This could be because of the location of the page since the .htaccess file affects the pages in its directory and all of the directories after it. This means that each time a page loads, the server scans its directory, and any directories preceding it until it reaches the highest directory or an .htaccess file. This process will occur as long as the AllowOverride directive allows the use of .htaccess files as was demonstrated in the enabling an .htaccess file step; whether or not the .htaccess files actually exist.

For security, the .htaccess file is much more accessible than standard Apache configuration and the changes are made live instantly (without the need to restart the server). This grants users permission to make alterations in the .htaccess file, giving them a lot of control over the server itself. Any directive placed in the .htaccess file, has the same effect as it would in the Apache configuration itself. It’s also important to note that Apache generally discourages the use of .htaccess if the user can access the Apache configuration files themselves.

Conclusion

The .htaccess file gives you a lot of flexibility to build up your site. To learn more about securing your site, read our tutorial on setting up password authentication with Apache. You can also read more in our tutorial about installing an Apache web server and specifically important Apache Files and Directories.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors

Default avatar

Technical Writer

Educator and writer committed to empowering our community by providing access to the knowledge and tools for making creative ideas into a reality


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
10 Comments


This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Thanks for this great tutorial. I encountered a few issues when trying to get this to work on Debian 8.2 and Apache 2.4.10: there was no default.conf and editing the 000-default.conf did not work.

I had to edit /etc/apache2/apache2.conf, and ensured the following part looked like this:

<Directory /var/www/> Options Indexes FollowSymLinks AllowOverride All Require all granted </Directory>

(AllowOverride All is the entry that made .htaccess work)

Kamal Nasser
DigitalOcean Employee
DigitalOcean Employee badge
September 15, 2013

@artisannm: Please pastebin apache’s config files (and .htaccess).

Try enabling the rewrite module: <pre>sudo a2enmod rewrite sudo service apache2 restart</pre>

If you can’t find it in /etc/apache2/sites-available/default it’s in /etc/apache2/apache2.conf

Change it to below:

<Directory /var/www/> Options Indexes FollowSymLinks AllowOverride All Require all granted </Directory>

Make sure to turn mod rewrite on: a2enmod rewrite and restart: service apache2 restart

If you also rewriting links: http://alexcican.com/post/how-to-remove-php-html-htm-extensions-with-htaccess/

Kamal Nasser
DigitalOcean Employee
DigitalOcean Employee badge
March 3, 2014

@team: Everything should be the same on CentOS except for the paths – you have to edit <code>/etc/httpd/conf/httpd.conf</code> instead.

I had the same problem. Thanks to post my admin I got it working. His comment should be included in the main article.

“1. Install Mod_rewite sudo a2enmod rewrite”

Hi everybody, I have same and fixed this problems.

  1. Install Mod_rewite sudo a2enmod rewrite
  2. Change AllowOverride from None to All sudo nano /etc/apache2/sites-available/default … <Directory /var/www/> Options Indexes FollowSymLinks MultiViews AllowOverride All Order allow,deny allow from all </Directory> …
  3. Restart apache sudo service apache2 restart
  4. Create .htaccess file by command sudo nano .htaccess pate your htaccess code -> Save and Exit My site working. I hope this is helpful :)
KFSys
Site Moderator
Site Moderator badge
June 17, 2024

As most have seen and commented, in order to make .htaccess file work, you’ll need to add the following to the apache2.conf:

<Directory /var/www/>
    Options Indexes FollowSymLinks MultiViews
    AllowOverride All
    Require all granted
</Directory>

Explanation of Each Directive

  1. <Directory /var/www/></Directory>:

    • This block specifies that the enclosed directives apply to the /var/www/ directory and all its subdirectories.
  2. Options Indexes FollowSymLinks MultiViews:

    • This directive controls which server features are available in the specified directory.

    • Indexes:

      • If a URL that maps to a directory does not have an index file (like index.html), Apache will generate and display a directory listing. This can be a security risk if not used carefully, as it exposes the directory contents to the web.
    • FollowSymLinks:

      • Allows the server to follow symbolic links in the directory. This means if there is a symlink within /var/www/ pointing to another file or directory, Apache will follow it.
    • MultiViews:

      • Enables content negotiation, allowing the server to provide different versions of a file based on the client’s capabilities or preferences. For example, it can serve a French version of a page if the user’s browser prefers French.
  3. AllowOverride All:

    • This directive controls which directives declared in .htaccess files (if present in the directory) can override server configuration.
    • All means that all types of directives are allowed to be overridden by .htaccess files. This can be useful for allowing directory-specific configurations but can also pose a security risk if not managed properly, as it allows users to modify server behavior within their directories.
  4. Require all granted:

    • This directive controls access to the directory.
    • Require all granted means that all requests are allowed access. This effectively means anyone can access the content served from /var/www/. This setting is essential for publicly accessible web content but should be used cautiously, especially for directories containing sensitive data.

Summary

By adding this block to your apache2.conf, you’re configuring Apache to:

  • Allow directory listings if no index file is found.
  • Follow symbolic links within /var/www/.
  • Use content negotiation to serve different versions of content.
  • Permit .htaccess files in /var/www/ to override server configurations.
  • Allow all users to access the content in /var/www/ without restrictions.

Under Apache 2.4 (which is installed by default under Debian 10 and probably other operating systems at this point), the advice above is not quite right.

My particular application was to add password control to some directories. I had to edit the config in /etc/apache2/apache2.conf to contain

 <Directory /var/www/>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride All
                Require all granted
 </Directory>

And then add .htaccess files to the necessary directories, each containing

AuthUserFile /etc/apache2/.htpasswd
AuthName "Please Enter Password"
AuthType Basic
Require valid-user

.htpasswd was created with htpasswd /etc/apache2/.htpasswd

and then of course reboot Apache with sudo service apache2 restart

Thanks for the helpful article but for my RHEL 7 + Apache 2.4, htaccesstools’ generator worked while the one linked in the article was broken and ended up in the server accepting all strings as valid.

As an added note when modifying the apache host configuration, AllowOverride All may have to be set in multiple config files. (e.g. 000-default.conf, default-ssl.conf, etc.)

The port may differ depending on if using SSL/TLS or not. (e.g. <VirtualHost _default_:443>, <VirtualHost *:80>, etc.)

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Become a contributor for community

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

DigitalOcean Documentation

Full documentation for every DigitalOcean product.

Resources for startups and SMBs

The Wave has everything you need to know about building a business, from raising funding to marketing your product.

Get our newsletter

Stay up to date by signing up for DigitalOcean’s Infrastructure as a Newsletter.

New accounts only. By submitting your email you agree to our Privacy Policy

The developer cloud

Scale up as you grow — whether you're running one virtual machine or ten thousand.

Get started for free

Sign up and get $200 in credit for your first 60 days with DigitalOcean.*

*This promotional offer applies to new accounts only.