Working with Network Load Balancers - AWS Transfer Family
Preserve the client's source IPClient compatibilityEnable PPv2 enforcement
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Working with Network Load Balancers

Whether you should place a Network Load Balancer (NLB) in front of an AWS Transfer Family server depends on the protocol that your server uses. Review the following guidance before you add an NLB to your architecture.

  • FTP and FTPS – We recommend against placing an NLB in front of the server. An NLB in this path increases costs and reduces the number of simultaneous connections that the server accepts. If your FTP or FTPS implementation requires an NLB, see Avoid placing NLBs and NATs in front of AWS Transfer Family servers for configuration recommendations.

  • SFTP – An NLB is supported for servers that use a VPC-hosted endpoint, though we recommend avoiding an NLB where possible. Where an NLB is required, you can preserve the client's source IP address with PROXY protocol v2 (PPv2).

A common reason to place an NLB in front of an AWS Transfer Family server is to offer a custom listener port. AWS Transfer Family already offers several ports, so review AWS Transfer Family endpoint type matrix and Create an SFTP-enabled server for the supported ports before you add an NLB to expose a custom listener port.

Preserving the client's source IP for SFTP with PROXY protocol v2

This feature applies to SFTP servers that use a VPC-hosted endpoint. When an NLB is in the path between your client and your SFTP server, AWS Transfer Family sees the private IP address of the NLB instead of the client's source IP address. PROXY protocol v2 (PPv2) solves this problem. The NLB adds a PPv2 header that carries the client's source IP address, and AWS Transfer Family reads that header.

When you enable PPv2, the client's source IP address becomes available in the following places:

  • Authentication requests that AWS Transfer Family sends to your custom identity provider. You can then write IP-based access policies.

  • Log entries in Amazon CloudWatch Logs.

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 SSH transport layer protocol (RFC 4253) on the IETF Datatracker website.

Some older SSH clients wait to receive the server's SSH identification string before they send their own. Clients that still support SSH protocol version 1 do this so that they can choose a protocol version based on the server's identification string. 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.

The following table lists common SSH clients and the minimum version of each that is known to be compatible with PROXY protocol v2 in its default configuration. This list isn't comprehensive. An older version might also work if you configure it to use only SSH protocol version 2. If you use a client that isn't in this table, test its compatibility before you enable PROXY protocol v2.

Client

Minimum version

WinSCP

5.8.1

OpenSSH

6.2

JSch

0.1.34

Paramiko

All versions

SSH.NET

2020.0.0

FileZilla

3.14.0

ssh2 (Node.js)

All versions

Apache MINA SSHD

All versions

libssh2

0.6

SSHJ

All versions

Cyberduck

2.2

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. 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.

Enable PROXY protocol v2 enforcement on an existing server

The SftpMode member of ProxyConfig controls how your server handles the PPv2 header. It has exactly two values: NONE (the default) and PROXY_PROTOCOL_V2_ENFORCED. For more information, see ProtocolDetails in the AWS Transfer Family API Reference.

Important

With PROXY_PROTOCOL_V2_ENFORCED, you must restrict the server's VPC endpoint security group to allow inbound traffic only through the trusted NLB. Because the server trusts the source IP address in the PPv2 header, this prevents a client from bypassing the NLB and presenting a spoofed source IP address.

Complete the following three steps in order to enable enforcement without refusing any connections. This order keeps the migration free of downtime.

Step 1: Enable PROXY protocol v2 on the NLB target group

Enable the proxy_protocol_v2.enabled attribute on the NLB target group that points at your server's VPC endpoint. This attribute tells the NLB to prepend a PPv2 header to each connection. For instructions, see Proxy protocol for your Network Load Balancer in the Elastic Load Balancing User Guide.

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.

Step 2: Verify that the header arrives on every connection

Before you enforce PPv2, confirm that the server receives a PPv2 header on every connection. Inspect your server logs for the CONNECTED activity type. In structured (JSON) logs in Amazon CloudWatch Logs, check the proxy-protocol-v2-header field for the value ignored. In legacy logs, check the ProxyProtocolV2Header field for the same value.

The field has the following semantics:

  • The field is absent when the connection included no PPv2 header.

  • The value is ignored when the connection included a PPv2 header while SftpMode is NONE.

  • The value is applied when the connection included a PPv2 header and the server honored it under PROXY_PROTOCOL_V2_ENFORCED.

Keep checking the logs until every CONNECTED entry carries the field with the value ignored. An absent field means that some path still reaches the server without a PPv2 header. If you enforce while any path is missing the header, the server refuses those connections. For more information about these log fields, see JSON structured logs for Transfer Family and Legacy logs for Transfer Family.

Step 3: Enforce PROXY protocol v2

Update the server so that the SftpMode member of ProxyConfig is PROXY_PROTOCOL_V2_ENFORCED. The server then requires a valid PPv2 header on every incoming SFTP connection. The server refuses connections that arrive without a valid PPv2 header and logs an error to Amazon CloudWatch Logs. To roll back, set SftpMode to NONE.

Console

On the Server details page, choose Edit next to Additional details, and then turn on the PROXY protocol configuration option. For the full edit-server procedure, see Edit server details.

AWS CLI

Run the following command to enforce PROXY protocol v2 on your server.

aws transfer update-server --server-id your-server-id --protocol-details ProxyConfig={SftpMode=PROXY_PROTOCOL_V2_ENFORCED}

If successful, the command returns the following code and updates your server.

{
    "ServerId": "your-server-id"
}