Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 30 ยท Apache Configuration

Apache Virtual Hosts

Host many sites on one Apache server: name-based and IP-based virtual hosts, ServerName and ServerAlias, the first-vhost default, per-site logs and Listen.

One Apache server rarely serves one website. A single machine usually hosts a company site, a blog, an admin tool and a staging copy, all answering on the same IP address and port 443. The browser tells the server which one it wants by sending a Host header (Host: blog.example.com), and Apache uses virtual hosts to pick the right configuration for it.

In this lesson you will write name-based virtual hosts, learn what ServerName and ServerAlias really do, understand the rule that makes the first vhost the default, give each site its own logs, and compare Apache's selection rule with the one nginx uses. The nginx half of the story is in Server Blocks and Choosing a Server; read both and you will understand how every request finds its site.

Listen and VirtualHost are different jobs

Two directives are easy to confuse:

  • Listen tells Apache which addresses and ports to open sockets on. Without a Listen 443 line there is no TLS socket, no matter what your vhost says.
  • <VirtualHost> says "when a request arrives on this address and port, use these settings". It never opens a port by itself.
APACHE
Listen 80
Listen 443

<VirtualHost *:80>
    ServerName www.example.com
    ServerAlias example.com
    DocumentRoot /var/www/example/public
    ErrorLog  ${APACHE_LOG_DIR}/example-error.log
    CustomLog ${APACHE_LOG_DIR}/example-access.log combined
</VirtualHost>

<VirtualHost *:80>
    ServerName blog.example.com
    DocumentRoot /var/www/blog/public
    ErrorLog  ${APACHE_LOG_DIR}/blog-error.log
    CustomLog ${APACHE_LOG_DIR}/blog-access.log combined
</VirtualHost>

Each <VirtualHost> holds the settings that differ per site: ServerName, DocumentRoot, logs, and any <Directory> blocks (see Apache httpd Configuration for how those merge). Anything outside a vhost is the main server configuration and acts as the default for every vhost; a vhost can override it.

Name-based, IP-based and port-based

There are three ways to tell sites apart:

How does Apache tell sites apart?

Name-based Same IP and port. The Host header decides.
IP-based Each site has its own IP address.
Port-based Each site listens on its own port.

Name-based is the default choice today.

1 / 2

Name-based hosting is what you will use almost always: every vhost is *:80 or *:443, and ServerName separates them. IP-based hosting puts a concrete address in the tag, like <VirtualHost 192.0.2.10:80>; it is still useful when a site needs its own address, for example for an old client that cannot send a Host header or for firewall rules. Port-based hosting is common for internal tools (Listen 8080 plus <VirtualHost *:8080>), where nobody minds a port number in the URL.

Over HTTPS, a client sends the host name early in the TLS handshake (SNI, Server Name Indication), so Apache can pick the right certificate before it has seen any HTTP headers. See HTTPS, TLS and Let's Encrypt.

ServerName and ServerAlias

ServerName is the main name of the site. ServerAlias adds more names, and may contain wildcards:

APACHE
<VirtualHost *:80>
    ServerName www.example.com
    ServerAlias example.com *.staging.example.com
    ...
</VirtualHost>

Apache compares the Host header (port removed, case ignored) with the ServerName and every ServerAlias of the vhosts it considers. The name is also used in some generated output, such as redirects Apache builds itself, so set it to the canonical name you want users to see. To redirect all alternative names to one canonical name, see Redirects and Rewrites.

Also set a global ServerName outside any vhost. If it is missing, Apache guesses from the machine's host name and prints the familiar warning "Could not reliably determine the server's fully qualified domain name" at startup.

How Apache chooses: the first vhost wins

Selection happens in two steps:

  1. Apache first finds the vhosts whose address and port match the connection. A vhost with a specific IP beats one with * for the same port.
  2. Among those, it walks them in the order they appear in the configuration and takes the first whose ServerName or ServerAlias matches the Host header. If none matches (or the request has no Host header), it uses the first vhost listed for that address and port.

That second rule has two practical consequences. First, the vhost that comes first is the default site: it answers for unknown names, for requests addressed to the bare IP address, and for the scanners that probe every server on the internet. On Debian files in sites-enabled are included alphabetically, which is why the default site is called 000-default.conf: the 000 makes it sort first. Second, order matters between overlapping names. If a vhost with ServerAlias *.example.com comes before the vhost for www.example.com, the wildcard grabs the request. Nginx behaves differently here: it prefers an exact name over a wildcard regardless of order.

A good production habit is to make the first vhost a harmless catch-all, so unknown names do not leak one of your real sites:

APACHE
<VirtualHost *:80>
    ServerName catchall.invalid
    DocumentRoot /var/www/empty
    <Directory /var/www/empty>
        Require all denied
    </Directory>
</VirtualHost>

The stand-in below implements both algorithms. Look at what happens to www.example.com when the order of the wildcard and the exact vhost changes.

JS Stand-in: Apache vs nginx site selection

Press Run (or Ctrl + Enter) to see the console output here.

No output.

With the wildcard first, Apache sends www.example.com to wildcard-site while nginx picks the exact name. Swap the order and Apache agrees with nginx. For other.org, nothing matches, so both fall back to their default: Apache's first vhost, nginx's default_server (or the first server when none is marked).

Do not rely on the fallback for security. A scanner that connects to your IP address will see whichever site is first. Make the default vhost an empty page or a refusal, and keep real sites behind real names.

Per-site logs and checking your work

Giving each vhost its own ErrorLog and CustomLog makes troubleshooting much easier: you read the log of the site that is broken instead of filtering a shared file. If you leave them out, a vhost inherits the main server's logs. Remember to rotate the new files (see Logs and Troubleshooting).

Apache can tell you exactly how it parsed your vhosts:

Terminal
sudo apachectl -S
# VirtualHost configuration:
# *:80    is a NameVirtualHost
#          default server catchall.invalid (/etc/apache2/sites-enabled/000-default.conf:1)
#          port 80 namevhost catchall.invalid ...
#          port 80 namevhost www.example.com ...

The line that starts with "default server" is your answer to "which site gets unknown names?". Run this after every vhost change, then test with curl by forcing the Host header without touching DNS:

Terminal
curl -I --resolve www.example.com:80:127.0.0.1 http://www.example.com/
curl -I -H "Host: blog.example.com" http://127.0.0.1/

A second stand-in: what a complete lookup looks like

Real requests also carry a port and sometimes arrive on a specific IP address. This second example reuses the idea with an IP-based vhost and shows how the specific address beats the wildcard:

JS Stand-in: address and port before names

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The first test shows an important detail: the request arrived on the address 10.0.0.5, where only admin-ip is defined, so it answers even though the Host header names a different site. The address match is decided first and names are compared only inside that group.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A request arrives with a Host header that matches no ServerName or ServerAlias. Which vhost answers?

    Apache falls back to the first vhost in configuration order for the matching address and port. That is why 000-default.conf is named to sort first on Debian.
  2. 2. What does the Listen directive do that VirtualHost does not?

    Listen creates the listening socket. A VirtualHost only describes how to handle requests that arrive on a socket that already exists.
  3. 3. ServerAlias *.example.com is in the first vhost and ServerName www.example.com in the second. Where does a request for www.example.com go in Apache?

    Apache takes the first matching vhost in order, with no preference for exact names. Put specific names before wildcards. (Nginx would pick the exact name instead.)
  4. 4. Why does HTTPS still work with many name-based vhosts on one IP address?

    Server Name Indication lets the client announce the host name before encryption starts, so the server can choose the matching vhost and certificate.

Summary

  • Listen opens ports; <VirtualHost> chooses settings for requests on them.
  • Name-based hosting uses the Host header and is the normal choice; IP-based and port-based hosting remain useful in special cases.
  • ServerName is the canonical name, ServerAlias adds more (wildcards allowed).
  • Apache matches address and port first, then takes the first name match in file order, otherwise the first vhost: the default site.
  • Nginx prefers exact names over wildcards regardless of order; Apache does not.
  • Give each site its own logs, make the default vhost harmless, and verify with apachectl -S and curl --resolve.

Next: .htaccess, Directory Rules and AllowOverride.