RewriteEngine指令

RewriteEnginedirective enables or disables the runtime rewriting engine. If it is set tooffthis module does no runtime processing at all. It does not even update theSCRIPT_URxenvironment variables.

Use this directive to disable the module instead of commenting out all theRewriteRuledirectives!

Note that, by default, rewrite configurations are not inherited. This means that you need to have aRewriteEngine ondirective for each virtual host in which you wish to use it.

RewriteLock指令

This directive sets the filename for a synchronization lockfile which mod_rewrite needs to communicate withRewriteMapprograms. Set this lockfile to a local path (not on a NFS-mounted device) when you want to use a rewriting map-program. It is not required for other types of rewriting maps.

RewriteLog指令

RewriteLogdirective sets the name of the file to which the server logs any rewriting actions it performs. If the name does not begin with a slash ('/') then it is assumed to be relative to theServer Root. The directive should occur only once per server config.

RewriteLogLevel指令

RewriteLogLeveldirective sets the verbosity level of the rewriting logfile. The default level 0 means no logging, while 9 or more means that practically all actions are logged.

To disable the logging of rewriting actions simply setLevelto 0. This disables all rewrite action logs.

RewriteMap指令

RewriteMapdirective defines aRewriting Mapwhich can be used inside rule substitution strings by the mapping-functions to insert/substitute fields through a key lookup. The source of this lookup can be of various types.

MapNameis the name of the map and will be used to specify a mapping-function for the substitution strings of a rewriting rule via one of the following constructs:

${MapName:LookupKey}
${MapName:LookupKey|DefaultValue}

When such a construct occurs the mapMapNameis consulted and the keyLookupKeyis looked-up. If the key is found, the map-function construct is substituted bySubstValue. If the key is not found then it is substituted byDefaultValueor by the empty string if noDefaultValuewas specified.

For example, you might define aRewriteMapas:

You would then be able to use this map in aRewriteRuleas follows:

The following combinations forMapType和MapSourcecan be used:

• Standard Plain Text
  MapType:txt, MapSource: Unix filesystem path to valid regular file

  This is the standard rewriting map feature where theMapSourceis a plain ASCII file containing either blank lines, comment lines (starting with a '#' character) or pairs like the following - one per line.

  MatchingKeySubstValue

  示例

  ## ## map.txt -- rewriting map ## Ralf.S.Engelschall rse # Bastard Operator From Hell Mr.Joe.Average joe # Mr. Average

  RewriteMap real-to-user txt:/path/to/file/map.txt

• Randomized Plain Text
  MapType:rnd, MapSource: Unix filesystem path to valid regular file

  This is identical to the Standard Plain Text variant above but with a special post-processing feature: After looking up a value it is parsed according to contained "|" characters which have the meaning of "or". In other words they indicate a set of alternatives from which the actual returned value is chosen randomly. For example, you might use the following map file and directives to provide a random load balancing between several back-end server, via a reverse-proxy. Images are sent to one of the servers in the 'static' pool, while everything else is sent to one of the 'dynamic' pool.

  Example:

  Rewrite map file

  ## ## map.txt -- rewriting map ## static www1|www2|www3|www4 dynamic www5|www6

  Configuration directives

  RewriteMap servers rnd:/path/to/file/map.txt

RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]
RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]

• Hash File
  MapType:dbm[=type], MapSource: Unix filesystem path to valid regular file

  Here the source is a binary format DBM file containing the same contents as aPlain Textformat file, but in a special representation which is optimized for really fast lookups. Thetypecan be sdbm, gdbm, ndbm, or db depending on compile-time settings. If thetypeis omitted, the compile-time default will be chosen. You can create such a file with any DBM tool or with the following Perl script. Be sure to adjust it to create the appropriate type of DBM. The example creates an NDBM file.

  #!/path/to/bin/perl ## ## txt2dbm -- convert txt map to dbm format ## use NDBM_File; use Fcntl; ($txtmap, $dbmmap) = @ARGV; open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n"; tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644) or die "Couldn't create $dbmmap!\n"; while () { next if (/^\s*#/ or /^\s*$/); $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/); } untie %DB; close(TXT);

  $ txt2dbm map.txt map.db

• Internal Function
  MapType:int, MapSource: Internal Apache function

  Here the source is an internal Apache function. Currently you cannot create your own, but the following functions already exists:

  • toupper:
    Converts the looked up key to all upper case.
  • tolower:
    Converts the looked up key to all lower case.
  • escape:
    Translates special characters in the looked up key to hex-encodings.
  • unescape:
    Translates hex-encodings in the looked up key back to special characters.
• External Rewriting Program
  MapType:prg, MapSource: Unix filesystem path to valid regular file

  Here the source is a program, not a map file. To create it you can use the language of your choice, but the result has to be a executable (i.e., either object-code or a script with the magic cookie trick '#!/path/to/interpreter' as the first line).

  This program is started once at startup of the Apache servers and then communicates with the rewriting engine over itsstdin和stdoutfile-handles. For each map-function lookup it will receive the key to lookup as a newline-terminated string onstdin. It then has to give back the looked-up value as a newline-terminated string onstdoutor the four-character string "NULL" if it fails (i.e., there is no corresponding value for the given key). A trivial program which will implement a 1:1 map (i.e., key == value) could be:

  #!/usr/bin/perl $| = 1; while () { # ...put here any transformations or lookups... print $_; }

  But be very careful:

  1. "Keep it simple, stupid" (KISS), because if this program hangs it will hang the Apache server when the rule occurs.
  2. Avoid one common mistake: never do buffered I/O onstdout! This will cause a deadloop! Hence the "$|=1" in the above example...
  3. Use theRewriteLockdirective to define a lockfile mod_rewrite can use to synchronize the communication to the program. By default no such synchronization takes place.

RewriteMapdirective can occur more than once. For each mapping-function use oneRewriteMapdirective to declare its rewriting mapfile. While you cannotdeclarea map in per-directory context it is of course possible tousethis map in per-directory context.

RewriteOptions指令

RewriteOptionsdirective sets some special options for the current per-server or per-directory configuration. TheOptionstring can be currently only one:

inherit

This forces the current configuration to inherit the configuration of the parent. In per-virtual-server context this means that the maps, conditions and rules of the main server are inherited. In per-directory context this means that conditions and rules of the parent directory's .htaccessconfiguration are inherited.

RewriteRule指令

RewriteRuledirective is the real rewriting workhorse. The directive can occur more than once. Each directive then defines one single rewriting rule. Thedefinition orderof these rules isimportant, because this order is used when applying the rules at run-time.

Patternis a perl compatibleregular expressionwhich gets applied to the current URL. Here "current" means the value of the URL when this rule gets applied. This may not be the originally requested URL, because any number of rules may already have matched and made alterations to it.

Some hints about the syntax of regular expressions:

Text:.Any single character[chars]Character class: One of chars[^chars]Character class: None of chars text1|text2 Alternative: text1 or text2Quantifiers:?0 or 1 of the preceding text*0 or N of the preceding text (N > 0)+1 or N of the preceding text (N > 1)Grouping:(text)Grouping of text (either to set the borders of an alternative or for making backreferences where theNth group can be used on the RHS of a RewriteRule with$N)Anchors:^Start of line anchor$End of line anchorEscaping:\char escape that particular char (for instance to specify the chars ".[]()"etc.)

For more information about regular expressions have a look at the perl regular expression manpage ("perldoc perlre"). If you are interested in more detailed information about regular expressions and their variants (POSIX regexetc.) have a look at the following dedicated book on this topic:

Mastering Regular Expressions, 2nd Edition
Jeffrey E.F. Friedl
O'Reilly & Associates, Inc. 2002
ISBN 0-596-00289-0

Additionally in mod_rewrite the NOT character ('!') is a possible pattern prefix. This gives you the ability to negate a pattern; to say, for instance: "if the current URL doesNOTmatch this pattern". This can be used for exceptional cases, where it is easier to match the negative pattern, or as a last default rule.

Substitutionof a rewriting rule is the string which is substituted for (or replaces) the original URL for whichPatternmatched. Beside plain text you can use

1. back-references$Nto the RewriteRule pattern
2. back-references%Nto the last matched RewriteCond pattern
3. server-variables as in rule condition test-strings (%{VARNAME})
4. mapping-function calls (${mapname:key|default})

Back-references are$N(N=0..9) identifiers which will be replaced by the contents of theNth group of the matchedPattern. The server-variables are the same as for theTestStringof aRewriteConddirective. The mapping-functions come from theRewriteMapdirective and are explained there. These three types of variables are expanded in the order of the above list.

As already mentioned above, all the rewriting rules are applied to theSubstitution(in the order of definition in the config file). The URL iscompletely replacedby theSubstitutionand the rewriting process goes on until there are no more rules unless explicitly terminated by aLflag - see below.

There is a special substitution string named '-' which means:NO substitution! Sounds silly? No, it is useful to provide rewriting rules whichonlymatch some URLs but do no substitution, 例如，in conjunction with theC(chain) flag to be able to have more than one pattern to be applied before a substitution occurs.

Additionally you can set specialflagsforSubstitutionby appending

[flags]

as the third argument to theRewriteRuledirective.Flagsis a comma-separated list of the following flags:

• 'chain|C' (chained with next rule)
  This flag chains the current rule with the next rule (which itself can be chained with the following rule,etc.). This has the following effect: if a rule matches, then processing continues as usual,i.e., the flag has no effect. If the rule doesnotmatch, then all following chained rules are skipped. For instance, use it to remove the ".www" part inside a per-directory rule set when you let an external redirect happen (where the ".www" part should not to occur!).
• 'cookie|CO=NAME:VAL:domain[:lifetime[:path]]' (setcookie)
  This sets a cookie on the client's browser. The cookie's name is specified byNAMEand the value isVAL. Thedomainfield is the domain of the cookie, such as '.apache.org',the optionallifetimeis the lifetime of the cookie in minutes, and the optionalpathis the path of the cookie
• 'env|E=VAR:VAL' (setenvironment variable)
  This forces an environment variable namedVARto be set to the valueVAL, whereVALcan contain regexp backreferences$N和%Nwhich 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) or CGI (例如，$ENV{'VAR'}). Additionally you can dereference it in a following RewriteCond pattern via%{ENV:VAR}. Use this to strip but remember information from URLs.
• 'forbidden|F' (force URL to beforbidden)
  This forces the current URL to be forbidden,i.e., it immediately sends back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with appropriate RewriteConds to conditionally block some URLs.
• 'gone|G' (force URL to begone)
  This forces the current URL to be gone,i.e., it immediately sends back a HTTP response of 410 (GONE). Use this flag to mark pages which no longer exist as gone.
• 'handler|H=Content-handler' (force Contenthandler)
  Force the Content-handler of the target file to beContent-handler. For instance, this can be used to simulate themod_aliasdirectiveScriptAliaswhich internally forces all files inside the mapped directory to have a handler of "cgi-script".
• 'last|L' (last rule)
  Stop the rewriting process here and don't apply any more rewriting rules. This corresponds to the Perllastcommand or thebreakcommand from the C language. Use this flag to prevent the currently rewritten URL from being rewritten further by following rules. For example, use it to rewrite the root-path URL ('/') to a real one, 例如，'/e/www/'.
• 'next|N' (next round)
  Re-run the rewriting process (starting again with the first rewriting rule). Here the URL to match is again not the original URL but the URL from the last rewriting rule. This corresponds to the Perlnextcommand or thecontinuecommand from the C language. Use this flag to restart the rewriting process,i.e., to immediately go to the top of the loop.
  But be careful not to create an infinite loop!
• 'nocase|NC' (nocase)
  This makes thePatterncase-insensitive,i.e., there is no difference between 'A-Z' and 'a-z' whenPatternis matched against the current URL.
• 'noescape|NE' (no URIescaping of output)
  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

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

  which would turn '/foo/zed' into a safe request for '/bar?arg=P1=zed'.
• 'nosubreq|NS' (used only ifno internalsub-request)
  This flag forces the rewriting engine to skip a rewriting rule if the current request is an internal sub-request. For instance, sub-requests occur internally in Apache whenmod_includetries to find out information about possible directory default files (index.xxx). On sub-requests it is not always useful and even sometimes causes a failure to if the complete set of rules are applied. Use this flag to exclude some rules.
  

  Use the following rule for your decision: whenever you prefix some URLs with CGI-scripts to force them to be processed by the CGI-script, the chance is high that you will run into problems (or even overhead) on sub-requests. In these cases, use this flag.

• 'proxy|P' (forceproxy)
  This flag forces the substitution part to be internally forced as a proxy request and immediately (i.e., rewriting rule processing stops here) put through the proxy module. You have to make sure that the substitution string is a valid URI (例如，typically starting withhttp://hostname) 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 ProxyPass directive, to map some remote stuff into the namespace of the local server.

  注意：mod_proxymust be enabled in order to use this flag.

• 'passthrough|PT' (passthrough to next handler)
  This flag forces the rewriting engine to set theurifield of the internalrequest_recstructure to the value of thefilenamefield. This flag is just a hack to be able to post-process the output ofRewriteRuledirectives byAlias,ScriptAlias,Redirect,etc.directives from other URI-to-filename translators. A trivial example to show the semantics: If you want to rewrite/abcto/defvia the rewriting engine ofmod_rewriteand then/defto/ghiwithmod_alias:

  RewriteRule ^/abc(.*) /def$1 [PT]
Alias /def /ghi

  If you omit thePTflag thenmod_rewritewill do its job fine,i.e., it rewritesuri=/abc/...tofilename=/def/...as a full API-compliant URI-to-filename translator should do. Thenmod_aliascomes and tries to do a URI-to-filename transition which will not work.

  Note:You have to use this flag if you want to intermix directives of different modules which contain URL-to-filename translators. The typical example is the use ofmod_alias和mod_rewrite..

• 'qsappend|QSA' (querystringappend)
  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.
• 'redirect|R[=code]' (forceredirect)
  PrefixSubstitutionwithhttp://thishost[:thisport]/(which makes the new URL a URI) to force a external redirection. If nocodeis 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:temp(default),permanent,seeother. Use it for rules which should canonicalize the URL and give it back to the client, 例如，translate "/~" into "/u/" or always append a slash to/u/user, etc.
  

  Note: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 withhttp://thishost[:thisport]/, 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.

• 'skip|S=num' (skip next rule(s))
  This flag forces the rewriting engine to skip the nextnumrules in sequence when the current rule matches. Use this to make pseudo if-then-else constructs: The last rule of the then-clause becomesskip=Nwhere N is the number of rules in the else-clause. (This isnotthe same as the 'chain|C' flag!)
• 'type|T=MIME-type' (force MIMEtype)
  Force the MIME-type of the target file to beMIME-type. For instance, this can be used to setup the content-type based on some conditions. For example, the following snippet allows.phpfiles to bedisplayedbymod_phpif they are called with the.phpsextension:

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

Here are all possible substitution combinations and their meanings:

Inside per-server configuration (httpd.conf)
for request "GET /somepath/pathinfo":

Given RuleResulting Substitution---------------------------------------------- ---------------------------------- ^/somepath(.*) otherpath$1 not supported, because invalid! ^/somepath(.*) otherpath$1 [R] not supported, because invalid! ^/somepath(.*) otherpath$1 [P] not supported, because invalid! ---------------------------------------------- ---------------------------------- ^/somepath(.*) /otherpath$1 /otherpath/pathinfo ^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo via external redirection ^/somepath(.*) /otherpath$1 [P] not supported, because silly! ---------------------------------------------- ---------------------------------- ^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo ^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo via external redirection ^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly! ---------------------------------------------- ---------------------------------- ^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo via external redirection ^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant) ^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo via internal proxy

Inside per-directory configuration for/somepath
(i.e., file.htaccessin dir/physical/path/to/somepathcontainingRewriteBase /somepath)
for request "GET /somepath/localpath/pathinfo":

Given RuleResulting Substitution---------------------------------------------- ---------------------------------- ^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo ^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo via external redirection ^localpath(.*) otherpath$1 [P] not supported, because silly! ---------------------------------------------- ---------------------------------- ^localpath(.*) /otherpath$1 /otherpath/pathinfo ^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo via external redirection ^localpath(.*) /otherpath$1 [P] not supported, because silly! ---------------------------------------------- ---------------------------------- ^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo ^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo via external redirection ^localpath(.*) http://thishost/otherpath$1 [P] not supported, because silly! ---------------------------------------------- ---------------------------------- ^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo via external redirection ^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant) ^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo via internal proxy

Example:

We want to rewrite URLs of the form

/Language/~Realname/.../File

into

/u/Username/.../File.Language

We take the rewrite mapfile from above and save it under/path/to/file/map.txt. Then we only have to add the following lines to the Apache server configuration file:

RewriteLog /path/to/file/rewrite.log RewriteMap real-to-user txt:/path/to/file/map.txt RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1