Avantfax/Hylafax - The Complete Fax Solution
Every once in a while you run across open-source projects that meet a real-word need in such an elegant manner that you just have to grin... Hylafax, standing alone is one heck of an enterprise class fax package that is the equivalent of the "swiss army knife" of faxing. However, while hylafax is a work-horse of a fax handler, many people shy away from its command line interface. There have been only a few successful sendfax GUI interfaces for it in the past and many of those are no longer mainted.
Enter Avantfax developed by David Mimms, Jr. Avantfax is a fantastic web based fax management system for hylafax. It is built on php and MySQL and provides a fantastic user interface for managing the sending and receiving of faxes, including managing your fax contacts and fax distribution lists and user lists for Avantfax itself. After having set up two Avantfax/Hylafax servers this past week and having drilled down the install for openSuSE and tweaking the configs, I thought I would make that information available to help others that deal with faxes regularly. (Yes, lawyers deal with lots of faxes.)
Well beyond simple fax management, Avantfax provides the option to integrate the Tesseract OCR package and the Linux barcode package for automatic text recognition and barcode capture to the MySQL database. It is truly impressive.
1. - System & Software Requirements
Since openSuSE provides the hylafax rpm, there being few install problems, this page concentrates on getting Avantfax setup with Tesseract OCR that will provide a bullet-proof, web-accessable, OCR capable fax server.
Hardware Requirements
What do you need to run a fax server? Got any old throw-away 486 boxes left lying around anywhere? I'm serious, the fax server for my office is an ancient 486 AMD K6-2/450 with 256M of RAM running openSuSE 10.3, and an old ISA bus US Robotics Speedster 56k faxmodem. This machine runs apache2, hylafax, lm_sensors, mysql, ntp, postfix, samba, and ssh -- comfortably. Any machine with similar specs will do.
Software Requirements
The two primary system packages required by Avantfax are hylafax and MySQL. In addition to hylafax and MySQL, there are a number of other little packages required that will be installed by the install script using Yast/yum.[1]
In order to piece together the fax system, you will need hylafax installed first. For openSuSE, the simplist way to accomplish that is to run "zypper in hylafax" and then run "faxaddmodem" to configure the package. Once you have hylafax installed, download the following packages:
- Avantfax -- avantfax-3.1.6.tgz
- The Tesseract OCR engine -- tesseract-2.03.tar.gz
- The Tessdata language libraries -- tesseract-2.00.eng.tar.gz
2. - Installing Avantfax
Installing Avantfax is straightforward. You will extract the contents of the avantfax package to a directory and then edit the [distro]-prefs.txt (sles-prefs.txt for openSuSE) and email2fax.txt files to supply the appropriate directory and webserver information and then run the [distro]-install.sh script (sles-install.sh for openSuSE) that will copy everything to the proper place and setup-postfix.sh. Very basic information is contained in the INSTALL.txt file included with the package. However, there were a number of changes required to properly set the package up on openSuSE.
Note: Only run the [distro]-install.sh script ONCE or or risk adding duplicate configuration settings to sudoers and the HylaFAX configuration files.[2]
To get started extract the contents of Avantfax with 'tar -xzf avantfax-3.1.6.tgz', then configure the [distro]-prefs.txt (sles-prefs.txt) and email2fax.txt files.
Edit the Preference Files
For openSuSE, the needed preference file configurations are:
sles-prefs.txt (with comments removed): FAXDOMAIN=yourhost.yourdomain.com INSTDIR=/srv/http/avantfax HYLADIR=/usr SPOOL=/var/spool/fax USER=avantfax PASS=pickapass DB=avantfax ROOTMYSQLPWD=yourMySQLrootPW HTTPDUSER=wwwrun HTTPDGROUP=www email2fax.txt (with comments removed): FAXDOMAIN=yourhost.yourdomain.com FAXMAILUSER=faxmail
If you have not initialized and secured your MySQL installation, do that before proceeding. See: openSuSE Server Setup: MySQL - Securing Your Server
Running the Install Scripts
Now simply install Avantfax by running both sles-install.sh and setup-postfix.sh from the command line as root:
sh sles-install.sh sh setup-postfix.sh
Making Needed Configuration Changes
When the install completes you will have two configuration files that you must edit to complete the Avantfax configuration. The files are located in the /srv/http/avantfax/includes directory and are named config.php and local_config.php. Rather than spending a lot of time talking about parameter, I have made mine available (without the default comments) for an easy reference. For my install I enabled Tesseract OCR but not the barcode feature. In each of the files, I have either added specific comments or highlighted the parameters to pay particular attention to:
Now to polish off the Avantfax package configuration, make sure you review the final steps in the Avantfax Installation Guide to check the remaining file permissions, etc...
Note: If when you access the advantfax pages such as yourserver.com/advantfax or ../advantfax/admin and you notice that you are without any icons or images on the page, or if the page is missing its formatting, check to see if you have conflicting designations of your "css", "images", or "js" aliases. Avantfax makes use of its own directories, but if you have global aliases for /css, /images, or /js it can cause problems. Advantfax defines its values for the above in ../avantfax/includes/templates/ (main_theme & admin_theme) /templates/index.tpl
Tightening sudo Security
By default Avantfax provides sudo capability to shutdown or reboot the server from the web interface along with providing sudo capability to download the faxes from the webserver and the mysql database. I wanted to eliminate the chance of, and prevent, any inadvertent shutdown or reboot of the server, so I simply modified the sudoers additions and removed /sbin/reboot and /sbin/halt. (type visudo to edit the file, do NOT edit it directly) The remaining sudo entry was:
wwwrun ALL= NOPASSWD: /usr/sbin/faxdeluser, /usr/sbin/faxadduser -u * -p * *
Before you will have a working configuration, you still need to configure apache to accommodate Avantfax.
3. - Configuring Apache for Avantfax
By default the install creates a name-based virtual host for Avantfax to operate from. This configuration didn't meet my needs because it prevented secure access the Avantfax using ssl https://. Your second option is to simply create a directory entry for avantfax in your /etc/apache2/httpd.conf.local file. I opted for a directory install instead of using the virtual host config to enable ssl secure remote access. Basically, all that was required was to move the directory information from /etc/apache2/vhosts.d/avantfax.conf into my httpd.conf.local file and restart the webserver. The basic directory definition looks like this:
# ## AvantFax secure fax system directory # Alias /avantfax/ "/srv/http/avantfax/" Alias /avantfax "/srv/http/avantfax/" <Directory "/srv/http/avantfax"> Options -Indexes +FollowSymLinks AllowOverride AuthConfig Options FileInfo Limit Order allow,deny Allow from all </Directory>
Additionally, I configured address rewrite and dbm2 authentication for the directory. My resulting directory definition was:
#
## AvantFax secure fax system directory
#
Alias /avantfax/ "/srv/http/avantfax/"
Alias /avantfax "/srv/http/avantfax/"
<Directory "/srv/http/avantfax">
Options -Indexes +FollowSymLinks
AllowOverride AuthConfig Options FileInfo Limit
# Address rewrite for secure connection in not local
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REMOTE_ADDR} !^192\.168\.0\.
RewriteCond %{HTTPS} !=on
RewriteRule .* https://%{SERVER_NAME}%{REQUEST_URI} [R,L]
</IfModule>
# Authenticate if not local
AuthType Basic
AuthName "SecureFiles"
AuthBasicProvider dbm
AuthDBMType DB
AuthDBMUserFile /usr/local/lib/apache2/mydatabase
Require valid-user
Order allow,deny
Allow from 192.168.0.
Satisfy Any
</Directory>
If you haven't configured SSL for apache and would like to, see my openSuSE Server Setup page.
4. - Installing Tesseract OCR
Move tesseract-2.03.tar.gz and tesseract-2.00.eng.tar.gz into the same directory and then extract tesseract-2.03.tar.gz first, change into the new tesseract-2.03 directory and then extract tesseract-2.00.eng.tar.gz which will create the needed 'tessdata' directory:
tar -xzf tesseract-2.03.tar.gz cd tesseract-2.03 tar -xzf ../tesseract-2.00.eng.tar.gz
The only issue with the tesseract install is the makefile (java/makefile) not having an appropriate target causing the make to fail. A patch is required in order to complete the build and install the package. I created a patch that named tesseract.suse.diff:
00:47 nirvana:~/linux/apps/tesseract-2.03> cat tesseract-suse.diff
--- java/makefile 2009-02-14 03:10:48.000000000 -0600
+++ java/makefile.patched 2009-02-14 00:15:03.000000000 -0600
@@ -39,8 +39,12 @@
clean :
rm -f ScrollView.jar *.class
+distclean : clean
+ rm -f Makefile
+
# all-am does nothing, to make the java part optional.
all all-am :
+all all-am install :
# dist runs the autoconf makefile to archive the files correctly.
dist distdir :
To patch the java/makefile, from the tesseract source directory (i.e. ./tesseract-2.03) simply run patch as follows:
patch java/makefile <tesseract.suse.diff
Then just install normally with './configure', 'make' and then 'make install' as usual. If you didn't enable Tesseract by changing the line 'define('ENABLE_OCR_SUPPORT', true);' in the avantfax/includes/local_config.php file, go back and do that now and you are through with the install.
Final Notes
When you are all done, point your browser to http://yourhost.yourdomain.com/avantfax/admin default username is 'admin' and the default password is 'password'. Go through the admin configuration, add users and check out the interface -- you will love it. Then just google 'faxback number' and find you favorite to send to your new install for testing. Have fun, and if you have any tips or can help with development, contact David Mimms, Jr. the maintainer whose email can be found at the avantfax.com website.
