aboutsummaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2020-03-21 20:21:05 +0200
committerSergey Poznyakoff <gray@gnu.org>2020-03-21 20:21:05 +0200
commita6d6598a99f654cf25a65e512ce7bf4856fda3b2 (patch)
tree5cd0500e3bf009c294fa0eeb06dfcf9759cfdb46 /README
parent0774e8317694461a0d16ec365d70be08f6554c92 (diff)
downloadvmod-remoteip-a6d6598a99f654cf25a65e512ce7bf4856fda3b2.tar.gz
vmod-remoteip-a6d6598a99f654cf25a65e512ce7bf4856fda3b2.tar.bz2
Version 1.0v1.0
Diffstat (limited to 'README')
-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 @@
1Vmod_remoteip 1#+TITLE: vmod_remoteip: Deduce actial client IP address for Varnish Cache
2=============
3 2
4Overview 3* Overview
5--------
6 4
7This modules is for Varnish Cache what mod_remoteip is for Apache. It 5This module is for Varnish Cache what =mod_remoteip= is for Apache. It
8determines the actual client IP address for the connection, using the 6determines the actual client IP address for the connection, using the
9useragent IP address list presented by a proxies or a load balancer 7useragent IP address list presented by a proxy or load balancer
10via the request headers and a preconfigred list of trusted IP 8via the request headers and a preconfigred list of trusted IP
11addresses. For example, if your Varnish server works behind a load 9addresses. For example, if your Varnish server works behind a load
12balancer or yet another reverse proxy (such as pound or haproxy to 10balancer or yet another reverse proxy (such as pound or haproxy to
13handle the TLS connection), you can use this module to get the real 11handle the TLS connection), you can use this module to get the real
14incoming connection IP address from the "X-Forwarded-For" header. 12incoming connection IP address from the =X-Forwarded-For= header.
15 13
16Example 14* Example
17-------
18 15
19An example of using this module: 16The following example VCL uses the client address deduced from the
17value of the =X-Forwarded-For= header to enable the code specific for
18hosts from the ACL "allowed":
20 19
20#+BEGIN_SRC vcl-script
21 import std; 21 import std;
22 import remoteip; 22 import remoteip;
23 23
24 sub vcl_init { 24 sub vcl_init {
25 remoteip.init("192.0.2.1, 127.0.0.0/8"); 25 // Register trusted proxy server addresses
26 remoteip.init("192.0.2.1, 127.0.0.1");
26 } 27 }
27 28
28 acl allowed { 29 acl allowed {
29 "127.0.0.1"; 30 "203.0.113.1";
30 ... 31 "192.0.2.10";
31 } 32 }
32 33
33 sub vcl_recv { 34 sub vcl_recv {
@@ -36,60 +37,118 @@ An example of using this module:
36 ... 37 ...
37 } 38 }
38 } 39 }
40#+END_SRC
39 41
40Installation 42* Installation
41------------
42 43
43In order to compile the package you need to have installed 44In order to compile the package you need the varnishd and varnishapi
44varnishd and varnishapi package. The module has been tested with 45packages. The module has been tested with Varnish version 6.3.1 and
45Varnish version 6.3.1. 46higher. Python 3, [[https://sourceforge.net/projects/docutils][Docutils]]
47and [[http://sphinx-doc.org][Sphinx]] are needed to build documentation.
48On Debian-based systems, this requires the =python3-docutils= and
49=python3-sphinx= packages.
46 50
47Supposing that condition is met, run: 51If these prerequisites are met, run:
48 52
53#+BEGIN_SRC shell-script
49 ./configure 54 ./configure
55#+END_SRC
50 56
51If your system offers Python versions 2.x and 3.x, it is quite often that 57If both Python versions 2.x and 3.x are installed on the system,
52version 2.x is used by default. In that case, we recommend to explicitly 58chances are version 2 is used by default. In that case, require
53require version 3.x, as shown in this example: 59version 3 explicitly, as shown in this example:
54 60
61#+BEGIN_SRC shell-script
55 ./configure PYTHON=python3 62 ./configure PYTHON=python3
63#+END_SRC
56 64
57Otherwise, the configure script should be able to automatically find 65Otherwise, the configure script should be able to automatically find
58the necessary components. In case it doesn't, tweak the configuration 66the necessary components. In case it doesn't, tweak the configuration
59variables as necessary. The most important one is PKG_CONFIG_PATH, 67variables as necessary. The most important one is =PKG_CONFIG_PATH=,
60which contains a path (in the UNIX sense) where the .pc files are 68which contains a path (in the UNIX sense) where the =.pc= files are
61located. It should contain a directory where the 'varnishapi.pc' file 69located. It should contain a directory where the =varnishapi.pc= file
62lives. Example usage: 70lives. Example usage:
63 71
72#+BEGIN_SRC shell-script
64 ./configure PKG_CONFIG_PATH=/opt/varnish/lib/pkgconfig:$PKG_CONFIG_PATH 73 ./configure PKG_CONFIG_PATH=/opt/varnish/lib/pkgconfig:$PKG_CONFIG_PATH
74#+END_SRC
65 75
66Please read the file INSTALL for a detailed discussion of available variables 76Please read the file =INSTALL= for a detailed discussion of available variables
67and command line options. 77and command line options.
68 78
69Once configured, do 79Once configured, do
70 80
71 make 81#+BEGIN_SRC shell-script
82 make
83#+END_SRC
72 84
73This will build the module. After this step you can optionally run 85This will build the module. After this step you can optionally run
74'make test' to test the package. 86=make test= to test the package.
75 87
76Finally, run the following command as root: 88Finally, run the following command as root:
77 89
90#+BEGIN_SRC shell-script
78 make install 91 make install
92#+END_SRC
79 93
80Documentation 94* Documentation
81-------------
82 95
83The manual page vmod_remoteip(3) will be available after a successful 96The manual page
84install. To read it without actually installing the module, run 97[[http://man.gnu.org.ua/manpage/?3+vmod_remoteip][vmod_remoteip(3)]] will
85`man src/vmod_remoteip.3'. 98be available after a successful install. To read it without actually
99installing the module, run =man src/vmod_remoteip.3= .
86 100
87An online copy of the documentation is available from 101An online copy of the documentation is available from
88http://ps.gnu.org.ua/software/vmod-remoteip. 102http://ps.gnu.org.ua/software/vmod-remoteip.
89 103
104* Downloads
105
106Source tarballs can be downloaded from
107https://download.gnu.org.ua/release/vmod-remoteip.
108
109The git repository is available at
110http://git.gnu.org.ua/cgit/vmod-remoteip.git.
111
112The project home page is
113https://puszcza.gnu.org.ua/projects/vmod-remoteip.
114
115* Copyright
116
117Copyright (C) 2020 Sergey Poznyakoff
118
119Permission is granted to anyone to make or distribute verbatim copies
120of this document as received, in any medium, provided that the
121copyright notice and this permission notice are preserved,
122thus giving the recipient permission to redistribute in turn.
123
124Permission is granted to distribute modified versions
125of this document, or of portions of it,
126under the above conditions, provided also that they
127carry prominent notices stating who last changed them.
128
90* Bug reporting 129* Bug reporting
91 130
92Send bug reports and suggestions to <gray@gnu.org> 131Send bug reports and suggestions to <gray@gnu.org>
93 132
133* Document settings :noexport:
134
135Please ignore this section. It supplies the variables necessary for
136proper rendering of this document.
137
138:PROPERTIES:
139:VISIBILITY: folded
140:END:
141
142#+STARTUP: showall
143#+EXCLUDE_TAGS: noexport
144#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
145#+OPTIONS: ^:nil
146
147# Local Variables:
148# mode: org
149# paragraph-separate: "[ ]*$"
150# version-control: never
151# End:
152
94 153
95 154

Return to:

Send suggestions and report system problems to the System administrator.