Server

Hotfixes Installation Notes

Updated: March 18, 2024

The purpose of this page is to describe the additional actions that need to be done when installing the hotfixes on Nuxeo Platform and that cannot be done automatically. The page provides an exhaustive list of manipulations for the installation of Nuxeo Platform LTS 2021 hotfixes, but you need only to apply those relevant for your own instance.

When you are installing/configuring a new Nuxeo instance, the very first thing to do is to install the hotfixes. Because it will provide fixes on the Nuxeo launcher, on the startup wizard and on the templates, installing them immediately will prevent from encountering known issues.

How to Keep Your Instance up-to-Date

Hotfixes always have dependencies on the previous hotfix. So if you need to install several hotfixes, you can download only the latest one: when you install it, it will trigger the installation of the previous hotfixes.

Installing Hotfixes from the Command Line

The Nuxeo Platform provides a command to automatically install all the available hotfixes. From the command line, run the following command:

  • For Linux and Mac OS users:

    $ ./nuxeoctl mp-hotfix --accept=true
    
  • For Windows users:

    > nuxeoctl.bat mp-hotfix --accept=true
    

The parameter --accept=true automatically replies yes to any prompt, which makes the hotfix installation smoother.

While installing hotfixes, you will see the following message, but you can ignore it and continue.

Use of the <copy /> command on JAR files is not recommended, prefer using <update /> command to ensure a safe rollback. (nuxeo-launcher-8.10-HF01-jar-with-dependencies.jar)

Installing Hotfixes from the Update Center

You can also download and install hotfixes from the Update Center in the Admin tab.The installation of hotfixes requires the server to be restarted to complete the installation: follow the manual installation and configuration steps required by the installed hotfixes before you restart your server.

While installing hotfixes, you will see the following message, but you can ignore it and continue.

Use of the <copy /> command on JAR files is not recommended, prefer using <update /> command to ensure a safe rollback. (nuxeo-launcher-9.10-HF01-jar-with-dependencies.jar)

Since LTS 2021, the addon "Nuxeo JSF UI" is handled outside the main Nuxeo repository on GitHub. As a consequence, the related fixes for JSF UI will not be embedded in a hotfix.
Therefore if the addon "Nuxeo JSF UI" is installed on your instance, you must upgrade this package after installing a hotfix by running the following command:

> nuxeoctl mp-upgrade

Note that this command will upgrade the versions of any package.

Instance Registration

Hotfixes released for LTS 2021 can only be used on valid, registered Nuxeo instances.

Why?
If you are using an unregistered LTS 2021 Nuxeo instance with hotfixes installed, you may encounter the following behavior:

  • A warning will be displayed in the logs during startup,
ERROR [RuntimeService] NUXEO INSTANCE NOT REGISTERED

***** This Nuxeo instance is not registered *****
It can only be used for development and will be stopped if used in production
  • Over a certain level of use the server will be stopped automatically. When this happens, a message is displayed in the logs to inform you as well.
ERROR [RuntimeService] NUXEO INSTANCE STOPPING

***** This Nuxeo instance is not registered *****
Stopping Nuxeo instance due to threshold exceeded (TOTAL_COMMITS > 100000) after failed registration checks

The current limits of use are:

  • 100,000 transaction commits
  • 10 concurrent sessions (a session correspond to an access to the core)

If the expiration date is close (less than 15 days), a warning will be displayed and indicate how many days are left before expiration. In the JSF UI, a message based on the Administrative message mechanism will be displayed: all users will be informed.

After expiration date, the following message will be displayed in the logs at startup:

ERROR [RuntimeService] NUXEO INSTANCE REGISTRATION EXPIRED

***** This Nuxeo instance registration is expired *****
It can only be used for development and will be stopped if used in production

The following message will be displayed in the logs when Nuxeo will be stopped automatically according to the same conditions as described earlier:

ERROR [RuntimeService] NUXEO INSTANCE STOPPING

***** This Nuxeo instance registration is expired *****
Stopping Nuxeo instance due to threshold exceeded (TOTAL_COMMITS > 100000) after registration expiration

How Can I Avoid This?

Make sure to register your Nuxeo instance: this can be done both for online and offline instances.

Could it Break My CI Chain? Do I Need to Register My Test Instances?

The level of use needed to stop an unregistered instance with hotfixes has been tuned to prevent any problems with CI chain tests. It would be possible to run the full test suite of Nuxeo server (both unit tests AND integration tests) several times before anything would happen.

Nevertheless, it is recommended to register your test instances, especially if you wish to test features that require heavy usage (e.g. load testing or mass import).

How Often Do I Need to Register My Instance?

Registration tokens are valid until your current contract's expiration date. When renewing your Nuxeo Online Services subscription, you should register your instances again.

I Have More Questions, Who Can I Ask For Help?

If you have any questions, feel free to contact our support team via a dedicated support ticket.

Hotfix 50

Throw an Error if a String Is Used to Query a Long/Integer Field

Added the nuxeo.primitive.type.strict.validation Framework property.

By default it is set to false, keeping the previous behavior: at low level, when trying to decode a string input as a number, fall back on 0 if the string cannot be decoded as a number, e.g. foo.

If set to true, in such case, a NumberFormatException is thrown.

Consequently, when executing a REST API search request on a PageProvider and passing foo as a query parameter for a predicate on an integer field, the server will respond with a 400 Bad Request status code, e.g.:

curl -u ******:******r -X GET http://localhost:8080/nuxeo/api/v1/search/pp/test_primitive_type_predicates/execute?integerField=foo | jq
{
  entity-type: exception,
  status: 400,
  message: java.lang.NumberFormatException: For input string: "foo"
}

 More on JIRA ticket NXP-32214

Hotfix 49

Add Support for ZIP Generated With 7-Zip and Including Files Whose Name Contains Special Characters

A fallback charset can be configured. This is being documented in nxdoc/preview. But here is the TL;DR:

<?xml version=1.0?>
<component name=org.nuxeo.ecm.zip.file.reader.fallback.config>
  <extension target=org.nuxeo.runtime.ConfigurationService point=configuration>
    <property name=org.nuxeo.ecm.zip.file.reader.charset.fallback>cp850</property>
  </extension>
</component>

 More on JIRA ticket NXP-32042

Hotfix 48

Set Snappy-Java Version to 1.1.10.5

The following dependency has been upgraded from 1.1.8.1 to 1.1.10.5:

<dependency>
  <groupId>org.xerial.snappy</groupId>
  <artifactId>snappy-java</artifactId>
</dependency>

 More on JIRA ticket NXP-32196

Hotfix 47

Upgrade or Remove Htmlunit From Nuxeo-Runtime-Test to Avoid Vulnerability

Removed the following Maven dependencies from nuxeo-runtime-test:

<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-api</artifactId>
</dependency>
<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-support</artifactId>
</dependency>
<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-firefox-driver</artifactId>
</dependency>
<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-ie-driver</artifactId>
</dependency>
<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-chrome-driver</artifactId>
</dependency>
<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>htmlunit-driver</artifactId>
</dependency>

Added the following Maven dependencies to nuxeo-features-test:

<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-firefox-driver</artifactId>
</dependency>
<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-ie-driver</artifactId>
</dependency>
<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-chrome-driver</artifactId>
</dependency>
<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>htmlunit-driver</artifactId>
</dependency>
<dependency>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-core</artifactId>
  <scope>compile</scope>
</dependency>

Moved the following classes from nuxeo-runtime-test to nuxeo-features-test:

Attachment.java
Browser.java
BrowserFamily.java
ConcordionFixture.java
Configuration.java
DriverFactory.java
HomePage.java
SkipBrowser.java
TakesAttachment.java
WebDriverFeature.java
WebPage.java
ExpectedCondition.java
TimeoutException.java
Wait.java
WebDriverWait.java
MyHomePage.java
SearchResultPage.java
WebTest.java

The related package names haven't changed:

org.nuxeo.runtime.test.runner.web
org.openqa.selenium.support.ui

If you are explicitly depending on one of these classes, you need to replace the Maven dependency:

<dependency>
  <groupId>org.nuxeo.runtime</groupId>
  <artifactId>nuxeo-runtime-test</artifactId>
  <scope>test</scope>
</dependency>

by:

<dependency>
  <groupId>org.nuxeo.ecm.platform</groupId>
  <artifactId>nuxeo-features-test</artifactId>
  <scope>test</scope>
</dependency>

 More on JIRA ticket NXP-32144

Fix Results Selection Actions Made From Multi-Repository Search Results

Added:

  • nuxeo.bulk.download.multi.repositories Framework property
  • AbsoluteDocumentRef
  • TypeAdapterHelper#createDocumentModel(AbsoluteDocumentRef docRef)
  • DocumentInputResolver#BULK_DOWNLOAD_MULTI_REPOSITORIES
  • TestDocumentInputResolvers
  • MultiRepositoryDummyOperation

 More on JIRA ticket NXP-31487

Hotfix 46

Upgrade Quartz to 2.4.0-rc2

The org.quartz-scheduler:quartz library was upgraded to 2.4.0-rc2.

 More on JIRA ticket NXP-32138

Upgrade LibreOffice in Docker Image

LibreOffice was upgraded to 7.5.8 in the Docker image

 More on JIRA ticket NXP-32137

Hotfix 45

Orphan Version Full GC Is Not Working With orphanVersionRemovalFilter Contributions

On 2023 the contribution org.nuxeo.ecm.core.event.orphanVersionRemoval.listener has been removed.

 More on JIRA ticket NXP-32073

Hotfix 41

Add Flexible Record Core API

When using the Retention package with a MongoDB backend, it is recommended to create new indexes manually, otherwise, the Nuxeo server will attempt to create them at start-up. In the case of an existing instance with large amounts of documents, this process may time out and/or affect performance.

db.default.createIndex({ ecm:isRecord: 1}, {sparse: true});
db.default.createIndex({ ecm:isFlexibleRecord: 1}, {sparse: true});

 More on JIRA ticket NXP-31968

Rename Compliance Mode as Strict Mode

The nuxeo.conf property nuxeo.retention.compliance.enabled has been deprecated in favor of nuxeo.retention.strictmode.enabled. When both properties are configured, nuxeo.retention.strictmode.enabled takes precedence.

 More on JIRA ticket NXP-31878

Hotfix 37

Add an Option to Disable Hostname Verification During Elastic/Opensearch SSL Handshake

You can now use elasticsearch.restClient.ssl.certificate.verification=false to disable hostname verification during SSL handshake for accessing a testing instance of OpenSearch or Elasticsearch running with a test certificate.

 More on JIRA ticket NXP-31837

GetAllDocumentBlobs (Document.GetBlobs) Returns Thumbnails

A new nuxeo.document.blob.extractor.legacy nuxeo.conf boolean property has been introduced to switch back to the behavior before NXP-31539 which made sure both static (defined by the document type) and dynamic (added by dynamic facets) blob properties were listed.

If true, only blob properties referenced by static schemas (attached to the doc type of a document) will be listed. The default value is false.

This property is available for convenience for 10.10 and 2021 only. The fix done in NXP-31539 is the expected behavior and it will be up to external projects to implement their own operation listing static blob properties for 2023.

 More on JIRA ticket NXP-31834

Hotfix 36

Backport H2 Version 2.x Upgrade to LTS 2021

H2 is upgraded to latest 2.x version

The H2 2.x upgrade comes with several breaking changes from H2 itself.

In case of upgrade, you have to delete the nxserver/data/h2 folder before starting Nuxeo. WARNING: In development environments you will lose data.

 More on JIRA ticket NXP-31785

Add an nuxeo.conf Property to Disable Immediate Blob Garbage Collection

To disable the Immediate Document's blobs Garbage Collection, set the following nuxeo.conf property to false:

nuxeo.bulk.action.blobGC.enabled=false

 More on JIRA ticket NXP-31794

Prevent Base64-Encoded Images From Being Sent to Elasticsearch

When using an HTML Note document, only the fulltext (extracted text) is submitted to elastic for indexation.

 More on JIRA ticket NXP-31698

Hotfix 35

PubSub Usage Must Be Monitored

There is now a metric to count the number of messages published using the PubSub service.

 More on JIRA ticket NXP-29386

Hotfix 34

Make Kafka Replication Factor Param Optional

Nuxeo is now relying on the default Kafka broker topic replication factor when creating a new topic. This is configured with kafka.default.replication.factor=-1. Note that it works only with Kafka cluster >= 2.4, if you want to use an older Kafka cluster, you have to set explicitly the replication factor in Nuxeo to something > 0.

 More on JIRA ticket NXP-31621

Hotfix 32

Fix Removal of ‘aceinfo’ Directory Entries When a Document Is Deleted

For existing instances on MongoDB, in order to improve performance on ace info removal the following index needs to be created manually:

db.aceinfo.createIndex({aceinfo:docId: 1})  

Then enable ace info garbage collection by adding the following line to your nuxeo.conf:

nuxeo.aceinfo.gc.enabled=true 

VCS users will need to make their own index.

 More on JIRA ticket NXP-31459

Hotfix 31

Reduce Retries on Recompute Bulk Actions

The maximum number of retries can now be configured for recompute bulk actions using the nuxeo.conf options below. The new default option is one retry (previously 3):

nuxeo.bulk.action.recomputeThumbnails.maxRetries=1
nuxeo.bulk.action.recomputeViews.maxRetries=1
nuxeo.bulk.action.recomputeVideoConversions.maxRetries=1

 More on JIRA ticket NXP-31550

Add Mongodb Index on ecm:Isversion

For MongoDB backend, create the index manually:

db.default.createIndex(
   { ecm:isVersion: 1 }
);

Otherwise, the nuxeo server will attempt to create this index if not present at start-up. In the case of an existing instance with large amounts of documents, this process may time out and/or affect performance.

 More on JIRA ticket NXP-31530

Hotfix 30

Make certificateKeyAlias Value Configurable From nuxeo.conf

A new nuxeo.conf property is available to configure the alias name for the certificate used in the HTTPS configuration: nuxeo.server.https.keyAlias.

 More on JIRA ticket NXP-31425

Create a MongoTransientStore That Can Handle Large Number Params

To use a MongoDB optimized implementation of the transientstore, (that is replacing the KeyValueTransientStore implementation), the following property must be seen on nuxeo.conf for 10.10 and LTS 2021:

nuxeo.transientstore.provider=mongodb

Note that on LTS 2023 this implementation is used by default.

 More on JIRA ticket NXP-31311

Hotfix 25

Avoid Transaction Timeout During Emails Check

To avoid transaction timeout there is a new limit in the number of mail that can be fetched per mailbox, the default limit is 2000 mails, this can be configured with nuxeo.conf option:

org.nuxeo.mail.message.limit=2000

Note that there is a warning in the log when the limit is reached.

 More on JIRA ticket NXP-31163

Unable to Detect Mimetype When Uploading Multipart Form Data

multipart/form-data upload is not supported and will be rejected. (400 Bad Request)

 More on JIRA ticket NXP-31123

Hotfix 23

Upgrade Various Dependencies to Fix CVE

Upgrade to netty 4.1.78.Final and jackson-databind 2.9.10.8 to fix CVE.

 More on JIRA ticket NXP-30979

Hotfix 22

Route Long Indexing Command to the Bulk Service Keeping WM Indexing Near Realtime

Use elasticsearch.index.recursive.bulkService=true in nuxeo.conf to activate the routing of long indexing command to the bulk service. In cluster mode, It is recommended to use the option when the bulk service is distributed (i.e. Kafka is enabled).

 More on JIRA ticket NXP-30805

Hotfix 21

Tune the CMIS Query During Login to Get Platform Information

The latestChangeLogToken returned by the CMIS endpoint is now searched on events of the past 2 weeks for performance reason. This limit can be tuned if needed using the following nuxeo.conf option:

# Improve performance on getLatestLogId limiting events to the past 2 weeks, using elastic date syntax
audit.elasticsearch.latestLogId.afterDate=now-14d/d

 More on JIRA ticket NXP-31016

Have a Way to Trace Full-text Search Performed on Repository

It is now possible to detect if repository full-text search is used by configuring log4j2 to activate the following logger:

  <Logger name=org.nuxeo.ecm.core.storage.mongodb.MongoDBRepositoryQueryBuilder level=debug />

 More on JIRA ticket NXP-31003

Hotfix 19

Use Elastic word_delimiter_graph instead of word_delimiter to Avoid Indexing Error

If you encounter indexing errors because of negative startOffset, your mapping needs to be updated.

If you have overridden the Elastic mapping then follow the recommended changes in the ticket. Then you need to reindex the repository, visit the related documentation for more information.

 More on JIRA ticket NXP-30785

Hotfix 17

Add property to set max_expansion on match_phrase_prefix operator

Max expansions can be configured through the Configuration service with a contribution like

    <extension target=org.nuxeo.runtime.ConfigurationService point=configuration>
        <property name=elasticsearch.max_expansions>200</property>
    </extension>

 More on JIRA ticket NXP-30878

Improve KV TransientStore GC Resiliency

Transient GC was not working in environments with segregated front and worker nodes. As the result, transient stores in s3 might have accumulated lots of data and the current transient GC implementation might not be able to clean them efficiently. In this case, it is recommended to purge manually all objects older than 3 days on transient stores before applying this hotfix.

This can be done using scripts or by creating an Object Lifecycle Management rule with a correct prefix /transient_*/.

 More on JIRA ticket NXP-30851

Allow Automation Contributions to be Disabled

When replacing an Automation operation, chain or script, its old aliases are lost. If you contribute to an operation and want to call it by an alias, you need to copy that alias on the new operation contribution or to use the ID of the operation rather than an alias.

OperationType (Please note you can't cross contribute to an OperationType implementation, a chain operation can't disable a scripted operation for example)

ChainOperationType:

<component name="org.nuxeo.ecm.automation.test-chain-operation" version="1.0">
  <extension target="org.nuxeo.ecm.core.operation.OperationServiceComponent" point="chains">
    <chain id="testScript" enabled="false" />
  </extension>
</component>

ScriptingOperationType:

<component name="org.nuxeo.ecm.automation.test-scripted-operation-disable" version="1.0">
  <require>org.nuxeo.ecm.automation.test-scripted-operation</require>
  <extension target="org.nuxeo.automation.scripting.internals.AutomationScriptingComponent" point="operation">
    <scriptedOperation id="testScript" enabled="false"/>
  </extension>
</component>

 More on JIRA ticket NXP-30761

Hotfix 15

Use partialFilterExpression on parentId When Creating the Unique Index to Avoid Duplicates

You MUST run the command below in a MongoDB Shell (assuming you're connected to the nuxeo database and your repository is default):

db.default.dropIndex("ecm:parentId_1_ecm:name_1");

As a workaround, you can configure the nuxeo.db.indexes.create property to false in nuxeo.conf.

 More on JIRA ticket NXP-30638

setUserAgentPrefix in S3 Config

The following nuxeo.conf properties have been added:

  • nuxeo.s3storage.user.agent.prefix, empty string by default
  • nuxeo.s3storage.user.agent.suffix, empty string by default

 More on JIRA ticket NXP-30797

Hotfix 13

Remove the Assignment to the ZIP Extra Field to Produce Correct ZIP

You can now disable the extra field setting when doing Nuxeo IO export by contributing the following:

  <extension target=org.nuxeo.runtime.ConfigurationService point=configuration>
    <property name=nuxeo.core.io.archive.extra.files.count>false</property>
  </extension>

This could be interesting if you want to open the produced archive with external tools such as Archive Utility.app.

This property has true as default as disabling this behavior may impact performance when re-importing to Nuxeo the archive.

 More on JIRA ticket NXP-30713

Bulk SetPropertiesAction - VersioningOption Parameter Does Not Take Effect When Versioning Service Is Extended via XML Extension

As documented in the automatic versioning system, the versioning policy order should be higher than 10, order lower than 10 is reserved for internal purposes. This restriction is now enforced on LTS 2021, a server having a versioning policy contribution that doesn't respect this rule will NOT start. On LTS 2019, an ERROR message will be logged during Nuxeo startup.

In addition to disable the automatic versioning system for setProperties action, we also have disabled the system for the following system related updates:

  • add/remove a document to/from a collection
  • recompute pictureViews
  • add/remove notifications subscriptions
  • add/remove tags
  • update quotas
  • recompute thumbnails
  • recompute transcodedVideos
  • recompute videoInfos

In a more general way, the system has been disabled in the code paths where auto checkout was disabled. This can impact positively performance by avoiding version creation on the above low-level updates.

 More on JIRA ticket NXP-30700

Hotfix 11

S3 Transfer Parameters Configurable

All the S3 multipart upload and copy parameters are configurable through nuxeo.conf.

The nuxeo.s3.multipart.copy.part.size ConfigurationService property, formerly contributed in configuration-properties.xml, is deprecated since 2021.11/10.10-HF54.

The new nuxeo.s3storage.multipart.copy.part.size nuxeo.conf property should be used instead, default value hasn't changed: 5242880 (5 MB).

If you have contributed a custom nuxeo.s3.multipart.copy.part.size ConfigurationService property with an XML component such as:

  <extension target="org.nuxeo.runtime.ConfigurationService" point="configuration">
    <property name="nuxeo.s3.multipart.copy.part.size">xxxx</property>
  </extension>

you need to remove it and replace it by nuxeo.s3storage.multipart.copy.part.size=xxxx in nuxeo.conf. Though, backward compatibility is kept.

The following nuxeo.conf properties have been added:

  • nuxeo.s3storage.multipart.copy.threshold, default value: 5368709120 (5 GB)
  • nuxeo.s3storage.multipart.upload.threshold, default value: 16777216 (16 MB)
  • nuxeo.s3storage.minimum.upload.part.size, default value: 5242880 (5 MB)

 More on JIRA ticket NXP-30595

Deletion BAF Action Now Runs With SYSTEM_USERNAME

org.nuxeo.ecm.core.storage.dbs.DBSSession#remove launches the DeletionAction BAF action to perform the db deletion of descendants of a folderish document being removed.

The problem is that we pass the current session's principal to run the action which will just skip the deletion of the document on which the current user does not have READ permission granted.

To fix that, we now run the DeletionAction as SYSTEM_USER.

 More on JIRA ticket NXP-30661

Upgrade to Apache PDFBox 2.0.24

The upgrade of Apache PDFBox from 1.8.16 to 2.0.24 introduces breaking changes to the library, code relying on it must be updated.

 More on JIRA tickets NXP-28825 and NXP-30662

Hotfix 10

Nuxeo Workflow Now Supports 2 Parallel Tasks Completed at the Same Time by 2 Different Users

A warning is logged when assigning an unauthorized workflow global variable instead of throwing an exception.

Assigning an unauthorized workflow global variable won't throw an exception anymore but log a warning. The assignment is ignored.

 More on JIRA ticket NXP-30589

Web UI - nuxeo-document-preview Should Not Load nuxeo-pdf-viewer For Unsupported MIME Types Since 2021.10

Web UI does not display anymore a preview for unsupported MIME types.

PDF rendition is no longer listed in available renditions when no converter is found for a document's main blob given MIME type.

 More on JIRA ticket NXP-30643