keepcalculator

06 Numbers and Powers

Apache Virtual Hosts in Gentoo: Setup Guide

Card No. 06·68618 · Updated · Standard formula, shown below

Apache virtual hosts on Gentoo let you host multiple websites on one server, each with its own domain name, document root, and configuration. You set this up by creating per-site configuration files in /etc/apache2/vhosts.d/ and enabling the vhosts USE flag before emerging Apache. This guide walks through the exact steps, common pitfalls, and answers to frequent questions.

Background: Why Gentoo Handles vhosts Differently

Gentoo’s Apache package (www-servers/apache) is built with USE flags that control which modules and features are compiled in. The vhosts USE flag specifically enables the mod_vhost_alias module and, more importantly, sets up the configuration directory structure that Gentoo’s Apache init scripts expect. Without this flag, the /etc/apache2/vhosts.d/ directory won’t exist, and the main httpd.conf won’t include any per-vhost files.

Most other distributions ship Apache with a generic sites-available and sites-enabled layout. Gentoo uses a single vhosts.d directory where every .conf file is loaded alphabetically. There’s no separate enable/disable step; you simply add or remove files. This is simpler once you understand it, but it can surprise people coming from Debian or Ubuntu.

Step-by-Step: Creating a Virtual Host

Here’s the complete process from a fresh Apache install to a working second site. These steps assume you already have Apache emerged and running.

  1. Check the USE flag: Run emerge -pv apache and look for vhosts in the USE output. If it’s not there, add it to /etc/portage/package.use/apache as www-servers/apache vhosts, then run emerge -1 apache to rebuild.
  2. Create the directory structure: For each site, create a document root, e.g. mkdir -p /var/www/example.com/htdocs. The default Gentoo layout often uses /var/www/localhost/htdocs for the main site.
  3. Add a test file: Put an index.html in each new htdocs directory so you can verify the virtual host works.
  4. Create the vhost config: In /etc/apache2/vhosts.d/, create a file like example.conf. A minimal working config looks like this: 
    <VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/example.com/htdocs
    ErrorLog /var/log/apache2/example-error_log
    CustomLog /var/log/apache2/example-access_log common
</VirtualHost>
  5. Reload Apache: Run rc-service apache2 reload (or systemctl reload apache2 if you use OpenRC with systemd compatibility).
  6. Test: Visit http://example.com or use curl -H "Host: example.com" http://localhost to verify the correct content is served.

If you want a default site that catches any unmatched host, create a 00-default.conf file (the leading zero ensures it loads first). This is a common pattern to avoid the “first vhost becomes default” behavior.

How Name-Based vhosts Actually Work

Apache uses the Host header sent by the browser to decide which virtual host to serve. When a request arrives, Apache scans the loaded <VirtualHost> blocks in order and picks the first one whose ServerName or ServerAlias matches the requested hostname. If no match is found, it falls back to the first defined vhost (or the main server config if none exist).

This means the order of files in vhosts.d/ matters. If you have two vhosts for the same IP and port, the one loaded first (alphabetically) becomes the default for unmatched names. To make this explicit, many admins create a 00-default.conf that catches everything with ServerName _default_ or a wildcard ServerAlias *.

You can also use IP-based vhosts by specifying different IPs in the <VirtualHost 192.168.1.10:80> directive, but this requires multiple network interfaces or IP aliases and is rarely needed for typical web hosting.

Choosing Between mod_vhost_alias and Static Config

Gentoo’s vhosts USE flag enables mod_vhost_alias, which lets you use wildcards in the document root path. For example:

VirtualDocumentRoot /var/www/%0/htdocs

This automatically maps http://example.com to /var/www/example.com/htdocs without writing a separate <VirtualHost> block for each site. The %0 is replaced with the full hostname, %1 with the first part (e.g. www), and so on.

This is extremely convenient for shared hosting or when you have dozens of sites. However, it makes per-site logging and custom directives harder. You can still use <Directory> blocks with wildcards, but you lose the ability to set different ErrorLog paths per site without additional tricks.

For most users with a handful of sites, static <VirtualHost> blocks are clearer and easier to debug. Use mod_vhost_alias when you need to add new sites without touching the config at all.

Common Problems and Fixes

Here are the issues people hit most often when setting up vhosts on Gentoo:

  • vhosts.d directory missing: This means the vhosts USE flag wasn’t set when Apache was compiled. Rebuild with the flag as described above.
  • All sites show the same content: Check that each vhost has a unique ServerName and that the document root paths are correct. Also verify the order of files; the first loaded vhost becomes the catch-all.
  • Permission denied errors: The Apache user (apache by default) must have read and execute permissions on the document root and all parent directories. Run chown -R apache:apache /var/www/example.com or at least chmod o+x /var/www /var/www/example.com.
  • Syntax errors in config: Run apache2ctl -t to test the configuration before reloading. This catches typos and missing directives.
  • Port 80 already in use: Check if another service is bound to port 80 with ss -tulpn. If you have nginx or another web server, you’ll need to stop it or change ports.
  • SSL vhosts not working: For HTTPS, you need <VirtualHost *:443> blocks and the ssl USE flag enabled on Apache. Also ensure the SSL module is loaded in httpd.conf.

If a vhost still isn’t working, check the Apache error log at /var/log/apache2/error_log. It usually gives a precise reason.

SSL and Multiple Domains

Modern web hosting almost always requires HTTPS. For each domain, you need a separate <VirtualHost *:443> block with the SSL certificate paths. With Let’s Encrypt, you can use certbot --apache which automatically creates and manages these vhost entries, but it needs to be run after you’ve set up the HTTP vhost.

A common mistake is forgetting to enable the SSL module. In Gentoo, this is controlled by the ssl USE flag. After enabling it, you must rebuild Apache and then add LoadModule ssl_module modules/mod_ssl.so to httpd.conf (or uncomment it if it’s already there).

For multiple domains on one IP, name-based vhosts work fine with SSL as long as the client supports SNI (Server Name Indication), which all modern browsers do. You don’t need a separate IP per domain.

Alternatives and Comparisons

Gentoo’s approach isn’t the only way to manage vhosts. Here’s how it compares:

  • Debian/Ubuntu: Use sites-available and sites-enabled with a2ensite/a2dissite. Gentoo’s single directory is simpler but less flexible for toggling sites on and off.
  • Nginx: Uses server blocks in sites-available (on Debian) or directly in nginx.conf. Nginx’s event-driven model handles high concurrency better, but Apache’s .htaccess support is a major reason to stick with it.
  • Caddy: Automatically obtains SSL certificates and configures vhosts from simple directives. It’s much easier but less flexible for complex rewrites and authentication.

For a small server with a few sites, Gentoo’s method is perfectly adequate. For a large hosting environment, you might want to use a configuration management tool like Ansible or Puppet to generate the vhost files, regardless of the distribution.

Frequently Asked Questions

Why does my vhost show the default site instead of my content?

This usually happens when the ServerName in your vhost doesn’t match the hostname you’re using to access it. Apache falls back to the first vhost (or the main server) when no match is found. Check your ServerName and ServerAlias directives, and make sure the file loads before any conflicting vhost. Also verify that the document root path is correct and has the right permissions.

Do I need to restart Apache after changing a vhost file?

No, a reload is sufficient. Reloading re-reads the configuration files without dropping active connections. You only need a full restart if you change the compiled modules or the main httpd.conf in a way that requires reinitializing the server. Use rc-service apache2 reload or systemctl reload apache2.

How do I make one vhost the default for any unknown domain?

Create a vhost file that loads first alphabetically (e.g. 00-default.conf) with ServerName _default_ and a wildcard ServerAlias *. This catches all requests that don’t match any other vhost. You can then redirect them to your main site or show a custom error page.

Can I use the same document root for multiple vhosts?

Yes, you can point multiple <VirtualHost> blocks to the same DocumentRoot. This is common when you want different domains to serve the same content, such as example.com and www.example.com. Just make sure each vhost has its own ServerName and optionally separate log files.

What does the ‘vhosts’ USE flag actually do?

It enables the mod_vhost_alias module and creates the /etc/apache2/vhosts.d/ directory. More importantly, it tells the Apache ebuild to include the necessary Include directive in httpd.conf so that all .conf files in that directory are loaded. Without this flag, you can still manually add Include lines, but the directory won’t be set up for you.

How do I set up a vhost for a subdomain like blog.example.com?

Simply create a new vhost file with ServerName blog.example.com and its own DocumentRoot. You also need a DNS A record pointing blog.example.com to your server’s IP address. The process is identical to setting up a top-level domain; Apache doesn’t distinguish between subdomains and full domains.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →