Skip to main content
Version: vNext (upcoming release)

To

Summary​

To is the destination(s) of a proxied request. It can be an internal resource, or an external resource.

How to configure​

YAML/JSON settingTypeUsageSchemes
toURLoptionalhttp, https, h2c, tcp, udp

Examples​

- from: https://example.com
  to: http://verify

- from: https://example.com
  to: https://192.1.20.12:8080

- from: https://example.com
  to: http://neverssl.com

- from: https://example.com
  to: https://verify.pomerium.com/anything/

Target multiple upstream resources​

Multiple upstream resources can be targeted by using a list instead of a single URL:

- from: https://example.com
  to:
    - https://a.example.com
    - https://b.example.com

Set load balancing weight​

A load balancing weight may be associated with a particular upstream by appending ,[weight] to the URL. The exact behavior depends on your lb_policy setting. See Load Balancing for example configurations.

- from: https://example.com
  to: ['http://a', 'http://b']

- from: https://example.com
  to: ['http://a,10', 'http://b,20']

HTTP/2 cleartext​

When Pomerium connects to an https upstream, it will negotiate either HTTP/1.1 or HTTP/2 using ALPN (as part of the TLS handshake).

To configure Pomerium to make requests to an upstream service using HTTP/2 without TLS (that is, in cleartext), use the special h2c:// scheme:

- from: https://example.com
  to: h2c://localhost:9090
info

The HTTP/2 specification refers to this case as having "prior knowledge" that a server supports HTTP/2.

One use case is connecting to an insecure gRPC server. As gRPC requires HTTP/2, a client has "prior knowledge" that the server supports HTTP/2.

TCP Routes​

You can configure Pomerium to handle a TCP route in one of two different ways.

If you specify a to URL with the tcp:// scheme, Pomerium will proxy the raw TCP connection to the upstream service:

- from: tcp+https://tcp.example.com:3001
  to: tcp://localhost:3001

If you specify a to URL with the scheme http:// or https://, Pomerium will instead proxy an HTTP CONNECT request to the upstream service:

- from: tcp+https://tcp.example.com:3001
  to: http://second-proxy.tcp.example.com:3002

This allows you to place Pomerium in front of another HTTP-to-TCP proxy.

If you specify a list of multiple to URLs in one route, you may not include both tcp:// and non-tcp:// URLs.

UDP Routes​

Starting in v0.29, you can configure Pomerium to handle a UDP route in one of two different ways.

If you specify a to URL with the udp:// scheme, Pomerium will proxy the raw UDP connection to the upstream service:

- from: udp+https://udp.example.com:3001
  to: udp://localhost:3001

If you specify a to URL with the scheme http:// or https://, Pomerium will instead proxy an HTTP CONNECT-UDP request to the upstream service:

- from: udp+https://udp.example.com:3001
  to: https://second-proxy.udp.example.com:3002

This allows you to place Pomerium in front of another HTTP-to-UDP proxy.

If you specify a list of multiple to URLs in one route, you may not include both udp:// and non-udp:// URLs.

note

See Routing - Route matching order for more information on how Pomerium processes and matches routes.

warning

Be careful with trailing slash.

With rule:

- from: https://verify.corp.example.com
  to: https://verify.pomerium.com/anything

Requests to https://verify.corp.example.com will be forwarded to https://verify.pomerium.com/anything, while requests to https://verify.corp.example.com/foo will be forwarded to https://verify.pomerium.com/anythingfoo.To make the request forwarded to https://httbin.org/anything/foo, you can use double slashes in your request https://httbin.corp.example.com//foo.

While the rule:

- from: https://verify.corp.example.com
  to: https://verify.pomerium.com/anything/

All requests to https://verify.corp.example.com/* will be forwarded to https://verify.pomerium.com/anything/*. That means accessing to https://verify.corp.example.com will be forwarded to https://verify.pomerium.com/anything/. That said, if your application does not handle trailing slash, the request will end up with 404 not found.

Either redirect or to must be set.