Varnish reverse proxy


Varnish is a reverse proxy that processes incoming enquiries from web clients before the actual web server. Web pages that are delivered to web clients are for the most part compiled from cached content. Only when the cache lifetime has expired, Varnish will query content from the web server. Then, OXID eShop must read and provide the requested data from the database.

During processing, Varnish divides the individual OXID eShop pages into small sections, the so-called widgets. These are labelled as ESI tags. This allows Varnish to separately query and update dynamic page areas, such as the shopping cart or login. In addition, graphics, product and category images, stylesheet and JavaScript files are always cached.

Web clients, Varnish and server with OXID eShop

To use Varnish for caching OXID eShop, you will need to install and configure this reverse proxy on a separate server.


Install Varnish on a server. The software and installation guide can be found on the manufacturer’s website: .


Varnish has its own language that can be used to configure its behaviour. Defined with VCL (Varnish Configuration Language), the configuration is translated into binary code and executed on requests from the web. The default configuration file, default.vcl is located in the /etc/varnish directory.

We have customised the default.vcl configuration file for cashing OXID eShop. The definitions correspond to a default shop and should only be changed for a highly customised shop. This applies only to changes in the shop’s default behaviour through modular extensions, such as completely changed handling of products or use of own cookies. The necessary changes in the configuration file require profound knowledge of the VCL. Incorrect instructions may affect performance and allow the shop to provide data that is out of date. Using the configuration file unchanged in a highly customised shop may result in data loss and unexpected behaviour.

The servers_conf.vcl configuration file contains the host names and IPs of the servers involved and needs to be adapted to the real system environment.

Varnish starting with version 4.0.3

Varnish version 3.0 is no longer supported because the software has reached the End-Of-Life (EOL) status since April 2015. The default.vcl file provided now contains the configuration for Varnish starting with version 4.0.3. Please don’t use versions 4.0.0, 4.0.1 and 4.0.2 because they had issues with handling cookies that led to products not being placed in the shopping cart and customers being unable to log in to the shop.

If this behaviour takes place in your shop and you can’t upgrade to the latest version of Varnish, you should try the following workaround. This has not been explicitly tested, so please check the shop’s behaviour thoroughly before applying the change to the production environment.

In the default.vcl configuration file, replace line 463

set beresp.http.Set-Cookie = regsuball(beresp.http.Set-Cookie,\"(, |^)[^@][^,|$]+\",\"\");

with the following line

set beresp.http.Set-Cookie = regsuball(beresp.http.Set-Cookie,\"(, |^)[^@]\",\"\");

Configuration files

The two configuration files default.vcl and servers_conf.vcl for configuring the reverse proxy can be dragged from a repository to GitHub using Composer. This protected repository can be accessed with the password that shop owners received when purchasing the high-load option. Please contact technical support if you experience any issues.

Copy the files to the /etc/varnish directory. If these files have already been customised in your system, you will need to merge their contents manually. Restart Apache and Varnish.

/etc/init.d/apache2 stop
/etc/init.d/varnish restart
/etc/init.d/apache2 start

Customising the configuration for OXID eShop Mobile Theme

If you are using OXID eShop Mobile Theme, you will need to customise the default.vcl configuration file of the reverse proxy. All necessary entries can be found in the device.vcl file included in the installation package.

  • Copy the contents of the device.vcl file.

  • Open Varnish configuration file, default.vcl stored in the /etc/varnish directory by default.

  • Search for the oxDefineDeviceTypeRecv function and replace the content with the copied code snippet.

  • Add this function if it doesn’t exist.

  • Now, search for the vcl_recv function.

  • Check whether the following line is included: call oxDefineDeviceTypeRecv;

  • Add this line if it’s missing.

  • Restart Varnish.

SSL encryption

Varnish processes requests from the web that use the HTTP protocol. Encrypted requests with HTTPS protocol can’t be executed through the reverse proxy. Since OXID eShop can switch to SSL encryption when user data is transferred, for example, during registration, login or in the shopping cart, a separate solution needs to be created. Currently, this can be done in two different ways. First, requests with the HTTPS protocol can be sent directly to the server with OXID eShop. This has to be implemented with server tools. Second, you can use a load balancer that forwards requests via HTTP, port 80 to Varnish and via HTTPS, port 443 directly to OXID eShop.