.TH IIPSRV 8 "June 2019" "Ruven Pillay"
.SH NAME

IIPSRV \- IIPImage Image Server

.SH DESCRIPTION
IIPImage is an advanced high-performance feature-rich multi-protocol image server for web-based streamed viewing and zooming of ultra high-resolution
images. It is designed to be fast and bandwidth-efficient with low processor and memory requirements. The system can comfortably handle gigapixel size images as
well as advanced image features such as 8, 16 and 32 bit depths, CIELAB colorimetric images and scientific imagery such as multispectral images.
Source images can be either TIFF (tiled multi-resolution) or JPEG2000 (if enabled).

The image server can also dynamically export images in JPEG format and perform basic image processing, such as contrast adjustment, gamma control, conversion from color to greyscale, color twist, region extraction and arbitrary rescaling. The server can also export spectral point or profile data from multispectral data and apply color maps or perform hillshading rendering.

.SH SYNOPSIS

Command line use:

.B iipsrv.fcgi --bind
.I host
:
.I port


.SH FILES

.IR iipsrv.fcgi
main executable

.IR iipsrv.log
log file: usually in
.IR /var/log/
or
.IR /tmp/


.SH OPTIONS

There are several parameters that can be supplied to
.B iipsrv.fcgi
These should be set via the appropriate web server configuration directives if running via Apache or Lighttpd. See
.B EXAMPLES
for details of web server configuations.
Alternatively these parameters can be set via environment settings if running directly from the command line or from
.B spawn-fcgi.

.IP 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.
.IP 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
.BR LOGFILE
has also been defined.
.IP 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.
.IP 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.
.IP 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.
.IP 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
.IP ALLOW_UPSCALING
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).
.IP MAX_LAYERS
The maximum number of quality layers to decode for image that support
progressive quality encoding, such as JPEG2000. Ignored for other file
formats. By default half of the available layers are decoded. If set to -1, all the available layers will be decoded.
.IP WATERMARK
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.
.IP WATERMARK_PROBABILITY
The probability that a particular tile will have a watermark applied to it. 0 means never, 1 means always.
.IP WATERMARK_OPACITY
The opacity (between 0 and 1) applied to the watermark image.
.IP MEMCACHED_SERVERS
A comma-delimitted list of memcached servers with optional
port numbers. For example: localhost,192.168.0.1:8888,192.168.0.2.
.IP MEMCACHED_TIMEOUT
Time in seconds that cache remains fresh. Default is 86400 seconds (24 hours).
.IP FILENAME_PATTERN
Pattern that follows the name stem for a panoramic image sequence.
eg: "_pyr_" for
.IR 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
relevant to 3D image sequences. The default is "_pyr_".
.IP INTERPOLATION
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.
.IP CORS
Cross Origin Resource Sharing setting. Disabled by default.
Set to "*" to enable for all domains or specify a single domain.
See http://www.w3.org/TR/cors/ for more details on CORS.
.IP BASE_URL
Set a base URL for use in certain protocol requests if web server rewriting has taken place and the public URL is not the same as that supplied to
.B iipsrv
.IP URI_MAP
Set a mapping from a URL prefix to a supported protocol. This enables iipsrv to
be able to work without requring 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.
.IP CACHE_CONTROL
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).
.IP EMBED_ICC
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).
.IP 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.
.IP KAKADU_READMODE
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.


.SH EXAMPLES

.B iipsrv
will be automatically started by both Apache and Lighttpd. But not by Nginx or Java Application Servers.
See the example configuration in the README or included with your distribution for the appropriate syntax.
Note that Apache has two FCGI modules: mod_fastcgi and mod_fcgid which are configured differently.

You may also wish to run
.B iipsrv
as a standalone program. To do this, use the following syntax to bind to a particular port and listen for FCGI (not HTTP) requests.
In the following example,
.B iipsrv
will bind to port 9000 on the machine's IP address 192.168.0.1:

% iipsrv.fcgi --bind 192.168.0.1:9000

There is additionally a
.B --backlog
parameter 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
.B iipsrv
can handle and is set to 2048 by default. For example:

% iipsrv.fcgi --bind 192.168.0.1:9000 --backlog 1024

Note that the backlog parameter must be specified
.B 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.


It is also possible to run
.I iipsrv
via the
.I spawn-fcgi
program. Set up any parameters via environment variables and run the command as follows to bind, as in the previous example to port 9000 on IP address 192.168.0.1:

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

For use in stand alone or spawn-fcgi mode, you will then need to configure your webserver on the same machine or another to direct FCGI protocol requests to this IP address and port.

For web servers such as Nginx or Java Application Servers such as Tomcat, JBoss or Jetty, which cannot automatically start FCGI processes,
.B iipsrv
will need to be started in stand alone mode or via spawn-fcgi.


.SH PROTOCOLS

The IIPImage server supports the
.B Internet Imaging Protocol (IIP)
, the
.B Zoomify
protocol, the
.B DeepZoom
and the
.B International Image Interoperability Framework (IIIF)
protocols. Client applications supporting these protocols should be able to use
.B iipsrv
as their back-end server.
.B IIP
is the most feature rich of the 4 protocols and allows access to the more advanced imaging server features.



.SH IMAGE PATHS

The image paths given to the server must be absolute paths on the server machine (eg. via the FIF variable for the IIP protocol: FIF=/images/test.tif) and
.I not
paths relative to the web server document root location. If the FILESYSTEM_PREFIX server directive has been set (see OPTIONS above), then this prefix is automatically pre-pended to all requests
to generate the absolute image path. Make sure that the server process owner is able to access and read the images.

Note that images do
.I not
need to be directly accessible externally by the client via the web server.


.SH SEE ALSO
IIPImage website: https://iipimage.sourceforge.io

.SH AUTHORS
Ruven Pillay <ruven@users.sourceforge.net>