Follow iipimage on Twitter

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

Debian

Alternatively for Debian users, there is a pre-built binary. First download the pre-requisite libraries:

% sudo apt-get install libfcgi, libjpeg62, libtiff4, zlib1g, libstdc++6

Then install the iipimage debian package from the download page:

% sudo dpkg -i iipimage-0.9.8.deb

The `iipsrv.fcgi` Fast CGI binary is installed into `/usr/lib/cgi-bin`. There is a lighttpd configuration file included in the debian package. See the lighttpd section below for details.

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 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.
  • LAYERS The number of quality layers to decode for image that support progressive quality encoding, such as JPEG2000. Ignored for other file formats. The default is 1.
  • 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_”.
  • 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.2.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. 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"
      )
  ))
)

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

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

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.

 
Donations appreciated Bookmark and Share
SourceForge.net Logo