OpenEMR 3.1.0 Appliance Manual

Page Last modified: 08/26/09 03:52:27 AM

LINK TO MANUAL IN PDF FORMAT

Author: Brady Miller

Email: brady@sparmy.com

Discussion Board: http://sourceforge.net/forum/?group_id=60081





Introduction

Main TOC Link

The clinical benefits of computerized medical records are clear, however, the costs of current proprietary systems are large. This high cost precludes many small practices from transitioning to computerized medical records. Open Source medical record systems are quickly becoming a viable, cost effective alternative.

The goal of this project is to maintain a comprehensive Open Source Medical Practice Management Software Appliance, which provides office scheduling, electronic medical records, prescriptions, insurance billing, accounting, and access controls. This appliance has many possible applications, such as a fully functional demo, a testing/developing platform, and as the starting point in real world clinic applications. It can be run on any operating system that supports the VMware Player. The detailed building instructions of this appliance are also included in this manual, which will allow easy modification/updates of appliance and will allow simple transition to a native server, if required.

OpenEMR is installed on the Ubuntu 8.04 Server Edition operating system. For users whom require a GUI desktop, the Ubuntu Server edition OS (8.04) does not come with a desktop, however it is easy to install and is described in this manual. The administration in the Ubuntu Server can be mostly done via Webmin, which is described in this manual.

This manual contains instructions on downloading, starting, and using the OpenEMR Appliance, OpenEMR user manual web links, helpful tips on OpenEMR use, instructions for configuration and administration of the Appliance, and full detailed instructions on how the Appliance was built.

The Download the OpenEMR Appliance and VMware Player chapter contains how and where to download software from.

The Start the OpenEMR Appliance chapter contains information on starting the OpenEMR Appliance.

The Using the OpenEMR Appliance chapter contains information on how to use the OpenEMR Appliance, web links to User Manuals, helpful tips, and all the login names and passwords that will be needed while using the appliance.

The Configuration of the OpenEMR Appliance chapter describes how to configure and administer OpenEMR and the appliance. There are instructions describing how to set up a printer, an email server, and an automated backup scheme. This chapter also describes how to choose the visual layout of OpenEMR and how to add the pharmacy dispensary module along with other instructions on setting up a static IP address, installing a desktop environment, setting the time, changing the password, and safely shutting the appliance down.

The Instructions for Building the OpenEMR Appliance chapter describes in detail how this Appliance was built.

Online Demo

Main TOC Link

Here is the online demo of the OpenEMR 3.1.0 appliance:

With the new frames look:

http://OpenSourceEMR.com:2094/openemr/ (Main OpenEMR program)

This is a fully functional demo, which allows you to play around with all the software packages in the appliance. It uses all the same logins and passwords as the appliance( refer to 'Login Name and Password' section). The OpenEMR users were added to demonstrate the access controls:

-Login name------Password---------Description

1. admin__________pass_____________Administrator

2. physician_______physician________Physician(more access than clinician)

3. clinician________clinician_________Clinician(less access than physician)

4. accountant______accountant______Accountant

5. receptionist_____receptionist_____Front desk receptionist

Don't worry about breaking it, because it resets itself to its original state every day at 9:30AM Pacific Time. Have fun. (If demo is not working email me at brady@sparmy.com)

Download the OpenEMR Appliance and VMware Player

Main TOC Link

1. Download and install the FREE VMware Player at: http://www.vmware.com/products/player/

2. Download the FREE OpenEMR Appliance.
   1. You can download Appliance via Direct Download or Torrent (file is 760MB, which extracts to 2GB):
      1. Direct Download from Sourceforge: http://sourceforge.net/project/showfiles.php?group_id=167832

      2. Torrent file link: http://www.bradymd.com/OpenEMR-3-1-0-appliance-1.torrent (If you need a torrent software client, then try: http://azureus.sourceforge.net/ )

Start the OpenEMR Appliance

Main TOC Link

Windows

Main TOC Link

1. Unpackage the OpenEMR-3-1-0-appliance-1.zip file.

2. Run VMware Player (screenshot below).

3. Start up the OpenEMR Appliance by opening the OpenEMR-3-1-0-appliance-1.vmx file in the VMware Player.

4. If this is your first time starting the OpenEMR Appliance, then a window will pop up (see screenshot below). Select 'I copied it' and click the 'OK' button.

5. Several windows may also pop up explaining that certain drives or sound drivers are not gonna work. Just click 'ok' and continue.

6. Ubuntu will now boot up, just give it some time. After boot up you will see the following introduction screen:

This is the introduction screen. Note that it automatically displays the IP address of your appliance, along with links to OpenEMR and Webmin. These links are customized for you depending on your IP address. The initial important user names and passwords are also displayed. To use appliance, proceed to the 'Using the OpenEMR Appliance' section below.

Linux

Main TOC Link

1. Unpackage the OpenEMR-3-1-0-appliance-1.zip file (use the 'unzip OpenEMR-3-1-0-appliance-1.zip' command).

2. Run VMware Player.

3. Start the OpenEMR appliance by opening the OpenEMR-3-1-0-appliance-1.vmx file in the VMware Player.

4. If this is your first time starting the OpenEMR Appliance, then the below window will pop up:

You will only see this window the first time you start the appliance. Click 'Create'.

5. Several windows may also pop up explaining that certain drives or sound drivers are not gonna work. Just click 'ok' and continue.

6. Ubuntu will now boot up, just give it some time. After boot up you will see the following introduction screen:

address of your appliance, along with links to OpenEMR and Webmin. These links are customized for you depending on your IP address. The initial important user names and passwords are also displayed. To use appliance, proceed to the 'Using the OpenEMR Appliance' section below.

Using the OpenEMR Appliance

Main TOC Link

Using OpenEMR Appliance

Main TOC Link

1. You connect with the OpenEMR Appliance through a web browser. You can get the Appliance IP address along with links to OpenEMR and Webmin on the above introduction screen. Use those links as the web address on another computer's web browser. (If you get a security error in your web browser, then first follow the instructions in below appendix section 'Configuring client web browser for https' to configure your web browser.)

1. OpenEMR at https://Appliance_IP_address/openemr

2. Webmin at https://Appliance_IP_address:10000/

3. For the list of application login names and passwords go to the 'Login Name and Password' section below.

2. You can also change your IP address to a static one, so it doesn't change after your virtual server is turned off or re-started. Directions to to do this are in the 'Static IP Address Setup' section.

OpenEMR User Training

Main TOC Link

1. There is an excellent OpenEMR wiki with user manual links at: http://www.oemr.org/modules/wiwimod/
2. You can ask question at the SourceForge OpenEMR forum at: http://sourceforge.net/forum/?group_id=60081
3. The OpenEMR home page is here: http://www.oemr.org/
4. The most current version of this appliance user manual will hopefully always be available at: http://www.bradymd.com/appliance

Helpful Tips

Main TOC Link

1. NEED to ensure clock is set correctly (Virtual computer time should not differ from the host computers, or there will be cron scheduling problems)

List of Login Names and Passwords

Main TOC Link

1. Ubuntu user -> user: 'openemr' password: 'openemrcool'
2. Ubuntu sudo command -> password: 'openemrcool'
3. Webmin -> user: 'openemr' password: 'openemrcool'
4. OpenEMR -> user: 'admin' password: 'pass'
5. MySQL user -> user: 'openemr' password: 'openemr'
6. MySQL admin -> user: 'root' NO PASSWORD

Configuration of the OpenEMR Appliance

Main TOC Link

OpenEMR Visual Layout Configuration

Main TOC Link

1. OpenEMR has three visual layouts to choose from; the traditional layout, a frames layout with radio buttons, and a frames layout with a tree view menu. We will first show screenshots of the available layouts, and then will show how to configure this option. The default view of OpenEMR 3.1.0 is the tree view.

Traditional view (also called old-style layout).

Frames with navigation by radio buttons.

Frames with navigation by a tree view menu.

2. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then type in your user password):

#edit the file /var/www/openemr/interface/globals.php:

sudo jed /var/www/openemr/interface/globals.php

#change below bolded number to desired layout :

// Set this to 1 or 2 to activate support for the new frame layout.

// 0 = Old-style layout

// 1 = Navigation menu consists of pairs of radio buttons

// 2 = Navigation menu is a tree view

//

$GLOBALS['concurrent_layout'] = 2;

TEXT EDITOR SAVE AND EXIT

Pharmacy Dispensary Module Configuration

Main TOC Link

1. The pharmacy dispensary module will allow you to dispense and keep track of your own med/herbs/supplement dispensary. It will also create bottle labels of the drugs you dispense.
2. Turn on the pharmacy dispensary module in the OpenEMR configuration file. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then type in your user password):

#edit file /var/www/openemr/interface/globals.php:

sudo jed /var/www/openemr/interface/globals.php

#edit the following bolded variable :

$GLOBALS['inhouse_pharmacy'] = true;

TEXT EDITOR SAVE AND EXIT

1. Here are some quick OpenEMR screenshots (note these were taken from version 2.8.3 with the Traditional View) that show how to navigate to the pharmacy dispensary module for administrative purposes:

Click 'Administration'

Click 'Drugs'.

Click 'Add Drug', enter stuff and play around to figure out how to use.

Quick OpenEMR screenshots of prescribing drugs with the dispensary:

Click 'Add Prescription'.

Note the things circled in red, which are part of the pharmacy dispensary module. Note that in version 3.0.1 the 'Prescribe and Dispense' button is now labeled 'Save and Dispense'.

Printer Setup

Main TOC Link

1. For USB printers, you will need to connect the device by clicking on printer on top of window. Your host computer may no longer be able to see the printer after this step(not permanent, but can be a pain).

In this case I click on the 'Hewlett-Packard...' button at top of VMware window.

This is just to demonstrate that the 'Hewlett-Packard...' button is now shaded.

2. Now, you need to add the printer . It would be great if we could add and administer the printer through webmin, but I was unable to get this to work. So we will add a new printer to CUPS directly. To do this, we will actually use a text based browser from the commandline (yes, you are now entering nerd world). Enter below bolded instructions on command line:

#open up web page with text based browser (use up/down arrow keys or 'tab' key to scroll thru links and hit 'enter' key to select a link)

lynx http://localhost:631

Select 'Administration'.

Select 'Find New Printers'. (it will take a bit of time to load next page)

Select the printer you want to add.

Follow instructions to fill out 'Name:', 'Location:', and 'Description:' fields. Then select 'Continue'. (it will take a bit of time to load next page)

Choose the 'Model:' (use right-arrow key to show the menu after you select this field). Then select 'Add printer'. (it will take a bit of time to load next page)

Enter username 'openemr'.

Enter your 'openemr' user password.

Shows printer was successfully added. Type 'q' to quit.

3. Now that the printer has been added, we can print a test page and learn how to administer the printer. Again, it would be great if we could do this through Webmin, but I was unable to get this to work. So we will go back to using CUPS directly through our text-based browser.

#open up web page with text based browser (use up/down arrow keys or 'tab' key to scroll thru links and hit 'enter' key to select a link)

lynx http://localhost:631

Select 'Printers'

Use down arrow key to scroll below the shown printer.

Select 'Print Test Page' (also note all the other administration options in case you need them in the future).

Confirmation of print job is shown. A test page should be sent to your printer. Type 'q' to quit. You are now officially a nerd.

Email Server Setup

Main TOC Link

1. This will allow only locally produced emails (such as “status” emails during the below 'backup script' and emails originating from OpenEMR for appt confirmations) to be sent over the internet.

2. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then type in your user password):

#log into root

sudo aptitude install postfix

-Hit 'tab' key to select 'Ok'.

Select 'Internet Site', then select 'OK'.

Enter the domain name that is put in the from field of your outgoing emails, for example ouroffice.com . (don't worry, this can always be changed after installation). Then select 'OK'.

3. Now we can configure the mail server in Webmin. First we will start the Postfix module in Webmin, and hen we will configure it. Point a web browser outside your appliance to the Webmin link reported in your appliance introduction screen.

(If you are getting a certificate security error, then first follow the instructions in below appendix section 'Configuring client web browser for https' to configure your web browser.)

Login.

Click 'Webmin'.

Click 'Webmin Configuration'

Click 'Webmin Modules'.

Toggle on 'From ftp or http url', then enter 'http://www.webmin.com/updates/postfix-1.450-1.wbm.gz'. Then click 'Install Module'. (We can't use the usual standard postfix module because of a bug in mail aliases).

Confirmed successful installation. Then click 'Postfix Mail Server'.

Click 'General Options'.

Sorry about the poor quality screenshot. Only several changes need to be made here (circled in red), which are all detailed directly below.

1) In 'Send outgoing mail via host', type your outgoing smtp mail server here (this should be given by your internet service provider).

2) In 'Local networks', toggle on 'Default'.

3) In 'Automatic local networks', choose 'Local machine only'.

4) Click the 'Save and Apply' button.

Click 'Mail Aliases'.

Click 'root'.

This is where you can direct all the administrative messages created by your appliance to your email address. Enter your email address in the field circled in red. Then click 'Save'.

It worked, click 'Return to Postfix Configuration' to restart Postfix.

At bottom of page click 'Stop Postfix'.

At bottom of page click 'Start Postfix'.

Click 'Refresh Modules'.

After done, then refresh browser (this will place a postfix link into Webmin's menu in the 'Servers' section).

3. You are now done. For the future you can now get to the postfix configuration menu in Webmin in the 'Servers' section.

Backup (Automatic) Setup

Main TOC Link

1. Automatic backups are extremely important. There are numerous strategies and tools to do this. You can back up the entire appliance (turn it off first), you can use tools in Webmin, or you can use scripts/tools in linux. There is no absolute right way to do it (many administrators will employ more than one mechanism), but you have to do it. Imagine the horror if you walked into your clinic one day, and all of your data was gone. Considering the sensitivity of data, it is also a good idea to consider encryption with some backup schemes. The things that need to be backed up in the OpenEMR 3.0.0 Appliance are the openemr MySQL database and the openemr web directory.

2. The script provided will enable a daily backup of the openemr database in the MySQL server and the OpenEMR web directory. The script will place a non-encrypted backup in the local hard drive secured /backup directory, and will also copy an encrypted backup to a DVD. The DVD copy works via multi-session, so you basically just need to leave one DVD in the DVD writer until it fills up. Do NOT use RW DVD. This script will work and should be used with R only DVD's. The output of the automated backup script will be emailed to the person's email entered in above email server setup.
   1. The local /backup directory will have to be manually cleaned up occasionally. I'd recommend deleting old backup sub-directories on a monthly basis or so. (of course, a script could be written for this)
   2. There is no restore script yet, will have to be done manually.
   3. The MySQL database is gzipped and the OpenEMR web directory is tarred and gzipped.

3. Configure file encryption package:
   1. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then type in your user password):

#Configure file encryption. If you want to be able to decrypt your encrypted files you need to remember (case sensitive) the passphrase that you type below. I'd also remember all the other info you type below.

cd /home/openemr

sudo gpg --gen-key

-'ENTER' to default of 1 for key selection

-'ENTER' to default 2048 keysize bits

-'ENTER' to default '0' so key does not expires

-Type 'Y' to confirm above

-Type your real full name

-Type your real email address

-Type 'openemr secure backup key'

-Type 'O' to confirm

-Type a very secure and long 'passphrase' (the longer your passphrase is the more secure, go for at least 15 characters with numbers, different cases, and strange characters)

#IMPORTANT!!! You NEED to backup the entire contents of directory /home/openemr/.gnupg on the most indestructible disk(s) you can find and then keep in a secure place. This directory contains your secret key file, and without this you will be unable to restore from your encrypted data backup!!! You also need to remember your passphrase, or you won't be able to restore your backed up data.

#The decrypt command, in case you need at some point:

#gpg -o OutputFilename -d InputFilename

4. Configure backup script and automate it:
   1. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then type in your user password):

#install the DVD burner software

sudo aptitude install dvd+rw-tools

-y to packages

#create a secure backup directory

sudo mkdir /backup

sudo chown root:root /backup

sudo chmod 700 /backup

#download and move the backup script to /root , secure it, and allow execution

wget http://www.bradymd.com/fullbackup3.sh

sudo mv fullbackup3.sh /root

sudo chown root:root /root/fullbackup3.sh

sudo chmod 700 /root/fullbackup3.sh

#edit file /root/dailybackup3.sh:

sudo jed /root/fullbackup3.sh

#edit the below DVDDEVICE line to what the

#device for the DVD writer is. In the appliance (3.0.0)

#it should be '/dev/scd0'.

DVDDEVICE=/dev/scd0

#edit full name you entered above for encryption key:

YOURFULLNAME='Brady Miller'

TEXT EDITOR SAVE AND EXIT

#Automate script to cron for a daily run at 1:02 AM. WARNING: This script needs to finish and start on the same day since it plays around with file names using the date command. Basically, don't start this script before midnight unless you are sure it will finish before midnight. This is why I have it set for 1:02AM.

export EDITOR=/usr/bin/jed

sudo crontab -e

#paste below line at end of file (also ensure you add a new line(enter key) after this line):

02 1 * * * /root/fullbackup3.sh

TEXT EDITOR SAVE AND EXIT

Static IP Address Setup

Main TOC Link

1. These are instructions for setting up a static IP address for your appliance using Webmin.

2. First, you should record the required IP addresses (example form below). The 'Appliance IP Address' is going to be the IP address of your appliance (within your network). The 'Subnet Mask' is 255.255.255.0 in most cases. The 'Broadcast IP Address' can be calculated by comparing the 'Appliance IP Address' and the 'Subnet Mask'. For example, if the 'Appliance IP Address' is 192.168.1.114 and the 'Subnet Mask' is 255.255.255.0, then the 'Broadcast IP Address' is 192.168.1.255. There is also a Subnet calculator that can calculate the 'Broadcast IP Address' at http://www.subnet-calculator.com/ . The 'Gateway IP Address' is the IP address of your gateway. The 'DNS server IP Address' entries are the IP addresses of your DNS servers (the DNS server IP addresses are generally supplied by your internet service providers, and there are usually two of them).

Appliance IP Address:_____________________________________________________

Subnet Mask:_____________________________________________________________

Broadcast IP Address:_____________________________________________________

Gateway IP Address:______________________________________________________

DNS server IP Address:___________________________________________________

DNS server IP Address:___________________________________________________

3. Point a web browser outside your appliance to the Webmin link reported in your appliance introduction screen.

(If you are getting a certificate security error, then first follow the instructions in below appendix section 'Configuring client web browser for https' to configure your web browser.)

Login.

Click 'Networking'.

Click 'Network Configuration'.

Click 'Network Interfaces'.

Click the 'Activated at Boot' tab.

Click 'eth0'.

1) Toggle on 'Static configuration'.

2) Enter 'Appliance IP Address' into 'IP Address' field.

3) Enter 'Subnet Mask' into 'Netmask' field.

4) Enter 'Broadcast IP Address' into 'Broadcast' field.

5) Click 'Save'.

Click 'Return to network configuration'.

Click 'Routing and Gateways'.

1) Toggle on 'Gateway'

2) Enter the 'Gateway IP Address' into 'Gateway' field

3) Click 'Save'.

Click 'Hostname and DNS client'.

Enter the 'DNS server IP Address' values into the 'DNS servers' fields, then click 'Save'.

Click 'System Information'.

4. Then reboot the appliance per the instructions found in the 'Reboot or Shutdown Appliance' section.

Change Clock

Main TOC Link

1. These are instructions on changing the time in your appliance using Webmin.

2. Point a web browser outside your appliance to the Webmin link reported in your appliance introduction screen.

(If you are getting a certificate security error, then first follow the instructions in below appendix section 'Configuring client web browser for https' to configure your web browser.)

Login.

Click 'Hardware'.

Click 'System Time'.

Set the time and timezone of your appliance here. Do NOT set up a 'time server sync'; this will screw up your appliance.

Change Appliance Password

Main TOC Link

1. These are instructions for changing the password to the 'openemr' user in your appliance using Webmin. This is important to secure your appliance. It will effectively change the 'openemr' user password for logging into Webmin, logging into your appliance's commandline, and to confirm usage of the 'sudo' command.

2. Point a web browser outside your appliance to the Webmin link reported in your appliance introduction screen.

(If you are getting a certificate security error, then first follow the instructions in below appendix section 'Configuring client web browser for https' to configure your web browser.)

Login.

Click 'System'

Click 'Change Passwords'.

Click 'openemr'.

Type and confirm new password, then click 'change'

Reboot or Shutdown Appliance

Main TOC Link

1. These are instructions on how to shutdown or restart your appliance using Webmin.

2. Point a web browser outside your appliance to the Webmin link reported in your appliance introduction screen.

(If you are getting a certificate security error, then first follow the instructions in below appendix section 'Configuring client web browser for https' to configure your web browser.)

Login.

Click 'System'.

Click 'Bootup and Shutdown'.

Scroll to bottom of page. To reboot your appliance, click the 'Reboot System' button. To shutdown your appliance, click the 'Shutdown System' button. You will be asked to confirm this on the next screen.

Desktop Installation

Main TOC Link

1. This is for those wimps whom are having difficulty with administration of the appliance via commandline and/or Webmin. These are instructions to install the KDE desktop (includes all the thrills such as OpenOffice etc.) on your appliance. This will increase the size of your appliance by 1.6 GB.

2. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then type in your user password):

#install kubuntu desktop

sudo apt-get install kubuntu-desktop

-enter Y to continue

-(this will take awhile)

#install the x-windows manager and start it

sudo apt-get install gdm

-enter Y to continue

-enter 'ok'

-select 'kdm'

#restart computer (will now boot into the KDE desktop)

sudo shutdown -r now

Instructions for Building the OpenEMR Appliance

Main TOC Link

LINK TO MANUAL IN PDF FORMAT

Software

Main TOC Link

Chapter Index Link

1. Ubuntu Server Edition (8.04)
2. Apache (2.2.8), MySQL (5.0.51a), and PHP (5.2.4)
3. Webmin (1.470)
4. OpenEMR (3.0.1 and 3.1.0)

Install the Ubuntu 8.04 Server Virtual Computer

Main TOC Link

Chapter Index Link

1. You can use either VMware Workstation or VMware Server to build the Ubuntu 8.04 Server Appliance.
2. Download Ubuntu Server Edition 8.04 installation ISO file from http://www.ubuntu.com/getubuntu/download .
3. Ubuntu Server Edition 8.04 Appliance Installation with Vmware Workstation version 6.5:

Click 'New Virtual Machine'.

Select 'Typical', then Click 'Next'.

Browse and select ubuntu-8.04.2-server-i386.iso file, then click 'Next'.

Type in name of appliance and location to save it to, then click 'Next'. I typed OpenEMR-3-0-1-appliance-1.

Set maximum disk size to 80GB, select 'Split virtual disk into 2GB files', then click 'Next'.

Click 'Customize Hardware...'.

Click 'Network Adapter'.

Select 'Bridged: Connected directly to the physical network' and check 'Replicate physical network connection state', then click 'OK'.

Click 'Finish'.

Click 'Power on this virtual machine'.

Select language.

Select 'Install Ubuntu Server'.

Select language.

Select country.

Select 'Yes' to detect keyboard layout.

Go through bunch of screens like above to figure out keyboard.

Select 'Continue' if detected correct keyboard.

Type 'openemr' for Hostname, and then 'Continue'.

Select time zone, I chose 'Pacific'.

Select 'Guided - use entire disk'.

Select the highlighted disk.

Select 'Yes'.

Type 'Openemr Appliance', then 'Continue'.

Type 'openemr', then 'Continue'.

Choose a password. I typed 'openemrcool' for password, then 'Continue'.

Confirm password 'openemrcool', then 'Continue'.

Leave blank and 'Continue'.

Select 'LAMP server', 'OpenSSH server', and 'Print Server'; then click 'Continue'.

Leave blank and 'Continue'.

Leave blank and 'Continue'.

Leave blank and 'Continue'.

Click 'Continue'.

login with user:openemr pass:openemrcool

4. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then use 'openemrcool'):

#update and upgrade ubuntu

sudo apt-get update

sudo apt-get upgrade

-enter Y to continue

#Install the php command line, imagemagick, lynx client browser, and jed text editor.

sudo aptitude install jed lynx php5-cli imagemagick

-enter Y to continue

#get packages required by Vmware Tools

sudo aptitude install build-essential linux-headers-$(uname -r)

-enter Y to continue

5. Prepare to install Vmware Tools:

Click 'VM' in top menu, and select 'Install VMware Tools...'.

6. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then use 'openemrcool'):

#mount the vmware drive

sudo mkdir /mnt/temp

sudo mount /dev/cdrom /mnt/temp

#get and unpackage vmware tools

cp /mnt/temp/VMwareTools-*.tar.gz .

tar -zxpf VMwareTools-*.tar.gz

#install Vmware Tools

cd vmware-tools-distrib

sudo ./vmware-install.pl

-hit 'enter' to select default for all questions

#clean up files

cd ..

rm -f VMwareTools-*.tar.gz

rm -fr vmware-tools-distrib

#unmount the vmware drive

sudo umount /dev/cdrom

sudo rm -fr /mnt/temp

Configure PHP and Apache (with SSL)

Main TOC Link

Chapter Index Link

1. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then use 'openemrcool'):

sudo jed /etc/php5/apache2/php.ini

#edit following variables:

short_open_tag = On

max_execution_time = 60

max_input_time = 90

memory_limit = 128M

display_errors = Off

log_errors = On

register_globals = Off

post_max_size = 30M

magic_quotes_gpc = On

file_uploads = On

upload_max_filesize = 30M

TEXT EDITOR SAVE AND EXIT

sudo jed /etc/apache2/apache2.conf

#Paste below to end of file:

<Directory "/var/www/openemr/documents">

order deny,allow

Deny from all

</Directory>

<Directory "/var/www/openemr/edi">

order deny,allow

Deny from all

</Directory>

<Directory "/var/www/openemr/era">

order deny,allow

Deny from all

</Directory>

TEXT EDITOR SAVE AND EXIT

#create an SSL certificate

sudo openssl req $@ -new -x509 -days 1825 -nodes -out /etc/apache2/apache.pem -keyout /etc/apache2/apache.pem

-ok to just select all defaults

#configure SSL in apache2

sudo a2enmod ssl

sudo cp /etc/apache2/sites-available/default /etc/apache2/sites-available/ssl

sudo ln -s /etc/apache2/sites-available/ssl /etc/apache2/sites-enabled/

#edit file /etc/apache2/sites-available/default

sudo jed /etc/apache2/sites-available/default

#Edit first two lines of file:

NameVirtualHost *:80

<VirtualHost *:80>

TEXT EDITOR SAVE AND EXIT

#edit file /etc/apache2/sites-available/default

sudo jed /etc/apache2/sites-available/ssl

#Edit first two lines of file:

NameVirtualHost *:443

<VirtualHost *:443>

#Insert the below code right above the 'Loglevel warn' line:

SSLEngine on

SSLCertificateFile /etc/apache2/apache.pem

TEXT EDITOR SAVE AND EXIT

#edit file /etc/apache2/mods-available/ssl.conf

sudo jed /etc/apache2/mods-available/ssl.conf

#Uncomment the following lines (near end of file):

SSLCipherSuite HIGH:MEDIUM:!ADH

SSLProtocol all -SSLv2

TEXT EDITOR SAVE AND EXIT

#restart apache

sudo /etc/init.d/apache2 restart

-do not worry about the domain name messages

Install OpenEMR 3.0.1

Main TOC Link

Chapter Index Link

1. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then use 'openemrcool'):

#Download OpenEMR

wget http://downloads.sourceforge.net/openemr/openemr-3.0.1.tar.gz

#Put the OpenEMR program in its place

sudo tar -pxzvf openemr-3.0.1.tar.gz

sudo rm -f openemr-3.0.1.tar.gz

sudo mv openemr-3.0.1 /var/www/openemr

sudo chown -R root:root /var/www/openemr

#Deal with file permissions

sudo chmod 666 /var/www/openemr/library/sqlconf.php

sudo chmod 666 /var/www/openemr/interface/globals.php

sudo chmod 666 /var/www/openemr/gacl/gacl.ini.php

sudo chmod 666 /var/www/openemr/gacl/gacl.class.php

sudo chown -R www-data:www-data /var/www/openemr/documents

sudo chown -R www-data:www-data /var/www/openemr/edi

sudo chown -R www-data:www-data /var/www/openemr/era

sudo chown -R www-data:www-data /var/www/openemr/custom/letter_templates

sudo chown -R www-data:www-data /var/www/openemr/gacl/admin/templates_c

sudo chown -R www-data:www-data /var/www/openemr/library/freeb

sudo chown -R www-data:www-data /var/www/openemr/interface/main/calendar/modules/PostCalendar/pntemplates/cache

sudo chown -R www-data:www-data /var/www/openemr/interface/main/calendar/modules/PostCalendar/pntemplates/compiled

sudo ifconfig

-Look at screenshot below to get IP address

The location where you will find the IP address of your appliance is circled in red above.

3. Now, open a webbrowser outside the appliance and point to (the APPLIANCE_IP_ADDRESS was found by above ifconfig command):

   https://APPLIANCE_IP_ADDRESS/openemr/setup.php

(If you are getting a certificate security error, then first follow the instructions in below appendix section 'Configuring client web browser for https' to configure your web browser.)

Click 'Continue'.

Select 'Have setup create the database', then click 'Continue'.

For my appliance I typed 'openemr' into 'Password' field, and otherwise kept defaults. Click 'Continue'.

Click 'Continue'.

Click 'Continue'.

We have already configured this in the above 'Configure PHP and Apache (with SSL)' section. Click 'Continue'.

We have already configured this in the above 'Configure PHP and Apache (with SSL)' section. Click 'Continue'.

Click 'Click here to start using OpenEMR' to go to OpenEMR.

Continue to below instructions.

3. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then use 'openemrcool'):

#Re-secure files

sudo chmod 644 /var/www/openemr/library/sqlconf.php

sudo chmod 644 /var/www/openemr/interface/globals.php

sudo chmod 644 /var/www/openemr/gacl/gacl.ini.php

sudo chmod 644 /var/www/openemr/gacl/gacl.class.php

Install and Configure Webmin

Main TOC Link

Chapter Index Link

1. Webmin is an awesome way to administer a ubuntu server with a graphical interface remotely.

2. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then use 'openemrcool'):

#download Webmin

wget http://prdownloads.sourceforge.net/webadmin/webmin_1.470_all.deb

#install Webmin

sudo dpkg -i webmin_1.470_all.deb

-IGNORE the dependency errors (below command will install)

sudo apt-get install -f

-enter 'Y' to continue

rm -f webmin_1.470_all.deb

1. Now, open a webbrowser outside the appliance and point to (the APPLIANCE_IP_ADDRESS was found by above ifconfig command):

   https://APPLIANCE_IP_ADDRESS:10000/

(If you are getting a certificate security error, then first follow the instructions in below appendix section 'Configuring client web browser for https' to configure your web browser.)

Login with user:'openemr' and pass:'openemrcool'.

Click 'Install Updates Now' button.

Scroll to bottom of window and click 'Return to Webmin configuration'.

Click 'Logout'.

Configure Firewall

Main TOC Link

Chapter Index Link

1. We will only allow access to the appliance through ports 22 (SSH), 443 (OpenEMR via https), and 10000 (Webmin via https). Note that we are blocking the http port (80) to force users to use https (encrypted) when connecting to OpenEMR.

2. Open a webbrowser outside the appliance and point to (the APPLIANCE_IP_ADDRESS was found by above ifconfig command):

   https://APPLIANCE_IP_ADDRESS:10000/

(If you are getting a certificate security error, then first follow the instructions in below appendix section 'Configuring client web browser for https' to configure your web browser.)

Login with user:'openemr' and pass:'openemrcool'.

Click 'Networking'.

Click 'Linux Firewall'.

Select 'Block all except SSH and IDENT on external interface'. Select the 'eth0' interface from the menu next to this. Toggle on the 'Enable firewall at boot time?'. Then click the 'Setup Firewall' button.

Select the line circled in red above. Then click the 'Delete Selected button.

Click the 'Add Rule' button circled in red above.

All places that require input are circled in red. Type 'SSL' in 'Rule comment'. Toggle on the 'Accept' in 'Action to take'. In 'Network protocol', select 'Equals'. In 'Destination TCP or UDP port', select 'Equals' and type '443' for 'Port(s). Then click the 'Create' button.

Click the 'Add Rule' button circled in red above.

All places that require input are circled in red. Type 'webmin' in 'Rule comment'. Toggle on the 'Accept' in 'Action to take'. In 'Network protocol', select 'Equals'. In 'Destination TCP or UDP port', select 'Equals' and type '10000' for 'Port(s). Then click the 'Create' button.

Click the 'Apply Configuration' button.

Click 'Logout'.

Finishing Touches On Appliance

Main TOC Link

Chapter Index Link

1. We will install a startup/shutdown script. On startup it will configure the introductory screen to give the user required information (IP address, login names/passwords, etc.). On shutdown it will reset the network card to ensure mobility of the virtual appliance.

2. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then use 'openemrcool'):

#download the script

sudo wget http://www.bradymd.com/openemrApplianceScript

#install the script

sudo mv openemrApplianceScript /etc/init.d/

sudo chown root:root /etc/init.d/openemrApplianceScript

sudo chmod +x /etc/init.d/openemrApplianceScript

sudo update-rc.d openemrApplianceScript defaults 99

#shutdown the appliance

sudo shutdown -h now

1. In Vmware, need to set the CD/DVD drive to autoset.

Double-click 'CD/DVD (IDE)'.

Select 'Use physical drive' and select 'Auto Detect' from menu. Then click 'OK'.

1. Because this appliance was built with Vmware Workstation 6.5, we now need to convert the appliance to an earlier version to ensure compatibility with all Vmware Player and Vmware Server versions. This is done with free software by Vmware, called 'VMware vCenter Converter Standalone Client'.
   1. Ensure Vmware Workstation is closed.

2. Download, install, and start the 'Vmware vCenter Converter Standalone Client' from vmware.com (it is free).

Click 'Convert Machine'.

Click 'Select source type:' field.

Select 'VMware workstation or other VMware virtual machine'.

Select the 'virtual machine file:', then click 'Next'.

Click 'Select VMware product:' field.

Select 'VMware Workstation 5.x'.

Click 'Next'.

Click the 'Data to copy' field.

Select '2 GB split not pre-allocated', then click 'Next'.

Click 'Finish'.

Upgrading to OpenEMR 3.1.0

Main TOC Link

Chapter Index Link

1. Enter below bolded instructions on command line (if prompted to give password during the sudo command, then use 'openemrcool'):

#Download openemr-3.1.0.tar.gz (version 3.1.0)

wget downloads.sourceforge.net/openemr/openemr-3.1.0.tar.gz

#install php5-gd package

sudo aptitude update

sudo aptitude install php5-gd

-enter 'Y'

-enter 'Y'

#make backup directories

sudo mkdir /backupopenemr

sudo mkdir /backupopenemr/3_0_1

#Backup the mysql openemr database into backup directory.

sudo mkdir /backupopenemr/3_0_1/mysqldatabase

sudo sh -c 'mysqldump openemr > /backupopenemr/3_0_1/mysqldatabase/mysql_backup.sql'

#move old OpenEMR 3.0.1 to the backup directory

sudo mv /var/www/openemr /backupopenemr/3_0_1/openemr

#put the new OpenEMR 3.1.0 program in its place

cd /var/www

sudo tar pxzvf /location/to/tar/openemr-3.1.0.tar.gz

sudo mv openemr-3.1.0 /var/www/openemr

#secure OpenEMR

sudo chown -Rf root:root openemr

# Restore some original directories

sudo cp -fr /backupopenemr/3_0_1/openemr/documents /var/www/openemr/

sudo cp -fr /backupopenemr/3_0_1/openemr/era /var/www/openemr/

sudo cp -fr /backupopenemr/3_0_1/openemr/edi /var/www/openemr/

sudo cp -fr /backupopenemr/3_0_1/openemr/custom/letter_templates /var/www/openemr/custom

#Need to change some file/folder permissions

sudo chown -R www-data:www-data /var/www/openemr/documents

sudo chown -R www-data:www-data /var/www/openemr/edi

sudo chown -R www-data:www-data /var/www/openemr/era

sudo chown -R www-data:www-data /var/www/openemr/custom/letter_templates

sudo chown -R www-data:www-data /var/www/openemr/gacl/admin/templates_c

sudo chown -R www-data:www-data /var/www/openemr/library/freeb

sudo chown -R www-data:www-data /var/www/openemr/interface/main/calendar/modules/PostCalendar/pntemplates/cache

sudo chown -R www-data:www-data /var/www/openemr/interface/main/calendar/modules/PostCalendar/pntemplates/compiled

#Now for the hardest part of the upgrade; editing the new config files. There are three files that need to be compared to your old config files:

openemr/library/sqlconf.php: Ensure the variables ($host, $port, $login, $pass, $dbase) at top of file are the same as the variables from previous 3.0.1 version. Also, change the $config variable (found near bottom of file within all the slashes) to $config = 1;

openemr/interface/globals.php: Ensure the variables ($webserver_root, $web_root) at top of file are the same as the variables from previous 3.0.1 version. Also ensure optional settings are configured like previous 3.0.1 version.

openemr/includes/config.php: Ensure optional settings are configured like previous 3.0.1 version.

For the openemr 3.0.1/3.1.0 appliance, luckily, only one change is required in /var/www/openemr/library/sqlconf.php .

#edit file /var/www/openemr/library/sqlconf.php:

sudo jed /var/www/openemr/library/sqlconf.php

#edit the following bolded $config variable:

//////DO NOT TOUCH THIS///

$config = 1; /////////////

//////////////////////////

TEXT EDITOR SAVE AND EXIT

3. Next, need to upgrade the mysql database. Now, open a webbrowser outside the appliance and point to (the APPLIANCE_IP_ADDRESS was found by above ifconfig command):

   https://APPLIANCE_IP_ADDRESS/openemr/sql_upgrade.php

Select '3.0.1' and click 'Upgrade Database'.

Ensure you got no errors. Close the window.

3. Next, need to upgrade the php-GACL access controls. Open a webbrowser outside the appliance and point to (the APPLIANCE_IP_ADDRESS was found by above ifconfig command):

   https://APPLIANCE_IP_ADDRESS/openemr/acl_upgrade.php

Ensure you got no 'ERRORS'. Close the window.

3. Secure openemr . Enter below bolded instructions on command line (if prompted to give password during the sudo command, then use 'openemrcool'):

sudo chmod 600 /var/www/openemr/acl_setup.php

sudo chmod 600 /var/www/openemr/acl_upgrade.php

sudo chmod 600 /var/www/openemr/sl_convert.php

sudo chmod 600 /var/www/openemr/setup.php

sudo chmod 600 /var/www/openemr/sql_upgrade.php

sudo chmod 600 /var/www/openemr/gacl/setup.php

Upgrade Database to UTF-8

Main TOC Link

Chapter Index Link

OpenEMR 3.1.0 is 100% UTF-8 compliant to allow special character languages (such as chinese, greek, etc.), however users that are upgrading from a previous version of OpenEMR will continue to have a hybrid UTF-8/latin1 database and thus won't have 100% UTF-8 compliance. Several ways to go for upgraders:

(If decide to convert to UTF8, ensure you backup the database before conversion.)

1) If your only using english characters currently and plan on only using English characters in the future, then doing a simple OpenEMR upgrade will suffice (no need to convert to database to 100% UTF-8).

2) If your only using english characters, however, plan to use a language with any special non-english characters in the future, then you should consider converting your database to 100% UTF-8. In this special case (since you were only using english characters previously) then a simple conversion will work. So, you would do the simple OpenEMR upgrade discussed elsewhere and then do following two command line commands on your upgraded database (assuming database name is openemr):

Step1) mysql --database=openemr -B -N -e "SHOW TABLES" | awk '{print "ALTER TABLE", $1, "CONVERT TO CHARACTER SET utf8;"}' | mysql --database=openemr &

Step2) mysql -e "ALTER DATABASE openemr CHARACTER SET utf8;"

(NOTE that above will alter your database and could possibly screw it up, so BACK IT UP first)

3) If your currently using non-english characters, and want to continue supporting non-english characters. This is the hard one, because OpenEMR's previous releases did not do a very good job maintaining consistent encoding in the database (a very common problem in other software also). You could try above strategy in number 2, however you have a possibility of getting garbage. If 2) doesn't work, then you will likely need to go a strategy like the following linked below:

http://codex.wordpress.org/Converting_Database_Character_Sets

To repeat:

---This only pertains to users that are upgrading (users that are installing 3.1.0 new do not need to worry about this stuff)

---Upgraders that are only planning to use english characters do not need to worry about this stuff. (unless you want to be cool, and say your using OpenEMR with 100% compliance...)

For the appliance upgrade, I will convert via step 2 (since there is no data in the blank appliance, it is straighforward). Enter below bolded instructions on command line (if prompted to give password during the sudo command, then use 'openemrcool'):

sudo mysql --database=openemr -B -N -e "SHOW TABLES" | awk '{print "ALTER TABLE", $1, "CONVERT TO CHARACTER SET utf8;"}' | sudo mysql --database=openemr &

sudo mysql -e "ALTER DATABASE openemr CHARACTER SET utf8;"

Upgrade Language Translation Tables

Main TOC Link

Chapter Index Link

Here we will upgrade to the language translation tables published with OpenEMR 3.1.0 . This is very simple to do. Note, however, that this will delete all current local language translation tables.

1. Download translation sql tables from sourceforge to desktop (via 'File'->'Save Page as'): http://openemr.cvs.sourceforge.net/viewvc/openemr/openemr/contrib/util/language_translations/currentLanguage_utf8.sql?revision=1.11.2.6

1. Login to OpenEMR:

Login.

Click 'Administration'->'Other'->'Database' from left tree menu.

Click 'openemr' database link near top left (highlighted by arrow).

Click 'Import' near top right (highlighted by arrow).

Click 'Browse' (highlighted by arrow).

Select the 'currentLanguage_utf8.sql' file that you downloaded in above first step, and click 'Open'.

Click 'Go' at bottom right (highlighted by arrow). After click, the import can take up to a minute or so.

After import is done, you should see the above yellow banner stating the import has been successfully finished.

ALL DONE

Appendix

Main TOC Link

A. Configuring client web browser for https

Main TOC Link

1. For security, this appliance forces users to use https (encrypted) over a web browser. Because we are using a homemade security certificate (real certificates cost money), most new web browsers will give a security error. This can easily be dealt with by following the browser instructions to create an exception. I have posted steps for both Firefox and Internet Explorer.

Click 'Or you can add an exception...'.

Click the 'Add Exception...' button.

Click the 'Get Certificate' button. (DO NOT edit the 'Location:')

Click 'Confirm Security Exception'. Ensure 'Permanently store this exception' is checked, so you don't have to go through this every time. Also, DO NOT change 'Location:'.

ALL DONE, go back and continue your previous instructions.

Click 'Continue to this website'.

ALL DONE, go back and continue your previous instructions.

B. Useful Websites

Main TOC Link

OpenEMR links:

1. http://www.oemr.org/ (Main OpenEMR website with a good Wiki and a new forum)

2. http://sourceforge.net/projects/openemr/ (Main OpenEMR forums are here)

3. http://www.bradymd.com/appliance/ (OpenEMR Virtual Appliance Homepage)

Virtual Machine links:

1. http://www.vmware.com/ (VMware website)

2. http://www.vmware.com/appliances/ (VMware virtual appliance explanation)

3. http://www.vmware.com/vmtn/appliances/overview.html (Another VMware virtual appliance explanation)

General EMR links:

1. http://www.linuxmednews.com/ (Open Source EMR news)

2. http://www.emrupdate.com/ (Great site and forums which discusses proprietary and open source EMRs. It also has a great actively updated price comparison for most proprietary EMR's)

3. http://ehr.gplmedicine.org/ (Great detailed reviews of OpenEMR, MirrorMed, and FreeMed)

4. http://www.bradymd.com/ (Installation instructions and quick reviews of OpenEMR, MirrorMed, FreeMed, and VistA.)

C. Author Email and License/Disclaimer

Main TOC Link

Author: Brady Miller

Email:brady@sparmy.com

www.bradymd.com

Copyright (C) <2006-2009> <Brady Miller>

This program is free software; you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

the Free Software Foundation; either version 2 of the License, or

(at your option) any later version.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

GNU General Public License for more details.

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.

51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Everyone is permitted to copy and distribute verbatim copies

of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your

freedom to share and change it. By contrast, the GNU General Public

License is intended to guarantee your freedom to share and change free

software--to make sure the software is free for all its users. This

General Public License applies to most of the Free Software

Foundation's software and to any other program whose authors commit to

using it. (Some other Free Software Foundation software is covered by

the GNU Lesser General Public License instead.) You can apply it to

your programs, too.

When we speak of free software, we are referring to freedom, not

price. Our General Public Licenses are designed to make sure that you

have the freedom to distribute copies of free software (and charge for

this service if you wish), that you receive source code or can get it

if you want it, that you can change the software or use pieces of it

in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid

anyone to deny you these rights or to ask you to surrender the rights.

These restrictions translate to certain responsibilities for you if you

distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether

gratis or for a fee, you must give the recipients all the rights that

you have. You must make sure that they, too, receive or can get the

source code. And you must show them these terms so they know their

rights.

We protect your rights with two steps: (1) copyright the software, and

(2) offer you this license which gives you legal permission to copy,

distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain

that everyone understands that there is no warranty for this free

software. If the software is modified by someone else and passed on, we

want its recipients to know that what they have is not the original, so

that any problems introduced by others will not reflect on the original

authors' reputations.

Finally, any free program is threatened constantly by software

patents. We wish to avoid the danger that redistributors of a free

program will individually obtain patent licenses, in effect making the

program proprietary. To prevent this, we have made it clear that any

patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and

modification follow.

GNU GENERAL PUBLIC LICENSE

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License applies to any program or other work which contains

a notice placed by the copyright holder saying it may be distributed

under the terms of this General Public License. The "Program", below,

refers to any such program or work, and a "work based on the Program"

means either the Program or any derivative work under copyright law:

that is to say, a work containing the Program or a portion of it,

either verbatim or with modifications and/or translated into another

language. (Hereinafter, translation is included without limitation in

the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not

covered by this License; they are outside its scope. The act of

running the Program is not restricted, and the output from the Program

is covered only if its contents constitute a work based on the

Program (independent of having been made by running the Program).

Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's

source code as you receive it, in any medium, provided that you

conspicuously and appropriately publish on each copy an appropriate

copyright notice and disclaimer of warranty; keep intact all the

notices that refer to this License and to the absence of any warranty;

and give any other recipients of the Program a copy of this License

along with the Program.

You may charge a fee for the physical act of transferring a copy, and

you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion

of it, thus forming a work based on the Program, and copy and

distribute such modifications or work under the terms of Section 1

above, provided that you also meet all of these conditions:

a) You must cause the modified files to carry prominent notices

stating that you changed the files and the date of any change.

b) You must cause any work that you distribute or publish, that in

whole or in part contains or is derived from the Program or any

part thereof, to be licensed as a whole at no charge to all third

parties under the terms of this License.

c) If the modified program normally reads commands interactively

when run, you must cause it, when started running for such

interactive use in the most ordinary way, to print or display an

announcement including an appropriate copyright notice and a

notice that there is no warranty (or else, saying that you provide

a warranty) and that users may redistribute the program under

these conditions, and telling the user how to view a copy of this

License. (Exception: if the Program itself is interactive but

does not normally print such an announcement, your work based on

the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If

identifiable sections of that work are not derived from the Program,

and can be reasonably considered independent and separate works in

themselves, then this License, and its terms, do not apply to those

sections when you distribute them as separate works. But when you

distribute the same sections as part of a whole which is a work based

on the Program, the distribution of the whole must be on the terms of

this License, whose permissions for other licensees extend to the

entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest

your rights to work written entirely by you; rather, the intent is to

exercise the right to control the distribution of derivative or

collective works based on the Program.

In addition, mere aggregation of another work not based on the Program

with the Program (or with a work based on the Program) on a volume of

a storage or distribution medium does not bring the other work under

the scope of this License.

3. You may copy and distribute the Program (or a work based on it,

under Section 2) in object code or executable form under the terms of

Sections 1 and 2 above provided that you also do one of the following:

a) Accompany it with the complete corresponding machine-readable

source code, which must be distributed under the terms of Sections

1 and 2 above on a medium customarily used for software interchange; or,

b) Accompany it with a written offer, valid for at least three

years, to give any third party, for a charge no more than your

cost of physically performing source distribution, a complete

machine-readable copy of the corresponding source code, to be

distributed under the terms of Sections 1 and 2 above on a medium

customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer

to distribute corresponding source code. (This alternative is

allowed only for noncommercial distribution and only if you

received the program in object code or executable form with such

an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for

making modifications to it. For an executable work, complete source

code means all the source code for all modules it contains, plus any

associated interface definition files, plus the scripts used to

control compilation and installation of the executable. However, as a

special exception, the source code distributed need not include

anything that is normally distributed (in either source or binary

form) with the major components (compiler, kernel, and so on) of the

operating system on which the executable runs, unless that component

itself accompanies the executable.

If distribution of executable or object code is made by offering

access to copy from a designated place, then offering equivalent

access to copy the source code from the same place counts as

distribution of the source code, even though third parties are not

compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program

except as expressly provided under this License. Any attempt

otherwise to copy, modify, sublicense or distribute the Program is

void, and will automatically terminate your rights under this License.

However, parties who have received copies, or rights, from you under

this License will not have their licenses terminated so long as such

parties remain in full compliance.

5. You are not required to accept this License, since you have not

signed it. However, nothing else grants you permission to modify or

distribute the Program or its derivative works. These actions are

prohibited by law if you do not accept this License. Therefore, by

modifying or distributing the Program (or any work based on the

Program), you indicate your acceptance of this License to do so, and

all its terms and conditions for copying, distributing or modifying

the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the

Program), the recipient automatically receives a license from the

original licensor to copy, distribute or modify the Program subject to

these terms and conditions. You may not impose any further

restrictions on the recipients' exercise of the rights granted herein.

You are not responsible for enforcing compliance by third parties to

this License.

7. If, as a consequence of a court judgment or allegation of patent

infringement or for any other reason (not limited to patent issues),

conditions are imposed on you (whether by court order, agreement or

otherwise) that contradict the conditions of this License, they do not

excuse you from the conditions of this License. If you cannot

distribute so as to satisfy simultaneously your obligations under this

License and any other pertinent obligations, then as a consequence you

may not distribute the Program at all. For example, if a patent

license would not permit royalty-free redistribution of the Program by

all those who receive copies directly or indirectly through you, then

the only way you could satisfy both it and this License would be to

refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under

any particular circumstance, the balance of the section is intended to

apply and the section as a whole is intended to apply in other

circumstances.

It is not the purpose of this section to induce you to infringe any

patents or other property right claims or to contest validity of any

such claims; this section has the sole purpose of protecting the

integrity of the free software distribution system, which is

implemented by public license practices. Many people have made

generous contributions to the wide range of software distributed

through that system in reliance on consistent application of that

system; it is up to the author/donor to decide if he or she is willing

to distribute software through any other system and a licensee cannot

impose that choice.

This section is intended to make thoroughly clear what is believed to

be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in

certain countries either by patents or by copyrighted interfaces, the

original copyright holder who places the Program under this License

may add an explicit geographical distribution limitation excluding

those countries, so that distribution is permitted only in or among

countries not thus excluded. In such case, this License incorporates

the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions

of the General Public License from time to time. Such new versions will

be similar in spirit to the present version, but may differ in detail to

address new problems or concerns.

Each version is given a distinguishing version number. If the Program

specifies a version number of this License which applies to it and "any

later version", you have the option of following the terms and conditions

either of that version or of any later version published by the Free

Software Foundation. If the Program does not specify a version number of

this License, you may choose any version ever published by the Free Software

Foundation.

10. If you wish to incorporate parts of the Program into other free

programs whose distribution conditions are different, write to the author

to ask for permission. For software which is copyrighted by the Free

Software Foundation, write to the Free Software Foundation; we sometimes

make exceptions for this. Our decision will be guided by the two goals

of preserving the free status of all derivatives of our free software and

of promoting the sharing and reuse of software generally.

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY

FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN

OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES

PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED

OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS

TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE

PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,

REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING

WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR

REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,

INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING

OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED

TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY

YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER

PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE

POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest

possible use to the public, the best way to achieve this is to make it

free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest

to attach them to the start of each source file to most effectively

convey the exclusion of warranty; and each file should have at least

the "copyright" line and a pointer to where the full notice is found.

<one line to give the program's name and a brief idea of what it does.>

Copyright (C) <year> <name of author>

This program is free software; you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

the Free Software Foundation; either version 2 of the License, or

(at your option) any later version.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

GNU General Public License for more details.

You should have received a copy of the GNU General Public License

along with this program; if not, write to the Free Software

Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this

when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) year name of author

Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.

This is free software, and you are welcome to redistribute it

under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate

parts of the General Public License. Of course, the commands you use may

be called something other than `show w' and `show c'; they could even be

mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your

school, if any, to sign a "copyright disclaimer" for the program, if

necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program

`Gnomovision' (which makes passes at compilers) written by James Hacker.

<signature of Ty Coon>, 1 April 1989

Ty Coon, President of Vice

This General Public License does not permit incorporating your program into

proprietary programs. If your program is a subroutine library, you may

consider it more useful to permit linking proprietary applications with the

library. If this is what you want to do, use the GNU Lesser General

Public License instead of this License.