Skip to content

Configure a reverse proxy

Reverse proxy configurations should be kept as simple as possible. The Site Address (URL) of a site behind a reverse proxy should be set to the same domain and subdirectory (where applicable) as the domain and path that the reverse proxy is pointed to. This is the simplest and most reliable configuration between a reverse proxy and a site on the VIP Platform.

All reverse proxy implementations should:

  • Forward traffic to the *.go-vip.net convenience domain for any routes that should come to VIP (e.g., /blog/* ) along with any URL parameters sent by the end user.
  • Set a Host HTTP request header to the application’s domain (Host: example.com), usually by passing the value that the end-user requested.
  • Set a True-Client-IP HTTP request header (from the reverse proxy to VIP) with the IP of the end-user.
  • Set an X-VIP-Proxy-Verification request header (from the reverse proxy to VIP) in an application, or add an IP allow list.
  • Forward the domain’s .well-known/acme-challenge/* route, or install a custom TLS certificate for the domain on the VIP environment.
  • Allow access to the site from:
  • Have valid TLS certificates for public-facing domains (applied to the proxy).
  • Have valid TLS certificates on VIP for all domains mapped to a VIP application.
    VIP recommends using Let’s Encrypt TLS certificates. Additional instructions can be found below for mapping a proxy to pass the ACME challenge for TLS provisioning.
  • Have DNS CNAME records for public-facing domains, pointed to the proxy.
  • Be documented in the application’s /docs directory in the GitHub repo, to facilitate troubleshooting.

Correctly logging end-user IPs

VIP supports two methods for verifying that requests are from a reverse proxy and enable logging the correct end-user IP.

Sending both the X-VIP-Proxy-Verification request header and the True-Client-IP request header from the proxy will allow VIP to verify (via a secret string) that the request came via the reverse proxy server, and that the REMOTE_ADDR value will be set in logs with the True-Client-IP value.

If neither of the methods are implemented, VIP will log only the reverse proxy’s IP(s) which can hinder troubleshooting. The configuration options for verification relate only to logging, and not to restricting access to a site.

The X-VIP-Proxy-Verification method has the following requirements:

  • The domain and URL structure of the VIP site must match incoming requests. For example, if a user requests example.com/blog, the resource on VIP should be available at example.com/blog.
  • The reverse proxy should set a True-Client-IP incoming HTTP request header with the IP of the end-user.
  • Secret string
    1. Generate a 40-character (or more) alphanumeric secret string. In the reverse proxy settings, set this string as the X-VIP-Proxy-Verification incoming request header value.
    2. Create a VIP Support ticket to notify VIP that the secret string has been generated for a reverse proxy, and securely supply the string using an application like Keybase, or another form of encryption. Under no circumstances should the string value be supplied in the VIP Support ticket.
  • The  X-VIP-Proxy-Verification and True-Client-IP are Incoming request headers (from the reverse proxy to VIP), not Outgoing.
  • Add the following code to an application’s vip-config.php file:
$proxy_lib = ABSPATH . ‘/wp-content/mu-plugins/lib/proxy/ip-forward.php’;

if ( ! empty( $_SERVER[‘HTTP_TRUE_CLIENT_IP’] )

    && ! empty( $_SERVER[‘HTTP_X_VIP_PROXY_VERIFICATION’] )

    && file_exists( $proxy_lib ) ) {

    require_once $proxy_lib;

// phpcs:disable WordPress.Security.ValidatedSanitizedInput.InputNotSanitized — Validated in the function call.

    Automattic\VIP\Proxy\fix_remote_address_with_verification_key(

        $_SERVER[‘HTTP_TRUE_CLIENT_IP’],

        $_SERVER[‘HTTP_X_VIP_PROXY_VERIFICATION’]

    );

// phpcs:enable

}

Custom headers can be sent to assist with the process of testing a reverse proxy configuration. VIP will not reject these requests.

The IP allow list method

If an X-VIP-Proxy-Verification request header cannot be set, the reverse proxy can be verified by using a list of trusted IPs and passing the client IP in the incoming request header True-Client-IP (from the reverse proxy to VIP). This list must be manually kept up to date.

The IP allow list method has the following requirements:

  • Create a vip-config/remote-proxy-ips.php file to contain an array of proxy IP addresses. The IPs can be provided as fully qualified IPv4 or IPv6 addresses, or in Classless Inter-Domain Routing (CIDR) notation. The contents of the file should be similar to the example below:
<?php

// A constant defining an array of allowed IP addresses and/or CIDRs

// which equate to the possible IP addresses of your Remote Proxy

define( ‘MY_PROXY_IP_ALLOW_LIST’, [

    ‘1.2.3.4/20’,

    ‘5.6.7.8/20’,

    ‘2.3.4.5’,

] );
  • Add the following code to vip-config/vip-config.php to check that the proxy’s IP address matches the allowed list, extracts the end user’s IP address from the True-Client-IP incoming request HTTP header, and forwards the end user’s real IP address as REMOTEADDR:
vip-config/vip-config.php
$proxy_lib = ABSPATH . ‘/wp-content/mu-plugins/lib/proxy/ip-forward.php’;

if ( ! empty( $_SERVER[‘HTTP_TRUE_CLIENT_IP’] ) && file_exists( $proxy_lib ) ) {

    require_once( __DIR__ . ‘/remote-proxy-ips.php’ );

    require_once( $proxy_lib );

    Automattic\VIP\Proxy\fix_remote_address(

        $_SERVER[‘HTTP_TRUE_CLIENT_IP’],

        $_SERVER[‘HTTP_X_FORWARDED_FOR’],

        MY_PROXY_IP_ALLOW_LIST

        );

}

Cloudflare-specific settings

The True-Client-IP header is only available on Cloudflare Enterprise. If using Cloudflare, but not the Cloudflare Enterprise package, use the CF-Connecting-IP header instead; this is the same value under a different key.

Amend the X-VIP-Proxy-Verification method code example shown above by replacing both instances of the string HTTP_TRUE_CLIENT_IP with HTTP_CF_CONNECTING_IP. A guide for setting HTTP request header modification rules can be reviewed in Cloudflare’s documentation.

Images not showing in Safari

CloudFlare does not support the Vary: Accept header that VIP sends. This causes cached copies of webp images to be served to all browsers. In the case of Safari, webp is not yet a supported file format, so images will not show.

To work around this, a rule should be created in CloudFlare that matches the wp-content/uploads path, and bypasses caching.

Akamai-specific settings

Akamai SureRoute

Akamai’s SureRoute technology attempts to find and cache the most optimal network route between the edge and the end user. VIP’s implementation of Anycast can cause SureRoute to use sub-optimal routes. For this reason it is recommended that clients disable SureRoute.

Images not showing in Safari

By default, Akamai removes the Vary headers passed from the origin, which can cause the caching of webp images on the edge nodes (this is unsupported on Safari). The most elegant workaround is to add a behavior to disable the removal of the Vary headers.

Edgio (previously Layer0)-specific settings

It might not be possible to send the True-Client-IP request header when using the Edgio reverse proxy. Edgio provides an x-0-client-ip header that contains the same value under a different key and can be used instead.

Amend the X-VIP-Proxy-Verification method code example shown above by replacing both instances of the string HTTP_TRUE_CLIENT_IP with HTTP_X_0_CLIENT_IP.

Removing a proxy configuration

To remove a reverse proxy and make use of the VIP Platform exclusively, ensure the following:

  • The application is configured with the final domain.
  • The domain has a valid TLS certificate installed on the VIP side.
  • The site has been tested and is reachable by using a hosts file to bypass any proxy and send requests directly to VIP

By following the recommendations above and configuring the VIP side as if there were no proxy in place, the final URL as well as certificate should already be set. Following those recommendation will make it possible to remove the proxy by updating DNS to point to VIP directly. No additional changes on the VIP side should be needed.

Last updated: September 12, 2022