Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
IIPSRV(8)		    System Manager's Manual		     IIPSRV(8)

       IIPSRV -	IIPImage Image Server

       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  im-
       agery  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 con-
       trol, conversion	from color to greyscale, color twist,  region  extrac-
       tion and	arbitrary rescaling. The server	can also export	spectral point
       or profile data from multispectral data and apply color maps or perform
       hillshading rendering.

       Command line use:

       iipsrv.fcgi --bind host : port

       iipsrv.fcgi main	executable

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

       There  are several parameters that can be supplied to iipsrv.fcgi These
       should be set via the appropriate web server  configuration  directives
       if  running  via	 Apache	 or  Lighttpd. See 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

	      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.

	      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  LOGFILE
	      has also been defined.

	      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 de-
	      fault is 75.

	      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 de-
	      fault is 5MB.

	      This is a	prefix automatically added by the server to the	begin-
	      ning  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/im-
	      ages/image.tif".	 Any  reverse directory	path component such as
	      ../ is also filtered out.	No default value.

	      The maximum permitted image pixel	size returned by the CVT  com-
	      mand in conjunction with WID or HEI or RGN. The default is 5000.
	      This prevents huge requests from overloading the server

	      Determines whether an image may be rendered at  a	 size  greater
	      than that	of the source image. A value of	0 will prevent upscal-
	      ing.  The	default	is 1 (upscaling	is allowed).

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

	      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 im-
	      age can be either	colour or grayscale.

	      The probability that a particular	tile will have a watermark ap-
	      plied to it. 0 means never, 1 means always.

	      The opacity (between 0 and 1) applied to the watermark image.

	      A	 comma-delimitted list of memcached servers with optional port
	      numbers. For example: localhost,,

	      Time in seconds that cache remains fresh.	Default	is 86400  sec-
	      onds (24 hours).

	      Pattern  that  follows  the  name	stem for a panoramic image se-
	      quence.  eg: "_pyr_" for FZ1_pyr_000_090.tif.  In	this  example,
	      just supply FZ1 to the FIF command. The "000" indicates the ver-
	      tical angle and "090" the	horizontal. This is only  relevant  to
	      3D image sequences. The default is "_pyr_".

	      Interpolation  method  to	use for	rescaling when using image ex-
	      port.  Integer value. 0 for fastest nearest neighbour interpola-
	      tion.  1	for  bilinear  interpolation (better quality but about
	      2.5x slower). Bilinear by	default.

       CORS   Cross Origin Resource Sharing setting. Disabled by default.  Set
	      to  "*"  to  enable  for all domains or specify a	single domain.
	      See for more details on CORS.

	      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 iipsrv

	      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	proto-
	      col handler without requiring web	server rewriting.

	      Set the HTTP Cache-Control header. See
	      cols/rfc2616/rfc2616-sec14.html#sec14.9  for  a full list	of op-
	      tions. If	 not  set,  header  defaults  to  "max-age=86400"  (24

	      Set whether the ICC profile is embedded within the output	image.
	      0	to strip profile, 1 to embed profile. The default is 1 (embed-
	      ded profiles).

	      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.

	      Set  the Kakadu JPEG2000 read-mode. 0 for	'fast' mode with mini-
	      mal 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  de-

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

       You  may	 also  wish to run 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, iipsrv will bind
       to port 9000 on the machine's IP	address

       % iipsrv.fcgi --bind

       There is	additionally a --backlog parameter that	is optional  and  sets
       the socket backlog value. The backlog value specifies the number	of re-
       quests can be queued and, therefore, increases the number of concurrent
       connections  that  iipsrv can handle and	is set to 2048 by default. For

       % iipsrv.fcgi --bind --backlog 1024

       Note that the backlog parameter must be specified after the bind	param-
       eter and	argument.  Note	also that this value may be limited by the op-
       erating 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 iipsrv via	the 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

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

       For use in stand	alone or spawn-fcgi mode, you will then	need  to  con-
       figure  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  Tom-
       cat,  JBoss  or Jetty, which cannot automatically start FCGI processes,
       iipsrv will need	to be started in stand alone mode or via spawn-fcgi.

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

       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=/im-
       ages/test.tif)  and  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 re-
       quests 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 not need to be directly accessible externally by
       the client via the web server.

       IIPImage	website:

       Ruven Pillay <>

Ruven Pillay			   June	2019			     IIPSRV(8)


Want to link to this manual page? Use this URL:

home | help