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 in <heliconZooServer> section of applicationHost.config. Here is an example:

<?xml  version="1.0" encoding="UTF-8"?>
<configuration>
 <system.webServer>
  <heliconZooServer>
   <engine name="ruby.1.9.pipe"
           fullPath="%SystemDrive%\Ruby19\bin\rubyw.exe"
           arguments="%SystemDrive%\Zoo\Workers\ruby\zack.rb"
           transport="NamedPipe"
           protocol="fastcgi"  />
   <engine 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>
   </engine>
  </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.
• protocol – possible values “fastcgi” or “http”.
• transport – possible values “namedpipe” or “tcp”.
• portLower – specifies lower automatic port range bound for TCP transport, default = 49152.
• portUpper – specifies upper automatic port range bound 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.
• minRequestsPerWorker – minimum requests queue length per worker to start garbage-collect unused workers, when load has lowered, default = 3.
• maxRequestsPerWorker – maximum requests queue length per worker to start new workers if possible, when load has increased, default = 15.
• 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 data to web engines.

Here is the list of environment variables set by Helicon Zoo Module:

• APPL_PHYSICAL_PATH – a physical path to IIS application 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_DIR – you can define an application specific directory, to store temporary POST data in files, if size of data is larger than postBuffer parameter. If postBuffer 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 upon every IIS application restart. Engine's script processor is used to call this script. This parameter is used for data migrations and deployment. So if you need to migrate data or run deploy procedure you will simply need to iisreset or restart IIS application after new versions of files are committed to the server. Path is Application Root-relative, example value="deploy.rb" - for Ruby applications.
• DEPLOY_LOG – file to store deploy script console output.
• 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
java.jetty
zotonic.http

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