Helicon Zoo Module

The core of Helicon Zoo technology is Helicon Zoo Module. It allows running all these engines and applications under IIS server. Basically, Helicon Zoo Module is a load balancing HTTP/FastCGI proxy with built-in process manager and some other features to help hosting applications under IIS.  Zoo module was initially designed to run automatically, without additional configuration needed. In this document you will find some explanations about Helicon Zoo Module internals and configuration directives you may use to tune the module.

Helicon Zoo Module is a fully native IIS 7 module written in pure C++ using super fast and capacitive technologies, like IOCP. It provides ability to run various web engines and technologies side by side on a single IIS web site and to utilize whole power of multicore servers by automatically increasing number of workers on multycore systems to reach best performance on high load applications. It can run FastCGI-compatible web engines as well as HTTP back-ends using TCP/IP or Named Pipes as transport protocol.

Helicon Zoo Module configuration

To separate web server administrator configurations from webmaster configurations we have used the concept of engines and applications.

applicationHost.config

Engines are declared globally in applicationHost.config file. Each engine tag sets properties, like command line arguments, protocol, transport, etc., to run specific web engine. Engines are configured as <engines> collection in <heliconZooServer> section of applicationHost.config. There is another collection called <userEngines> which has same syntax and owerrides <engines> collection. The <userEngines> collection is used to override engines and create new ones, if you need to preserve these settings between Helicon Zoo Module upgrades. Helicon Zoo installation wil not modify or delete <userEngines> section. Here is an example:

<?xml  version="1.0" encoding="UTF-8"?>
<configuration>
 <system.webServer>
  <heliconZooServer>
   <engines>
       <add name="ruby.1.9.pipe"
             fullPath="%SystemDrive%\Ruby19\bin\rubyw.exe"
             arguments="%SystemDrive%\Zoo\Workers\ruby\zack.rb"
             transport="NamedPipe"
             protocol="fastcgi"  />
       <add name="nodejs.http" 
             fullPath="%SystemDrive%\node\bin\node.exe"
             arguments="&quot;%APP_WORKER%&quot;"
             transport="tcp"
             protocol="http" >
          <environmentVariables>
            <add name="APP_WORKER" value="%APPL_PHYSICAL_PATH%\server.js" />
            <add name="NODE_PATH" value="%APPL_PHYSICAL_PATH%\node_modules" />
            <add name="WATCH_FILE_CHANGES_MASK" value="*.js" />
          </environmentVariables>
       </add>
    </engines>
    <userEngines>
       <add name="php.5.2.pipe" displayName="Php 5.2 fastCgi" fullPath="%ProgramFiles(x86)%\PHP\v5.2\php-cgi.exe"
            arguments="-c &quot;%PHP_INI%&quot;" transport="NamedPipe" protocol="fastcgi">
          <environmentVariables>
             <add name="ERROR_LOG_DIR" value="NULL" />
             <add name="WATCH_FILE_CHANGES_MASK" value="php.ini" />
             <add name="PHP_INI" value="%ProgramFiles(x86)%\PHP\v5.2\php.ini" />
             <add name="PHP_FCGI_MAX_REQUESTS" value="100000" />
          </environmentVariables>
       </add>
    </userEngines>
  </heliconZooServer>
 </system.webServer>
</configuration>


This is the list of all possible attributes of <engine> tag with explanations:

  • name – sets a name for the engine.
  • fullPath – a path to a worker executable file.
  • arguments – set of arguments to be passed to a worker on a call, can include special environment variables, see below.
  • deployArguments – optional set of arguments to be passed to a worker on a call to deploy script.
  • protocol – possible values “fastcgi” or “http”.
  • transport – possible values “namedpipe” or “tcp”.
  • portLower – specifies lower bound for automatic port range for TCP transport, default = 49152.
  • portUpper – specifies upper bound for automatic port range for TCP transport, default = 65535 (different engines can share same port region).
  • minInstances – minimum number of worker instances. Zoo will pre-start this amount of instances even if there’s no load to the server, default = 1
  • maxInstances – maximum number of instances of worker processes to start under high load. Default value of 0 means start as many instances as there are cores.
  • postBuffer – maximum size of a memory buffer used to temporarely store request post data. Useful to protect against slow post DDOS attacks. default = 1024 (kilobytes). Use postBuffer="0" to disable buffering post requests.
  • timeLimit – restart the worker after it has worked for specific amount of time (minutes), default = 0 (infinite).
  • memoryLimit – restart the worker if it has consumed specific amount of memory (megabytes), default = 0 (unlimited).
  • gracefulShutdownTimeout – time given to worker to finish all current requests and shutdown gracefully, otherwise it will be killed after this timeout, default = 30 (seconds).


Aditionally to parameters you can specify environment variables. These variables will be available in web engine's environament and can be used as additional parameters to specific applications or engine specific settings.

Some environment variables has special meaning to Helicon Zoo Module. Some are used to pass application specific parameters to Zoo Module, others are set by Zoo Module to pass some application specific data to web engines.

Here is the list of environment variables set by Helicon Zoo Module that will be available to engine's worker:

  • APPL_PHYSICAL_PATH – a physical path to IIS application (web site) being called.
  • APPL_VIRTUAL_PATH – virtual path to IIS application being called.
  • HOST – usually 127.0.0.1.
  • PORT – port number assigned to this worker call form available ports range.


This is the list of environment variables you can set to confiugure application specific settings in Zoo Module:

  • POST_BUFFER – 1024 kilobytes by default.
  • POST_CACHE_DIR – you can define an application specific directory, to store temporary POST data in files, if size of data is larger than POST_BUFFER parameter. If POST_BUFFER is set to zero (0) this parameter is ignored and POST requests are not buffered by Zoo.
  • CURRENT_DIRECTORY – a start up directory for worker application; default is %APPL_PHYSICAL_PATH%.
  • ERROR_LOG_DIR – relative path to a directory where log files to be stored. Value of "NULL" disables logging.
  • WATCH_FILE_CHANGES_MASK – file mask to watch for file changes and restart workers if change is made. Example: "*.js".
  • DEPLOY_FILE – script file name that will be called when application needs to deploy. Engine's script processor is used to call this script. Path is Application Root-relative, example value="deploy.rb" - for Ruby applications. After deploy process is finished the deploy file will be renamed as "filename_done.ext" to prevent subsequent call to this script. Rename file back to start deploy again.
  • DEPLOY_LOG – file to store deploy script console output. If this parameter is not set deploy output will be shown to any client requesting the web site during deploy.
  • WORKER_REQUEST_TIMEOUT – smart worker request timeout; default = 30 (seconds). Helicon Zoo will try to "ping" backend if no response was provided during this timeout. If no response to the "ping" provided, "500 Error" is reported to the client and backend is restarted. If "ping" is responded Zoo continues to wait for next timeout. Therefore if backend hangs it will be restarted, but long polling and websocket communications will work without changing this smart timeout value.


In <engine> tag parameters, like fullPath or arguments you can reference environment variables using %VARIABLE_NAME% syntax and environment variables set in web.config files can also be referenced here.

Here is the list of all engines currently declared in applicationHost.config.

python.2.7.pipe
python.2.7.wsgi
python.2.7.http 
python.2.7.twisted 
ruby.1.9.pipe 
ruby.1.9.rack 
ruby.1.9.thin
ruby.goliath
ruby.1.8.pipe 
ruby.1.8.rack 
php.5.2.pipe 
php.5.3.pipe 
perl.5.12.pipe 
perl.5.12.psgi
nodejs.http
railo
railo.3
railo.4
java.jetty
java.appdir
zotonic.http

web.config

After declaring engines in applicationHost.config you can use them in web.config to initiate an application in specific location. Here is web.config section example:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
 <system.webServer>
  <heliconZoo>
   <application name="rails.project" >
    <environmentVariables>
     <add name="DEPLOY_FILE" value="deploy.rb" />
     <add name="DEPLOY_LOG" value="log\zoo-deploy.log" />
     <add name="RACK_ENV" value="development" />
    </environmentVariables>
    <fastcgiVariables>
     <add name="SCRIPT_NAME" value="%APPL_VIRTUAL_PATH%"  />
    </fastcgiVariables>
   </application>
  </heliconZoo>
  <handlers>
       <add name="rails.project#x86" scriptProcessor="ruby.1.9.rack"
          path="*" verb="*" modules="HeliconZoo_x86"
          preCondition="bitness32" resourceType="Unspecified"
          requireAccess="Script" />
       <add name="rails.project#x64" scriptProcessor="ruby.1.9.rack"
          path="*" verb="*" modules="HeliconZoo_x64"
          preCondition="bitness64" resourceType="Unspecified"
          requireAccess="Script" />
  </handlers>
 </system.webServer>
</configuration>

In <heliconZoo> section you can set or owerride environment variables specific for this application. Name of application used in <heliconZoo> section should be the same as name of appropriate handler in <handlers> section except for the #suffix. The #x86 or #x64 suffix is used to decalre different handlers for 32 or 64 bitness modules since web.config syntax requires every handler to have unique name. Helicon Zoo will ignore these suffixes so you can have only one <application> section for two handlers. The example above decalres two handlers which form one application and will be called when IIS is started in appropriate bitness.

Explanation of <handlers><add>tag attributes:

  • name="rails.project#x86" – name of the handler (with optional #suffix) for reference;
  • scriptProcessor="ruby.1.9.pipe" – name of the engine declared in applicationHost.config to use;
  • modules="HeliconZoo_x86" – 32-bit version of Helicon Zoo Module, for 64-bit version use "HeliconZoo_x64".