vmod_remoteip: Deduce actial client IP address for Varnish Cache

Table of Contents

1 Overview

This module is for Varnish Cache what mod_remoteip is for Apache. It determines the actual client IP address for the connection, using the useragent IP address list presented by a proxy or load balancer via the request headers and a preconfigred list of trusted IP addresses. For example, if your Varnish server works behind a load balancer or yet another reverse proxy (such as pound or haproxy to handle the TLS connection), you can use this module to get the real incoming connection IP address from the X-Forwarded-For header.

2 Example

The following example VCL uses the client address deduced from the value of the X-Forwarded-For header to enable the code specific for hosts from the ACL "allowed":

import std;
import remoteip;

// Register trusted proxy server addresses
acl trusted { 

acl allowed {

sub vcl_recv {
    set req.http.x-real-ip = remoteip.get(trusted, req.http.X-Forwarded-For);
    if (std.ip(req.http.x-real-ip) ~ allowed) {

3 Installation

In order to compile the package you need the varnishd and varnishapi packages. The module has been tested with Varnish version 6.3.1 and higher. Python 3, Docutils and Sphinx are needed to build documentation. On Debian-based systems, this requires the python3-docutils and python3-sphinx packages.

If these prerequisites are met, run:


If both Python versions 2.x and 3.x are installed on the system, chances are version 2 is used by default. In that case, require version 3 explicitly, as shown in this example:

./configure PYTHON=python3

Otherwise, the configure script should be able to automatically find the necessary components. In case it doesn't, tweak the configuration variables as necessary. The most important one is PKG_CONFIG_PATH, which contains a path (in the UNIX sense) where the .pc files are located. It should contain a directory where the varnishapi.pc file lives. Example usage:

./configure PKG_CONFIG_PATH=/opt/varnish/lib/pkgconfig:$PKG_CONFIG_PATH

Please read the file INSTALL for a detailed discussion of available variables and command line options.

Once configured, do


This will build the module. After this step you can optionally run make test to test the package.

Finally, run the following command as root:

make install

4 Documentation

The manual page vmod_remoteip(3) will be available after a successful install. To read it without actually installing the module, run man src/vmod_remoteip.3 .

An online copy of the documentation is available from http://ps.gnu.org.ua/software/vmod-remoteip.


Source tarballs can be downloaded from https://download.gnu.org.ua/release/vmod-remoteip.

The git repository is available at http://git.gnu.org.ua/cgit/vmod-remoteip.git.

The project home page is https://puszcza.gnu.org.ua/projects/vmod-remoteip.

6 Copyright

Copyright (C) 2020 Sergey Poznyakoff

Permission is granted to anyone to make or distribute verbatim copies of this document as received, in any medium, provided that the copyright notice and this permission notice are preserved, thus giving the recipient permission to redistribute in turn.

Permission is granted to distribute modified versions of this document, or of portions of it, under the above conditions, provided also that they carry prominent notices stating who last changed them.

7 Bug reporting

Send bug reports and suggestions to <gray@gnu.org>

Author: Sergey Poznyakoff

Created: 2020-03-25 Wed 13:51

Emacs 25.3.1 (Org mode 8.2.10)