Search the OSCAR Documentation
< All Topics

2: OSCAR Install: Finishing Touches

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


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 open source router such as pfSense.


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 users smartphone (something they have).  Starting in OSCAR 19.1 a 2FA.sql script will be set to run for new installs, and be made available for running for upgrades.

First for global control set the key for Time-based One-Time Password TOTP to 1

 For a given user to be able to use 2FA the table will need to have totp_enabled set to 1 and a mime32 encoded secret set.  The following is the setup for an user named oscardoc
MariaDB [oscar_15]> UPDATE security SET totp_enabled=1 WHERE user_name='oscardoc';
MariaDB [oscar_15]> UPDATE security SET totp_secret='ELA3JCFBOSJCGZEF7U2BVSZQQ7VJ4DHOBKWI35K3A3QV26HW' WHERE user_name='oscardoc';
Remember to use this secret, the time period (default 30s) and encryption (default sha1) to set up the Authenticator app on the smart phone (you can use FreeOTP app).
The server side is handled by OATHTOOL
sudo apt-get install oathtool
Ensure that crontab has an appropriate entry for the script that calls oathtool
* * * * * /usr/share/oscar-emr/

Configuring PGP

Generate a key for use in OSCAR for the tomcat8 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.

$ 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
[email protected]:~$ tmux
[detached (from session 0)]

[email protected]:~$ 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: [email protected]
You selected this USER-ID:
"peter <[email protected]>"

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]
uid                      peter <[email protected]>
sub   rsa3072 2019-05-16 [E] [expires: 2021-05-15]

[email protected]:~$

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

PGP_KEY: peter <[email protected]>

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 tomcat8 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
[email protected]:~$ tmux
[detached (from session 0)]
[email protected]:~$ gpg -d

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

Uncomplicated Firewall

The default settings should 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 externally on port 8443, it needs to be open
  • if you are using SSH to access your sever you need to allow your port (usually 22) *before* you enable the firewall
  • 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 settings

sudo ufw status

Upgrades and Downgrades


Migrations from OSCAR 15 use the same syntax for upgrade as for installation and both the program and the database will be updated.  You can do this safely as you will not break your installation.  However as upgrading will occasionally break functionality with a new bug, be prepared to revert by downgrading.  Ensure you have backup in hand (!) and then you can revert to an earlier OSCAR 19 thusly

sudo dpkg -i oscar_emr19beta-1~932.deb

Data Migration OSCAR 15-19

If you are upgrading from OSCAR 15 remember to run the data migration tools in Administration to finish your setup.  Everyone has to run the migrations to Roster Data.

Administration > Updates and Migrations

Only those with pre-existing HRM data need to run the HRM utility.  ONAR migration is a tool for migration from OSCAR 12, you do not need to run.  The DEB will migrate you to the new Contacts interface (the old one is deprecated), do not run the migration utility after a DEB install or you will have duplicate entries!  You will need to upgrade the Roster data.  Do not rush, for even a medium sized clinic these migrations can take over an hour.

Upgrade Roster Data

This utility will migrate OSCAR 15 rostered physician data to the newer OSCAR 19 format (OntarioMD 5.0 CMS standard). This utility will set the Enrolled To Physician to that of MRP for patients where Roster Status was set to ROSTERED.
This is only run once on conversion of an OSCAR 15 system to an OSCAR 19
Allow a coffee break for this to run.  When finished “Upgrade Complete” will display

Migrate HRM

This utility will migrate OSCAR 15 HRM data to the newer OSCAR 19 format. This is only run once on conversion of an OSCAR 15 system to an OSCAR 19. Allow at least an hour for this
when done the “Changes were successful” message will display

Middle Names

In prior versions middle names were often inserted into the first name spot in the master demographic record.  You can migrate them to the middle names section with the following.

First log into MariaDB and clean the data in case end users have  added padding to the first_name

$ sudo mysql -uroot -p
Enter password: 
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 65
Server version: 10.1.34-MariaDB-0ubuntu0.18.04.1 Ubuntu 18.04

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> UPDATE demographic set first_name=TRIM(first_name);

Now extract the second (and further) name for middleNames

UPDATE `demographic` SET `middleNames` = CASE
    WHEN `middleNames`='' OR `middleNames` IS NULL
        THEN If(length(`first_name`) - length(replace(`first_name`, ' ', ''))>0,SUBSTRING_INDEX(`first_name`, ' ',   -length(`first_name`) + length(replace(`first_name`, ' ', ''))), '')
    ELSE `middleNames` END;

Now trim the first_name to just the first

UPDATE demographic SET first_name=If(length(first_name) - length(replace(first_name, ' ', ''))>0,SUBSTRING_INDEX(first_name, ' ', 1) ,first_name);


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 using Java 8 and Tomcat 8.5 you can use a DEB no older than oscar_emr15-88~844.deb.

sudo dpkg -i oscar_emr15-88~844.deb

Removal of OSCAR

Although OSCAR isn’t for everyone, consider asking for help on the sourceforge 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 /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 © 2012-2021 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License

Previous 1: OSCAR Install: Version 19 Installation
Next Backups
Table of Contents