Skip to main content
Mapagam

Managing Name-Based Virtual Hosts

1. Understanding Name-Based Hosting Mechanism

Name-based virtual hosting allows multiple domains to be served from a single IP address by using the ServerName and ServerAlias directives to distinguish between different sites.

Directive Description Example
ServerName Defines the primary domain name for a virtual host ServerName example.com
ServerAlias Defines alternative domain names for a virtual host ServerAlias www.example.com
VirtualHost Defines a virtual host block using IP and port <VirtualHost 192.168.1.1:80>
Note: Name-based virtual hosting relies on the Host header sent by the client's browser to determine which virtual host to serve.

Example: Basic Name-Based Virtual Host Configuration

<VirtualHost *:80>
    ServerName example.com
    ServerAlias www.example.com
    DocumentRoot /var/www/example
</VirtualHost>

<VirtualHost *:80>
    ServerName another.com
    ServerAlias www.another.com
    DocumentRoot /var/www/another
</VirtualHost>

2. Configuring Multiple Domains on Single IP

Directive Description Example
ServerName Defines the primary domain name for the server ServerName example.com
ServerAlias Defines alternative domain names for the server ServerAlias www.example.com
VirtualHost Defines a virtual host block for a specific IP and port <VirtualHost *:80>

Example: Basic Virtual Host Configuration

<VirtualHost *:80>
    ServerName example.com
    ServerAlias www.example.com
    DocumentRoot /var/www/example
</VirtualHost>

Example: Multiple Domains on Same IP

<VirtualHost *:80>
    ServerName site1.com
    ServerAlias www.site1.com
    DocumentRoot /var/www/site1
</VirtualHost>

<VirtualHost *:80>
    ServerName site2.com
    ServerAlias www.site2.com
    DocumentRoot /var/www/site2
</VirtualHost>
Note: The VirtualHost directive must be used to define each domain's configuration block. All domains must have unique ServerName or ServerAlias values to avoid conflicts.

3. Setting Up ServerName per VirtualHost

Directive Values Description
ServerName example.com Defines the primary name for the server
ServerName www.example.com Alternative name for the server

Example: Configuring ServerName in VirtualHost

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/example
</VirtualHost>

<VirtualHost *:80>
    ServerName www.example.com
    DocumentRoot /var/www/example
</VirtualHost>
Note: The ServerName directive should be set to the canonical name of the host.

4. Using ServerAlias for Multiple Domains

Directive Description Usage
ServerAlias Defines additional hostnames that can be used to access the same virtual host ServerAlias example.com www.example.com

Example: Setting up ServerAlias

<VirtualHost *:80>
    ServerName example.com
    ServerAlias www.example.com
    DocumentRoot /var/www/example
</VirtualHost>
Note: ServerAlias allows multiple domains to point to the same virtual host configuration, useful for managing subdomains or alternate names.

5. Configuring Wildcard ServerAlias

Directive Values Description
ServerAlias *.example.com Defines a wildcard alias for the virtual host

Example: Wildcard ServerAlias Configuration

<VirtualHost *:80>
    ServerName example.com
    ServerAlias *.example.com
    DocumentRoot /var/www/example
</VirtualHost>
Note: The *.example.com pattern matches any subdomain of example.com.

6. Setting Default Catch-All VirtualHost

Directive Values Description
ServerName example.com Primary domain name for the server
DocumentRoot /var/www/html Directory from which to serve files
ErrorLog /var/log/apache2/error.log Path to the error log file
CustomLog /var/log/apache2/access.log combined Path to the access log file and format

Example: Default Catch-All VirtualHost Configuration

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/html
    ErrorLog /var/log/apache2/error.log
    CustomLog /var/log/apache2/access.log combined
</VirtualHost>
Note: The *:80 wildcard allows the virtual host to listen on any IP address for port 80.

7. Using Server Name Indication for SSL

Server Name Indication (SNI) is an extension to the TLS protocol that allows a client to indicate which hostname it is attempting to connect to at the start of the TLS handshake. This enables a single IP address to host multiple SSL/TLS-enabled virtual hosts.

Directive Description Default Notes
SSLEngine Enables or disables SSL/TLS for a virtual host off Must be set to on for SNI support
SSLCertificateFile Path to the certificate file None Required for SSL/TLS
SSLCertificateKeyFile Path to the private key file None Required for SSL/TLS
SSLCertificateChainFile Path to the certificate chain file None Optional but recommended for intermediate certificates

Example: Basic SNI Configuration

<VirtualHost *:443>
    ServerName example.com
    SSLEngine on
    SSLCertificateFile /path/to/example.com.crt
    SSLCertificateKeyFile /path/to/example.com.key
    SSLCertificateChainFile /path/to/chain.crt
</VirtualHost>

<VirtualHost *:443>
    ServerName another.example.com
    SSLEngine on
    SSLCertificateFile /path/to/another.example.com.crt
    SSLCertificateKeyFile /path/to/another.example.com.key
    SSLCertificateChainFile /path/to/chain.crt
</VirtualHost>
Note: Ensure that all certificates used in SNI configurations are valid and properly signed by a trusted CA. Also, make sure that the client supports SNI; older clients may not support it.

8. Testing VirtualHost Resolution

Example: Testing Virtual Host Configuration

curl -H "Host: example.com" http://192.168.1.100/
Test Method Description Notes
curl with Host header Send HTTP request with specific Host header to server IP Useful for testing name-based virtual hosts without DNS
Local DNS override Modify /etc/hosts (Linux/Mac) or hosts file (Windows) Maps domain name to server IP for local testing
Browser dev tools Use browser's network tab to inspect request headers Can simulate different Host headers in some cases
Note: Ensure that the server's ServerName directive is set correctly to avoid default virtual host behavior.
Warning: If ServerName is not set, Apache may use the IP address as the default server name, potentially causing incorrect virtual host resolution.

9. Debugging VirtualHost Issues

Example: Check VirtualHost Configuration

apachectl -t -D DUMP_VHOSTS
Issue Possible Cause Solution
No matching VirtualHost Request does not match any defined <VirtualHost> Verify IP/port combinations and use apachectl -t -D DUMP_VHOSTS
Default VirtualHost used Missing or incorrect ServerName in config Add proper ServerName or ServerAlias
SSL mismatch HTTPS request to non-SSL VirtualHost Ensure <VirtualHost *:443> is configured for SSL
Note: Use apachectl -S to list all configured VirtualHosts and their matching rules.

Debugging Steps

  1. Run apachectl -t -D DUMP_VHOSTS to view all VirtualHosts
  2. Check apachectl -S for server configuration details
  3. Verify ServerName and ServerAlias in each VirtualHost
  4. Confirm IP/port bindings match incoming requests
  5. Use curl -H "Host: example.com" to test specific host headers

10. Managing DNS for Virtual Hosts

Resource Description Usage
A Record Maps a domain name to an IP address Used for primary DNS resolution of virtual hosts
CNAME Record Creates an alias from one domain name to another Useful for subdomains or redirecting traffic
TXT Record Stores text information for domain verification Used for SPF, DKIM, and domain ownership validation

Example: DNS Configuration for Virtual Hosts

; Example DNS zone file for virtual hosts
example.com. IN A 192.168.1.100
www.example.com. IN CNAME example.com.
api.example.com. IN A 192.168.1.101
mail.example.com. IN A 192.168.1.102
Note: Ensure DNS propagation is complete before testing virtual hosts.
Warning: Misconfigured DNS can lead to traffic being routed incorrectly or security issues.

11. Organizing VirtualHost Configuration Files

Example: Basic Virtual Host Configuration

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/example
    <Directory "/var/www/example">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
Directive Description Usage
VirtualHost Defines a virtual host block Required for each virtual host
ServerName Primary domain name for the virtual host Used for name-based matching
DocumentRoot Root directory for the virtual host's content Must point to valid directory path
Directory Configuration for a specific directory Used to set permissions and overrides
Note: Use <VirtualHost *:80> to match any IP on port 80.

Best Practices for Configuration Organization

  • Separate configuration files by domain or project
  • Use Include directives to manage multiple files
  • Keep common settings in a shared configuration file
  • Use descriptive names for configuration files (e.g., example.com.conf)

12. Understanding VirtualHost Precedence Rules

Rule Description Example
Default VirtualHost The first VirtualHost defined in the configuration is used as the default if no matching VirtualHost is found. 
<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/example
</VirtualHost>

<VirtualHost *:80>
    ServerName another.com
    DocumentRoot /var/www/another
</VirtualHost>
Specific IP Address Match VirtualHosts with specific IP addresses take precedence over wildcard or any address matches. 
<VirtualHost 192.168.1.10:80>
    ServerName specific.example.com
    DocumentRoot /var/www/specific
</VirtualHost>

<VirtualHost *:80>
    ServerName wildcard.example.com
    DocumentRoot /var/www/wildcard
</VirtualHost>
Port Match VirtualHosts matching the specific port take precedence over those that do not specify a port. 
<VirtualHost *:80>
    ServerName port80.example.com
    DocumentRoot /var/www/port80
</VirtualHost>

<VirtualHost *:443>
    ServerName port443.example.com
    DocumentRoot /var/www/port443
</VirtualHost>
ServerName Match VirtualHosts with matching ServerName take precedence over those without a matching ServerName. 
<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/example
</VirtualHost>

<VirtualHost *:80>
    ServerName another.com
    DocumentRoot /var/www/another
</VirtualHost>
ServerAlias Match VirtualHosts with matching ServerAlias take precedence over those without a matching alias. 
<VirtualHost *:80>
    ServerName example.com
    ServerAlias www.example.com
    DocumentRoot /var/www/example
</VirtualHost>

<VirtualHost *:80>
    ServerName another.com
    DocumentRoot /var/www/another
</VirtualHost>

Was this article helpful?

Related Cheat Sheets