PROXY protocol

note

Users of Teleport Cloud don't need to manage PROXY protocol setting manually. It's set to on automatically and can't be changed, since cloud Proxy/Auth services managed by Teleport run behind a L4 load balancer with PROXY protocol configured.

What is PROXY protocol

The PROXY protocol is a prefix added to the TCP connection containing information about the client IP. It is most commonly used when networking setup includes a Layer 4 (L4) load balancer between the user and the endpoint service, like Teleport Proxy/Auth. L4 load balancers, by design, do not retain the original client's IP address and port when forwarding the connection and PROXY protocol allows to overcome this problem by adding the client's original IP address and port before the actual TCP stream.

An example of the PROXYv1 protocol header:

PROXY TCP4 127.0.0.1 127.0.0.2 12345 42\r\n

Security

Misconfiguration of the PROXY protocol behavior can lead to security problems. Since the PROXY protocol lacks built-in authentication, a malicious attacker could send falsified custom PROXY protocol headers to spoof the their IP address. To prevent this, you must explicitly configure PROXY protocol settings according to your network setup - if you don't run Teleport behind a L4 load balancer, that send PROXY headers, you must disable PROXY protocol support on Teleport.

Configuring PROXY protocol for Teleport

Teleport Proxy/Auth relies on PROXY protocol to get the client's real IP address when behind a L4 load balancer. Having reliable client IP information is important from the security standpoint, because such features as audit logging and IP pinning depend on it and if PROXY protocol is not configured correctly, these features will be compromised.

Usage of PROXY protocol in Teleport is controlled by proxy_protocol setting in the configuration for both proxy_service and auth_service sections separately.

By default in a new installation of Teleport proxy_protocol is unspecified, users can manually set proxy_protocol to on or off:

• on: PROXY Protocol is enabled and mandatory. If a PROXY protocol header is received, Teleport will parse the header and extract the client's IP address and port. If the header isn't present, it will reject the connection with an error.
• off: PROXY Protocol is disabled and forbidden. Any connection with a PROXY protocol header is automatically rejected.

Users are encouraged to explicitly set their proxy_protocol setting to on or off mode depending on the network setup. Default unspecified value mode is not suitable for production, it is only suitable for test environments. If proxy_protocol is unspecified Teleport does not require PROXY header for the connection, but will parse it if present, client's source IP address will be replaced with the one from PROXY header and this address will appear in the audit events. Incoming connections with PROXY header will also be marked by setting source port to 0 and this will be visible in the audit events as well.

warning

IP pinning will not work if proxy_protocol setting wasn't explicitly set in the config. Connections that are marked with source port = 0 will be rejected during IP pinning checks.

Main rule for configuring proxy_protocol setting - If Teleport is running behind a L4 load balancer, that is set to send PROXY protocol headers, you should set proxy_protocol: on.

proxy_service:
  proxy_protocol: on

Otherwise you should set proxy_protocol: off

proxy_service:
  proxy_protocol: off

You should make sure that Teleport is only accessible through the load balancer if you run it with proxy_protocol: on, so malicious attackers can't spoof their IP address or bypass IP Pinning restrictions by connecting directly and sending a custom PROXY header. Teleport only allows one PROXY protocol header for an incoming connection - it will reject requests that include multiple PROXY lines to prevent attacks when proxy_protocol: on.

PROXY protocol behavior is controlled separately for Auth service and Proxy service. So you should ensure both have the correct setting. If there's a PROXY-enabled L4 load balancer between your Proxy and Auth services, you should set proxy_protocol: on on the Auth, otherwise set it to off.

You can also have Teleport Proxies have different PROXY protocol settings, if you run some of them behind a load balancer and some not, for example if you have dedicated Proxies for private and public networks.

Running Teleport behind a L4 load balancer that doesn't send PROXY protocol headers will lead to all incoming connections seemingly coming from the same IP address from Teleport's point of view, making the audit trail less useful and the IP pinning feature not helpful.