Skip to content

Commit 496b27a

Browse files
poespaspoespas
authored
Merge branch 'master' into add-redis-menu
2 parents 8e5b0a5 + c997f96 commit 496b27a

2 files changed

Lines changed: 178 additions & 0 deletions

File tree

‎docs/hypernode-platform/nginx/how-to-use-nginx.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,3 +128,48 @@ rewrite ^/fr/(.*)$ http://yourshop.fr/$1 permanent;
128128
This will also maintain subfolders and query strings (such as <http://yourshop.com/fr/subfolder?arguments>).
129129

130130
If the move is only temporary, you should use redirect instead of permanent.
131+
132+
## Redirects using mapping
133+
134+
The map directive allows you to define conditional logic outside of your main server block. This keeps your configuration:
135+
136+
- Easier to read
137+
- More scalable for large numbers of redirects
138+
- More efficient than stacking multiple if statements
139+
140+
You will define your redirects in two parts:
141+
142+
1. A mapping configuration (placed in an `/data/web/nginx/http.*` file)
143+
1. A rewrite rule (placed in a `/data/web/nginx/server.*` file)
144+
145+
Step 1: Define the Redirect Mapping
146+
147+
`/data/web/nginx/http.*`
148+
149+
```nginx
150+
map $uri $out_redirect {
151+
~/the-location-you-want-to-redirect /new-location;
152+
}
153+
```
154+
155+
You can expand this map with multiple rules:
156+
157+
```nginx
158+
map $uri $out_redirect {
159+
~/old-page /new-page;
160+
~/blog/(.*) /articles/$1;
161+
~/deprecated /;
162+
}
163+
```
164+
165+
Step 2: Apply the Redirect in the Server Block
166+
167+
`/data/web/nginx/server.*`
168+
169+
```nginx
170+
if ($out_redirect) {
171+
rewrite 301 $out_redirect;
172+
}
173+
```
174+
175+
Using `map` for redirects in NGINX provides a clean, scalable, and efficient way to manage URL rewrites. By separating logic from execution, your configuration remains easy to maintain even as the number of redirects grows.

‎docs/hypernode-platform/varnish/Investigating-varnish-errors-on-hypernode.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
myst:
3+
html_meta:
4+
description: Learn how to investigate and resolve Varnish errors on Hypernode
5+
by checking NGINX and Varnish logs, identifying header and workspace issues,
6+
and applying the correct buffer and workspace settings.
7+
title: Investigating Varnish errors on Hypernode
8+
---
9+
10+
# Investigating Varnish errors
11+
12+
When Varnish is enabled, two common HTTP errors can occur: **502 Bad Gateway** and **503 Service Unavailable**. Both are related to how NGINX and Varnish handle response headers and buffers, but they have different causes and solutions. This article guides you through identifying and resolving both.
13+
14+
## 502 Bad Gateway
15+
16+
### What causes it?
17+
18+
One common cause of a `502 Bad Gateway` error with Varnish enabled is that NGINX receives response headers from Varnish that exceed its configured buffer sizes.
19+
20+
This can happen after enabling Varnish or after a change that increases the
21+
size of response headers, for example:
22+
23+
- large cookies
24+
- many `Set-Cookie` headers
25+
- additional custom response headers
26+
27+
### Step 1: Check the NGINX Error Log
28+
29+
Inspect `/var/log/nginx/error.log` and look for the following message:
30+
31+
```console
32+
upstream sent too big header while reading response header from upstream
33+
```
34+
35+
If this message is present, increase the NGINX buffer sizes used for upstream.
36+
37+
### Step 2: Solution
38+
39+
Create a custom NGINX config file at `~/nginx/server.header_buffer` with the following content:
40+
41+
```console
42+
fastcgi_buffers 16 16k;
43+
fastcgi_buffer_size 32k;
44+
proxy_buffer_size 128k;
45+
proxy_buffers 4 256k;
46+
proxy_busy_buffers_size 256k;
47+
```
48+
49+
This increases the buffer sizes NGINX uses when reading response headers from upstream (Varnish), which resolves the "too big header" issue in the vast majority of cases.
50+
51+
```{tip}
52+
After creating the file, NGINX will be reloaded automatically
53+
```
54+
55+
## 503 Service Unavailable (Backend Fetch Failed)
56+
57+
### What causes it?
58+
59+
A 503 error occurs when Varnish itself runs out of workspace memory while processing the response from the backend (e.g. PHP-FPM). This is an internal Varnish issue, visible in the Varnish log as an `out of workspace (Bo)` error.
60+
61+
### Step 1: Check the NGINX Access Log
62+
63+
Start by checking `/var/log/nginx/access.log` for any `503` responses. Look for a line similar to the following:
64+
65+
```log
66+
./access.log:{"time":"2026-02-26T06:55:31+00:00", "remote_addr":"122.173.26.219", "remote_user":"", "host":"www.domain.com", "request":"GET /some/url/", "status":"503", "body_bytes_sent":"552", "referer":"", "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36", "request_time":"0.000", "handler":"varnish", "country":"NL", "server_name":"www.domain.com", "port":"443", "ssl_cipher":"TLS_AES_128_GCM_SHA256", "ssl_protocol":"TLSv1.3"}
67+
```
68+
69+
### Step 2: Check the Varnish Log
70+
71+
If you confirmed a `503` response, inspect the Varnish logs using `varnishlog` to identify the root cause. Look for lines like the following:
72+
73+
```
74+
- FetchError workspace_backend overflow
75+
- BackendClose 24 boot.default
76+
- Timestamp Error: 1772091843.439388 0.032699 0.000160
77+
- BerespProtocol HTTP/1.1
78+
- Error out of workspace (Bo)
79+
- LostHeader 503
80+
- BerespReason Service Unavailable
81+
- BerespReason Backend fetch failed
82+
- Error out of workspace (Bo)
83+
```
84+
85+
The key indicators are:
86+
87+
- `FetchError: workspace_backend overflow` — Varnish could not allocate enough workspace to process the backend response.
88+
- `Error: out of workspace (Bo)` — the backend object workspace (`Bo`) is too small for the response headers being returned.
89+
90+
### Step 3: Solution
91+
92+
#### Increase the Varnish backend workspace
93+
94+
Increase the backend workspace limit using the `hypernode-systemctl` CLI:
95+
96+
```console
97+
hypernode-systemctl settings varnish_workspace_backend 256k
98+
```
99+
100+
A value of `256k` is a good starting point; increase further if the error persists.
101+
102+
#### Increase the response header buffer sizes
103+
104+
If the backend is sending unusually large response headers, also raise the following settings:
105+
106+
```console
107+
# Maximum size of a single response header line
108+
hypernode-systemctl settings varnish_http_resp_hdr_len 8k
109+
110+
# Maximum total size of all response headers combined
111+
hypernode-systemctl settings varnish_http_resp_size 32k
112+
```
113+
114+
```{important}
115+
After changing these settings, Varnish will restart automatically. Allow a moment for it to reload before testing.
116+
```
117+
118+
### Verification
119+
120+
After applying the changes, monitor the Varnish log to confirm `503` errors are no longer occurring:
121+
122+
```console
123+
varnishlog -q "BerespStatus == 503"
124+
```
125+
126+
If errors continue, consider gradually increasing the workspace values further (e.g., `512k` for `varnish_workspace_backend`).
127+
128+
If the problem persists after applying these fixes, contact support for further assistance.
129+
130+
```{information}
131+
For more information about Varnish configuration and tuning, see our [documentation on improving Varnish hit rate](https://docs.hypernode.com/hypernode-platform/varnish/improving-varnish-hit-rate-on-hypernode.html) and the official
132+
[Varnish documentation](https://varnish-cache.org/docs/).
133+
```

0 commit comments

Comments
 (0)