MapServer upgrade from Debian 11 to Debian 12

Finally I decided to upgrade my home server from Debian 11 Bullseye to Debian 12 Bookworm; here you can read some notes about the upgrade: Aggiornamento da Debian 11 Bullseye a 12 Bookworm.

One change that deserves a dedicated page is the upgrade from MapServer 7.6.2 shipped with Debian 11 to MapServer 8.0.1 shipped with Debian 12; in fact it happened that almost all the MapServer based applications stopped working.

In version 8 it became mandatory to have a configuration file, the default location of which is /etc/mapserver.conf. See the syntax here: https://mapserver.org/mapfile/config.html. You must declare at least the MS_MAP_PATTERN path.

In the past I used to have some CGI-Mapserver services (as native MapServer or as WMS service) where the service URL contained the full path of the mapfile, something like this:

http://www.rigacci.org/cgi-bin/mapserv?map=/usr/local/lib/mapserver/mie-strade-wms.map&

It is not a good practice to accept from the internet a parameter that is the full path to a local file. MapServer 8 requires that you declare at least a pattern that the received mapfile must obey to (MS_MAP_PATTERN). Better than that, you can define several aliases (short names pointing to the mapfiles wherever they resied) and accept from the client only that aliases, disallowing the requests for a full path mapfile (MS_MAP_NO_PATH). I opted for the latter mode:

# MapServer 8.0 Config File
# https://mapserver.org/mapfile/config.html
CONFIG
  MAPS
    # Define the aliases for mapfile paths.
    MIE_STRADE_WMS "/usr/local/lib/mapserver/mie-strade-wms.map"
  END
  ENV
    # Disallow using full path for mapfiles (use aliases defined in CONFIG:MAPS instead).
    MS_MAP_NO_PATH "true"
    # Limit mapfile access when using full paths, this setting is never used 
    # if CONFIG:ENV:MS_MAP_NO_PATH is set.
    MS_MAP_PATTERN "^/usr/local/lib/mapserver"
  END
END

In this way the above URL will be changed into:

http://www.rigacci.org/cgi-bin/mapserv?map=MIE_STRADE_WMS&

In MapServer 8 mapfiles the TRANSPARENT identifier is not longer accepted inside the MAP object, you have to move it into the OUTPUTFORMAT object; something like this:

  OUTPUTFORMAT
    NAME agg_png
    DRIVER "AGG/PNG"
    MIMETYPE "image/png"
    IMAGEMODE RGBA
    EXTENSION "png"
    TRANSPARENT ON
  END

One of the biggest problem of the upgrade is the change of the name of some CGI parameters; notably the map_size option is not longer supported.

I had web application based on OpenLayers 2.11, which included a MapServer bitmap layer. The JavaScript code automatically generates the request URL, something like this (parameters are split on different lines for readability):

/cgi-bin/mapserv?map=/usr/local/lib/mapserver/mie_strade.map
    &format=image%2Fpng
    &mode=map
    &map_imagetype=png
    &mapext=1235758.1079621+5432310.5814201+1242666.1043925+5443174.1940635
    &imgext=1235758.1079621+5432310.5814201+1242666.1043925+5443174.1940635
    &map_size=1446+2274
    &imgx=723
    &imgy=1137
    &imgxy=1446+2274

Unfortunately the map_size option is not longer accepted and the resulting PNG image has the default size declared into the MAP:SIZE object of the mapfile, instead of the requested 1446×2274 pixels. This causes a totally distorted map image into the web application!

This problem cannot be easily fixed, because the URL options are hard-coded into the OpenLayers code. So I had to replace all the OpenLayers 2.x code with the current OpenLayers 8.x, which required a total refactory of the code.