Elastic Load Balancing
Developer Guide (API Version 2012-06-01)
« 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.Did this page help you?  Yes | No |  Tell us about it...

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 Elastic Load Balancing command line interface (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:

Enable Proxy Protocol Using the 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 command elb-describe-lb-policies to list all the policies supported by Elastic Load Balancing.

    elb-describe-lb-policy-types  --headers
  2. Elastic Load Balancing responds with the names and descriptions of the supported policy types.

    POLICY_TYPE  NAME                                          DESCRIPTION
    POLICY_TYPE  PublicKeyPolicyType                              ...                  
    POLICY_TYPE  AppCookieStickinessPolicyType                    ...         
    POLICY_TYPE  LBCookieStickinessPolicyType                     ...         
    POLICY_TYPE  SSLNegotiationPolicyType                         ...            
    POLICY_TYPE  BackendServerAuthenticationPolicyType            ... 
    POLICY_TYPE  ProxyProtocolPolicyType                          ...  			    	

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

  3. Enter the elb-create-lb-policy command to create a new policy.

    elb-create-lb-policy my-test-loadbalancer --policy-name EnableProxyProtocol --policy-type ProxyProtocolPolicyType  --attribute "name=ProxyProtocol, value=true"  
    
  4. Elastic Load Balancing responds as in the following example.

       OK-Creating LoadBalancer Policy

To enable the policy

  1. Enter the command elb-set-lb-policies-for-backend-server to set the newly created policy to the back-end instance port.

    Note

    The elb-set-lb-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.

    elb-set-lb-policies-for-backend-server my-test-loadbalancer --instance-port 80 --policy-names EnableProxyProtocol, MyPolicyName2, MyPolicyName3
  2. Elastic Load Balancing responds as in the following example.

    OK-Setting Policies

To verify that the Proxy Protocol is enabled

  1. Enter the elb-describe-lbs command to verify that the Proxy Protocol is enabled.

    elb-describe-lbs my-test-loadbalancer --headers --show-long
  2. Elastic Load Balancing responds as in the following example.

    LOAD_BALANCER,NAME,DNS_NAME,CANONICAL_HOSTED_ZONE_NAME,CANONICAL_HOSTED_ZONE_NAM
    E_ID,HEALTH_CHECK,AVAILABILITY_ZONES,SUBNETS,VPC_ID,INSTANCE_ID,LISTENER_DESCRIP
    TIONS,BACKEND_SERVER_DESCRIPTIONS,OTHER_POLICIES,SOURCE_SECURITY_GROUP,SECURITY_
    GROUPS,CREATED_TIME,SCHEME
    LOAD_BALANCER,my-test-loadbalancer,my-test-loadbalancer-1086370712.us-east-1.elb
    .amazonaws.com,my-test-loadbalancer-1086370712.us-east-1.elb.amazonaws.com,Z3DZX
    E0Q79N41H,"{interval=30,target=HTTP:80/install.php,timeout=5,healthy-threshold=1
    0,unhealthy-threshold=2}",us-east-1e,(nil),(nil),"i-48bb5d38, i-78bc5a08, i-98e2
    04e8, i-ccbb5dbc","{protocol=HTTP,lb-port=80,instance-protocol=HTTP,instance-por
    t=80,policies=},{protocol=HTTPS,lb-port=443,instance-protocol=HTTP,instance-port
    =80,cert-id=arn:aws:iam::803981987763:server-certificate/scert,policies=AWSConsole-SSLNegotiationPolicy-my-test-loadbalancer}","{instance-port=80,policies=Enabl
    eProxyProtocol}","AWSConsole-SSLNegotiationPolicy-my-test-loadbalancer, EnablePr
    oxyProtocol","{owner-alias=amazon-elb,group-name=amazon-elb-sg}",(nil),2013-01-2
    4T20:51:35.710Z,internet-facing

The description {instance-port=80,policies=EnableProxyProtocol} in the OTHER_POLICIES 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 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.

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

To disable the Proxy Protocol policy

  1. Enter the command elb-set-lb-policies-for-backend-server to disable the Proxy Protocol policy.

    Note

    The elb-set-lb-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:

    elb-set-lb-policies-for-backend-server 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
  2. Elastic Load Balancing responds as in the following example.

    OK-Setting Policies

To verify that the Proxy Protocol policy is disabled

  1. Enter elb-describe-lbs command to verify if the policy is disabled.

    elb-describe-lbs my-test-loadbalancer --headers --show-long
  2. Elastic Load Balancing responds as in the following example.

    LOAD_BALANCER,NAME,DNS_NAME,CANONICAL_HOSTED_ZONE_NAME,CANONICAL_HOSTED_ZONE_NAM
    E_ID,HEALTH_CHECK,AVAILABILITY_ZONES,SUBNETS,VPC_ID,INSTANCE_ID,LISTENER_DESCRIP
    TIONS,BACKEND_SERVER_DESCRIPTIONS,OTHER_POLICIES,SOURCE_SECURITY_GROUP,SECURITY_
    GROUPS,CREATED_TIME,SCHEME
    LOAD_BALANCER,my-test-loadbalancer,my-test-loadbalancer-1086370712.us-east-1.elb
    .amazonaws.com,my-test-loadbalancer-1086370712.us-east-1.elb.amazonaws.com,Z3DZX
    E0Q79N41H,"{interval=30,target=HTTP:80/install.php,timeout=5,healthy-threshold=1
    0,unhealthy-threshold=2}",us-east-1e,(nil),(nil),"i-48bb5d38, i-78bc5a08, i-98e2
    04e8, i-ccbb5dbc","{protocol=HTTP,lb-port=80,instance-protocol=HTTP,instance-por
    t=80,policies=},{protocol=HTTPS,lb-port=443,instance-protocol=HTTP,instance-port
    =80,cert-id=arn:aws:iam::803981987763:server-certificate/scert,policies=AWSConso
    le-SSLNegotiationPolicy-my-test-loadbalancer}",(nil),"AWSConsole-SSLNegotiationP
    olicy-my-test-loadbalancer, EnableProxyProtocol","{owner-alias=amazon-elb,group-
    name=amazon-elb-sg}",(nil),2013-01-24T20:51:35.710Z,internet-facing

The (nil) in the OTHER_POLICIES field indicates that EnableProxyProtocol is not associated with any instance port.

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://elasticloadbalanc
    ing.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.