---
layout: manual
title: Upgrading
---

<h1>Upgrading</h1>

<p class="text-info"><i class="fa fa-info-circle"></i> If you are skipping versions, work through this page backwards from your current version.</p>

<h2>3.4.x &rarr; 4.0</h2>

<ol>
  <li>Rename the following configuration keys:
    <ul>
      <li>Any key containing the string <code>Resolver</code> to contain <code>Source</code></li>
      <li><code>HttpSource.auth.*</code> to <code>HttpSource.BasicLookupStrategy.auth.*</code></li>
      <li><code>AmazonS3Source.*</code> to <code>S3Source.*</code></li>
      <li><code>StreamProcessor.retrieval_strategy</code> to <code>processor.stream_retrieval_strategy</code></li>
      <li><code>KakaduProcessor.path_to_binaries</code> to <code>KakaduDemoProcessor.path_to_binaries</code></li>
      <li><code>AmazonS3Cache.*</code> to <code>S3Cache.*</code></li>
    </ul>
  </li>
  <li>Add the following keys from the sample configuration:
    <ul>
      <li><code>S3Source.endpoint</code></li>
      <li><code>S3Source.BasicLookupStrategy.path_prefix</code></li>
      <li><code>S3Source.BasicLookupStrategy.path_suffix</code></li>
      <li><code>processor.fallback_retrieval_strategy</code></li>
      <li><code>processor.imageio.*</code></li>
      <li><code>S3Cache.endpoint</code></li>
      <li><code>cache.server.source.ttl_seconds</code></li>
      <li><code>cache.server.derivative.ttl_seconds</code></li>
    </ul>
  </li>
  <li>Remove the following configuration keys:
    <ul>
      <li><code>S3Source.bucket.region</code></li>
      <li><code>processor.limit_to_8_bits</code></li>
      <li><code>S3Cache.bucket.region</code></li>
      <li><code>cache.server.source.enabled</code></li>
      <li><code>cache.server.ttl_seconds</code></li>
    </ul>
  </li>
  <li>Change any <code>AmazonS3Source</code> configuration values to <code>S3Source</code>.</li>
  <li>Change any configuration values containing <code>Resolver</code> to contain <code>Source</code>.</li>
  <li>Change any <code>AmazonS3Cache</code> configuration values to <code>S3Cache</code>.</li>
  <li>The delegate script architecture has changed, and the 3.x script is not compatible. See the "Delegate Script" section of the user manual for migration info.</li>
  <li>The deprecated <code>DELETE /cache/:identifier</code> HTTP API method has been removed. See the "Remote Management" section of the user manual for information about its successor.</li>
  <li>The <code>X-IIIF-ID</code> reverse proxy header is deprecated and will be removed in a future version. Start using <code>X-Forwarded-ID</code> instead.</li>
  <li>If you'd like to use the new KakaduNativeProcessor non-commercially for decoding JPEG2000 images, see the "Processors" section of the user manual for information on configuring it.</li>
</ol>

<h2>3.4 &rarr; 3.4.3</h2>

<p>Nothing to do.</p>

<h2>3.3.x &rarr; 3.4</h2>

<ol>
  <li>Add the following keys from the sample configuration:
    <ul>
      <li><code>temp_pathname</code></li>
      <li><code>http.http2.enabled</code></li>
      <li><code>https.http2.enabled</code></li>
      <li><code>http.accept_queue_limit</code></li>
      <li><code>endpoint.iiif.min_size</code></li>
      <li><code>endpoint.admin.username</code></li>
      <li><code>HttpResolver.trust_all_certs</code></li>
      <li><code>HttpResolver.request_timeout</code></li>
      <li><code>AmazonS3Resolver.max_connections</code></li>
      <li><code>processor.flv</code></li>
      <li><code>processor.limit_to_8_bits</code></li>
      <li><code>cache.server.source.enabled</code></li>
      <li><code>cache.server.derivative.enabled</code></li>
      <li><code>cache.server.info.enabled</code></li>
      <li><code>AmazonS3Cache.max_connections</code></li>
      <li><code>HeapCache.*</code></li>
      <li><code>RedisCache.*</code></li>
      <li><code>log.error.*</code></li>
    </ul>
  </li>
  <li>Rename the following keys:
    <ul>
      <li><code>auth.*</code> to <code>endpoint.public.auth.*</code></li>
      <li><code>admin.enabled</code> to <code>endpoint.admin.enabled</code></li>
      <li><code>admin.password</code> to <code>endpoint.admin.secret</code></li>
      <li><code>PdfBoxProcessor.dpi</code> to <code>processor.dpi</code></li>
      <li><code>cache.source</code> to <code>cache.server.source</code></li>
      <li><code>cache.derivative</code> to <code>cache.server.derivative</code></li>
      <li><code>metadata.*</code> to <code>processor.metadata.*</code></li>
    </ul>
  </li>
  <li>If you are using the delegate script, add a <code>context</code> argument to the method signature of any existing source delegates. See <span class="filename">delegates.rb.sample</span> for examples.</li>
  <li>The <code>DELETE /cache/:identifier</code> HTTP API method is deprecated and will be removed in version 4. Begin migrating now to the updated equivalent.</li>
  <li>Managing the cache on the command line with VM arguments is deprecated and will be removed in version 4. Begin migrating now to the cache management methods in the HTTP API.</li>
</ol>

<h2>3.3 &rarr; 3.3.5</h2>

<p>Nothing to do.</p>

<h2>3.2.x &rarr; 3.3</h2>

<ol>
  <li>Add the following keys from the sample configuration:
    <ul>
      <li><code>delegate_script.cache.enabled</code></li>
      <li><code>endpoint.api.*</code></li>
      <li><code>processor.dcm</code></li>
      <li><code>processor.normalize</code></li>
      <li><code>processor.background_color</code></li>
      <li><code>processor.upscale_filter</code></li>
      <li><code>processor.downscale_filter</code></li>
      <li><code>processor.sharpen</code></li>
      <li><code>processor.jpg.progressive</code></li>
      <li><code>processor.jpg.quality</code></li>
      <li><code>processor.tif.compression</code></li>
      <li><code>cache.server.ttl_seconds</code></li>
      <li><code>overlays.BasicStrategy.type</code></li>
      <li><code>overlays.BasicStrategy.string</code></li>
      <li><code>overlays.BasicStrategy.string.*</code></li>
    </ul>
  </li>
  <li>Rename the following keys:
    <ul>
      <li><code>watermark.*</code> to <code>overlays.*</code></li>
    </ul>
  </li>
  <li>Remove the following configuration keys:
    <ul>
      <li><code>JdbcResolver.max_pool_size</code></li>
      <li><code>FfmpegProcessor.sharpen</code></li>
      <li><code>GraphicsMagickProcessor.sharpen</code></li>
      <li><code>GraphicsMagickProcessor.background_color</code></li>
      <li><code>ImageMagickProcessor.sharpen</code></li>
      <li><code>ImageMagickProcessor.background_color</code></li>
      <li><code>JaiProcessor.sharpen</code></li>
      <li><code>JaiProcessor.jpg.quality</code></li>
      <li><code>JaiProcessor.tif.compression</code></li>
      <li><code>Java2dProcessor.upscale_filter</code></li>
      <li><code>Java2dProcessor.downscale_filter</code></li>
      <li><code>Java2dProcessor.sharpen</code></li>
      <li><code>Java2dProcessor.jpg.quality</code></li>
      <li><code>Java2dProcessor.tif.compression</code></li>
      <li><code>KakaduProcessor.upscale_filter</code></li>
      <li><code>KakaduProcessor.downscale_filter</code></li>
      <li><code>KakaduProcessor.sharpen</code></li>
      <li><code>OpenJpegProcessor.upscale_filter</code></li>
      <li><code>OpenJpegProcessor.downscale_filter</code></li>
      <li><code>OpenJpegProcessor.sharpen</code></li>
      <li><code>PdfBoxProcessor.upscale_filter</code></li>
      <li><code>PdfBoxProcessor.downscale_filter</code></li>
      <li><code>PdfBoxProcessor.sharpen</code></li>
      <li><code>FilesystemCache.ttl_seconds</code></li>
      <li><code>JdbcCache.max_pool_size</code></li>
      <li><code>JdbcCache.ttl_seconds</code></li>
      <li><code>AmazonS3Cache.ttl_seconds</code></li>
      <li><code>AzureStorageCache.ttl_seconds</code></li>
    </ul>
  </li>
  <li>If you are using FilesystemCache, purge your cache.</li>
  <li>If you are using the <code>authorized?()</code> or <code>watermark()</code> delegate methods, note that the contents of the <code>operations</code> argument have changed; see the new sample delegate script for more information.</li>
  <li>If you are using the <code>watermark()</code> delegate method, note that the <code>pathname</code> key in the returned hash must be changed to <code>image</code>.</li>
  <li>Rename the <code>watermark()</code> delegate method to <code>overlay()</code>.</li>
</ol>

<h2>3.2 &rarr; 3.2.4</h2>

<p>Nothing to do.</p>

<h2>3.1.2 &rarr; 3.2</h2>

<ol>
  <li>Add the following keys from the sample configuration:
    <ul>
      <li><code>FfmpegProcessor.sharpen</code></li>
      <li><code>GraphicsMagickProcessor.sharpen</code></li>
      <li><code>ImageMagickProcessor.sharpen</code></li>
      <li><code>JaiProcessor.sharpen</code></li>
      <li><code>Java2dProcessor.upscale_filter</code></li>
      <li><code>Java2dProcessor.downscale_filter</code></li>
      <li><code>Java2dProcessor.sharpen</code></li>
      <li><code>KakaduProcessor.upscale_filter</code></li>
      <li><code>KakaduProcessor.downscale_filter</code></li>
      <li><code>KakaduProcessor.sharpen</code></li>
      <li><code>OpenJpegProcessor.upscale_filter</code></li>
      <li><code>OpenJpegProcessor.downscale_filter</code></li>
      <li><code>OpenJpegProcessor.sharpen</code></li>
      <li><code>PdfBoxProcessor.upscale_filter</code></li>
      <li><code>PdfBoxProcessor.downscale_filter</code></li>
      <li><code>PdfBoxProcessor.sharpen</code></li>
      <li><code>metadata.*</code></li>
    </ul>
  </li>
  <li>Remove the following configuration keys:
    <ul>
      <li><code>Java2dProcessor.scale_mode</code></li>
      <li><code>KakaduProcessor.post_processor.*</code></li>
      <li><code>OpenJpegProcessor.post_processor.*</code></li>
      <li><code>PdfBoxProcessor.post_processor.*</code></li>
    </ul>
  </li>
</ol>

<h2>3.1.1 &rarr; 3.1.2</h2>

<p>Nothing to do.</p>

<h2>3.1 &rarr; 3.1.1</h2>

<ul>
  <li>Add the <code>http.host</code> and <code>https.host</code> keys from the sample configuration.</li>
</ul>

<h2>3.0.1 &rarr; 3.1</h2>

<ul>
  <li>Replace the <code>get_iiif2_service</code> delegate script method with <code>extra_iiif2_information_response_keys</code>.</li>
</ul>

<h2>3.0 &rarr; 3.0.1</h2>

<p>Nothing to do.</p>

<h2>2.2 &rarr; 3.0</h2>

<ol>
  <li>Add the following keys from the sample configuration:
    <ul>
      <li><code>admin.*</code></li>
      <li><code>delegate_script.enabled</code></li>
      <li><code>endpoint.iiif.2.restrict_to_sizes</code></li>
      <li><code>StreamProcessor.retrieval_strategy</code></li>
      <li><code>cache.source</code></li>
      <li><code>AmazonS3Cache.*</code></li>
      <li><code>AzureStorageCache.*</code></li>
      <li><code>redaction.enabled</code></li>
    </ul>
  </li>
  <li>Rename the following keys:
    <ul>
      <li><code>delegate_script</code> to <code>delegate_script.pathname</code></li>
      <li><code>cache.server</code> to <code>cache.derivative</code></li>
    </ul>
  </li>
  <li>Remove the following keys:
    <ul>
      <li><code>JdbcResolver.function.*</code></li>
    </ul>
  </li>
  <li>Add the following methods from the sample delegate script:
    <ul>
      <li><code>redactions</code></li>
      <li><code>Cantaloupe::JdbcResolver::get_database_identifier</code></li>
      <li><code>Cantaloupe::JdbcResolver::get_media_type</code></li>
      <li><code>Cantaloupe::JdbcResolver::get_lookup_sql</code></li>
    </ul>
  </li>
  <li>Rename the following delegate script methods:
    <ul>
      <li><code>Cantaloupe::get_pathname</code> to <code>Cantaloupe::FilesystemResolver::get_pathname</code></li>
      <li><code>Cantaloupe::get_url</code> to <code>Cantaloupe::HttpResolver::get_url</code></li>
      <li><code>Cantaloupe::get_azure_storage_blob_key</code> to <code>Cantaloupe::AzureStorageResolver::get_blob_key</code></li>
      <li><code>Cantaloupe::get_s3_object_key</code> to <code>Cantaloupe::AmazonS3Resolver::get_object_key</code></li>
    </ul>
  </li>
  <li>If you are using JdbcResolver, be aware that the <code>JdbcResolver.function.*</code> configuration keys are now obsolete, and these functions will have to be rewritten as delegate script methods.</li>
  <li>If you are using JdbcCache, modify your database schema:
    <pre>ALTER TABLE {JdbcCache.info_table} CHANGE COLUMN last_modified last_accessed;
ALTER TABLE {JdbcCache.derivative_image_table} CHANGE COLUMN last_modified last_accessed;</pre>
  </li>
  <li>Note that the information that used to be available on the landing page (<span class="filename">/</span>) has moved to the Control Panel (<span class="filename">/admin</span>). Log in with a username of "admin" and the password defined in the <code>admin.password</code> configuration option.</li>
</ol>