1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="access.xml.meta">
24 <parentdocument href="./">Rewrite</parentdocument>
26 <title>Using mod_rewrite to control access</title>
30 <p>This document supplements the <module>mod_rewrite</module>
31 <a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
32 how you can use <module>mod_rewrite</module> to control access to
33 various resources, and other related techniques.
34 This includes many examples of common uses of mod_rewrite,
35 including detailed descriptions of how each works.</p>
37 <note type="warning">Note that many of these examples won't work unchanged in your
38 particular server configuration, so it's important that you understand
39 them, rather than merely cutting and pasting the examples into your
43 <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
44 <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
45 <seealso><a href="remapping.html">Redirection and remapping</a></seealso>
46 <!-- <seealso><a href="access.html">Controlling access</a></seealso> -->
47 <seealso><a href="vhosts.html">Virtual hosts</a></seealso>
48 <seealso><a href="proxy.html">Proxying</a></seealso>
49 <seealso><a href="rewritemap.html">Using RewriteMap</a></seealso>
50 <seealso><a href="advanced.html">Advanced techniques</a></seealso>
51 <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
53 <section id="blocked-inline-images">
55 <title>Forbidding Image "Hotlinking"</title>
61 <p>The following technique forbids the practice of other sites
62 including your images inline in their pages. This practice is
63 often referred to as "hotlinking", and results in
64 your bandwidth being used to serve content for someone else's
71 <p>This technique relies on the value of the
72 <code>HTTP_REFERER</code> variable, which is optional. As
73 such, it's possible for some people to circumvent this
74 limitation. However, most users will experience the failed
75 request, which should, over time, result in the image being
76 removed from that other site.</p>
77 <p>There are several ways that you can handle this
80 <p>In this first example, we simply deny the request, if it didn't
81 initiate from a page on our site. For the purpose of this example,
82 we assume that our site is <code>www.example.com</code>.</p>
84 <!-- TODO: Add discussion here of why we have !^$ in there. -->
86 <highlight language="config">
87 RewriteCond "%{HTTP_REFERER}" "!^$"
88 RewriteCond "%{HTTP_REFERER}" "!www.example.com" [NC]
89 RewriteRule "\.(gif|jpg|png)$" "-" [F,NC]
92 <p>In this second example, instead of failing the request, we display
93 an alternate image instead.</p>
95 <highlight language="config">
96 RewriteCond "%{HTTP_REFERER}" "!^$"
97 RewriteCond "%{HTTP_REFERER}" "!www.example.com" [NC]
98 RewriteRule "\.(gif|jpg|png)$" "/images/go-away.png" [R,NC]
101 <p>In the third example, we redirect the request to an image on some
104 <highlight language="config">
105 RewriteCond "%{HTTP_REFERER}" "!^$"
106 RewriteCond "%{HTTP_REFERER}" "!www.example.com" [NC]
107 RewriteRule "\.(gif|jpg|png)$" "http://other.example.com/image.gif" [R,NC]
110 <p>Of these techniques, the last two tend to be the most effective
111 in getting people to stop hotlinking your images, because they will
112 simply not see the image that they expected to see.</p>
119 <p>If all you wish to do is deny access to the resource, rather
120 than redirecting that request elsewhere, this can be
121 accomplished without the use of mod_rewrite:</p>
123 <highlight language="config">
124 SetEnvIf Referer "example\.com" localreferer
125 <FilesMatch "\.(jpg|png|gif)$">
126 Require env localreferer
134 <section id="blocking-of-robots">
136 <title>Blocking of Robots</title>
139 <dt>Description:</dt>
143 In this recipe, we discuss how to block persistent requests from
144 a particular robot, or user agent.</p>
146 <p>The standard for robot exclusion defines a file,
147 <code>/robots.txt</code> that specifies those portions of your
148 website where you wish to exclude robots. However, some robots
149 do not honor these files.
152 <p>Note that there are methods of accomplishing this which do
153 not use mod_rewrite. Note also that any technique that relies on
154 the clients <code>USER_AGENT</code> string can be circumvented
155 very easily, since that string can be changed.</p>
161 <p>We use a ruleset that specifies the directory to be
162 protected, and the client <code>USER_AGENT</code> that
163 identifies the malicious or persistent robot.</p>
165 <p>In this example, we are blocking a robot called
166 <code>NameOfBadRobot</code> from a location
167 <code>/secret/files</code>. You may also specify an IP address
168 range, if you are trying to block that user agent only from the
169 particular source.</p>
171 <highlight language="config">
172 RewriteCond "%{HTTP_USER_AGENT}" "^NameOfBadRobot"
173 RewriteCond "%{REMOTE_ADDR}" "=123\.45\.67\.[8-9]"
174 RewriteRule "^/secret/files/" "-" [F]
182 Rather than using mod_rewrite for this, you can accomplish the
183 same end using alternate means, as illustrated here:
185 <highlight language="config">
186 SetEnvIfNoCase User-Agent "^NameOfBadRobot" goaway
187 <Location "/secret/files">
190 Require not env goaway
195 As noted above, this technique is trivial to circumvent, by simply
196 modifying the <code>USER_AGENT</code> request header. If you
197 are experiencing a sustained attack, you should consider blocking
198 it at a higher level, such as at your firewall.
207 <section id="host-deny">
209 <title>Denying Hosts in a Blacklist</title>
212 <dt>Description:</dt>
215 <p>We wish to maintain a blacklist of hosts, rather like
216 <code>hosts.deny</code>, and have those hosts blocked from
217 accessing our server.</p>
223 <highlight language="config">
225 RewriteMap hosts-deny "txt:/path/to/hosts.deny"
226 RewriteCond "${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}" "!=NOT-FOUND" [OR]
227 RewriteCond "${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}" "!=NOT-FOUND"
228 RewriteRule "^" "-" [F]
235 ## ATTENTION! This is a map, not a list, even when we treat it as such.<br />
236 ## mod_rewrite parses it for key/value pairs, so at least a<br />
237 ## dummy value "-" must be present for each entry.<br />
240 193.102.180.41 -<br />
241 bsdti1.sdm.de -<br />
242 192.76.162.40 -<br />
249 The second RewriteCond assumes that you have HostNameLookups turned
250 on, so that client IP addresses will be resolved. If that's not the
251 case, you should drop the second RewriteCond, and drop the
252 <code>[OR]</code> flag from the first RewriteCond.
259 <section id="referer-deflector">
261 <title>Referer-based Deflector</title>
264 <dt>Description:</dt>
267 <p>Redirect requests based on the Referer from which the request
268 came, with different targets per Referer.</p>
274 <p>The following ruleset uses a map file to associate each Referer
275 with a redirection target.</p>
277 <highlight language="config">
278 RewriteMap deflector "txt:/path/to/deflector.map"
280 RewriteCond "%{HTTP_REFERER}" !=""
281 RewriteCond "${deflector:%{HTTP_REFERER}}" "=-"
282 RewriteRule "^" "%{HTTP_REFERER}" [R,L]
284 RewriteCond "%{HTTP_REFERER}" !=""
285 RewriteCond "${deflector:%{HTTP_REFERER}|NOT-FOUND}" "!=NOT-FOUND"
286 RewriteRule "^" "${deflector:%{HTTP_REFERER}}" [R,L]
289 <p>The map file lists redirection targets for each referer, or, if
290 we just wish to redirect back to where they came from, a "-" is
291 placed in the map:</p>
293 <highlight language="config">
298 http://badguys.example.com/bad/index.html -
299 http://badguys.example.com/bad/index2.html -
300 http://badguys.example.com/bad/index3.html http://somewhere.example.com/