   This is the online documentation for the mgetty + sendfax package.

   Copyright (C) 1993-1997 Gert Doering

Converting fax files
====================

   I recommend getting the `pbmplus' package written by Jeff Poskanzer,
which includes lots of small programs to convert various bitmap formats
into a portable intermediate format (`pbm') that can easily be
converted to fax format with the `pbm2g3' program. Further, it comes
with lots of tools to scale, flip, and otherwise manipulate the `pbm'
bitmaps. Be warned: it includes its own version of G3 conversion
programs (`pbmtog3' and `g3topbm'), so be careful which one you use.
The programs in the `mgetty' package (`pbm2g3' and `g32pbm') behave
slightly different (that is, they work!), and are significantly faster.
Note that the `pbmplus' package does not include a graphical front end.

   The `pbmplus' package can be found on most major FTP sites, e.g. on
ftp.x.org in the `/contrib' directory. See ftp.

   If you want to view the images using X11, you should get one of the
many image viewers, like `xview', `xloadimage' or `xv'.  See
Fax-Tools. A simple, but very fast fax viewer can be found in
`mgetty/frontends/X11/'.

   Here are some examples for viewing fax files using `g32pbm':

   * You can print a fax on a PostScript printer (try `lpr -Pps' if you
     don't have `lp'):

          cat $faxfile | g32pbm | pnmtops -noturn | lp -dest postscript

   * or on an Epson-LQ, scaled for fine resolution (use -yscale 1.84 for
     normal resolution):

          cat $file | g32pbm | pnmscale -xscale 1.76 -yscale 0.92 |\
              pgmtopbm | pbmtodot -360x180| lp -o epson -

   * or you could view it using X11 via one of the following commands:

          $ viewfax -v $file

          $ cat $file | g32pbm >/tmp/fax.pbm ; xloadimage /tmp/fax.pbm

          $ g32pbm $file | xv -

   There are three easy ways to create g3 fax files, either use `pbm2g3'
(included in this package. Do not use `pbmtog3' from the pbmplus
toolkit. *Note:* See pbmtog3), use GhostScript (GNU Software, can
be found on prep.ai.mit.edu) which contains a "digifax" driver that
will produce the required format, or try Chris Lewis' `hp2pbm' package
which will convert HP Laserjet print files into g3 fax files (`hp2hig3'
program).

   Once you have the right tools, there are lots of ways to create fax
files for a wide variety of applications. Here are some examples:

   * Ascii files can be converted using `pbmtext | pbm2g3' (use a
     *large* font, and don't convert texts longer than about 50 lines).
     Alternatively, you can convert ascii files to PostScript using
     `psify', the `pslp.ps' program from the ghostscript distribution,
     or similar tools, and feed their output into GhostScript.

   * PostScript input can be converted by GhostScript (version 2.4 or
     higher), using the digifax (`dfaxhigh' and `dfaxlow') drivers.  It
     will generate a plain g3 file with a 64 byte additional header,
     which will be skipped automatically. (You have to generate
     separate g3 files, one per page).

     A typical call to ghostscript would look like this:

          gs -sDEVICE=dfaxhigh -sOutputFile=/tmp/fax.g3.%d yourdocument.ps

     Do *not* use the "tiffg3" or similar drivers, they will create
     output files with headers that sendfax does not understand, thus
     causing the receiving fax machine to reject the data (it will
     assume that the transmitted headers are garbled data).

     If you use Ghostscript version 3.01 and up, you can use the `faxg3'
     driver as well, its output is identical to the output of the
     `dfaxhigh' driver except for the 64 byte header.  Besides this,
     there should not be any difference.

     I have observed that with Ghostscript 5.01, the output of the
     `faxg3' driver is rendered better than that of the `dfaxhigh'
     driver. In addition, the former is compiled-in by default, while
     the latter is not.  Thus, the default driver used by `faxspool' is
     now (starting with 1.1.7) the `faxg3' driver.

   * Bitmaps can be converted using the `pbmplus' tools, but you'll have
     to do the proper scaling by hand. Use a pipeline with `pbm2g3' at
     the end.

   * TeX dvi files can be converted to PostScript using `dvialw' or
     `dvips'. If you want to get the best possible output quality, you
     can use Metafont to create a set of 204x196 dpi fonts, which will
     look a lot better than scaled 300 dpi fonts (look into
     `contrib/dvi-fax' for instructions how to do this). You can use
     the `epsf' macros to include encapsulated PostScript files, e.g. a
     scanned signature.

   * Another way for TeX file conversion is Ralf Schleicher's `faxdvi'
     package, found at

     `ftp://ftp.leo.org/pub/comp/networking/communication/modem/mgetty/faxdvi-1.1.tar.gz'.
     Don't ask me about, ask him!

   * HP-Laserjet files can be translated with Chris Lewis' `hp2pbm'
     package. It contains a program `hp2hig3' that will read
     HP-Laserjet `PCL4' files and produce G3 output.

     *Warning:* the G3 files that hp2hig3 emits lack the leading EOL
     code, thus causing `sendfax' to complain and possibly fail. As a
     quick fix, you can pipe those files through `g3cat', it will fix
     the data.

   A rather crude sample conversion program (`faxcvt') is provided in
the fax directory.

   Better conversion, including guessing of the format of the input
files, is done by the `faxspool' program, also provided in the fax
directory. See Queuing.

Receiving faxes
===============

   If everything has been set up properly, faxes will be received
automatically. Obviously, mgetty has to be listening to the proper modem
line. Then, if a fax arrives, mgetty will store it in the directory
`FAX_SPOOL_IN' and send a mail to `MAIL_TO' (defined in `policy.h').

   The file name format is somewhat tricky (the reason behind it is
that I have to create something unique without using `mktemp()',
because that would make it impossible to find out which pages belong to
which fax). It is:
     f<res><seq><line>[-<remote id>].<pagenr>
   `<res>' is `n' or `f', depending on the resolution of the fax.
`<seq>' is a sequence number, 7 digits wide, somewhat related to the
reception time. `<line>' are the last two letters of the tty device,
e.g. `S1'. If the sending side specified a fax station id, it comes
next, after a leading dash (all blanks are replaced by dashes).
Finally, after a dot, you'll see the page number.

   If you want to process incoming faxes automatically, for example,
print them, re-send them to another fax, send them by mail to you when
you're on vacation, you could use what I call "notify programs":

   If you define `FAX_NOTIFY_PROGRAM' in `policy.h', mgetty will call
this program (or shell script) when a fax has been completely received.
It will be called with the following command line arguments:

     FAX_NOTIFY_PROGRAM <HANGUP CODE> '<SENDER ID>' <NR OF PAGES> \
                        <FILE NAME PAGE 1> <FILE NAME PAGE 2> ...

   <HANGUP CODE> is 0 if the receive was successful, non-zero
otherwise.  <SENDER ID> is the fax identification string received from
the other side.  <FILE NAME PAGE (I)> is the full path name for each
received page.

   A sample command line might look like this:

     /usr/bin/new_fax 0 "+49 89 3243328" 1 /var/spool/fax/ff-01.a123

   Such a "notify program" could print out the fax, convert it into a
MIME metamail and send it away, display it in an X window (this a
little bit tricky), or whatever. (A friend of mine uses it on his Linux
box to call a program that will make the keyboard LEDs blink when a fax
has arrived - as you can see, maximum flexibility is possible).

   I provide a few examples (printing on HP laserjet, mailing as
gzip'ed, uuencoded pbm file, ...) in `samples/new_fax.*'

   If you have the `dialog' shell tool, you can use the `faxv' program
("faxview") that I provide in `frontends/dialog/faxv' to browse through
all faxes in the incoming spool directory, view them, print them,
rename and move them, .... `faxv' is really more a sample program to
show you how to do it, and you have to configure the X11 viewer and the
printing program in the source code, but I use it for my faxes, and it
works. Because of limitations on some operating systems, the list of
faxes displayed is limited to the last 50 faxes received.

Basic `sendfax' usage
=====================

   Sendfax is very primitive--no spool management, no format conversion,
etc.  It is designed to be able to send exactly one fax (consisting of
multiple pages) to exactly one fax machine, but it is usable from
within shell scripts.  Its input are pages in "g3" format, either
created with ghostscript or with pbm2g3.

   It is called like this:

     sendfax [-v] [-n] <PHONE-NUMBER> <FAX PAGE(S)>

   e.g.

     sendfax 0893243328 /tmp/to_gert_1.g3 /var/spool/fax/outgoing/picture.g3

   It will then attempt to open the fax device and send all the pages to
the remote fax machine, in the given order.

   It will print little or nothing to stdout or stderr, except if it
cannot find or open one of the named files, or if some transmission
errors occur.

   (There are a few stubs in the code to put headers on the pages at
run-time, but since most class 2 faxmodems do not implement the command
set properly, putting a header on a page does not work with them -
because of that, I had to disable the corresponding code.  `faxspool'
works around this problem by using `g3cat' (see Fax-Tools) to
"paste" a header line on top of each page)

   If you specify `-v', sendfax will output more verbose progress
messages.

   If you specify `-n', it will try to send the fax data in normal
resolution, default is fine resolution. (No conversion is done, so make
sure that your input data is already in the proper format.)

   Detailed reports can be found in the log file (usually
`/var/log/Faxlog') -- but they may be of little more than technical
interest since virtually all conversation with the fax modem is logged.
(Nevertheless, if you send me any bug report, *please include all log
files*)

   *Warning:* Watch sendfax closely when sending the first few faxes. I
had it abort a transfer a couple of times, not being able to recover
and *not* hanging up the modem (the modem was completely locked up,
with the phone line off-hook)! In my case, it was a problem of the
modem that went away when I upgraded the firmware. Very old ZyXEL
releases sometimes stopped the DTE and forgot to re-start it again.

   The return codes of the sendfax program were chosen to make it easy
for external programs (i.e. faxrunq) to decide whether to try again or
not:

      0: all pages transmitted successful
      1: error on command line
      2: cannot open fax device (typically happens if fax device is
         locked, but could also be a permission problem)
      3: error initializing the modem
      4: dial failed, "BUSY"
      5: dial failed, "NO DIALTONE"
     10: dial failed, "ERROR" or "NO CARRIER"
     11: waiting for XON failed (should never be seen)
     12: transmitting page(s) failed (or polling failed)
     15: some catastrophe hit (termination signal or blocked modem)

   If the error code is less than 10, the attempt didn't cost anything,
so an external program should try again to send the files. If it is 10
or higher, the failed attempt probably cost something, and the program
should decide whether to try again (thus expending more money) or mail
the operator and tell him something went wrong. My `faxrunq' program
will suspend the job after five unsuccessful tries with error codes >=
10.

Fax polling using `sendfax'
===========================

   Sendfax can also be used for fax polling (that is, you call someone
and initiate a fax connection, and then *receive* a document. Don't
confuse it with fax-on-demand, this is something different), the syntax
is:

     sendfax -p <FAX-NUMBER>

   or for sending a fax and then switch to polling:

     sendfax -p <FAX-NUMBER> <SEND-DOCUMENTS>

   (in this case <SEND-DOCUMENTS> are sent, and then the documents from
the other modem are polled, if there are any)

   the received pages are written to the current directory, so make sure
you have write access...

   *Warning:* Fax polling does *not* work with ZyXEL Modems with ROM
releases before 6.00 - with the 6.01 and 6.10 Eproms it works, but
6.11a is broken again. 6.12 and 6.13 work fine.

   It definitely doesn't work with some Rockwell-based Faxmodems
(Supra), since many versions of this chipset does not support polling.
Some work, though, so you simply have to try it.

   Could anybody try this with an Everex Faxmodem?

Automated fax queuing
=====================

   For fax spooling and processing the queue, four additional utility
programs are provided:

   * `faxspool' will spool a number of files (accepting various formats)
     and put them into the fax spool directory. Its syntax is:

          faxspool [options] phone-number input-file(s)

     `phone-number' can be an alias, in this case the private and global
     alias files `$HOME/.faxnrs' and `/etc/mgetty+sendfax/faxaliases'
     will be searched for a line starting with this alias. The
     remainder of this line will then be used as fax number.

     `faxspool' interacts with the `file' program and `/etc/magic' to
     determine the file type of the input files. If your `/etc/magic'
     lacks entries for the various bitmap files, take a look at
     `fax/etc-magic', it contains the most important magic numbers.

     `faxspool' reads the text to put on top of each fax page from a
     text file, `faxheader', located in `/etc/mgetty+sendfax/'. This
     file must contain pure ASCII text. Some tokens are replaced by the
     actual values: @T@ becomes the destination phone number, @P@
     becomes the actual and @M@ the total page number, and @U@ is
     replaced by the user name. If your fax modem cuts of a few lines
     on top of each page, it may be a good idea to put a blank line
     before the header line itself, and it is also a good idea to
     indent the line about 5 spaces.

     For the available options, please read the `faxspool.1' man page.

   * `faxrunq' will read this directory and try to send all the faxes
     queued there (time scheduling is available, but primitive). If
     faxrunq succeeds, the fax is deleted and the sender is mailed. If
     it does not succeed after five tries (`BUSY' or a locked fax modem
     do *not* count for this) it will send a mail and not try any
     further to send this fax. (This should prevent your faxmodem from
     making you bancrupt...).

     `faxrunq' should be called at regular intervals from `cron' to
     process the queued jobs. It should only be executed by *root*, to
     make sure that all the files in the fax spool directory are read-
     and writeable.

   * `faxq' will display all entries in the fax queue. If called with
     the `-o' parameter, it will also display completed, but not yet
     deleted jobs (JOB.done files). If called with the `-v' parameter,
     the output will be more verbose.

     Jobs that are just being sent are not shown (`faxq' doesn't see
     locked jobs)

   * `faxrm' can be used to remove fax jobs from the queue. It is called
     with the job ids of the to-be-removed faxes as command line
     argument. The job ids are those that `faxq' returns.

   These utilities do still have some rough edges, but I think they are
fairly usable by now.

   Earlier variants of those utilities had to be configured in the
source code, from release 0.20 on, this is done by `make'. Please check
the scripts nevertheless, whether all directories and files are set up
properly.

Additional tools for working with g3 files
==========================================

   Some additional tools are provided for manipulating G3 fax files:

   * `g3cat' (in the `g3/' directory) concatenates multiple G3 fax
     files. It accepts "raw" g3 files and digifax files and outputs a
     "raw" g3 file without headers. Its syntax is analogous to `cat',
     except that you *have* to specify `-' to read from `stdin'.

     `g3cat' recognizes two flags: `-l', to separate the fax files with
     a thin black line, and `-a' to byte-align the end-of-line codes in
     the file (Warning: some modems do not like this).

   * To convert an incoming fax to Jef Poskanzers `portable bitmap'
     (`pbm') format, you can use the `g32pbm' program that is also
     provided in `g3/'. It's advantages over Jef's `g3topbm' program
     are that it's approximately five times faster and takes only one
     eigth as much virtual memory (on machines with low virtual memory,
     it can thus be up to 100 times faster!). Its disadvantage is that
     it produces only "raw" (i.e., binary) `pbm' files; and it's not as
     stable when handling erroneous `g3' data (means that if one line
     is severly corrupted, it can happen that the next line will not be
     decoded properly. The rest of the file will then be OK again).

     Syntax:
          g32pbm [-r] [-s] [-l] [-d <dpi>] [g3-file]

     If no g3 file is specified, standard input is used.

     The `-s(tretch)' option causes `g32pbm' to double each row of the
     g3 file.  You can use this to adjust the aspect ratio of a "normal"
     resolution fax file to match that of a "fine" resolution fax.  Of
     course you can use other `pbmplus' tools for this instead, but
     `-s' is sure to be faster.

     If you have a HP Laserjet printer, you can make `g32pbm' output HP
     LJ data with the `-l' switch. The desired resolution is chosen with
     the `-d 75|150|300' switch.

   * For the other direction, I have provided a `pbm2g3' program that
     will convert Jef Poskanzer's Portable BitMap format into G3 fax
     data suitable for faxing with `sendfax'. The `pbm' files can be
     produced by various sources, e.g. drawing programs (`xpaint'),
     bitmap manipulation programs (`xv'), or simply be converted from
     other file formats by means of the `pbmplus' tools.

     As above, my variant is a lot faster than Jef's, and unlike his, it
     produces g3 data that adheres to the T.4 standard (if you don't
     fiddle too much with the options...), so you don't have to apply
     any patches to make it work together with `sendfax'.

     Syntax:
          pbm2g3 [-r] [-a] [-w page with] [-h blank lines] [pbm-file]

     if no pbm file is specified, standard input is used.

     For a detailed description, see the `pbm2g3(1)' man page.

   * `viewfax'. To view G3 data files under X11, Frank D. Cringle has
     written a very nice and fast tool that will display the files on
     screen, turn them, zoom them in and out, ...

     The source code can be found in the `mgetty/frontends/X11'
     directory.  It's not (yet) built and installed by default, but
     it's straightforward.

     For a detailed description, see the `README' and `viewfax.man'
     files in that directory.

   * To convert an incoming fax into X-Windows `xwd' bitmaps, you can
     use Chel van Gennip's `g3toxwd' program, found in the `contrib/'
     directory.

   * If you want to print out faxes on a HP laserjet printer, you have
     two opions: you can use Chel's `g3tolj' program (also in the
     `contrib/' directory), or you use my `g32pbm' program with the
     `-l' option, which will make it output LJ data.

Using an external fax as a scanner
==================================

   It is possible to tell mgetty to answer the phone even if it is not
ringing (I call this "virtual rings"). Just send mgetty a signal
`SIGUSR1', this is usually done with `kill -USR1 <MGETTY-PID>'.  Mgetty
will then pick up the phone and try to make a connection.

   If you have a normal fax machine connected to the fax modem, it
should be possible to have that fax machine dial any digit (to turn off
the dial tone), and then have mgetty answer the phone to receive the
"incoming" fax, thus using the fax machine as scanner without paying
for a call. For a description of an sample setup (thanks, caz!), please
see `doc/scanner.txt'.

   Whether it works may depend on your phone company's setup, but it
should.

   If you have a modem that has a `data/voice' button, it should also be
possible to hit that button to make the modem pick up the phone. Mgetty
will automatically notice that and handle it properly. (I've tested this
only with ZyXELs - could somebody else please test this with other modem
types and send me a logfile? Thanks)

Runtime configuration for sendfax: `sendfax.config'
===================================================

   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 `/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

   - `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.

   - `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"
     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 I recommend using the
     config file instead.

   - `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'

   - `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

Voice Operations
****************

   This chapter explains how you can use mgetty to implement an
answering machine if you have a modem that understands the voice
command set (i.e. the ZyXEL).

   The first version of these extentions was written by Klaus Weidner.

   Since February 1995 these extentions are now developed and maintained
by Marc Eberhard (Marc.Eberhard@Uni-Duesseldorf.DE) so please send
email about the voice features to him, not to me.

   *I have removed the whole chapter from the documentation for now, as
the voice stuff has changed too much, but the docs were not updated
accordingly. Please see the programs and examples in the `voice'
subdirectory for ideas how to get it going. Configuration is explained
in `voice.conf'*.

   The `voice' subtree is *NOT* included in the official release 1.0,
because of the lack of documentation, and because Marc thinks it's not
stable enough yet.  It *is* included in the 0.99 and 1.1 beta
development trees, so if you want to play with it, get one of those
version. *BUT* keep in mind what "beta" means: lacking documentation,
problems, crashes, whatever.

Common problems and solutions (TROUBLESHOOTING)
***********************************************

   This chapter tries to describe some known problems that can occur
when installing or using this package. Don't worry, most of these have
been solved.

Modems
======

   This section describes problems that can occur when using various
types of modems. Unfortunately, the class 2 fax implementations vary
quite a bit between different manufacturers.

   Many of the instructions for certain modem types below still refer to
changing `#define's in `policy.h' instead of listing the appropriate
`mgetty.config'/`sendfax.config' lines, mainly because I haven't had
the time to figure it out myself and didn't get enough feedback from
config file users yet.

Problems common to many modem types
-----------------------------------

   * Disable auto-answer in the modem (`ATS0=0'), because it will
     interfere with the manual answer done by `mgetty'. If you *have*
     to use auto-answer, set the `mgetty' ring-counter (`-n <i>') high
     enough that `mgetty' will never try to answer the phone manually.

   * Make sure that your modem is set to return *verbose result codes*,
     that is, set `ATV1'. Otherwise, the modem won't return `CONNECT'
     or `RING' but `1' or `2' as result code, and mgetty definitely
     doesn't understand that. By default, `mgetty' sets `ATV1'
     automatically, but if you change the init sequence, watch out for
     this.

   * Make sure that your modem is set to the proper dialing type
     (`ATT&W' for touch-tone, `ATP&W' for pulse dialing) -- `sendfax'
     uses `ATD...' to dial out, assuming that the modem knows which
     dialing method to use. Alternatively, set `FAX_DIAL_PREFIX' in
     `policy.h' or `dial-prefix' in `sendfax.config' accordingly.

   * If the default modem initialization string in `policy.h', which is
     quite generic, doesn't work for your modem, you can either change
     it according to your needs, or store all settings in the
     non-volatile RAM (NVRAM) inside the modem and change the
     initialization strings to plain `ATZ' (modem reset).

     These settings ought to work with most modems:

     `ATS0=0': do not auto-answer, `E1': echo on, `Q0': send modem
     responses, `&D3': reset on DTR->low.

     The following, for example, are ZyXEL specific things:

     `&H3': set handshake to RTS+CTS, `&N0': "multi-auto" connect,
     accept all known protocols, `&K4': enable v42bis/mnp5 compression.

     Naturally, you can use any init string you want (but the modem has
     to return OK) -- check with your modem manual.

   * On USR and some ELSA Modems, it has occasionally been reported
     that the initialization phase runs through fine, but incoming
     `RING' messages are not recognized, and mgetty complains about
     `junk on the line'.  In all those cases, it were baud rate
     problems. The modem was initialized with an init-sequence of `""
     ATZ OK' only. Problem with this is, after ATZ, the modem changes
     to the DTE baud rate that the last AT&W command was sent with. If
     that baud rate differs from the `mgetty' port speed, a RING won't
     be detected.  Fix is easy: send another `AT' command after the
     `ATZ'. For example, make the init sequence `"" ATZ OK AT OK'. The
     second `AT' command will set the modem back to the mgetty port
     speed.

   * Some modems do not like the `+FDCC=1,5,...' command.

     In the latest version, mgetty and sendfax will automatically
     detect if the modem isn't able to do 14400 bps for faxing and will
     use 9600 bps -- `+FDCC=1,3,...' -- instead. So don't worry about
     the error message.

   * Sometimes mgetty cannot initialize the modem, it times out waiting
     for the first `OK'. (USR Sportsters are known to hit this).

     I assume that the problem is the DTR-induced modem reset before
     sending the first `+++ATH' to the modem.  I know that some modems
     need quite a lot time after a reset, so this should go away if you
     add more delays before sending the first string to the modem:

     In `conf_mg.c' (line 38 or so) change

          char *def_init_chat_seq[] =
                     { "", "\\d\\d\\d+++\\d\\d\\d\r\\dATQ0V1H0", "OK",

     to

          char *def_init_chat_seq[] =
                     { "", "\\d\\d\\d\\d\\d\\d+++\\d\\d\\d\r\\dATQ0V1H0", "OK",
                             ^^^^^^^^^ additional delays here

     Or, if you don't want to modify the code, just set the `init-chat'
     sequence in `mgetty.config' accordingly.

     Alternatively, you can just switch off the toggling of DTR (since
     the HUPCL flag is set, it should work as well) by setting
     `toggle-dtr no' in `mgetty.config'.

   * Some operating systems send their commands too fast for some
     modems (Linux is known to do this). In that case it may be
     necessary to increase the delay times for `DO_CHAT_SEND_DELAY' and
     `FAX_COMMAND_DELAY' in `policy.h'.

   * Some Modems toggle DCD between pages, possibly correlated to the
     presence of the "high speed" page transmission carrier. `sendfax'
     normally runs carrier-sensitive, and will then get a lot error
     messages in the `read' and `write' calls, logging them as `I/O
     Error' or something similar when sending the first or second page.
     To work around this, set `ignore-carrier true' in `sendfax.config'.

     If you run into this problem, `sendfax' will complain about `Error
     +FHNG:-5 (Unexpected hangup / read() error / write() error)' and
     abort.

   * Some modems do not understand `ATH0', responding with `ERROR' to
     that. Just modify the `init-chat' setting in `mgetty.config' to
     send `ATH' instead of `ATH0'. This will fix it.

   * Faxing to some modems works very well, faxing to "normal" fax
     machines fails all the time.

     In most cases, this error is caused by badly created G3 files. If
     you use the old `pbm2g3' program, or an old copy of `hp2hig3', it
     will cause bad G3 files.

     Recently, a new problem appeared for postscript files created by
     certain programs that insist on setting their ideas of the page
     size (some versions of WinWord, FrameMaker, and dvipsk). If used
     together with ghostscript 3.*, the resulting G3 file's width isn't
     correct. For a fix, try creating the postscript file with a
     different program, use a newer version of ghostscript, or an older
     one (2.62 is fine). Quite often it helps to add `-sPAPERSIZE=a4'
     to Ghostscript's command line (in `faxspool').

     With a `mgetty' version later than June 1996, the `g3cat' program
     should take care of this problem, fixing the line width
     on-the-fly. It will print a warning, to tell you about the problem,
     though. So if you get this warning, faxing should work, but you'd
     better check all your programs anyway.

   * Some other Modems cannot (or not properly) distinguish between
     calling faxes and calling modems.

     Some of them just refuse to answer both, only recognizing one and
     failing on the other (NO CARRIER) -- in that case, there's nothing
     you can do to make it receive both (except making the manufacturer
     fix it). What you can do is to force it to receive always fax or
     always data (what is more important for you). Data-Only can be set
     by the `data-only' keyword in the configuration file, and Fax-Only
     with the `fax-only' keyword.

     In some cases, those problems may be caused by the modem
     forgetting the `AT+FAA=1' command if it receives any other command
     after it. To fix it, it may help to change the "answer chat
     command" in the config file to

          answer-chat "" AT+FAA=1;A CONNECT \c \r

     if this helps for your modem, please tell me so, and I'll include
     it into the documentation.

     Some other modems can distinguish the different call types *most of
     the time*, but some 2400 bps modems mysteriously fail. That may be
     caused by some - strange - modems sending a certain tone when
     *calling* the other side, and the receiving end mistaking that for
     the fax calling tone.  Arne Marschall said about that: "...Or try
     calling your modem with your phone and whistle. If it says "+fcon"
     it is one one those which can't deal with modems using a calling
     tone" - try it.

     Another, quite simplistic approach of some modem manufacturers is
     that they distinguish Fax by waiting until the time specified in
     register `S7' (time to carrier) runs out, and then switching from
     data to fax carrier. That normally works quite well - if the other
     side is patient enough to wait that long .... For example, if the
     modem switches to fax after 60 seconds have passed, and the caller
     has a timeout of 50 seconds, it will definitely fail. If in doubt,
     try setting `ATS7=30' (but only if all else fails - and don't ask
     *me* why it doesn't work...)

   * Except if you feel sure that your modem needs less, do not try to
     send or receive faxes with a port speed of less than 19200 bps.
     Since fax transmission is synchronous (no start and stop bit!),
     you need at least 12000 bps on the Computer-Modem line to transmit
     9600 bps on the line.

   * For some modems, incoming faxes are detected properly, but mgetty
     times out about two minutes later in `fax_wait_for(OK)'. Most
     likely, the `FAX_RECEIVE_SWITCHBD' (`policy.h') resp. `switchbd'
     (`mgetty.config') speed is set wrongly. Nearly all cheapo modems
     (e.g. Rockwell-Chip based ones) step to 19200 bps upon fax
     reception, and setting this option to `19200' will tell mgetty
     about it. Better modems have no need for that, so if you have
     defined it and your modem does *not* change bit rates, it won't
     work either.

     If you have this problem, your log file for an incoming fax call
     will look like this:

          09/21 09:55:48 yS1  waiting for ``RING''
          09/21 09:55:48 yS1  got: [0d][0a]RING ** found **
          09/21 09:55:48 yS1  send: ATA[0d]
          09/21 09:55:48 yS1  waiting for ``CONNECT''
          09/21 09:55:48 yS1  got: [0d][0a]ATA[0d][0d][0a]FAX
          09/21 09:55:50 yS1  found action string: ``FAX''
          09/21 09:55:50 yS1  start fax receiver...
          09/21 09:55:50 yS1  fax receiver: entry
          09/21 09:55:50 yS1  fax_wait_for(OK)
          09/21 09:55:56 yS1  fax_wait_for: string '+FCON'
          09/21 09:57:50 yS1  Warning: got alarm signal!
          09/21 09:57:50 yS1  fax_read_byte: read returned -1: Interrupted system call
          09/21 09:57:50 yS1  fax_get_line: cannot read byte, return: Interrupted system call

   * For a couple of modems, you can find initialization and setup
     hints in the file `doc/modems.db'. Just browse through it, maybe
     you'll find something helpful. (You're welcome to provide entries
     for modems not yet in the list).

   * Sometimes, very weird things happen upon login (that is, long after
     `mgetty' has done its work), for example, /bin/login blocks
     infinitely, the caller is thrown out immediately again, or the
     shell won't notice a logout, etc.

     Quite often, this is caused by a modem not setting the data
     carrier detect (DCD) line properly (properly meaning here
     "reflecting the actual line conditions"). On most modems this is
     done with the `AT&C1' command.

     Another possibility are too long or otherwise broken modem cables
     that corrupt the signals, and introduce noise on the modem control
     lines. Flat cables are famous for this, use round, shielded modem
     cables, no longer than necessary.

   * `mgetty' will complain loudly if you switch off your modem.

     Well, what should I say, this is a feature :-) - I think that
     mgetty should detect and complain if a modem is not working, and
     if you switch it off, it is most definitely not working.

     Others argue about power consumption, noise, lights, and
     everything - but I refuse to make mgetty less noisy in case of a
     powered-off modem. But, as usual, there is a way around this
     (which is what came out of a discussion with Rolf Ade recently).
     You just create a file, `/etc/nomodem.ttyS1', or however you want
     to name it, when you intend to switch off your modem.  Instead of
     running `mgetty' from `/etc/inittab', you run a "wrapper" script
     that will wait until the nomodem file disappears, and then starts
     `mgetty'. That way, you can just prevent `mgetty' from starting
     when you don't want it to.

     The wrapper is easy:

          #!/bin/sh
          #
          while test -f /etc/nologin.ttyS1
          do
             sleep 60
             done
          exec /usr/local/sbin/mgetty ttyS1

     A more advanced wrapper program could, for example, check the
     status of the DSR line to determine whether the modem is active,
     but as so many systems have flakey DSR detection (Solaris, AIX), I
     didn't bother to invest much time into this only to find that it
     isn't working reliably anyway. It's not difficult, though.

ZyXEL
-----

   First of all, yes, ZyXELs tend to somewhat non-deterministic
behaviour - most modems work perfectly with `mgetty+sendfax', a few
don't, and I do not always find out what's wrong.

   If it works first, and then suddenly stops working, it does quite
often help do to a *full* modem reset, that is, switch it off, press the
DATA/VOICE key, switch it on again and hold the key for about 20
Seconds.  (That's for the 1496E and E+, for other models, it works
differently, check you manual). That cured the problems in many cases.

   The same holds true after a firmware change: always do a full modem
reset in case you change the ROM version!

   Do not use non-plus ZyXELs (the "slower" ones) for faxing with DTE
speeds above 38400 bps, I got a report that it won't work.

   Do not use the `S18' register, set it to 0. Its purpose is for dumb
`getty' programs where the modem has to change its baud rate back to a
certain value if some other program has modified it. Since `mgetty'
will reinitialize the modem anyway if another program has dialed out,
the `S18' register cannot improve anything, it can only harm (e.g., if
it is set to `3', the modem will send any `RING' with 19200 bps --
imagine what happens if `mgetty' sets the port to 38400 ...)

   If you want to use Caller ID (and have subscribed to it), add
S40.2=1 to the modem initialization string [For the ZyXEL 2864, this
might be S84.4=0, but check with your modem manual!].

   *Warning:* If you use a very old ZyXEL and try to send some complex
graphics (the "tiger.ps" example file in the GhostScript package is
known to produce this), it may lock up. This is because the old ZyXEL
firmware had *lots* of bugs concerning hardware flow control--sometimes
the ZyXEL just forgot to raise CTS when it can accept data again. The
symptoms are that the transmission hangs, no modem LEDs are flashing
any more, the logfile won't grow any more and the receiving machines
hangs up after printing a partial page.

   This bug has been fixed in ROM release 6.01, so you should consider
upgrading your eproms if you run into this. With ROM release 6.01 and
6.11a, it works correctly (a hundred-odd faxes sent without problems).

   Rom releases I've never been able to make `sendfax' work reliably are
6.00 and 6.10 (6.10a works), and various 5.0x releases.

   Fax polling (both server and client side) is broken in ROM 6.11a.

   The very latest ROM releases, 6.12, 6.13 and 6.15, work perfectly in
every possible aspect. I tried fax sending, receiving, polling, data
calls, ... - and everything simply *works*!

   The latest ZyXEL roms can normally be found on ftp.zyxel.com, in
`/pub/other/zyxel/r*'.

   Some models, seemingly only the `EG+' (german telekom approved),
toggle the DCD line during the pre-page handshake, thus causing
`sendfax' to abort (with a "I/O error" during read/write operations).
You can work around this by defining `ignore-carrier true' in
`sendfax.config'.

   ZyXEL modems can do security callback (`AT*Gi' with `i' > 0).  With
ROM releases up to 6.11a, this doesn't interact very well with mgetty.
If you want to use it anyway, send me a note and I'll describe what to
change (but be warned, mgetty operation will become somewhat unreliable
by those changes!). With 6.12, it works very good.

   Oh, one additional note: ZyXELs can do voice recording and playback.
Klaus Weidner and Marc Eberhard have written voice handling tools, to
turn your modem into a sophisticated answering machine. Yo can finde
this tools in the `voice' subdirectory. (NOTE: In version 1.0, I
haven't included the stuff, because the docs are heavily lacking and
Marc thinks it's not ready yet. Get 0.99 or 1.1-betas to play with
voice).

   Josef Wolf (jw@raven.inka.de) has added some comments about the ZyXEL
Eproms (I don't know whether it's true or not, ask him or
support@zyxel.com):

   Most EPROMs require /PGM and Vpp to be Vcc while in ROM-Mode. On
ZyXELs these two pins are removed in the socket so the pins are
_floating_. This treatment is *out of spec* for *any* EPROM. The
TI-Types originally used by ZyXEL seem to tolarate this treatment. But
most other EPROMS won't work properly. There are two solutions to this
problem:

   1.) use the types which zyxel used. (could be troublesome to find
some)

   2.) take two sockets, solder jumpers between pins 1, 31 and 32
(these are     /PGM, Vpp and Vcc) and place them into the original
sockets before     inserting the EPROMs.