Apache Virtual Host Containers in Separate Files
Contents
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
<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 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
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
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.orgor, 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.orgor, 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.