Howto: Receiving Faxes With efax

The following text describes how to setup the efax software and an additional shell script on Linux systems to receive faxes with a standard Class 2 modem connected to the serial port (RS-232). At Leisenfels we use this solution to access incoming faxes also while being out of office and because faxes are directly feeded into the support ticket system. In addition to this reception-only solution we use a classic fax device to send faxes in order to get a reliable protocol of outgoing messages. The classic fax device works as a failsafe device in this scenario, too.

If you have a Linux system up and running already then it could be easily extended to receive and distribute fax pages by e-mail. In many cases it is not necessary to print the fax pages, so this solution helps saving natural resources. You could also recycle a modem e.g. buy a used one from eBay.

System requirements

This installation has been successfully tested with the following configurations, other modem hardware and (Linux) operating systems may also work. Just give it a try.

Notices: Serial extension cards for RS-232 like the EXSYS EX41098 normally work as long as regular /dev/ttySx devices are being created. Modem must support Class 2, Class 1 modems like Acer Modem 56 Surf will not work!

If you want to do both receive and send faxes please check the commercial solutions on the market like ActFax, GFIFAXmaker, David.fx or Visendo.

Please read the following steps to setup your Linux system:

• Step 1: Setup hardware and connection
• Step 2: Download and install efax
• Step 3: Configure the fax_xxxxxx shell skript
• Step 4: Start fax server via inittab
• Step 5: Testing

Step 1: Setup hardware and connection

First of all please setup your hardware. Connect the fax modem to a free serial port of your Linux server as described in the manual shipped with the modem. Make sure that the modem is connected to the telephone line to receive incoming fax calls. Your external fax MSN must be routed to this telephone line.

The following list shows some useful commands to check your modem. Please read the man pages or documentation of the mentioned tools to setup your modem properly. Normally, none of these commands need to be executed in order to get the fax solution up and running as described by the next steps.

• setserial: Show port configuration
• stty: Configure RS-232 port
• minicom: Serial communication program

Step 2: Download and install efax

Now download the current efax distribution (we used efax-0.9.tar.gz). This archive may be unpacked into a directory of your choice on your Linux system (we suggest /opt).

# cd /opt
# tar -xvzf efax-0.9.tar.gz
# cd efax-0.9

You may want to edit the file /opt/efax-0.9/Makefile to install the executables in /usr/local/bin instead of /usr/bin. Please adjust the following lines this way with your favorite editor (here emacs, save with CTRL+X/CTRL+S and exit with CTRL+X/CTRL+C). If you use another Linux distribution please adjust the paths accordingly to your system.

# emacs -nw Makefile

BINDIR=/usr/local/bin
MANDIR=/usr/share/man

Then please type the following commands to compile and install the efax executables. If errors are being generated please consult the efax documentation. Often libraries are missing which can be installed easily by using the system's administration tool like YAST for SuSe Linux distributions.

# make
# make install

Step 3: Configure the fax_xxxxxx shell script

The basic fax reception is done with efax, sending the fax pages attached to an e-mail must be done separately with an additional fax shell script. Please download the fax_xxxxxx script to the /usr/local/bin directory of your system. Rename the script according to the external fax number like fax_123456 using the mv command if you want to operate multiple fax numbers with separate modems. The scripts can be easily configured to send the fax pages to different e-mail addresses etc. Allow the shell script be executed with the chmod command.

# mv fax_xxxxxx fax_123456
# chmod 755 fax_123456
# emacs -nw fax_123456

Wherever you see the fax_xxxxxx script name in the next sections please replace by your renamed file name.

The following snippet shows the configuration section of the shell script with variable values that need to be adjusted for your server. Please make sure that all expected paths to executables like mimencode are correct (e.g. /usr/bin/mimencode), adjust paths otherwise. If executables are missing on your system, please check out the admin tool that comes with the Linux distribution like YAST for SuSE.

#!/bin/sh
 
# /usr/local/bin/fax_xxxxxx
 
# Copyright (c) 2002-2013 Leisenfels. All rights reserved.
# Use is subject to license terms.
 
# Configuration section. please adjust values.
# Add additional recipients separated by comma.
MAILTO="info @ yourdomain.com"
SENDER='root @ yourdomain.com (fax service)'
TARGET_MSN="123456"
MAILER="/usr/sbin/sendmail"
ARCHIVE_DIR="/var/spool/fax/incoming"
ARCHIVE_PERMS="600"
ARCHIVE_OWNER="root"
TEMP_FILE="/tmp/`basename $0`.$$"
NOW_DATE=`date`
NOW_FILE=`date +%Y-%m-%d_%H:%M:%S`
NEW_LOG_FILE="${TARGET_MSN}_${NOW_FILE}.txt"
ATTACH_FAX_FILES="yes"
ATTACH_LOG_FILE="yes"
NICE="nice -n -10"
EFAX="/usr/local/bin/efax"
DEV="ttyS0"
INIT="-iZ0 -i&F&D2&C1&K3S7=120 -iM1L1 -i#CID=1"
CLASSINIT="-o0"
LOCK="/var/lock/LCK..$DEV"
FROM="+49 1234 $TARGET_MSN"
SUBJECT="[fax] New fax for $FROM"
RESET="-kZ0"
ANSRINGS=1
ANSFNAME="${TARGET_MSN}_%Y-%m-%d_%H:%M:%S"
CLEANUP="rm -f ${TARGET_MSN}_*-*-*_*:*:*.[0-9][0-9][0-9]"
SUFFIX="tif"
MIMENCODE="/usr/bin/mimencode"
LINK1=""
LINK2=""
 

As you can see, only a few values require to be adjusted:

• MAILTO: Add the recipient e-mail address(es) as comma separated list
• SENDER: Set the sender e-mail address and optional name
• TARGET_MSN: Add your external fax MSN
• DEV: Specify your serial device
• FROM: Set your full station identifier transmitted to the fax senders
• ANSRINGS: Set the desired number of rings to take the call

Feel free to adjust the e-mail subject and English body text used by the script. Please consult your modem's manual if the AT commands used by the script do not work (INIT).

Step 4: Start fax server via inittab

Basic configuration should be complete by now, let's start the fax server by adding a new entry at the end of the /etc/inittab file of your Linux system. Replace the "S0" value by the number of the /dev/ttySx device that you are using. For instance if you are using /dev/ttyS7 then set "S7" to the very beginning of the inittab line. The respawn field causes the fax script to be automatically restarted if a fax has been received or if the process has been interrupted.

S0:12345:respawn:/usr/local/bin/fax_xxxxxx

Then reinitialize the runlevel services with the following command. The efax application should now be listed with the other processes of your system.

# init q
# ps aux|grep efax

Step 5: Testing

Now it's time to check if the fax functionality works as expected. Please make sure that your modem is attached to a line that is signaled when your fax number is being dialed.

Please dial your fax number (possible also from your phone or cell phone). The modem should take the call after the configured number of rings. You should hear the typical fax initiating sounds. If nothing happens then probably the call is not signaled to your modem. Please check your modem's manual if there is a way to see when a call has been detected (e.g. some flashing LED).

If this test has been successful then please send a fax from another fax device. The fax modem should then receive the fax completely (all pages) and the fax pages should be send as attachments to the configured e-mail account(s). The script stores the fax pages together with the reception log in the /var/spool/fax/incoming directory. This sort of archive can still be viewed of sending the fax pages via e-mail did not work e.g. due to a misconfigured e-mail server.

Depending on the e-mail client you use the TIFF image attachments may be visible directly. It may be necessary to install and configure an appropriate image viewer like The GIMP to view the fax pages attached to your e-mails. The following screenshot shows how such an e-mail is displayed by the Thunderbird e-mail client (click to enlarge).

For improvement suggestions or any other feedback please fill out our support request form.

How to continue

• Howto: VFSLib - Apache Commons VFS Reloaded
• Tech Zone: Java System Properties (JavaInfo)
• Tech Zone: JAR File Extension (JarInfo)
• Supported Projects
  

Print Email