Manpage of fax4CUPS
Section: User Commands (1)
Updated: by Sebastiano Vigna
Return to Main Contents
fax4CUPS - A fax back-end for CUPS (Common Unix Printing System)
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/),
mgetty-fax (http://www.leo.org/~doering/mgetty/index.html) or
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).
Sets the media size--A4 (the default), Letter or Legal (case is not significant).
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.
Sets high resolution (204x196 dpi). This is the default.
Sets low resolution (204x98 dpi).
The job name will be dialled for you. This is the default.
Sets manual dialling: the fax will go through, but you must manually dial the number.
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.
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.
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
for efax, in
for mgetty-fax, in
for capisuite-fax, and in
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.
The banners printed at the top of each page sent cannot be customised
using CUPS options. However, if you create a file named
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:
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.
Your name (it will appear at the top of the fax).
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.
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
variable in the first lines of the back-end script.
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.
- CUPS OPTIONS
- ERROR MESSAGES
- CONFIGURATION FILE
This document was created by
using the manual pages.
Time: 14:59:29 GMT, February 10, 2010