How to Exclude Specific Files from Apache ProxyPass/ProxyPassMatch: A Practical Guide for Reverse Proxy Configurations


4 views 



When setting up reverse proxy configurations with Apache's ProxyPass, developers often need to exclude specific files or patterns from being proxied. The documentation mentions the exclamation mark (!) syntax for exclusions, but practical examples are scarce.




Here's the correct syntax to exclude test.html from being proxied:



<VirtualHost *:80>
    # Main proxy configuration
    ProxyPass / http://localhost:9000/
    ProxyPassReverse / http://localhost:9000/
    
    # Exclusion rules
    ProxyPass /test.html !
    ProxyPassReverse /test.html !
</VirtualHost>



For more complex exclusion patterns, use ProxyPassMatch with regular expressions:


# Exclude all HTML files
ProxyPassMatch ^/(.*\.html)$ !
    
# Exclude multiple file types
ProxyPassMatch ^/(.*\.(html|css|js))$ !



1. Order Matters: Apache processes ProxyPass directives in order. Place exclusions before the general proxy rule.


# Wrong order (will proxy everything)
ProxyPass / http://localhost:9000/
ProxyPass /test.html !

# Correct order
ProxyPass /test.html !
ProxyPass / http://localhost:9000/



2. Matching Exact Paths: For exact path matching, ensure no trailing slashes:


# Might not work as expected
ProxyPass /test.html/ !
    
# Correct syntax
ProxyPass /test.html !



Here's a complete virtual host configuration that excludes multiple file patterns:


<VirtualHost *:443>
    ServerName example.com
    
    # Exclusions first
    ProxyPass /index.html !
    ProxyPass /healthcheck !
    ProxyPassMatch ^/(.*\.(html|css|js|png))$ !
    
    # Main proxy configuration
    ProxyPass / http://localhost:9000/
    ProxyPassReverse / http://localhost:9000/
    
    # SSL configuration would go here
</VirtualHost>



Enable debug logging to verify your exclusion rules:


LogLevel debug proxy:trace5



Check Apache's error log after making changes to confirm which requests are being proxied.






When setting up reverse proxying with Apache, you might encounter situations where you need to exclude certain files or patterns from being proxied to the backend server. The standard ProxyPass directive forwards all matching requests, making exclusions non-trivial.


The exclamation mark (!) is the key to exclusion patterns in ProxyPass directives, but its placement and context matter significantly. Here's what works:



# Correct exclusion syntax
ProxyPass /test.html !
ProxyPass /static/ !



Let's examine several common scenarios with working solutions:



# Case 1: Excluding a specific file
ProxyPass /special.html !
ProxyPass / http://localhost:9000/

# Case 2: Excluding an entire directory
ProxyPass /images/ !
ProxyPass / http://localhost:9000/

# Case 3: Excluding by pattern (using ProxyPassMatch)
ProxyPassMatch ^/(.*\.pdf)$ !
ProxyPass / http://localhost:9000/



Apache processes ProxyPass directives in order. Your exclusions must appear before the catch-all rule:



# Wrong order - will proxy everything
ProxyPass / http://localhost:9000/
ProxyPass /test.html !  # This will never be reached

# Correct order - exclusions first
ProxyPass /test.html !
ProxyPass / http://localhost:9000/



Developers often make these mistakes when trying to exclude files:


    

  • Placing the exclusion after the catch-all ProxyPass
    • 

  • Using incorrect regex patterns with ProxyPassMatch
    • 

  • Forgetting to include the leading slash in paths
    • 



For complex exclusions, ProxyPassMatch offers regex capabilities:



# Exclude multiple file extensions
ProxyPassMatch ^/(.*\.(html|css|js))$ !
ProxyPass / http://localhost:9000/

# Exclude based on query parameters
ProxyPassMatch ^/api\?nocache= !
ProxyPass / http://localhost:9000/



Always verify your setup by:


    

  1. Restarting Apache: sudo apachectl restart
    2. 

  2. Checking error logs: tail -f /var/log/apache2/error.log
    3. 

  3. Using curl to test specific paths
    4.