AWS Security ChangesHomeSearch

AWS transfer: Document SSH client compatibility with PROXY protocol v2

Service: transfer · 2026-10-30 · Documentation low

File: transfer/latest/userguide/working-with-nlb.md

Summary

Adds a section explaining that some older SSH clients stall when PROXY protocol v2 is enabled on an NLB target group, provides a table of minimum compatible client versions, and advises using structured logging to identify clients before enabling PPv2.

Security assessment

This is operational/compatibility guidance about connection stalls caused by PROXY protocol v2, not a vulnerability or security control. It references structured logging only as a diagnostic aid, so it is security-tangential at most.

Evidence

SSH clients that wait to receive the server's SSH identification string before they send their own fail to complete the connection when PROXY protocol v2 is enabled.

Diff

diff --git a/transfer/latest/userguide/working-with-nlb.md b/transfer/latest/userguide/working-with-nlb.md
index bbc93a6..34d838b 100644
--- a//transfer/latest/userguide/working-with-nlb.md
+++ b//transfer/latest/userguide/working-with-nlb.md
@@ -7 +7 @@
-Preserve the client's source IPEnable PPv2 enforcement
+Preserve the client's source IPClient compatibilityEnable PPv2 enforcement
@@ -34,0 +35,21 @@ When you enable PPv2, the client's source IP address becomes available in the fo
+## SSH client compatibility with PROXY protocol v2
+
+After the TCP connection is established, both the client and the server send an SSH identification string as their first data. This string identifies their SSH protocol and software versions, for example `SSH-2.0-OpenSSH_10.3`. For more information, see the [SSH transport layer protocol (RFC 4253)](https://datatracker.ietf.org/doc/html/rfc4253#section-4.2). Some older SSH clients wait to receive the server's SSH identification string before they send their own. When PROXY protocol v2 is enabled on an NLB target group, the NLB doesn't deliver the server's identification string to the client until the client sends data. These clients connect and wait for the server's identification string, so they never send their own, and the connection stalls until it times out.
+
+SSH clients that wait to receive the server's SSH identification string before they send their own fail to complete the connection when PROXY protocol v2 is enabled. The following table lists common SSH clients and the minimum version of each that is known to be compatible with PROXY protocol v2. This list isn't comprehensive. If you use a client that isn't in this table, test its compatibility before you enable PROXY protocol v2.
+
+Client | Minimum version  
+---|---  
+JSch | 0.1.28  
+OpenSSH | 6.2  
+Apache MINA SSHD | 2.3.0  
+WinSCP | 5.8.1  
+Rebex SSH | 2.0.4086  
+libssh2 | 1.2.2  
+Paramiko | 1.15.1  
+Maverick Legacy | 1.7.15  
+ssh2 (Node.js) | 0.0.23  
+SSHJ | 0.19.1  
+  
+To find the SSH clients that connect to your server, enable structured logging for your server. The `client` field contains the client's identification string, for example `SSH-2.0-OpenSSH_10.3`. For more information, see [JSON structured logs for Transfer Family](./cw-structure-logs.html#json-log-entries). If a client waits for the server's SSH identification string before sending its own, or doesn't appear in this table, ask those users to upgrade before you enable PROXY protocol v2 for your NLB.
+
@@ -49 +70,5 @@ Enable the `proxy_protocol_v2.enabled` attribute on the NLB target group that po
-While the server is still set to `SftpMode=NONE`, it reads and ignores any PPv2 header. Enabling PROXY protocol v2 on the target group at this stage causes no disruption.
+While the server is set to `SftpMode=NONE`, it accepts connections with or without a PPv2 header.
+
+###### Note
+
+Some SSH clients wait to receive the server's SSH identification string before sending their own. When you enable PROXY protocol v2, these clients fail to complete the connection. Before you enable PROXY protocol v2, confirm that your users' clients send their identification string first. For details, see SSH client compatibility with PROXY protocol v2.