Configuring Apache Virtual Hosts on Gentoo

Apache is the web server behind applications that ship .htaccess files and expect mod_rewrite, mod_php, or other Apache-specific modules. On Gentoo, Apache is installed via Portage and managed through OpenRC, with a configuration layout that differs from Debian's sites-available/sites-enabled pattern. Gentoo uses a single vhosts.d directory and an APACHE2_OPTS variable in /etc/conf.d/apache2 to control which modules are loaded.

Installing Apache

emerge -av www-servers/apache

Gentoo's Apache package compiles from source with USE flags controlling which modules are built. Common USE flags for a web server hosting PHP applications:

cat > /etc/portage/package.use/apache << 'EOF'
www-servers/apache ssl threads
EOF

After installation, verify the default configuration is valid:

apache2ctl configtest

This should output:

Syntax OK

If it reports errors, the default configuration files may need adjustment before proceeding.

Understanding Gentoo's Apache Layout

Gentoo's Apache configuration differs from other distributions. The key files and directories:

Module Loading

Unlike Debian's a2enmod/a2dismod system, Gentoo controls which Apache modules are loaded through the APACHE2_OPTS variable in /etc/conf.d/apache2.

View the current module flags:

grep APACHE2_OPTS /etc/conf.d/apache2

The default typically looks like:

APACHE2_OPTS="-D DEFAULT_VHOST -D INFO -D SSL -D SSL_DEFAULT_VHOST -D LANGUAGE"

Each -D FLAG activates a corresponding <IfDefine FLAG> block in the module configuration files under /etc/apache2/modules.d/. To enable a module, add its flag. To disable it, remove the flag.

Common module flags:

For example, to enable mod_rewrite and mod_proxy:

APACHE2_OPTS="-D DEFAULT_VHOST -D INFO -D SSL -D SSL_DEFAULT_VHOST -D LANGUAGE -D REWRITE -D PROXY"

After changing APACHE2_OPTS, restart Apache:

rc-service apache2 restart

Default Virtual Hosts

Gentoo installs two default virtual host configurations:

• /etc/apache2/vhosts.d/00_default_vhost.conf — HTTP (port 80)
• /etc/apache2/vhosts.d/00_default_ssl_vhost.conf — HTTPS (port 443)

These serve content from /var/www/localhost/htdocs/ and are activated by the DEFAULT_VHOST and SSL_DEFAULT_VHOST flags in APACHE2_OPTS. Leave them in place as a fallback for requests that don't match any named virtual host.

Verify they exist:

ls /etc/apache2/vhosts.d/

Expected output:

00_default_vhost.conf
00_default_ssl_vhost.conf

If these files are missing (e.g., from a previous cleanup), re-emerge Apache to restore them:

emerge -av www-servers/apache

Creating Named Virtual Hosts

Each domain or application gets its own configuration file in /etc/apache2/vhosts.d/. Files are loaded in alphabetical order, so the 00_ prefixed defaults always load first.

HTTP Virtual Host

Create /etc/apache2/vhosts.d/example.com.conf:

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

    <Directory /var/www/example.com/htdocs>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog /var/log/apache2/example.com-error.log
    CustomLog /var/log/apache2/example.com-access.log combined
</VirtualHost>

HTTPS Virtual Host

For SSL-enabled sites, create /etc/apache2/vhosts.d/example.com-ssl.conf:

<IfDefine SSL>
<VirtualHost *:443>
    ServerName example.com
    ServerAlias www.example.com
    DocumentRoot /var/www/example.com/htdocs

    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/example.com.crt
    SSLCertificateKeyFile /etc/ssl/private/example.com.key
    SSLCertificateChainFile /etc/ssl/certs/example.com-chain.crt

    <Directory /var/www/example.com/htdocs>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog /var/log/apache2/example.com-ssl-error.log
    CustomLog /var/log/apache2/example.com-ssl-access.log combined
</VirtualHost>
</IfDefine>

The <IfDefine SSL> wrapper ensures this block is only loaded when the SSL flag is active in APACHE2_OPTS.

HTTP to HTTPS Redirect

To force all traffic to HTTPS, modify the HTTP virtual host to redirect:

<VirtualHost *:80>
    ServerName example.com
    ServerAlias www.example.com
    Redirect permanent / https://example.com/
</VirtualHost>

Creating the Document Root

mkdir -p /var/www/example.com/htdocs
chown -R apache:apache /var/www/example.com

Create a test page:

echo "<h1>example.com</h1>" > /var/www/example.com/htdocs/index.html
chown apache:apache /var/www/example.com/htdocs/index.html

Directory Options

The <Directory> block controls how Apache serves files from a directory. Key directives:

Options -Indexes — disables directory listing. Without this, if a directory has no index.html, Apache shows a file listing to the visitor. This is a security issue on production servers.

Options +FollowSymLinks — allows Apache to follow symbolic links. Needed for many applications that symlink assets or share directories.

AllowOverride All — allows .htaccess files to override directory-level settings. Applications like WordPress, Matomo, and Nextcloud rely on .htaccess for URL rewriting and access control. Set this to None if the application doesn't need .htaccess — it avoids the per-request overhead of Apache checking for .htaccess files in every directory.

Require all granted — allows all connections. Use Require ip 192.168.1.0/24 to restrict access to specific networks for admin panels.

PHP Integration

Apache on Gentoo can run PHP through either mod_php (embedded in the Apache process) or PHP-FPM (FastCGI Process Manager, separate process pool).

PHP-FPM (Recommended)

PHP-FPM runs PHP as a separate process, which is more secure and allows different PHP configurations per virtual host. Install PHP-FPM:

emerge -av dev-lang/php

Ensure the fpm USE flag is set:

cat >> /etc/portage/package.use/php << 'EOF'
dev-lang/php fpm mysql mysqli pdo gd xml zip curl
EOF

Enable mod_proxy_fcgi in Apache. Add PROXY to APACHE2_OPTS in /etc/conf.d/apache2 if not already present.

In your virtual host, add a FilesMatch directive to pass PHP requests to FPM:

<FilesMatch \.php$>
    SetHandler "proxy:unix:/run/php-fpm/www.sock|fcgi://localhost"
</FilesMatch>

Start PHP-FPM:

rc-update add php-fpm default
rc-service php-fpm start

mod_php (Alternative)

For simpler setups, mod_php processes PHP inside the Apache worker process. Add the PHP flag to APACHE2_OPTS:

APACHE2_OPTS="... -D PHP"

mod_php is simpler to configure but runs PHP with the same privileges as Apache and can't be configured per-virtual-host.

Validating and Restarting

After any configuration change, validate first:

apache2ctl configtest

If valid, restart:

rc-service apache2 restart

Check that Apache is listening:

ss -lnt sport = :80
ss -lnt sport = :443

Logging

Apache logs to /var/log/apache2/ by default. Each virtual host should specify its own error and access logs for easier debugging.

View the error log:

tail -f /var/log/apache2/example.com-error.log

The combined log format in the access log includes the referrer and user agent, which is useful for traffic analysis.

Security Hardening

Hide Server Version

Add to /etc/apache2/httpd.conf or a file in /etc/apache2/modules.d/:

ServerTokens Prod
ServerSignature Off

ServerTokens Prod reduces the Server header from Apache/2.4.58 (Gentoo) OpenSSL/3.1.4 to just Apache. ServerSignature Off removes the version string from error pages.

Disable Unnecessary Modules

Review loaded modules:

apache2ctl -M

Remove flags from APACHE2_OPTS for modules you don't need. Each loaded module increases the attack surface and memory usage.

Restrict Access by IP

For admin panels or staging sites, restrict access:

<Directory /var/www/example.com/htdocs/admin>
    Require ip 192.168.1.0/24
    Require ip 10.0.0.0/8
</Directory>

Starting Apache at Boot

Enable Apache in the default runlevel:

rc-update add apache2 default
rc-service apache2 start

Verify it's running:

rc-status | grep apache2

Summary

After completing these steps:

• Apache is installed on Gentoo with SSL and required modules
• Module loading is controlled via APACHE2_OPTS in /etc/conf.d/apache2
• Named virtual hosts serve content from per-domain document roots
• PHP applications run through PHP-FPM via mod_proxy_fcgi
• Server version information is hidden from responses
• Each virtual host has its own log files for independent troubleshooting

Apache handles applications that need .htaccess support and Apache-specific modules. For reverse proxying to backend applications, nginx is typically a better choice.