summaryrefslogtreecommitdiffabout
path: root/README
Side-by-side diff
Diffstat (limited to 'README') (more/less context) (ignore whitespace changes)
-rw-r--r--README127
1 files changed, 93 insertions, 34 deletions
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 <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:
+

Return to:

Send suggestions and report system problems to the System administrator.