Upgrading existing versions

Warning

Be aware that some upgrades are not reversible, meaning that the data directory may be changed so that it is no longer compatible with older versions of GeoServer. See Migrating a data directory between versions for more details.

The general GeoServer upgrade process is as follows:

  1. Back up the current data directory. This can involve simply copying the directory to an additional place.

  2. Make sure that the current data directory is external to the application (not located inside the application file structure).

    Check the GeoServer Server status page to double check the data directory location.

  3. Make a note of any extensions you have installed.

    • The GeoServer About ‣ Server Status page provides a Modules tab listing the modules installed.

    • Some extensions include more than one module, as an example the WPS extension is listed as gs-wps-core and gs-web-wps.

  4. Uninstall the old version and install the new version.

    • Download maintenance release to update existing installation

    • Download stable release when ready to upgrade

  5. Be sure to download and install each extension used by your prior installation.

  6. Make sure that the new installation continues to point to the same data directory used by the previous version.

Notes on upgrading specific versions

REST API URL Checks (GeoServer 2.26 and newer)

URLChecks are now available for REST API upload.

Use the existing URL Checks page to add any locations or directories for use.

GRIB Layers (GeoServer 2.26 and newer)

GeoServer 2.26 upgraded underlying Unidata NetCDF libraries, from 4.x to 5.x, which includes internal changes to how GRIB files are intepreted (mapping tables and GRIB parameters interpretation changes). The results in the underlying library to give some variables a different name, as well as interpreting the temporal variables differently (e.g., from period to instant, and changing the number of available times as a consequence).

Due to the above compatibility issues, some layers based on underlying GRIB datasets may stop working properly after the upgrade. If that is the case, the recommended action is to do a backup before doing the upgrade and then reconfigure the layers.

Backup

  1. Backup the GeoServer Datadir

  2. Backup eventual DB tables being used as catalog for the GRIB Datasets (That could be needed if ImageMosaic of GRIB have been configured, storing the mosaic index on DB)

  3. Backup the index file automatically generated by GRIB/NetCDF library for the involved GRIB files (i.e. *.gbx9, *.ncx3; *.ncx4)

Basic cleanup

  1. Remove any auxiliary/cache file associated with the underlying GRIB file (assuming the file is named gribfile.grib2):

    • gribfile.ncx3

    • gribfile.ncx4

    • gribfile.gbx9

    • .gribfile_hash folder (if not previously deleted) either located beside the original file, or within the configured NETCDF_DATA_DIR (if defined).

    • The screenshot below, represents an actual example of a tpcprblty.2019100912.incremental.grib2 file with related auxiliary/cache files

    ../_images/grib_auxiliary_files.png

Additional steps needed in case of ImageMosaic of GRIBs

  1. Remove any automatically created ImageMosaic configuration file within the ImageMosaic root folder. Assuming the underlying ImageMosaic was named mosaicM, containing coverages related to VariableA, VariableB, VariableC, …:

    • VariableA.properties, VariableB.properties, VariableC.properties, …

    • VariableAsample_image.dat, VariableBsample_image.dat, VariableCsample_image.dat, …

    • mosaicM.xml

  2. If using a datastore.properties connecting to an actual DB, cleanup the tables from the DB

    • Assuming that all the grib files belonging to the same ImageMosaic are affected by the same issue, you can delete the related tables and allow the imageMosaic reconfiguration to recreate them.

    • Based on the above example, the naming convention is that granules for VariableA are stored on table named VariableA and so on.

  3. Recreate the indexer.xml and _auxiliary.xml file as reported in the NetCDF documentation . (At the end, GRIB file are served through the NetCDF libraries)

Configuration cleanup

The GeoServer configuration refers to the “native name” of the variables, as reported by the underlying libraries, which might have changed during the upgrade.

If you are lucky, the following might help you to reconfigure the layers:

  1. Open the coverage.xml file of the affected layer and check the nativeName and nativeCoverageName` attributes, to the new variable name (you can pick it up from tools like ToolsUI or Panoply).

  2. Reload the GeoServer configuration, either by restarting the GeoServer service or by using the GeoServer Admin UI.

  3. Check if the layer is now working.

If the above did not help, then a full cleanup of the GeoServer configuration is needed:

  1. Remove the affected store, either Mosaic or GRIB Store, referring to the problematic GRIB files.

    • Follow up standard procedure to delete affected stores and underlying layer

    • Alternatively, consider using REST APIs to do that by referring to the DELETE method for /workspaces/{workspace}/coveragestores/{store} . Use ?recurse=true&purge=metadata to delete layers and auxiliary files as well

  2. Recreate the stores and layers using the known procedures.

Disk Quota validation query (GeoServer 2.25.4 and newer)

When using the JDBC Disk Quota:

  • Validation query for H2 is limited to SELECT 1.

  • Validation query for Oracle is limited to SELECT 1 FROM DUAL.

  • Validation query for other JDBC formats receive a warning in the logs if is not one of the common examples above.

Note

If you find your JDBC Disk Quota is no longer loaded on startup: check the logs for message about validation query, edit the configuration, and restart.

External Entity Allow List default (GeoServer 2.25 and newer)

The external entity allow list has changed to the following default locations:

  • www.w3.org

  • schemas.opengis.net

  • www.opengis.net

  • inspire.ec.europa.eu/schemas

  • proxy base url if configured

The external entity allow list is an important setting from a security standpoint. This update changes its use from a recommended best practice to a default covering the most common locations used for OGC web services.

Note

In general only application schema extension users need to update this setting.

Note

To restore the previous behavour use system property ENTITY_RESOLUTION_ALLOWLIST=* to allow external entity resolution from any http or https location.

For more information, including how to add additional allowed locations see External Entities Resolution.

FreeMarker Template HTML Auto-escaping (GeoServer 2.25 and newer)

As of GeoServer 2.25, the FreeMarker library’s HTML auto-escaping feature will be enabled by default to prevent cross-site scripting (XSS) vulnerabilities in WMS GetFeatureInfo HTML output when using the default FreeMarker templates and WMS service settings. Some users may experience incorrectly escaped HTML output when using custom templates or if HTML tags are stored in vector data stores.

See the FreeMarker Template Auto-escaping page for information about the limitations of this feature and for instructions to disable this feature and delegate to the WMS service setting which defaults to disabling HTML auto-escaping.

Spring Security Strict HTTP Firewall (GeoServer 2.25 and newer)

As of GeoServer 2.25, Spring Security’s StrictHttpFirewall will be enabled by default which will provide stronger default protection, particularly against potential path traversal vulnerabilities.

In some cases valid requests may be blocked if the names of GeoServer resources (e.g., workspaces) contain certain special characters and are included in URL paths. See the Spring Security Firewall page for instructions to disable the strict firewall and revert to the DefaultHttpFirewall used by earlier versions.

WCS ArcGRID output format removal (GeoServer 2.24 and newer)

The ArcGRID output format for WCS has been removed in GeoServer 2.24.0. If you have been using this format, you will need to switch to another text based format, such as GML coverage, or can get back the ArcGRID format by installing the WCS GDAL community module and use a configuration like the following (please adapt to your system):

<ToolConfiguration>
  <executable>gdal_translate</executable>
  <environment>
    <variable name="GDAL_DATA" value="/usr/local/share/gdal" />
  </environment>
  <formats>
    <Format>
      <toolFormat>AAIGrid</toolFormat>
      <geoserverFormat>ArcGrid</geoserverFormat>
      <fileExtension>.asc</fileExtension>
      <singleFile>true</singleFile>
      <mimeType>application/arcgrid</mimeType>
    </Format>
  </formats>
</ToolConfiguration>

Disk Quota HSQL DB usage (GeoServer 2.24 and newer)

As of GeoServer 2.24, H2 DB support will be replaced with HSQL DB for Tile Caching / Disk Quota store.

  • H2 option under “Disk quota store type” and “Target database type” is replaced with HSQL.

  • The default store type will be in-process HSQL.

  • Existing installations with in-process H2 selection will automatically be migrated to in-process HSQL. Old H2 database files will remain in gwc/diskquota_page_store_h2/ under the data directory. You may delete those or leave them for a possible downgrade.

  • Important: Existing installations with external H2 database selection will not be migrated automatically. You will get an error message at startup and disk quota will be disabled, unless you use a plugin/extension with H2 dependency. But other features of GeoServer will keep working. You can go to Disk Quota page and configure an external HSQL database or switch to in-process HSQL. In case you want to keep using H2 as an in-process/external database, you can add H2 store plugin or any other extension or plugin that has H2 dependency.

  • GeoServer installations with extensions/plugins having H2 dependency will still have H2 option under “Disk quota store type” and “Target database type”.

Remote requests control (GeoServer 2.24 and newer)

As of GeoServer 2.24, remote requests control has been added, and enabled by default, in GeoServer. This feature allows administrators to control which remote requests are allowed to be made to GeoServer. By default, no authorizations are included, thus GeoServer will deny remote requests originating from user interaction. In particular, the following use cases are affected:

  • WMS operations with remotely fetch styles (sld parameter) and style referencing remote icons (in general, icons outside of the data directory). As a reminder, when a remote icon is not found, GeoServer will fall back to a default icon, a gray square with a black border.

  • WMS “feature portrayal” with dynamic remote WFS references provided in the request (REMOTE_OWS_TYPE and REMOTE_OWS_URL parameters).

  • WPS remote inputs via either GET or POST request (e.g., remote GeoJSON file source).

The list of locations that are safe to contact can be configured using the URL Checks page.

Log4J Upgrade (GeoServer 2.21 and newer)

As of GeoServer 2.21, the logging system used by GeoServer has been upgraded from Log4J 1.2 to Log4J 2.

  • GeoServer now uses xml files for the built-in logging profiles (previously properties files were used).

  • The built-in logging profiles are upgraded with xml files:

    DEFAULT_LOGGING.xml
DEFAULT_LOGGING.properties.bak

  • A backup of the prior properties files are created during the upgrade process. If you had previously made any customizations to a built-in profiles these backup files may be used as a reference when customizing the xml file.

  • Log4J 2 does have the ability to read Log4j 1.2 properties files although not all features are supported.

    Any custom properties files you created will continue to be available for use.

  • If necessary you can recover a customization you performed to a built-in logging profile by restoring to a different filename. To recover a customization from PRODUCTION_LOGGING.properties.bak rename the file to PRODUCTION_LOGGING.properties.bak to CUSTOM_LOGGING.properties.

  • If you never plan to customize the built-in logging profiles the UPDATE_BUILT_IN_LOGGING_PROFILES=true system property will always ensure you have our latest recommendation.

JTS Type Bindings (GeoServer 2.14 and newer)

As of GeoServer 2.14, the output produced by REST featuretype and structured coverage requests using a different package name (org.locationtech instead of com.vividsolutions) for geometry type bindings, due to the upgrade to JTS (Java Topology Suite) 1.16.0. For example:

Before:

...
<attribute>
  <name>geom</name>
  <minOccurs>0</minOccurs>
  <maxOccurs>1</maxOccurs>
  <nillable>true</nillable>
  <binding>com.vividsolutions.jts.geom.Point</binding>
</attribute>
...

After:

...
<attribute>
  <name>geom</name>
  <minOccurs>0</minOccurs>
  <maxOccurs>1</maxOccurs>
  <nillable>true</nillable>
  <binding>org.locationtech.jts.geom.Point</binding>
</attribute>
...

Any REST clients which rely on this binding information should be updated to support the new names.

GeoJSON encoding (GeoServer 2.6 and newer)

As of GeoServer 2.6, the GeoJSON produced by the WFS service no longer uses a non-standard encoding for the CRS. To re-enable this behavior for compatibility purposes, set GEOSERVER_GEOJSON_LEGACY_CRS=true as a system property, context parameter, or environment variable.

Previous: Docker Container
Next: Getting started