Software Version Notes

Document Version History

• v1.0 – initial OSCAR 19 version published to oscargalaxy.org – Nov 1, 2021
• v1.0 – MariaDB password authentication notes – Jan 18, 2022
• v1.1 – whhtmltopdf hardening notes – Dec 28, 2022
• v1.2 – patched wkhtmltopdf notes – Feb 20, 2024

Copyright © 2021-2022 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License

Life Cycles and End of Life

Each bit of software in OSCAR has a lifecycle

OSCAR 15 and prior versions are End of Life and no longer supported. The current version at the time of this writing is OSCAR 19. OSCAR depends on a software stack that has various end of life (EOL) dates. The following are reference installation environments tested and recommended for installing OSCAR debs. They are not dependencies per se but rather supported combinations that worked at the time. Thus earlier and later software combinations may and do work but are not the default installation. Expiry dates are for the combination of software that form the stack although some component may still be maintained past that date. Note that future expiry dates are provisional.

Notes on Java

Note that Oracle Java requires a commercial license to run OSCAR in production as of Jan 2019

Lifespans of various Java (Non paid security support end dates)

• Java 6 2006-Dec 2013
• Java 7 2011-April 2015
• Java 8 LTS 2014-Nov 2026
• Java 9 2017-March 2018
• Java 10 2018-Sept 2018
• Java 11 LTS 2018-Oct 2024
• Java 17 LTS 2021-Sept 2027
• Java 21 LTS 2023-Dec 2029

OSCAR 19 code technically remains Java 6 compliant, however on Dec 13 2021 builds of oscar_emr19-47~1479.deb and newer are now exclusively compiled against Open JDK 8, which then becomes the minimal Java version.

Java 17 breaks the Jasper Reports library in OSCAR.  For daily use that means label printing is no longer available.  Also certain reports will be impacted including the BC AR 2020, Patient Letters, end of year subreport, Rourke 2017, lab day sheet, and Billing Invoice.

Open JDK is a project controlled by Oracle who currently only supports a version for 6 months or so.  After that the community takes over support.  AdoptOpenJDK provides extended security support and binaries for anyone’s use including Linux distributions.

Open JDK is provided by many binaries (look for ones that are Java SE compatible) including those provided by AdoptOpenJDK, Zulu, J9, Corretto, etc and those packaged by many Linux distros including Ubuntu. 

The OSCAR 19 war package has been tested in production environments with Ubuntu JDK 8, Eclipse J9 JDK8 and Zulu JDK 8. Java 11 and Java 17  support was introduced in the oscar_emr19-46~1364.deb of Nov 1, 2021.  Java 21 support is current in 2024.

The Eclipse J9 is suggested if you are having Java errors with the Ubuntu package. Its JVM is completely different than hotspot which may be a performance advantage.  If you add the repository as below it will also get automated updates.

$ wget -qO - https://adoptopenjdk.jfrog.io/adoptopenjdk/api/gpg/key/public | sudo apt-key add -
$ sudo add-apt-repository --yes https://adoptopenjdk.jfrog.io/adoptopenjdk/deb/ 
$ apt-get update 
$ apt-get install adoptopenjdk-8-openj9

Test if desired (your output will be slightly different):

$ java -version
openjdk version "1.8.0_292"
OpenJDK Runtime Environment (build 1.8.0_292-b10)
Eclipse OpenJ9 VM (build openj9-0.17.0, JRE 1.8.0 Linux amd64-64-Bit Compressed References 20191017_442 (JIT enabled, AOT enabled)
OpenJ9   - 77c1cf708
OMR      - 20db4fbc
JCL      - 97b5ec8f383 based on jdk8u232-b09)

For a new install the DEB will pick the update-alternatives configured at time of installation regardless of brand.  If you change the configured Java after initial installation Tomcat 9 will follow you to the new version. However it is still suggested that you manually change to the correct JDK with the $JAVA_HOME setting with the following

$ sudo nano /etc/default/tomcat9

For example below we have commented out the Ubuntu open JDK and configured J9

#JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
JAVA_HOME=/usr/lib/jvm/adoptopenjdk-8-openj9-amd64

Notes on Tomcat

Tomcat is a “pure Java” HTTP web server environment that provides the OSCAR application. Different versions of Tomcat require different minimum Java. For Tomcat 10.1 it is Java 11. For Tomcat 9 that theoretically is Java 8 as the Tomcat 9 code doesn’t use any features of newer Java. Unfortunately if Tomcat is compiled in a newer Java (as it is in Ubuntu 22.04 where it is compiled against Java 11) the minimum version becomes the Java that it is compiled against. The installation instructions for Tomcat 9 in Ubuntu 22.04 have been amended to describe how you can patch it to run Java 8.  OSCAR 19 currently does NOT run on Tomcat 10.1

OSCAR 19 has been tested on Tomcats 7-9

• Tomcat 7 EOL April 2021
• Tomcat 8.5 EOL April 2024
• Tomcat 9 EOL ? April 2027 (announcement pending)

Notes on wkhtmltopdf

As many OSCAR installations depend on faxing or pdf of eForms that are of arbitrary origin this constitutes a potential security hazard. The developers themselves warn you should never convert untrusted html with wkhtmltopdf and yet we do. To mitigate the risk there are several options. For existing installations I recommend the second solution with AppArmor which is robust and will work for both source and DEB installed OSCAR’s of any vintage.

Note: The final release of wkhtmltopdf was 0.12.6. It is no longer being maintained. https://wkhtmltopdf.org/status.html#summary

The NO wkhmltopdf option

Using the internal library is an option for OSCAR 19 build 2781 and later. The internal converter requires Debian Bullseye or Ubuntu 20.04/22.04 and a list of dependencies.  Note that ‘libjpeg62-turbo’ and ‘ libssl1.1’ have no installation candidates available for Ubuntu 24.04, so the internal converter may not work in the latest Ubuntu.

apt-get -qq -y --no-install-recommends install ca-certificates fontconfig libc6 libfreetype6 libjpeg62-turbo libpng16-16 libssl1.1 libstdc++6 libx11-6 libxcb1 libxext6 libxrender1 xfonts-75dpi xfonts-base zlib1g

You will then need to ensure that oscar properties no longer points to the wkhtmltopdf executable but to the internal library, adjust oscar.properties to indicate WKHTMLTOPDF_COMMAND=internal

The internal converter uses a subset of the wkhtmltopdf arguments for backwards compatibility. Supported arguments for WKTHMLTOPDF_ARGS= are

WKHTMLTOPDF_ARGS=--print-media-type --disable-smart-shrinking --minimum-font-size 11 --zoom 0.9

The wkhtmltopdf with AppArmor mitigation option

You can mitigate the risk of Server-Side Request Forgery SSRF in wkhtmltopdf by applying AppArmor policy to wkhtmltopdf

Enable AppArmor on boot through:

systemctl enable apparmor
systemctl start apparmor

Then you need to install a profile

sudo nano /etc/apparmor.d/usr.local.bin.wkhtmltopdf

The profile should look like the following for all DEB installed OSCARs.

# vim:syntax=apparmor
# OSCAREMR AppArmor policy for wkhtmltopdf 
# ### P Hutten-Czapski ###
# ### (c) 2022 ###
# ### released under GPL ###                      
#include <tunables/global>

/usr/local/bin/wkhtmltopdf {
  # Allows
  #include <abstractions/base>
  #include <abstractions/fonts>
  #include <abstractions/nameservice>
  #include <abstractions/openssl>

  deny capability sys_ptrace,

  # System paths wkhtmltopdf needs to operate
  /etc/ssl/certs/ r,
  /proc/*/maps r,
  /usr/local/bin/wkhtmltopdf mr,
  /var/cache/fontconfig/* r,
  /tmp/** rwlk,

}

To activate the profile simply sudo systemctl reload apparmor

With AppArmor running I recommend the wkhtmltopdf maintained by the developers (which is no more secure but has more features than the one supplied by Ubuntu. ) Currently the list of additional features include:

• Running without an X11 server (“headless” eg Ubuntu server edition)
• Printing more than one HTML document into a PDF file.
• Adding a document outline to the PDF file.
• Adding headers and footers to the PDF file.
• Generating a table of contents.
• Adding links in the generated PDF file.
• Printing using the screen media-type.
• Disabling the smart shrink feature of webkit.

The only feature that OSCAR has to have in a headless server is the ability to run without  X11.  The ability to disable the smart shrink can solve some output issues. You can get this version from the developer, and then install it and its dependencies with apt. You are on your own to notice download and install newer versions.  Note that versions 12.6 and above disable local file access by default and need to be run with the –enable-local-file-access option.

Installing the patched version of wkhtmltopdf

Although wkhtmltopdf is no longer supported, the patched versions are available online.

$ wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb
Need a font:
$ sudo apt-get update -y
$ sudo apt-get install -y xfonts-75dpi
$ sudo dpkg -i wkhtmltox_0.12.6.1-3.jammy_amd64.deb

For OSCAR to pick up this binary either change the OSCAR property file or make a link

sudo ln -s /usr/local/bin/wkhtmltopdf /usr/bin/wkhtmltopdf

Test it to check the resultant pdf to see that it has the following output and displays correctly.

$  wkhtmltopdf -s Letter -T 10mm -L 8mm -R 8mm --print-media-type --disable-smart-shrinking --enable-local-file-access http://oscargalaxy.org /tmp/test.pdf
Loading pages (1/6)
Counting pages (2/6)                                               
Resolving links (4/6)                                                       
Loading headers and footers (5/6)                                           
Printing pages (6/6)
Done

Notes on MySQL and MariaDB

• MariaDB 5.3 2012-Mar 2017
• MariaDB 5.5 2012-Apr 2020
• MariaDB 10.0 2014-Mar 2019
• MariaDB 10.1 2015-Oct 2020
• MariaDB 10.3 2018- May 2023
• MariaDB 10.4 2019 – June 2024
• MariaDB 10.5 2020 – June 2025
• MariaDB 10.6 2021 – July 2026
• MariaDB 10.8 2022 – July 2027

While OSCAR previously used MySQL, MySQL 5.7 and newer do not natively support OSCAR 15 although this is technically possible with modification. The MariaDB database is a binary compatible fork of MySQL. Its developers (who founded MySQL) claim that it is faster than MySQL and better optimized. Advanced cluster replication is available but varies from MySQL.

The unix plugin prevents non system root users from logging in to MariaDB, but allows for root users to log in to MariaDB directly without a password. By removing the plugin everyone (including the non privileged tomcat user who has to access it without root access) can, and has to, sign into MariaDB by providing the MariaDB password.

Earlier MariaDB used the mysql method to disable the unix plugin to allow for password based access

MariaDB [none]> use mysql;
MariaDB [mysql]> update user set plugin='' where User='root';
MariaDB [mysql]> flush privileges;
MariaDB [mysql]> quit

Current MariaDB allow the unix plugin to be disabled in the following

ariaDB password to replace ****** below

MariaDB [(none)]> ALTER USER root@localhost IDENTIFIED VIA mysql_native_password; MariaDB [(none)]> SET PASSWORD = PASSWORD('*******');

MariaDB 10.2.4 and newer add in additional complications from strict mode enforcement of certain limits in its default configuration for Ubuntu. To meet them various OSCAR 19 tables have been altered from varchar to TEXT and several legacy forms have been removed. Strict mode and other default restrictions adds certain safeties. ONLY If you need those forms you should edit my.cnf [mysqld] section to override the default sql_mode. sql_mode= can be set blank or to any of the options supported, just avoid the ones that sound strict.

These newer MariaDB require another approach to setup password based access as detailed in the instructions for Ubuntu 20.04 and newer and referenced https://mariadb.com/kb/en/authentication-plugin-unix-socket/