Introduction
The IIPImage server is a feature-rich high performance image 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 written in C++ and uses the Fast CGI protocol to interface with a front-end web server such as Apache, Lighttpd or Nginx. It, therefore, requires you to have administration rights to your web server in order to configure it. Clients can communicate with the server using several APIs, including the IIP protocol, IIIF, Zoomify or DeepZoom protocols.
The server has been designed to be cross-platform and runs on Linux, Sun Solaris, Mac OS X and Windows. It should also work in 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.
The following sections explain how to build, install, configure and run the IIPImage server. There are also explanations on how to interface to different web servers and how to setup proxying or setup clean URLs.
Installing the IIPImage Server
Building on Linux, Mac OS X, *BSD, UNIX etc
Several Linux distributions as well as FreeBSD include official IIPImage binary packages. However, on systems that don’t include such a package, you will need to compile the server yourself for your system. The build process is straightforward and 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, which is almost always installed by default your distribution. Make sure you have the development versions of these packages installed, not just the runtime libraries.
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
If you have downloaded a development version from Github, run the following command before you run ./configure
% ./autogen.sh
Once the build process is complete, the server binary, called iipsrv.fcgi, will have been created in the src subdirectory of the distribution. This binary should be copied to an appropriate location on your system depending on how you intend to use iipsrv. Note that “make install” will not install the binary for you. See below for how to configure with various web servers.
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 download the binary distribution. The pre-built binaries available for download have been built with Visual Studio. If you prefer to build yourself, use the Visual Studio solution file in the windows sub-directory corresponding to your version of Visual Studio. See this guide for full details on building with Visual Studio.
You will then need to install these binaries depending on whether you are using Apache or IIS:
- 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 and the official IIS FCGI documentation for more details.
Mac OS X
Mac OS X users can also download a binary distribution. See this post for how to install and configure.
FreeBSD
IIPImage is an official FreeBSD package. Users can use the ports package system to install. See this blog post for more details on installation on FreeBSD.
Solaris
A binary distribution is available for Solaris users. See this blog post for more details on installation on Solaris.
Server Configuration
Startup variables
There are a number of configuration options for the server. However, these are all optional and the default settings are sufficient in most 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. Version 1.1 and later of iipsrv also supports logging to syslog if “syslog” is given as the value.
- 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.
- PNG_QUALITY (iipsrv-1.2 or later) The default PNG quality factor for compression when the client does not specify one. The value should be between 1 (highest level of compression) and 9 (highest image quality). The default is 1.
- WEBP_QUALITY (iipsrv-1.2 or later) The default WebP quality factor for compression when the client does not specify one. The value should be between 0 (highest level of compression) and 100 (highest image quality). The default is 50.
- 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.
- FILESYSTEM_SUFFIX (iipsrv-1.2 or later) This is a suffix added to the end of each file system path. It can be combined with FILESYSTEM_PREFIX. It is not used in combination with FILENAME_PATTERN. If e.g. this is set to “.tif”, an image URL such as “/UUID” will look for “${FILESYSTEM_PREFIX}/UUID.tif”. In the IIIF info.json document, the image @id will be set without the “.tif” suffix.
- 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).
- 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 http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9 for a full list of options. If not set, header defaults to “max-age=86400” (24 hours).
- ALLOW_UPSCALING (iipsrv-1.1 or later) Determines whether an image may be rendered at a size greater than that of the source image. A value of 0 will prevent upscaling. The default is 1 (upscaling is allowed).
- EMBED_ICC (iipsrv-1.1 or later) Set whether the ICC profile is embedded within the output image. 0 to strip profile, 1 to embed profile. The default is 1 (embedded profiles).
- URI_MAP (iipsrv-1.1 or later) Set a mapping from a URL prefix to a supported protocol. This enables iipsrv to be able to work without requiring full CGI query strings. Map must be of the form “prefix=>protocol” where prefix can be either empty or any string prefix and protocol must be one of IIP, IIIF, DeepZoom, Zoomify. Used, for example, to map requests of the form
http://server/iiif/to the IIIF protocol handler without requiring web server rewriting. See the clean URLs section for further details. - KAKADU_READMODE (iipsrv-1.1 or later) Set the Kakadu JPEG2000 read-mode. 0 for ‘fast’ mode with minimal error checking (default), 1 for ‘fussy’ mode with no error recovery, 2 for ‘resilient’ mode with maximum recovery from codestream errors. See the Kakadu documentation for further details.
- CODEC_PASSTHROUGH (iipsrv-1.3 or later) Enable pre-encoded tiles to be sent directly to the client without re-encoding or processing if the requested output encoding matches the encoding used within the source image. Enabled only for tile requests that map to a single tile in the source image and that do not specify or require any image processing or manually set the encoding quality level. Only works for TIFF with either JPEG or WebP-encoded tiles. Set to 1 to activate or 0 to disactivate. Default is 1 (activated).
- OMP_NUM_THREADS Set the number of OpenMP threads to be used by the iipsrv image processing routines (See OpenMP specification for details). All available processor threads are used by default.
- IIIF_VERSION (iipsrv-1.2 or later) Set the major IIIF Image API version. Values should be a single digit. For example: 2 for versions 2 or 2.1 etc. 3 for IIIF version 3.x. If not set, defaults to version IIIF 3.x
- IIIF_DELIMITER (iipsrv-1.3 or later) Set delimiter to enable page or slice selection for a multi-page or image stack for IIIF requests. Delimiter can be a single character or an arbitrary string. Disabled by default.
- IIIF_EXTRA_INFO (iipsrv-1.3 or later) Add extra arbitrary field to all IIIF info.json files. Must be a string containing a valid JSON key, value line. Key and value quotes should be escaped if necessary and no trailing comma should be added. For example, to add a preferredFormats field: IIIF_EXTRA_INFO='”preferredFormats”: [“webp”]’
- COPYRIGHT Specify a global copyright or rights statement if this is not available in the image metadata itself
- DECODER_MODULES Comma separated list of external modules for decoding other image formats. This is only necessary if you have activated
--enable-modulesfor./configureand written your own image format handler(s).
Web Servers
Apache
If you wish to use iipsrv with Apache and have Apache start and manage iipsrv for you automatically, you will need to install an Apache FCGI module. If, on the other hand, you only wish to forward IIPImage requests to another machine that hosts iipsrv, you should skip this section and instead configure your web server to do FCGI proxy forwarding.
Apache has two different modules that can handle FCGI: mod_fastcgi and mod_fcgid.
For mod_fastcgi, if your distribution already includes this module, you should use the package manager to install. Otherwise download and build mod_fastcgi. 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 /var/www/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 </Directory> # Set the handler AddHandler fastcgi-script fcg fcgi fpl # Initialise the FCGI server - set some default values FastCgiServer /var/www/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
mod_fcgid is a binary compatible replacement for mod_fastcgi and is an official Apache subproject. It is configured differently to mod_fastcgi. 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/fcgi-bin/" # Set the options on that directory <Directory "/var/www/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 </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 FcgidMaxProcessesPerClass 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" => "0.0.0.0",
"port" => 9000,
"check-local" => "disable",
"min-procs" => 1,
"max-procs" => 1,
"bin-path" => "/var/www/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")
)
)
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
Nginx is a 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 start iipsrv manually through spawn-fcgi, the command line or through using a process manager.
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 on localhost.
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 {
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 iipsrv.fcgi -a 0.0.0.0 -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>/fcgi-bin/iipsrv.fcgi</url-pattern>
</servlet-mapping>
You then need to start an instance of iipsrv on the requested port (6667 in this example).
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 0.0.0.0: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
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 0.0.0.0:9000 --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"=>"0.0.0.0", "port"=>9000, "check-local"=>"disable")
)
)
Automatically Starting the IIPImage Server
There are a number of ways to have iipsrv run automatically. Apache and Lighttpd, as mentioned above, have in-built FCGI process management which can start and monitor the iipsrv process automatically. However, when used with Nginx or Tomcat or if you wish to host iipsrv on a dedicated server behind your web server, you will need a different way to start the iipsrv process automatically.
As we’ve seen above, iipsrv can be run on the command line as an independent process. Because of this, it’s possible to use a process manager to run the iipsrv process. On UNIX-based systems, there exist a number of ways to mange and supervise processes. The most obvious is to use your system’s init software, such as systemd.
Systemd
To use with systemd, you can define an iipsrv service file, iipsrv.service, which should be placed in the /lib/systemd/system/ directory and should contain something like the following:
[Install] WantedBy=multi-user.target [Unit] Description=IIPImage server After=network.target Documentation=https://iipimage.sourceforge.io man:iipsrv(8) [Service] User=www-data Group=www-data EnvironmentFile=/etc/default/iipsrv ExecStart=/path/to/iipsrv.fcgi --bind 0.0.0.0:9000 --backlog 1024 Restart=on-failure
You should, of course, modify the path in ExecStart to point to the location of your iipsrv.fcgi binary. You should also set the User and Group under which iipsrv will run appropriately (www-data) is standard for Debian and Ubuntu-based distributions.
You can then create a settings file containing environment configuration variables for iipsrv, which should look something like:
VERBOSITY=5 LOGFILE=/var/log/iipsrv.log MAX_IMAGE_CACHE_SIZE=10 JPEG_QUALITY=90 MAX_CVT=5000 MEMCACHED_SERVERS=localhost
This should be put in the file /etc/default/iipsrv for Debian or Ubuntu or/etc/sysconfig/iipsrv for Fedora, CentOS or RHEL.
To start the iipsrv process, simply use the standard systemd tools:
systemctl start iipsrv
and to enable iipsrv to start automatically at boot:
systemctl enable iipsrv
Supervisor
An alternative to using your OS’s init system is to use a process control manager, such as supervisor or daemontools, which unlike systemd, is not designed to handle a full init system.
Supervisor is a Python-based process control manager, which has native support for FCGI and allows multiple FCGI processes to be started and share a single socket. To use, add something like the following to your /etc/supervisor/supervisord.conf configuration file:
[fcgi-program:iipsrv]
command=/path/to/iipsrv.fcgi
socket=tcp://0.0.0.0:9000
process_name=%(program_name)s_%(process_num)02d
numprocs=4
autostart=true
autorestart=unexpected
redirect_stderr=true
redirect_stdout=true
user=www-data
group=www-data
environment=MEMCACHED_SERVERS="127.0.0.1:11211",JPEG_QUALITY="90",MAX_CVT="5000",VERBOSITY="5",LOGFILE="/var/log/iipsrv_%(process_num)02d.log"
This example creates an FCGI socket on port 9000 and starts 4 iipsrv processes, which share this same socket. Environment configuration parameters for iipsrv are set via the environment directive.
Clean URLs
The default way to make a request to the server is through a URL of the form:
www.your.server/fcgi-bin/iipsrv.fcgi?IIIF=image.tif/info.json
which uses a standard URI query string syntax consisting the name of the iipsrv executable with a question mark followed by the iipsrv protocol request itself. However, it is possible configure iipsrv to use a shorter or “cleaner” URL without requiring the use of the full query string, question mark or protocol prefix as in the following IIIF example:
www.your.server/iiif/image.tif/info.json
To do this, you will need to configure your web server to relay requests from the requested URL prefix to the iipsrv process and also configure iipsrv to handle this request appropriately. The necessary web server configuration depends on the server being used. For Apache, this can be done in a number of ways, the simplest being to use the ScriptAlias directive to point to the executable like so:
ScriptAlias /iiif "/var/www/fcgi-bin/iipsrv.fcgi"
For lighttpd:
"/iiif" => (
("host"=>"0.0.0.0", "port"=>9000, "check-local"=>"disable")
)
For Nginx
location /iiif {
...
}
You now need to configure iipsrv via the URI_MAP server directive to map this prefix to a protocol supported by iipsrv such as IIIF. Using URI_MAP avoids having to configure your web server to perform URL rewrites. To set, for example, the “iiif” prefix to map to a clean IIIF request, set the URI_MAP parameter to “iiif=>IIIF”. For Apache and mod_fcgid, for example, this is done by adding the following line to your iipsrv server configuration:
FcgidInitialEnv URI_MAP "iiif=>IIIF"
This can be made to work for any of iipsrv’s supported image API’s, so for example, to have requests to a prefix “images” map to IIP requests, use the configuration:
FcgidInitialEnv URI_MAP "images=>IIP"
which allows requests to be made of the following form:
www.your.server/images/image.tif&WID=500&CVT=jpeg
Logging
It is possible for iipsrv to provide logging into a file or via the standard POSIX syslog logging facility on platforms that support this (version 1.1 onwards). Logging is controlled by the LOGFILE server directive, which controls where the log is sent to. Set this either to the full path of a file to which the iipsrv process has write access or to “syslog” to use syslog.
The mount of logging is determined by the VERBOSITY directive, where 0 disables logging.
Syslog
Logging via syslog has a number of advantages over writing directly to a file. It is not only more efficient to offload the work of logging to a separate service, but the syslog format is widely supported making it possible to use a wide range of monitoring software. Syslog itself is very customizable and can be configured in a number of ways. By default syslog messages are written to a common system log file. If you wish to re-direct iipsrv messages into its own separate log file, put the following into a configuration file in the appropriate location for your syslogger (for example on Debian or Ubuntu with rsyslog: /etc/rsyslog.d/20-iipsrv.conf):
$umask 0022 $FileCreateMode 0644 :programname,isequal,"iipsrv" /var/log/iipsrv.log & stop
Restart both iipsrv and your syslog service and logging will be output to this file.
Proxy Forwarding
It is often useful to host iipsrv on a separate machine to the main web server. This can be for both performance or security reasons. The Ajax and Java security models, for example, 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. The way to overcome this security limitation is to perform proxy forwarding, which allows the iipsrv host to be transparently hidden behind the front web server.
With Apache, it’s possible to do this with mod_proxy. In addition, you will need a specific transport layer module for HTTP through mod_proxy_http or from Apache 2.3 onwards, directly for FCGI using mod_proxy_fcgi. The direct FCGI proxy will give the better performance, so use this if available.
First enable mod_proxy and either mod_proxy_http or mod_proxy_fcgi in the Apache configuration file if it has not already been activated
LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so
Then include a proxy directive to forward requests to your iipsrv instance hosted on another machine. For an FCGI proxy to redirect to an iipsrv instance running on host remotehost on port 9000:
ProxyPass "/fcgi-bin/iipsrv.fcgi" "fcgi://remotehost:9000/"
Note that using a direct FCGI proxy will require the iipsrv.fcgi instance to be available at the remote host IP address on the given port number.
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.
It’s also possible to enable direct FCGI proxy forwarding using Lighttpd:
fastcgi.server = (
"/fcgi-bin/iipsrv.fcgi" => (
("host"=>"remotehost", "port"=>9000, "check-local"=>"disable")
)
And for Nginx by simply changing the fastcgi_pass parameter:
location /fcgi-bin/iipsrv.fcgi {
fastcgi_pass remotehost:9000;
...
}
Server Management
The internal iipsrv caches can be managed without having to stop and restart the server. To do this, use the POSIX signal functionality available on most platforms to send SIGHUP to iipsrv. This can be easily done on the command line on Linux, Mac OS X and Solaris using the kill command, where PID is the numerical process ID of the running instance. This signal empties the internal iipsrv caches without restarting it:
kill -SIGHUP PID
Note, however, that if you are using Memcached or a caching proxy server such as Varnish, those caches will not be affected by this.
