Commit a170bced authored by Richard Bowen's avatar Richard Bowen
Browse files

I used to think that the order of the flags was there for a reason, but 

nobody seems to know what that reason is. Alphabetic order is a Good
Thing.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@157365 13f79535-47bb-0310-9956-ffa450edef68
parent e9282291

docs/manual/mod/mod_rewrite.html.en

+135 −135
Original line number Diff line number Diff line
@@ -1382,33 +1382,44 @@ When using the NOT character 
      following flags: </p>



      <ul>

        <li>

          '<strong><code>redirect|R</code>

          [=<em>code</em>]</strong>' (force <a id="redirect" name="redirect"><strong>r</strong>edirect</a>)<br />

           Prefix <em>Substitution</em> with

          <code>http://thishost[:thisport]/</code> (which makes the

          new URL a URI) to force a external redirection. If no

          <em>code</em> is given a HTTP response of 302 (MOVED

          TEMPORARILY) is used. If you want to use other response

          codes in the range 300-400 just specify them as a number

          or use one of the following symbolic names:

          <code>temp</code> (default), <code>permanent</code>,

          <code>seeother</code>. Use it for rules which should

          canonicalize the URL and give it back to the client,

          <em>e.g.</em>, translate ``<code>/~</code>'' into

          ``<code>/u/</code>'' or always append a slash to

          <code>/u/</code><em>user</em>, etc.<br />

        <li>'<strong><code>chain|C</code></strong>'

        (<strong>c</strong>hained with next rule)<br />

         This flag chains the current rule with the next rule

        (which itself can be chained with the following rule,

        <em>etc.</em>). This has the following effect: if a rule

        matches, then processing continues as usual, <em>i.e.</em>,

        the flag has no effect. If the rule does

        <strong>not</strong> match, then all following chained

        rules are skipped. For instance, use it to remove the

        ``<code>.www</code>'' part inside a per-directory rule set

        when you let an external redirect happen (where the

        ``<code>.www</code>'' part should not to occur!).</li>



        <li>

		'<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'

        (set <strong>co</strong>okie)<br />

        This sets a cookie on the client's browser.  The cookie's name

        is specified by <em>NAME</em> and the value is

        <em>VAL</em>. The <em>domain</em> field is the domain of the

        cookie, such as '.apache.org',the optional <em>lifetime</em>

	is the lifetime of the cookie in minutes, and the optional 

	<em>path</em> is the path of the cookie</li>



          <p><strong>Note:</strong> When you use this flag, make

          sure that the substitution field is a valid URL! If not,

          you are redirecting to an invalid location! And remember

          that this flag itself only prefixes the URL with

          <code>http://thishost[:thisport]/</code>, rewriting

          continues. Usually you also want to stop and do the

          redirection immediately. To stop the rewriting you also

          have to provide the 'L' flag.</p>

        </li>

        <li>

        '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>'

        (set <strong>e</strong>nvironment variable)<br />

         This forces an environment variable named <em>VAR</em> to

        be set to the value <em>VAL</em>, where <em>VAL</em> can

        contain regexp backreferences <code>$N</code> and

        <code>%N</code> which will be expanded. You can use this

        flag more than once to set more than one variable. The

        variables can be later dereferenced in many situations, but

        usually from within XSSI (via <code>&lt;!--#echo

        var="VAR"--&gt;</code>) or CGI (<em>e.g.</em>

        <code>$ENV{'VAR'}</code>). Additionally you can dereference

        it in a following RewriteCond pattern via

        <code>%{ENV:VAR}</code>. Use this to strip but remember

        information from URLs.</li>



        <li>'<strong><code>forbidden|F</code></strong>' (force URL

        to be <strong>f</strong>orbidden)<br />
@@ -1425,29 +1436,14 @@ When using the NOT character 
        this flag to mark pages which no longer exist as gone.</li>



        <li>

          '<strong><code>proxy|P</code></strong>' (force

          <strong>p</strong>roxy)<br />

           This flag forces the substitution part to be internally

          forced as a proxy request and immediately (<em>i.e.</em>,

          rewriting rule processing stops here) put through the <a href="mod_proxy.html">proxy module</a>. You have to make

          sure that the substitution string is a valid URI

          (<em>e.g.</em>, typically starting with

          <code>http://</code><em>hostname</em>) which can be

          handled by the Apache proxy module. If not you get an

          error from the proxy module. Use this flag to achieve a

          more powerful implementation of the <a href="mod_proxy.html#proxypass">ProxyPass</a> directive,

          to map some remote stuff into the namespace of the local

          server. 



          <p>Notice: To use this functionality make sure you have

          the proxy module compiled into your Apache server

          program. If you don't know please check whether

          <code>mod_proxy.c</code> is part of the ``<code>httpd

          -l</code>'' output. If yes, this functionality is

          available to mod_rewrite. If not, then you first have to

          rebuild the <code class="program"><a href="../programs/httpd.html">httpd</a></code> program with mod_proxy

          enabled.</p>

        </li>

        '<strong><code>handler|H</code></strong>=<em>Content-handler</em>'

        (force Content <strong>h</strong>andler)<br />

         Force the Content-handler of the target file to be

        <em>Content-handler</em>. For instance, this can be used to

        simulate the <code>mod_alias</code> directive

        <code>ScriptAlias</code> which internally forces all files

        inside the mapped directory to have a handler of

        ``<code>cgi-script</code>''.</li>



        <li>'<strong><code>last|L</code></strong>'

        (<strong>l</strong>ast rule)<br />
@@ -1472,42 +1468,31 @@ When using the NOT character 
         <strong>But be careful not to create an infinite

        loop!</strong></li>



        <li>'<strong><code>chain|C</code></strong>'

        (<strong>c</strong>hained with next rule)<br />

         This flag chains the current rule with the next rule

        (which itself can be chained with the following rule,

        <em>etc.</em>). This has the following effect: if a rule

        matches, then processing continues as usual, <em>i.e.</em>,

        the flag has no effect. If the rule does

        <strong>not</strong> match, then all following chained

        rules are skipped. For instance, use it to remove the

        ``<code>.www</code>'' part inside a per-directory rule set

        when you let an external redirect happen (where the

        ``<code>.www</code>'' part should not to occur!).</li>

        <li>'<strong><code>nocase|NC</code></strong>'

        (<strong>n</strong>o <strong>c</strong>ase)<br />

         This makes the <em>Pattern</em> case-insensitive,

        <em>i.e.</em>, there is no difference between 'A-Z' and

        'a-z' when <em>Pattern</em> is matched against the current

        URL.</li>



        <li>

        '<strong><code>type|T</code></strong>=<em>MIME-type</em>'

        (force MIME <strong>t</strong>ype)<br />

         Force the MIME-type of the target file to be

        <em>MIME-type</em>. For instance, this can be used to

        setup the content-type based on some conditions.

        For example, the following snippet allows <code>.php</code> files to

        be <em>displayed</em> by <code>mod_php</code> if they are called with

        the <code>.phps</code> extension:

          '<strong><code>noescape|NE</code></strong>'

          (<strong>n</strong>o URI <strong>e</strong>scaping of

          output)<br />

           This flag keeps mod_rewrite from applying the usual URI

          escaping rules to the result of a rewrite. Ordinarily,

          special characters (such as '%', '$', ';', and so on)

          will be escaped into their hexcode equivalents ('%25',

          '%24', and '%3B', respectively); this flag prevents this

          from being done. This allows percent symbols to appear in

          the output, as in 

<div class="example"><p><code>

            RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]

    RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]

</code></p></div>

        </li>



        <li>

        '<strong><code>handler|H</code></strong>=<em>Content-handler</em>'

        (force Content <strong>h</strong>andler)<br />

         Force the Content-handler of the target file to be

        <em>Content-handler</em>. For instance, this can be used to

        simulate the <code>mod_alias</code> directive

        <code>ScriptAlias</code> which internally forces all files

        inside the mapped directory to have a handler of

        ``<code>cgi-script</code>''.</li>

          which would turn '<code>/foo/zed</code>' into a safe

          request for '<code>/bar?arg=P1=zed</code>'. 

        </li>



        <li>

          '<strong><code>nosubreq|NS</code></strong>' (used only if
@@ -1531,38 +1516,29 @@ When using the NOT character 
          sub-requests. In these cases, use this flag.</p>

        </li>



        <li>'<strong><code>nocase|NC</code></strong>'

        (<strong>n</strong>o <strong>c</strong>ase)<br />

         This makes the <em>Pattern</em> case-insensitive,

        <em>i.e.</em>, there is no difference between 'A-Z' and

        'a-z' when <em>Pattern</em> is matched against the current

        URL.</li>



        <li>'<strong><code>qsappend|QSA</code></strong>'

        (<strong>q</strong>uery <strong>s</strong>tring

        <strong>a</strong>ppend)<br />

         This flag forces the rewriting engine to append a query

        string part in the substitution string to the existing one

        instead of replacing it. Use this when you want to add more

        data to the query string via a rewrite rule.</li>



        <li>

          '<strong><code>noescape|NE</code></strong>'

          (<strong>n</strong>o URI <strong>e</strong>scaping of

          output)<br />

           This flag keeps mod_rewrite from applying the usual URI

          escaping rules to the result of a rewrite. Ordinarily,

          special characters (such as '%', '$', ';', and so on)

          will be escaped into their hexcode equivalents ('%25',

          '%24', and '%3B', respectively); this flag prevents this

          from being done. This allows percent symbols to appear in

          the output, as in 

<div class="example"><p><code>

    RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]

</code></p></div>

          '<strong><code>proxy|P</code></strong>' (force

          <strong>p</strong>roxy)<br />

           This flag forces the substitution part to be internally

          forced as a proxy request and immediately (<em>i.e.</em>,

          rewriting rule processing stops here) put through the <a href="mod_proxy.html">proxy module</a>. You have to make

          sure that the substitution string is a valid URI

          (<em>e.g.</em>, typically starting with

          <code>http://</code><em>hostname</em>) which can be

          handled by the Apache proxy module. If not you get an

          error from the proxy module. Use this flag to achieve a

          more powerful implementation of the <a href="mod_proxy.html#proxypass">ProxyPass</a> directive,

          to map some remote stuff into the namespace of the local

          server. 



          which would turn '<code>/foo/zed</code>' into a safe

          request for '<code>/bar?arg=P1=zed</code>'. 

          <p>Notice: To use this functionality make sure you have

          the proxy module compiled into your Apache server

          program. If you don't know please check whether

          <code>mod_proxy.c</code> is part of the ``<code>httpd

          -l</code>'' output. If yes, this functionality is

          available to mod_rewrite. If not, then you first have to

          rebuild the <code class="program"><a href="../programs/httpd.html">httpd</a></code> program with mod_proxy

          enabled.</p>

        </li>



        <li>
@@ -1602,6 +1578,41 @@ When using the NOT character 
          <code>mod_rewrite</code>..</p>

        </li>



        <li>'<strong><code>qsappend|QSA</code></strong>'

        (<strong>q</strong>uery <strong>s</strong>tring

        <strong>a</strong>ppend)<br />

         This flag forces the rewriting engine to append a query

        string part in the substitution string to the existing one

        instead of replacing it. Use this when you want to add more

        data to the query string via a rewrite rule.</li>



         <li>'<strong><code>redirect|R</code>

          [=<em>code</em>]</strong>' (force <a id="redirect" name="redirect"><strong>r</strong>edirect</a>)<br />

           Prefix <em>Substitution</em> with

          <code>http://thishost[:thisport]/</code> (which makes the

          new URL a URI) to force a external redirection. If no

          <em>code</em> is given a HTTP response of 302 (MOVED

          TEMPORARILY) is used. If you want to use other response

          codes in the range 300-400 just specify them as a number

          or use one of the following symbolic names:

          <code>temp</code> (default), <code>permanent</code>,

          <code>seeother</code>. Use it for rules which should

          canonicalize the URL and give it back to the client,

          <em>e.g.</em>, translate ``<code>/~</code>'' into

          ``<code>/u/</code>'' or always append a slash to

          <code>/u/</code><em>user</em>, etc.<br />

           



          <p><strong>Note:</strong> When you use this flag, make

          sure that the substitution field is a valid URL! If not,

          you are redirecting to an invalid location! And remember

          that this flag itself only prefixes the URL with

          <code>http://thishost[:thisport]/</code>, rewriting

          continues. Usually you also want to stop and do the

          redirection immediately. To stop the rewriting you also

          have to provide the 'L' flag.</p>

        </li>



        <li>'<strong><code>skip|S</code></strong>=<em>num</em>'

        (<strong>s</strong>kip next rule(s))<br />

         This flag forces the rewriting engine to skip the next
@@ -1613,30 +1624,19 @@ When using the NOT character 
        'chain|C' flag!)</li>



        <li>

        '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>'

        (set <strong>e</strong>nvironment variable)<br />

         This forces an environment variable named <em>VAR</em> to

        be set to the value <em>VAL</em>, where <em>VAL</em> can

        contain regexp backreferences <code>$N</code> and

        <code>%N</code> which will be expanded. You can use this

        flag more than once to set more than one variable. The

        variables can be later dereferenced in many situations, but

        usually from within XSSI (via <code>&lt;!--#echo

        var="VAR"--&gt;</code>) or CGI (<em>e.g.</em>

        <code>$ENV{'VAR'}</code>). Additionally you can dereference

        it in a following RewriteCond pattern via

        <code>%{ENV:VAR}</code>. Use this to strip but remember

        information from URLs.</li>

        '<strong><code>type|T</code></strong>=<em>MIME-type</em>'

        (force MIME <strong>t</strong>ype)<br />

         Force the MIME-type of the target file to be

        <em>MIME-type</em>. For instance, this can be used to

        setup the content-type based on some conditions.

        For example, the following snippet allows <code>.php</code> files to

        be <em>displayed</em> by <code>mod_php</code> if they are called with

        the <code>.phps</code> extension:

        <div class="example"><p><code>

            RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]

        </code></p></div>

        </li>



        <li>

		'<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'

        (set <strong>co</strong>okie)<br />

        This sets a cookie on the client's browser.  The cookie's name

        is specified by <em>NAME</em> and the value is

        <em>VAL</em>. The <em>domain</em> field is the domain of the

        cookie, such as '.apache.org',the optional <em>lifetime</em>

	is the lifetime of the cookie in minutes, and the optional 

	<em>path</em> is the path of the cookie</li>



      </ul>

docs/manual/mod/mod_rewrite.xml

+138 −138

File changed.

Preview size limit exceeded, changes collapsed.