Server

Introduction

IIPImage is a client-server system. The server is an Fast CGI module written in C++ that runs within a host web server such as Apache, Lighttpd or MyServer. The client application connects to the server and receives back image metadata, image tiles or dynamically generated complete JPEG images at the desired resolution and JPEG quality factor. The client communicates with the server using the IIP protocol.

The server has been successfully tested on Linux, Sun Solaris, Mac OS X and Windows. It should also work on any other UNIX environment. If anyone has tried and succeeded (or especially failed!) on SGI or HP-UX etc, please get in touch!

Building the IIPImage Server

Linux, Mac OS X, *BSD, UNIX etc

On Linux and other UNIX systems, it is recommended that you compile the server, if possible, in order to fully optimize it for your system. The build process is based on the standard GNU autoconf system and should work in all UNIX style environments (eg Linux, Solaris, Mac OSX etc). The only external dependencies are the libtiff TIFF library and the IJG JPEG library. If you use deflate-compressed TIFF images, you will also need zlib compression library, but this is almost always installed by default anyway. Simply unpack the IIPImage server distribution and use the usual build sequence:

% tar jxvf iipsrv-<version>.tar.bz2
% cd iipsrv-<version>
% ./configure
% make

This should create the server binary, called iipsrv.fcgi, in the src subdirectory of the distribution, which should be copied to the Fast CGI directory of your web server.

Windows

The easiest way is simply to install MyServer and use the Windows IIPImageServer installer, which will install and configure everything for you! It is also, of course, possible to build it yourself. The pre-built binary available for download has been built with the open source dev-c++ IDE and MinGW.

Server Configuration

Startup variables

The startup variables are all optional:

LOGFILE The log file the module will (attempt) to write to. If no value is given, no log will be written. Make sure the server process has write access to this directory. Paths with spaces in them may not work correctly.
VERBOSITY The level of logging. 0 means no logging, 1 is minimal logging, 2 lots of debugging stuff and 3 even more debugging stuff and 4 a very large amount indeed ;-) Logging is only enabled if LOGFILE has also been defined.
JPEG_QUALITY The default JPEG quality factor for compression when the client does not specify one. The value should be between 1 (highest level of compression) and 100 (highest image quality). The default is 75.
MAX_IMAGE_CACHE_SIZE Max image cache size to be held in RAM in MB. This is a cache of the compressed JPEG image tiles requested by the client. The default is 5MB.
DECODER_MODULES External modules for decoding other image formats. This is only necessary if you have activated --enable-modules for ./configure and written your own image format handler(s).
FILENAME_PATTERN Pattern that follows the name stem for a panoramic image sequence. eg: "_pyr_" for FZ1_pyr_000_090.tif. In this example, just supply FZ1 to the FIF command. The "000" indicates the vertical angle and "090" the horizontal. This is only relevent to 3D image sequences. The default is "_pyr_".
MAX_CVT The maximum permitted image pixel size returned by the CVT command in conjunction with WID or HEI or RGN. The default is 5000. This prevents huge requests from overloading the server.

Apache

You will require Apache with FCGI module support. Many Linux distributions already include the Apache FCGI module (for example, on Gentoo, simply do emerge mod_fastcgi). Otherwise download and build mod_fastcgi-2.4.2.tar.gz from the FastCGI source directory.

Make sure it is activated by checking that mod_fastcgi appears at the top of the http://your.server/server-status status page. If the status page does not work, check your apache configuration to make sure the server-status feature is enabled. If the status page is working, but it does not mention mod_fastcgi, make sure a line like this appears in the apache configuration file to load the module:

LoadModule fastcgi_module /path/to/apachemodules/mod_fastcgi.so

You will then need to configure Apache for the IIPImage server. This is an example extract from the apache configuration file (normally httpd.conf) which activates and passes several parameters to the IIPImage server. A directory for your FastCGI programs should be created if one does not already exist (eg. fcgi-bin in the server root directory next to the cgi-bin directory for CGI programs) and the server binary should be copied into this directory. In the following example, the FastCGI directory has been created in /usr/local/httpd/fcgi-bin/. This path can be changed to any path directory accessible by the apache process.

# Set the options on that directory
<Directory "/usr/local/httpd/fcgi-bin">
AllowOverride None
Options None
Order allow,deny
Allow from all
</Directory>


# Set the handler
AddHandler fastcgi-script fcg fcgi fpl


# Initialise the FCGI server - set some default values
FastCgiServer /usr/local/httpd/fcgi-bin/iipsrv.fcgi \
-initial-env LOGFILE=/tmp/iipsrv.log \
-initial-env VERBOSITY=2 \
-initial-env JPEG_QUALITY=50 \
-initial-env MAX_IMAGE_CACHE_SIZE=10 \
-initial-env MAX_CVT=3000

In addition, the -processes directive can set the number of server instances to run in parallel. The more simultaneous clients you have, the more instances you will need. For example, to run 4 instances of iipsrv, add -processes 4 line to the end of the FastCgiServer directive.

mod_fcgid

mod_fcgid is a binary compatible replacement for mod_fastcgi. It works in the same way, but is configured differently. Load the module like this:

LoadModule fcgid_module /path/to/apachemodules/mod_fcgid.so

Here is an example configuration. Note that mod_fcgid does not have a FastCgiServer directive and there is no need to explicitly start the server:

# Create a directory for the iipsrv binary
ScriptAlias /fcgi-bin/ "/var/www/localhost/fcgi-bin/"

# Set the options on that directory
<Directory "/var/www/localhost/fcgi-bin/">
   AllowOverride None
   Options None
   Order allow,deny
   Allow from all

   # Set the module handler
   AddHandler fcgid-script .fcgi
</Directory>

# Set our environment variables for the IIP server
DefaultInitEnv VERBOSITY "5"
DefaultInitEnv LOGFILE "/tmp/iipsrv.log"
DefaultInitEnv MAX_IMAGE_CACHE_SIZE "10"
DefaultInitEnv JPEG_QUALITY "50"
DefaultInitEnv MAX_CVT "3000"

# Define the idle timeout as unlimited and the number of processes we want
IdleTimeout -1
DefaultMaxClassProcessCount 1

Lighttpd

Lighttpd is a fast and light-weight web server that comes with built-in FastCGI support. Simply add the following lines to your configuration file (normally /etc/lighttpd.conf):

fastcgi.server = ( "/fcgi-bin/iipsrv.fcgi" =>
  (( "host" => "127.0.0.1",
     "port" => 9000,
     "check-local" => "disable",
     "min-procs" => 1,
     "max-procs" => 1,
     "bin-path" => "/var/www/localhost/fcgi-bin/iipsrv.fcgi",
     "bin-environment" => (
        "LOGFILE" => "/tmp/iipsrv.log",
        "VERBOSITY" => "5",
        "MAX_IMAGE_CACHE_SIZE" => "10",
        "FILENAME_PATTERN" => "_pyr_",
        "JPEG_QUALITY" => "50",
        "MAX_CVT" => "3000"
      )
  ))
)

MyServer

MyServer has only been tested with IIPImage on Windows so far. In order to install, simply run the IIPImageServer installer, paying attention to put files in the right place, run MyServer Configuration and in the MIME section, choose the .fcgi extension and select:

MIME Type: application octet-stream
Action: Execute self contained FastCGI
Manager: NONE

Unfortunately you cannot pass any arguments to the server

Proxy Forwarding

The Ajax and Java security models only permit connections to be made to the same host as that which served the web page. These must also be written in the same way - you cannot mix numerical and written hostnames even if they point to the same machine. However, it is often a good idea to host the IIP image server on a separate machine to the main webserver. To overcome the security limitation, you will need to perform proxy forwarding in this case. With Apache, for example, there is the mod_proxy module which can easily do this. First enable mod_proxy in the Apache configuration file if it has not already been activated:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so

Then include a proxy directive to forward requests to iipsrv.fcgi to another machine:

ProxyPass /fcgi-bin/iipsrv.fcgi http://remotehost/fcgi-bin/iipsrv.fcgi
ProxyPassReverse /fcgi-bin/iipsrv.fcgi http://remotehost/fcgi-bin/iipsrv.fcgi

All requests to /fcgi-bin/iipsrv.fcgi on your public web server will now be transparently forwarded to your image server, which does not now need to even be directly connected to the internet.