eRez Imaging Server 3.1
Configuration Guide
04-may-2005
Copyright 2001-2005 YaWah.com. All Rights Reserved
NOTE: Version 3.0 and later of the eRez Imaging Server comes with a web based configuration tool that allows you to edit almost all settings of the configuration files.
So, unless you want to read or write the eRez configuration files from your own applications or need to tweak some of the rarely used settings, you can skip reading this document.
Table of contents
This document describes the various configuration files and how they are used to configure the eRez Imaging Server. The server will check for changes to the configuration files every 30 seconds and automatically reconfigure itself accordingly.
All configuration files are in XML format. If you don’t know XML but know the basics of HTML you will be soon be familiar with the format. But, don’t panic If you have never seen an XML or HTML document before. XML is not rocket science and you will quickly learn enough of the syntax to deal with the eRez configuration files. If you want to learn the basics before you continue you can run though one of the many online tutorials on the web like http://www.w3schools.com/xml/.
The main configuration file is called erez.xml and is placed in the WEB-INF folder in the erez2 folder. This is what the standard file looks like:
<?xml version="1.0" encoding="iso-8859-1"?>
<yawah>
<system file="WEB-INF/config/system.xml"/>
<users file="WEB-INF/config/users.xml"/>
<license file="WEB-INF/config/license.xml"/>
<shares file="WEB-INF/config/shares.xml"/>
<formats file="WEB-INF/config/formats.xml"/>
</yawah>
This file simply contains references to 5 other configuration files normally located in the WEB-INF/configuration folder. You only need to edit erez.xml if you have moved your configuration files to a different location. You might want to do that in order to to share the same set of configuration files between multiple eRez server.
The XML files can be edited using a standard text editor. If you have Microsoft Internet Explorer installed on your machine you can use it verify the syntax of the XML files. When opening the erez.xml in Internet Explorer it would look like this:
Microsoft Internet Explorer can be used to verify the syntax of XML files
and present the content in a more readable way.
The 5 files used by erez are:
Among the very first things to do after installing eRez is to change the password for the “administrator” user account. This is done by editing the users.xml as explained in the next section.
Among the first things you should do is to change the password for the “administrator” account and configure and enable the “emailer” settings.
To change the password for the administrator account please refer to “User Administration”.
To avoid unintentional sending of emails when the software is first installed sending of emails has been disabled. To enable emails refer to the chapter “The <emailer > element”.
The default user.xml file looks like this:
<?xml version="1.0" encoding="iso-8859-1"?>
<usersandgroups>
<group name="administrator"/>
<group name="users"/>
<!--
Admin User. Encrypted password created using the Apache
htpasswd utility: Typing: htpasswd -snb admin admin
Outputs: admin:{SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc=
-->
<user
login="admin"
password="{SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc="
email="administrator@yawah.com"
firstname="eRez"
lastname="Administrator"
>
<member group="*"/>
</user>
<!--
Sample User with plain-text password.
-->
<user
login="user"
password="user"
email="user@yawah.com"
firstname="eRez"
lastname="User"
>
<member group="users"/>
</user>
</usersandgroups>
The text between the “<!—“ and “-->” are comments and ignored when the file is read by eRez.
The file starts with a standard XML header. Next comes a “tag” marking the beginning of the “usersandgroups” element. Inside this tag there can be any number of “group” and “user elements”.
A “group” element simply contains the name of a group. To add a third group called “friends” you simply add it to the document like this:
<group name="administrator"/>
<group name="users"/>
<group name="friends"/>
The “administrator” group is a special group. Only members of the administrator group will be able to check the status of the server and enter a license key.
A “user” elements looks like this:
<user
login="user"
password="user"
email="user@yawah.com"
firstname="eRez"
lastname="User"
>
<member group="users"/>
</user>
The meaning of “login”, “password”, “email”, “firstname” and “lastname” attributes requires no further explanation. The value of the password attribute can either be a plain-text password or an encrypted password like in the “administrator” example:
<user
login="admin"
password="{SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc="
email="administrator@yawah.com"
firstname="eRez"
lastname="Administrator"
>
<member group="*"/>
</user>
Encrypted passwords start with the string “{SHA}” and are automatically identified by the eRez server as such. These encrypted passwords can be generated by means of the htpasswd utility that comes with the Apache web server.
The password for the administrator was generated by entering:
htpasswd -snb admin admin
It is very important to use the “s” option to specify SHA encryption. The ouputt looks like this:
admin:{SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc=
The password to place in the users.xml is the part following the initial colonand starting with {SHA},
Individual users are assigned membership of a group by means of a “member” sub-element,
To add the user “user” to the new “friends” group you simple add an extra “member” element like this:
<user
login="user"
password="user"
email="user@yawah.com"
firstname="eRez"
lastname="User"
>
<member group="users"/>
<member group="friends"/>
</user>
You can add individual memberships of as many groups as you like to a single user. If you use “*” as the group name, the user will be given membership of ALL groups. This is the case for the administrator:
<user
login="admin"
password="{SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc="
email="administrator@yawah.com"
firstname="eRez"
lastname="Administrator"
>
<member group="*"/>
</user>
The default shares.xml file looks like this:
<?xml version="1.0" encoding="iso-8859-1"?>
<yawah>
<mount
name="Format Samples"
path="WEB-INF/sample images/formats"
cache="WEB-INF/cache"
viewgroup="*"
listgroup="*"
downloadgroup="?"
uploadgroup="?"
editgroup="?"
deletegroup="administrator"
/>
<mount
name="Color Management"
path="WEB-INF/sample images/cms"
cache="WEB-INF/cache"
viewgroup="?"
listgroup="users"
downloadgroup="administrator"
uploadgroup="administrator"
editgroup="administrator"
deletegroup="administrator"
/>
</yawah>
Inside the “yawah” element there must be a “mount” for every folder that you want to share.
The various xxxgroup attributes define the groups to which a user must belong in order to carry out certain operations. Two special values for the xxxgroups attributes exist:
If one or more of the xxxgroup attributes are removed altogether, the operation(s) will be completely disabled. If for example you don’t want anybody (including the administrator) to be able delete and edit files and folders, you can delete the lines with the deletegroup and editgroup attributes:
<mount
name="Color Management"
path="WEB-INF/sample images/cms"
cache="WEB-INF/cache"
viewgroup="?"
listgroup="users"
downloadgroup="administrator"
uploadgroup="administrator"
/>
After removing these lines no one will be able to delete or edit files or folders in the share.
Attributes for the mount element:
name |
The public name of the share. This is the name that users will see when listing the contents of the server. |
path |
The local path to the directory with images and sub-directories. This can be a path to a local hard drive or a remote server like "\\HOST\SHARE\EREZ\STUFF" on a Windows System. The sample configuration file that ships with the software uses a special path: "WEB-INF/…”. "WEB-INF" is a special case supported in order to make the eRez Imaging Server work with sample images immediately after the installation. DO NOT PLACE YOUR OWN IMAGES OR CACHE IN THE WEB-INF DIRECTORY. |
cache |
The directory where derived images are stored for reuse. The same cache directory can be shared by several shares or you can use a separate cache for each. |
viewgroup |
The group to which a user must belong in order to view images. |
listgroup |
The group to which a user must belong in order to list the contents of the share. Without this group membership the share will be completely invisible to the user- |
downloadgroup |
The group to which a user must belong in order to download images. |
uploadgroup |
The group to which a user must belong in order to upload images. |
editgroup |
The group to which a user must belong in order to edit images and folders. |
deletegroup |
The group to which a user must belong in order to delete images and folders. |
hotfolder |
Setting this attribute to the value “0” disables monitoring and indexing of the files for full text search etc. All other values or omitting the attribute entirely leaves indexing and monitoring enabled. |
The file formats.xml contains a “yawah” element with an arbitrary number of “format” and/or “downloadformat” elements. The “format” elements define the image templates for use with the real-time channel. The “downloadformat” elements define the image templates for use with the asynchronous – or download – channel.
This is what the “format” element for the thumbnail template looks like:
<format name="Thumbnail">
<crop top="0" left="0" bottom="1" right="1"/>
<size width="90" height="90"/>
<color colorspace="sRGB"/>
<sharpen amount="20"/>
<output format="JPEG" quality="80"/>
</format>
Format only has a single attribute. The rest of the data is defined as sub-elements. The individual values of the templates can be modified by specifying a different value as part of the image URL. Please refer to the HTTP Command Reference for more information on how to override the values from a template.
Attributes for format:
name |
The name of the template. |
hidden |
Optional. If this is set to “1” the template will not be displayed to the user. |
Attributes for crop (optional format sub-element):
top |
The part of the image to remove at the top. Must be in the range 0.0 (top) to 1.0 (bottom). |
left |
The part of the image to remove at the left. Must be in the range 0.0 (left) to 1.0 (right). |
bottom |
The amount of the image to remove at the bottom. Must be in the range 0.0 (top) to 1.0 (bottom). |
right |
The part of the image to remove at the right. Must be in the range 0.0 (left) to 1.0 (right). |
angle |
The rotation of the image in degrees. |
Attributes for size (format sub-element):
width |
The maximum width of the image in pixels. |
height |
The maximum height of the image in pixels. |
keepaspect |
Preserves the relative width and height of the source image (default). When this is disabled by setting the value to “0” the dimensions of the resulting image will be exactly as requested. |
antialias |
Optional. If this is set to “0” the default anti-alias filter will be disabled. |
Attributes for color (format sub-element):
colorspace |
Not currently used. MUST BE "sRGB" FOR FUTURE USE. |
Attributes for sharpen (format sub-element):
amount |
The amount of sharpening to apply to the image. Must be in the range -500 (heavy blur) to 500 (strong sharpening). A value of 0 applies no sharpening. |
Attributes for output (format sub-element):
format |
The image file format for the generated image. Legal values are: |
quality |
The quality of JPEG compressed images. Must be in the range 0 (poor quality/small image) to 100 (perfect quality/very large image). For PDF images a value of "0" means no JPEG compression and ZIP compression will be used instead. For PNG and EPS this attribute is ignored. |
chromasubsampling |
Enables downsampling of color information during JPEG compression (default). When setting this attribute to the value “0” this will be disabled the file size will increase as much as 30 percent. But the color information is preserved at full resolution. Certain computer generated images may appear blurry unless this option is disabled. |
Attributes for fill (optional format sub-element):
color |
The RGB background color used to pad the image in order to fill the template box. Uses standard web color format (e.g. ff0000 is red, 00ff00 is green etc..). |
Attributes for watermark (optional format sub-element):
image |
The local path and filename to an uncompressed RGB TIFF image with an alpha channel (transparency). This can be a path to a local harddrive or a remote server like "\\HOST\SHARE\EREZ\STUFF" on a Windows System. The sample configuration file that ships with the software uses a special path: "WEB-INF/overlays/*.tif". "WEB-INF" is a special case supported in order to make the eRez Imaging Server work with sample setup immediately after the installation. DO NOT PLACE YOUR OWN WATERMARK IMAGES IN THE WEB-INF DIRECTORY. |
Attributes for downloadformat:
name |
The name of the template. This is the name used to refer to the template from an URL. |
description |
A human readable description that can be displayed to the user while choosing from the templates. |
Attributes for size (downloadformat sub-element):
width |
The maximum width of the image in pixels. |
height |
The maximum height of the image in pixels. |
Attributes for interpolate (downloadformat sub-element):
maxscale |
Maxscale defines the maximum enlargement of the source image in percent. The default value is 100. For example to allow the images to be enlarged (interpolated) by 20 percent use a value of 120. |
action |
Action controls the behavior of image processor when the source image does not contain sufficient data to create the destination image without breaking the maxscale barrier. Legal values are: |
Attributes for color (downloadformat sub-element):
colorspace |
The description of the ICC profile to use. This is NOT the filename - but the textual description as embedded in the profile. You can see a list of descriptions from the available profiles on the Server Status page. See the <iccprofiles> element above on how to add additional ICC profiles. |
renderingintent |
Optional rendering intent for the color transformation. Legal values are: 0: Perceptual 1: Relative Colorimetric 2: Saturation 3: Absolute Colorimetric |
Attributes for sharpen (downloadformat sub-element):
amount |
The amount of sharpening to apply to the image. Must be in the range -500 (heavy blur) to 500 (strong sharpening). A value of 0 applies no sharpening. The "sharpen" filter is best suited for low resolution output. Use "unsharpmask" instead for high resolution CMYK output. |
Attributes for unsharpmask (downloadformat sub-element):
amount |
The amount of sharpening to apply. The interpretation of "amount" has been designed to mimic the behavior of Adobe Photoshop - but you will have to experiment a little to get the optimum result. As an alternative you may consider using the simple "sharpen" filter for low resolution images. |
radius |
The radius of the gauss kernel used to calculate the unsharp value. The interpretation of "radius" has been designed to mimic the behavior of Adobe Photoshop - but you will have to experiment a little to get the optimum result. |
threshold |
This attribute is currently ignored and reserved for future use. |
Attributes for output (downloadformat sub-element):
format |
The image file format for the generated image. Legal values are: |
quality |
The quality of JPEG compressed images. Must be in the range 0 (poor quality/small image) to 100 (perfect quality/very large image). For PDF images a value of "0" means no JPEG compression and ZIP compression will be used instead. For EPS this attribute is ignored. |
dpi |
The resolution of the output image in "dots per inch". A value of 0 means that the dpi is automatically calculated to preserve the width and height (as in centimeters or inches) of the source image. |
compression |
The compression scheme to use for TIFF images. Legal values are: "none" - no compression. "jpeg" - JPEG compression. "zip" - lossless ZIP compression. |
renderpaths |
If this is set to “1” the current clipping path (if any) will be applied and the background will be filled with white. (from eRez version 2.5) |
chromasubsampling |
Enables downsampling of color information during JPEG compression (default). When setting this attribute to the value “0” this will be disabled the file size will increase as much as 30 percent. But the color information is preserved at full resolution. Certain computer generated images may appear blurry unless this option is disabled. |
tilesize |
A value of “0” uses the standard “stripped” layout for the TIFF file (default). Specifying a tile size will using such as 128, 256 or 512 will create images organized as quadratic tiles which increases performance considerably depending on the size of the source images. This is highly recommended when working with images larger than 50 Mb and a “must” for images with a size of several gigabytes. Note: This format is in compliance with the TIFF specification but some older imaging applications may not be able to read it correctly. |
The erez-home element defines the public URL of the eRez sever. This is used when creating emails and building HTML page with the URL Builder. Erez-home only contains a single attribute URL.
Sample: <erez-home url=http://localhost:8080/erez2 />
The emailer element specifies various properties used when sending emails. If the “Admin” is set to a valid email address then an email is sent to that address when the server is started and when an error requires immediate attention. The settings for smtp and bcc are used when a user emails an image or folder. If “bcc” is set to a valid email address then a blind carbon copy of every email is sent to that address as well.
Sample:
<emailer
disabled="0"
smtp="smtp.yawah.com"
from="erez2@yawah.com"
replyto="devnull@yawah.com"
bcc="devnull@yawah.com"
admin="devnull@yawah.com"
/>
Attributes for emailer:
disabled |
Used to disable the email functions. By default this is set to “1”. To enable email change it to “0”. |
smtp |
The hostname or ip address of the outgoing SMTP server. |
from |
The default “from” email address. |
replyto |
The default “replyto” email address. |
bcc |
An email address that “Blind Carbon Copies” are sent to to every time an email sent. |
admin |
The email address of the eRez administrator, |
The flat-images element specifies the maximum uncompressed size in Mb allowable for a single-resolution image such as JPEG. The default value is 4 Mb and you should only increase it if you have a very powerful server with lots of memory.
Sample:
<flat-images
sizelimit="4"
/>
The imagefactory element controls behavior of the real-time image-processor. Only one <imagefactory> element is allowed in the configuration file.
Sample: <imagefactory threads="2" cachelimit="100"/>
Attributes for imagefactory:
threads |
The maximum number of concurrent image processing operations. The default value is 2. The optimal setting depends on the number of CPUs and available memory on the server. |
cachelimit |
The maximum size of each cache in mega bytes. When this attribute is present the server will check each cache every 5 minutes and delete the least recently used images until the total size of the images is equal or less to the cachelimit value. Make sure that every cache in the mount element is correct and contains nothing but eRez data before adding a cachelimit to your configuration. |
The downloadfactory element controls behavior of the asynchronous/download image-processor. Only one <downloadfactory> element is allowed in the configuration file.
Note that you must restart the servlet container in order for modifications to the downloadfactory element to take effect and alocate a minimum of 128MB RAM per thread to the Java Virtual Machine.
Sample: <downloadfactory threads="1" workpath="WEB-INF/download"/>
Attributes for downloadfactory:
threads |
The maximum number of concurrent image processing operations. The default value is 1. The optimal setting depends on the number of CPUs and available memory on the server. |
workpath |
The path of a directory to temporarily hold the processed images and ZIP files. The sample value "WEB-INF/download" in order for eRez to work immediately after installation - but it is strongly recommended to change this to a folder outside the "erez" directory. |
The "browser" element controls the layout of the thumbnail listings. Only one <browser> element is allowed in the configuration file.
Sample: <browser rows="3" columns="4" width="110" imageheight="110" textheight="12"/>
Attributes for browser:
rows |
The vertical number of thumbnails per page. |
columns |
The horisontal number of thumbnails per page. |
width |
The width in pixels for each thumbnail cell. |
imageheight |
The height in pixels of the image part of each thumbnail cell. |
textheight |
The height in pixels of the text part of each thumbnail cell. |
From eRez version 1.1.7 rows and columns can be specified via parameters and the other properties are now controlled directly from the template.
The "iccprofiles" element is used to specify paths to directories with external ICC profiles. You can add as many <iccprofiles> elements as you need.
Sample: <iccprofiles path="WEB-INF/icc profiles"/>
Attributes for iccprofiles:
path |
The local path to the directory with ICC profiles. This can be a path to a local hard drive or a remote server like "\\HOST\SHARE\EREZ\PROFILES" on a Windows System. The sample configuration file that ships with the software uses a special path: "WEB-INF/sample images". "WEB-INF" is a special case supported in order to make the eRez Imaging Server work with the bundled profiles immediately after the installation. |
The "mactext" element is used to identify and convert IPTC text data created on an Apple Macintosh computer. Because the Macintosh uses a special character set, national and special characters like the Danish æ,ø and å will be displayed incorrectly by eRez and other software packages on another platform. Because there is no simple way to detect if an IPTC record was created on a Macintosh we use a trigger mechanism. When one of the trigger characters is found in an IPTC text the entire chunk of text is treated as being "MacRoman".
The MacRoman character set is used for at least the following Mac OS, localizations: U.S., British, Canadian French, French, Swiss, French, German, Swiss German, Italian, Swiss Italian, Dutch, Swedish, Norwegian, Danish, Finnish, Spanish, Catalan, Portuguese, Brazilian, and the default International system.
This example will trigger on the danish characters 'æ', 'ø', 'å', 'Æ', 'Ø' and 'Å':
<mactext>
<trigger value="be"/>
<trigger value="bf"/>
<trigger value="8c"/>
<trigger value="ae"/>
<trigger value="af"/>
<trigger value="81"/>
</mactext>
Attributes for trigger (mactext sub-element):
value |
The hexadecimal representation of a character (see table below). |
The Standard MacRoman character set.
The hotfolder element is used to specify the pause time between each scan for changes to the contents of shared folders.
Example: <hotfolders sleeptime="300" />
The attribute specifies the pause time in seconds. If there is no hotfolder element or sleeptime attribute a default value of 300 seconds (5 minutes) is used.
The encoding element is used to specify the encoding used when creating HTML document from velocity templates.
Example: <encoding charset="iso-8859-1" />
The attribute charset defines the encoding. Using a value of “” will use the standard encoding as obtained by Java from the underlying operating system. If there is no encoding element or charset attribute “iso-8859-1” will be used.
The metadatacache element is used to specify the maximum number of images to cache metadata for in memory.
Example: <metadatacache size="500" />
The attribute size specifies the maximum number of images to cache metadata for in memory. eRez will keep an up-to-date copy of the metadata for the most recently used images in RAM to increase the performance for frequently used images.
The encryption element is used to override the secret password used by eRez to build special URLs for use with slideshows and showcases for non-public folders and queries.
Example: <encryption key="snullerbat" />
The attribute key specifies the secret password used by eRez to build special URLs for use with slideshows and showcases for non-public folders and queries.