README.md
1# mod_cloudflare for Apache #
2Copyright CloudFlare Inc. 2016
3
4## mod_cloudflare.c ##
5
6Based on mod_remoteip.c, this Apache extension will replace the remote_ip variable in user's logs with the correct remote IP sent from CloudFlare. The module only performs the IP substitution for requests originating from CloudFlare IPs by default.
7
8In addition to this, the extension will also set the HTTPS environment variable to "on" in cases where Flexible SSL is in use. This prevents software such as WordPress from being broken by Flexible SSL.
9
10To install, either run apxs2 directly against the .c source file:
11
12 $ apxs2 -a -i -c mod_cloudflare.c
13
14An alternative way to install is to use GNU autotools, which requires that autoconf and automake already be installed:
15
16 $ autoconf
17 $ ./configure
18 $ make
19 $ make install
20
21### OS Support ###
22
23- CentOS - Supported
24- CloudLinux - Not Supported
25
26No further configuration is needed. However, if you wish to override the default values, the following directives are exposed:
27
28### CloudFlareRemoteIPHeader ###
29
30This specifies the header which contains the original IP. Default:
31
32 CloudFlareRemoteIPHeader CF-Connecting-IP
33
34### CloudFlareRemoteIPTrustedProxy ###
35
36This is to add additional trusted IP addresses or ranges from which we will allow `CloudFlareRemoteIPHeader` to be used from. We will rewrite remote IPs and the SSL variable (in the case of Flexible SSL) from these trusted IPs, additionally `DenyAllButCloudflare` will not deny requests from IPs listed here. See [here][1] for a complete list.
37
38### DenyAllButCloudFlare ###
39
40When this is set, we will deny requests from IPs which aren't in the `CloudFlareRemoteIPTrustedProxy` directive or are not from a Cloudflare IP.
41
42Note that by default, `DenyAllButCloudflare` will not allow Remote IPs, they will need to be whitelisted through `CloudFlareRemoteIPTrustedProxy`.
43
44## Loading the Module ##
45
46Note that on some systems, you may have to add a `LoadModule` directive manually. This should look like:
47
48 LoadModule cloudflare_module /usr/lib/apache2/modules/mod_cloudflare.so
49
50Replace `/usr/lib/apache2/modules/mod_cloudflare.so` with the path to `mod_cloudflare.so` on your system.
51
52## Installing apxs/apxs2 ##
53
54If you cannot find `apxs` or `apxs2`, install `apache2-dev` on Debian and Ubuntu, or `httpd-devel` on Red Hat and CentOS:
55
56 $ apt-get install apache2-dev
57 $ yum install httpd-devel
58
59## Additional Notes ##
60
61- If mod\_cloudflare and mod\_remoteip are enabled on the same web server, the server will crash if they both try to set the remote IP to a different value.
62- Enabling mod\_cloudflare will not effect the performance of Apache in any noticeable manner. AB testing both over LAN and WAN show no equivalent numbers with and without mod\_cloudflare.
63- If you like, you may also add the directive `DenyAllButCloudFlare`. This will result in all requests from IPs which are not in the `CloudFlareRemoteIPTrustedProxy` range being denied with a status of 403.
64
65 [1]: https://www.cloudflare.com/ips
66