//Nabla 52 - /projects/fax_server

I know only one thing: I know nothing

HOME PROJECTS SOFTWARE HARDWARE OTHER FACTS LINKS

Sorry this section is under construction.

Why a fax server

Even we are supposed to become a paperless society, I can find that we are producing more paper than before. I think that is because it is too easy and cheap to print nowadays. One of my pet hates in this respect is the use of faxes instead of emails. It is still the only way to send documents in lots of circumstances. However I found myself most of the times typing the document in my favorite word-processor, printing the pages to be faxed and then throwing those pages to the bin when done. What a waste! I know that there are solutions that let you fax from your computer. Unfortunately they are costly and thus my company has decided not to implement them. I then started to look around the internet for a free solution. As you might expect it came from Linux and the open source community. The answer to my problem is called Hylafax. This is a server which lets you fax documents by way of printing them. Even if the solution sounded simple, to put into practice was a lot of more complex than I thought. The issue is on the client side. When you print a document to be faxed, you want to enter the fax number as well. But how? In normal circumstances the print dialog box cannot be customized to let the user enter a fax number. You simply print. That's it.

How to get the fax number from the user

Ok first I did a Google search as you would expect and found lots of solutions that basically involve writting a special print driver that will prompt the user for the fax number and other information such as the cover page. Even if this is quite good I found that this is prone to buggy drivers which also need to be rewritten for each new Windows version! You are also stuck with what the driver asks the user. No customization. Moreover to program a print driver this is not easy and require source headers not freely available (bad Microsoft bad!).

Other solutions assume that the user will type the fax number within the document to be faxed. The server will then (try) to extract the fax number. Normally that implies that the fax number must be entered according to strict rules. No very user friendly especially if your users are called dumb bob !

After a while researching I drew up the following requirements:

• Use the default Windows print drivers such as the one provided by CUPS which are also used in my PDF server. This way no buggy or half tested printer drivers.
• Customisable interface that prompts the user for the fax information: fax number, cover page and so on.
• Most processing must be held on the server and as little on each client.

From the Hylafax links page, I found this small program that was doing something clever. It waits for the server to request the fax number then opens a dialog box to prompt the user to enter the fax number and finally returns the string back to the server. Even if that was still too much of the interface on the client side, it gave me the idea that the server could push a request to the client machine to get the fax number. The sequence of events should be as follows:

1. The user prints the document using a special Fax printer implemented as a backend with CUPS and made available via Samba.
2. The backend script stores the document and requests the fax information back to the client.
3. A server on the client machine acknowledges the request and opens the default browser to show a web page held on our server (that's the clever bit).
4. Our web server prompts for the extra information via web pages. This can be easily customised because anyone could write their own web pages to suit their needs. Moreover the processing bit is held on the server and in one place. That will simplified any changes to the interface.
5. When finished, the web server transfers the fax request to Hylafax with the original document and the extra information.

As you can see there are 5 programs to cover the whole process:

• CUPS
• Samba
• Web server
• Tiny server on each client
• Hylafax

Server side requirements

In order to implement our fax server you will need the following.

• The server
  So first you need a server running Linux. In my case this will be Gentoo then! If you allocate one machine for the job (or even better a virtual machine using Xen of course) you should install a bare minimalistic kernel. Yes this means a console only server. I know that for some this is going back into the past but graphic just adds too much overheads. You can still manage your machine via SSH anyway if you really want a GUI working environment.
• uuenview
  This encoder can be found here. For those with Gentoo, this is more simple: emerge uudeview
• CUPS
  Next you need to install CUPS. This is the printer server that will held our fax printer. In my case I simply did: emerge CUPS Then edit /etc/cups/mime.convs file and uncomment application/octet-stream line. You need also the Windows printer drivers that will be installed automatically onto your clients. For that purpose create the folder /usr/share/cups/drivers and copy these files into it. Those drivers are the default one made available on CUPS web site. I would thus recommend you to head there and pick up the lastest version. Finally add cupsd to your default runlevel. In Gentoo: rc-update add cupsd default
• Samba
  In order for our Windows clients to talk to the Linux server and enumerate our printers we also need to install Samba. emerge samba My configuration file is available here. You should tailor it to suit your needs. However a critical line must be included towards the beginning of the config file in the Printing Options: cups options = "samba_client_ip=%I" This trick allows the printer backends to know the IP of the client machine. Next create the folder /etc/samba/drivers. If you want you can make sure you can access Samba web setup interface to make things easier. Otherwise you can still use the command line to publish CUPS printers via Samba. Finally add Samba to your default runlevel: rc-update add samba default To export CUPS printers to Samba using the web interface simply click Export to Samba button. Otherwise type the following: cupsaddsmb -H localhost -h localhost -v -U root -a After exporting printers you should always restart your samba server. /etc/init.d/samba restart Remember you can always test your Samba configuration by running testparam.
• ghostscript
  This utility will help convert a printed document to a Postscript file which are the type of files that Hylafax can send down the line. In Gentoo: emerge ghostscript
• tiff
  Image format. In Gentoo: emerge tiff For those using other distributions than mine, you must start understanding why I've chosen Gentoo. It's so simple to install a program!
• Hylafax
  This is the actual program that sends your fax. Installation requires more than a simple emerge because you need to set it up for your country. Here I assumes that you've already setup your modem (ttyS0 in my case) and I will show you what are the settings for the UK:
  • Run faxsetup and answer using the default values except for the following:
    • Country code: 44
    • Area code: 0117 (or yours)
    • Long distance prefix: 0
    • International prefix: 010
    • Dial rules: etc/dialrules.europe
  • Next run faxaddmodem ttyS0. Other than the default values I used the following:
    • Mode: ttyS0
    • Fax number: +44.[your fax number here]
    • Local id string: [your company name here]
    • Mode: 0644
    • Rings before answer: 0 (i.e. not to receive fax)
    Speaker can be turned on or off with the values high or off.
  Finally add hylafax to your default runlevel. There are still a few things to check out.
  • Open /etc/inittab and check if the following line is included s0:23:respawn:/usr/sbin/faxgetty /dev/ttyS0 If not then add it and run init q.
  • Check that the file /var/spool/fax/etc/setup.cache contains FAXQ_SERVER="yes" and HFAXD_SERVER="yes".
  • Edit your cron file (/etc/crontab in my case) and add the following schedule:
    • 0 * * * * /usr/sbin/faxqclean
    • 25 23 * * * sh /usr/sbin/faxcron | mail FaxMaster
  Hylafax maintains a list of users that are allowed to fax. To add root user simply run the following command. faxadduser -a [your password here] -u 0 root For some reason you then need to edit /var/spool/fax/etc/hosts.hfaxd and move root user to the first line. Once done Hylafax should be ready to fax. Below is a few helpful tips when using Hylafax:
  • The modem setup file is /var/spool/fax/etc/config.ttyS0.
  • Hylafax config file is /usr/lib/sendfax.conf.
  • To display the list of current faxes: faxstat -s -l -i
  • To remove orphan faxes run faxqclean
  • To remove a fax from the queue run faxrm [ID]. However on my system the program fails to remove the fax. Looking at the code, it does not remove the file that needs to be deleted. Thus I wrote a small shell script to do it my way and you might have to do the same.
  • To send a fax manually/usr/bin/sendfax -d [fax number here] file.ps Note that there are TWO sendfax programs, one in /usr/sbin and the other in /usr/bin, not to confuse people !
• Web server
  I've installed Apache but you could also use a lightweight web server instead. In my case installation and setup of Apache was easy with Gentoo so I went for it. If you do so don't forget to add apache to your default runlevel.
• Helper scripts
  The location of repetitive codes is in helper scripts. I've especially created the following routines:
  • A script that scans a config file and define variables for each <name,value> pair that it finds. Download procconfig.sh to /usr/bin/ folder and changes its attributes to +rx for all (i.e. ugo). This script is also used for my PDF server. To invoke it do as below: eval `$PROC_CONFIG "$CONFIG_FILE"`
  • A script that scans CGI parameters and define variables for each <name,value> pair that it finds. Download proccgi.sh to /usr/bin/ folder and changes its group to apache and its attributes to +rx for root and apache. Very handy when writing cgi-bin scripts in bash. To invoke it do as below: eval `$PROC_CGI $*`

Step 1: installing Print_To_FAX virtual printer

This is the printer to be installed on each client. However this will be as simple as selecting the printer from the list of printers made available via Samba by CUPS and running the Install command. Only the CUPS drivers will be installed on each client while the printer script resides on the server.

To install this printer on the server, follow the next steps:

• Copy hylaFAX.conf to /etc/cups/ folder.
• Copy hylaFAX.sh to /usr/libexec/cups/backend/ folder. This is the backend shell script that will called by CUPS. Don't forget to change its attributes to +rwx for root only!
• Copy hylaFAX.ppd to /usr/share/cups/model/ folder.
• Create folder /var/spool/cups-hylafax/etc and make its group apache with +rwx attributes.
• Create folder /var/spool/cups-hylafax/jobs and make its group apache with +rwx attributes.
• Change the ownership of folder cups-hylafax to root:apache. Then change its mode to g+rwx and o+rx.

Next use CUPS web administration to add the printer by clicking Add Printer. Select make as Postscript and model as HylaFAX Virtual Printer.

Step 2: installing Web Push Server on client machines

create folder /var/www and extract this folder in there. You need to make sure that all files are owned by apache user and group. To do so type chown -r apache:apache localhost

emerge sudo run visudo and add the following lines: Host_Alias SERVERX01 = localhost apache SERVER01=(root) NOPASSWD: /usr/bin/hylafax_sendps.sh Defaults logfile=/var/log/sudo

© 2007. Nabla 52