Basically, sendfax can work very well with the compiled-in defaults
(from policy.h), sometimes slightly modified by command line
options.
If you use more than one fax modem, possibly of different type, this is very awkward, because the command line will get very long. For that reason, there is a configuration file which will control nearly every detail of sendfax’ behaviour.
It is usually named /usr/local/etc/mgetty+sendfax/sendfax.config.
The config file consists of multiple sections, separated from each other by the keyword ‘port’. All configuration options given before the first ‘port’ statement specify global options, and everything between two ‘port’ statements applies only for the device with the given name (‘port’ takes an argument). Let me show you an example:
# global defaults: # fax station id is always the same fax-id ++49-89-1234 # always have the speaker on modem-init ATM1L3 # port specific: for /dev/tty1a, switch the speaker off port tty1a modem-init ATM0L0 # port specific: for ttyS1, use another fax station id port ttyS1 fax-id ++1234567
As you can see, empty lines and comment lines (starting with "#") are allowed.
Every line in the config file that is not a comment - or empty - starts with a keyword (listed in detail below), followed by a "data" field. In the example above, ‘fax-id’ is the keyword, ‘++49-89-1234’ is the corresponding data, the fax ID for the sending machine. Most data fields are strings, but there are a few boolean and integer items.
The available keywords are (if it’s possible to set this item from the command line, the flag is given in brackets).
fax-devices [-l] ttys
Sets the fax modems to use, e.g. ‘tty1a:tty2a’. Default is
FAX_MODEM_TTYS from policy.h. The device names given here are
used to look up the corresponding port section later. Watch out for
upper-/lowercase.
It is not very useful to specify this in the per-port section, so it is ignored if met there.
modem-init [-m] command
Specifies an ‘AT...’ command that is to be sent to the modem right at the beginning of all modem talk (even before setting the modem into fax mode, so this could be an ‘ATZ’ if you want to reset the modem).
modem-handshake command
Specifies an ‘AT...’ command that will be sent to the modem at the
end of the modem initialization, right before dialing. Do
not use ATZ or such here, since resetting the modem will switch off fax
mode. Default is FAX_MODEM_HANDSHAKE.
modem-type [-C] type
Force the modem command set to use. Default is ‘auto’ (auto-detect,
which may not work on very cheap modems), possible other values are
‘cls2’, for “class 2 only” modems, and ‘c2.0’ for “class 2.0”
faxmodems. Default is DEFAULT_MODEMTYPE. See runtime-mgetty.
modem-quirks bitmask
Same as in mgetty, this can be used to adapt sendfax to
some peculiarities in certain modems. See runtime-mgetty.
reset-after-fail command
Specifies an ‘AT...’ command that is to be sent to the modem in the case of a dialup failure (NO CARRIER, NO DIALTONE). This could be something to reset the modem’s ISDN logic (‘ATZ!’) in case you run into communication problems between modem and ISDN PABX. Should only ever be necessary in very special cases.
max-tries nnn
Specify the maximum number of tries per page if the receiving end reports
reception errors. If nnn tries do not suffice to successfully
transmit a page, sendfax will give up or simply go on, depending on
the setting of max-tries-continue (see below). If this is set to
‘0’, sendfax will ignore retransmission requests and simply go
on. Default is FAX_SEND_MAX_TRIES.
max-tries-continue y|n
After the maximum number of tries for one page are reached, sendfax
can report an error and abort (max-tries-continue no), or go
on with the next page (yes).
For “mission critical” faxes, I’d set it to no, but since the page quality is most often quite good even if reported as “page bad”, the default is yes.
speed baudrate
Set the port speed to use for fax send operations. Usually, ‘38400’ is
a good choice, but a few dumb modems (for example, some based on rockwell
chipsets) need ‘19200’ or even ‘9600’. A few modems can go
higher, but sendfax may not support it, and it may not always work.
Default is FAX_SEND_BAUD.
switchbd baudrate
On some (very few) modems it is necessary to start with baudrate "A" and
switch to baudrate "B" after sending the ‘AT+FCLASS=2’ command. If you
specify this, sendfax will switch from speed to
switchbd right after setting the modem to class 2/2.0. Default is
FAX_SEND_SWITCHBD, I’d recommend not using it unless you’re
sure that you need it.
open-delay msec
A few modems respond to raising the DTR line (when opening the device)
with ‘OK’. This can confuse sendfax, because it will see
this OK as response to the next command. In the log file, you can see if
your modem exhibits this problem if the echo of each AT command
can be seen when waiting for the response to the next AT
command. With open-delay you can give a number of milliseconds to
wait after the device is active until sendfax flushes all incoming
responses and goes ahead.
The only modems that need this so far are an ELSA 33.6 and an ELSA MicroLink 56k, and delaying for about 1500 ms cured the problem.
ignore-carrier y|n
Some misbehaving modems lower the DCD (carrier detect) line briefly between sending multiple pages. Depending on the operating system used, this may cause all subsequent port accesses on this serial port to fail. You’ll recognize it if you get a “weird-looking” sendfax log file that works fine up to the end of the first page, and then aborts with ‘I/O error’ or so.
In earlier versions, you could achieve this by setting
FAX_SEND_IGNORE_CARRIER in policy.h, but this has been
removed. Use the config file instead.
Modems where this is known to be necessary include all USR modems (Courier and Sportsters), some ZyXEL 1496 EG(+), and some GVC models.
The default is ignore-carrier yes, as there are just too many users
out there to read documentation, and it does less harm that way.
dial-prefix command
This is the command used for dialing out. Usually this will be something
simple, as ‘ATD’ or ‘ATDP’, but if you have an unusual setup, it
could also be something like ‘ATX0DP0;X4DT’ (meaning: switch off
dial-tone detection, pulse-dial ‘0’, back to command mode, switch on
dial-tone detection, and go ahead dialing with touch tones). The phone
number will be sent right after the dial-prefix. Default is
FAX_DIAL_PREFIX.
fax-id [-I] your fax phone
specifies the "fax station id" used to identify your fax machine to the
receiving end. Usually this is the telephone number of your own fax
machine, but if you want to (and if your modem support it), you can put up
to 20 alphanumeric characters here, e.g. +1-11-222 Fred. Default is
FAX_STATION_ID.
Watch out: the faxspool program only uses the global
definition from sendfax’ config file, so the fax id it puts on the header
might not be the same as the one transmitted by sendfax, if you use port
specific settings for fax-id in sendfax.config (Paul Sands).
poll-dir [-d] full path
This is used to specify a directory where polled faxes (wheather maps and such) are to be saved into. Default is the current directory.
normal-res y|n [-n]
If set to ‘yes’ or ‘true’ (boolean), sendfax won’t attempt
to make a fax connection in "fine resolution" mode. Normally you won’t need
to use that option, since faxrunq will set the -n switch if
needed. Default is ‘no’
fax-min-speed speed
Sets the lowest transmission speed that the modem will negotiate with the receiving modem. (Not implemented yet).
fax-max-speed speed [-M]
Sets the maximum transmission speed that the modem will negotiate with the
fax receiver. Usually, you don’t need this, as decent modems will pick
the best speed automtically, but sometimes (e.g. for the USR Courier
series) this doesn’t always works, and transmission fails with +FHS:25.
If you see that error, you might want to try fax-max-speed 7200.
verbose y|n [-v]
If set to ‘yes’ or ‘true’, sendfax will output progress
reports on stdout, if set to ‘no’, sendfax will only print
error and warning messages. Default is ‘no’.
debug [-x] nn
controls the amount of information written into the fax log file
(FAX_LOG in policy.h). ‘0’ means "totally silent" (not
even errors are written), ‘9’ is really noisy. I usually use ‘3’
or ‘4’ in normal use, and ‘6’ for debugging. Default is
LOG_LEVEL.
page-header [-h] file
Yet unused (because of implementation shortcomings in all tested modems)
To show you how it will look like, I have included a sample sendfax.config file below. Three modem lines exist on my system, all modems have different initialization and flow control commands, and on one line I have to tell the modem to use pulse dial because the PBX is too old.
# # sample configuration file for sendfax # # global settings verbose y # the modems are attached to the following ports: fax-devices tty1a:tty2a:tty4c # this is my fax number fax-id +49-89-xxxxxx # generic defaults modem-init ATL3M1 dial-prefix ATD debug 4 # port specific overrides # Zoom 28K8 port tty1a modem-handshake AT&K4 # MultiTech port tty2a dial-prefix ATDP modem-handshake # ^^^ this means "no extra command to set modem handshake" debug 9 # ZyXEL port tty4c modem-init ATM1L2 modem-handshake AT&H3