The IIPImage server is a feature-rich high performance imaging server engineered to be stable, fast and lightweight. It is designed for streaming extremely high resolution images and is capable of handling advanced image features such as 16 and 32 bit per channel depths, floating point data, CIELAB colorimetric images and scientific imagery such as multispectral or hyperspectral images and digital elevation map data.

The server  is an Fast CGI module written in C++ that is designed to be embedded within a host web server such as Apache, Lighttpd or Nginx. It, therefore, requires you to have administration rights to your web server. Client applications connect to the server and receives back image metadata, image tiles or dynamically generated complete JPEG images at the desired resolution and JPEG quality factor. Clients can communicate with the server using either the native IIP protocol or alternatively, the Zoomify or DeepZoom protocols.

The server has been designed to be cross-platform and 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!

For detailed source code level documentation, see the documentation included with the source code or online.

Installing the IIPImage Server

Building on Linux, Mac OS X, *BSD, UNIX etc

On systems that don’t include an IIPImage package, you will need to compile the server for your system. The build process is based on the standard GNU autoconf system and should work on all UNIX style environments (eg Linux, Solaris, Mac OSX etc). The only external dependencies are the libtiff TIFF library and a libjpeg compatible library, which can be either the official IJG JPEG library or libjpeg-turbo. If you use deflate-compressed TIFF images, you will also need zlib compression library, but this is almost always installed by default anyway. To compile, first unpack the IIPImage server distribution and use the following standard 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 FastCGI directory of your web server. Note that “make install” will not install the binary for you.


For Debian and Ubuntu users, IIPImage is included as an official package from Ubuntu 12.10 and Debian 7.0 onwards. To install, simply install as you would any other software:

sudo apt-get install iipimage-server

For older versions, there are pre-built binaries available for download. You will need to install the prerequisite libraries, a web server (either Apache or Lighttpd) and the iipimage-server package. These packages includes Memcached support and, optionally, JPEG2000 support.

See this blog post for more details on how to install and use this package.


IIPImage is officially packaged in the core Fedora repositories for Fedora 19 onwards and available for Red Hat Enterprise Linux and CentOS via the EPEL repository. To use, simply install with the default yum package manager:

sudo yum install iipsrv

To use with Apache, install mod_fcgid and the iipsrv configuration files:

sudo yum install iipsrv-httpd-fcgi

See this blog post for more details and for how to install with Lighttpd or to run as an independent service.


Windows users should just download the binaries. It is also, of course, possible to build it yourself. The pre-built 1.0 and 0.9.9 binaries available for download have been built with Visual C++. Earlier versions were built with the open source dev-c++ IDE and MinGW.

To install with Apache on Windows, see this tutorial on how to install in 11 easy steps!.

To install with IIS5 or IIS6 on Windows, see this tutorial on IIS5/6 support. For IIS7, see this detailed tutorial on Installing IIPImage on IIS7.

Mac OS X

Mac OS X users can also download a binary distribution. See this post for how to install and configure.

Server Configuration

Startup variables

There are a number of configuration options for the server. However, these are all optional and the default settings are enough in many cases. If you require logging, you may wish to set the LOGFILE and VERBOSITY parameters. The full list of options are the following:

  • 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 6 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 10MB.
  • FILESYSTEM_PREFIX This is a prefix automatically added by the server to the beginning of each file system path. This can be useful for security reasons to limit access to certain sub-directories. For example, with a prefix of
    “/home/images/” set on the server, a request by a client for “image.tif” will
    point to the path “/home/images/image.tif”.¬† Any reverse directory path component such as ../ is also filtered out. No default value.
  • MAX_CVT Limits the maximum image dimensions in pixels (the WID or HEI commands) allowable for dynamic JPEG export via the CVT command. This prevents huge requests from overloading the server. The default is 5000.
  • MAX_LAYERS The maximum number of quality layers to decode for images that support progressive quality encoding, such as JPEG2000. Ignored for other file formats. If not set, half of the available quality layers will be decoded by default. If set to -1, all the available layers will be decoded by default.
  • FILENAME_PATTERN Pattern that follows the name stem for a multispectral or 3D 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 such multiple image sources. The default is “_pyr_”.
  • WATERMARK (iipsrv-0.9.9 or later) TIFF image to use as watermark file. This image should be not be bigger the tile size used for TIFF tiling. If bigger, it will simply be cropped to the tile size. If smaller, the watermark will be positioned randomly within the available space. The image can be either colour or grayscale. See this section on watermarking for more information on how to create and use watermarks with iipsrv.
  • WATERMARK_PROBABILITY (iipsrv-0.9.9 or later) The probability that a particilar tile will have a watermark applied to it. 0 means never, 1 means always.
  • WATERMARK_OPACITY (iipsrv-0.9.9 or later) The opacity (between 0 and 1) applied to the watermark image.
  • MEMCACHED_SERVERS (iipsrv-0.9.9 or later) A comma-delimitted list of memcached servers with optional port numbers. For example: “localhost,,”.
  • MEMCACHED_TIMEOUT (iipsrv-0.9.9 or later) Time in seconds that cache remains fresh. Default is 86400 seconds (24 hours).
  • INTERPOLATION¬†(iipsrv-1.0 or later) Interpolation method to use for rescaling when using image export. Integer value. 0 for fastest nearest neighbour interpolation. 1 for bilinear interpolation (better quality but about 2.5x slower). Bilinear by default.
  • CORS (iipsrv-1.0 or later) Cross Origin Resource Sharing setting. Sets the Access-Control-Allow-Origin status on the server for AJAX requests. Use “*” for full public access or specify a particular IP address or domain. Not set by default. See the W3C specification or¬†this tutorial for more details.
  • BASE_URL (iipsrv-1.0 or later) Set the public base URL the server is accessed from in case URL rewriting is taking place. Used for certain metadata responses with, for example, the IIIF protocol.
  • CACHE_CONTROL¬†(iipsrv-1.0 or later) Set the HTTP Cache-Control header. See for a full list of options. If not set, header defaults to “max-age=86400” (24 hours).
  • DECODER_MODULES Comma separated list of 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).


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.6.tar.gz from the FastCGI source directory. Windows users may find it useful to follow this tutorial for installing with Apache.

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/

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

  # Syntax for access is different in Apache 2.4 - uncomment appropriate version
  # Apache 2.2
  #   Order allow,deny
  #   Allow from all

  # Apache 2.4
  Require all granted

# 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 \
-listen-queue-depth 1024 \
-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

The -initial-env directives allow you to pass startup variable arguments directly to iipsrv. The -listen-queue-depth directive defines the depth of the listen queue, which is set by mod_fastcgi to only 5 by default. A higher value will allow the server to handle larger bursts of requests. 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. 1 instance should, however, be enough for most cases.


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

LoadModule fcgid_module /path/to/apachemodules/

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
  # Syntax for access is different in Apache 2.4 - uncomment appropriate version
  # Apache 2.2
  #   Order allow,deny
  #   Allow from all

  # Apache 2.4
  Require all granted

  # Set the module handler
  AddHandler fcgid-script .fcgi

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

# Define the idle timeout as unlimited and the number of # processes we want
FcgidIdleTimeout 0
FcgidMaxClassProcessesPerClass 1

[Note that on CentOS, FcgidIPCDir is configured by default to /var/log/httpd/fcgidsock, which may not be writable by Apache. If this is the case, specify another location for FcgidIPCDir, which is writable, such as /tmp/fcgidsock]


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" => "",
     "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"

It’s also possible to use load balancing within lighttpd by adding multiple hosts. Each of these iipsrv instances needs to be started on these hosts either via lighttpd or using the command line on that host:

fastcgi.server = (
        "/fcgi-bin/iipsrv.fcgi" => (
            ("host"=>"", "port"=>9000, "check-local"=>"disable"),
            ("host"=>"", "port"=>9000, "check-local"=>"disable"),
            ("host"=>"", "port"=>9000, "check-local"=>"disable")

For Debian and Ubuntu users, if lighttpd is installed on your system. the lighttpd configuration file is automatically installed at /etc/lighttpd/conf-available/20-iipsrv.conf. You can edit the *bin-environment* field in this file as above to configure the IIPImage server parameters. Then restart lighttpd in the usual way:

sudo /etc/init.d/lighttpd force-reload


Nginx is an increasingly popular high-performance HTTP server and reverse proxy, which also supports FastCGI. The one drawback with regards to iipsrv is that it cannot automatically spawn FCGI processes, so you will need to use nginx together with spawn-fcgi or start iipsrv from the command line.

To set up nginx with iipsrv add a directive such as this to your nginx configuration, which will forward requests to /fcgi-bin/iipsrv.fcgi to a running iipsrv process on port 9000.

location /fcgi-bin/iipsrv.fcgi {
	fastcgi_pass 	localhost:9000;
	fastcgi_param   PATH_INFO $fastcgi_script_name;
        fastcgi_param   REQUEST_METHOD $request_method;
        fastcgi_param   QUERY_STRING $query_string;
        fastcgi_param   CONTENT_TYPE $content_type;
        fastcgi_param   CONTENT_LENGTH $content_length;
        fastcgi_param   SERVER_PROTOCOL $server_protocol;
        fastcgi_param   REQUEST_URI $request_uri;
        fastcgi_param   HTTPS $https if_not_empty;

Nginx can also handle load balancing to multiple iipsrv instances, which can be hosted on the same machine on multiple ports or on different hosts. For a multiple host configuration, declare the load balancing like this:

upstream iip {

and change the fastcgi_pass parameter in the above location configuration to point to this instead of a fixed address:

fastcgi_pass 	iip;


iipsrv can also be used with lighttpd’s spawn-fcgi without the need for a full web server. Simply spawn the iipsrv process on the command line. The process can be bound to an IP address and port for backend load-balancing configurations. For example:

spawn-fcgi -f src/iipsrv.fcgi -a -p 9000

You can set the server parameters by setting them as environment variables before starting the above command. For example:

export LOGFILE=/tmp/iipsrv.log
export VERBOSITY=5

Java Application Servers (Tomcat, Jetty, JBoss etc)

IIPImage can also be used with Java Application Servers such as Apache Tomcat, JBoss and Jetty. Simply add the JFastCGI jar file to your webapp and add the following to your web.xml configuration file in order to re-route FCGI requests to the IIPImage server on the specified port.

<!-- Gateway Servlet to IIPImage FCGI server -->



You then need to start an instance of the server on the requested port (6667 in this example) using spawn-cgi (see spawn-cgi section above).

Command Line

It is also possible to start iipsrv directly on the command line (iipsrv-0.9.9 or later). For example:

iipsrv.fcgi --bind

where the argument given to bind is the socket on which to listen to FCGI requests. This can be either a UNIX socket or an IP address and port number. Set the configuration parameters via environment variables before starting iipsrv:

export VERBOSITY=5
export MEMCACHED_SERVERS=localhost
export WATERMARK=/tmp/watermark.tif

There is additionally a --backlog parameter (iipsrv-1.0 or later), that is optional and sets the socket backlog value. The backlog value specifies the number of requests can be queued and, therefore, increases the number of concurrent connections that iipsrv can handle and is set to 2048 by default. For example:

iipsrv.fcgi --bind --backlog 1024

Note that the backlog parameter must be specified after the bind parameter and argument. Note also that this value may be limited by the operating system. On Linux kernels < 2.4.25 and Mac OS X, the backlog limit is hard-coded to 128, so any value above this will be limited to 128 by the OS. If you do provide a backlog value, verify whether the setting /proc/sys/net/core/somaxconn should be updated.

Starting iipsrv on the command-line enables iipsrv to listen to FCGI (not HTTP) requests. To use iipsrv started in this way, you need a web server, which needs to have FCGI enabled and which must be configured to connect to this socket for FCGI. For example, the iipsrv instance above can be used with lighttpd by adding the following configuration directive:

fastcgi.server = (
  "/fcgi-bin/iipsrv.fcgi" => (
        ("host"=>"", "port"=>9000, "check-local"=>"disable")

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/
LoadModule proxy_http_module modules/

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.

Flattr this

Donations appreciated Bookmark and Share
Get IIPImage at Fast, secure and Free Open Source software downloads