cupsfax 0.4

cupsfax project contains a set of two scripts to integrate a fax server into the CUPS printing system.

  Add it to your Download Basket!

 Add it to your Watch List!


Rate it!
send us
an update
Public Domain 
3.4/5 16
Olaf Titz
ROOT \ Printing
1 cupsfax Screenshot:
cupsfax project contains a set of two scripts to integrate a fax server into the CUPS printing system. To send a fax, the user prints it to the designated printer queue. He will then receive a mail with a link to a web form. In this web form, the user may enter additional parameters - most importantly, the receiving fax number.

This way, there are no additional conditions on what can be printed, like fax numbers embedded into the file or job name. This can also be fully integrated into a samba/CUPS configuration, enabling Windows clients to send arbitrary documents as fax. It also gives the full power of the CUPS print processing pipeline to sending faxes.


CUPS (tested with 1.2.4)
HylaFAX (tested with 4.3)
For other fax programs the CGI script would have to be adapted.
perl (tested with 5.8) with the CGI and MIME::Base64 modules.
Any CGI-capable webserver.

How to install:

Edit the parameters at the top of the Makefile as needed.

Run "make install" as root.

This installs the programs and creates a spool directory. It also installs a cron.daily script if your system has the cron.daily directory. If not, it is advisable to install this manually somewhere and have it run regularly. (This cron script simply removes old spool files left over from errors or abandoned jobs.)

Note: the spool directory must be on a filesystem which supports case-sensitive filenames with a length of up to 30 characters. Do not use the existing CUPS spool directory.

Restart cupsd. Create a printer definition on CUPS with the following characteristics:

Device: "Require user response"
Device URI: userresponse: followed by the CGI link.

E.g. userresponse:http://printserver/cgi-bin/cupsfax

Provide a PPD file: use the PostscriptFAX.ppd found in this package.

How it works:

The userresponse backend writes two files in the spool directory. The job file name is random (see below why). This file contains one line with parameters. The print data is written into a second file, named like the first with "_d" appendend.

Then the backend sends a mail to the job owner, containing a link to the cupsfax CGI program with the job file name as parameter. If no error has happened so far, the job is completed in the CUPS system.

When called by the user with the right parameters, the CGI program reads the job file. It emits a form to fill out. After the form gets submitted, the CGI program calls sendfax. When sendfax finishes without errors, it removes the spool files and the job is completed.

The userresponse is actually a generic program which can be used for arbitrary post-processing of print jobs. It just writes the spool files and notifies the user. Further processing happens via the CGI program.


The spool files are written and read under the job owner's ID with mode 600, so only the job owner can access the job. For this purpose, both scripts are installed setuid root and assume the user's identity when necessary. Because the CGI script has access to all jobs - as given by the job filename - the job filename is a random string. The spool directory is not world-readable, so it is not possible for a user to find out the right parameters to manipulate another user's jobs.

This can be made still more secure by protecting the CGI script with HTTP authentication, where the user name must match the print job owner name. See the comment in This requires appropriate configuration of the webserver.

The spool files

The job file contains, on one line, the printer name, job ID, user name, creation time and job title. The fields are separated by TAB. The time is give in UNIX seconds. The data file contains the print data, which gets passed to the sendfax program on standard input.

Last updated on January 25th, 2007

#fax server #CUPS fax #printing system #cupsfax #fax #server #CUPS

Add your review!