The OpenAS2 project is pleased to announce the release of OpenAS2 4.0.0
The release download file is: OpenAS2Server-4.0.0.zip
The zip file contains a PDF document (OpenAS2HowTo.pdf) providing information on installing and using the application.
Version 4.0.0 - 2024-10-15
This is an major change and enhancement release. IMPORTANT NOTE: Please review upgrade notes below if you are upgrading
- Java 8 is NO LONGER supported. Support is for Java 11 and newer releases only.
- The logging facade was switched from Jakarta Commons Logging to SLF4J and the default implementation uses the Logback framework.
- The DB state logging for external databases now uses an Hikari connection pool and persists to the database using a separate thread to improve performance.
- Switch to Jakarta package for mail and REST API implementations
- Remove the insecure "remote" socket command processor and associated support class in the OpenAS2 server.
- Remove redundant packages from maven build.
- Fix MDN cleanup occurring when resend mode is entered.
##Upgrade Notes See the openAS2HowTo appendix for the general process on upgrading OpenAS2.
1. Ensure you implement all logging that you had configured for ealrier versions using the logback configuration or replace with another framework that works with SLF4J facade. See the OpenAS2HowTo.pdf logging section for more details.
2. The property for email configuration in the config.xml changed:
Change ALL occurrences of javax.mail.properties to jakarta.mail.properties in config.xml and the .properties file if you implemented it.
3. If using an external database for message state tracking, make sure that your configuration will work with the new Hikari JDBC pool that improves performance. See the OpenAS2HowTo.pdf message state tracking section for more details.
4. Completely replace all library files in the existing "lib" folder wit hthe ones supplied in the new install package (per recommended standard procedure in the user guide).
1. Run the following command after the upgrade of the code base is complete and BEFORE you start the OpenAS2 server:
- Open a shell (Command prompt or Powershell in Windows or a Terminal window in NIX systems)
- Run this command (NOTE the backslash escape to prevent command line expansion of asterisk):
> java -cp /path/to/openas2/lib/\* <version of DB before upgrade> <DB user> <DB password> <path to DB file excluding the .mv.db extension>
The version of the DB before upgrade will be the same last 3 digits of the h2 jar file in your install BEFORE the upgrade.
If upgrading from 3.5.0 then the number is 214.
The user ID, password and location of the DB file will be in your config file or if overridden then in the custom properties file.
As an example assuming a vanilla install of OpenAS2 in /opt/OpenAS2 folder (replace / with \ for Windows):
> cd /opt/OpenAS2
> java -cp lib/\* UpgradeH2Database 214 sa OpenAS2 config/DB/openas2
NOTE: The old config will work without change but it is strongly recommended that you follow these steps to convert your existing configuration to the new format as it provides a cleaner and less complicated setup and the old config will eventually be discontinued
1. Follow the instructions for specific versions between your current version and this version as defined below before executing the commands below to convert your existing config.xml and partnerships.xml files to use the enhanced poller configuration.
2. Open a terminal window (command window in Windows)
3. Change to the <install>/config directory of the new version.
4. Copy the config.xml and partnerships.xml from your existing version to the new version if not already done in other steps.
5. Run this command: java -cp ../lib/\* org.openas2.upgrades.MigratePollingModuleConfig config.xml partnerships.xml
6. A backup will be created of the original file (with .00 extension|) that can be removed if the conversion is successful.
Below are some specific things to focus on depending on which version you are upgrading from.
You must review all notes for the relevant intermediate versions from your version to this release version.
1. If you are using the DB tracking module with the default H2 database then you will need to follow the DB upgrade steps "Appendix: Updating database structure" defined in the OpenAS2HowTo.pdf to ensure you do not lose your existing data because the new H2 version has issues with old databases.
2. A change to the way the private key is looked up in the receiver handler means that if you have duplicated a certificate in the keystore, some partnerships may start to fail. This fix may fix other strange certificate issues when receiving messages. To fix partnership failures that occur after the upgrade, find the duplicates and remove them making sure the one you leave behind is the one with the correct private key. Alternatively, use the **use_new_certificate_lookup_mode** attribute at partnership level set to **false** and the old mechanism will be used but this is not advised as a long term solution as it will eventually be removed in a future version.
If you have been passing the password for the certificate file on the command line in a shell script (no change to the Windows .bat file):
1. The mechanism to pass the password on the command line has changes. You must now use this format:
-./start_openas2.sh -Dorg.openas2.cert.Password=<keyStorePwd>
where <keyStorePwd> is either a reference to an environment variable or the actual paasword itself.
Since passing the password in the command line does not provide for any additional security, it is recommended you use the new environment variable option described in the docs.
1. There is a script in the "upgrade" folder : <installDir>/bin/upgrade/config_transform.sh.
This script can be run without parameters to get usage message.
The simplest way to run it is to open a terminal in the upgrade folder and run:
config_transform.sh <path to old config.xml file>
This will produce a file named config.xml.new in the upgrade folder. Copy this file to the config.xml in the new OpenAS2 version.
Windows user can use the new Linux shell to run the above script or run this command from within the upgrade folder:
java -jar lib/saxon9he.jar -xsl:config.xslt -o:config.xml.new -s:<path to old config.xml file>
1. Run the schema upgrade process as defined in the Appendix for the relevant database you are tracking messages in.
1. Change the name of the MDN sender module from "AsynchMDNSenderModule" to "MDNSenderModule" in the config.xml if using your existing config.xml file in the upgrade. If "AsynchMDNSenderModule" is not in the config then add the following: <module classname="org.openas2.processor.sender.MDNSenderModule" retries="3"/>
2. Change the name of the partnership attribute "messageid" to "as2_message_id_format" if used in any partnership definition.
3. Change the "as2_mdn_options" attribute to use $attribute.sign$ instead of hard coded signing algorithm
4. If you experience issues with partners failing that were working in the previous version, check the troubleshooting section of the OpenAS2HowTo guide - specifically the issues around Content Transfer Encoding and Content Length/Chunking
1. If you have developed custom modules to enhance OpenAS2 they will need to be upgraded to include a healthcheck() method.
1. If using a custom startup script, re-integrate your customizations into the new script as the jar file for OpenAS2 is now tagged with its release version. (use asterisk [*] in classpath)
1. Add the new module to your existing config.xml (see classname="org.openas2.processor.msgtracking.DbTrackingModule" in release config.xml)
2. If using a custom startup script, re-integrate your customizations into the new script
3. As of 2.3.1 the log date format was changed to international standard. If you have log processing utilities that rely on a specific date format then you must change as needed (see documentation for mechanism)
Java 1.7 or later is required.
The version of H2 database included in this release used for storing tracking messages will only support Java 1.7.
If you do not need the DB tracking feature then simply remove it from the config.xml file.
Otherwise:
- download the older version of H2 that was compiled with support for Java 1.6 from this site:
https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/h2database/h2-2014-01-18.zip
- Extract the file named h2-1.3.175.jar from the zip and replace the h2-1.4.192.jar in the "lib" folder with this one.
- Change the startup script to include the replaced version of H2 jar in the classpath
- Start OpenAS2 (required to run next statement successfully) and import the DDL (located in the config folder as db_ddl.sql) into the DB created by the older version like this:
java -cp [path to OpenAS2 install]/lib/h2-1.3.175.jar org.h2.tools.RunScript -user sa -password OpenAS2 -url jdbc:h2:tcp://localhost:9092/openas2 -script [path to OpenAS2 install]/config/db_ddl.sql