How Does Apache Handle Symlinks with Options?

The Options directive in the Apache HTTP Server controls which server features are available in specific directories. When it comes to handling symbolic links (symlinks), Apache relies on two primary values within this directive: FollowSymLinks and SymLinksIfOwnerMatch. Security administrators and web developers must understand how these options function, as misconfiguring symlink behavior can expose sensitive system files to unauthorized users or severely impact server performance.

The Core Symlink Directives

Apache determines whether to traverse a symbolic link based on the parameters passed to the Options directive in your httpd.conf file or .htaccess files.

• Options FollowSymLinks: This is the more permissive setting. When enabled, the server will follow symbolic links in the specified directory. If a symlink points to a file or directory outside the document root, Apache will still serve it, provided the underlying operating system file permissions allow the Apache user read access.
• Options SymLinksIfOwnerMatch: This setting introduces a strict security check. Apache will only follow the symbolic link if the target file or directory is owned by the exact same user ID (UID) as the symbolic link itself. If the owners do not match, Apache returns a 403 Forbidden error.

Security vs. Performance Trade-offs

Choosing between these two options requires balancing the security needs of your server against its performance capabilities.

The Security Risks of FollowSymLinks

Enabling FollowSymLinks without restrictions can pose a massive security risk, especially in shared hosting environments. If a malicious user can upload or create a symlink in their web directory, they could point it to critical system files like /etc/passwd or configuration files belonging to other users. If the Apache process has read access to those files, it will serve them to the browser.

Using SymLinksIfOwnerMatch mitigates this risk by ensuring users can only link to files they actually own.

The Performance Cost of SymLinksIfOwnerMatch

While SymLinksIfOwnerMatch is significantly more secure, it comes with a performance penalty. To verify that the owners match, Apache must issue additional system calls (lstat()) for every portion of the request path.

For example, if a request is made for /www/htdocs/app/index.html, Apache must check the attributes of:

• /www
• /www/htdocs
• /www/htdocs/app
• /www/htdocs/app/index.html

On high-traffic websites, these extra system calls can result in noticeable CPU overhead and slower response times.

How to Configure Symlinks in Apache

To configure these settings, you add the Options directive inside a <Directory> block in your main configuration file.

Enabling Secure Symlinks

To prioritize security while still allowing users to utilize symlinks within their own file boundaries, use the following configuration:

<Directory "/var/www/html">
    Options +SymLinksIfOwnerMatch
    AllowOverride None
    Require all granted
</Directory>

Optimizing for Maximum Performance

If you completely control the server environment and are certain that no untrusted users can create symlinks, you can maximize performance by combining FollowSymLinks with the disabling of .htaccess file overrides:

<Directory "/var/www/html">
    Options +FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

By setting AllowOverride None, you prevent users from overriding these performance-optimized settings in local .htaccess files, ensuring your security and performance baselines remain intact across the entire web server.