Apache Configuration

All configuration for DIMS should be in the ‘’dims.conf’’ configuration file.

To load mod_dims add the following to your Apache server configuration:

<IfModule !mod_dims.c>
    LoadModule dims_module /path/to/mod_dims.so
</IfModule>

AddHandler dims-local .gif .jpg .png
DimsAddClient test http://placehold.it/350x150 86400

<Location /dims/>
    SetHandler dims
</Location>

<Location /dims3/>
    SetHandler dims3
</Location>

<Location /dims4/>
    SetHandler dims4
</Location>

<Location /dims-status/>
    SetHandler dims-status
</Location>

You will want to add configuration parameters detailed below.

It is also useful to enable core dumps using CoreDumpDirectory and setting ulimit -c unlimited.

Configuration Parameters

DimsDefaultImageURL: The image to display in case of errors or invalid requests. It should be a URL to an image. It can be a file:/// URL.

DimsDefaultImageURL http://o.aolcdn.com/art/ch_music2/albumartmissing DimsDefaultImageURL file:///path/to/no_image.gif

DimsDownloadTimeout: The length of time, in milliseconds, to wait for a remote image source to be retreived.

DimsDownloadTimeout 5000

DimsImagemagickTimeout: The length of time, in milliseconds, to allow ImageMagick to perform manipulations.

DimsImageMagickTimeout 25000

DimsCacheExpire: The default length of time, in seconds, to set the Cache-Control, Edge-Control and Expires headers.

DimsCacheExpire 86400

DimsNoImageCacheExpire: The default length of time, in seconds, to set the Cache-Control, Edge-Control and Expires headers when a NOIMAGE is returned.

DimsNoImageCacheExpire 60

DimsAddClient: Add a client to the list of valid clients. Arguments are client_id noimage_url max_age downstream_ttl trust_source min_src_cache max_src_cache secret_key. The max_age and downstream_ttl arguments control the times returned for the Cache-Control and Edge-Control HTTP headers, respectively. The trust_source parameter expects the single value “trust” indicating that dims should forward the Cache-Control header from the source image (if it exists) into the returned Cache-Control AND Edge-Control HTTP headers. If it is missing, the values specified in max_age and downstream_ttl will be returned. The last two arguments min_src_cache and max_src_cache specify the range of allowable values to be forwarded from the source image. If the Cache-Control header is not within range, max_age and downstream_ttl will be returned. Only client_id is required. If
you do not want to set an argument, put ‘-’ as its value. If max_age is not set the default will be used. If downstream_ttl is not set it will not be returned in the headers. The secret_key is used with /dims4/ prefix to provide secure image manipulation of any
image without using whitelisting.

DimsAddClient PGMC http://o.aolcdn.com/art/ch_music2/albumartmissing 86400 86400 trust 3600 86400 s3cr3t
DimsAddClient TEST1 http://o.aolcdn.com/art/ch_music2/albumartmissing 86400 86400 trust
DimsAddClient TEST2 http://o.aolcdn.com/art/ch_music2/albumartmissing 86400 - trust
DimsAddClient TEST3 http://o.aolcdn.com/art/ch_music2/albumartmissing 86400 86400
DimsAddClient TEST4 http://o.aolcdn.com/art/ch_music2/albumartmissing 86400

DimsAddWhitelist: Add a hostname to the whitelist for retrieving remote images. Can be specified as a prefix glob *.aolcdn.com or an exact host, o.aolcdn.com. Multiple hostnames can be added per entry separated by a space or multiple entries can be used.

DimsAddWhitelist *.aolcdn.com cdn.aol.com

Available Log Metrics

A few metrics are available for logging by modifying the Apache LogFormat. To add these metrics to the Apache log add %{<metric_name>}n to the LogFormat.

DIMS_STATUS: This will contain an number indicating the status of the request.

Possible status code values are:

• 0 – DIMS_SUCCESS
• 1 – DIMS_FAILURE
• 2 – DIMS_DOWNLOAD_TIMEOUT
• 4 – DIMS_IMAGEMAGICK_TIMEOUT
• 8 – DIMS_BAD_CLIENT
• 16 – DIMS_BAD_URL
• 32 – DIMS_HOSTNAME_NOT_IN_WHITELIST

DIMS_ORIG_BYTES: The size, in bytes, of the original image before applying operations to it.

DIMS_DL_TIME: The time, in milliseconds, it took to download the original image. Always 0 for local image requests.

DIMS_IM_TIME: The time, in milliseconds, it took ImageMagick to apply the request operations. If ImageMagick operations timed out this will contain a -.

DIMS_TOTAL_TIME: The total time for this request, in milliseconds.

Cache Configuration

DIMS by itself does not cache the results of an image manipulation. Use mod_cache to prevent DIMS from resizing every request. It is probably easiest to use the mod_mem_cache variant (not to be confused with memcached) of mod_cache as the DIMS by itself uses very little memory leaving a lot of memory for caching.

Here is an example configuration, note that CacheMaxExpire should to be set otherwise mod_cache will attempt to use the Expires header which may be much longer.

LoadModule cache_module modules/mod_cache.so
LoadModule mem_cache_module modules/mod_mem_cache.so

<IfModule mod_cache.c>
    CacheEnable mem /
    CacheDisable /dims-status/

    CacheMaxExpire 120
    CacheDefaultExpire 120

    # mod_mem_cache (128MB cache size with max of 1M per object and max of 1024 objects)
    MCacheSize 131072
    MCacheMinObjectSize 1024
    MCacheMaxObjectSize 1048576
    MCacheMaxObjectCount 100
    MCacheRemovalAlgorithm LRU
</IfModule>

More information on this module can be found in the [http://httpd.apache.org/docs/2.2/caching.html Apache Caching Guide].