윈도우 서버 IIS 6 이하 reWrite

Ionic's Isapi Rewrite Filter (IIRF)

http://www.codeplex.com/IIRF

DonationWare

 

수정법
---------------------------------

설정의 수정은 IsapiRewrite4.ini 파일을 통해서 가능.

%SystemRoot%\System32\inetsrv\IIRF 에 설치한 필자의 경우

# notepad %SystemRoot%\System32\inetsrv\IIRF\IsapiRewrite4.ini

해서 수정한다.

수정의 적용은 w3svc 서비스 재로딩이 필요 없이 실시간 반영된다.

 

설치법
---------------------------------

간단하지만, 수동이다.
ISAPI Filter 로의 설치가 필요하다.
IIS MMC panel을 통해 시행하라.
모든 웹사이트 또는 부분적 웹사이트에 필터를 추가.

다음을 따라해본다:

1. Copy the filter DLL (IsapiRewrite4.dll) to an appropriate folder,
such as c:\windows\system32\inetsrv\IIRF .  Or it could be in a totally
separate directory tree.  It's up to you.

The only thing - don't put it in the web document tree.  (it causes
problems with detecting changes in the ini file.  There's more about
this later in the readme).

Place the settings file (IsapiRewrite4.ini), in the same directory as
the DLL file. The filter will look for its settings in that file.

2. Grant READ permissions on the DLL, the ini file, and the containing
directory to the appropriate Windows principal (IUSR_hostname).  On
Windows Server, also grant Read permissions to the IIS_WPG group for all
these things.

3. 인터넷 서비스 관리자를 연다 (MMC).
시작...실행...%SystemRoot%\System32\inetsrv\iis.msc
또는 you can browse on WinXP to Start...Control
Panel...Administrative Tools....Internet Information Services.

4. Select the appropriate level for the ISAPI filter:

- to use the ISAPI filter with all Web sites, select the "Web Sites" 
   icon just under the machine name.
- to use the ISAPI filter with a specific Web site, select the icon
   for that Web site (for example, the default Web site).
5. Right-click the level (icon) that you selected. Click the
   Properties button.

6. ISAPI 필터 탭 클릭.

7. Add 클릭.

8. Type a name for the ISAPI filter. Eg, "Ionic Rewriter".

9. Click Browse and select the ISAPI filter DLL that you copied in
   step 1.

10. OK를 클릭.

11. IISADMIN 서비스 중지. 하는법은, 명령표시줄에서 net stop
    iisadmin /y 을 입력하던지 관리자 도구들에 있는 서비스애플릿을 사용.

12. Start the World Wide Web Publishing Service.  Do this by typing
    net start w3svc at a command prompt, or by using the Services
    applet that is located in Administrative Tools.

더 자세한것은, general instructions from Microsoft on how to do install ISAPI filters, 여길 보시오:
http://support.microsoft.com/kb/150312/EN-US/

----

Windows Server 2003 또는 2008 에서, 다중 사이트 운영중이고 IIRF의 다중 설치를 원한다면, DLL 을 설치하고 서로다른 공간에 .ini 파일을 두고 각각의 웹사이트에 ISAPI filter 설정을 적용한다.
Obviously, the ini files may be different for each installation.

WS2003/2008 에서, you must add IIRF to the allowed Web Service
Extensions, for each web that uses IIRF. Each instance of IIRF
needs to be added to the list.

IIRF 는 IIS5 (업그레이드 요망됨), XP상의 IIS6 와 IIS7, Vista, WS2003, 그리고 WS2008 에서 돌아간다.

If you want to use the IirfVersion utilities (IirfVersion.exe,
TestParse.exe, etc), you can copy the exe's into the same directory as
you copied the IsapiRewrite4.dll .

Or, you can set up a separate directory, off the web server completely.

설치 위치와 IIS Metabase
--------------------------------------------

metabase 를 백업하길 원한다면, \windows\system32\intesrv 에 IIRF 를 설치하지 마라. 
알다시피, you can install IIRF in any directory you choose.  Installing IIRF in
\windows\system32\intesrv causes an inconvenience with IIS
administrative operations. 

In this case, any changes to the IIS configuration (adding a new
website, changing a virtual directory, turning on logging, etc.)
requires a service stop & start to ensure that the changes are
saved.  Also, if you try to back-up the IIS configuration
(right-clicking on the server, selecting Backup/Restore and then
creating a new backup), you will get an error that reads "The
process cannot access the file because it is being used by
another process."  In order to backup the IIS configuration in
this case, you need to stop IIS, and then perform the backup.
All of this can be inconvenient.

Why does this happen?  IIRF starts a thread that watches for
changes in a directory via the Win32 call
ReadDirectoryChangesW(). This essentially will keep open a file
in the directory. If the IIRF directory happens to be the same
directory as that which stores the IIS metabase, then you will
have this problem.

The solution is to install IIRF in a directory other than inetsrv.
하위폴더를 사용하면 좋다 (예를들어,  c:\windows\system32\inetsrv\IIRF)

Troubleshooting Installation
---------------------------------

See this link for help on troubleshooting:
http://blogs.msdn.com/david.wang/archive/2005/06/21/HOWTO_Diagnose_and_Fix_Common_ISAPI_Filter_Installation_Failures.aspx

On Filter Settings
---------------------------------

All the settings for the filter are set in the .ini file.  The DLL
locates the ini file by looking in the same directory as that which
contains the IsapiRewrite4.dll.  In other words, you MUST put the ini
file in the same directory as where you put the dll.

The ini file is automatically reloaded when it changes.  You do not need
to restart IIS in order to load in new settings.  They are loaded
dynamically.  It is also possible to stop the IIS Server, modify the ini
file, and then restart the server. It's possible to do this, but not necessary.

If you save an ini file with a bad format, IIRF will not load
the new settings, and will revert to the last good
configuration.  Take care to save valid ini files.  Check the
IIRF log to verify that the ini file you save, has actually been
successfully loaded. 

Also, with a running IIS server, try not to make many small changes in
the ini file, saving the file in each step. With each save of the file,
IIRF will try to reload the settings.  It is better to make all the
changes and save the file once.

On Logging
---------------------------------

Logging is relatively expensive.  Each log statement writes and
flushes the file.  For best performance, Turn logging down as
low as possible (to zero).  For general usage or monitoring of
URL re-writing, set LogLevel to 3.   For troubleshooting, set
LogLevel to 5. In between values are ok, too.

If you have a low-volume website, 10 hits per second or less,
you can probably safely keep logging on at level 3.  Mind the
disk space, though.  There is no auto-rollover of logfiles as
the file grows in size. You should add management of IIRF log
files to the list of tasks you periodically (and we hope
automatically) do on your web server, like archiving IIS logs,
etc.

Configuring the filter
---------------------------------

You specify settings for this ISAPI in an ini file.  The
location of the Ini file is in the same directory as the DLL,
with the same name, but with an extension of .ini.  By default
it is IsapiRewrite4.ini .

The format of the ini file is similar in philosophy to that of
the properties file used by Apache's mod_rewrite.  Because this
ISAPI is simpler in intent and execution than mod_rewrite, the
ini file is correspondingly simpler.

These are the directives supported for the ini file:

  RewriteRule
  RedirectRule
  RewriteHeader
  RewriteCond
  RewriteLog
  RewriteLogLevel
  RewriteFilterPriority
  IterationLimit
  MaxMatchCount 
  StrictParsing

The directive names are NOT case-sensitive.  Whitespace
following the directive name is not significant.

A number of sample ini files are included in this
shipment. Check the tests and examples directories.

Below is an overview of the meaning of each of the directives:

RewriteRule <url-pattern> <replacement-string>   [<modifiers>]
----------------------------------------------------------------

With this directive, administrators can specify how to map and transform
incoming URL requests.  This directive may occur more than once in the
file, and usually does.  There are 2 required arguments for the
directive: the url-pattern (which is a regular expression pattern) and a
replacement string.

There is a 3rd "modifiers" argument, which is optional. We'll describe
that in a bit. These three arguments are separated by whitespace.

Here's how it works: when the server gets an incoming URL request (the
URL that the browser sends to the server), the url-pattern is matched
against the incoming URL request.  If the pattern matches, then the
request is rewritten to the request specified in the replacement string.

Keep in mind that "the request is rewritten" means that on the server
side, the result of the rewrite is served.  The result could be a static
page, or an image file, or a dynamic page (like a php page or an aspx
page).  Regardless of the result of the URL rewrite, the browser is not
notified that a rewrite has occurred. 

In a rewrite, the browser may ask for /definition/football.htm and may
get /definition/soccer.htm, but is not aware that the server has done
this substitution. 

This is a cause for confusion among many people, so I will repeat it:
the browser cannot detect if the server has rewritten its request.
There is no difference to the browser.  If a server URL rewrite occurs,
the browser is not informed.  No update of the address in the browser
URL address bar occurs, in the event of a rewrite!

Are we clear on that?

Example 1:

  RewriteRule  ^/cart  /ViewCart.aspx 

The above rule allows the user to enter something like
http://server.com/cart in the browser address bar, and then on the
server side, the resource that is actually run and executed is
ViewCart.aspx page.  The browser does not display the ViewCart.aspx URL
in the address bar (it remains as http://server.com/cart), though the
result of the ViewCart.aspx page execution is displayed in the browser
window.

In the url-pattern you can include "wildcard" type pattern matches
according to the regular expression language.  And within the
replacement string you can insert references to the matches from the url
pattern.

For example, the following rule will transform incoming URLs
that contain original into URLs that contain modified:

Example 2:

  RewriteRule  ^/original/(.*).html  /modified/$1.aspx

The wildcard in this case is (.*), which says "match any sequence of
characters".   The reference to the thing the wildcard matched is $1.

With this rule, an incoming URL like this:
   /original/subdir/page.html

will cause this to be executed on the server side:
   /modified/subdir/page.aspx

Note: Because this is a rewrite, The browser still displays
/original/subdir/page.html in the address bar.

Notice that the replacement string does not begin with http://server...
The replacement string should be the URL *after* the scheme and hostname
and port.

The Regular Expression support is from PCRE.  It provides a
fully-powered, perl-compatible, regular expression library.  For
example, with IIRF, you can use rules to transform path elements
into query string params.

Example 3:

   RewriteRule  ^/dinoch/album/([^/]+)/([^/]+).(jpg|JPG|PNG)   /chiesa/pics.aspx?d=$1&p=$2.$3

The above example says, for a URL request for an image, like
   /dinoch/album/foo/bar.jpg

rewrite the URL to:
   /chiesa/pics.aspx?d=foo&p=bar.jpg

Remember, when I say "rewrite the URL" - that is a SERVER SIDE
OPERATION.  The browser is not aware of the rewrite.  IF you are
thinking, "rewrite means update the address that is shown in the browser
address bar" you are thinking incorrectly.

Once this URL is rewritten on the server side, the request would then be
handled by the ASP.NET engine, in the pics.aspx module, which could
inject whatever processing it needed to, before serving the bar.jpg
image. For example, thumbnailing the image, auditing the access count,
authorizing the request, or what have you.

You could also do the converse, such as rewriting an ASPX request,
to a URL for a binary image file.  Such as: 

Example 4:

   RewriteRule  ^/chiesa/pics.aspx?d=([^&]+)&p=(.+).(jpg|JPG|PNG)   /dinoch/album/$1/$2.$3

With this rule, an incoming request like
   /chiesa/pics.aspx?d=foo&p=Alpha.jpg

would get rewritten to
   /dinoch/album/foo/Alpha.jpg

and could then get served by the ISAPI for jpg files (typically
just directly served by IIS). I think**.  This is a performance
optimization, because with this rewrite rule, ASP.NET would
presumably not get involved with serving JPG files (unless the
.jpg extension were mapped to the ASP.NET ISAPI). 

[** because as of v1.2.10, IIRF uses SF_NOTIFY_AUTH_COMPLETE, it
may be "too late" to rewrite from an aspx to a static file like
a .jpg.  Not sure. Try it and let me know.  ]

The replacement string can contain:

- constant text

- references to the matched substrings in the input, in the form
  of $n, where n is a digit. (Eg $1, $2, $3...).  These are
  called back-references.

- references to the matched substrings in the most recently
  evaluated RewriteCond associated to that RewriteRule.  [Don't
  worry too much about RewriteCond just yet.  We'll get to that
  in a minute. Just be aware that the replacement string can
  contain references to matched substrings from a RewriteCond.]
  These take the form %n, where n is a digit. (Eg %1, %2, %3...)

- references to server variables.  Eg, %{QUERY_STRING} in the
  replacement pattern embeds the query string of the incoming
  request, into the output (rewritten) URL.

- case folding directives : #L #U #E #l #u
  These work just as \L \U \E \l \u do in PERL.
  In other words, everything between #L and #E says "force
  lowercase".  Everything between #U and #E says "Force upper".
  and the #u and #l are one-character versions of those
  directives.

- a special pattern, '-', which tells IIRF to "do nothing".  In other
  words, not rewrite the URL.  You can use this with the [L]
  flag to eliminate certain URL patterns from further consideration.

Example 5:

   RewriteRule ^/([^/]+)/([^/]+)/(\d+)/(\d+)/$  /index.php?option=com_$1&task=$2&id=$3&item=$4

This rule says, given a URL like this:
   /content/blogcategory/0/33/
rewrite it to this:
   /index.php?option=com_content&task=blogcategory&id=0&item=33

This is especially useful for search engine optimization of
URLs, for Mambo, or is it Joomla?  (I am no expert on Mambo or
Joomla).

Example 6:

   RewriteRule ^(/[^.]+)$ /dispatch.fcgi?$1

This works with Ruby-on-Rails.  The pattern will match any URL
without a full-stop, rewriting it to be handled by
dispatch.fcgi. Should you not want to run FastCGI, you'll need
to change "dispatch.fcgi" to "dispatch.cgi", and create the
appropriate mapping within IIS. 

When mapping to dispatch.fcgi or .cgi, you may want to apply the
[L] modifier flag, which you will learn about in the next
section.

These are just a few examples.  As you can see, in the
RewriteRule pattern matching, you have a great deal of
flexibility.  In fact with IIRF, you have the full power of PCRE
regex support, including zero-width lookaheads, negation, match
counts, case-insensitivity, and so on.

See the provided Ini files, within the various test directories,
for more examples.

In IIRF V1.2.12 and prior, the replacement string cannot contain
spaces !  In v1.2.12, you can include spaces (and ampersands and
other characcters) by URL-escaping them.  For example, to
include a space in a replacement string, you would use %%20. 

Example 7:

  RewriteRule  ^/downloads/myapp.exe /downloads/myapp%%201.2.exe

The above rule would rewrite an incoming request for myapp.exe
to "myapp 1.2.exe"

For more on this, in the tests directory, see the
SpacesInReplacementString sub-directory.

Including case-folding directives  in the replacement string,
tells the IIRF engine to change the case of the output URL.  The
#L...#E tells IIRF to fold case downward between the #L and the
#E.  The #U...#E sequence tells IIRF to fold case upward. 
The #l and #u directives tell IIRF to fold the case of the next
character only, either downward or upward.

We do not use backslash, because in Windows, paths use
backslashes, and in some cases IIRF is dealing with paths.

Example 8:
  RewriteRule ^/lowercase/(.+)\.asp$  /lowercase-output/#L$1#E.asp  [L]
  RewriteRule ^/uppercase/(.+)\.asp$  /uppercase-output/#U$1#E.asp  [L]
  RewriteRule ^/OneCharLower/(.+)\.asp$  /OneCharLower-output/#l$1.asp  [L]
  RewriteRule ^/OneCharUpper/(.+)\.asp$  /OneCharUpper-output/#u$1.asp  [L]

The first rule above would rewrite an incoming request like
/lowercase/This.Is.A.Test.asp  to /lowercase/this.is.a.test.asp

The second rule would do this:
incoming:   /uppercase/TesTiNgCaseConVerSion.asp
output:  /uppercase/TESTINGCASECONVERSION.asp

And so on.

Modifiers
-------------------------------------------------

The optional modifier flags can tweak or change  the operation
of the  RewriteRule. The modifer flags supported in this release
of IIRF include: 
   NF = Not found
   L = Last test if match
   F = Forbidden
   I = Do case-insensitive matching
   U = Store original url in server Variable HTTP_X_REWRITE_URL

The flags must be specified in square brackets.  If you need to
combine flags together - for example to combine a Last test with
a case-insensitive match - separate the flags with a comma.
Example: [I,L]. 

It makes sense to combine the case-insensitive [I] flag, or the
keep-original-url [U] flag with some other flags, but most combinations
of flags do not make sense.  Often they are mutually exclusive.
Example: [NF,L] - implies a "not found" response and also says "don't
look for more matches."  But a "not found" or a Forbidden, both imply
that IIRF will stop doing pattern matches immediately.

So, at this time, such combinations of flags are not supported.  If you
do this, you will get a grumpy warning message in the log file. Starting
with v1.2.15, the affected rule will not be processed - it will be
ignored.  (you can turn this off with "StrictParsing OFF").

Also, if you use an unsupported flag character (example: [Q]), IIRF will
emit a warning message, and will ignore the rule.  (Again, you can turn
this off with "StrictParsing OFF"). So do check your logs for warnings
to verify that you've fashioned your rules and modifiers properly.
There will be a big WARNING on the line for each warning.

Here's some further discussion on each flag.

[L]
----
This flag tells IIRF to process no more patterns if the current
one matches.  The default behavior is to recurse, until no match
is found, or until the iteration limit is reached.

[NF]
----
When this pattern matches, the return code given is 404, Not Found.
Useful to "turn off" certain URLs on the server selectively, without
actually removing the web content.  Also, combined with a RewriteCond,
the 404 can be used to filter results for a given requester, when a
given url pattern matches. You could use this to filter out requests
that include what appear to be SQL Injection attacks.  You can imagine
other uses as well. When using the NF flag, the rewrite pattern can be
anything, it does not matter.

[F]
---
Similar to the NF flag, this one sets a 403, Forbidden return
code.  Like the [NF] flag, the [F] flag can be utilized with a
RewriteCond for flexibility - you could return a 403 only for
requests coming from a certain REMOTE_ADDR, or you could deny
requests that do not have HTTPS enabled.  And so on.

[I]
---
Do a case-insensitive match on the pattern.  When using this
modifier flag, a pattern like ^/(.*).php$ will match a url like
Home.PHP. 

PCRE, the regular expression engine used by IIRF, supports a
syntax within the regular expression itself, for turning on
case-insensitive matching within the pattern itself.  Place a
(?i) anywhere in the pattern, and all matching after that point
in the pattern is done without regard for case.  Turn off this
behavior with (?-i). In this way, some portions of the pattern
can be matched in a case insensitive manner, and others will
not.  In the specific case, use (?i) at the beginning of the
pattern and the entire pattern is matched in a case insensitive
manner.  Consult the PCRE documentation for complete details.
(See http://www.pcre.org/pcre.txt and search for INTERNAL OPTION
SETTING).

Because of the support of (?i) in PCRE, the [I] flag is
redundant and not really unnecessary, but it is included in IIRF
because it may be familiar for some who are accustomed to
Isapi_Rewrite, and it may be more readable as well. 

Consult the tests\CaseInsensitive directory for examples of
case-insensitive matching.

[U]
---
This flag tells the filter to store the original, unmodified URL
in the server variable called HTTP_X_REWRITE_URL, and also tells
IIS to log the original, pre-rewrite URL in the IIS log file.
This is useful if you want to have generic handler logic (in
say, CFMX) that can do its own parsing of the original URL, or
if you want to expose Search-Engine Friendly URLs, and want to
preserve those URLs in the IIS log files for click analysis.

Unmangling will occur when ANY rule decorated with the [U] flag
is satisfied for a given incoming URL.  Remember, IIRF recurses
on URLs.  It may rewrite an incoming URL, then rewrite the result
of the rewrite.  It continues until the iteration limit is
reached, or until no more rules are satisfied.  If any of the
rules applied to a given URL include [U], then unmangling occurs.

One noteworthy behavior associated to use of the [U] flag on
Windows Server 2003, with the kernel-mode IIS cache enabled: To
implement this, IIRF uses the SF_NOTIFY_LOG event for IIS.
Registering for this event is considered "cache unfriendly", and
actually turns off the kernel response cache on IIS6.  This can
mean a performance degradation on IIS6 when your site relies on
the kernel-mode cache.

Because of this, IIRF asks to receive log events only when the
rules in the ini file say that it needs log events. In other
words, only when the [U] flag is employed in at  one or more
RewriteRules. 

But, the filter registers for notifications only once, at filter
startup, and so because of this, changes to the un-mangling
settings on rules work differently than changes to any other
filter settings in the ini file.  In short, changes involving the
use of [U] flags are not always immediately effective, and in
some cases you will need to restart the filter to make them
effective.

This is because it is not possible for an ISAPI filter to
dynamically change its event registrations - it can ask for
notification of log events only at filter startup.

Some examples: Suppose you start the filter, and have no rules
that use the [U] unmangle flag.  In this case, the filter will
start up, and will not register for log events.  If you then
modify the ini file to use unmangling on one or more rules, the
filter will reload the ini file.  But in this case, unmangling
will not work, as IIRF will not have registered for log event
notifications, and so will not have the opportunity to unmangle
the log.  Restarting the filter allows this change to become
effective.

On the other hand, suppose you have a [U] flag on at least one
active rule, and you have started the filter.  In this case IIRF
will register for log event notifications, and log unmangling
will work properly, though no requests that the filter handles
will be served via the IIS6 kernel-mode cache.  Now suppose you
then change the ini file so that another rule also uses [U].  The
unmangle settings on that changed rule will become active
immediately.  No restart is necessary in this case.

Finally, consider the case where at least one RewriteRule has
[U], and you start the filter (start IIS).  Every use of [U]
should work properly, though again, no requests will be served
from the IIS6 kernel cache.  Then suppose you modify the ini file
and remove all [U] flags.  The filter will continue to receive
SF_NOTIFY_LOG events, and it will continue to behave
correctly.  But in this case, the IIS6 kernel cache will continue to be not
used.  Subsequently, if you then modify the ini file again, and
re-introduce a [U] flag on one or more RewriteRules, the
unmangling will work properly, without restart of IIS, because
log event notifications are already flowing to IIRF.

When in doubt, restart the filter when changing the [U] flag for
any rule.

If you don't care about the IIS6 kernel cache, and want to avoid
this issue and "enable" log unmangling all the time, then you can
insert a dummy RewriteRule into your ini file, a rule that is
never satisfied, but uses the [U] flag.  This will cause IIRF to
register for log notifications, always.

IIS5 has no kernel mode cache.  If you use IIRF on Windows XP or
Windows 2000, you don't have to worry about this issue.

RedirectRule <url-pattern>   <replacement-string>   [<modifiers>]
----------------------------------------------------------------

This directive works the same was as RewriteRule, except that the result
is a REDIRECT.  This is a browser redirection - the ISAPI filter issues
a "302 Redirect" response back to the browser, setting the Location
header in that response to the URL specified by the replacement
string. When the 302 code is returned to the browser, the browser then
re-submits the request to the new location, and updates the URL in the
browser address bar.  The user sees the new address. Repeat: with
browser redirects, the URL bar in the browser is updated.

If you do not understand the difference between a server-side rewrite
and a REDIRECT, please go read the resources now.  Understanding the
difference now will eliminate a lot of confusion for you later, I
promise.

The url pattern and the replacement string work the same way as in the
RewriteRule directive.  In this case, though, the replacement-string
can include the scheme, hostname, and port (if any).  If the scheme
hostname and port are excluded, then the redirect happens to the local
server.

The only modifier flag that makes sense is the [I] flag, for
case-insensitive matching. This works the same as with the RewriteRule.

There is an additional modifier flag supported on the RedirectRule
directive, the [R] flag.

[R=code]
----------------
The [R=code] form allows you to specify the HTTP status code for the
redirect.

The default code is 302 (HTTP Status code for Moved Temporarily), but
you may wish to use 301 (Moved Permanently), or some other redirect
code.  The range of valid values for the R code is 301 to 399.  If you
specify a code outside that range, the default 302 code will be used. If
you specify a code that is not valid for HTTP, IIRF will blindly return
that code to the requesting browser.  So do be careful.

See the IETF RFC 2616 for complete details on HTTP Redirect
codes.  (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)

If you specify [R=302], it has no effect.  (This is the default behavior
for RedirectRule).

Example 9:

   RedirectRule ^/(W.*)$  http://server.dyndns.org:7070/$1  [R=301]

Given this incoming URL request:
   /Wookie
This rule would redirect the browser with a 301 (Moved Permanently)
response to this location:
http://server.dyndns.org:7070/Wookie

The browser would then update the address bar and submit the request to
that new location.

With this directive, IIRF can redirect to a different IIS
instance on the same box, a different IIS on a different box, or
a non-IIS server on either the local or remote box.  For
example, if you have multiple websites on a single Windows
Server machine, an IIRF installed on one of those instances
would be able to redirect to another instance.

You can also use this directive to change the scheme, so that all
requests go through a secure channel (https).

This directive can also be used to redirect requests to an
anchor point in an HTML document. (URLs containing a # name)

Example 10:

      RedirectRule ^/([^.?]+[^.?/])$ /$1/ [R=301]

This rule says, add a trailing slash to all URLs that don't end in a
slash, and also don't have any dots in the URL.

The above rule will have the following results:

'/foo/something'       ==> Browser Redirect (301) to '/foo/something/'
'/home/foo/admin'      ==> Redirect (301) to         '/home/foo/admin/'
'/module.php'          ==> No redirect
'/foo/something.aspx'  ==> No redirect 
'/foo/something.'      ==> No redirect 

You could imagine combining this rule with a "directory existence"
RewriteCond (see the notes on the -d flag), so that the redirect
would occur only if the target directory actually exists.

RewriteHeader <header-name> <pattern> <replacement-string>   [<modifiers>]
----------------------------------------------------------------

This works much like the RewriteRule directive, except that it is an
HTTP Header that is being rewritten.  The <header-name> must end with a
colon.  The <pattern> matches against the
value of the HTTP header specified.  The <replacement-string>
and <modifiers> work the same as in RewriteRule.

If you want to simply set an arbitrary header, you can use a pattern of
.* , to match anything.  If you want this rule to apply only when the
header is empty, then use ^$ as the pattern. 

Back-refs and Server variables can be used in the replacement string,
just as with RewriteRule. 

Example:

  RewriteCond %{QUERY_STRING} ^$
  RewriteHeader Query-Is-Empty: .* YaHuh [L]

The rule above says to set the Header "Query-Is-Empty" to the value
"Yahuh" when the server variable QUERY_STRING is empty.

  RewriteCond %{QUERY_STRING} ^.+$
  RewriteHeader Query-Is-Not-Empty: .* YaHuh [L]

The rule above says to set the Header "Query-Is-Not-Empty" to the value
"Yahuh" when the server variable QUERY_STRING is NOT empty.

You should be careful with RewriteHeader directives.  They fall under the
same iteration rules as RewriteRule directives. When a RewriteHeader
rule matches, then evaluation of the URL / Request starts all over again
with the current ruleset, subject to the iteration limits described
elsewhere in this documentation.

What this means is, you can inadvertently "mask" your RewriteRule
directives with a poorly constructed RewriteHeader directive.  For
example, in the directives above, I set the header always.  A better
approach would be to set the header only if it is not already set.  For
example:

  RewriteCond %{QUERY_STRING} ^.+$
  RewriteHeader Query-Is-Not-Empty: ^$ YaHuh

RewriteCond <test-string> <pattern> [<modifier flag[,...]>]
-------------------------------------------------

When this directive precedes a RewriteRule or RedirectRule directive,
the RewriteRule or RedirectRule directive is applied only when the
condition supplied in the RewriteCond directive evaluates to true.  When
there are multiple RewreiteCond directives in series, the RewriteRule or
RedirectRule directive is applied when the entire chain evaluates to
true.

By default successive RewriteCond directives are linked by a
logical AND. There is an optional modifier_flag [OR] that allows
you to chain the next RewriteCond with a logical OR. 

The evaluation of each RewriteCond is done per-request.  The
test string may include plain text, rule-pattern back references
of the form $N (N=1,2,3...), Condition back references of the
form %N, or references to server variables of the form %{NAME},
as well as the case-folding directives #L #U #E #l #u.

Back References like $n and %n
--------------------------------

Back references in the replacement pattern of the form $n refer to the
matched substrings in the url-pattern of the RewriteRule or
RedirectRule.  This is consistent with most regular-expression
utilities.  IIRF also supports, within the replacement pattern of the
RewriteRule or RedirectRule, back-references to matched substrings in
the previously evaluated condition pattern, using the form %N, where
N=1,2,3,....

The "previously evaluated condition pattern" is not always the
previous RewriteCond in the file, because depending on the
logical operators used, some RewriteCond's will not be evaluated
at all. 

Here's an explanation for why this is so.  For each RewriteCond,
IIRF does this:

1. generate a value for the <test-string>, replacing any Server
   Variables, and back-references to do so.

2. apply the regular expression <pattern> to see if it matches. 

If the regex matches, then the back-references of the form (%1,
%2) become available for the next RewriteCond, or for the
RewriteRule.

Now, suppose you have this rule with these conditions:

   RewriteCond <test-string-A>  <pattern-A>  [OR]
   RewriteCond <test-string-B>  <pattern-B>
   RewriteCond <test-string-C>  <pattern-C>
   RewriteRule ^/blah$   %1

In English, this translates to: if (A OR (B AND C)), then apply
the RewriteRule.

Supposing that RewriteCond A evaluates to TRUE, then RewriteCond B and
RewriteCond C will never be evaluated.  Therefore any back-references in
the RewriteRule replacement pattern (like %1 above) will refer to
matched substrings (if any) in RewriteCond A.

Now suppose that RewriteCond A evaluates to FALSE, and both B and C are
true. In this case, any back-references of the form %1, %2... in
<test-string-B> will refer to RewriteCond A - but they will be invalid
references as RewriteCond A evaluated to false.  On the other hand,
back-references of that form in <test-string-C> will refer to matched
substrings from RewriteCond B, and these will be active and valid.
Finally, back-refs like %n in the RewriteRule or RedirectRule will refer
to matched substrings from RewriteCond C.

In this example, there is no possibility that references like %n in the
RewriteRule or RedirectRule replacement string will ever refer to
matched substrings from RewriteCond B, because the order of logical
evaluation implies that RewriteCond B will never be the most recently
evaluated condition after the overall condition set evaluates to
TRUE. Get it?

Order of evaluation of RewriteCond and RewriteRule/RedirectRule
--------------------------------------------------

It may be a bit counter-intuitive at first, so I will repeat here for
clarity: it is possible to include back-references of the form $n in the
test-string for RewriteCond.  This is because the RewriteRule or
RedirectRule pattern is evaluated, but not applied, BEFORE the
associated chained set of RewriteConds.  The $n in any RewriteCond test
string will refer to matched substrings from the pattern in the
RewriteRule or RedirectRule.  Only if the RewriteRule or RedirectRule
pattern matches, and any associated chain of RewriteCond statements
evaluates to TRUE, will the RewriteRule or RedirectRule actually be
applied.

서버변수 참조
--------------------------

서버변수는 다음 중 하나이어야 한다:
    APPL_MD_PATH
    APPL_PHYSICAL_PATH
    AUTH_PASSWORD
    AUTH_TYPE
    AUTH_USER
    CERT_COOKIE
    CERT_FLAGS
    CERT_ISSUER
    CERT_KEYSIZE
    CERT_SECRETKEYSIZE
    CERT_SERIALNUMBER
    CERT_SERVER_ISSUER
    CERT_SERVER_SUBJECT
    CERT_SUBJECT
    CONTENT_LENGTH
    CONTENT_TYPE
    GATEWAY_INTERFACE
    HTTPS
    HTTPS_KEYSIZE
    HTTPS_SECRETKEYSIZE
    HTTPS_SERVER_ISSUER
    HTTPS_SERVER_SUBJECT
    INSTANCE_ID
    INSTANCE_META_PATH
    LOCAL_ADDR
    LOGON_USER
    PATH_INFO
    PATH_TRANSLATED
    QUERY_STRING
    REMOTE_ADDR
    REMOTE_HOST
    REMOTE_USER
    REQUEST_METHOD
    SCRIPT_NAME
    SERVER_NAME
    SERVER_PORT
    SERVER_PORT_SECURE
    SERVER_PROTOCOL
    SERVER_SOFTWARE
    URL
    HTTP_ACCEPT
    HTTP_ACCEPT_LANGUAGE
    HTTP_CONNECTION
    HTTP_HOST
    HTTP_REFERER
    HTTP_USER_AGENT
    HTTP_ACCEPT_ENCODING

특별 값:
    REQUEST_FILENAME

If you use something other than one of these values, then the
string will not be interpreted - it will evaluate to the name.
For example, if you pass %{THIS_IS_NOT_VALID}, the RewriteCond
will evaluate at runtime to "THIS_IS_NOT_VALID" which is
probably not what you want.

The special value "REQUEST_FILENAME" is not a server variable,
but it can be referenced within a RewriteCond using the
server variable syntax (eg %{REQUEST_FILENAME} ).  This special name
will evaluate to the physical path of the requested URL, which
may or may not correspond to an existing file.

Example 11:

  RewriteCond %{REMOTE_ADDR}   ^(?!127.0.0.1)([0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3})(.*)$
  RewriteRule  ^/(?!redirected.htm)(.*)$      /redirected.htm

The above condition evaluates to true when the server-variable
"REMOTE_ADDR" evaluates to an ip address which is NOT
127.0.0.1. The ?! is a zero-width negative lookahead, and the
(.*) at the end of the regex is to catch any rubbish that
sometimes appears in that variable.  The rule following the
condition says, for any URL which is not "redirected.htm", map
it to "redirected.htm".  This prevents endless re-writing. (You
could also prevent endless rewriting with an [L] modifier flag).
You might use this pair of condition and rule to redirect any
externally originated requests to the IIS server on WinXP.
Local requests would still be honored.

Example 12:

  RewriteCond %{QUERY_STRING} ^$
  RewriteRule ^(.*)$ /index.php?q=$1 [L]

  RewriteRule ^(.*)\?(.*)$ /index.php?q=$1&$2 [L]

There is a QSA modifier in Mod_rewrite, which is not supported  by
IIRF.  But the above set of rules works like QSA: they append any
existing query string onto the rewritten URL. 

For example, the rules above would map URLs this way:

/what/ever                    ==> /index.php?q=/what/ever
/what/ever?query=string       ==> /index.php?q=/what/ever&query=string

Example 13:

    RewriteCond %{HTTP_REFERER} ^(?!HTTP_REFERER)
    RewriteCond %{HTTP_REFERER} ^(?!https?://(?:www\.)mysite\.net/)   [I]
    RewriteCond %{HTTP_REFERER} ^(?!https?://203\.0?30\.0?46\.178/)
    RewriteCond %{HTTP_REFERER} ^(?!https?://(?:www\.)foo\.com/)      [I]
    RewriteCond %{HTTP_REFERER} ^(?!https?://203\.0?30\.0?46\.181/)
    RewriteRule \.(?:gif|jpg|jpeg|png)$ /blocked.png   [I,L]

    RewriteRule ^blocked\.png$/ blocked.png [I,L]

There are 2 rules.  The first rewrite rule will block direct
image linking, with a list of sites allowed to link.  The rule
pattern says "match anything that ends in a .gif, jpg, jpeg or
png."  IF this match happens, the URL gets rewritten to
blocked.png.  But, this rewriteRule is only in effect if the
RewriteCond chain applies.  In this case, there are five
RewriteCond statements in the chain.  In each case the cond
should read, "when HTTP_REFERER is NOT the given pattern (notice
the ?! in each pattern.  So, when all of these are true, then
the request for an image is blocked.  If any is not true, then
the request for an image is not blocked.

The first RewriteCond that mentions HTTP_REFERER says - if
HTTP_REFERER evaluates to HTTP_REFERER.  This happens in IIRF if
there is no HTTP_REFERER server variable.  So you've got to
handle that in the ruleset.

The second rule just strips trailing slashes.

----

Note: I haven't tested all of these Server Variables - some of
them may not be set inside the SF_NOTIFY_AUTH_COMPLETE event in
the ISAPI Filter.  The documentation is not clear on this point.

수정자 표식들
-------------------------------------------------

There are two modifier flags supported on a RewriteCond:

  I = case insensitive matching.  See comments on [I] for
      RewriteRule.

  OR = combine rule conditions with a logical OR. Without this,
      successive RewriteCond directives are joined by a logical AND.

Example 14:

  RewriteCond %{HTTP_HOST} ^www.domain1.tw$  [OR]
  RewriteCond %{HTTP_HOST} ^www.domain2.tw$
  RewriteRule (?!^/index.php)(?!.*\/$)(?!.*\.html$)^/(.*)$        /index.php?$1

In English, what this says is, when the incoming URL
  does not begin with /index.php
  does not end in a slash
  and does not end in a .html
then match everything following the first slash
and rewrite it to prepend index.php? to it.
and by the way, apply this rule only when the HTTP_HOST matches www.domain1.tw or www.domain2.tw

With this rule, we get these outputs, when the domain name
is www.domain1.tw:

'/news/2006-04/newsitem.html'       ==> No Rewrite (ends in .html)
'/news/'                            ==> No Rewrite (ends in a slash)
'/news'                             ==> '/index.php?news'
'/foo/bar/bah/'                     ==> No Rewrite (ends in a slash)
'/foo/bar/bah'                      ==> '/index.php?foo/bar/bah'
'/news/index.php/newsitem.html'     ==> No Rewrite (ends in .html)
'/news/index.php/newsitem.js'       ==> '/index.php?news/index.php/newsitem.js'
'/news/index.php/newsitem'          ==> '/index.php?news/index.php/newsitem'
'/news/index.php-04/newsitem.html'  ==> No Rewrite  (ends in .html)
'/news/index.php-04/newsitem.js'    ==> '/index.php?news/index.php-04/newsitem.js'
'/news/index.php-04/newsitem'       ==> '/index.php?news/index.php-04/newsitem'
'/news/foo-index.php/newsitem.html' ==> No Rewrite (ends in .html)
'/news/foo-index.php/newsitem.js'   ==> '/index.php?news/foo-index.php/newsitem.js'
'/news/foo-index.php/newsitem'      ==> '/index.php?news/foo-index.php/newsitem'

RewriteCond: 특수 패턴들
-------------------------------------------------

RewriteCond supports some special patterns, as an
alternative to using a regular expression. These are:

  -d
  Treats the TestString as a pathname and tests if it exists,
  and is a directory.

  -f
  Treats the TestString as a pathname and tests if it exists and
  is a regular file.

  -s
  Treats the TestString as a pathname and tests if it exists and
  is a regular file with size greater than zero.

These may be particularly useful when employed with the server
variables such as:
  PATH_TRANSLATED, the translated PATH_INFO for the request.
  SCRIPT_TRANSLATED, which is new for IIS6.  Probably what you want.

The flags may also be used with the special pseudo-server variable
"REQUEST_FILENAME" that is known within IIRF. 

Each of these special patterns can be logically negated with a !
prepended to the special pattern.  To clarify, !-s evaluates to
TRUE, when the TestString is not a valid file, or when the test
string is a directory, or when the test string is a file of zero
length.

Example 15:

  RewriteCond %{HTTP_URL}             (/|\.htm|\.php|\.html|/[^.]*)$   [I]
  RewriteCond %{REQUEST_FILENAME}     !-f
  RewriteCond %{REQUEST_FILENAME}     !-d                                 
  RewriteRule ^.*$                    /index.aspx                      [U,L]

This ruleset says, if the URL ends in .htm, .php, or .html (case
insensitive); AND the physical path associated to the URL is not
a file AND it is not a directory, then rewrite the URL to
index.aspx, and parse no more rules. Also, log the original
(un-rewritten) URL in the log file.  I think something close to
this should work for Joomla and OpenSEF, but I don't test those
things so I cannot verify that.

Nota Bene: You should not count on PATH_TRANSLATED to be the
same as REQUEST_FILENAME.  It is not the same, consult the
section in this doc on server variables for more information on
this.

http://blogs.msdn.com/david.wang/archive/2005/08/04/What-is-PATH-TRANSLATED.aspx

PATH_INFO

The extra path information, as given by the
client. In other words, scripts can be accessed by
their virtual pathname, followed by extra
information at the end of this path. The extra
information is sent as PATH_INFO. This information
should be decoded by the server if it comes from a
URL before it is passed to the CGI script.

PATH_TRANSLATED

The server provides a translated version of
PATH_INFO, which takes the path and does any
virtual-to-physical mapping to it.  This gets set
only if PATH_INFO is set!

SCRIPT_NAME

A virtual path to the script being executed, used
for self-referencing URLs.

-----

In IIS6 there is an additional Server variable called
SCRIPT_TRANSLATED which may be the same as REQUEST_FILENAME.
Ymmv.  Also, as noted elsewhere, REQUEST_FILENAME is NOT an IIS
Server Variable - you won't find it in any other ISAPI, and you
cannot get it from within PHP or ASPX as far as I know.  It is a
pseudo-Server Variable in IIRF, and its value is generated
within IIRF, and known and usable only within IIRF.

Example 16:

  RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
  RewriteRule  ^/$                 /homepage.max.html  [L]

This ruleset says, if the User-Agent is Mozilla, then rewrite to
a special html page.

Note that in some cases HTTP_USER_AGENT is not passed by the
client. This is legal in HTTP.  You should not rely on User-Agent
being non-empty.

Example 17:

  RewriteCond %{SERVER_NAME}          ([^\.]+)\.chiesa\.net$                [I]
  RewriteCond c:\Inetpub\wwwroot\%1   !-d
  RewriteRule ^(.*)$                  /NotFound.htm                         [U,I,L]

  RewriteCond %{SERVER_NAME}          ([^\.]+)\.chiesa\.net$                [I]
  RewriteCond c:\Inetpub\wwwroot\%1   -d
  RewriteRule ^(.*)$                  /common/driver.aspx?url=$1&host=%1    [U,I,L]

This one redirects a request based on the hostname specified in
the request.  If there is no subdirectory under
c:\InetPub\wwwroot with the same name as the hostname specified
in the request, then the first rule fires,and the user gets a
NotFound.htm page. If there is a sub-directory, then the 2nd
rule fires and the incoming request is rewritten to a common
driver.aspx, specifying the hostname (back-ref %1) and the URL
request (back-ref $1) to that driver.

In this way the rewriter changes its behavior depending on the
state of the filesystem underlying the IIS server.  For example,
when you register new users or new hosts, you might create a new
file or directory in the filesystem.  When a request comes in,
the rewriter can check for the file or directory and rewrite
accordingly.  Pretty cool.

 

IterationLimit {integer}
-------------------------------------------------

When a URL is matched to a RewriteRule pattern, the default
behavior of IIRF is to recurse - to apply the rules again,
iteratively, until no pattern matches.  (This behavior can be
modified using the [L] flag).   In other words, the
output of a RewriteRule, is processed as input.

The IterationLimit ini-file directive specifies how many times the
rewrite filter will loop on a single URL.  After a URL has been
transformed successfully, the result will be run through the
Rewrite rules again, to be transformed again.  This continues
for a single URL, as many times as necessary, or until the
IterationLimit is exceeded, whichever comes first.

The IterationLimit is included as a fail-safe mechanism.
Consider the simplest case: It is possible to create a rewrite
rule that generates an output that matches its own input
pattern.  The effect is a logical infinite loop.  It is also
possible to have more complex loops, for example the output of
one rule matches the input of another rule, and vice versa. 

With an infinite loop or cycle in your ini-file Rewrite rules, and
without an IterationLimit, the ISAPI filter would loop
infinitely, and resulting in a stack overflow, and a
denial-of-service in IIS.

The simple solution would be: don't design sets of rules that
induce loops.  But sometimes it can be difficult to determine if
a loop might occur. The IterationLimit removes the potential for
this infinite loop.

The default IterationLimit is 8.  This default applies if you do
not specify an IterationLimit in the ini file.  The default may
or may not be suitable for any particular deployment.  It is not
likely that you will need more iterations, but if you do, change
the limit with the IterationLimit directive.

NB: the IterationLimit does not apply only to the case where the
same RewriteRule is applied to the URL.  It applies to the
number of passes through ALL of the rules. If a URL matches any
Rule, then the rule is applied, the iteration count is
incremented and the IIRF engine does another pass.

Example 18:

   IterationLimit 5
   RewriteRule ^/([^0-9]*)$  /1/$1
   RewriteRule ^/1/([^0-9]*)$  /2/$1
   RewriteRule ^/2/([^0-9]*)$  /3/$1
   RewriteRule ^/3/([^0-9]*)$  /4/$1
   RewriteRule ^/4/([^0-9]*)$  /5/$1
   RewriteRule ^/5/([^0-9]*)$  /6/$1
   RewriteRule ^/6/([^0-9]*)$  /7/$1

Given the above set of rules, you will get these results:

'/index.html' ==> '/6/index.html'
'/1/index.html' ==> '/7/index.html'
'/2/index.html' ==> '/7/index.html'

The range of valid values for IterationLimit is 1 to 30. 
If you specify an IterationLimit out of this range, the default
value of 8 will be used, and a message will be logged in the log
file.

 

MaxMatchCount {integer}
---------------------------------------------

The MaxMatchCount directive specifies the maximum number of
matches to collect for each match.  The example regular
expressions in the same ini file have 1 or 2 matches. In more
complex scenarios, an RE might have 8 or 12 matches.  The
MaxMatchCount allows an admin to specify the upper limit for
this number.  The default is 10.

The range of valid values for MaxMatchCount is 4 to 25.
If you specify an MaxMatchCount out of this range, the default
value of 10 will be used, and a message will be logged in the
log file.

 

RewriteLog <filename stub>
---------------------------------------------

This directive sets the logfile name.

The value should specify a fully-qualified filename.  The name
specified in the ini file is used as a stub: to this stub, the filter
appends the process ID (also known as the 'pid') and ".log" to
the provided name to get the final filename.  This is necessary
to allow for multiple worker processes in IIS6.  Example:

   RewriteLog c:\temp\iirf

gives a net logfilename of

   c:\temp\iirf.1672.log

if the process ID of the w3wp.exe is 1672. 

You will get multiple logfiles if you have multiple worker
processes.

The file will be created by the ISAPI filter when it handles its
first URL.  If the file path is not valid, or if the ISAPI does
not have permissions to write to the specified file path, then
no logging will be generated.  If you expect to see a logging
file and don't see one, check your paths and permissions.

If you do not include a RewriteLog directive in your ini file,
then you will get no logging at all.  This may be what you want.

As of v1.2.11d, according to a request from AlexanderGross on
CodePlex.com, the RewriteLog directive will now accept log file
stubs that include spaces.  Leading and trailing spaces are
stripped.  For example:

   RewriteLog     c:\Websites and Stuff\web1.out

...gives a net logfilename of

   c:\Websites and Stuff\web1.out.1882.log

...if the process ID of the w3wp.exe is 1882. 

Special Note:

For the RewriteLog, you should  specify a different directory
from that which contains the .ini file. 

Here is why: IIRF monitors the directory where the .ini file
resides, looking for changes.  Under Windows, it is not possible
to monitor a single file for changes. Instead, the application
must monitor an entire directory tree, and the application is
notified in *any* file in the monitored directory tree,
including in subdirectories, changes.  If your log file and ini
file are in the same directory, or if your log file is in a
subdirectory of the directory for the ini file, then every time
the log file is updated, which of course happens quite often,
IIRF detects a change in a file in the monitored directory tree.
If you have a RewriteLogLevel greater than 2, the file change
watcher then logs some messages, which of course results in a
change in the log file. Again IIRF detects a change in the
directory tree. Again it logs some messages, and the cycle
continues.  As a result, when the log file and the ini file are
in the same directory, there can be a very long cycle of
activity, most of it useless.  Eventually the notifications
cease, but it can cause detrimental effects in the behavior of
IIRF.

Currently IIRF checks to verify that the Logfile does not fall
under the directory for the ini file, and logs a warning message
in the logfile if this occurs.  However, IIRF does not enforce
the recommendation to use separate directory trees.  To avoid
the problem and the warning message, specify a different
directory.

 

RewriteLogLevel {0,1,2,3,4,5}
---------------------------------

This directive sets the logging level.  a higher number means
more logging:
  0 - no logging
  1 - a little logging
  2 - a little more
  3 - really verbose logging
  4 - also emit trace on server variable replacement and string
      replacement
  5 - also include messages on file change events and some other
      minor events of interest.  This is generally not useful
      for end users.

The default is zero.  If you set an out-of-range value for the
log level, you may not get logging. a Non-Zero value is useful
for auditing and monitoring purposes, as well as for giving you
that warm fuzzy feeling, knowing that something good is happening.

Do not use level 5 in production - it can result in large log
files with lots of useless information.  This level is
useful only for troubleshooting.

 

RewriteFilterPriority {HIGH|MEDIUM|LOW}
-------------------------------------------------

ISAPI has a concept of filter priority.  In versions of IIRF
1.2.10 and prior, IIRF always registered at the DEFAULT
priority, which was MEDIUM.  Some applications require IIRF to
cooperate with other ISAPIs, which means it needs to have a
different priority than the default.  In most cases, this is not
necessary. 

Example 19:
  RewriteFilterPriority HIGH

If an invalid value is specified for RewriteFilterPriority, the
value used by IIRF will remain unchanged.  The default priority
for IIRF is DEFAULT, which for IIS5 and IIS6 works out to "MEDIUM."

If you do not include a RewriteFilterPriority directive, IIRF
will use the default, which is DEFAULT.  You cannot specify
DEFAULT in the ini file.  If you want DEFAULT for the filter
priority, then just don't use a RewriteFilterPriority directive.

Changes to this directive in the ini file are not effective,
until the IIS server or ISAPI filter is restarted.  This is
because the filter priority is set once, when the ISAPI DLL is
loaded by the server.  If you want to change the filter
priority, be sure to restart the IIS Server or ISAPI filter to
make that change effective.

 

CondSubstringBackrefFlag
----------------------------

Back-refs to matched substrings of the form %n can be confused with
characters you would like to include in the pattern. 

For example, a replacement pattern might look like
/results?query=http%3A%2F%2Fserver%2Fpage.asp%3Farg=%2

The %3A%2F%2F is really meant to be :// - it is url escaped.  But the %3
sure looks like a backreference to a matched substring from the most
recently matched RewriteCond statement. It's ambiguous.  When there is
no third substring, IIRF just passes the %3 through, so the %3A works as
desired, representing the colon character in the output.  But if there
is a third substring, then it will be injected at that point, and you
won't get what you want.

This directive allows you to use a different flag character for
back-references, to disambiguate between URL-escaped characters and
numbered back-references.

The directive takes a single argument , a character.  It must be one of
the following: % @ * _ ^ ! ~ .

You should set this at most once in the ini file.

Example 20:

when using this directive:
CondSubstringBackrefFlag *

...then a replacement string like this will append the 2nd matched
substring from the most recently evaluated RewriteCond, at the end of
the URL.

   /results?query=http%3A%2F%2Fserver%2Fpage.asp%3Farg=*2

Be careful using % as the backref character.

 

StrictParsing  (ON|OFF)
----------------------------

With StrictParsing ON, the filter will log a warning and ignore a rule
for which the modifier flags are badly formed or invalid.

With it OFF, the filter will log a warning but will keep the rule. This
may lead to incorrect or unintended filter behavior.

By default, StrictParsing is ON.

You probably want this ON, it helps to track down errors and typos.

Prior to v1.2.15, the parser was not Strict - invalid modifier flags
were silently tolerated.

Example 21:
  StrictParsing  ON

NB: The strictness applies only to rules following the StrictParsing
directive in the ini file.  In other words, if you have a typo or
invalid modifier flag in the ini file, and then following that rule, you
have a StrictParsing directive, the typo in the earlier rule will not be
treated strictly.

Unrecognized Directives
---------------------------------

Any unrecognized directives in the INI file will be tolerated
without generating any exception.  So, be careful of spelling.
If you specify

  RWriterule xyz abc

...(notice the missing E) the filter won't do anything except
emit a warning message in the log. If you don't check the log,
you may be none the wiser.

As noted elsewhere, case is not sensitive in the directive name,
so
  ReWrItERUle
is as good as
  RewriteRule
which is as good as
  rewriterule

All of them are accepted and interpreted.  It is probably
best form and most readable to use RewriteRule. 

Any unrecognized directives will be logged with a WARNING, and
ignored.  Also, incorrectly formatted directives will also
result in a WARNING.  Obviously such errors in the ini file may
materially affect the operation of the filter. 

To be clear, if you have a spelling error or typo in your ini file,
your filter may silently not behave the way you expect it to.
So do be careful and check your logs for WARNINGS, especially
the loading sequence, after every change in your ini file.

One could imagine a directive like "Option Strict" where any
unrecognized or poorly formatted directives are flagged as
ERRORS, not warnings, and cause the filter to barf and refuse to
load.  If anyone has specific requests on this feature, please
do let me know.

There is a tool in the IIRF distribution called TestParse.exe,
which will load an ini file and display the log messages for
parsing the file.  TestParse does not test the operation of the
filter, it only loads the ini file.  It can be handy in foing
first-pass checking on ini file syntax.

Processing Rules
---------------------------------

Rules are processed in the order they appear in the file. 

This means, if the first RewriteRule rewrites every incoming URL
to "foo", and the next RewriteRule never matches "foo", then the
second RewriteRule will never be satisfied. 

Also, if you set the RewriteLog at the end of the file, logging
won't start until the file has been mostly processed.  This
means you won't see log messages of the parser as it reads in
RewriteRule directives and RewriteCond directives.  Those log
messages can be helpful in troubleshooting or debugging, so I
recommend you put the RewriteLog and RewriteLogLevel directives
in the beginning of the ini file. But you don't have to.

More on Regular Expressions
-------------------------------------------------

The Regular Expression language is a powerful but complex one.
For many people Regular Expressions can be a sort of "dark
magic" but with a little study, and with some useful examples,
most can get productive with regular expressions.

For more information on regular expressions, try searching like:
http://search.msn.com/results.aspx?q=regular+expressions&FORM=QBRE

or, see the Perl doc:
http://www.perl.com/doc/manual/html/pod/perlre.html

or try a book, like this:
http://www.amazon.com/exec/obidos/tg/detail/-/1565922573?v=glance

or go to the PCRE doc:
http://www.pcre.org/pcre.text