Websites

NGINX rules and .htaccess

Add custom NGINX directives to a website's server block, or turn on .htaccess files so Apache serves the site behind NGINX for rewrites and protection.

Last updated

VaultPanel generates each website's NGINX configuration from its settings. When a site needs more, such as redirects, rewrites, headers or caching, you have two options: add custom NGINX rules to its server block, or turn on .htaccess files so Apache serves the site behind NGINX, the way WordPress plugins and many PHP applications expect.

Custom NGINX rules

Custom rules are added to the site's server block, like a virtual host include. Open the website, go to the Settings tab and use the Custom NGINX rules card.

Custom rules
# Send the old blog to its new address.
location /blog/ {
    return 301 https://blog.example.com$request_uri;
}

# Cache static assets for a month.
location ~* \.(css|js|png|jpg|svg|woff2)$ {
    expires 30d;
    add_header Cache-Control "public";
}

gzip on;
gzip_types text/css application/javascript;

Before saving, VaultPanel reads the rules the way NGINX does and checks every directive against an allow list. The agent checks them again, writes the configuration and runs nginx -t. If the test fails, the site keeps its current configuration.

What is allowed

KindAllowed
Blockslocation, if, limit_except
Redirects and rewritesreturn, rewrite, break, set, try_files, error_page, internal, absolute_redirect, port_in_redirect, server_name_in_redirect, merge_slashes
Headers and cachingadd_header, add_trailer, expires, etag, if_modified_since, charset, default_type, index, autoindex
Compressiongzip, gzip_comp_level, gzip_min_length, gzip_proxied, gzip_types, gzip_vary
Accessallow, deny, satisfy, valid_referers
Limits and timeoutsclient_max_body_size, client_body_timeout, keepalive_timeout, send_timeout, limit_rate, limit_rate_after
Proxyingproxy_pass (to a fixed http:// or https:// address), proxy_set_header, proxy_hide_header, proxy_pass_header, proxy_http_version, proxy_buffering, proxy_cache_bypass, proxy_connect_timeout, proxy_read_timeout, proxy_send_timeout, proxy_redirect
PHPfastcgi_param, fastcgi_buffer_size, fastcgi_buffers, fastcgi_read_timeout
Contentsub_filter, sub_filter_once, sub_filter_types, log_not_found

Anything else is refused, including root, alias, include, log directives and Unix sockets, and so is another location / (the site already has one). The rules can be up to 8,192 characters.

Who can set them

Custom rules go into NGINX as text, so only staff can write them: a hosting customer's change to them is refused. They need agent 0.18.0 or newer on the server.

.htaccess files

With Use .htaccess files on, NGINX passes the site's requests to Apache, which reads .htaccess files in the site's folders. Rewrites, redirects, headers and password protection in .htaccess then work, as WordPress plugins and many PHP applications expect. NGINX still handles HTTPS, certificates and the Let's Encrypt check.

Turn it on

  1. Install Apache on the server: open the server's page, go to the Websites tab and install it from the Web stack card. Apache is optional software and is not part of Install all missing.
  2. Open the website, go to the Settings tab, tick Use .htaccess files and save.

How it runs

  • Apache listens on 127.0.0.1:8080 only, behind NGINX, as its own user (vp-apache). It joins a site's group only while that site has .htaccess files on, so it can read that site's files and no others.
  • PHP still runs in the site's own PHP-FPM pool, as the site user.
  • The site's Apache configuration is /etc/apache2/sites-available/vp-<site name>.conf, and its logs are /var/log/apache2/vp-<site name>.access.log and .error.log. VaultPanel tests it with apache2ctl configtest and puts the previous one back when the test fails.

What .htaccess files may contain

Besides the AuthConfig, Indexes and Limit groups (password protection, directory listings and access rules), .htaccess files may use:

PurposeDirectives
RewritesRewriteEngine, RewriteBase, RewriteCond, RewriteRule, RewriteOptions
RedirectsRedirect, RedirectMatch, RedirectPermanent, RedirectTemp
Errors and headersErrorDocument, Header
CachingExpiresActive, ExpiresByType, ExpiresDefault, FileETag
File typesAddType, AddCharset, AddDefaultCharset, AddEncoding, AddLanguage, DefaultLanguage

Directives such as SetHandler and SetEnv are not allowed, so a site cannot send requests to another site's PHP or change PHP's settings. Symbolic links are followed only when they belong to the same owner, and hidden files other than .well-known are never served.

Limits

  • .htaccess files are for static and PHP sites, not reverse proxies.
  • A static site cannot be a single-page app and use .htaccess files at the same time: add the index.html fallback to your .htaccess file instead.
  • .htaccess files need agent 0.18.0 or newer.

Turning .htaccess files off removes the site's Apache configuration and takes Apache's user out of the site's group.