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.
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.
# 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
| Kind | Allowed |
|---|---|
| Blocks | location, if, limit_except |
| Redirects and rewrites | return, rewrite, break, set, try_files, error_page, internal, absolute_redirect, port_in_redirect, server_name_in_redirect, merge_slashes |
| Headers and caching | add_header, add_trailer, expires, etag, if_modified_since, charset, default_type, index, autoindex |
| Compression | gzip, gzip_comp_level, gzip_min_length, gzip_proxied, gzip_types, gzip_vary |
| Access | allow, deny, satisfy, valid_referers |
| Limits and timeouts | client_max_body_size, client_body_timeout, keepalive_timeout, send_timeout, limit_rate, limit_rate_after |
| Proxying | proxy_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 |
| PHP | fastcgi_param, fastcgi_buffer_size, fastcgi_buffers, fastcgi_read_timeout |
| Content | sub_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
- 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.
- Open the website, go to the Settings tab, tick Use .htaccess files and save.
How it runs
- Apache listens on
127.0.0.1:8080only, behind NGINX, as its own user (vp-apache). It joins a site's group only while that site has.htaccessfiles 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.logand.error.log. VaultPanel tests it withapache2ctl configtestand 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:
| Purpose | Directives |
|---|---|
| Rewrites | RewriteEngine, RewriteBase, RewriteCond, RewriteRule, RewriteOptions |
| Redirects | Redirect, RedirectMatch, RedirectPermanent, RedirectTemp |
| Errors and headers | ErrorDocument, Header |
| Caching | ExpiresActive, ExpiresByType, ExpiresDefault, FileETag |
| File types | AddType, 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
.htaccessfiles are for static and PHP sites, not reverse proxies.- A static site cannot be a single-page app and use
.htaccessfiles at the same time: add theindex.htmlfallback to your.htaccessfile instead. .htaccessfiles 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.
PHP versions
Install PHP 7.4 to 8.5 side by side on a server and choose the version each PHP website runs, without touching its files or settings.
File manager
Browse, edit, upload and download a website's files in the browser, unpack and create archives, and change permissions, all as the site's own Linux user.