diff options
author | Sergey Poznyakoff <gray@gnu.org> | 2020-03-21 20:21:05 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org> | 2020-03-21 20:21:05 +0200 |
commit | a6d6598a99f654cf25a65e512ce7bf4856fda3b2 (patch) | |
tree | 5cd0500e3bf009c294fa0eeb06dfcf9759cfdb46 /README | |
parent | 0774e8317694461a0d16ec365d70be08f6554c92 (diff) | |
download | vmod-remoteip-a6d6598a99f654cf25a65e512ce7bf4856fda3b2.tar.gz vmod-remoteip-a6d6598a99f654cf25a65e512ce7bf4856fda3b2.tar.bz2 |
Version 1.0v1.0
Diffstat (limited to 'README')
-rw-r--r-- | README | 127 |
1 files changed, 93 insertions, 34 deletions
@@ -1,33 +1,34 @@ | |||
1 | Vmod_remoteip | 1 | #+TITLE: vmod_remoteip: Deduce actial client IP address for Varnish Cache |
2 | ============= | ||
3 | 2 | ||
4 | Overview | 3 | * Overview |
5 | -------- | ||
6 | 4 | ||
7 | This modules is for Varnish Cache what mod_remoteip is for Apache. It | 5 | This module is for Varnish Cache what =mod_remoteip= is for Apache. It |
8 | determines the actual client IP address for the connection, using the | 6 | determines the actual client IP address for the connection, using the |
9 | useragent IP address list presented by a proxies or a load balancer | 7 | useragent IP address list presented by a proxy or load balancer |
10 | via the request headers and a preconfigred list of trusted IP | 8 | via the request headers and a preconfigred list of trusted IP |
11 | addresses. For example, if your Varnish server works behind a load | 9 | addresses. For example, if your Varnish server works behind a load |
12 | balancer or yet another reverse proxy (such as pound or haproxy to | 10 | balancer or yet another reverse proxy (such as pound or haproxy to |
13 | handle the TLS connection), you can use this module to get the real | 11 | handle the TLS connection), you can use this module to get the real |
14 | incoming connection IP address from the "X-Forwarded-For" header. | 12 | incoming connection IP address from the =X-Forwarded-For= header. |
15 | 13 | ||
16 | Example | 14 | * Example |
17 | ------- | ||
18 | 15 | ||
19 | An example of using this module: | 16 | The following example VCL uses the client address deduced from the |
17 | value of the =X-Forwarded-For= header to enable the code specific for | ||
18 | hosts 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 | ||
40 | Installation | 42 | * Installation |
41 | ------------ | ||
42 | 43 | ||
43 | In order to compile the package you need to have installed | 44 | In order to compile the package you need the varnishd and varnishapi |
44 | varnishd and varnishapi package. The module has been tested with | 45 | packages. The module has been tested with Varnish version 6.3.1 and |
45 | Varnish version 6.3.1. | 46 | higher. Python 3, [[https://sourceforge.net/projects/docutils][Docutils]] |
47 | and [[http://sphinx-doc.org][Sphinx]] are needed to build documentation. | ||
48 | On Debian-based systems, this requires the =python3-docutils= and | ||
49 | =python3-sphinx= packages. | ||
46 | 50 | ||
47 | Supposing that condition is met, run: | 51 | If these prerequisites are met, run: |
48 | 52 | ||
53 | #+BEGIN_SRC shell-script | ||
49 | ./configure | 54 | ./configure |
55 | #+END_SRC | ||
50 | 56 | ||
51 | If your system offers Python versions 2.x and 3.x, it is quite often that | 57 | If both Python versions 2.x and 3.x are installed on the system, |
52 | version 2.x is used by default. In that case, we recommend to explicitly | 58 | chances are version 2 is used by default. In that case, require |
53 | require version 3.x, as shown in this example: | 59 | version 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 | ||
57 | Otherwise, the configure script should be able to automatically find | 65 | Otherwise, the configure script should be able to automatically find |
58 | the necessary components. In case it doesn't, tweak the configuration | 66 | the necessary components. In case it doesn't, tweak the configuration |
59 | variables as necessary. The most important one is PKG_CONFIG_PATH, | 67 | variables as necessary. The most important one is =PKG_CONFIG_PATH=, |
60 | which contains a path (in the UNIX sense) where the .pc files are | 68 | which contains a path (in the UNIX sense) where the =.pc= files are |
61 | located. It should contain a directory where the 'varnishapi.pc' file | 69 | located. It should contain a directory where the =varnishapi.pc= file |
62 | lives. Example usage: | 70 | lives. 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 | ||
66 | Please read the file INSTALL for a detailed discussion of available variables | 76 | Please read the file =INSTALL= for a detailed discussion of available variables |
67 | and command line options. | 77 | and command line options. |
68 | 78 | ||
69 | Once configured, do | 79 | Once configured, do |
70 | 80 | ||
71 | make | 81 | #+BEGIN_SRC shell-script |
82 | make | ||
83 | #+END_SRC | ||
72 | 84 | ||
73 | This will build the module. After this step you can optionally run | 85 | This 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 | ||
76 | Finally, run the following command as root: | 88 | Finally, run the following command as root: |
77 | 89 | ||
90 | #+BEGIN_SRC shell-script | ||
78 | make install | 91 | make install |
92 | #+END_SRC | ||
79 | 93 | ||
80 | Documentation | 94 | * Documentation |
81 | ------------- | ||
82 | 95 | ||
83 | The manual page vmod_remoteip(3) will be available after a successful | 96 | The manual page |
84 | install. 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'. | 98 | be available after a successful install. To read it without actually |
99 | installing the module, run =man src/vmod_remoteip.3= . | ||
86 | 100 | ||
87 | An online copy of the documentation is available from | 101 | An online copy of the documentation is available from |
88 | http://ps.gnu.org.ua/software/vmod-remoteip. | 102 | http://ps.gnu.org.ua/software/vmod-remoteip. |
89 | 103 | ||
104 | * Downloads | ||
105 | |||
106 | Source tarballs can be downloaded from | ||
107 | https://download.gnu.org.ua/release/vmod-remoteip. | ||
108 | |||
109 | The git repository is available at | ||
110 | http://git.gnu.org.ua/cgit/vmod-remoteip.git. | ||
111 | |||
112 | The project home page is | ||
113 | https://puszcza.gnu.org.ua/projects/vmod-remoteip. | ||
114 | |||
115 | * Copyright | ||
116 | |||
117 | Copyright (C) 2020 Sergey Poznyakoff | ||
118 | |||
119 | Permission is granted to anyone to make or distribute verbatim copies | ||
120 | of this document as received, in any medium, provided that the | ||
121 | copyright notice and this permission notice are preserved, | ||
122 | thus giving the recipient permission to redistribute in turn. | ||
123 | |||
124 | Permission is granted to distribute modified versions | ||
125 | of this document, or of portions of it, | ||
126 | under the above conditions, provided also that they | ||
127 | carry prominent notices stating who last changed them. | ||
128 | |||
90 | * Bug reporting | 129 | * Bug reporting |
91 | 130 | ||
92 | Send bug reports and suggestions to <gray@gnu.org> | 131 | Send bug reports and suggestions to <gray@gnu.org> |
93 | 132 | ||
133 | * Document settings :noexport: | ||
134 | |||
135 | Please ignore this section. It supplies the variables necessary for | ||
136 | proper 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 | ||