Attention! Helicon Tech Blog has moved to www.helicontech.com/articles/

Monday, April 27, 2009

HeliconTech on Twitter

Dear customers,
We've opened an official twitter account: @helicontech. Please follow us to get some “fresh meat” news :)

Always yours,
HeliconTech Team

ISAPI_Rewrite 3.1.0.63 already available

We've recently released a new build (63rd) of ISAPI_Rewrite 3 that can't actually boast any significant changes or features, but has some really important fixes:

- now ISAPI_Rewrite deals well with map files paths with spaces (e.g. C:\Program Files\...);
- RewriteHeader directive is now correctly converted from v2 syntax using our syntax converting tool;
- and some improvements in Unicode representation in the rewrite log were made.

That's all for now:)

Wednesday, April 22, 2009

mod_log_config capabilities

Hello!
We are always happy to offer you new features. Recently Helicon Ape has got mod_log_config - the module for logs tweaking.

Why is it useful? Look, sometimes all of us have troubles. Reason searching may be pretty difficult so some extra help would be great. To log important actions is a good idea. You can always explore and find what's happened. But of course you wanna choose a “verbosity” of logging. That's mod_log_config job. And here you will see the flexibility by yourself. Let's start! ;)

mod_log_config

The module was included in version 1.2.0.18. To enable mod_log_config you must uncomment this line in httpd.conf file:
LoadModule log_config_module modules/mod_log_config.so
3 directives are supported: CustomLog, TransferLog and LogFormat. Let's leave boring directive description for mod_log_config documentation but let us point out that unlike in Apache, in Ape you may write the module configuration everywhere you need (not in server configuration only).

mod_log_config stores files relative to server configuration (httpd.conf). Please note there are potential issues with insufficient permissions.

Simple log

CustomLog my.log "%t %U%q %s"
It's quite simple, isn't it? You will get messages like
[13/Apr/2009:04:49:21 +0300] /index.php?q=1 200

Getting more

Numerous format strings are at your disposal. You may catch HTTP-headers, information about each request and so on and so forth. The configuration below could be useful to store an information about each request:
CustomLog access.log "%t %a,%{User-Agent}i %U%q %s"
Here is the result:
[14/Apr/2009:05:09:32 +0300] 127.0.0.1,Opera/9.64 (Windows NT 6.0; U; en) Presto/2.1.1 /iisstart.htm 200
[14/Apr/2009:05:09:32 +0300] 127.0.0.1,Opera/9.64 (Windows NT 6.0; U; en) Presto/2.1.1 / 200
[14/Apr/2009:05:09:32 +0300] 127.0.0.1,Opera/9.64 (Windows NT 6.0; U; en) Presto/2.1.1 /welcome.png 304
[14/Apr/2009:05:09:32 +0300] 127.0.0.1,Opera/9.64 (Windows NT 6.0; U; en) Presto/2.1.1 /favicon.ico 404
Perhaps you think the game is not worth the candle because there are IIS logs available. Yep, that's right. More useful way is to have separate logs for some interesting requests.

Per status code differentiation

We all like HTTP status 200. It means 'OK' and that's why we're not interested in loging it. Most common situation is when we are looking for some psecific status code in the logs. With mod_log_config you may create separate logs for every needed status. Please look at this configuration:
CustomLog ok.log "%200t %200a,%200{User-Agent}i %200U%200q %200s"
CustomLog redirections.log "%301t %301a,%301{User-Agent}i %301U%301q %301s"
CustomLog not_found.log "%404t %404a,%404{User-Agent}i %404U%404q %404s"
CustomLog server_error.log "%500t %500a,%500{User-Agent}i %500U%500q %500s"
There are four log files for four statuses: 200 - OK, 301 - permanent redirect, 404 - file not found, 500 - internal server error. Log records will look like:
[22/Apr/2009:03:05:51 +0300] 127.0.0.1,Opera/9.64 (Windows NT 6.0; U; en) Presto/2.1.1 /iisstart.htm 200
Pretty good thing except one nuance: when status doesn't match each log will contain a non-informative record like this:
- -,- -- -
Why? Because we didn't link each CustomLog directive with a status code. Instead of that we linked format strings. The configuration below is 100% compatible with Apache and Ape emulates its behaviour. We decided it isn't usable and implemented some extra features.

Our hacking module - mod_setenvif is becoming a kind of programming language;) It has very nice features to evaluate various conditions. So we've upgraded the module and now you may use the following syntax:
SetEnvIf status_code = 200 STATUS_OK
SetEnvIf status_code = 301 STATUS_REDIRECTION
SetEnvIf status_code = 404 STATUS_NOTFOUND
SetEnvIf status_code = 500 STATUS_ERROR

CustomLog ok.log "%t %a,%{User-Agent}i %U%q %s" env=STATUS_OK
CustomLog redirections.log "%t %a,%{User-Agent}i %U%q %s" env=STATUS_REDIRECTION
CustomLog not_found.log "%t %a,%{User-Agent}i %U%q %s" env=STATUS_NOTFOUND
CustomLog server_error.log "%t %a,%{User-Agent}i %U%q %s" env=STATUS_ERROR
Of course it isn't compatible with Apache. But with this syntax each file will have only sensible records. Four mod_setenvif rules compare HTTP status retrieved from the server and set environment variables. Each mod_log_config rule is waiting for its own variable and if it exists then the rule fires.

Long requests

There is quite simple solution for long requests logging. The solution isn't Apache compatible. Here it is:
SetEnvIf request_duration > 1000 LONG_REQUEST
CustomLog long_requests.log "%t %a,%{User-Agent}i %U%q %s, duration=%D"
It gives an output like:
[22/Apr/2009:03:05:51 +0300] 127.0.0.1,Opera/9.64 (Windows NT 6.0; U; en) Presto/2.1.1 /iisstart.htm 200, duration=26366
mod_setenvif compares a duration with 1000 microseconds and sets LONG_REQUEST environment variable in case the duration really exceedes specified limit. Then mod_log_config processes CustomLog directive in case LONG_REQUEST variable exists. Easy, isn't it? Well, let's see one more finger-licking good thing;)

Binding with modules

mod_log_config supports very useful format - %{module_note}n. The other Ape's modules can store theirs own variables which are available through this format. It gives a cool opportunity to track modules operation. Currently only three modules use this feature: mod_gzipmod_auth_basic and  mod_auth_digest.

GZIP compression statistic

The feature described above allows us to get some statistic information about mod_gzip work results. Please try out the following:
CustomLog mod_gzip.log "%h %u %t \"%V %r\" %s %{mod_gzip_result}n \
 In:%{mod_gzip_input_size}n -< Out:%{mod_gzip_output_size}n = %{mod_gzip_compression_ratio}n pct."
mod_gzip.log records will look like:
127.0.0.1  [22/Apr/2009:03:37:10 +0300] "localhost GET /iisstart.htm HTTP/1.1" 200 compressed In:689 -< Out:442 = 35,84906 pct

Authentication catching

If you want to know which users have been authenticated and which haven't, you should use something like that:
SetEnvIf status_code = 401 STATUS_UNAUTHORIZED
SetEnvif status_code = 200 STATUS_OK
CustomLog authorized.log "%t %a,%{User-Agent}i,name=%u %U%q %s" env=STATUS_OK
CustomLog unauthorized.log "%t %a,%{User-Agent}i,[usr=%{auth_failed_username}n] %U%q %s" env=STATUS_UNAUTHORIZED
authorized.log:
[22/Apr/2009:04:11:41 +0300] 192.168.1.84,r2d3,name=user1 /ape/auth/basic/file/groupfile/index.html 200
unauthorized.log:
[22/Apr/2009:04:12:30 +0300] 192.168.1.84,r2d2,[usr=user1] /ape/mod_rewrite/proxy/auth-basic/index.htm 401

Looking forward

Much more modules will be configured to work with mod_log_config in the future. Also using customers responses we are going to improve and extend the module features. We hope you will like the functionality Helicon Ape has got.

Best wishes,
HeliconTech Team

Monday, April 6, 2009

How to install Helicon Ape on shared hosting

Helicon Ape product offers a bunch of unique features to shAPE up IIS7-based web servers, and one of the most exciting is that you don't actually need a dedicated server to install it! If your hosting provider supplies shared accounts with IIS7 support, you will almost undoubtedly be able to install Helicon Ape on your web site without having to bother the server administrator.

We’ll now tell you the steps to be done to do this:
  1. Find a hosting with IIS7 on it;
  2. Download Helicon Ape to your local machine. Not to the hosting!
  3. Install it locally specifying «Manual package» installation type.

  4. Open Helicon Ape installation folder (e.g. "C:\Program Files\Helicon\Ape\ManualInstall");
  5. Open target site via FTP and go to wwwroot folder;

  6. Copy all content of ManualInstall folder into wwwroot (preserving folder structure). "All" includes:
    - Bin\Helicon.Ape.dll – the module itself;
    - Helicon\httpd.conf – server configuration file;
    - .htaccess – distributed config example;
    - example_web.config – Helicon Ape registration for the site;
    If there's no web.config in the root of the site, rename example_web.config into web.config. If web.config is already there, add the following lines into - section:
    <?xml version="1.0" encoding="UTF-8"?>
    <configuration>
            ...
            <system.webServer>
                    ...
                    <modules>
                      <add name="Ape" type="Helicon.Ape.ApeModule" />
                    </modules>
                    <handlers>
                      <add name="Ape" path="*.apeproxy" verb="*" type="Helicon.Ape.Mod.ProxyHandler" 
                      resourceType="Unspecified" preCondition="integratedMode" />
                    </handlers>
                    ...
            </system.webServer>
            ...
    </configuration>
  7. Open wwwroot\.htaccess and put the following lines at the bottom to check operability:

    RewriteEngine On
    RewriteRule . – [G]
  8. Make any request to your site and you should get the following result:

  9. That’s all. Helicon Ape is working!

Issues

"But it isn’t actually working!” you exclaim indignantly.
There are several possible issues:
  1. Firstly, let's have a glance at wwwroot\Helicon\error.log.

  2. In our case the hosting has restricted permissions in a way that doesn’t allow Ape use it’s trial protection, so it is necessary to enter the registration data. Ask for trial keys on support@helicontech.comJust add the following lines at the top of wwwroot\Helicon\httpd.conf and save changes:
    RegistrationName= Name
    RegistrationCode= XXXXX-XXXXX-XXXXX-XXXXX
  3. There may be issues with your distributed configuration. .htaccess files may be used by other applications (such as ISAPI_Rewrite, IISPassword, etc) and it’s not that handy to create them in Windows Explorer. Luckily you are empowered to change the default config name using AccessFilename directive:

    AccessFileName Ape.ini
  4. Sometimes hosting configures the site to work in Classic pipeline mode. Ape can work in such environment (see how to configure wildcard mapping) but it’s better to ask your hosting to switch the pool to Integrated mode.
  5. It may happen that hosting has set too low.Net Trust Level for the site. This may affect Helicon Ape operation.

    Full level ensures flawless operation of all modules. It is acceptable to use any level down to Medium. With lower level values Helicon Ape will work with substantial limitations.

Resume

As you could see configuring Helicon Ape on shared hosting is piece of cake! And no administrator help is needed. You can do everything by yourself in a matter of minutes.
We are looking forward to your comments and suggestions.

Good luck and best wishes,
HeliconTech Team