2: OSCAR19 Install: Finishing Touches

Access to custom directory. To access OSCAR files the tomcat9.service has to have an entry ReadWritePaths=/usr/share/oscar-emr/

• The tomcat9 config file is located in /etc/default

Removal of OSCAR

Although OSCAR isn’t for everyone, consider asking for help on the mailing list for BC-users (its misnamed) or sending us a note why you are uninstalling it. OSCAR can be removed using dpkg :

sudo dpkg --remove oscar-emr

This will remove the program, but keep the data and configurations.
For complete removal of all sensitive patient data, or just to clear your server for further testing, you need to use purge. Be very careful that you are on the right server and have backups on hand before you run this as it cannot be undone.

sudo dpkg --purge oscar-emr
(Reading database ... 1456783 files and directories currently installed.)
Removing oscar-emr (19-40~1336) ...
Removing drugref.war
Dropping drugref database
Purging configuration files for oscar-emr (19-40~1336) ...
Purging will delete ALL data and settings
***********LAST CHANCE TO SAVE YOUR DATA WITH A CTL-C ************
Now proceeding with Purge
Removing symlinks
Reversing Changes to tomcat9 configuration
grep the password from the properties file
Dropping drugref
Dropping oscar_15
Deleting oscar.properties
Deleting /usr/share/oscar-emr/

Then you clear the deb template that saved your responses for the interactive part of the dpkg install:

echo PURGE | sudo debconf-communicate oscar-emr

 Documentation copyright [c] 2012-2025 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License

• Database errors. MariaDB 10.3 uses strict mode. Some early databases have definitions that are not supported which may be fixed by running the latest patch.sql
• Cache. OSCAR is huge and requires a lot of caching. Newer debs set context.xml <Resources cacheMaxSize=”102400″ />
• Access to custom directory. To access OSCAR files the tomcat9.service has to have an entry ReadWritePaths=/usr/share/oscar-emr/
  • The tomcat9 config file is located in /etc/default

Removal of OSCAR

Although OSCAR isn’t for everyone, consider asking for help on the mailing list for BC-users (its misnamed) or sending us a note why you are uninstalling it. OSCAR can be removed using dpkg :

sudo dpkg --remove oscar-emr

This will remove the program, but keep the data and configurations.
For complete removal of all sensitive patient data, or just to clear your server for further testing, you need to use purge. Be very careful that you are on the right server and have backups on hand before you run this as it cannot be undone.

sudo dpkg --purge oscar-emr
(Reading database ... 1456783 files and directories currently installed.)
Removing oscar-emr (19-40~1336) ...
Removing drugref.war
Dropping drugref database
Purging configuration files for oscar-emr (19-40~1336) ...
Purging will delete ALL data and settings
***********LAST CHANCE TO SAVE YOUR DATA WITH A CTL-C ************
Now proceeding with Purge
Removing symlinks
Reversing Changes to tomcat9 configuration
grep the password from the properties file
Dropping drugref
Dropping oscar_15
Deleting oscar.properties
Deleting /usr/share/oscar-emr/

Then you clear the deb template that saved your responses for the interactive part of the dpkg install:

echo PURGE | sudo debconf-communicate oscar-emr

 Documentation copyright [c] 2012-2025 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License

This is a part of a series on installing OSCAR19. Start by reading the first part.

Preface

You have 99% of a production ready OSCAR instance at this point. There are some minimal additional configuration settings that you really should do at this point to secure any exported data and to protect the server itself.

Two-factor authentication increases the security of the login process.

Data exports depend on PGP to encrypt the zipped patient files.

Principles of layered security require that a firewall be configured on the server even if your box is behind a solid firewall such as pfSense or FortiGate.

Document Revision History

• v1.0 – initial release by Peter Hutten-Czapski MD – 2017
• v1.2 – updated to include 2FA by Peter Hutten-Czapski MD – Jun 19, 2022
• v1.3 – general update including UFW changes by Adrian Starzynski – Oct 11, 2022
• v1.4 – updated PGP by Peter Hutten-Czapski MD – June 8, 2025

2FA

OSCAR can be configured to support increased security. Two-factor authorization is achieved with the user name and password (what the end user knows) and a one-time pin generated by an authenticator housed in the user’s smartphone (something they have). As of OSCAR 19.5 this is available through the UI when you setup a user.

Uncomplicated Firewall (UFW)

The default settings allow all outgoing connections and deny all incoming:

sudo ufw default deny incoming
sudo ufw default allow outgoing

The following are ports that you will need to consider in any firewall on an OSCAR server:

• As a minimum, users will access OSCAR on port 8443, so it needs to be open
• If you are using SSH to access your sever, you need to allow your ssh port (usually 22) *before* you enable the firewall, otherwise you will be LOCKED OUT with only method of access to the server being physical. If you are running OSCAR on a VM or on a cloud provider like Amazon EC2, and you turn on UFW without first enabling SSH, you will be completely locked out with no way of getting back in.
• OPTIONAL: Certbot needs port 80 to renew the server certificate
• OPTIONAL: Phpmyadmin uses port 80 to administer MariaDB
• OSCAR uses port 3306 locally to access patient data in MariDB, it can be closed to external access
• OSCAR uses port 8080 locally to access drugref for the lists of drugs, it can be closed to external access

sudo ufw allow 8443
sudo ufw allow 22

Ports 3306 and 8080 will be blocked to external access with the default rules but I like to explicitly close them with:

sudo ufw close 3306
sudo ufw close 8080

Enable the firewall:

sudo ufw enable

Check the firewall status

sudo ufw status

Configuring PGP

PGP is used to encrypt chart export. At the start I would hold off generating a key and provide chart export unencrypted. You can always encrypt afterwards, and its much easier to trouble shoot. While obviously insecure by itself you can just alter the oscar.properties file to allow for unencrypted output

demographic.export.encryptedOnly=false

Assuming that you want chart exports to be encrypted you can generate a key for use in OSCAR for the tomcat user. Follow the prompts (the defaults will do fine), and set a pass phrase. Be sure to set a name and email to serve as the UID for the key, and as a handle on any files you need to sign. The following is similar to expected output and was written for the convention used in tomcat 8. For tomcat 9 replace ‘tomcat8’ with ‘tomcat’.

$ sudo mkdir /var/lib/tomcat8/.gnupg
$ sudo chown tomcat8:tomcat8 /var/lib/tomcat8/.gnupg
$ sudo chmod 700 /var/lib/tomcat8/.gnupg
$ sudo -H -s -u tomcat8
tomcat8@hfht:~$ tmux
[detached (from session 0)]

tomcat8@hfht:~$ gpg --gen-key
gpg (GnuPG) 2.2.4; Copyright (C) 2017 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

gpg: keybox '/var/lib/tomcat8/.gnupg/pubring.kbx' created
Note: Use "gpg --full-generate-key" for a full featured key generation dialog.

GnuPG needs to construct a user ID to identify your key.

Real name: peter
Email address: phc@hfht.ca
You selected this USER-ID:
"peter <phc@hfht.ca>"

Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: /var/lib/tomcat8/.gnupg/trustdb.gpg: trustdb created
gpg: key 5751416F6141C64A marked as ultimately trusted
gpg: directory '/var/lib/tomcat8/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/var/lib/tomcat8/.gnupg/openpgp-revocs.d/2E1B55F5826A3B1D0A7A85E15751416F6141C64A.rev'
public and secret key created and signed.

pub   rsa3072 2019-05-16 [SC] [expires: 2021-05-15]
      2E1B55F5826A3B1D0A7A85E15751416F6141C64A
uid                      peter <phc@hfht.ca>
sub   rsa3072 2019-05-16 [E] [expires: 2021-05-15]

tomcat8@hfht:~$

To configure OSCAR to use pgpgpg you need to change the oscar.properties file key value to the UID you selected, in the above case you would use:

PGP_KEY: peter <phc@hfht.ca>

Update the location of the keyring and configuration for the tomcat8 user, for the method cited that would be the following.

PGP_ENV: GNUPGHOME=/var/lib/tomcat8/.gnupg

There are many options for encryption and you must balance ease of use and security. Symmetric encryption will assign a password to both encrypt/decrypt the generated file. You can configure that with the following setting (replace the ******* below with a password string)

PGP_CMD: -c --batch --passphrase *****************

To test your configuration you must

1. restart tomcat to apply these property settings
2. define a “demographic set” in Report > Demographic Report Tool
3. export in Administration > Data Management > Demographic Export
4. test decryption of the resultant file

There are many programs that support PGP standards in many operating systems. You can decrypt as your previously configured tomcat8 user on the OSCAR server itself with something similar to:

$ sudo -H -s -u tomcat8
tomcat8@hfhtphd03:~$ tmux
[detached (from session 0)]
tomcat8@hfht:~$ gpg -d export_set1_20190516143152.zip.pgp

You will need to supply the password that you set earlier in oscar.properties

Upgrades and Downgrades

Upgrade OSCAR 19

OSCAR 19 is a rolling release.  You can upgrade simply by running the deb for the version that interests you.  As downgrades to your existing is as easy you can do this with a minimum of paranoia.  Backup

sudo dpkg -i oscar_emr19-98~4831.deb

Downgrades

OSCAR 19 is a rolling release so that stability can fluctuate. If the newer version you install appears unstable you can downgrade the installation by running the older deb to overwrite the new. With OSCAR you used to have to delete the existing oscar.war first to be sure that newer java classes can be replaced with the older ones. This is no longer strictly necessary but remains good form.

sudo rm /var/lib/tomcat8/webapps/oscar.war

then run the older deb over the new one. Note that if you have used a data migration tool in OSCAR 19 you can only go back to OSCAR 18 or newer, there is no going back to OSCAR 15 at that point. If you are on Tomcat 9 you can go back no earlier than oscar_emr19-49~1508.deb (the first to support Tomcat 9).

Upgrade Server

The recommended path is always the same.

1. Upgrade OSCAR to the latest on your existing system
2. If Ubuntu upgrade is desired, do that as a NEW install of both Ubuntu and OSCAR 19 and check that it works on a new server
3. Load the backup onto the new server
4. Transfer any custom oscar.properties to the new server

In theory you can upgrade in place by first upgrading OSCAR to the latest and then upgrading Ubuntu to the desired version. To a certain extent this is advantaged as your data will be migrated to the latest MariaDB without a strict mode restrictions. In practice the changes that the DEB will apply to a new install will be missed. Several suggestions are here to help out those who may try this “easier” but at the risk in the end of being a harder road.

Note that Tomcat 9 is the latest supported Tomcat. Early DEB’s can potentially fail on one or several grounds that have been fixed in current DEBs. If that happens and you need an older DEB the solution may be to install the latest and then downgrade the WAR to the one in the earlier WAR by installing the old DEB over the successfully installed new DEB.

• Database errors. MariaDB 10.3 uses strict mode. Some early databases have definitions that are not supported which may be fixed by running the latest patch.sql
• Cache. OSCAR is huge and requires a lot of caching. Newer debs set context.xml <Resources cacheMaxSize=”102400″ />
• Access to custom directory. To access OSCAR files the tomcat9.service has to have an entry ReadWritePaths=/usr/share/oscar-emr/
  • The tomcat9 config file is located in /etc/default

Removal of OSCAR

Although OSCAR isn’t for everyone, consider asking for help on the mailing list for BC-users (its misnamed) or sending us a note why you are uninstalling it. OSCAR can be removed using dpkg :

sudo dpkg --remove oscar-emr

This will remove the program, but keep the data and configurations.
For complete removal of all sensitive patient data, or just to clear your server for further testing, you need to use purge. Be very careful that you are on the right server and have backups on hand before you run this as it cannot be undone.

sudo dpkg --purge oscar-emr
(Reading database ... 1456783 files and directories currently installed.)
Removing oscar-emr (19-40~1336) ...
Removing drugref.war
Dropping drugref database
Purging configuration files for oscar-emr (19-40~1336) ...
Purging will delete ALL data and settings
***********LAST CHANCE TO SAVE YOUR DATA WITH A CTL-C ************
Now proceeding with Purge
Removing symlinks
Reversing Changes to tomcat9 configuration
grep the password from the properties file
Dropping drugref
Dropping oscar_15
Deleting oscar.properties
Deleting /usr/share/oscar-emr/

Then you clear the deb template that saved your responses for the interactive part of the dpkg install:

echo PURGE | sudo debconf-communicate oscar-emr

 Documentation copyright [c] 2012-2025 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License