Apache Virtual Host Containers in Separate Files

1. Introduction

With the size of the Apache configuration file what it is, it can be easier to find and change a virtual host container (configurations) if the settings are in separate files.

<!> This isn't strictly recommended by the upstream documentation, but is a common manual extension to make the system more manageable.

<!> All manual extensions to your system should be documented for future reference.

<!> There are several places that virtual host source files can be put. This is a complex topic with several major points of view and is not fully addressed in this document.

2. Usual Practice: conf.d/

The most common location for discrete virtual host configuration files is /etc/httpd/conf.d/. The config files can be named to reflect the website(s) to which they refer, provided they don't conflict with configuration files of existing or future modules. The matching content can be placed under /var/www/ or /var/www/html/ in sub-directories, such as /var/www/example.com/ or /var/www/html/example.com/.

This has the advantage that the parent directories are already created and SELinux is familiar through rule inheritance, as to how to handle access rights. The packaging system leverages this, of course, by dropping the php.conf file into that configurartion directory such that after a package based install of php, and a restart of the webserver, PHP parsed pages 'just work'

Though placing a vhost configuration file in a directory full of non-vhost related matter, such as: php.conf and mailman.conf, initially appears an out of order jumble, upon closer reading of the documentation, from Apache HTTP Server Version 2.2 - Configuration Sections, we see that: "Most containers are evaluated for each request."

So, Apache applies the virtual host directives after all non-vhost related stanzas, regardless of the seeming alphabetical sort order position in the configuration file, or in a merged directory full of such config files, in the matter processed.

This is largely a settled area of Systems Administration, such that the most recent documentation from upstream does not appear to include a 'System Administration Guide' in the CentOS 5 series. The System Administration Guide from CentOS 4, Chapter 24. Apache HTTP Server Configuration covers the matter in greater depth.

3. Virtual Host Files

Virtual Host container files can be placed in the configuration directory directly or by link. The name must end with .conf to be included. If using links, make sure to update the SELinux properties of the actual file.

3.1. Example

The file should contain the configuration items specific to this host. An example.conf could be...

# file: /etc/http/conf.d/example.conf
# vhost: example.org *.example.org
<VirtualHost *:80>
  ServerName example.org
  ServerAlias *.example.org
  ServerAdmin webmaster@example.org
  ErrorLog /var/log/httpd/example.err
  CustomLog /var/log/httpd/example.log combined
  DocumentRoot /var/www/example.org
  <Directory "/var/www/example.org">
    Order allow,deny
    Allow from all
  </Directory>
</VirtualHost>

Of course, a virtual host configuration file may refer to more than one URL or DNS result as a single file tree.

[userid@webhost conf.d]$ cat example.conf 
### two domain vhost sites handled here:  
###       example.com and example.org
###
### the .COM
<VirtualHost x.x.x.x >
        ServerAdmin     webmaster@example.com
        DocumentRoot    /var/www/html/example.com/public_html/
        ServerName      example.com
        ServerAlias     www.example.com
        ErrorLog        logs/example.com-error_log
        TransferLog     logs/example.com-access_log
        AccessFileName .htaccess
</VirtualHost>

### the .ORG
<VirtualHost x.x.x.x >
        ServerAdmin     webmaster@example.org
        DocumentRoot    /var/www/html/example.org/public_html/
        ServerName      example.org
        ServerAlias     www.example.org
        ErrorLog        logs/example.org-error_log
        TransferLog     logs/example.org-access_log
        AccessFileName .htaccess
</VirtualHost>

This file sets up the two domains, one the .com and the other the .org. As to each, it would provide the same content at the bare domain name, and also at the www when used either way in a URL for a web browser, which is usually the desired result, but of course possibly differing content between the two TLD variations as the content down the file tree specified.

4. Virtual Host Inclusion

There might be times when it is desirable to disable a virtual host. Since the include in /etc/httpd/conf/httpd.conf specifies *.conf, it is possible to hide a virtual host by changing the configuration file name.

4.1. Disable Virtual Host

Virtual hosts can be disabled by renaming the file so it doesn't match the *.conf file specification. Adding a disabled extension is one way.

mv --verbose /etc/httpd/conf.d/example.conf /etc/httpd/conf.d/example.conf.disabled

If less typing is desired, it can be shortened:

mv -v /etc/httpd/conf.d/example.conf{,_}

4.2. Enable Virtual Host

Virtual hosts can be re-enabled by removing the extra.

To remove the disabled flag:

mv --verbose /etc/httpd/conf.d/example.conf.disabled /etc/httpd/conf.d/example.conf

For the shorter version:

mv -v /etc/httpd/conf.d/example.conf{_,}

<!> Enabling or disabling a virtual host using this method will not take effect until the web server is restarted.

5. Restart Apache

To make your changes take effect, restart Apache. Using the graceful option ensures that existing processes are allowed to finish serving the current page, reducing the chance of disrupting a user's browsing experience.

service httpd graceful


{i} Thanks for the graceful suggestion, Filipe. And the pointer to Apache section interpretation.

6. Optional: vhost.d/ method

6.1. Disclaimer

<!> This section advocates an alternate approach that is outside of the strict, minimalist configuration used by many CentOS system administrators. Like any manual extension of your CentOS system, an update of the distribution could render your system broken.

Another location for virtual host container files is a new directory, /etc/httpd/vhost.d/ for example, and adding a vhost.conf file in conf.d/ to tell apache where they are. This segregates the virtual host container files from the module configuration files. This approach allows for easier backups of virtual host configuration changes and removes the possible chance of the different types of files having conflicting names.

6.2. Create Directory

Creating the directory with the same SELinux attributes as /etc/httpd/conf.d/...

mkdir --context=system_u:object_r:httpd_config_t /etc/httpd/vhost.d

6.3. Update SELinux Properties

Verifying the SELinux properties is as simple as...

ls -lZ /etc/httpd

and should return something similar to...

drwxr-xr-x  root root system_u:object_r:httpd_config_t conf
drwxr-xr-x  root root system_u:object_r:httpd_config_t conf.d
lrwxrwxrwx  root root system_u:object_r:httpd_log_t    logs -> ../../var/log/httpd
lrwxrwxrwx  root root system_u:object_r:httpd_modules_t modules -> ../../usr/lib/httpd/modules
lrwxrwxrwx  root root system_u:object_r:httpd_config_t run -> ../../var/run
drwxr-xr-x  root root system_u:object_r:httpd_config_t vhost.d

Since /etc/httpd/vhost.d/ is under /etc/httpd/, it should inherit any policy changes made to /etc/httpd/ and should survive a file system relabel.

6.4. Create New Virtual Host Configuration File

Let Apache know about the virtual host configurations location by creating a new configuration file in conf.d/.

echo "Include vhost.d/*.conf" >>/etc/httpd/conf.d/vhost.conf

Change the context to make sure Apache is allowed to read it

chcon --reference /etc/httpd/conf.d/README /etc/httpd/conf.d/vhost.conf


{i} Thanks, BrianMathis, for the conf.d/vhost.conf suggestion.

7. Optional: Configuration File Prefix

Naming the files with a prefix, like vhost-, might be more intuitive for others, might make the TLD more visible and would group the active and non-active virtual hosts.

<!> This method only works with an additional include directive in /etc/httpd/conf/httpd.conf.

<!> This can be combined with creating a new configuration file in conf.d/ to avoid modifying the distributed httpd.conf.

7.1. Include Directive

Instead of including files that end in .conf, include files that start with vhost-:

echo "Include conf.d/vhost-*" >>/etc/httpd/conf/httpd.conf

or, if using vhost.d/ method:

echo "Include vhost.d/vhost-*" >>/etc/httpd/conf/httpd.conf

7.2. Disable Virtual Host

Add _ to the beginning of a virtual host file name to prevent its inclusion:

mv -v /etc/httpd/conf.d/{,_}vhost-example.org

or, if using vhost.d/ method:

mv -v /etc/httpd/vhost.d/{,_}vhost-example.org

7.3. Enable Virtual Host

Remove the _ from the beginning of a virtual host file name to allow its inclusion:

mv -v /etc/httpd/conf.d/{_,}vhost-example.org

or, if using vhost.d/ method:

mv -v /etc/httpd/vhost.d/{_,}vhost-example.org

<!> Enabling or disabling a virtual host using this method will not take effect until the web server is restarted.


This page created by Ed Heron.

TipsAndTricks/ApacheVhostDir (last edited 2012-07-12 19:06:36 by EdHeron)