github.com/krum110487/go-htaccess@v0.0.0-20240316004156-60641c8e7598/tests/data/apache_2_2_34/manual/rewrite/intro.html.en (about) 1 <?xml version="1.0" encoding="ISO-8859-1"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head> 4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" /> 5 <!-- 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 This file is generated from xml source: DO NOT EDIT 8 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 9 --> 10 <title>Apache mod_rewrite Introduction - Apache HTTP Server Version 2.2</title> 11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" /> 14 <script src="../style/scripts/prettify.min.js" type="text/javascript"> 15 </script> 16 17 <link href="../images/favicon.ico" rel="shortcut icon" /><link href="http://httpd.apache.org/docs/current/rewrite/intro.html" rel="canonical" /></head> 18 <body id="manual-page"><div id="page-header"> 19 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p> 20 <p class="apache">Apache HTTP Server Version 2.2</p> 21 <img alt="" src="../images/feather.gif" /></div> 22 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div> 23 <div id="path"> 24 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.2</a> > <a href="./">Rewrite</a></div><div id="page-content"><div class="retired"><h4>Please note</h4> 25 <p> This document refers to a legacy release (<strong>2.2</strong>) of Apache httpd. The active release (<strong>2.4</strong>) is documented <a href="http://httpd.apache.org/docs/current">here</a>. If you have not already upgraded, please follow <a href="http://httpd.apache.org/docs/current/upgrading.html">this link</a> for more information.</p> 26 <p>You may follow <a href="http://httpd.apache.org/docs/current/rewrite/intro.html">this link</a> to go to the current version of this document.</p></div><div id="preamble"><h1>Apache mod_rewrite Introduction</h1> 27 <div class="toplang"> 28 <p><span>Available Languages: </span><a href="../en/rewrite/intro.html" title="English"> en </a> | 29 <a href="../fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> 30 </div> 31 32 <p>This document supplements the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> 33 <a href="../mod/mod_rewrite.html">reference documentation</a>. It 34 describes the basic concepts necessary for use of 35 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. Other documents go into greater detail, 36 but this doc should help the beginner get their feet wet. 37 </p> 38 </div> 39 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li> 40 <li><img alt="" src="../images/down.gif" /> <a href="#regex">Regular Expressions</a></li> 41 <li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">RewriteRule Basics</a></li> 42 <li><img alt="" src="../images/down.gif" /> <a href="#flags">Rewrite Flags</a></li> 43 <li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">Rewrite Conditions</a></li> 44 <li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">Rewrite maps</a></li> 45 <li><img alt="" src="../images/down.gif" /> <a href="#htaccess">.htaccess files</a></li> 46 </ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="rewritemap.html">Using RewriteMap</a></li><li><a href="advanced.html">Advanced techniques</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 47 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> 48 <div class="section"> 49 <h2><a name="introduction" id="introduction">Introduction</a></h2> 50 <p>The Apache module <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> is a very powerful and 51 sophisticated module which provides a way to do URL manipulations. With 52 it, you can do nearly all types of URL rewriting that you may need. It 53 is, however, somewhat complex, and may be intimidating to the beginner. 54 There is also a tendency to treat rewrite rules as magic incantation, 55 using them without actually understanding what they do.</p> 56 57 <p>This document attempts to give sufficient background so that what 58 follows is understood, rather than just copied blindly. 59 </p> 60 61 <p>Remember that many common URL-manipulation tasks don't require the 62 full power and complexity of <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. For simple 63 tasks, see <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and the documentation 64 on <a href="../urlmapping.html">mapping URLs to the 65 filesystem</a>.</p> 66 67 <p>Finally, before proceeding, be sure to configure 68 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>'s log level to one of the trace levels using 69 the <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code> directive. Although this 70 can give an overwhelming amount of information, it is indispensable in 71 debugging problems with <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> configuration, since 72 it will tell you exactly how each rule is processed.</p> 73 74 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> 75 <div class="section"> 76 <h2><a name="regex" id="regex">Regular Expressions</a></h2> 77 78 <p>mod_rewrite uses the <a href="http://pcre.org/">Perl Compatible 79 Regular Expression</a> vocabulary. In this document, we do not attempt 80 to provide a detailed reference to regular expressions. For that, we 81 recommend the <a href="http://pcre.org/pcre.txt">PCRE man pages</a>, the 82 <a href="http://perldoc.perl.org/perlre.html">Perl regular 83 expression man page</a>, and <a href="http://shop.oreilly.com/product/9780596528126.do">Mastering 84 Regular Expressions, by Jeffrey Friedl</a>.</p> 85 86 <p>In this document, we attempt to provide enough of a regex vocabulary 87 to get you started, without being overwhelming, in the hope that 88 <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s will be scientific 89 formulae, rather than magical incantations.</p> 90 91 <h3><a name="regexvocab" id="regexvocab">Regex vocabulary</a></h3> 92 93 <p>The following are the minimal building blocks you will need, in order 94 to write regular expressions and <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s. They certainly do not 95 represent a complete regular expression vocabulary, but they are a good 96 place to start, and should help you read basic regular expressions, as 97 well as write your own.</p> 98 99 <table> 100 <tr> 101 <th>Character</th> 102 <th>Meaning</th> 103 <th>Example</th> 104 </tr> 105 106 <tr><td><code>.</code></td><td>Matches any single 107 character</td><td><code>c.t</code> will match <code>cat</code>, 108 <code>cot</code>, <code>cut</code>, etc.</td></tr> 109 <tr><td><code>+</code></td><td>Repeats the previous match one or more 110 times</td><td><code>a+</code> matches <code>a</code>, <code>aa</code>, 111 <code>aaa</code>, etc</td></tr> 112 <tr><td><code>*</code></td><td>Repeats the previous match zero or more 113 times.</td><td><code>a*</code> matches all the same things 114 <code>a+</code> matches, but will also match an empty string.</td></tr> 115 <tr><td><code>?</code></td><td>Makes the match optional.</td><td> 116 <code>colou?r</code> will match <code>color</code> and <code>colour</code>.</td> 117 </tr> 118 <tr><td><code>^</code></td><td>Called an anchor, matches the beginning 119 of the string</td><td><code>^a</code> matches a string that begins with 120 <code>a</code></td></tr> 121 <tr><td><code>$</code></td><td>The other anchor, this matches the end of 122 the string.</td><td><code>a$</code> matches a string that ends with 123 <code>a</code>.</td></tr> 124 <tr><td><code>( )</code></td><td>Groups several characters into a single 125 unit, and captures a match for use in a backreference.</td><td><code>(ab)+</code> 126 matches <code>ababab</code> - that is, the <code>+</code> applies to the group. 127 For more on backreferences see <a href="#InternalBackRefs">below</a>.</td></tr> 128 <tr><td><code>[ ]</code></td><td>A character class - matches one of the 129 characters</td><td><code>c[uoa]t</code> matches <code>cut</code>, 130 <code>cot</code> or <code>cat</code>.</td></tr> 131 <tr><td><code>[^ ]</code></td><td>Negative character class - matches any character not specified</td><td><code>c[^/]t</code> matches <code>cat</code> or <code>c=t</code> but not <code>c/t</code></td></tr> 132 </table> 133 134 <p>In <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> the <code>!</code> character can be 135 used before a regular expression to negate it. This is, a string will 136 be considered to have matched only if it does not match the rest of 137 the expression.</p> 138 139 140 141 <h3><a name="InternalBackRefs" id="InternalBackRefs">Regex Back-Reference Availability</a></h3> 142 143 <p>One important thing here has to be remembered: Whenever you 144 use parentheses in <em>Pattern</em> or in one of the 145 <em>CondPattern</em>, back-references are internally created 146 which can be used with the strings <code>$N</code> and 147 <code>%N</code> (see below). These are available for creating 148 the strings <em>Substitution</em> and <em>TestString</em> as 149 outlined in the following chapters. Figure 1 shows to which 150 locations the back-references are transferred for expansion as 151 well as illustrating the flow of the RewriteRule, RewriteCond 152 matching. In the next chapters, we will be exploring how to use 153 these back-references, so do not fret if it seems a bit alien 154 to you at first. 155 </p> 156 157 <p class="figure"> 158 <img src="../images/rewrite_backreferences.png" alt="Flow of RewriteRule and RewriteCond matching" /><br /> 159 <dfn>Figure 1:</dfn> The back-reference flow through a rule.<br /> 160 In this example, a request for <code>/test/1234</code> would be transformed into <code>/admin.foo?page=test&id=1234&host=admin.example.com</code>. 161 </p> 162 163 164 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> 165 <div class="section"> 166 <h2><a name="rewriterule" id="rewriterule">RewriteRule Basics</a></h2> 167 <p>A <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> consists 168 of three arguments separated by spaces. The arguments are</p> 169 <ol> 170 <li><var>Pattern</var>: which incoming URLs should be affected by the rule;</li> 171 <li><var>Substitution</var>: where should the matching requests be sent;</li> 172 <li><var>[flags]</var>: options affecting the rewritten request.</li> 173 </ol> 174 175 <p>The <var>Pattern</var> is a <a href="#regex">regular expression</a>. 176 It is initially (for the first rewrite rule or until a substitution occurs) 177 matched against the URL-path of the incoming request (the part after the 178 hostname but before any question mark indicating the beginning of a query 179 string) or, in per-directory context, against the request's path relative 180 to the directory for which the rule is defined. Once a substitution has 181 occurred, the rules that follow are matched against the substituted 182 value. 183 </p> 184 185 <p class="figure"> 186 <img src="../images/syntax_rewriterule.png" alt="Syntax of the RewriteRule directive" /><br /> 187 <dfn>Figure 2:</dfn> Syntax of the RewriteRule directive. 188 </p> 189 190 191 <p>The <var>Substitution</var> can itself be one of three things:</p> 192 193 <dl> 194 <dt>A full filesystem path to a resource</dt> 195 <dd> 196 <div class="example"><p><code> 197 RewriteRule ^/games.* /usr/local/games/web 198 </code></p></div> 199 <p>This maps a request to an arbitrary location on your filesystem, much 200 like the <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> directive.</p> 201 </dd> 202 203 <dt>A web-path to a resource</dt> 204 <dd> 205 <div class="example"><p><code> 206 RewriteRule ^/foo$ /bar 207 </code></p></div> 208 <p>If <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> is set 209 to <code>/usr/local/apache2/htdocs</code>, then this directive would 210 map requests for <code>http://example.com/foo</code> to the 211 path <code>/usr/local/apache2/htdocs/bar</code>.</p> 212 </dd> 213 214 <dt>An absolute URL</dt> 215 <dd> 216 <div class="example"><p><code> 217 RewriteRule ^/product/view$ http://site2.example.com/seeproduct.html [R] 218 </code></p></div> 219 <p>This tells the client to make a new request for the specified URL.</p> 220 </dd> 221 </dl> 222 223 <p>The <var>Substitution</var> can also 224 contain <em>back-references</em> to parts of the incoming URL-path 225 matched by the <var>Pattern</var>. Consider the following:</p> 226 <div class="example"><p><code> 227 RewriteRule ^/product/(.*)/view$ /var/web/productdb/$1 228 </code></p></div> 229 <p>The variable <code>$1</code> will be replaced with whatever text 230 was matched by the expression inside the parenthesis in 231 the <var>Pattern</var>. For example, a request 232 for <code>http://example.com/product/r14df/view</code> will be mapped 233 to the path <code>/var/web/productdb/r14df</code>.</p> 234 235 <p>If there is more than one expression in parenthesis, they are 236 available in order in the 237 variables <code>$1</code>, <code>$2</code>, <code>$3</code>, and so 238 on.</p> 239 240 241 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> 242 <div class="section"> 243 <h2><a name="flags" id="flags">Rewrite Flags</a></h2> 244 <p>The behavior of a <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> can be modified by the 245 application of one or more flags to the end of the rule. For example, the 246 matching behavior of a rule can be made case-insensitive by the 247 application of the <code>[NC]</code> flag: 248 </p> 249 <div class="example"><p><code> 250 RewriteRule ^puppy.html smalldog.html [NC] 251 </code></p></div> 252 253 <p>For more details on the available flags, their meanings, and 254 examples, see the <a href="flags.html">Rewrite Flags</a> document.</p> 255 256 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> 257 <div class="section"> 258 <h2><a name="rewritecond" id="rewritecond">Rewrite Conditions</a></h2> 259 <p>One or more <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> 260 directives can be used to restrict the types of requests that will be 261 subject to the 262 following <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. The 263 first argument is a variable describing a characteristic of the 264 request, the second argument is a <a href="#regex">regular 265 expression</a> that must match the variable, and a third optional 266 argument is a list of flags that modify how the match is evaluated.</p> 267 268 <p class="figure"> 269 <img src="../images/syntax_rewritecond.png" alt="Syntax of the RewriteCond directive" /><br /> 270 <dfn>Figure 3:</dfn> Syntax of the RewriteCond directive 271 </p> 272 273 <p>For example, to send all requests from a particular IP range to a 274 different server, you could use:</p> 275 <div class="example"><p><code> 276 RewriteCond %{REMOTE_ADDR} ^10\.2\.<br /> 277 RewriteRule (.*) http://intranet.example.com$1 278 </code></p></div> 279 280 <p>When more than 281 one <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> is 282 specified, they must all match for 283 the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be 284 applied. For example, to deny requests that contain the word "hack" in 285 their query string, unless they also contain a cookie containing 286 the word "go", you could use:</p> 287 <div class="example"><p><code> 288 RewriteCond %{QUERY_STRING} hack<br /> 289 RewriteCond %{HTTP_COOKIE} !go<br /> 290 RewriteRule .* - [F] 291 </code></p></div> 292 <p>Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".</p> 293 294 <p>Matches in the regular expressions contained in 295 the <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>s can be 296 used as part of the <var>Substitution</var> in 297 the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> using the 298 variables <code>%1</code>, <code>%2</code>, etc. For example, this 299 will direct the request to a different directory depending on the 300 hostname used to access the site:</p> 301 <div class="example"><p><code> 302 RewriteCond %{HTTP_HOST} (.*)<br /> 303 RewriteRule ^/(.*) /sites/%1/$1 304 </code></p></div> 305 <p>If the request was for <code>http://example.com/foo/bar</code>, 306 then <code>%1</code> would contain <code>example.com</code> 307 and <code>$1</code> would contain <code>foo/bar</code>.</p> 308 309 310 311 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> 312 <div class="section"> 313 <h2><a name="rewritemap" id="rewritemap">Rewrite maps</a></h2> 314 315 <p>The <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive 316 provides a way to call an external function, so to speak, to do your 317 rewriting for you. This is discussed in greater detail in the <a href="rewritemap.html">RewriteMap supplementary documentation</a>.</p> 318 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> 319 <div class="section"> 320 <h2><a name="htaccess" id="htaccess">.htaccess files</a></h2> 321 322 <p>Rewriting is typically configured in the main server configuration 323 setting (outside any <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section) or 324 inside <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> 325 containers. This is the easiest way to do rewriting and is 326 recommended. It is possible, however, to do rewriting 327 inside <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> 328 sections or <a href="../howto/htaccess.html"><code>.htaccess</code> 329 files</a> at the expense of some additional complexity. This technique 330 is called per-directory rewrites.</p> 331 332 <p>The main difference with per-server rewrites is that the path 333 prefix of the directory containing the <code>.htaccess</code> file is 334 stripped before matching in 335 the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. In addition, the <code class="directive"><a href="../mod/mod_rewrite.html#rewritebase">RewriteBase</a></code> should be used to assure the request is properly mapped.</p> 336 337 </div></div> 338 <div class="bottomlang"> 339 <p><span>Available Languages: </span><a href="../en/rewrite/intro.html" title="English"> en </a> | 340 <a href="../fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> 341 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 342 <script type="text/javascript"><!--//--><![CDATA[//><!-- 343 var comments_shortname = 'httpd'; 344 var comments_identifier = 'http://httpd.apache.org/docs/2.2/rewrite/intro.html'; 345 (function(w, d) { 346 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 347 d.write('<div id="comments_thread"><\/div>'); 348 var s = d.createElement('script'); 349 s.type = 'text/javascript'; 350 s.async = true; 351 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 352 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 353 } 354 else { 355 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 356 } 357 })(window, document); 358 //--><!]]></script></div><div id="footer"> 359 <p class="apache">Copyright 2017 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 360 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 361 if (typeof(prettyPrint) !== 'undefined') { 362 prettyPrint(); 363 } 364 //--><!]]></script> 365 </body></html>