Question 1

How to configure Pomerium to require client certificates from a trusted private CA?

Accepted Answer

Use the downstream mTLS CA option to specify a trusted CA. Pomerium will automatically add a deny rule for missing or invalid client certificates on all routes. Example configuration:
```yaml
downstream_mtls:
  ca_file: /path/to/trusted/CA.pem
```
No route-level Certificate Matcher is required for basic enforcement; it is only needed for additional per-route restrictions.

Question 2

How to allow access only from local (private) IP addresses in Pomerium?

Accepted Answer

Use the source_ip policy criterion with the RFC 1918 and RFC 4193 private address blocks: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, and fd00::/8. To avoid repeating these lists in multiple routes, you can use YAML anchors. Example:

```yaml
routes:
 - from: https://route-a.example.com
   to: https://backend-a.internal
   policy: &allow_local_ip
     allow:
       or:
         - source_ip: 10.0.0.0/8
         - source_ip: 172.16.0.0/12
         - source_ip: 192.168.0.0/16
         - source_ip: fd00::/8
 - from: https://route-b.example.com
   to: https://backend-b.internal
   policy: *allow_local_ip
```
If you use a template engine (e.g., Jinja2), you can manage the CIDR blocks centrally. There is no built-in `local_source_ip` shortcut at this time.

Question 3

How to route Tailscale or Headscale traffic through Pomerium with custom HTTP Upgrade header?

Accepted Answer

As of the merged PR #6216, Pomerium now supports a policy-level `allow_upgrades` option to permit custom HTTP Upgrade protocols. For example, to allow Tailscale traffic, add to your route:

allow_upgrades:
  - "tailscale-control-protocol"

This configuration tells Envoy to forward the custom upgrade header, eliminating the 'upgrade_failed' error. Previously, the only workaround was to use a separate proxy for Tailscale connections.

Question 4

Why does Envoy reject HTTP/3 listener on macOS with 'Listening on UDP when concurrency is > 1 without the SO_REUSEPORT socket option'?

Accepted Answer

This error occurs because SO_REUSEPORT is disabled on macOS for all listeners by default (due to a known issue #5066), but QUIC/UDP requires it when concurrency > 1 to ensure stable packet delivery. The immediate workaround is to set `concurrency: 1` in your Pomerium configuration file (e.g., `pomerium.yaml`), which forces a single worker process. Alternatively, if you have advanced Envoy configuration access, explicitly enable the `reuse_port` option on the UDP listener. Example config snippet:
```yaml
concurrency: 1
```
Restart Pomerium after making this change.

Question 5

Why is Pomerium using 200% CPU on macOS after upgrading?

Accepted Answer

A regression in envoy's kqueue handling (since commit #6183) causes full-core CPU consumption on macOS. Apply the fix by updating to the patched envoy-custom version: `go get github.com/pomerium/envoy-custom@837dd381d8a1735e5b7b1684dbfc4695e8168440` then `make build`. This rebuilds Pomerium with the corrected envoy binary. Alternatively, downgrade to a version prior to the regression (before commit 9931410c).

pomerium

Core Features

What It Can't Do

Use Cases

Tags

Getting Started

Similar Projects