Proxy Hosts on PosternProxy Documentation

Load Balancing

Mon, 01 Jan 0001 00:00:00 +0000

Load Balancing#

PosternProxy supports distributing traffic across multiple upstream backends for a single proxy host. Configuration is on the Upstreams tab of the Add/Edit Proxy Host modal.

Adding backends#

The first upstream is always the Primary backend (set on the Details tab). Additional backends are added on the Upstreams tab. Each extra backend requires:

Host / IP — the internal address of the backend server
Port — the port the backend listens on

There is no enforced limit on the number of backends.

Health Checks

Mon, 01 Jan 0001 00:00:00 +0000

Health Checks#

PosternProxy exposes Caddy’s built-in health-check machinery through the Health tab of the proxy host form. Health checks keep your load balancer from routing traffic to backends that are down or degraded.

Active health checks#

Active checks probe each upstream on a schedule by sending an HTTP request and evaluating the response.

Setting	Default	Description
Path	`/`	URL path Caddy requests on each backend
Interval	`30s`	How often to run the check
Timeout	`5s`	Maximum time to wait for a response
Expected status	`200`	HTTP status code that counts as healthy

Enable active checks with the Enable health checks toggle on the Health tab.

SSL / TLS

Mon, 01 Jan 0001 00:00:00 +0000

SSL / TLS#

PosternProxy leverages Caddy’s automatic HTTPS to handle TLS with minimal configuration. The SSL tab controls certificate selection and security options.

Automatic Let’s Encrypt (default)#

Leave the SSL Certificate field set to None / Caddy automatic. Caddy will:

Obtain a certificate from Let’s Encrypt the first time a request arrives for the domain
Store the certificate in its managed certificate store
Renew automatically before expiry

Requirements for automatic certificates:

Rate Limiting

Mon, 01 Jan 0001 00:00:00 +0000

Rate Limiting#

PosternProxy can cap the number of requests a single IP address can make to a proxy host within a sliding time window. Rate limiting is configured on the Security tab.

How it works#

Rate limiting is implemented via the caddy-ratelimit Caddy plugin, which is included in the PosternProxy Caddy build.

When a client exceeds the limit, Caddy returns a 429 Too Many Requests response. The limit resets on a sliding window basis — it is not a hard per-minute bucket.

TLS Passthrough

Mon, 01 Jan 0001 00:00:00 +0000

TLS Passthrough#

TLS Passthrough lets Caddy forward encrypted TLS connections directly to an upstream without terminating (decrypting) them. The upstream handles TLS itself — Caddy never sees the plaintext.

When to use it#

Use TLS Passthrough when:

The upstream requires mutual TLS (mTLS) / client certificates that Caddy cannot forward
The upstream is a database or other service presenting its own TLS certificate
You need end-to-end encryption between client and upstream with no proxy in the middle
The upstream uses a private CA certificate that Caddy cannot validate

How to enable#

On the Details tab, toggle TLS Passthrough on. When enabled:

Custom Error Pages

Mon, 01 Jan 0001 00:00:00 +0000

Custom Error Pages#

PosternProxy can serve custom HTML pages when a proxy host returns a 404, 502, or 503 status code. This replaces Caddy’s default plain-text error responses with your own branded or user-friendly HTML.

Configuration#

Open the Errors tab of the Add/Edit Proxy Host modal. You will see three panels, one for each supported status code:

Code	Meaning	Common cause
404	Not Found	Route exists but upstream returned 404; or path not matched
502	Bad Gateway	Upstream is down or returned an invalid response
503	Service Unavailable	Upstream is overloaded or in maintenance mode

Paste your HTML into the relevant textarea. Leave a field blank to use Caddy’s default behaviour for that code.

Custom Headers

Mon, 01 Jan 0001 00:00:00 +0000

Custom Headers#

PosternProxy can inject, modify, or remove HTTP headers on requests sent to your upstream and on responses returned to clients. Header rules are configured on the Headers tab.

Adding a rule#

Each rule has four fields:

Field	Options	Description
Direction	Request / Response	Whether the rule applies to the upstream request or the downstream response
Operation	Set / Add / Delete	What to do with the header
Name	Any string	The header name (case-insensitive)
Value	Any string	The header value (not used for Delete)

Click + Add Rule to insert a new row. Rows with an empty Name are ignored on save.

Custom Locations

Mon, 01 Jan 0001 00:00:00 +0000

Custom Locations#

Custom locations let you override proxy behaviour for specific URL paths within a proxy host. They are configured on the Locations tab.

What locations do#

By default, a proxy host forwards all paths to the same upstream. Locations allow you to:

Send /api/* to a different backend than /
Apply different forward_scheme per path
Set path-specific Caddy directives using Advanced Config

Adding a location#

Click + Add Location on the Locations tab. Each location has:

Config History

Mon, 01 Jan 0001 00:00:00 +0000

Config History#

PosternProxy records a snapshot of every proxy host’s configuration before each change. You can browse the history and roll back to any previous state.

Viewing history#

Open the ⋮ menu on any proxy host row in the table and click History. A drawer slides open showing the last 100 snapshots in reverse chronological order.

Each entry shows:

Timestamp of the change
The user who made it
A brief diff of what changed

Rolling back#

Click Restore on any snapshot to revert the proxy host to that state. PosternProxy will: