Vmod_remoteip
=============

Overview
--------

This modules 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 proxies or a 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.

Example
-------

An example of using this module:

  import std;
  import remoteip;
 
  sub vcl_init {
      remoteip.init("192.0.2.1, 127.0.0.0/8");
  }

  acl allowed {
      "127.0.0.1";
      ...
  }

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

Installation
------------

In order to compile the package you need to have installed
varnishd and varnishapi package.  The module has been tested with
Varnish version 6.3.1.

Supposing that condition is met, run:

   ./configure

If your system offers Python versions 2.x and 3.x, it is quite often that
version 2.x is used by default.  In that case, we recommend to explicitly
require version 3.x, 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

  make

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

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.

* Bug reporting

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