- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
Users of Teleport Cloud don't need to manage PROXY protocol setting manually. It's set to
and can't be changed, since cloud Proxy/Auth services managed by Teleport run behind a L4 load balancer with PROXY protocol configured.
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
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.
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
auth_service sections separately.
By default in a new installation of Teleport
proxy_protocol is unspecified, users can manually set
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
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.
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_service: proxy_protocol: on
Otherwise you should set
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 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
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.