Server

Introduction

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 colour depths, floating point data, CIELAB colorimetric images and scientific imagery such as multispectral or hyperspectral images.

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, MyServer 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.

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.

Debian/Ubuntu

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.

Fedora/Redhat/CentOS

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

Windows users should just download the binaries. It is also, of course, possible to build it yourself. The pre-built 0.9.9 binary available for download has 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

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 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,192.168.0.1:8888,192.168.0.2″.
  • MEMCACHED_TIMEOUT (iipsrv-0.9.9 or later) Time in seconds that cache remains fresh. Default is 86400 seconds (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).

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.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/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 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/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
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

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"
      )
  ))
)

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"=>"192.168.0.1", "port"=>9000, "check-local"=>"disable"),
            ("host"=>"192.168.0.2", "port"=>9000, "check-local"=>"disable"),
            ("host"=>"192.168.0.3", "port"=>9000, "check-local"=>"disable")
        )
)

Debian users who have installed the iipimage package can simply use the included configuration file. First install lighttpd and enable iipimage:

sudo apt-get install lighttpd
sudo ln -s /etc/iipimage/iipimage-lighttpd.conf /etc/lighttpd/conf-available/99-iipimage.conf
sudo lighty-enable-mod iipimage
sudo /etc/init.d/lighttpd force-reload

You can edit the *bin-environment* field in this file to configure the IIPImage parameters.

Finally, link the default IIPMooViewer into the webserver root directory:

sudo ln -s /usr/share/iipimage/www /var/www/iip

Nginx

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
}

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 {
	server 192.168.0.1:9000;
	server 192.168.0.2:9000;
	server 192.168.0.3:9000;
	server 192.168.0.4:9000;
}

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

fastcgi_pass 	iip;

spawn-fcgi

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 192.168.0.1 -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 -->

<servlet>
  <servlet-name>fcgi</servlet-name>
  <servlet-class>net.jr.fastcgi.FastCGIServlet</servlet-class>
  <init-param>>
    <param-name>server-address</param-name>
   <param-value>127.0.0.1:6667</param-value>
  </init-param>
</servlet>

<servlet-mapping>
  <servlet-name>fcgi</servlet-name>
  <url-pattern>/cgi-bin/iipsrv.fcgi</url-pattern>
</servlet-mapping>

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).

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

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 192.168.0.1:9000

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

Your web server needs to be configured to use this socket. For example with lighttpd:

fastcgi.server = (
  "/fcgi-bin/iipsrv.fcgi" => (
        ("host"=>"192.168.0.1", "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/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.

Flattr this




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