# NGINX rules and .htaccess

URL: https://docs.vaultpanel.net/guides/websites/nginx-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.

```nginx
# 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.

> **Warning:**
Custom rules apply to every request the server block handles. Test them on a staging site first: a rule that passes `nginx -t` can still redirect or block more than you meant.

## .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:

| 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

- `.htaccess` files are for static and PHP sites, not reverse proxies.
- A static site cannot be a [single-page app](https://docs.vaultpanel.net/guides/websites#change-a-websites-settings) 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.
