Freepbx/Asterisk Hylafax w/Avantfax for Dummies (Ubuntu)
PREFACE: Goal is to implement a fully functioning Hylafax system with Avantfax front end on a Freepbx/Asterisk based pbx. This method allows the client to be platform independent. A web browser is used to send and receive the faxes. Supported formats include pdf, tiff and txt. It's a minor inconvenience to generate a pdf. Nearly every system now has some sort of print to pdf built in (windows10, chrome, opera), or third party software can be used.
Yet another Java HylaFAX client (https://www.yajhfc.de/) is a very nice client with lots of features but requires java be installed.
Scouring the internet provided bits and pieces how to make this work. I've cobbled together enough tidbits to have a usable end result. This guide will assist in installation & configuration of the Hylafax components and Avantfax gui. As I'm no pbx or linux expert, some steps may be simplified or omitted by more expert users.
My pbx is set up as a VM under esxi 6.5, ubuntu 18.04 lts (64bit), freepbx 14, asterisk 15.
PREQUISITES:
1) Fully configured asterisk pbx system with at least 1 trunk. You should be able to successfully make and receive calls. This will be used as a starting point.
2) Pbx should have working email.
PROCESS OUTLINE:
1) Hylafax and iaxmodem installation
2) Configure fax inbound/outbound routes
3) Avantfax installation
Hylafax & Iaxmodem Installation:
1) Ssh into the pbx and download/extract the attached file archive. These files are from archive in the first post of this thread - https://www.dslreports.com/forum/r30661088-PBX-FreePBX-for-the-Raspberry-Pi . Thanks RonR!
Extract contents of attached zip into a tmp or home directory.
2) Execute the install-fax script - this downloads and install hylafax server & iaxmodem components. This should be done with sudo or as root. No user input required. There will be some warnings. They can be safely ignored.
htmlsudo ./install-fax
3) Create extensions and virtual modems. One extension/virtual modem pair is needed for each trunk channel you wish to use. Google voice allows 3 concurrent channels. This will allow you to send and receive at the same time up to the limit of available channels/trunk. Each should be a unique extension number. Create as many as needed.
Keep in mind, inbound and outbound routes ultimately determine which trunks are used for what purpose. At least one needs to be defined for this to work at all.
Execute the following script to create the extension/virtual modem pair.
jssudo ./add-fax-extension
js~$ sudo ./add-fax-extension Extension number: 123Fax number: 11231231234Local identifier / Fax name: 11231231234EMAIL address: email@domain.comCountry code: 1Area code: 123Long distance prefix: 1International prefix: 001Extension number: 123Fax number: 11231231234Fax name: 11231231234EMAIL address: email@domain.comCountry code: 1Area code: 123Long distance prefix: 1International prefix: 001Continue (y/n)? y
After all extension/modem pairs are created, login to the pbx for the next step.
Configure fax inbound/outbound routes
1) Create the inbound/outbound routes to link with the new extension. If you set up multiple pairs then a ring group would better suited for the inbound route. Details below. For a single pair just reference an extension.
A) Edit the new extension(s) to disable call waiting under Applications -> Extensions, 123, edit. Do this for each extension defined in #3 above.
1) Advanced tab, extension options, call waiting
B) Inbound routes
1) Click on Connectivity/Inbound routes, + Add Inbound Route. Fill in as indicated below
Description: FAX-in
DID number: 1231231234
Set Destination: --> Extensions --> 123
Ring group instructions will be provided later.
C) Outbound routes
1) Click on Connectivity/Outbound routes, + Add Outbound Route. Fill in as indicated below
Route name: FAX-out
Trunk Sequence for Matched Routes: {select trunk you wish to use for fax}
2) In the dial patterms tab enter the following for each row:
prepend: 1
match pattern: NXXNXXXXXX
caller id: 123
This ensures calls made by the 123 extension will only go out on the defined trunk. When dialing only the 10 digit number is needed.
D) Click apply at the top when done. Reboot the server
2) Testing
A) We'll use minicom to make sure the line is working properly in both directions. Minicom is a basic terminal program to communicate with the modem.
js sudo apt install minicom sudo minicom -D /dev/ttyI123 atz <enter> output --> OK atdt{10 digit test number to call} <enter>
You should hear fax tones after picking up the test number phone.
Hang up and dial your fax number back. You should see the word RING appear in Minicomm, repeating about every few seconds.
You can hang up now. Ctrl-A, q to exit Minicom.
This confirms successful setup of Hylafax & Iaxmodem components.
You can stop at this point if you'll be using some other client such as the one referenced in the preface to communicate with the fax system. The next part installs the Avantfax interface. The basic steps below come from this blog post - http://hardwarefetish.com/732-freepbx-with-hylafax-and-avantfax-on-debian-jessie . There are some errors in his/her instructions. These are resolved including commentary in the steps that follow.
Avantfax installation
1) Download & extract the Avantfax installer
jssudo -icd /usr/srcwget http://downloads.sourceforge.net/project/avantfax/avantfax-3.3.5.tgztar -xzvf avantfax-3.3.5.tgzrm avantfax-3.3.5.tgzcd avantfax-3.3.5/
2) Edit debian-prefs.txt using your favorite editor
jsnano debian-prefs.txt
a) Change the HTTPDUSER/GROUP to asterisk
jsHTTPDUSER=asteriskHTTPDGROUP=asterisk
b) You can edit FAXDOMAIN too but don't make any other changes. Other parts of the installer are hardcoded with the existing user/pass. If changed, installation will complete but the gui will fail to open when launched. I chose to leave the default installation path as this will keep Avantfax separate from freepbx.
Start the installer
js./debian-install.sh
Some of the modules will fail to install. I believe this is because they're outdated. I was able to get a working system even with these errors.
c) Create the apache vhost config file
jsnano /etc/apache2/sites-available/002-avatfax.conf
d) Paste one of the following. Change ServerAdmin email address to a real email address (not required). This email addr shows up if the site is inaccessible for some reason.
js<VirtualHost *:80> DocumentRoot /var/www/avantfax ServerName avantfax.local.domain ServerAlias avantfax ServerAdmin fax_webmaster@domain.com ErrorLog ${APACHE_LOG_DIR}/avantfax-error_log CustomLog ${APACHE_LOG_DIR}/avantfax-access_log common <Directory "/var/www/avantfax"> AllowOverride All </Directory></VirtualHost>
This is where things get complicated. I want Avantfax to only be accessible locally on my lan. I don't have port 80/443 open to the outside. There's several ways of dealing with this. One way is to run the Avantfax portal on a different port (simpler). The other is to define a record in the local dns proxy using an alias for the server ip. The code above defines the vhost in this manner. Those of you running a local dns server or proxy (pfsense, UTM, etc.) should have no difficulty making this sort of definition. I'm not sure if defining a static entry will work for those with more traditional routers. In that case you'll want to just run it on a different port.
The code below defines the Avantfax server on a different port.
jsListen 81 <VirtualHost *:81> DocumentRoot /var/www/avantfax ServerName my.faxdomain.com ServerAdmin fax_webmaster@domain.com ErrorLog ${APACHE_LOG_DIR}/avantfax-error_log CustomLog ${APACHE_LOG_DIR}/avantfax-access_log common <Directory "/var/www/avantfax"> AllowOverride All </Directory></VirtualHost> e) Enable the site
jsa2ensite 002-avatfaxservice apache2 reload
f) Confirm the server is accessible - open http://my.faxdomain.com or http://{IP of pbx:81} , respectively. Do not log in. We'll be making a number of config edits first. Be _VERY_ careful when editing these files. I recommend making a backup copy first. Be mindful of single, double quotes, colons and semicolons. One less or one too many will break things!!!
Changes to functions.php take effect immediately on page reload.
js Improve fax qualityfile /var/spool/hylafax/bin/pdf2fax.gsline 67Change vres=98 to vres=196 /etc/hylafax/sendfax.confadd VRes: 196 #Don't use, messes up outbound faxes, use above mods only#file /var/www/avantfax/includes/functions.php#line 534#$SENDFAX to $SENDFAX -G
Other tweaks and config changes. Adjust as needed
js /var/www/avantfax/includes/local_config.php Line 73 - admin email - emails sent from Avantfax will have this in the From fieldchange root@localhost to DONOTREPLY_avantfax@domain.com Line 80 - NOTIFY_INCLUDE_PDF - true or false. True will include sent fax pdf as an attachment for all sent faxes. If sending PHI/PII faxes, receiving pdf attachment in email defeats the whole reason for using fax in the first place. Line 84 - FAXRCVD_INCLUDE_PDF - true or false. True includes the received fax as an email attachment for all received faxes. If receiving PHI/PII faxes, receiving pdf attachment in email defeats the whole reason for using fax in the first place. Line 112 - ENABLE_DL_TIFF - true or false. True adds a link next to each fax to download original tiff image. Line 151 - MIN_PASSWD_SIZE - adjust as needed. I'm keeping this real simple at 4 Line 232 NOTIFY_ON_SUCCESS - true or false. Generates email notification on successful fax transmission. Leave true @Ward or RonRNeeds further research: How to disabling pdf attachments for failed sent faxes. Notification email is fine, but don't include the fax content. Line 235 & 236 - email signature/link. I just set these both to '' Line 253 - PAPERSIZE - change to letter Line 271-273 date format - swap %m and %d to adjust month/date format for US. Change divider from . to / file /var/www/avantfax/includes/langs/en.phpline 272 - adjust email template to include the port number if you're using port 81change http://%s to http://%s:81
Reboot before continuing.
g) Open Avantfax url in browser, default login/pass is admin/password. You'll be prompted to change the password.
h) Click the wrench icon under the logout button to open up the admin section
i) Open Modems in the Menu under Configure. Add the modems defined earlier. If you forgot what they're called, run faxstat through ssh
Each modem requires 3 parameters
Device ttyI123
Alias {description}
Contact email@domain.com
You will not receive email notifications is the contact field is empty!
j) Select User list in the menu then click on the AvantFax Admin
Change email address to real address.
k) I would create a non admin user for daily use.
Done!
Some useful shell commands
faxstat
More to be added later
fax log path - /var/spool/hylafax/log
Each fax just has a separate log file c00000xxx. Lots of useful info.
Other details
* Don't send faxes from one google voice number to another. Something gets done to the signal which results in fax failure. Forward to another DID offnetwork (callcentric, ipcomm, etc). Or better yet don't use gv for fax at all. It's troublesome to say the least.
↧