Freedom, Community & Sustainability

Apache configuration made simple - Survival kit

November 3, 2014 -- William
Last modified on August 2016
Duration: +- 15 minutes

Let's be frank, Apache configuration is a pain in the neck. It takes usually much more time than we would like to and often we miss something and it gets weird. Don't worry, this tutorial will make things much easier for you! If you need help troubleshooting, move on to the end of the tutorial.

General concepts

Apache configuration consists of fiddling with:

  • apache.conf / httpd.conf general configuration file
  • configuring your sites in /etc/apache2/sites-available
  • enabling these sites with the command a2ensite nameofsite
  • setting up hosts (site names) in the file /etc/hosts
  • restarting apache (every time you do something!)

We will go through the configuration of each of these files and also some troubleshooting. If you are dealing with PHP and MySQL you might also want to tweak the files php.ini and my.cnf. Technically they are not Apache so I'll leave the configuration of these services for another tutorial.

Apache.conf vs httpd.conf vs vhosts.conf?

Apache.conf and httpd.conf can be used almost interchangeably since both are valid configuration files applicable to the entire server. The file httpd.conf is there just to separate the "main" configuration file from "user" configurations. The only difference is that httpd.conf overrides apache.conf. For this reason apache.conf should be the main configuration file, httpd.conf (if needed) will override it and the virtual hosts (located at /etc/apache2/sites-available) override both of them. In this hierarchy the most general configurations get overridden by more specific configurations. To summarize, the hierarchy follows this order:

apache.conf > httpd.conf > [vhosts].conf (virtual hosts are created by users so the name of the file could be different, like mysite.conf...)

What is a virtualhost?

If you only have one site on your server you don't need virtual hosts. The default configuration of Apache will send all traffic to the only site you have. If on the other hand you have more than one site on your server you need to tell Apache about each of these sites (their domain, the folder where it is located, alternative log location...). Once this is done Apache will read the URL that the user typed and point her/him to the appropriate site.

Apache configuration of virtualhosts - checklist:

  1. Add website configurations to the folder /etc/apache2/sites-available. Just copy the default configuration file and make your changes to it.
  2. Add your website to the /etc/hosts file (again, just copy a default line and make your changes from there)
  3. Enable your website with the command a2ensite mysite (the name of the configuration file must match the name and should be located at /etc/apache2/sites-available/mysite.conf). To disable sites, use the command a2dissite myothersite.

Permissions and the Apache user: www-data

Apache user is often called www-data and all files that Apache needs to work with need to be accessible by www-data and have the appropriate permissions. There's one caveat though, you don't want to give too much permission on these files because they are on Internet! (as a rule of thumb, chmod 777 is always a bad idea). You can check the name of your Apache user with this command:

ps aux | grep apache

The permission for each folder on your site will certainly vary. Most of the folders will have a permission that allows Apache to read but not write. Some folders where users can upload files will need to have write permission as well. This is an example of permissions and ownership for these two kinds of folders, adapt it to your needs!

drwxrwx---  3 www-data www-data 4096 2014-10-18 08:34 writable/
drwxr-x--- 19 www-data www-data 4096 2014-10-18 09:52 readable/

Apache modules

Apache comes with many modules that can be enabled/disabled with the commands a2enmod [module_name] / a2dismod [module_name]. Sometimes things will not work because a particular module is disabled. To check which modules you have enabled, run the following command:

apache2ctl -M

These are some of the common modules not included by default that you might want to check (note that the name of the module might be slightly different, on the list you might see rewrite_module but it's name is actually mod_rewrite):

  • mod_php: allows the use of PHP language within Apache
  • mod_rewrite: allows URLs to be rewritten on the fly
  • mod_ssl: enables secure connections

See a complete list of modules on the official Apache site.

Set up alternative ports

It's rare to have to change ports because they are standardised. Http is by default on port 80 and https on port 443. If however you need to change these ports globally you can do so modifying the file /etc/apache2/ports.conf. This is the general configuration file and you should also check the configuration of your virtual-hosts at /etc/apache2/sites-available. Changing ports is useful  when you are setting up Apache on a network that blocks the standard ports or when setting up a reverse cache like Varnish.

On /etc/apache2/ports.conf you should see something like:

Listen: 80
<ifModule ssl_module>
    Listen: 443

On /etc/apache2/sites-available/[vhost.conf] you will notice this line:

<VirtualHost *:80>

Localhost development environment

On a development environment you can easily skip the configuration of virtual-hosts by using the "one size fits all" localhost. The localhost points to the web root folder where you will see all the folders of your sites. You can then navigate to all sites without having to set up virtual-hosts (although it's better to configure them). This is only possible because you know what you are doing and you won't be scared to see complicated URLs.

For the permissions on a development environment you can give ownership to your user and assign the group to www-data. In this way you AND Apache will be able to work with the files without problems. The command is (replace what's between [] with your data):

sudo chown -R [myname]:www-data /var/www/[html]

Troubleshooting common problems

Before starting this "problems and solutions" section let's just make sure that Apache is fresh and running, that it's syntax is correct and that the virtual hosts are configured correctly. The commands to do that are, respectively:

service apache2 restart
apache2ctl -t
apache2ctl -S

Problem: [warn] NameVirtualHost *:80 has no VirtualHosts


  • Check on /etc/apache2/sites-available/[vhost.conf] that you have defined the port for the virtualhost <VirtualHost *:80>
  • Check that this configuration is not duplicated in other configuration files (only one config file should be defining NameVirtualHost) : apache2.conf, httpd.conf, ports.conf.
  • Check that your NameVirtualHost has a corresponding VirtualHost

Problem: apache2: Could not reliably determine the server's fully qualified domain name, using for ServerName

Solution: Define your ServerName in /etc/apache2/apache2.conf (put it under "General configuration"). You should also add the ServerName for each of your virtualhosts. Here are two examples, the first line can be in apache2.conf to remove the error but you should also set each domain on your virtual hosts like on the second line below:

ServerName localhost
ServerName example.com

Read also:
Common Apache misconfigurations

Add new comment