Hylafax Setup for Oscar

Owned by Marc Dumontier
Last updated: Feb 23, 2021 by John Wilson
5 min read

It is very convenient to fax directly from the desktop. These instructions cover fax Configuration with Hylafax for use with Oscar on the LAN. This is the legacy technique introduced in OSCAR 12, and remains as an alternative to the OSCAR Fax service.

This page has been imported from http://www.oscarmanual.org and has not yet been reviewed by OSCAR EMR.


Preface

This is a basic installation of a Hylafax Server for use with Oscar.  Security details are not covered.  Hylafax can be more tightly integrated with the OSCAR Fax service instructions elsewhere.

Document Version History

  • v1.0 – initial public release to oscarmanual.org – August 20, 2012
  • v1.1 - additional hylafax notes - February 18, 2013
  • v1.2 - added notes regarding paths and switched cron to run q 3 min - May 27, 2013
  • v1.3 - added Hylafax troubleshooting as per Dennis Warren  - July 3, ,2013
  • v1.4 - added note regarding MultiTech MT9234ZBA USB modem - March 13, 2014
  • v1.5 - updated instructions for OSCAR 15 - Nov 13, 2016

 copyright ©2012-2016 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License


Contents

  1. Preface
  2. Document Version History
  3. Installing Server Packages
  4. Installing Client Packages
  5. Oscar Fax Settings

Prerequisites

It is assumed that

  1. You have installed Oscar and configured it for faxing (the default DEB install)
  2. You have a basic level of Linux knowledge
  3. You can open a Linux terminal
  4. You can cut and paste EXACTLY the following instructions

NOTE: Firefox will copy with Control+C while a Linux terminal requires Shift+Control+V for paste

Installing Server Packages


Hylafax is the leading open source computer to fax server that converts documents (usually pdf or tiff) to fax through a local modem and phone line.  The main advantages of Hylafax over an Internet Fax Gateway is that you do not need internet connectivity for it to work, and that all numbers reachable by a local fax machine, including "in province" 1-800 numbers, are supported.  Its main costs are for the phone line.

It is easiest to configure Hylafax on the same server as Oscar, but any PC with the following characteristics will do

  1. Running Linux (tested on Ubuntu LTS)
  2. With a Hylafax compatible fax modem (google the card for this before you buy)
  3. Plugged into a phone line and the local area network (LAN)

Install Hylafax by typing or pasting the following into the command line.

sudo apt-get install hylafax-client hylafax-server

Configure the modem

sudo faxsetup
sudo faxaddmodem

Answer the questions as they come.  The defaults will suit except for the following

  • Local identification string (for TSI/CIG): [your clinic name] (otherwise all your faxes will come from "NothingSetup")
  • protection mode for received fax: 0644
  • protection mode for session logs: 0644
  • protection mode for ttySx: 0666

Notes on Hylafax and faxaddmodem

  1. USB modems may be defined as device USB0 or ttyACM0.  Use the lsusb program to detect USB devices.
  2. Ubuntu 10.04 support for USB modems does not work for the Multi-Tech MT9234ZBA USB modem.  Under Ubuntu 12.04 the modem works fine.  MultiTech will update the firmware to fix the problem if you send it back to them.
  3. Oscar likes PDF files more than TIF files.  Create /var/spool/hylafax/FaxDispatch to use tiff2pdf and move the incoming faxes from /var/spool/hylafax/recvq to a folder accessible by the Oscar InBox. 
  4. Only sending headers?  Add -dMaxStripSize=0 \  to the command at the end of /var/spool/hylafax/bin/ps2fax.gs and pdf2fax.gs

Then stop the Hylafax server:

sudo /etc/init.d/hylafax stop

add a fax user to Ubuntu server (write down the UID as you will need that later)

sudo adduser [faxuser]

add the fax user to Hylafax

faxadduser -a [adminpass] -p [userpass] -u [uid] [username]

start the Hylafax server:

sudo /etc init.d/hylafax start

test the server (enter the faxuser password if you are prompted):

faxstat

Now test that it works supplying your own fax number (on a different telephone line than the modem!) for XXXXXXXXXX.

sendfax -n -d XXXXXXXXXX /usr/share/doc/hylafax-server/copyright

Troubleshooting

I get some kind of font error after testing with the sendfax command.

This is because Hylafax could not find the ghostscript fonts. First you need to locate the font file with this command: 

locate Fontmap

append this font link to the list at (drop the filename after "fonts"):

sudo nano /etc/hylafax/hyla.conf
FontMap: /var/lib/defoma/gs.d/dirs/fonts

Restart the server:

sudo /etc/init.d/hylafax restart


 
Faxes that I send are blank with just the header info showing.

Either Add Use2D: no to the config file

sudo nano /etc/hylafax/config
Use2D: no

OR

Add -dMaxStripSize=0 \  to the command at the end of /var/spool/hylafax/bin/ps2fax.gs and pdf2fax.gs

Restart the server:

sudo /etc/init.d/hylafax restart


 

Access is denied in YajHFC (admin and/or user). I cannot see the received faxes.

Stop Hylafax: 

sudo /etc/init.d/hylafax stop

Hylafax has a known bug which mounts the same directory multiple times.  You can determine this with: 

mount|grep ^'/etc/hylafax'

Run umount until every directory is unmounted:

sudo umount /etc/hylafax

Run faxadduser again: 

faxadduser -a [adminpass] -p [userpass] -u [uid] [username]

Check the hosts file to ensure the user was written:

sudo nano /etc/hylafax/hosts.hfaxd 

You can also add: 127\.0\.0\.::

remove any extra users

Start Hylafax 

sudo /etc/init.d/hylafax start


 

Check to ensure that /etc/hylafax mounted correctly:

sudo nano /var/spool/hylafax/etc/hosts.hfaxd


 

If this file is blank or missing user data start over from the beginning.  All /etc/hylafax directories must be unmounted for this to work.

Now a cron job

With the default deb installation Oscar drops faxes into /tmp/tomcat7-tomcat7-tmp as matching txt files with the fax number and pdf for the image to be faxed.  The Deb already drops gateway.sh as a cron job.  Merely adust for Hylafax with adding a sendfax line (bolded below)

#!/bin/bash
#
# Fax Gateway cron
# Picks up the files dropped by OSCAR
# If a mutt line is uncommented will send a fax to that fax gateway
# Otherwise it just clears the files dropped by OSCAR
# Make sure you adjust the paths and mutt switches appropriately
#


if test -n "$(find /tmp/tomcat7-tomcat7-tmp -maxdepth 1 -name '*.txt' -print -quit)"; then
	echo "Faxes found to be sent"
	for f in `ls /tmp/tomcat7-tomcat7-tmp/*.txt`; do 
		t=`echo $f | sed -e s"/\/tmp\/tomcat7-tomcat7-tmp\///" -e s"/[._][0-9]*.txt//" -e s"/prescription_/Rx-/"
		sendfax -n -d \"`sed s"/ *//g" $f|tr -d "\n"`\" `echo $f | sed s"/txt/pdf/"`;
#		mutt -s "Oscar Fax $t" 1`sed s"/ *//g" $f|tr -d "\n"`@srfax.com -a `echo $f | sed s"/txt/pdf/"` < /dev/null
#		mutt -s "Oscar Fax" 1`sed s"/ *//g" $f|tr -d "\n"`@metrofax.com -a `echo $f | sed s"/txt/pdf/"` < /dev/null
#		mutt -s "Oscar Fax 2442" `sed s"/ *//g" $f|tr -d "\n"`@prestofax.com -a `echo $f | sed s"/txt/pdf/"` < /dev/null
		rm $f; 
		rm `echo $f | sed s"/txt/pdf/"`; 
	done
fi

If you are only faxing the things in Oscar that can be faxed directly (eForms, Consult requests and Rx's) you can stop here

However there are server and client options that can be easily added

Installing Client Packages

This is necessary only if you want to print a fax from any program from any workstation on your local network.  However installing clients on the network is not necessary to fax out of Oscar.

YajHFC http://www.yajhfc.de/downloads/current-version

Download YajHFC on the workstation It is a java based client for hylafax ie. a program that runs on the workstation and can fax out via the hylafax host.

Download and install YajHFC onto your client machines. Choose all the options for a full install. After install proceed to setup the client. 
Normally this is offered at startup but if not:

From the navigation menu: Extras / Options / Servers / Default ...

In Connection Settings

Host Name: [your server ip]
Port: [use default] ensure this port is unblocked
Username: [hylafax username]
Password: [hylafax password]
Admin Password: [hylafax password]
Uncheck "Always ask" next to Admin Password

Click: Test connection

And then from the navigation menu: Extras / Admin mode

Authentication issues? Check troubleshooting.

Read the documentation for setting up phone directory and database tables. 
This could potentially access the consultation directories on Oscar.
The address book can live anywhere (just point YajHFC at where it is). It also has cover sheets.

The YajHFC website has instructions for installing a 'printer' (in CUPS) - so that an open document can be printed directly to that fax machine without being saved as a pdf.

 Avant fax http://sourceforge.net/projects/avantfax/files/

This is a web GUI administration for Hylafax.

Notes on Avantfax

  1. As this loads php and Apache2 it those installations will need security hardning
  2. Don't hit your thumb by changing the mysql root password when installing it as part of the AvantFax install (just say no when it makes you this unkind offer).
  3. There can be an issue with the configuration of ghostscript  - which leads to faxes being blank.....see http://www.ttsmi.com/avantfax_hylafax_ubuntu/ for the fix
  4. AvantFax coversheets may not work but there is no need to try to fix them. YajHFC does coversheets anyway.