Personal tools
You are here: Home / OSCAR EMR 12.x / 4.0 Developers / 4.5 OSCAR Faxing / 4.5.2 Hylafax Setup for Oscar

4.5.2 Hylafax Setup for Oscar

It is very convenient to fax directly from the desktop. These instructions cover fax Configuration with Hylafax for use with Oscar on on the LAN


This is a basic installation of a Hylafax Server for use with Oscar.  Security details are not covered

Document Version History

  • v1.0 – initial public release to – 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,14
 copyright ©2012-2013 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License



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


It is assumed that

  1. You have installed Oscar and configured it for faxing
  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 10.04 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/ and

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):


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


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


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

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/tomcat6-tmp as matching txt files with the fax number and pdf for the image to be faxed.  (note that you should check the path for the tmp file, it can be /tmp/tomcat6-tomcat6-tmp/) Once adjusted for your setting save the following as hylafax.cron

# Hylafax cron
# Picks up the files dropped by OSCAR for faxing
# Make sure you adjust the paths appropriately
for f in `ls /tmp/tomcat6-tmp/*.txt`; do 
	sendfax -n -d \"`sed s"/ *//g" $f|tr -d "\n"`\" `echo $f | sed s"/txt/pdf/"`;
	rm $f; 
	rm `echo $f | sed s"/txt/pdf/"`; 

Now make it executable

chmod 777 hylafax.cron

And set it up as a cron job with

sudo crontab -e
And add an entry like the following that executes every 3 minutes
*/3 * * * * /home/peter/hylafax.cron

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.


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

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 for the fix
  4. AvantFax coversheets may not work but there is no need to try to fix them. YajHFC does coversheets anyway.


Document Actions