Skip to main content
Version: 7.2405.x.x LTS

nevisProxy migration guide from LTS-2021 to LTS-2024

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 LTS2024 and eventually to RR and subsequent LTS. A deprecation notice looks like this in the navajo log:

03:39:44.317 4.6.13.0 <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: 5.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:

  • The BackendConnectorServlet is production ready and can now be used instead of the Http[s]ConnectorServlet.
  • We added the LoadBalancerServlet. It can be used in combination with the BackendConnectorServlet for load balancing over backends.
  • We introduced the parameter Cookie.KeepOldCookieTimeout of the SessionManagementFilter. With this parameter issues caused by parallel requests during login can be solved.
  • We added the parameter ‘crashRecoveryStrategy’ to navajo.xml.
  • There is a new experimental servlet, the PostgreSQLSessionStoreServlet. It can be used as an alternative to the MySQLSessionStoreServlet.
  • RedHat 9 is now supported as well. There is an extra RedHat9 package available.
  • In the OpenTelemetry section of navajo.xml you can now configure the OpenTelemetry settings.

What has changed​

  • From now on, nevisProxy uses the default open files resource limit of the system. See the Increase the number of open file descriptors sub-chapter on how to increase it, if your system default is not high enough.
  • Due to an improvement for IPv6 support for your backend connections in the web.xml, nevisProxy may fail to connect to the backend if the hostname is resolved to an IPv6 address, but the backend does not support or is not configured for IPv6 support. This can happen if the hostname (for example, localhost for a local connection to nevisAuth) was stored in /etc/hosts for both IPv4 and IPv6 addresses, but the host does not support IPv6. Generally, we do not recommend to use localhost in your web.xml.
  • In the ModSecurityFilter, the logged line for matched rules is refactored. Check if your setup depends on these log lines, and adapt them to your needs:
    • The matched rules will always have the log level NOTICE.
    • Removed any duplicated information.
  • Due to a security fix, redirects starting with // or / url-encode the second slash to avoid a redirect to a malicious page.
  • Due to systemd limitations, the directories of an instance have to belong to the User configured in the systemd configuration file: /usr/lib/systemd/system/[email protected]. On a newly installed nevisproxy package, the value is set to root.
  • For the dynamic session store to accommodate bigger values, the datatype of the VALUE column in the ATTRIBUTE table changed from VARBINARY(60000) to MEDIUMBLOB as default. For new instances, the SQL scripts are adapted. For existing instances, you can execute the following SQL command on the database:
ALTER TABLE attribute MODIFY VALUE MEDIUMBLOB;
  • Because the parameter AutoRewrite of the HttpConnectorServlet supports the rewriting of the Link-header, the LuaFilter could do a second rewriting. In such a case Link header would not work correctly any longer. If you configured one of those filters, then you can remove it, unless the AutoRewrite parameter in the HttpConnectorServlet does not have the link rewriteheader enabled.
  • The Encrypter Lua class handles differently the passwords that contains zero characters (\x00) and the failed decryptions.
  • The default RequestFlags of the RewriteFilter and InflateFilter changed: +PRUNE_ACCEPT_ENCODING, which modifies the Accept-Encoding request header.
  • The default value for the Frontend connectors' SSLHonorCipherOrder is changed to "on".
  • The default value for the Server's LogFormat is changed to &quot;%h %l %u %t \&quot;%r\&quot; %>s %b %{content-length}i %T \&quot;%{Referer}i\&quot; \&quot;%{User-Agent}i\&quot; trID=%{UNIQUE_ID}e&quot;.
  • The Engine/Host/Context/trailingSlashRedirect option's default value is changed to "true".
  • If you enabled the secure defaults as described in the chapter Secure defaults, these new secure defaults will be applied to the parameters that are not defined explicitely in your UrlEncryptionFilters. This change makes your UrlEncryptionFilters more secure, at the risk of generating some false positive results, and blocking some requests that should be authorized. Therefore, before deploying the new nevisProxy version:
    • Check that the new secure default values match your security policies;
    • Check that your UrlEncryptionFilters provide the expected results with these new values.
  • Requests that contain form data in their body will now be blocked if Encryption_VerifyBody is set to true and the requests’ body are not encrypted. To correctly handle such scenarios, visit the UrlEncryptionFilter’s documentation and read the VerifyBody parameter’s description.
  • Some so far allowed queries (mainly form submits) might be blocked when Encryption_VerifyBody is set to true because of the UrlEncryptionFilter’s QueryWhiteList bugfix.
  • Changed the redirections of relative URL-s to only contain the URL’s path when ch.nevis.navajo.response.Location.rfc2616compliant is false.
  • mod_qos works for the hypertext transfer protocol version 1.0 and 1.1 only. If you decide to use HTTP/2, you should only use the request level control directives of mod_qos.
  • If both the InitialURI and StoreInterceptedRequest is set, the StoreInterceptedRequest has precedence over the InitialURI, and the latter is ignored.
  • Local URL-s that contain ':' inside the URL's path, query or fragment/anchor part, will now be encrypted by the UrlEncryptionFilter. If you have URL-s that shouldn't be encrypted but contain ':', then add these URL-s to the Encryption_PlainTextUrls.
  • Due to the upgrade from OpenSSL 1.1.1 to OpenSSL 3.0 some old backends or frontends may not work anymore if they don't support at least TLSv1.2. Read the Troubleshooting section on how to proceed in case of problems.
  • Http(s)ConnectorServlet may return different Location headers when its AutoRewrite parameter contains 'redirect' because the redirections are now jailed under servlet path when mappingType is set to pathInfo and relative URL-s are rewritten to absolute URL-s.
  • Set-Cookie headers coming from the backends are now passed unchanged to the frontend unless a filter or servlet modifies one of the cookie attributes. On previous releases, they may have been parsed and either the expiry date (due to a wrong format) or the order of the fields could have changed.
  • For on premises installations without nevisadmin4 the systemd configuration file has changed in order to support graceful shutdown. This may have an impact if an instance can not be shut down properly.
  • Because of an improvement in the IdentityCreationFilter with OriginalUrl.Enable to true and InterceptionRedirect to never, requests without a body will not generate a redirect any longer after a successful authentication, but the original request will be sent directly to the backend.
  • In the MariaDB server configuration the default of the parameter slave_parallel_mode was changed to optimistic starting from version 10.5.1. Our load tests showed that with this configuration the replication may stop under heavy load. We therefore recommend to set the slave_parallel_mode to conservative if you use MariaDB server 10.5.1 or newer with replication.
  • The custom based session management filter will now base62 encode the custom id in order to have only alpha numeric characters in it. As a consequence, sessions using the custom-based session management will get lost when upgrading from a previous version, even if they are stored in a database. Furthermore all instances sharing the same database have to be updated to version 7.2311.x or newer.
  • The SSLCipherSuites parameter of the HttpsConnectorServlet and of the ICAPFilter as well as the Secure.CipherSuites parameter of the BackendConnectorServlet does not accept any spaces between the various cipher suites. The cipher suites have to be separated by a :. They can now be prefixed by the protocol where they should be applied.
  • If a request is blocked because it exceeds the size configured by LimitRequestBody in navajo.xml, a statuscode 413 (Request Entity Too Large) is now sent back to the frontend.
  • If a user wants access to a session with an expired sectoken, the session is killed and in most cases the user gets the login page. If you want the old behavior, where the user got the logout page, you have to set the parameter SectokenExpireStrategy of the IdentityCreationFilter to logout
  • The defaultvalue of the bc property ch.nevis.navajo.tracing.TraceId.Format has changed from %u to %o (the OpenTelemetry trace id). In order to use the old format you have to set it back to %u and not enable the OpenTelemetry configuration (which is disabled by default).
  • With some special configuration using the IdentityCreationFilter and the MultiLevelSessionStore the MariaDB may be filled up. In that case add the following unique key to the MariaDB based dynamic session management:
    • alter table attribute add constraint uc_id_name unique (ID, NAME);

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:

  • The remote (MySQL) legacy session store.
  • The deprecated nevisProxy commands.
  • The AuditFilter is now removed. Use the LoggerFilter instead.
  • The undocumented PCREUTF8 option for regular expressions (use PCRE(utf8) instead).
  • The all-SSLv2 TLS protocol.
  • The deprecated parameters CarrierVersion, Verbose (in the Core tag), and DefaultType in navajo.xml.
  • The undocumented authentication method join in the EsAuth4ConnectorServlet.
  • The deprecated parameters of the UnbluFilter.
  • The deprecated RedirectFormFilter.
  • The deprecated SessionResourceFilter.
  • The deprecated profiles and parameters of the InputValidationFilter.
  • The deprecated RLIMIT_ parameters from navajo.xml.
  • The deprecated EngineLeaksOnCascadeDelete parameter of the MySQLSessionStoreServlet.
  • The deprecated parameters org.apache.host and org.apache.location of the RewriteFilter.
  • The parameter ProActive from the WebSocketServlet.
  • The QoS element from the navajo.xml configuration file.
  • The deprecated UserStatusServlet.
  • The deprecated parameter LimitUserLogins from IdentityCreationFilter.
  • The deprecated attribute MaxClientsPerIpAddr.
  • The deprecated VirtualSessionFilter.
  • We removed the parameter ExclusiveSessionLock of IdentityCreationFilter and SecurityRoleFilter. If set to “false”, as a side effect of this parameter, a session was completed invalidated if several IdentityCreationFilters or SecurityRoleFilter shared the same StateKey. To have the same behavior, the parameter ‘InvalidateSessionOnStateRemoval’ is introduced. We therefore recommend to set InvalidateSessionOnStateRemoval to “true” whenever you set ExclusiveSessionLock to “false”.
  • Instead of the removed Apache directive ‘SSLLogLevel’, use the directive ‘LogLevel’ under the Server tag in navajo.xml. For further information on how to configure the LogLevel directive, see Server configuration.
  • We replaced the error code [BASE-0031] by a NOTICE.
  • We removed the SAMLErrorFilter.
  • We removed the parameter SSLDHParametersFile from navajo.xml.
  • Due to the Apache upgrade to version 2.4.52, the functionality controlled by the undocumented bc property ch.nevis.navajo.RestartAfterHsmError does not work anymore, therefore the property has been removed.
  • We removed the PrivateURIScheme parameter of the IdentityCreationFilter.
  • We removed the deprecated XMLValidationFilter.
  • We removed the deprecated POSIX based regular expression.
  • We removed the Kerberos-related parameters in the DelegationFilter.
  • We removed the TLS-based identification in the SessionManagementFilter.
  • We removed support for the Legacy Session Store (or Container Based Session Management).
  • We removed the deprecated SecToken versions.
  • We removed the deprecated parameter RemoveIntereceptedRequestAfterAuthentication from the IdentityCreationFilter.
  • We removed the deprecated HTTP Profiles of the InputValidationFilter.
  • We removed the deprecated parameter ?OriginalUrl.SecretKeyFile? of the IdentityCreationFilter.