Apache configuration files on Gentoo

Let's take a look at where apache's config files wind up when installed with the Gentoo 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 emerge, you will find the root of apache's config directory at:


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/.

If you take a look inside that directory:

ls /etc/apache2/

You should see something like this as the output:

custom  httpd.conf  magic  modules.d  vhosts.d

The Include directive

Before we dive into what each file in this directory is for let's talk about my favorite apache directive ever: Include.

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. 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? Well, for one thing, because we already used it once. And for another, the main apache config file has an Include by default to a directory that holds all the module config files. 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.



This is the first configuration file apache will read. It contains most of the settings for apache by default.

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.

When you look through httpd.conf note the Include directives you'll find (including, presumably, the one we added when we installed apache.



Despite its inviting name the "magic" file is a difficult one to read through. It's used by apache to determine the MIME types of files based on their headers.

MIME types are identifiers used by web servers and web clients to indicate that a file is of a particular type. For example, "application/pdf" is the MIME type for a PDF file.

If that doesn't make a lot of sense to you don't worry about it. Just know that this isn't a file you're likely to want to change unless you understand MIME types and the proper format of the entries in this file.

Your custom configs

Now we come back to that Include directive. If you didn't create a directory to hold your custom configs back when you set the ServerName, make the directory now:

sudo mkdir /etc/apache2/custom

And if you haven't already, add an Include directive toward the end of the httpd.conf file. Put it right before the "Supplemental configuration" section (the block that ends with "Include /etc/apache2/modules.d/*.conf"):

Include /etc/apache2/custom/*.conf

When adding a directive to apache that doesn't belong somewhere else, consider putting it in a file in "custom" instead of editing the main config file. Using your custom directory to hold changes 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.

Bear in mind that the way we set it up, the Include directive will only grab files from conf/custom that end in a ".conf" extension. That means you can change the name of a config file to disable it easily without deleting it entirely.



The modules.d directory contains a mix of module-specific config files and some more general configuration options.

Some of the files in this directory that control some general settings are:


The "00defaultsettings.conf" file contains some default settings for apache, like the connection Timeout or KeepAlive length. We'll look at that more closely when we examine apache configuration options.

The "00_mpm.conf" file contains settings for the MPMs apache uses. We'll talk about the MPM in a while too.

The other files in this directory are only loaded if an associated keyword is enabled in /etc/conf.d/apache2. We'll discuss how to do that in a moment, but for now take a look inside some of those files and note the "IfDefine" directive toward the top of each. The term after "IfDefine" is that module or config's keyword.

For example:

<IfDefine SSL>

Is at the head of the SSL config file, and shows its keyword to be "SSL". For the mod_LDAP config file, it looks like:

<IfDefine LDAP>

The "IfDefine" block ensures that apache will only load the configuration directives within if that keyword is enabled.



The vhosts.d directory is for virtual host definitions. That's another thing we'll go into in a later article, but the short version is that a virtual host is like a site definition. If you have multiple domains you can host them from the same instance of apache using virtual hosts.

Inside the vhosts.d directory you'll find these files:

00_default_ssl_vhost.conf  00_default_vhost.conf  default_vhost.include

The first two are default virtual hosts that handle SSL connections and non-SSL connections, respectively. Note that at the beginning of those files are more of those "IfDefine" directives, so you can control whether or not these default virtual hosts are used by enabling or disabling their associated keywords.

That last file, "default_vhost.include", is a template you can use to make your own virtual host. That file isn't included by the main apache config file (since it doesn't end in ".conf"), but it is explicitly included by the two default virtual host config files in the vhosts.d directory.

In /etc/conf.d

The /etc/conf.d directory is where Gentoo stores its own config files that pertain to certain software packages. The file we're interested in from this directory is:


The file is well-commented, so you can browse that file to look at some of the options that can be set to affect how apache is launched. Right now we're most interested in a particular line:


The "APACHE2_OPTS" value defines the options that will be passed to the apache process when it launches. The part you need to know about right now is that you can enable configuration keywords by putting them in this line with a "-D" in front of them (to "define" that keyword).

In the above example, the enabled keywords are "DEFAULTVHOST", "INFO", "SSL", "SSLDEFAULT_VHOST", "LANGUAGE", and "PHP5".

If you looked through the config files in modules.d and vhosts.d you'd find the IfDefine statements that check for those keywords. That would let you know that those keywords enable, in order, the default virtual host, modinfo, modssl, the default SSL virtual host, additional language support, and mod_php.

If you want to disable any keywords just remove them from the list. To enable other keywords, add them. For example, if you wanted to add a keyword to enable mod_userdir you would add the keyword "USERDIR" like so:



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
Want to comment?

(not made public)


(use plain text or Markdown syntax)