#+TITLE: vmod_remoteip: Deduce actial client IP address for Varnish Cache

* 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.

* 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":

#+BEGIN_SRC vcl-script
  import std;
  import remoteip;
 
  sub vcl_init {
      // Register trusted proxy server addresses
      remoteip.init("192.0.2.1, 127.0.0.1");
  }

  acl allowed {
      "203.0.113.1";
      "192.0.2.10";
  }

  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) {
          ...
      }
  }
#+END_SRC

* 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, [[https://sourceforge.net/projects/docutils][Docutils]] 
and [[http://sphinx-doc.org][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:

#+BEGIN_SRC shell-script
   ./configure
#+END_SRC

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: 

#+BEGIN_SRC shell-script
   ./configure PYTHON=python3
#+END_SRC
   
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:

#+BEGIN_SRC shell-script
   ./configure PKG_CONFIG_PATH=/opt/varnish/lib/pkgconfig:$PKG_CONFIG_PATH
#+END_SRC

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

Once configured, do
 
#+BEGIN_SRC shell-script
   make
#+END_SRC

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:

#+BEGIN_SRC shell-script
  make install
#+END_SRC

* Documentation

The manual page
[[http://man.gnu.org.ua/manpage/?3+vmod_remoteip][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.

* Downloads

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.

* 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.

* Bug reporting

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

* Document settings :noexport:

Please ignore this section. It supplies the variables necessary for
proper rendering of this document.

:PROPERTIES:
:VISIBILITY: folded
:END:

#+STARTUP: showall
#+EXCLUDE_TAGS: noexport
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
#+OPTIONS: ^:nil

# Local Variables:
# mode: org
# paragraph-separate: "[ 	]*$"
# version-control: never
# End: