Reverse proxies and VIP Go

VIP Go platform specific

This document is for sites running on VIP Go.

Learn more

Overview #

A reverse proxy is a server that sits between the end user requesting information from your site and the VIP application that serves the content . Most VIP applications do not require them, but if yours does, there are a few technical requirements and considerations to take into account before you implement one.

The first question to ask is whether you truly need a reverse proxy. Here are a few common use cases. If your primary domain is example.com and hosted on VIP, you probably do not need a reverse proxy. If you’re not sure if you need one, feel free to ask your TAM or a Support Engineer.

↑ Top ↑

Common use cases for reverse proxies #

VIP is one of many applications on your domain #

If you run example.com outside of VIP, and your VIP application serves a resource within example.com, like https://example.com/blog/, then you will need a reverse proxy. It should be configured to forward all requests for /blog/ to the VIP application in order to return the correct content back to example.com.

The reverse of that scenario is also possible: where example.com is your VIP application but example.com/blog/ is for a resource hosted elsewhere. You’ll need a reverse proxy to forward /blog/ to the outside resource and all other requests to VIP.

↑ Top ↑

Requests for your domain are terminated before reaching VIP #

You run example.com on VIP but use a CDN to route requests correctly based on the end user’s physical location. To accomplish this, you need a reverse proxy in front of the VIP application that terminates the connection to example.com and routes requests appropriately. If this is your use case, we strongly encourage you to consider doing this routing through VIP rather than adding an additional layer of complexity by introducing a CDN.

↑ Top ↑

Requests require rewriting the URL to reach the VIP resource #

Finally, you may have a resource on example.com like /abc/ and you need it to resolve to your VIP Go application at /def/. This is called URL transformation and is among the most complex reverse proxy scenarios. For that reason, we strongly encourage you to avoid URL transformation.

↑ Top ↑

Why you don’t need a reverse proxy #

Employing a reverse proxy introduces complexity to your application. We encourage you not to use one unless you are sure it’s necessary.

↑ Top ↑

Caching or page speed #

VIP provides built-in caching and performance features including load balancing and a globally distributed cache. You do not need a reverse proxy to facilitate any of this, it is built-in to your application. Adding this layer may ultimately reduce the performance of your site.
Additionally, it is likely that at least some of your site’s users will be routed suboptimally, negatively affecting page speed. This is because your proxy will stand in front of our globally distributed edge cache network. The user will be routed to the proxy and then to the VIP node closest to the proxy.

↑ Top ↑

Support efficiency #

Even the simplest reverse proxy configuration will increase complexity because of the additional layer of functionality outside the VIP application. This may cause difficulties for developers supporting the application in the long term. VIP will have more difficulty debugging issues that arise, especially if they are related to the proxy connection. In some cases, we may need to communicate with the reverse proxy provider.

We’re happy to help you weigh the benefits of using a reverse proxy, and we already support many sites which use this functionality to support their business requirements.

↑ Top ↑

What we need from you (or your reverse proxy provider) #

The more you can tell us about your proxy server, the better we can support your connecting it to VIP.

Our preferred method of implementing a reverse proxy setup is as follows:

  • The VIP Go domain and URL structure matches the incoming request. That is, if the user requested example.com/blog the resource VIP will return is example.com/blog… and:
  • The reverse proxy should set a True-Client-IP HTTP request header with the IP of the end user… and:
  • The reverse proxy should set an X-VIP-Proxy-Verification header with an agreed secret string as the value (contact us to agree on and set this string)

Sending the VIP-PROXY-VERIFICATION header along with TRUE-CLIENT-IP from the proxy will allow us to verify the reverse proxy server via the secret key previously shared with us and saved in the site’s configuration on our end. The following code must then be used in the site’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 );
	Automattic\VIP\Proxy\fix_remote_address_with_verification_key(
		$_SERVER['HTTP_TRUE_CLIENT_IP'],
		$_SERVER['HTTP_X_VIP_PROXY_VERIFICATION']
	);
}
  • Finally, if you would like to send custom headers to help you test the proxy application, you may do so. VIP will not reject these requests.

↑ Top ↑

How VIP will set up your application #

  • Set the primary domain for the application to the production domain (http://www.example.com). This is so that requests returned back to the proxy server have the production domain. For multisite installations, see our documentation on special considerations for mapping domains.
  • Replace all instances of the VIP placeholder domain with the production domain
  • Map and issue SSL Certificates for the domain you provided for the VIP application

↑ Top ↑

How it all works #

Using the scenario where you want to host a VIP application at http://www.example.com/blog:

↑ Top ↑

Alternate implementations #

If a X-VIP-Proxy-Verification header cannot be set, the proxy can be verified by using an IP whitelist and passing the client IP in the header True-Client-IP. Please note that the whitelist must be kept up to date.

This implementation assumes a file vip-config/remote-proxy-ips.php, which contains an array of proxy IP addresses. The contents of the file should be similar to the example below:

<?php
// A constant defining an array of whitelisted IP addresses and/or CIDRs
// which equate to the possible IP addresses of your Remote Proxy
define( 'MY_PROXY_IP_WHITELIST', [
	'1.2.3.4/20',
	'5.6.7.8/20',
	'2.3.4.5',
] );

The IPs can be provided as fully qualified IPv4 or IPv6 addresses, or in CIDR notation.
Then, the following code in vip-config/vip-config.php checks the Reverse Proxy’s IP address matches the whitelist, extracts the end user’s IP address from the True-Client-IP HTTP Header, and forwards the End User’s real IP address as REMOTEADDR:

$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_WHITELIST 
        ); 
} 

↑ Top ↑

Validating your proxy configuration #

We encourage you to test your proxy configuration extensively leading up to launch.

↑ Top ↑

Using cURL #

One way to validate the reverse proxy is to configure the proxy and use curl to send a request to a URI that you expect to be forwarded to VIP and inspect the response headers. You should see x-hacker, x-powered-by, and other headers sent by VIP alongside the headers sent by the proxy server.

If example.com is your proxy server and the VIP application is at example.com/blog/ when you run curl -I https://example.com/blog/ you should see X-powered-by: WordPress.com VIP <https://wpvip.com&gt; and the headers identifying the proxy server.

↑ Top ↑

Using a staging server #

Another strategy for testing is to configure a staging proxy server for the routes you intend to set in production. If you have staging.example.com you can point staging.example.com/blog/ to the VIP application. If you would like to do this please notify VIP with the following:

  • The domain name of your staging server (staging.example.com)
  • When you would like to begin testing

VIP will map the domain and configure SSL certificates once DNS records are in place. Once you’re ready to start testing we can search-replace for the go-vip.co or go-vip.net placeholder domain. When you’re ready to launch, you need only to replicate the proxy configuration on your production server.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.