Elastic Load Balancing
Developer Guide (API Version 2012-06-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Enable or Disable Proxy Protocol Support

By default, when you use Transmission Control Protocol (TCP) or Secure Sockets Layer (SSL) for both front-end and back-end connections, your load balancer forwards the request to the back-end instances without modifying the request headers. If you enable Proxy Protocol, a human-readable header gets prepended to the request header with connection information such as the source IP address, destination IP address, and port numbers. The header is then sent to the back-end instance as part of the request.

Proxy Protocol is an Internet protocol used for carrying connection information from the source requesting the connection to the destination for which the connection was requested. Elastic Load Balancing uses Proxy Protocol version 1, which uses a human-readable header format.

Proxy Protocol can only be enabled on ports using either SSL or TCP protocols. You can use Proxy Protocol to capture your client’s source IP when you are using a non-HTTP protocol, or when you are using HTTPS and not terminating the SSL connection on your load balancer.

If you have a Proxy Protocol enabled proxy server in front of your load balancer, then you must not enable Proxy Protocol on your load balancer. If the Proxy Protocol is enabled on both the proxy server and the load balancer, the load balancer will add another header to the request that already has a header from the proxy server. Depending on how your back-end instance is configured, this duplication might result in errors.

The following diagrams illustrate the incorrect and correct configurations for enabling Proxy Protocol when you have a proxy server in front of your load balancer.

This section walks you through the process for enabling Proxy Protocol and then associating it with your back-end instance using either the AWS command line interface (AWS CLI) or the Query API. At present, the Elastic Load Balancing console does not support enabling Proxy Protocol.

Prerequisites for Enabling Proxy Protocol

Before you begin, be sure that you complete the following steps:

  • Create a basic load balancer by specifying either an SSL or a TCP protocol for both front-end and back-end listeners. For more information, see Get Started with Elastic Load balancing.

  • Confirm that your back-end instances can process the Proxy Protocol information.

Enable Proxy Protocol Using the AWS Command Line Interface

To enable Proxy Protocol, you need to create a policy of the type ProxyProtocolPolicyType and then set the policy to the back-end instance port.

In this walkthrough, you will create a new policy EnableProxyProtocol of the type ProxyProtocolPolicyType for a load balancer named my-test-loadbalancer, set the newly created policy to the back-end instance on port 80, and verify that the policy is enabled.

To create a policy

  1. Enter the describe-load-balancer-policy-types command to list all the policies supported by Elastic Load Balancing.

    aws elb describe-load-balancer-policy-types
  2. Elastic Load Balancing responds with the names and descriptions of the supported policy types. The following example shows a partial listing of the supported policy types.

    {
        "PolicyTypeDescriptions": [
            {
                "PolicyAttributeTypeDescriptions": [
                    {
                        "Cardinality": "ONE_OR_MORE",
                        "AttributeName": "PublicKeyPolicyName",
                        "AttributeType": "PolicyName"
                    }
                ],
                "PolicyTypeName": "BackendServerAuthenticationPolicyType",
                "Description": "Policy that controls authentication to back-end server(s) and contains one or more policies, such as an instance of a
     PublicKeyPolicyType. This policy can be associated only with back-end servers that are using HTTPS/SSL."
            },
            {
                "PolicyAttributeTypeDescriptions": [
                    {
                        "Cardinality": "ONE",
                        "AttributeName": "PublicKey",
                        "AttributeType": "String"
                    }
                ],
                "PolicyTypeName": "PublicKeyPolicyType",
                "Description": "Policy containing a list of public keys to accept when authenticating the back-end server(s). This policy cannot be a
    pplied directly to back-end servers or listeners but must be part of a BackendServerAuthenticationPolicyType."
            },
            {
                "PolicyAttributeTypeDescriptions": [
                    {
                        "Cardinality": "ONE",
                        "AttributeName": "CookieName",
                        "AttributeType": "String"
                    }
                ],
                "PolicyTypeName": "AppCookieStickinessPolicyType",
                "Description": "Stickiness policy with session lifetimes controlled by the lifetime of the application-generated cookie. This policy
    can be associated only with HTTP/HTTPS listeners."
            },
            {
                "PolicyAttributeTypeDescriptions": [
                    {
                        "Cardinality": "ZERO_OR_ONE",
                        "AttributeName": "CookieExpirationPeriod",
                        "AttributeType": "Long"
                    }
                ],
                "PolicyTypeName": "LBCookieStickinessPolicyType",
                "Description": "Stickiness policy with session lifetimes controlled by the browser (user-agent) or a specified expiration period. Thi
    s policy can be associated only with HTTP/HTTPS listeners."
            },
            {
                "PolicyAttributeTypeDescriptions": [
                    {
                        "Cardinality": "ONE",
                        "AttributeName": "ProxyProtocol",
                        "AttributeType": "Boolean"
                    }
                ],
                "PolicyTypeName": "ProxyProtocolPolicyType",
                "Description": "Policy that controls whether to include the IP address and port of the originating request for TCP messages. This pol
    icy operates on TCP/SSL listeners only"
            },
            {
               "PolicyAttributeTypeDescriptions": [
                    {
                        "Cardinality": "ZERO_OR_ONE",
                        "AttributeName": "Protocol-SSLv2",
                        "AttributeType": "Boolean"
                    }
    				{
                        ..............
                    }
    
                ],
                "PolicyTypeName": "SSLNegotiationPolicyType",
                "Description": "Listener policy that defines the ciphers and protocols that will be accepted by the load balancer. This policy can be
     associated only with HTTPS/SSL listeners."
            }
        ]
    }

    Use the policy type ProxyProtocolPolicyType to create a new policy EnableProxyProtocol.

  3. Enter the create-load-balancer-policy command to create a new policy.

    aws elb create-load-balancer-policy --load-balancer-name my-test-loadbalancer --policy-name EnableProxyProtocol  --policy-type-name ProxyProtocolPolicyType --policy-attributes AttributeName=ProxyProtocol,AttributeValue=True
    

To enable the policy

  • Enter the command set-load-balancer-policies-for backend-server to set the newly created policy to the back-end instance port.

    Note

    The set-load-balancer-policies-for-backend-server command replaces the current set of policies associated with your instance port. Every time you use this command to enable the policies, use the --policy-names option to list all the policies you want to enable.

    aws elb set-load-balancer-policies-for-backend-server --load-balancer-name my-test-loadbalancer --instance-port 80 --policy-names EnableProxyProtocol MyPolicyName2 MyPolicyName3

To verify that the Proxy Protocol is enabled

  1. Enter the describe-load-balancers command to verify that the Proxy Protocol is enabled.

    aws elb describe-load-balancers --load-balancer-name my-test-loadbalancer
  2. Elastic Load Balancing responds as in the following example.

    {
        "LoadBalancerDescriptions": [
            {
                "Subnets": [], 
                "CanonicalHostedZoneNameID": "Z3DZXE0Q79N41H", 
                "CanonicalHostedZoneName": "my-test-loadbalancer-521886987.us-east-1.elb.amazonaws.com", 
                "ListenerDescriptions": [
                    {
                        "Listener": {
                            "InstancePort": 443, 
                            "SSLCertificateId": "arn:aws:iam::55555555:server-certificate/production/myservercert", 
                            "LoadBalancerPort": 443, 
                            "Protocol": "HTTPS", 
                            "InstanceProtocol": "HTTPS"
                        }, 
                        "PolicyNames": [
                            "MySSLNegotiationPolicy"
                        ]
                    }, 
                    {
                        "Listener": {
                            "InstancePort": 80, 
                            "LoadBalancerPort": 80, 
                            "Protocol": "TCP", 
                            "InstanceProtocol": "TCP"
                        }, 
                        "PolicyNames": []
                    }
                ], 
                "HealthCheck": {
                    "HealthyThreshold": 10, 
                    "Interval": 30, 
                    "Target": "TCP:443", 
                    "Timeout": 5, 
                    "UnhealthyThreshold": 2
                }, 
                "BackendServerDescriptions": [
                    {
                        "InstancePort": 80, 
                        "PolicyNames": [
                            "EnableProxyProtocol"
                        ]
                    }
                ], 
                "Instances": [], 
                "DNSName": "my-test-loadbalancer-521886987.us-east-1.elb.amazonaws.com", 
                "SecurityGroups": [], 
                "Policies": {
                    "LBCookieStickinessPolicies": [], 
                    "AppCookieStickinessPolicies": [], 
                    "OtherPolicies": [
                        "ELBSecurityPolicy-2014-01", 
                        "MySSLNegotiationPolicy", 
                        "EnableProxyProtocol"
                    ]
                }, 
                "LoadBalancerName": "my-test-loadbalancer", 
                "CreatedTime": "2014-08-03T02:43:43.860Z", 
                "AvailabilityZones": [
                    "us-east-1c"
                ], 
                "Scheme": "internet-facing", 
                "SourceSecurityGroup": {
                    "OwnerAlias": "amazon-elb", 
                    "GroupName": "amazon-elb-sg"
                }
            }
        ]
    }

The description in the BackendServerDescriptions field confirms that the EnableProxyProtocol policy is associated with the instance port 80.

Disable the Policy

At any time you can disable the policies associated with your back-end instance and then enable them at a later time. Skip this step if you want to continue associating the Proxy Protocol policy with your back-end instance.

To disable the Proxy Protocol policy

  • Use the set-load-balancer-policies-for-backend-server command to disable the Proxy Protocol policy by not specifying the Proxy Protocol policy name with the --policy-names option.

    Note

    The set-load-balancer-policies-for-backend-server command replaces the current set of policies associated with your instance port. Every time you use this command to disable policies, use the --policy-names option to list the policy names you want to enable and omit the policy names you want to disable.

    If you do not have any other policies to enable for the instance port 80, use an empty string with --policy-names option as shown in the following example:

    Note

    The following example uses JSON syntax on a Windows operating system to specify the attributes. For information about specifying JSON syntax on your operating system, see Quoting Strings.

    aws elb set-load-balancer-policies-for-backend-server --load-balancer-name my-test-loadbalancer --instance-port 80 --policy-names "[]"

    If you want to enable policies other than the Proxy Protocol policy for the instance port 80, use --policy-names option to list the other policies.

    elb-set-lb-policies-for-backend-server my-test-loadbalancer --instance-port 80 --policy-names MyPolicyName2 MyPolicyName3

To verify that the Proxy Protocol policy is disabled

  1. Enter describe-load-balancers command to verify if the policy is disabled.

    aws elb describe-load-balancers --load-balancer-name my-test-loadbalancer
  2. Elastic Load Balancing responds as in the following example.

    {
        "LoadBalancerDescriptions": [
            {
                "Subnets": [], 
                "CanonicalHostedZoneNameID": "Z3DZXE0Q79N41H", 
                "CanonicalHostedZoneName": "my-test-loadbalancer-521886987.us-east-1a.elb.amazonaws.com", 
                "ListenerDescriptions": [
                    {
                        "Listener": {
                            "InstancePort": 443, 
                            "SSLCertificateId": "arn:aws:iam::55555555:server-certificate/production/myservercert", 
                            "LoadBalancerPort": 443, 
                            "Protocol": "HTTPS", 
                            "InstanceProtocol": "HTTPS"
                        }, 
                        "PolicyNames": [
                            "MySSLNegotiationPolicy"
                        ]
                    }, 
                    {
                        "Listener": {
                            "InstancePort": 80, 
                            "LoadBalancerPort": 80, 
                            "Protocol": "TCP", 
                            "InstanceProtocol": "TCP"
                        }, 
                        "PolicyNames": []
                    }
                ], 
                "HealthCheck": {
                    "HealthyThreshold": 10, 
                    "Interval": 30, 
                    "Target": "TCP:443", 
                    "Timeout": 5, 
                    "UnhealthyThreshold": 2
                }, 
                "BackendServerDescriptions": [], 
                "Instances": [], 
                "DNSName": "my-test-loadbalancer-521886987.us-east-1a.elb.amazonaws.com", 
                "SecurityGroups": [], 
                "Policies": {
                    "LBCookieStickinessPolicies": [], 
                    "AppCookieStickinessPolicies": [], 
                    "OtherPolicies": [
                        "ELBSecurityPolicy-2014-01", 
                        "MySSLNegotiationPolicy", 
                        "EnableProxyProtocol"
                    ]
                }, 
                "LoadBalancerName": "my-test-loadbalancer", 
                "CreatedTime": "2014-08-03T02:43:43.860Z", 
                "AvailabilityZones": [
                    "us-east-1c"
                ], 
                "Scheme": "internet-facing", 
                "SourceSecurityGroup": {
                    "OwnerAlias": "amazon-elb", 
                    "GroupName": "amazon-elb-sg"
                }
            }
        ]
    }
    

The empty BackendServerDescriptions field confirms that the instance port 80 is not associated with any policy.

Enable Proxy Protocol Using the Query API

To enable Proxy Protocol, you need to create a policy of the type ProxyProtocolPolicyType and then set the policy to the back-end instance port.

In this walkthrough, you will create a new policy EnableProxyProtocol of the type ProxyProtocolPolicyType for a load balancer named my-test-loadbalancer, set the newly-created policy to the back-end instance on port 80, and verify that the policy is enabled.

For information on making a query request, see Use Query Requests to Call Elastic Load Balancing APIs

To create a policy

  1. Call the DescribeLoadBalancerPolicyTypes action to list all the policies supported by Elastic Load Balancing.

    Your request should look similar to the following example:

    https://elasticloadbalancing.amazonaws.com/?Version=2012-06-01
    &Action=DescribeLoadBalancerPolicyTypes
    &AUTHPARAMS
  2. The response includes the names and descriptions of the supported policy types. The following example is a partial response.

    <DescribeLoadBalancerPolicyTypesResponse  xmlns="http://elasticloadbalancing.amazonaws.com/doc/2012-06-01/">
    <DescribeLoadBalancerPolicyTypesResult>
      <PolicyTypeName>SSLNegotiationPolicyType</PolicyTypeName>
           < . . . .>
       <PolicyTypeName>BackendServerAuthenticationPolicyType</PolicyTypeName>
          < . . . .>
       <PolicyTypeName>PublicKeyPolicyType</PolicyTypeName>
         < . . . .>
       <PolicyTypeName>AppCookieStickinessPolicyType</PolicyTypeName>
       < . . . .>
       <PolicyTypeName>LBCookieStickinessPolicyType</PolicyTypeName>
         < . . . .>
       <PolicyTypeName>ProxyProtocolPolicyType</PolicyTypeName>
         < . . . .>
    </DescribeLoadBalancerPolicyTypesResult>
     <ResponseMetadata>
        <RequestId>94a1d9fd-e01b-11e2-bff8-276f19bc1b97</RequestId>
      </ResponseMetadata>   
    </ DescribeLoadBalancerPolicyTypesResponse >	
    	

    Use ProxyProtocolPolicyType to create a new policy EnableProxyProtocol.

  3. Call the CreateLoadBalancerPolicy action to create a new policy EnableProxyProtocol by specifying the following parameters:

    • Load Balancer name = my-test-loadbalancer

    • Policy name = EnableProxyProtocol

    • Policy type = ProxyProtocolPolicyType

    • PolicyAttributeName = ProxyProtocol

    • PolicyAttributeValue = true

    Your request should look similar to the following example:

    https://elasticloadbalancing.amazonaws.com/?PolicyAttributes.member.1.AttributeName=ProxyProtocol
    &PolicyAttributes.member.1.AttributeValue=true
    &PolicyTypeName=ProxyProtocolPolicyType
    &LoadBalancerName=my-test-loadbalancer
    &PolicyName=EnableProxyProtocol
    &Version=2012-06-01
    &Action=CreateLoadBalancerPolicy
    &AUTHPARAMS
  4. If your request was successful, you should get a confirmation like the following example:

    <CreateLoadBalancerPolicyResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2012-06-01/">
      <CreateLoadBalancerPolicyResult/>
      <ResponseMetadata>
        <RequestId>2f5856c5-dddf-11e2-a79c-e97dcEXAMPLE</RequestId>
      </ResponseMetadata>
    </CreateLoadBalancerPolicyResponse>   

To enable the policy

  1. Call the SetLoadBalancerPoliciesForBackendServer action with the following parameters:

    Note

    The SetLoadBalancerPoliciesForBackendServer action replaces the current set of policies associated with your instance port. Every time you use this action to enable the policies, use the Policy Names parameter to list all the policies you want to enable.

    • Load Balancer name = my-test-loadbalancer

    • Back-end instance port number = 80

    • Policy names = EnableProxyProtocol

      Policy names = MyPolicyName2

      Policy names = MyPolicyName3

    Your request should look similar to the following example:

    https://elasticloadbalancing.amazonaws.com/?InstancePort=80
    &PolicyNames.member.1=EnableProxyProtocol
    &PolicyNames.member.2=MyPolicyName2
    &PolicyNames.member.3=MyPolicyName3
    &LoadBalancerName=my-test-loadbalancer
    &Version=2012-06-01
    &Action=SetLoadBalancerPoliciesForBackendServer
    &AUTHPARAMS
  2. If your request was successful, you should get a confirmation like the following example:

    <SetLoadBalancerPoliciesForBackendServerResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2012-06-01/">
      <SetLoadBalancerPoliciesForBackendServerResult/>
      <ResponseMetadata>
        <RequestId>0eb9b381-dde0-11e2-8d78-6ddbaEXAMPLE</RequestId>
      </ResponseMetadata>
    </SetLoadBalancerPoliciesForBackendServerResponse>

To verify that Proxy Protocol policy is enabled

  1. Call the DescribeLoadBalancers action with the following parameter:

    • Load Balancer name = my-test-loadbalancer

    Your request should look similar to the following example:

    https://elasticloadbalancing.amazonaws.com/?LoadBalancerNames.member.1=my-test-loadbalancer
    &Version=2012-06-01
    &Action=DescribeLoadBalancers
    &AUTHPARAMS
  2. The response includes details about your load balancer. The information you get should be similar to the following example:

    <DescribeLoadBalancersResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2012-06-01/">
      <DescribeLoadBalancersResult>
        <LoadBalancerDescriptions>
          <member>
            <SecurityGroups/>
            <CreatedTime>2013-01-24T20:51:35.710Z</CreatedTime>
            <LoadBalancerName>my-test-loadbalancer</LoadBalancerName>
            <HealthCheck>
              . . . .
            </HealthCheck>
            <ListenerDescriptions>
             . . . .
            </ListenerDescriptions>
            <Instances>
              . . . .
            </Instances>
            <Policies>
              <AppCookieStickinessPolicies/>
              <OtherPolicies>
                <member>AWSConsole-SSLNegotiationPolicy-my-test-loadbalancer</member>
                <member>EnableProxyProtocol</member>
              </OtherPolicies>
              <LBCookieStickinessPolicies/>
            </Policies>
              . . . .
              . . . .           
            <BackendServerDescriptions>
              <member>
                <PolicyNames>
                  <member>EnableProxyProtocol</member>
                </PolicyNames>
                <InstancePort>80</InstancePort>
              </member>
            </BackendServerDescriptions>
            <Subnets/>
          </member>
        </LoadBalancerDescriptions>
      </DescribeLoadBalancersResult>
      <ResponseMetadata>
        <RequestId>d0463294-e331-11e2-9776-c3fEXAMPLE</RequestId>
      </ResponseMetadata>
    </DescribeLoadBalancersResponse>
    			

The descriptions in the BackendServerDescriptions field confirms that the policy is associated with the instance port.

Disable the Policy

At any time you can disable the policies associated with your backend instance and then enable them at a later time. Skip this step if you want to continue associating the Proxy Protocol policy with your back-end instance.

Use the SetLoadBalancerPoliciesForBackendServer action to disable the Proxy Protocol policy by not specifying the Proxy Protocol policy name with the Policy Names parameter.

Note

The SetLoadBalancerPoliciesForBackendServer action replaces the current set of policies associated with your instance port. Every time you use this action to disable policies, use the Policy Names parameter to list the policy names you want to enable and omit the policy names you want to disable.

To disable the Proxy Protocol policy

  1. Call the SetLoadBalancerPoliciesForBackendServer action by specifying the following parameters. If you do not have any other policies to enable for the instance port 80, use an empty string with the Policy Names parameter.

    • Load Balancer name = my-test-loadbalancer

    • Back-end instance port number = 80

    • Policy Names =

    Your request should look similar to the following example:

    https://elasticloadbalancing.amazonaws.com/?InstancePort=80
    &PolicyNames=
    &LoadBalancerName=my-test-loadbalancer
    &Version=2012-06-01
    &Action=SetLoadBalancerPoliciesForBackendServer
    &AUTHPARAMS

    If you want to enable policies other than the Proxy Protocol policy for the instance port 80, list those policies using the Policy Names parameter, as in the following example:

    • Load Balancer name = my-test-loadbalancer

    • Back-end instance port number = 80

    • Policy names = MyPolicyName2

      Policy names = MyPolicyName3

    Your request should look similar to the following example:

    https://elasticloadbalancing.amazonaws.com/?InstancePort=80
    &PolicyNames.member.1=MyPolicyName2
    &PolicyNames.member.2=MyPolicyName3
    &LoadBalancerName=my-test-loadbalancer
    &Version=2012-06-01
    &Action=SetLoadBalancerPoliciesForBackendServer
    &AUTHPARAMS
  2. If your request was successful, you should get a confirmation like the following example:

    <SetLoadBalancerPoliciesForBackendServerResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2012-06-01/">
      <SetLoadBalancerPoliciesForBackendServerResult/>
      <ResponseMetadata>
        <RequestId>0eb9b381-dde0-11e2-8d78-6ddbaEXAMPLE</RequestId>
      </ResponseMetadata>
    </SetLoadBalancerPoliciesForBackendServerResponse>

To verify that the Proxy Protocol policy is disabled

  1. Call the DescribeLoadBalancers action with the following parameter:

    • Load Balancer name = my-test-loadbalancer

    Your request should look similar to the following example:

    https://elasticloadbalancing.amazonaws.com/?LoadBalancerNames.member.1=my-test-loadbalancer
    &Version=2012-06-01
    &Action=DescribeLoadBalancers
    &AUTHPARAMS
  2. The response includes details about the load balancer. The information you get should be similar to the following example:

    <DescribeLoadBalancersResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2012-06-01/">
      <DescribeLoadBalancersResult>
        <LoadBalancerDescriptions>
          <member>
            <SecurityGroups/>
            <CreatedTime>2013-01-24T20:51:35.710Z</CreatedTime>
            <LoadBalancerName>my-test-loadbalancer</LoadBalancerName>
            <HealthCheck>
              . . . .
            </HealthCheck>
            <ListenerDescriptions>
             . . . .
            </ListenerDescriptions>
            <Instances>
              . . . .
            </Instances>
            <Policies>
              <AppCookieStickinessPolicies/>
              <OtherPolicies>
                <member>AWSConsole-SSLNegotiationPolicy-my-test-loadbalancer</member>
                <member>EnableProxyProtocol</member>
              </OtherPolicies>
              <LBCookieStickinessPolicies/>
            </Policies>
              . . . .
              . . . . 
            <BackendServerDescriptions/>
            <Subnets/>
          </member>
        </LoadBalancerDescriptions>
      </DescribeLoadBalancersResult>
      <ResponseMetadata>
        <RequestId>d0463294-e331-11e2-9776-c3fEXAMPLE</RequestId>
      </ResponseMetadata>
    </DescribeLoadBalancersResponse>
    			

The empty BackendServerDescriptions field confirms that the instance port is not associated with any policy.