Product Documentation
ADC
14.1 - Current Release 13.1 13.0 12.1
View PDF

Proxy protocol

December 29, 2023
Contributed by: 
C S

Proxy protocol safely transports client details from client to server across NetScaler appliances. The appliance adds a proxy protocol header with client details and forwards it to the back-end server. Following are some of the usage scenarios for proxy protocol in a NetScaler appliance.

  • Learning original client IP address
  • Selecting a language for a website
  • Block listing selected IP addresses
  • Logging and collecting statistics.

Following are the three modes of operation:

  • Insert. NetScaler inserts the client details and sends it to the back-end server.
  • Forward. NetScaler forwards the client details to the back-end server. Starting from NetScaler 14.1-12.x release, along with the client details, NetScaler forwards the TLV (Type Length Value) information sent in proxy protocol V2 to back-end servers if the Proxy Protocol feature is enabled on the virtual server and service.
  • Stripped. NetScaler stores the client details for log purpose. Also, if the proxy protocol is not supported on the back-end server, sends the client details to the server by using the rewrite policy configuration

The following table provides you information on the status of LB virtual server and service in different proxy protocol modes:

Proxy Protocol Mode LB virtual server Service
Insert Disabled Enabled
Forward Enabled Enabled
Stripped Enabled Disabled

Limitations

The proxy protocol is not supported for the TCP Fast Open (TFO) and MultiPath TCP features. The feature is supported only for services for which the NetScaler appliance does TCP connection termination. It is not support for other services, for example, “ANY”.

How proxy protocol works in a NetScaler appliance

The following flow diagrams show how you can configure the proxy protocol across NetScaler appliances for Insert, Forwards, and Stripped operation:

Insert operation

Insert operation

The component interact is as follows:

  • At the NetScaler instance, you must enable proxy protocol in the net profile and bind it to the service.
  • In the Insert operation, NetScaler adds a proxy header with client connection details and forwards it to the back-end server.
  • On the sending side, the appliance decides the proxy protocol version based on CLI configuration.

Forward operation

Forward operation

The component interact is as follows:

  • A client sends a request along with the proxy header to the NetScaler. The appliance dynamically identifies the version.
  • In NetScaler, it is a Forward operation. The proxy protocol is enabled on the load balancing virtual server or content switching virtual server and enabled on the service. The appliance receives the proxy header along with the TLV in Proxy Protocol V2 and forwards the header and TLV to the back-end server.
  • If the proxy header details are in invalid format, the appliance resets the connection.
  • On the sending side, the appliance decides the proxy protocol version based on CLI configuration.

Stripped operation

Stripped operation

The component interact is as follows:

  • A client sends a request along with a proxy header to the NetScaler appliance.
  • In the NetScaler appliance, if it is a Stripped operation, the appliance forwards the client information obtained from the proxy protocol and inserts it into the HTTP header using rewrite policy expressions.
  • The client details such as source IP address, destination IP address, source port, and destination port are added in an HTTP header using rewrite policy expressions. The rewrite policy evaluates the expression and if “true,” the corresponding rewrite policy action is triggered. And the client details are forwarded to the back-end server in an HTTP header.
  • If the proxy header details are in invalid format, the appliance resets the connection.

Proxy protocol version formats

The Proxy protocol version is available as two formats. The appliance decides to use a format based on the incoming data length. For detailed information, see Proxy Protocol RFP.

  1. Proxy protocol version-1 format

    PROXY TCP4/TCP6/UNKNOWN <SRC IP> <DST IP> <SRC PORT> <DST PORT>

    • PROXY -> Unique string format for Proxy header version -1.
    • Support protocols TCP over IPv4 and TCP over IPv6. For the remaining protocols, this is UNKNOWN.
    • SRC IP – Source IP (Original Client IP) address of a packet.
    • DST IP – Destination IP address of a packet.
    • SRC port – Source port of a packet.
    • DST port – Destination port of a packet.

  2. Proxy protocol version-2 format

    0D 0A 0D 0A 00 0D 0A 51 55 49 54 0A <13th byte> <14th byte> <15-16th byte> <17th byte onwards>

    • D 0A 0D 0A 00 0D 0A 51 55 49 54 0A -> Unique binary string for Proxy header version -2.
    • Support protocols TCP over IPv4 and TCP over IPv6. For the remaining protocols, this is UNKNOWN.
    • Thirteenth byte – protocol version and command.
    • Fourteenth byte – address and protocol family.
    • 15-16th byte – Address length in network order.
    • Seventeenth byte onwards – Addresses info present in network order- src IP, dst IP, src port, dst port.

Responder policy infrastructure expression support

The proxy protocol supports the following responder policy infrastructure expressions for virtual servers of type TCP and HTTP:

  1. CLIENT.PROXY.SRCIP_STR
  2. CLIENT.PROXY.DSTIP_STR
  3. CLIENT.PROXY.SRCPORT
  4. CLIENT.PROXY.DSTPORT
  5. CLIENT.PROXY.ETHERTYPE

Note

NetScaler supports responder policy infrastructure expression for the proxy protocol on a virtual server of type TCP from NetScaler release 13.1-48.x onwards.

Configure Proxy protocol in NetScaler appliance

Complete the following steps to configure the Proxy protocol in your NetScaler appliance.

  1. Enable proxy protocol as global.
  2. Configure proxy protocol for Insert operation.
  3. Configure proxy protocol for Forward operation.
  4. Configure proxy protocol for Strip operation.

Enable the proxy protocol as global

At the command prompt, type the following:

set ns param –proxyProtocol ENABLED

Configure proxy protocol for Insert operation

To configure the proxy protocol for Insert operation, you must disable the protocol on the load balancing virtual server and enable the protocol on the service.

Add net profile with Proxy protocol disabled for load balancing virtual server

At the command prompt, type the following:

add netprofile <name> -proxyProtocol ENABLED/DISABLED> -proxyprotocoltxversion <V1/V2>

Example:

Add netprofile proxyprofile-1 –proxyProtocol DISABLED –proxyprotocoltxversion V1

Note:

If you disable proxy protocol on your appliance, you need not set the protocol version parameter.

Add net profile with a proxy protocol enabled for service

At the command prompt, type the following:

add netprofile <name> -proxyProtocol ENABLED/DISABLED> -proxyprotocoltxversion <V1/V2>

Example:

add netprofile proxyprofile-2 –proxyProtocol ENABLED –proxyprotocoltxversion V1

Add load balancing virtual server for NetScaler appliance in the proxy layer

At the command prompt, type the following:

add lb vserver <name>@ <serviceType> [(<IPAddress>@ <port>)]

Example:

add lb vserver lbvserver-1 http 1.1.1.1 80

Add HTTP service for NetScaler appliance in the proxy layer

At the command prompt, type the following:

add service <name>@ (<IP>@ | <serverName>@) <serviceType> <port>

Example:

Add service http-service-1 2.2.2.1 http 80

Set net profile with load balancing virtual server in NetScaler appliance

At the command prompt, type the following:

set lb vserver <vserver name> -netprofile <name>

Example:

set lb vserver lbvserver-1 –netprofile proxyProfile-1

Set net profile with HTTP service in NetScaler appliance

At the command prompt, type the following:

set service <service name> –netprofile <name>

Example:

set service http-service-1 –netprofile proxyProfile-2

Bind the load balancing virtual server to service

At the command prompt, type the following:

bind lb vserver <vserver name> <service name>

Example:

bind lb vserver lbvserver-1 http-service-1

Configure proxy protocol for forward operation

To configure the proxy protocol for Forward operation for the next NetScaler instance in the proxy layer, you must enable the protocol and bind to the virtual server or service.

Note:

The net profile created for load balancing virtual server can also be used for service .

Add net profile with proxy protocol enabled for load balancing virtual server

At the command prompt, type the following:

add netprofile <name> -proxyProtocol ENABLED/DISABLED> -proxyprotocoltxversion <V1/V2>

Example:

add netprofile proxyprofile-3 –proxyProtocol ENABLED –proxyprotocoltxversion V1

Add net profile with proxy protocol enabled for service

At the command prompt, type the following:

add netprofile <name> -proxyProtocol ENABLED/DISABLED> -proxyprotocoltxversion <V1/V2>

Example:

add netprofile proxyprofile-4 –proxyProtocol ENABLED –proxyprotocoltxversion V1

Add load balancing virtual server for NetScaler appliance in the proxy layer

At the command prompt, type the following:

add lb vserver <name>@ <serviceType> [(<IPAddress>@ <port>)]

Example:

add lb vserver lbvserver-2 http 2.2.2.2 80

Add HTTP service for NetScaler appliance in the proxy layer

At the command prompt, type the following:

add service <name>@ (<IP>@ | <serverName>@) <serviceType> <port>

Example:

Add service http-service-2 3.3.3.1 http 80

Set net profile with load balancing virtual server in NetScaler appliance

At the command prompt, type the following:

set lb vserver <vserver name> -netprofile <name>

Example:

set lb vserver lbvserver-2 –netprofile proxyProfile-3

Set net profile with HTTP service in NetScaler appliance

At the command prompt, type the following:

set service <service name> –netprofile <name>

Example:

set service http-service-2 –netprofile proxyProfile-4

Bind the load balancing virtual server to service

At the command prompt, type the following:

bind lb vserver <vserver name> <service name>

Example:

bind lb vserver lbvserver-2 http-service-2

Configure proxy protocol for strip operation

To configure the proxy protocol for strip operation, you must enable the proxy protocol on the load balancing virtual server and disable the proxy protocol on the service.

Add net profile with proxy protocol enabled for virtual server

At the command prompt, type the following:

add netprofile <name> -proxyProtocol ENABLED> -proxyprotocoltxversion <V1/V2>

Example:

add netprofile proxyprofile-5 –proxyProtocol ENABLED –proxyprotocoltxversion V1

Add load balancing or content switching virtual server for NetScaler appliance in the proxy layer

At the command prompt, type the following:

add lb vserver <name>@ <serviceType> [(<IPAddress>@ <port>)]

Example:

add lb vserver lbvserver-3 http 2.2.2.2 80

Add HTTP service for NetScaler appliance in the proxy layer

At the command prompt, type the following:

add service <name>@ (<IP>@ | <serverName>@) <serviceType> <port>

Example:

Add service http-service-3 3.3.3.1 http 80

Set net profile with load balancing or content switching virtual server in NetScaler appliance

At the command prompt, type the following:

set lb vserver <vserver name> -netprofile <name>

Example: set lb vserver lbvserver-3 –netprofile proxyProfile-5

Bind the load balancing virtual server to service

At the command prompt, type the following:

bind lb vserver <vserver name> <service name>

Example:

bind lb vserver lbvserver-3 http-service-3

Configure responder policy infrastructure expression for proxy protocol by using the CLI

To configure a responder policy, at the command prompt, type:

add responder policy <name> <expression> <action>

Example:

> add responder policy resppol_proxy_srcip "CLIENT.PROXY.SRCIP_STR.EQ(\"10.106.26.83\")" RESET
Done
<!--NeedCopy-->

To bind the responder policy with the load balancing virtual server, at the command prompt, type:

bind lb vserver <name> -policyname <string> -priority <positive_integer> -gotoPriorityExpression <expression> -type <type>

Example:

> bind lb vserver lb_tcp1 -policyName resppol_proxy_srcip -priority 10 -gotoPriorityExpression END -type REQUEST
Done
<!--NeedCopy-->

Sample end-to-end configuration 

> add ns tcpProfile tcp-proxy-profile -tcpmode ENDPOINT

> add netprofile net_proxyv1 -MBF DISABLED -proxyProtocol
ENABLED

> enable ns mode l2

> enable ns mode l3 usnip

> add ns ip 10.106.26.146 255.255.255.0 -type SNIP
Done
> add ns ip 10.106.26.144 255.255.255.0 -type SNIP
Done

> add lb vserver lb_tcp1 TCP 10.106.26.141 80
> add service s1 10.106.26.82 TCP 8080

> bind lb vserver lb_tcp1 s1

> set lb vserver lb_tcp1 -tcpProfileName tcp_proxy -netProfile net_proxyv1

> set ns param -proxyProtocol ENABLED

> add responder policy resppol_proxy_srcip "CLIENT.PROXY.SRCIP_STR.EQ(\"10.106.26.83\")" RESET

> bind lb vserver lb_tcp1 -policyName resppol_proxy_srcip -priority 10 -gotoPriorityExpression END -type REQUEST
Done
<!--NeedCopy-->

Configure Proxy protocol by using NetScaler GUI

  1. Navigate to System > Settings > Change Global System Settings.
  2. In the Configure Global System Settings Parameters page, select Proxy Protocol check box.
  3. Click OK and Close.
  4. Navigate to System > Network > Net Profiles.
  5. In the details pane, click Add to create a net profile for the load balancing virtual server.
  6. In the Net Profile page, set the following parameters:
    1. Name : Name of the net profile.
    2. Proxy Protocol: Enable or disable proxy protocol for the load balancing virtual server.
    3. Proxy Protocol TX Version: Set proxy protocol version as V1 or V2 based on incoming data format.
  7. Click OK.
  8. Navigate to Traffic Management > Load Balancing > Virtual Servers.
  9. In the details pane, click Add.
  10. In the Load Balancing Virtual Server page, the set the basic parameters.
  11. In the Advanced Settings section, select Profiles.
  12. In the Profiles section, click the pencil icon.
  13. Select a net profile and click OK.
  14. Click Done.
  15. Navigate to Traffic Management > Load Balancing > Services.
  16. In the details pane, click Add.
  17. In the Load Balancing Service page, set the basic parameters.
  18. In the Advanced Settings section, select Profiles.
  19. In the Profiles section, click the pencil icon.
  20. Select a net profile and click OK.
  21. Click Done.

Note:

If you have more than one NetScaler appliance as part of the proxy layer, you must set the proxy protocol configuration on each appliance for the Forward operation.

Proxy protocol
December 29, 2023
Contributed by: 
C S
December 29, 2023
Contributed by: 
C S

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.