Content-type: text/html Manpage of fax4CUPS

fax4CUPS

Section: User Commands (1)
Updated: by Sebastiano Vigna
Index Return to Main Contents

NAME

fax4CUPS - A fax back-end for CUPS (Common Unix Printing System)

DESCRIPTION

fax4CUPS consists of PPD (PostScript Printer Definition) files and shell scripts that act as a CUPS back-end using efax (http://www.cce.com/efax/), HylaFAX (http://www.hylafax.org/), mgetty-fax (http://www.leo.org/~doering/mgetty/index.html) or capisuite-fax (http://www.capisuite.de/) to send faxes when something is printed through them.

Note that to use a fax back-end, you must install it first. Moreover, you need to install sudo and guarantee that your fax program can be run by the user running the backend using sudo without password.

You have to create a CUPS printer using a URI of the form efax:/dev/<device> for efax or mgetty-fax:/dev/<device> for mgetty-fax, where <device> must be a serial device (/dev/modem is ok if it is defined), capisuite-fax:/dev/<device> for capisuite-fax, or hylafax:/local, for a local HylaFAX server; of course, you must use the corresponding PPD file. Then, printing will result in sending the fax to the number contained in the job name (which can be set with the -J option of lpr) or in the phone regular option (setting the phone number through a job name now works also when using Samba). The creation of the printer can also be easily accomplished from the CUPS web interface, by choosing a suitable device.

If you cannot set the job name or add a regular option to the command line, you will have to dial the number manually setting a suitable CUPS option.

Note that if you are using fax4CUPS from a graphical user interface you can choose any dialling method (it will be overridden by the graphical front end).

CUPS OPTIONS

media=<size>: Sets the media size--A4 (the default), Letter or Legal (case is not significant).
phone=<number>: Sets the phone number to dial (target fax number). It can be useful to add a space in front of the number, as in phone=" 012345", to prevent CUPS from evaluating the argument as an octal number.
hires: Sets high resolution (204x196 dpi). This is the default.
lowres: Sets low resolution (204x98 dpi).
jobname: The job name will be dialled for you. This is the default.
manual: Sets manual dialling: the fax will go through, but you must manually dial the number.

USAGE

Just print with CUPS on a printer that uses the fax back-end. The default options can be changed, as usual, via the web interface of CUPS.

ERROR MESSAGES

The back-end reports to CUPS, so you can see what happened by checking the printer status with a(ny) browser, as you would do for any other printer. You should always get one of these messages:

Fax sent: Everything is OK, your fax got through.
Busy: efax tried to call, but the called number was busy.
Could not send fax: Generic system error: disk full, wrong permissions etc.
Modem protocol error: efax did not receive the expected response from the modem.
Modem not responding: It says it all.
Fax program terminated: efax was terminated by a signal.

Unknown error: HylaFAX had problems.

Note that in the last cases you should check what went wrong by looking at the CUPS error log and also possibly at the additional log files in /var/log/fax for efax, in /var/log/mgetty for mgetty-fax, in /var/log/capisuit for capisuite-fax, and in /var/log/hylafax for HylaFAX (or, in the latter case, also using faxstat).

When a fax does not go through, the printer is stopped. When you restart it, CUPS will try to send the fax again. If you do not want this to happen, you have to remove the job from the job queue.

CONFIGURATION FILE

The banners printed at the top of each page sent cannot be customised using CUPS options. However, if you create a file named /etc/sysconfig/fax it will be sourced by the efax back-end (for HylaFAX, you must suitably configure the server). In the file you can set the following variables:

FROM: You phone number (max 20 characters--it will appear on the other fax). Some faxes may restrict this string to only digits, spaces, and the "+" character.
NAME: Your name (it will appear at the top of the fax).
FAXPRG: The location of the fax sending command, usually the fax script provided with efax, the sendfax command provided with HylaFAX or the faxspool command provided with mgetty-fax.
LOGDIR: The logging directory (it should be writable by the user that runs the back-end).

Note that the file must be created on the CUPS server. If you prefer a different location for the configuration file you have to edit the assignment of the CONFIG variable in the first lines of the back-end script.

AUTHORS

fax4CUPS was written by Sebastiano Vigna, with additional coding from Glenn Burkhardt, Daniel Glanzmann, Michael Goffioul, Kevin Ivory, Diab Jerius, Arnold Moene, and Leigh Wedding.

This document was created by man2html, using the manual pages.
Time: 14:59:29 GMT, February 10, 2010