Apache configuration files on Ubuntu

Let's take a look at where apache's config files wind up when installed with the Ubuntu package manager.

---

The apache config directory

Let's take a look at where apache gets its settings from. Note that when we talk about a "config" we mean "configuration" or "configuration setting", depending on the context. Think of the shorthand version as hip hacker slang.

If you went through the first article in this series to install apache via aptitude, you will find the root of apache's config directory at:

/etc/apache2/

If you compiled apache from source, you probably won't see it there, you rebel you. The configuration directory will be wherever you told it to be during your install. Maybe poke around in /usr/local/.

The configuration directory structure for apache when it's installed via aptitude is different from what you would see when apache is installed from source. It's important to keep that in mind when looking at apache documentation on the web, which will usually reference the default config layout. This article will discuss the structure aptitude puts in place.

So, if you take a look inside that directory:

ls /etc/apache2

You should see something like this:

We'll start our overview with the core configuration file, apache2.conf.

Main config file

The first configuration file apache will read when it starts is:

/etc/apache2/apache2.conf

The file is pretty well commented, so you can look through the file contents (with "cat" or "more" or "less", your preference) and get some idea of what the default settings look like and how you can change them. We'll go into the most important ones in a later article, so for now it's okay to just skim.

There is one important directive that's used in that file that you might keep an eye out for as you read. That's the "Include" directive.

The Include directive

While it's possible to cram every apache setting into the main config file, it can be a bit awkward having to open one huge file and navigate through it every time you want to make a change. That's why the apache team thoughtfully provided a way to add more config files to your installation.

The "Include" directive tells apache to read another file and parse it for configuration options. Well, more than that, it can also point to a directory and tell apache to read all or some of the files in that directory. In short, it's pretty darned nifty if you're trying to reduce the headaches that come with editing one gargantuan config file every time you need to add a site.

Why am I telling you about this directive now, instead of waiting for the more detailed configuration articles? I'll be pointing out the Include directives from the main config file for each file and directory apache might read. That should give you an idea of how the additional config files are used, and how you can set up your own includes down the line.

With the stage set, let's look at the other things you'll find in the apache config directory.

conf.d

Include /etc/apache2/conf.d/

The conf.d directory is meant to hold "generic snippets of statements", according to the apache folks. You got a look at it when we were installing apache and wanted to set the ServerName directive. Rather than edit the main config file, we created a new file in conf.d to hold the ServerName directive.

When adding a directive to apache that doesn't belong somewhere else, consider putting it in a file in conf.d instead of editing the main config file. Using conf.d makes it easier to isolate a recent configuration change (by checking modification dates), lets you find directives you've added quicker, and reduces the risk that you could make a bad edit in the main config file.

ports.conf

Include /etc/apache2/ports.conf

The ports.conf file contains the instructions to apache to listen to port 80 (the default port for HTTP traffic), as well as port 443 if SSL support is installed.

If you want apache to listen to additional ports, just add more "Listen" directives. If you want to fix it so apache is listening to a port other than port 80, just change that entry in ports.conf.

sites-available

The sites-available directory contains just one file, "default", by, er, default. That file contains the directives that set up a basic default site, with a document root (appropriately found in the DocumentRoot entry) and some permissions for that directory.

We'll discuss adding virtual domains in a later article, but it's worth noting that the "default" file makes a good template for adding sites to your web server instance later.

You might have noticed that I didn't list an Include directive pointing to sites-available. That's because there isn't one — apache doesn't look inside this directory. But there is another directory with a similar name...

sites-enabled

Include /etc/apache2/sites-enabled/

The sites-enabled directory is included in the apache config, while sites-available isn't. The names of the directories should help illustrate the reason for this: A site isn't enabled (available to web browsers) unless there's a link from the site config file in sites-available to sites-enabled.

By default you should find a symlink (shortcut) in sites-enabled that points back to the "default" configuration file in sites-available. The "000" is stuck in front of "default" in order to make sure it actually is the default site config when it's present in sites-enabled. Apache reads config files in the order in which they'd show up in a basic directory listing (alphabetical order), and tacking 000 on there ensures that one gets read first (and is therefore treated as the default config).

Why a default site? Because, as you'll see when we talk about virtual hosts, sometimes you have a site all planned out for a domain, and sometimes you don't. If someone visits your web server by plugging "www.example.com" into their browser, and you have a site config file specifically for www.example.com, apache will use that config. If it can't find a config file that matches the domain name the web browser was looking for (because it doesn't exist, or because it's not enabled), it serves up the default site instead.

Enabling and disabling site configs is most easily handled by using some commands specially installed to accommodate this configuration setup.

The a2ensite and a2dissite commands

Two commands, a2ensite and a2dissite, are installed with apache to handle switching sites from disabled to enabled and back again. You can use them now to see how this business with sites-enabled works.

First, point your browser to your slice again so you can see the default "It works!" page for the server.

Now go ahead and run the command to disable the "default" site:

sudo /usr/sbin/a2dissite default

Then restart apache so it will reread its configuration.

sudo /usr/sbin/apache2ctl graceful

Try visiting your slice in the web browser again. You'll get a response from apache, but this time it will be a "Not found" error. This is because you've disabled the default site config, so apache has no idea where to look for any files to serve to visitors. If you check the sites-enabled directory you'll notice the symlink to the "default" config file is gone.

To turn the default site back on, run a2ensite and reload apache again:

sudo /usr/sbin/a2ensite defaultsudo /usr/sbin/apache2ctl graceful

Now going to the slice in a browser should get you the "It works!" page again. And the symlink will be back in sites-enabled.

The a2ensite and a2dissite commands can be useful for managing sites you add to your server, but also for handling special situations like site maintenance. You could, for example, define a site config that would direct all traffic to a "This site is down for maintenance" page. Then when you want visitors to see that instead of your main site, just disable your site config and enable the maintenance site config, then reload apache. When you're done working on the site, re-enable the site config, disable the maintenance config, and reload apache again.

mods-available

Just as we have a sites-available directory to hold site configs, there's a mods-available directory for storing module configs. These look a bit different, since a module has to be loaded by apache before it can be configured. You probably won't need to create these config files yourself, so it should suffice to know that a file named after a module with ".load" at the end contains the directive needed for apache to load the module, and then the file ending in ".conf" contains any additional configuration needed for that module.

mods-enabled

Include /etc/apache2/mods-enabled/*.loadInclude /etc/apache2/mods-enabled/*.conf

Similar in function to the sites-enabled directory, the mods-enabled directory contains symlinks to the config files for any modules that you want apache to load when it starts up. The order of those Include directives up there is important: First the ".load" files for enabled modules are read (which loads the modules), and then the ".conf" files for those modules are read (which configures those modules).

The a2enmod and a2dismod commands

The a2enmod and a2dismod commands work like a2ensite and a2dissite. They just manipulate module config files instead of site config files.

This would be a good time to look over the modules that are enabled and prune any you know you won't need, and enable any you know you will need. For example, if you wanted to enable the "userdir" mod (which allows apache to automatically serve pages from the home directories of users on your slice), you would run:

sudo /usr/sbin/a2enmod userdir

Likewise, if you knew that you wouldn't be using the "status" module (which can be used to serve a page showing the current status of the apache server), you could disable it like so:

sudo /usr/sbin/a2dismod status

If you make any changes to which modules should load, remember to reload or restart apache to make the changes take effect. Don't worry too much about getting the modules right just yet, you can always come back here and poke around when you're done with this tutorial.

envvars

The "envvars" file contains some environment variables that are used by some apache-related scripts, like apache2ctl. You should only need to modify this file if you change the user and group apache runs under.

httpd.conf

Include /etc/apache2/httpd.conf

When apache is compiled from source, its main config file is named "httpd.conf" if you don't customize it. As it happens, using the apache2.conf file for the main config is a custom change by the package maintainers to make it a bit more user-friendly. The httpd.conf file is in the config directory just in case an application tries to write a config change to the default apache config file.

The httpd.conf file is empty by default.

Summary

That should cover the files that can be found in apache's configuration directory after a package install, and what settings you can generally expect to find where. Remember that when you alter apache's configuration you'll need to reload or restart the web server before the change will take effect.

In the next article we'll look at apache's MPM options and how you may want to change them to account for your server's available memory.

• -- Jered