Skip to main content
Version: 8.2607.0.x LTS26

nevisProxy migration guide from LTS24 to LTS26

Before starting the migration process, review the following additions and changes, and consider if they have an impact on your use case.

You should first eliminate most deprecation notices in the logs of your existing setup. This will facilitate the transition to LTS26 and eventually to RR and subsequent LTS. A deprecation notice looks like this in the navajo log:

03:39:44.317 7.2511.1.2 <the related tracegroup> 03241.139830376855296.000ca9-17082275843162036-18dba4c613c 5-NOTICE:     DEPRECATED: <here you have more information>. The deprecated value will be removed in the next major release: 8.x

You can also set the bc property ch.nevis.ErrorOnDeprecated to true. In that case using deprecated configuration values will result in an error (error code CONF-0001) and the proxy will either not start or the filter or servlet using the deprecated value will not work and the request will be blocked.

In Appendix H (Deprecation List) you can get more information on what has been deprecated and how it has been replaced.

What’s new​

Here a list of the most important new features:

  • We did some major improvements for the Opentelemetry configuration
  • The Lua JWT handler now supports token verification using a JWK key.
  • The DeflateFilter and InflateFilter support now the most common compression algorithm (brotli, gzip, deflate)
  • We now support RFC 7512 conform PKCS11 URLs for Securoys.
  • We added the QosFilter.
  • We improved the LoadBalancerServlet
  • We added the Http2Servlet for gRPC support

What has changed​

Here a list of the most important changes. Read as well the release notes for more details:

  • The following unique key to the MariaDB based dynamic session management has to be added:
alter table attribute add constraint uc_id_name unique (ID, NAME);
Important
  • Before adding the unique key be sure that all instances using this database have been upgraded to the latest RR.
  • The command may fail if there are duplicated attributes. In that case you have to retry later. We recommended adding this key while there is low load.

  • For nevisproxy to run correctly, you need at least SP6 if running on SLES15.

  • The Apache config generation is changed when multiple hosts are defined in navajo.xml. Now the default hosts' virtual hosts are moved to the beginning. In the old config generation, the virtual hosts order was defined by the connectors' order.

  • The XmlFilter checks now the content against the configured XSD schema (if any). If the content doesn't match the schema, or a schema is missing, the request will be blocked. In order to switch back to the old behaviour you need to set the parameter ValidateSchema to false.

  • the handling of PKCS#11 cerificates and URLs has changed. Read the chapter Setup the Securosys HSM or CloudHSM for more information.

  • If you have a Securosys HSM or any other PKCS#11-based HSM configured, add SSLCryptoDevice="pkcs11" to the Service section of navajo.xml.

  • If you have a PKCS#11-based HSM configured, add OPENSSL_ENGINES=/opt/nevisproxy/lib/engines and export OPENSSL_ENGINES to your env.conf file.

  • Due to the upgrade of the OpenTelemetry Library the name of the deployment environment variable has changed from deployment.environment to deployment.environment.name and all metrics data coming from nevisProxy data is now sent as Histogram instead of UpDownCounter.

  • In NProxyOP and NavajoOP tracing we trace the number of received bytes by the frontend (bRF in NProxyOP, bF in NavajoOP). You might have to adapt any scripts which parses these log lines.

  • Due to the refactoring of the RewriteFilter those parameters behaves differently if a condition is set:

    • RequestURL
    • RequestURI
    • RequestHeader
    • ResponseHeader

    If a Condition is followed by several rules, wrap them with Pragma: block-begin / Pragma: block-end to preserve the previous behavior. Without this, only the first rule after the Condition fires conditionally; all subsequent rules always fire. See Conditional parameters and pragmas.

  • The SSLCertificateChainFile has been deprecated by Apache. Therefore nevisProxy will merge the file configured as SSLCACertificateFile with the file configured as SSLCertificateChainFile and store the result in a new file saved into the /var/opt/nevisproxy/<instance>/run directory. This file will be set as SSLCACertificateFile.

  • Due to the OpenSSL upgrade RSA keys are now required to be at least 2048 bits long and certain old ciphers might no longer be usable

  • Requests using a Kubernetes setup could now be blocked with the status code 421 ("Misdirected Request") if the ingress is not SNI aware. See also https://bz.apache.org/bugzilla/show_bug.cgi?id=69743. In that case you can weaken the protection via the new parameter SSLVHostSNIPolicy in navajo.xml. We recommend to do this only if your entrypoint itself is protected against CVE-2025-23048.

  • The CompressionWindowSize parameter of the DeflateFilter no longer accepts positive values.

  • The new LoadExternalEntity parameter of the SoapFilter defaults to false, which blocks external entity loading. If your setup relied on this, set LoadExternalEntity to true.

  • The QS_KeepAliveTimeout and QS_MaxKeepAliveRequests dynamic keep-alive settings have been removed from mod_qos. Use QS_KeepAliveEnd instead.

  • ResourceManager.NoSessionCookie.CookieSecure now defaults to true in the Http[s]ConnectorServlet and WebSocketServlet.

  • URLMode of the EncryptionFilter now defaults to hmacsha256.

  • SecureConnection of the IdentityCreationFilter now defaults to true, meaning the filter rejects non-HTTPS requests. Set it to false if the client is allowed to communicate over plain HTTP.

  • ResourceManager.DisablePing now defaults to true in the HttpConnectorServlet, disabling automatic backend liveness probing. Set it to false explicitly if you rely on the proxy detecting a down backend via pings.

  • The MaintenanceFilter no longer forwards frontend query parameters to the MaintenanceServlet.

What has been removed​

For this release, the nevisProxy software has been cleansed of software elements that were either deprecated, undocumented and/or not-used.

Note that the removed software elements are not only removed from the code, but you will not find them in the reference guide anymore. For more information about these elements, have a look at the reference guides of earlier nevisProxy releases.

The removed elements are:

  • REMOVED: We removed the deprecated ReadLineSize of the InputValidationFilter. (NEVISPROXY-7031)
  • REMOVED: We removed the undocumented Lua method session:renegotiateCookie(). (NEVISPROXY-7030)
  • REMOVED: We removed the deprecated values of the RenewIdentification parameter of IdentityCreationFilter. (NEVISPROXY-7029)
  • REMOVED: We removed the deprecated RemoteServlet parameter of the MultiLevelSessionStoreServlet. (NEVISPROXY-7028)
  • REMOVED: We removed the deprecated Lua method session:renegotiateSSL(). (NEVISPROXY-7027)
  • REMOVED: We removed the deprecated attributes and elements of the navajo_1_0.dtd file. (NEVISPROXY-7026)
  • REMOVED: We removed the deprecated values of the InterceptionRedirect parameter of the IdentityCreationFilter. (NEVISPROXY-7022)
  • REMOVED: We removed the deprecated parameters in the CacheFilter . (NEVISPROXY-7021)
  • REMOVED: We removed the undocumented wwwauthenticate value of RenderingProvider in the LoginRendererServlet. (NEVISPROXY-7017)
  • REMOVED: We removed the deprecated parameter AuditLog.Key from the InputValidationFilter. (NEVISPROXY-6966)
  • REMOVED: We removed the deprecated TelemetryFilter. (NEVISPROXY-6955)
  • REMOVED: We removed the deprecated InsertWrapperFilter. (NEVISPROXY-6682)
  • REMOVED: We removed the undocumented SIGPWR signal handling . (NEVISPROXY-6548)
  • REMOVED: We removed the deprecated Milestone features from the CSRFFilter. (NEVISPROXY-6508)
  • REMOVED: We removed the deprecated values of the AutoRewrite parameter from the HttpConnectorServlet. (NEVISPROXY-6227)
  • REMOVED: We removed the deprecated OutboundProxyAuthorization parameter of the HttpConnectorServlet. (NEVISPROXY-6217)
  • REMOVED: We removed the deprecated attribute DocumentRoot from navajo.xml. (NEVISPROXY-6068)
  • REMOVED: We removed the deprecated memory attributes from navajo.xml. (NEVISPROXY-5993)
  • REMOVED: We removed the deprecated DB Node Affinity from the MySQLSessionStoreServlet. (NEVISPROXY-5208)
  • REMOVED: We removed the system memory usage tracing. (NEVISPROXY-7209)
  • REMOVED: We removed the deprecated ContentType parameters of the EncryptionFilter. (NEVISPROXY-7023)
  • REMOVED: We removed the deprecated path attribute in the Context section of navajo.xml. (NEVISPROXY-6059)
  • REMOVED: We removed the support of Set-Cookie2 headers. (NEVISPROXY-6449)