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

nevisProxy migration guide from LTS-2019 to LTS-2021

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

You should also eliminate most Deprecation notices in the logs of your existing setup. This will facilitate the transition to LTS2021 and eventually to RR and subsequent LTS.

What’s new​

  • NEW: The SecurityRoleFilterincludes the new parameter InvalidateOnError, which is set to true by default. As a consequence, the SecurityRoleFilter now automatically invalidates a session if nevisAuth returns an error. This new behavior may break backward-compatibility. If you run into problems because of this, set the filter's new parameter InvalidateOnError to "false". This will restore the previous behaviour. Also contact Nevis Support so that we can analyze the problem.

  • NEW: Due to a wrong configuration, a core dump could occur in the UnbluFilter. To avoid this, some checks have been added to the following parameters of the UnbluFilter:

  • NEW: nevisProxy now supports SSL identification with HTTP/2. Because of this, nevisProxy may behave slightly differently in case of TLS identification. TLS1.3 and HTTP/2 introduced differences into how TLS identification works for the sake of privacy. We recommend testing your new setup, to make sure it works as expected. If this is not the case, switch to Cookie identification and inform Nevis Support of the issue to see if it may be possible to improve the situation.

  • NEW: For security reasons, the IdentityCreationFilter now contains the new parameter RenegotiateCookieOnAuthContinue. The parameter is enabled by default to prevent session fixation attacks. In this case, the session Cookie is renegotiated on every authentication step. The introduction of this parameter can lead to backward compatibility issues, especially if parallel requests take place during the authentication phase. To avoid this, make sure that parallel requests that do not need authentication are not mapped to the IdentityCreationFilter.

What has changed​

  • CHANGED: The peer hostname check of the backend connections has been refactored. It now performs additional validations besides the check against the CN/SAN of the certificate. Therefore, if the peer hostname check is enabled, it is now mandatory to configure the CA of the peer's node certificate. For backward-compatibility reasons, the flag bc.net.ssl.EnableLegacyHostnameCheck has been added, allowing you to switch back to the previous mechanism. For more information, check the parameter SSLCACertificateFile of the HttpsConnectorServlet, or the parameter Secure.CACertificateFile of the BackendConnectorServlet.

  • CHANGED: Error handling has been improved and works slightly differently. Now nevisProxy handles errors in responses coming from the backend more strictly and accurately. It can block a request if the backend sends unexpected or invalid content in the response. If you notice a change in behavior in your setup concerning error handling, investigate the validity of the response from the backend.

  • CHANGED: The default behavior of the [EsAuth4ConnectorServlet]has changed. The pollTerminatedSession feature is disabled by default, meaning that nevisProxy will not continuously poll the nevisAuth instance for terminated sessions. If needed, you can re-enable this feature with the new parameter EnablePollTerminatedCalls. If set to true, nevisAuth will notify nevisProxy about terminated sessions. A possible consequence is that if nevisAuth returns an error or a redirect and invalidates the session, then the session is still valid in the proxy and this may lead to an endless login-loop because the session is not invalidated in the proxy and in auth the session is not found.

  • CHANGED: As of this release, the cookieHttpOnly parameter of the UserAgent section in the navajo.xml file is only valid for the cookies of the legacy session management. For all other cookies, this parameter is now ignored. Now the cookies from the backend are kept as they are, unless some filter in between (RewriteFilter, LuaFilter) adds the flag. For cookies generated by nevisProxy, this parameter is available on the filter or servlet that generated it. For all cookies set by the proxy this flag can be configured in the filter/servlet which creates the cookie

  • CHANGED: The new eventMulti-Processing Module replaces the previous worker Multi-Processing Module in the Apache httpd server. As a consequence, the proxy may not start due to the low value of the MaxClients parameter in the [Server tag] of the navajo.xml file . In this case, increase the value of the MaxClients parameter - the recommended default value is 600.

  • CHANGED: Session reaping in the [MysqlSessionStoreServlet] has been improved. See the [Notes] section of RR4 for further instructions.

  • CHANGED: The default value for the parameter UnbluCompatMode of the UnbluFilter has been changed from "-1" (legacy) to "5". As a consequence, the UnbluFilter may no longer work correctly, especially if one of the following conditions is true:

    In those cases, perform one of the following:

  • Set the parameter UnbluCompatMode to "-1", or

  • Switch to UnbluServer version 5 or higher, or

  • Replace or remove the (deprecated) parameters BaseUrlPattern or BaseUrlHeader.

  • CHANGED: For the dynamic session store, depending on the amount of data, the maximum size of a parameter in the attribute table may be reached, which causes the proxy to stop working correctly. For this reason the datatype of the row ATTRIBUTE_ID in the attribute table has been changed from INT to BIGINT to allow storing more data in the session store.

    alter table attribute MODIFY column ATTRIBUTE_ID BIGINT NOT NULL AUTO_INCREMENT;

    It is recommended that you execute this command when there is no load on the database.

  • CHANGED: The Navajo based SSLCache has been refactored to behave like the Apache SSLSessionCache. This should not cause any actual side effects but depending on your use case, client certificate authentication may demonstrate minor differences from previous versions.

  • CHANGED: The default value for the KeepAlive parameter of the HttpConnectorServlet has been changed from false to true. This may prevent your backend from working correctly if it does not support keep alive requests.

  • CHANGED: When a filter or servlet blocked a request due to a security issue, either the status code 500 or 403 was sent to the frontend, depending on the position on which the filter or servlet was mapped. Now the system alwayssends a status code 403 (Forbidden) to the frontend, independent of the mapping position. If you rely on those status codes in you integration (e.g. monitoring), you need to adjust your logic accordingly.

  • CHANGED: The default value of the attribute (flag) ProActive in the WebSocketServlet is now false. RFC conforming backends should not require this flag to operate. This change may break backward compatibility. If problems relating to websockets occur with the new default value, re-set the ProActive flag to true and contact nevisProxy support. This flag is completely removed in the upcoming RR.

  • CHANGED: The default value of the low-level bc.property ch.nevis.bc.net.multipart.formdata.rfccompliant is now true. Requests with content type multipart/form-data are now allowed to have preamble and epilogue parts. For security reasons, do not set the parameter ch.nevis.bc.net.multipart.formdata.rfccompliant to false.

  • CHANGED: The JsonFilter and SoapFilter no longer accept the values true or false for the parameter BlockOnError. For a description of the allowed parameter values, see the chapters JsonFilter and SoapFilter respectively.

  • CHANGED: Due to the upgrade of mod_setenvifplus to version 0.39, the attribute SetEnvIfCmpPlus no longer silently ignores extra arguments. This new behavior will result in an error if too many arguments are provided.

  • CHANGED: The mod_qos library is now linked in nevisProxy. Perform the following steps if you get this error: module qos_module is built-in and can't be loaded

    LoadModule mod_qos /opt/nevsiproxy/lib/libmodqos_2_4.so.1

  • CHANGED: The following filters and servlets now use an updated and therefore more secure SSL cipher suites set: HttpsConnectorServlet, WebSocketServlet, ICAPFilter and Esauth4ConnectorServlet. This also results in a new default setting for the filter/servlet attribute SSLProtocol: "-all +TLSv1.2 +TLSv1.3". Because of this update, some backends using TLSv1.1 may not work anymore. If so, either adapt the corresponding parameter of the given servlet, or upgrade the backend to use one of the recommended protocols.

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 deprecated SSL protocol SSLv3.

  • The deprecated ApacheServlet.

  • The following deprecated filters:

  • The certificate verification before booting nevisProxy.

  • The deprecated local-memory cache provider (technical expression: LocalMemoryCacheProvider).

  • The deprecated log analyzer files written in Perl.

  • All attributes in the navajo.xml file that were deprecated in the past. This includes the following attributes:

  • The following deprecated parameters of the [HttpConnectorServlet]:

  • The following deprecated parameters of the [EncryptionFilter]:

  • The following undocumented or deprecated parameters of the:

  • The following undocumented or deprecated profiles have been replaced by the ModSecurityFilter and have been removed from the [InputValidationFilter]:

  • The misspelled and therefore deprecated parameters SplittMultipartBody and SkippResponseHeaderCondition of the [ICAPFilter].Use their correctly spelled counterparts instead.

  • The deprecated parameter VirtualSession, which was used by the filters.

  • The renegotiation parameter from the Navajo cookie cache (technical name: NavajoCookieCache).

  • The processing flag from the rewrite rules of the [RewriteFilter].

  • The deprecated or undocumented cookie rules "on", "always" and "check" of the CookieManager attribute. The CookieManager is used in the [CookieCacheFilter].

  • The client identification type "combined", from the identification attribute in the navajo.xml file section).

  • The undocumented low level property ch.nevis.navajo.servlet.engine-memory.increment.<servlet-name>.

  • The command nevisproxy <instance> reinit.