From a6d6598a99f654cf25a65e512ce7bf4856fda3b2 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Sat, 21 Mar 2020 20:21:05 +0200 Subject: Version 1.0 --- README | 127 +++++++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 93 insertions(+), 34 deletions(-) (limited to 'README') diff --git a/README b/README index 30140c4..ca814ba 100644 --- a/README +++ b/README @@ -1,33 +1,34 @@ -Vmod_remoteip -============= +#+TITLE: vmod_remoteip: Deduce actial client IP address for Varnish Cache -Overview --------- +* Overview -This modules is for Varnish Cache what mod_remoteip is for Apache. It +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 proxies or a load balancer +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. +incoming connection IP address from the =X-Forwarded-For= header. -Example -------- +* Example -An example of using this module: +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 { - remoteip.init("192.0.2.1, 127.0.0.0/8"); + // Register trusted proxy server addresses + remoteip.init("192.0.2.1, 127.0.0.1"); } acl allowed { - "127.0.0.1"; - ... + "203.0.113.1"; + "192.0.2.10"; } sub vcl_recv { @@ -36,60 +37,118 @@ An example of using this module: ... } } +#+END_SRC -Installation ------------- +* 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. +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. -Supposing that condition is met, run: +If these prerequisites are met, run: +#+BEGIN_SRC shell-script ./configure +#+END_SRC -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: +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 +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 +Please read the file =INSTALL= for a detailed discussion of available variables and command line options. Once configured, do - - make + +#+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. +=make test= to test the package. Finally, run the following command as root: +#+BEGIN_SRC shell-script make install +#+END_SRC -Documentation -------------- +* 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'. +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 +* 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: +#+OPTIONS: ^:nil + +# Local Variables: +# mode: org +# paragraph-separate: "[ ]*$" +# version-control: never +# End: + -- cgit v1.2.1