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

   Copyright (C) 1993-1997 Gert Doering

Telelink IMS 08 Faxline+ Modems
-------------------------------

   Thanks to friendly support by MVS, Germany, I got a Telelink IMS 08
modem for testing and was able to adapt `mgetty' accordingly.

   The modems factory defaults are very good, so it's sufficient for
`mgetty' operations to set `init-chat' (in `mgetty.config') to ATQ0V1E0
OK AT&F2S0=0&D3X6&K3 OK, and `switchbd' to 19200 (yep, it switches baud
rate.  Stupid, but true). After that, receiving fax + data calls works
fine.

   Fax sending is not that trivial. Basically, it works after setting
`modem-handshake' to `AT&K3'. `FAX_SEND_FLOW' (in `policy.h') can be
anything that the host machine supports (because the modem does both
Xon/Xoff and RTS/CTS handshake simultaneously).

   Unfortunately, a few problems remain:

   - faxing multi-page faxes to ZyXELs with ROM release 6.11a doesn't
work (fails on the receiving end with +FHNG:100 and on the sending side
with +FHNG:50).

   - faxing to some paper fax machines fails completely, for others,
"only" complex graphics (like the Ghostscript-"tiger.ps") fail. This
one can be partially cured by adding lots of padding zeroes into the
fax data (`g3cat -p 24') - but that's unelegant, not complying to class
2 specs, and not supported (besides, it still doesn't work all the
time). Maybe later versions of `sendfax' will do the padding
automatically.

   I recommend against using this modem with sendfax. In addition to the
technical problems, their customer support (at least, that of the german
distributor MVS) is basically non-existant. (I wrote them four times
describing my problems with the modem, and never got an answer).

Rockwell-based modems, e.g. Supra
---------------------------------

   As far as I know, sending or receiving are no problem (although you
have to use 19200 baud when in class 2 faxmode - set `speed' to `19200'
in `sendfax.config', and set `switchbd' to `19200' in `mgetty.config'.
Remember to change the modem initialization strings to the proper
values for your modem, that is, ATQ0V1E0 OK AT&K3S0=0 OK.

   Especially for the `SupraFax' modem, I've been told that you have to
set `modem-handshake' to `AT&K3' and initialize the modem with
`AT&S0&D2&K3'. Since the modem does not like being reset with DTR->low
(do *not* use `&D3'!), an `ATZ' in the first initizalization string in
`mgetty.c', to reset the modem into a known state, is a good idea, too.

   (Thanks to Christof Junge, chris@cj.in-berlin.de, for trying out
several weeks until everything worked!)

   Some other SupraFAX Rom releases seem to forget that they are set to
use RTS/CTS handshake if a `+FCLASS=0' is sent to them. I think it
should help to store the `AT&K3' into NVRAM, but maybe you have to patch
`mgetty.c'. See `contrib/readme.supra' for details.

   Fax polling does not work because the Rockwell chipset does not
support it.

Zoom VFP/VFX 24K FaxModem (V.FAST modem, 24,000 bps)
----------------------------------------------------

   For the Zoom V.FAST 24,000 modem, you should change `init-chat' to
`ATE1Q0V1 OK AT&FS0=0&C1&D2W1 OK' (see the manual for the meaning of
the commands). After that, everything should work. (I got very euphoric
reports).

   My own experience with my Zoom VFX 28.800 is also quite good, but it
doesn't seem to like automatic fax/data distinction too much, that is,
some data calls are "recognized" as fax and fail miserably. Dunno how
to fix it, I run my Zoom as data-only.

   Fax polling doesn't work.

Best 14496 EC fax modem
-----------------------

   Works quite well. Use `FLOW_HARD' for all flow control settings (in
`policy.h', use 19200 bps for sending and receiving. Set `modem-init'
to `ATE1Q0V1 OK ATS7=60&D3\\Q3%C1\\N7 OK' (`mgetty.config'), and
`modem-handshake' to `AT\\Q3&S0' (`sendfax.config').

   After that it should work. Kudos to Sami Koskinen (tossu@krk.fi).

GVC FM-144Vbis+/1 (Rockwell-based)
----------------------------------

   Basically, the modem is similar to the SupraFax modem.

   Change `speed' in `mgetty.config' and `sendfax.config' to `19200'
and set `modem-handshake' to AT&K4.

   Further, if your model toggles DCD betwen fax pages (`sendfax' fails
mysteriously between pages), `ignore-carrier true' in `sendfax.config'.

   After that, it should work.

   Note: If your modem doesn't properly distinguish incoming fax from
data calls (i.e., a 2400 bps caller is repeatedly "identified" as fax
caller), upgrade your firmware. I've been told (thanks to John Watson,
watson%carssdf@rutgers.edu) that a new firmware release, *v1.69* exists
that will fix those problems.

CREATIX Modem (Rockwell-Based)
------------------------------

   For the new CREATIX modem, use the following settings in
`mgetty.config' (thanks to Jens Hektor, jens@physiology.rwth-aachen.de):

     speed 38400
     init-chat "" ATE1Q0V1 OK ATS0=0&D3&K3

   and `modem-handshake' AT&K3 in `sendfax.config'.

   The modem has a voice mode, too, and it should work with `vgetty' by
now. As the docs for vgetty are out-of-date, I don't really know how to
get it to work, though.

German Telekom approved GVC modems
----------------------------------

   (GM-144VBIS+  RC9696/14 (?))

   This modem does *not(!)* use Xon/Xoff flow control. Further, the
default modem profile sets `&S1', which makes the modem disable DSR all
the time. On systems using the FAS serial driver, this will *disable
CTS flow control*!

   So, #define `FAX_MODEM_HANDSHAKE "AT\\Q3&S0"' in `policy.h', do not
define `FLOW_SOFT' for flow control, and fax sending should work. (It
does for me!)  Changing `FAX_SEND_BAUD' to `B19200' is not necessary,
it works with `B38400'.

   Fax receiving... I did not fully test it. It's somewhat difficult
since that modem insists on using auto-answer, but it should be
possible to let it auto-answer if you set mgetty's ring counter high
enough. Or, you can trick the modem, by changing mgetty's answer
command (`ATA') into `ATS0=1' - upon the next RING, the modem will
"auto-answer".

Dallas Fax 14.4
---------------

   Change `FAX_SEND_BAUD' and `DEFAULT_PORTSPEED' to `B19200', change
all occurances of `AT&H3' to `AT&K5', remove `AT&N0' and `&K4' in
`policy.h'.

Everex
------

   All I programmed is strictly to everex specs, thus, it should work.
Most likely, some fiddling with the initialization strings is necessary.
(If you have an Everex modem, please report to me what you did change).

Exar 9624 fax modem
-------------------

   This modem needs two stop bits (when sending), so you have to add
`CSTOPB' to `tio.c_cflag = ...' in `tio.c' / `tio_mode_sane()'.

   Also, use `#define FAX_SEND_BAUD B19200' and, for fax reception,
`#define DEFAULT_PORTSPEED B19200'.

   Further, the modem is a little bit timing critical - please insert
`delay(500)' calls at the end of `fax_open_device()' (`sendfax.c', line
122) and before sending the page punctuation (`fax_command("+FET=...")'
in `sendfax.c', `main()', around line 540).

   Also, for at least one Exar 9624 (built into a Compaq notebook),
it's been necessary to add two delays (`\\d\\d') before the
`AT+FCLASS=0' initialization string in `mgetty.c'.

Tornado / Lightspeed modems
---------------------------

   Here is a suggested setting for the default profile for these modems.
See Common

   For Lightspeed store profile:
     at&f
     at&c1
     at&d3
     ats0=0
     at%c2
     atw1
     at&w

   and for tornado store profile:

     at&f
     at&d3
     ats0=0
     at&w

   Then just initialize the modem with `init-chat' set to `"" ATZ OK'.

Zoltrix Platinum Series 14.4
----------------------------

   This modem is also Rockwell-based, so don't expect anything
unusual... - it works quite well, both fax sending and fax/data
answering. You should use the following settings in `policy.h'
(suggested by las@io.org, Laszlo Herczeg)

     #define DATA_FLOW	FLOW_HARD
     #define FAXREC_FLOW	FLOW_SOFT
     #define FAXSEND_FLOW	FLOW_SOFT
     #define FAX_SEND_BAUD B38400
     #define FAX_MODEM_HANDSHAKE "AT&K3"
     #define MODEM_INIT_STRING	"ATS0=0V1Q0&D3&K3%C1W1"

   In some circumstances, sending of *large* graphics files (the
well-known `tiger.ps') may fail.

MultiTech modems (MT1432BG and MT2834BG)
----------------------------------------

   First of all, I want to thank MultiTech Munich for their support
(borrowing me two test modems w/o charge).

   Second, I can only strongly recommend these modems, they are *great*
(but expensive). Got it, unpacked it, switched it on, set mgetty's init
string (`MODEM_INIT') to `ATS0=0&S1' - and everything simply worked.
Flawlessly. (Warning: usually I recommend `AT&S0' to force the DSR line
high - needed, because otherwise some O/Ses won't do hardware flow
control - but that doesn't seem to work on my model. AT&S1 means that
H/W flow control only works when a carrier is present, but then, who
needs flow control in command mode?)

   The modems do very reliably distinguish incoming fax and data calls,
and outgoing fax works also very good (unfortunately, it's limited to
9600 bps fax rate, but that's no big problem).

   The only problem I've seen is that those modem do the fax bit order
on reception *right* (everybody else does it wrong, to be compatible
with Rockwell, who botched it in the first place). Thus, `g32pbm' won't
be able to decode the data, unless you call it as `g32pbm -r'.  (You
can see if the bit order is wrong if g32pbm complains in every single
line). I'll work something out for one of the next releases to work
around this (MODEM-TYPE CLS2OK).

   BUT: There seems to be a way to tell the modem to behave like a
Rockwell one and use the "wrong" byte order. Carlos Fonseca found the
following text on ftp.multitech.com:

     Function          Command       Description

     PROCESS           +FRBOR        Maintaining compatibility with
     DATA IN                         Rockwell Class 2 chip set for fax data
     DIRECT OR                       reception .
     REVERSE ORDER                   FRBOR=0 - Process received fax data in
                                     direct order.
                                     FRBOR=1 - Process received fax data in
                                     reverse order.

   so, with AT+FRBOR=1 added to the modem initialization string, it
should be possible to get fax reception on the MultiTechs going without
tricks.

   Glenn Thobe suggested the following definitions for `policy.h' (which
mostly are factory defaults anyway, but it wouldn't harm to set them)

     #define MODEM_INIT_STRING	"ATS0=0Q0&D3&E1&E4&E13&E15"
     #define FAX_MODEM_HANDSHAKE "AT&E4"

   My `mgetty.config' for those modems looks like this (everything not
mentioned is set to the defaults I ship in `policy.h').

     # MultiTech MT1432BG
     port <whatever1>
       init-chat "" \d\d\d+++\d\d\dATE0E1V1H0 OK ATL0M0S0=0 OK
       modem-type cls2

     # MultiTech MT2834BG
     port <whatever2>
       init-chat "" \d\d\d+++\d\d\dATH0&F OK ATX4&D3 OK ATQ0L0M0S0=0 OK
       modem-type cls2

USR Courier/Sportster Fax/Data modems
-------------------------------------

   After long wait, the USR Faxmodems finally have a faxmode. It's
class 2.0, which is quite good for compatibility/standardization
reasons.  Unfortunately, their tech guys aren't very clever, so their
implementation has bad bugs, depending on the ROM release.

   Very old USR modems had the nasty habit of interpreting the "maximum
connection speed" setting as "minimum speed", thus failing to connect to
any non-14400 fax machine. This is fixed.

   Many older models insist on switching the baud rate to 19200 when
receiving a fax, but, alas, not at the same place in the protocol
Rockwell uses, but at yet another place.

   Those two get taken care of if you `#define FAX_USRobotics' in
`policy.h'.

   Another problem that appeared recently is that they have severe bugs
when doing RTS/CTS (that is, hardware) flow control. Occasionally, a
byte gets lost, and sometimes this confuses the modem enough to abort
transmission with the error message
     Transmission error: +FHNG:44 (Unrecognized Transparent data command)
   Sam Leffler recommends using Xon/Xoff flow control for both fax
sending and fax receiving (`#define FAX_SEND_FLOW FLOW_SOFT' and
`#define FAX_REC_FLOW FLOW_SOFT' in `policy.h').

   Some day in the future, I'll make those "quirks" configurable from
the config file, but until then, you'll have to live with recompiling.
Sorry.  (Buy a decent modem!).

   Fax polling with the USRs is *not* working, even though the modem
claims so. It will work half-way through, but fail miserably later.

Elink ISDN Terminal Adaptors 293, 310, 393 with X.75 and V.110
--------------------------------------------------------------

   The TA's are connected to national German ISDN (1TR6) or Euro-ISDN.
The host side is a standard serial port with an AT-command set, letting
them look like a conventional modem. Therefore they are often (wrongly)
called 'ISDN modems'.

   It is strongly recommended to feed them with 115k2 bps, else only
V.110 (38k4 bps) is available. Configuration may differ slightly,
depending on which of those Elinks is used, wether it is connected to
Euro-ISDN or 1TR6 and last but not least they are still under
developement, so you're on your own with that.

   ISDN generally supports two nice features: first it is now possible
to check callers number, which may be used to identify callers, second
ist the charge service, where it is possible to request the amount of
charge units for the call. For mgetty the second one is only from minor
interest, but the first one is.  The opposite phone number will be
shown with the command `AT\O'. If a call comes in, `AT\OA' will answer
the call, display caller's id in a 'digit only' (e.g. `04419808550')
form and then print out the `CONNECT'-String.

   To enable mgetty to utilize this, the "get caller ID" sequence must
be set up accordingly and the `CND' feature must be enabled:

   Use `get-cnd-chat "" AT\\O OK' in `mgetty.config', and make sure
that `#define CNDFILE ".../dialin.config"' at the end of `policy.h' is
enabled.

   If you only want to grab the phone number and not check it against
`dialin.config', you can try playing with something like  `answer-chat
"" AT\\OA CONNECT \c \r' in `mgetty.config'.

   Having a glance at the output of `AT I4'-output of the Elink, it
looks as if it is able to support Fax-Service too, but there is no hint
in the manual. So mgetty will likely put itself into data-only mode. (I
got some information from the Elink people that some of the Elinks have
a data/fax analog modem built in, which should work nicely with the fax
part of `mgetty', but I didn't try yet.)

   (Thanks to Ulrich Tieman, lord@olis.north.de, for this section.
Don't ask me, ask him if you use an ELINK)

Class 1 Faxmodems
-----------------

   These do not work. They are not going to be supported (class 1
faxing is a mess, and the timing is extremely critical--nearly
impossible in a unix environment--read the comments to the FlexFax
package for details).

Operating Systems
=================

   This section describes problems that have occured while porting the
package to various operating systems.

   If your system is not in the list, that doesn't mean it won't work.
It just means that I didn't get a report (or a port) for that system
yet.

   mgetty+sendfax should work on most unixoid operating systems, as
long as they provide `SysV termio' or `POSIX termios' call for tty
management. `BSD sgtty' support isn't finished yet.

   For best results, your system should have `select(S)' or `poll(S)',
but if both functions are not available or don't work on ttys
(`poll(S)' is known to do this on SVR3.1 and earlier), you can use a
kludge, `-DUSE_READ'.

   Besides that, you'll need some fiddling with the header files to get
all defines and prototypes right.

   Further, you'll have to check `tio.c', function
`tio_set_flow_control()', whether the way hardware flow control is
activated works on your system. Most likely, it won't -- that's one of
the major portability problems. If you change something and get it to
work, please send me patches. (You're welcome to do so anyway).

Generic problems and common mistakes
------------------------------------

   There are a few things that can go wrong on all supported operating
systems. This section is meant to give a few hints how to find them.

   * `mgetty' is correctly set up in `/etc/inittab', but `ps' doesn't
     list `mgetty' anyway.

     This is usually caused by not notifying the `init' of your changes
     to `/etc/inittab' (or `/etc/ttytab' on BSD). You have to signal
     `init' with a HUP signal (`kill -1 1') that it should re-read this
     file.

   * `mgetty' is setup correctly, runs a while, then stops being listed
     by `ps', and `init' complains something like `respawning to fast,
     disabling ...'.

     This means, there is an error in the mgetty set up. If the `mgetty'
     process quits too fast (because of an error), and too often in a
     row, `init' will assume that something is going crazy, and disable
     the process. You can re-enable it with `kill -1 1', but you should
     check the mgetty log file (!!!!!) before, to find out *why* it
     failed in the first place

SCO Unix 3.2.2 (ODT 1.0 / 1.1)
------------------------------

   No major twiddling needs to be done. If your `select()' refuses to
sleep less than one second, use poll(S) instead (set `-DUSE_POLL' in
the CFLAGS section of `Makefile').

   Use the modem-control devices for mgetty and dial-outs (e.g.
`/dev/tty2A'), or (far better), use FAS with minor number of 80+port,
using full RTS + CTS handshake, and non-blocking opens (`/dev/ttyF01')
- the original SCO serial driver is slow, unreliable and doesn't do
proper hardware flow control. See SCO-324.

   Ignore all the warnings about "passing arg 2 of signal from
incompatible pointer type". They are caused because the SCO 3.2.2
development system header files are somewhat unusual.

   If it doesn't work, or some weird things happen on login (e.g.,
zmodem downloads do not work), try compiling with -DSYSV_TERMIO. I had
some problems with Posix termios on SCO ODT 1.0.

SCO Unix 3.2.4 (ODT 2.0 and ODT 3.0)
------------------------------------

   I'm using mgetty on SCO 3.2v4(.2) (in fact, developing it there), so
be assured: it works.

   I consider the way that hardware flow control is handled on SCO to be
broken, so I *strongly* recommend using the `FAS' serial driver
(version 2.11 or higher, earlier versions may crash the system), to be
found on your nearest comp.sources.unix archive. With `fas', use the
devices with a minor number of `80+port number' for best results. Make
sure that your modem enables the `DSR' line, because otherwise, `FAS'
won't do hardware handshake.

   If you don't use `fas', I've been told that you have to use the
`modem control' lines, that is, the "uppercase" lines, e.g.
`/dev/tty1A', because SCO's serial driver won't do any hardware flow
control at all on the "lowercase" lines. Be warned, the driver will also
disable hardware flow control if you use Xon/Xoff flow control (no way
to use both). Since I do not have a SCO system without `fas', I'd like
to hear very much about results on one.

   Also, you've to define `LOCKS_LOWERCASE', since that's the convention
on SCO Unix and most other programs expect it.

   If mgetty works only partially, but hangs the moment `/etc/issue' is
printed, before the `system!login:' prompt is output, you may have to
change the following line of `mgetty.c' (around line 780):

             /* honor carrier now: terminate if modem hangs up prematurely
              */
             tio_carrier( &tio, TRUE );

   to:

             tio_carrier( &tio, FALSE );

   But before you do this, make sure that your modem enables the CD line
while a carrier is present (Hayes modems: `AT&C1') and also enables the
DSR line (otherwise the port will block once `CLOCAL' is removed).

   This could have been a problem specific to Uwe's dumb AST-compatible
fourport card, but I do not think so.

   Compilation issues:

   Ignore warnings about `struct utimbuf' and `struct timeb', they are
caused by improper include files. On SCO 3.2v4.2, ignore the warnings
about the getopt() prototype, or change prototype or include files.

   Installation:

   SCO provides two utilities to manipulate `/etc/inittab', `enable'
and `disable'. Those tools work only if you have specified a gettydefs
tag on the `mgetty' command line, otherwise they will complain about
"not a valid tty". So, either append the gettydefs tag (`mgetty' will
ignore it if not compiled with `USE_GETTYDEFS') or change
`/etc/inittab' manually.

Linux
-----

   In current stable kernels (i.e. the latest 2.0.xx release or even
one of the 1.2.xx series) and current shared libraries (libc version
5.2.xx) there should be no bug to interfere with this software.

   If you have a really old Linux system, notice that Linux kernel
versions prior to 0.99pl15 have a bug in the serial handshake code,
that is, if the `CRTSCTS' flag is set, software flow control (XON/XOFF)
won't work. The alarm() call is broken in 4.1 and 4.4.2 libraries,
which sometimes results in aborting the fax receiving.

   Hardware handshake (RTS+CTS) on Linux works flawlessly (but only if
mgetty is compiled with POSIX_TERMIOS, but that is default on Linux
anyway). Nevertheless, the `scrts.c' program in `contrib/' is still
provided, it has some other uses, too.

   Linux has no poll(S), so, don't #define `USE_POLL', and the default,
`USE_SELECT', will be used.

   *Important note:* Use the `/dev/ttyS*' devices for getty and for
dial-out (that is, for kermit, uucico, cu, seyon, ...) - *never* use
`/dev/cua*'. Dialing out on `/dev/cua*' will result in the error
message "device busy". (There are reasons why `mgetty' cannot use the
"`ttyS*' vs. `cua*' kernel locking mechanism", see below). If *all*
programs agree on using `/dev/cua*' only, it will work, too - but they
have to agree on one variant.

   For some background about `ttyS' vs. `cua', you might want to read a
mail from the author of the Linux serial drivers, Ted Ts'o, posted to
the Linux-PPP mailing list. I have included it in `doc/ttyS-cua.txt'.

   Some guys seemingly can't resist posting misinformation to the net
all the time, don't believe 'em. The `/dev/cua*' devices are *not*
different from the `/dev/ttyS*' devices concerning data flow or modem
control lines. The only difference is how the device reacts if you do an
`open()': Opening `/dev/ttyS*' normally blocks until the "carrier
detect" line goes active (unless `open()' is called with the `O_NDELAY'
flag; `mgetty' and all dial-out programs do that), and opening
`/dev/cua*' will return an error message (`errno=EBUSY') if another
process has the device already open, thus *preventing dial-out on
`/dev/cua*'* if `mgetty' is active on `/dev/ttyS*'.

   We use `/dev/ttyS*' all the time for dial-in *and* for dial-out, and
believe me, it works, and it's the *only* combination that will work
properly. The kernel locking mechanism only works if you use modem
auto-answer (the getty process sleeps until the modem gets a carrier),
and mgetty uses manual answer (it waits for the RING message from the
modem), which will save your callers a lot of grief because their calls
will only be answered if your computer is ready to receive a call. Part
of the motivation for writing mgetty was being tired of losing lots of
money for useless calls to a hung machine.

   I'd recommend against using `/dev/modem' as a link to the real
device, but if you do that, make it a *hard link* to the appropriate
`/dev/ttyS*'. A soft link will cause problems with the device ownership
because of a peculiarity in the linux `chown()' implementation (that I
refuse to work around).

   If you get into trouble with write permissions on ttySx, you may add
a new group `dialout' to `/etc/group', then `chown .dialout /dev/ttySx'
your device, and add your users to the dialout group. Don't forget to
add the system user `uucp' to that group (UUCP needs to have modem
access), and make sure, `port-group' in mgetty's configuration file is
set up correctly.  The concept of such a dialout group is already used
in most Linux distributions today.

   There are various different `init' and `last' programs out there,
some work with mgetty, some don't. If you get some strange output from
`who' or `last' and are using a different `init' program than the `sysv
init', try to define `-DNO_SYSVINIT'. That should help.

   I've been told that it's necessary to do that if you use the
`simple-init'.

   Anyway, I can only *strongly* recommend to switch over to `SysVinit'
if you use `simple init', since the latter seems to be severely broken
regarding utmp and controlling tty handling.

   If you have problems because of an uninitialized `TERM' environment
variable (which really isn't getty's job, but `getty_ps' insists on
doing it, and people rely on it), use the `term ...' config file option
to set it according to your needs.

   If you're experiencing problems with hanging `/bin/login' processes,
see login-hang.

ISC
---

   The ISC port has been done by Russell Brown, russell@lutton.lls.com.
Thanks!

   First of all, define `-DISC' in the Makefile. This will take care of
some minor problems. Then, link with `-linet -lpt'.

   If you have a ISC Unix 4.0, you may have to define `-D_POSIX_SOURCE'
to get around some include file problems and link `-lcposix'.

   If you have problems with the AWK programs in the `fax/' shell
scripts, try defining `AWK=nawk' in the `Makefile'. That should take
care of those problems.

   Again, for best results I recommend using the FAS serial driver, and
using a port with a minor number of 80+portno (ttyF01 etc.)

   If you use a Digiboard smart serial cart (e.g. the digiboard pc/8e),
use the `/dev/ttyi*' devices instead of `/dev/cui*', becaus only the
former ones honour carrier drops (If you use `cui*', your processes
won't die if the modem unexpectedly hangs up)

SVR4 Unix
---------

   mgetty has been ported to SVR4 now (many thanks to Bodo Bauer,
<bodo@hal.nbg.sub.org>, Martin Husemann, <martin@bi-link.owl.de> and
Marc Boucher <marc@cam.org>).

   As far as I know, it's sufficient to add `-DSVR4' to the CFLAGS in
Makefile. If you have any problems or suggestions, please report them
also to the people above, since I do not have a SVR4-System to run
tests on.

   If you use the `SAS' serial driver (streams-version of `FAS') and
want to force `sas' to use hardware-handshake all the time, use a
device with a minor device number of `80+port number' (see the `sas'
manual for explantations). If you use a port with a minor device number
of `7*16+i', `mgetty' is able to switch hardware handshake on and off
according to the flags set in policy.h, using `sys/termiox.h'. (Well,
it works - but apparently fax reception doesn't work with this minor
device number. Symptom: only one byte is received during fax reception
(0x00). Anybody any clue?).

   If you use `FAS', use the devices with a minor device number of
`80+port number' (as usual).

SVR4.2 - Onsite Unix, UnixWare, ...
-----------------------------------

   Basically, SVR4.2 is quite similar to SVR4, but you have to watch
out for some details (defining `-DSVR42' in the Makefile will do it for
you).

   Most important, the *termiox* interface via the `TCGETX' / `TCSETX'
`ioctl()'s does not seem to work any longer - the calls return an
error, and the port behaves strangely. If you're experiencing this,
please try commenting out the corresponding code in `tio.c', funtion
`tio_set_flow_control()' and mail me whether that make it work.

   Further, ussing `USE_POLL' or `USE_READ', won't work. The default of
`USE_SELECT' is OK.

   To enable hardware handshake, use the tty device with the trailing
"h", e.g.  `tty01h'. On the other one (`tty01'), the driver won't do
H/W handshake.

   Depending on the configuration, parallel dial-out with Taylor-UUCP
may fail (uucico complaining that it cannot set `CLOCAL'), in that
case, you've to recompile Taylor with different settings for the
`termio' selection (POSIX vs. SYSV).

   Many thanks to Joerg Weber (joerg@interface-business.de) for finding
all those problems.

   Ed Hall (edhall@rand.org) found another major glitch on UnixWare
4.2: if you run `sendfax' without setting `ignore-carrier true' in
`sendfax.config', and `sendfax' switches off carrier detection at the
end of the very last page, the kernel code messes up something and
bytes get lost. The modem then returns funny error codes, like, for
example,
     Transmission error: +FHNG:44 (Unrecognized Transparent data command)
   If you're experiencing this, just set `ignore-carrier true' and
everything should work just fine (please tell me in any case whether it
was necessary, because if it happens for other people as well, I'll
make this permanent on SVR42).

   See Solaris2.

BSD-like flavours of Unix
-------------------------

   A port to 386BSD, NetBSD, FreeBSD has been done by Martin Husemann,
martin@bi-link.owl.de, and Gunther Shadow,
gusw@fub46.zedat.fu-berlin.de.

   I think it works quite well, except that the `VTIME' mechanism to
timeout `read()' calls doesn't work in older *BSD versions. If `mgetty'
hangs, with the last line in the log file being something like "waiting
for line to clear", upgrade your kernel, or, if you can't do that,
compile `mgetty' with `-DBROKEN_VTIME' (in that case, select() will be
used).

   For older versions of BSD Unix that do not have `termios.h', you'll
have to complete the unfinished support for `sgtty.h' in `tio.c' and
`tio.h'.

   Generally, BSD Unices do not have a `/etc/inittab' as system V has.
Instead, they have `/etc/ttytab'. Thus, you have to enter a line like
     cua0    "/usr/sbin/mgetty -x 3 cua0"       vt100
   or
     cua00	"/usr/sbin/mgetty -x 3"    vt100 on insecure
   there. See the corresponding manpage for an exect description of the
files format on your system. Don't forget to remove (or comment out) the
original getty on the corresponding `/dev/tty*' line.

IBM's AIX Operating System
--------------------------

   Chris Lewis, Harald Milz and Michael Staats have done excellent work
on porting `mgetty' to AIX. I think that some problems may still remain,
but as far as I know, it works now.

   On AIX it's not allowed to manipulate `/etc/inittab' directly,
instead, you've got to use some system administration tools. To ease
`mgetty' installation on AIX, Michael Staats has provided a small shell
script, `inittab.aix', that will help you setup your `inittab' after
you've run `make install'. Just call it with the name of the tty you're
modem is connected to, e.g.

   `./inittab.aix tty0'.

   I have received a couple of problem reports on AIX 4.1 where
"suddenly" the modem line stopped working and all mgetty reported were
error messages. If that happens to you, set `toggle-dtr no' in
`mgetty.config'. AIX 4.1 doesn't seem to like programs that fiddle with
the modem control lines.

   Christoph Brinck (100743.3537@CompuServe.COM) has also reported that
it's necessary to enable the "dtropen line discipline" for the serial
line you're using (whatever that may mean). This is done with the
command:

     chdev -l 'tty1' -a flow_disp='rts'
     chdev -l 'tty1' -a open_disp='dtropen'

   or via the `chgtty' part of `SMIT'.

SunOS 4.1.1 and up
------------------

   mgetty has been ported to SunOS, and seems to work quite well.  If
you use SunOS, please send me a brief report about your results.

   Thanks to Earl Hartwig, earl@fozzi.ocunix.on.ca, for the initial
port.

   For compilation, please define `-Dsunos4'.

   In `policy.h', you've to adapt the location of the LOCK files.

   In the Makefile, set `ECHO='...'' to `/usr/5bin/echo', because the
standard one doesn't support escape codes like `\n' or `\c'.
Alternatively, if you don't have the System5 options installed, use
`mg.echo'.

   If a fax reception hangs shortly after the `+FCON' is seen, please
try setting `FAXREC_FLOW' to Xon/Xoff (`FLOW_SOFT'). Hardware handshake
has problems on SunOS versions without the "Jumbo TTY" patch.

   If fax sending hangs mysteriously between the first and the second
page, you're likely to have a modem that drops DCD during pages. As
SunOS' serial drivers are dumb, reception of data will fail if DCD is
low and handshake is set to RTS/CTS. So, `#define
FAX_SEND_IGNORE_CARRIER' *and* `#define FAXSEND_FLOW FLOW_SOFT' in
`policy.h' and fax sending should work.

   Please use the "outgoing" devices (`/dev/cua*') for mgetty and
dial-outs, using the "incoming" devices (`/dev/tty*') will make dialout
impossible. Further, carrier detect (DCD) is only honoured on the
`cua*' lines.

   It is *very* strongly recommended that you install the "jumbo tty
patch" (patch number 100513-05 for 4.1.2 or .3, patch number 101621-01
for 4.1.3_u1 and up) because it will fix a lot misbehaviour of the
serial line drivers.

   Please read also the generic BSD section.

Solaris 2.3 and 2.4
-------------------

   mgetty runs successfully and without trouble under Solaris 2.3 and
2.4.  For compilation use `-Dsolaris2'. With Solaris 2.3 it's
recommended to use GNU gcc, but with Solaris 2.4 it compiles fine with
the SPARCompiler C 3.0.1.  Define `CC=cc'.

   In `policy.h' you have to define `term/a' or `term/b' as
`FAX_MODEM_TTYS'. Don't use the outgoing devices `/dev/cua/*'!!

   As `DEVICE_GROUP' you should configure `uucp'.  If you want allow to
normal users to dial out, add all users allowed to do that, to the group
`uucp'. Then it's important to change the permissions of
`/var/spool/locks' from the default permissions `drwxr-xr-x' to
`drwxrwsr-x'. Make sure that it's owned by `uucp.uucp'.  Otherwise no
one wanting to dial out is able to create a lock file.  The `FILE_MODE'
in `policy.h' must be `0660' as well.

   If you don't want allow anyone to dial out you should set `FILE_MODE'
to `0640' or `0600'.

   For the "notify mail" message to look best, define `MAILER' in
`policy.h' to /USR/LIB/SENDMAIL and define `NEED_MAIL_HEADERS'. So a
proper subject header is created.  Nevertheless, `/usr/bin/mailx'
works, as it is the default for SVR4.

   If everything compiled well and you did `make install', you have to
add an entry to `/etc/inittab' like the following:

     ya:234:respawn:/usr/local/sbin/mgetty -s 38400 -x 3 term/a

   *Don't use the Solaris `admintool' to create any port monitoring
entries in `/etc/saf/_sactab' and `/etc/saf/zsmon/_pmtab'.*

   Many thanks to Stefan Muehlenweg (muehlenw@samhh.hanse.DE) for this
section.

AT&T 3b1
--------

   Glenn Thobe and Chris Lewis have ported mgetty+sendfax to AT&T's 3B1
machines, it should compile without changes to the source (but define
-D_3B1_ in the Makefile).

   These ports are to two different environments:

   Glenn's port was with GCC (ANSI C) and an add-on select() library
routines.  Chris's port was with stock 3b1 C, without select().  Both
seem reliable.

   Some further hints concerning a select() library and the pbmplus
tools can be found in the file `contrib/3b1' which are the notes from
Glenn's port.

   Chris's port relies simply on the suggested definitions (especially
`-DUSE_READ') in the Makefile.  Chris suggests that you use select() if
you already have it for some other reason, but that it seems to work
just fine without it.

   Right now, I think mgetty won't compile with the standard C compiler
(it will with gcc), because the stuff I do in the `conf_*.c' source
files is a little bit too hard for it. I'll work on it.

The HP-UX operating system
--------------------------

   `mgetty' runs on HP-UX, but that's very much all I can say about it
(I don't know anything about HPs, except that they are somewhat
strange).

   But, there are good news: Joerg Weber has volunteered to answer
questions about mgetty on HP. His mail address is
`joerg@interface-business.de'.  Ask him *many* questions, and he'll
write a chapter about HP-UX :-)

The NEXTSTEP operating system
-----------------------------

   NEXTSTEP is lacking quite a few commands used by mgetty and its
tools: Luckily, they are available from the GNU project (please mail me
if I forgot any), e.g. gawk, cut (from textutils), id and logname (from
sh-utils). All of them can be compiled for NEXTSTEP without problems,
and it's certainly a good idea to install them anyway. ghostscript
needs some fiddling for NEXTSTEP, but it's available precompiled on the
arcives as GSPrintFilter.  If you don't intend to use faxspool and
friends, you may succeed without installing the forementioned utilities.

   Having said this, there are two different ways to compile `mgetty'
for NEXTSTEP, each with their pros and contras:

   * With termios interface: To use `mgetty''s termios interface (the
     default), you have to link against NEXTSTEP's buggy POSIX library.

     In the Makefile, add "-posix -DBSD" to CFLAGS and LDFLAGS.

     Drawbacks: The log file will be corrupted due to an append bug in
     libposix.

     Use this only if you want to try vgetty. In all other cases it's
     probably better to choose the second variant:

   * With sgtty interface: Ben Stuyts `benst@stuyts.nl' has done an
     effort to make a `mgetty' port using the BSD sgtty style interface
     to the serial ports. This port doesn't need the POSIX library.

     In the Makefile, add "-DNEXTSGTTY -DBSD".

     This port has been tested with m68k and i386 machines.

     For i386 machines, you may want to use the /bin/login replacement
     `modem-login' in `mgetty''s contrib directory. NEXTSTEP's login
     has problems with 8-bit logins. I've got one report from Ben
     Stuyts, though, that `modem-login' does fix problems on "Black
     NeXT"s as well. Just try it.

     Drawback: You can't compile vgetty with sgtty support yet! If you
     want to use vgetty with NEXTSTEP, you'll have to stick with the
     termios port. There are problems with the LNOHANG bit not being
     acknowledged correctly, therefore hanging the modem when the
     caller hangs up.

   For i386 machines, it's wise to use the /dev/cudfX (hardware flow
control,...) devices. I'm using them with NeXT's most recent serial port
driver, Mark Salyzyn's Mux driver also supports them.

   For m68k machines, you have to stick with /dev/cufa.

   This are the settings I use in the Makefile:

     CC=cc
     CFLAGS=-DNEXTSGTTY -DBSD -O2  (-posix -DBSD for termios port)
     INSTALL=install -c -o root -g wheel
     spool=/usr/spool
     SBINDIR=$(prefix)/etc
     ECHO="mg.echo"
     INSTALL_MECHO=mg.echo
     AWK=gawk

   Furthermore, you should define binary lock files, in policy.h:

     #define LOCKS_BINARY 1

   Finally, when using NEXTSTEP's cc, you need to run "make noident" in
the first place to remove the #ident directives from the source files.

   If you have questions, comments or suggestions regarding `mgetty'
with NEXTSTEP, feel free to contact Gregor Hoffleit
`flight@mathi.uni-heidelberg.de' or Ben Stuyts `benst@stuyts.nl'.

   * Coming real soon now:

     How to use `mgetty' to send faxes via the NEXTSTEP fax panel

     (using Kevin Peckover's ps2g3 package, available as
     `ftp://peanuts.leo.org/pub/next/Tools/postscript/ps2g3.s.tar.gz').

   * Coming soon:

     How to patch and use `mgetty' to spool received faxes in the
     NEXTSTEP fax system.

General problems
================

pbmtog3
-------

   The `pbmtog3' program from the `pbmplus' distribution produces G3
data that does not adhere to the T.4 standard. The initial EOL code is
missing, and the lines are not always 1728 pixels wide.  So, some fax
machines won't accept the output at all (not printing even one line),
and others will complain.

   A fix for this problem is available: I have included a patch for
pbmtog3, called `patches/pbmtog3.p1', that will fix the problems. (Oh,
by the way, if you try to send a fax generated with an unpatched
pbmtog3, sendfax will complain that it doesn't like the file ... I've
added a small sanity check to spare me the time browsing through the
logfiles guessing *why* sendfax failed (won't work if the file has been
processed by `g3cat', though!)). If you use the `pbm2g3' program that is
shipped with `mgetty', there is *no need to patch anything*.

   Basically, there is no need at all to use `pbmplus'' `pbmtog3'
program any more, since `mgetty' includes an own copy. I just wanted to
warn you.

   Anyway, my program is lots faster ....

Lock files
----------

   Kermit et.al. cannot dial out while mgetty is running (modem
responses are eaten by mgetty)--what's wrong?

   Most propably, you have not configured the `LOCK' and `LOCKS_BINARY'
defines in `policy.h' properly. Make sure that the lockfiles kermit (or
cu, pcomm, seyon,...) expect are in the path specified in `LOCK' and
set `LOCKS_BINARY' to 1 if they do not write the PID of the locking
process in ascii (10 bytes) to the lock file but as a 4-byte integer
instead. Mgetty and Sendfax will understand both types of lock files,
but if `LOCKS_BINARY' is not set properly, other programs may not
understand the lock file.

   Also, make sure that both processes use the same name for the device.
(i.e., mgetty locking `/dev/ttyS0' and kermit locking `/dev/modem' will
definitely fail.)

mgetty works, /bin/login hangs
------------------------------

   A problem seen fairly often on directly connected serial lines
(`mgetty -r'), and seldomly on modem lines, is that `mgetty' works
flawlessly, but `/bin/login' just hangs instead of prompting for the
user password.

   The reason for this is that many `login' programs reopen `/dev/tty'
(the controlling tty of a process) to make sure they have full control
over the password entered by the user (for example, to prevent
snooping). This will block on some systems if the DCD (carrier detect)
line coming from the modem or the other machine is low. Notably those
systems are those that have callin/callout device pairs for one serial
device, e.g.  Linux, SunOS, SCO/FAS, etc.

   The fix is easy: make sure that the DCD line is high.

   If you use a modem, the command to do this is usually `AT&C1' (but
check with your modem manual).

   If you're using a direct null-modem connection to another host, the
recommended solution is to wire DCD on your side to the DTR line on the
other side and vice versa. That way, when the remote machine "hangs up"
(calling program exits and DTR drops), your host will get notified as
well. This is what a properly wired (!) "null-modem cable" does anyway.

   If you don't have free lines in your serial cable (classic three-wire
approach), wire DCD to the DTR line on your own host, and make sure that
mgetty won't toggle DTR upon startup (causing a hangup signal!), e.g. by
setting `toggle-dtr no' in `mgetty.config'.

ECU 3.20 or earlier on SCO collides with mgetty
-----------------------------------------------

   ECU releases 3.20 and earlier had a severe bug in the utmp handling
that prevented dialing out on a port that mgetty uses. It has been
fixed in ECU 3.27. If you run into that problem, please get a newer
release.  Alternatively, you can use the patch that Uwe Fuerst
provided, it can be found in `patches/ecu320.p1'.

Sample Log files
================

   Both mgetty and sendfax can provide logfiles that can be very
helpful for debugging and accounting purposes. The amount that is
logged is controlled with the default set in `policy.h' and the command
line argument `-x <level>'. Higher numbers give more details.

   At this place, I want to show you some typical cases, so you can
compare your log files to those given here and check what is different.

   (Note: naturally all the modem initializations, and also some of the
modem responses, vary between modem brands!)

   All the mgetty log files have been done with log level `L_MESG',
that is, `-x 4'. The sendfax log file was done with `L_NOISE', `-x 5'.

mgetty, incoming data call
--------------------------

   This is a log file of a typical data connection, ZyXEL-to-ZyXEL
modems, connect with 19200 bps on a port speed of 38400, login as
"Uartinet", the login program called is `/usr/lib/uucp/uucico'
(controlled by `LOGIN_CFG_FILE', which directs all login names starting
with "U" to uucico)

     03/03 22:40:15  check for lockfiles
     03/03 22:40:15  locking the line
     03/03 22:40:16  lowering DTR to reset Modem
     03/03 22:40:16  send: \d\d\d+++\d\d\d[0d]\dATQ0V1H0[0d]
     03/03 22:40:20  waiting for ``OK'' ** found **
     03/03 22:40:20  send: ATS0=0Q0&D3&H3&N0&K4[0d]
     03/03 22:40:20  waiting for ``OK'' ** found **
     03/03 22:40:20  send: AT+FCLASS=0[0d]
     03/03 22:40:20  waiting for ``OK'' ** found **
     03/03 22:40:20  send: AT+FAA=1;+FBOR=0;+FCR=1[0d]
     03/03 22:40:20  waiting for ``OK'' ** found **
     03/03 22:40:20  send: AT+FLID="49 89 3243328"[0d]
     03/03 22:40:20  waiting for ``OK'' ** found **
     03/03 22:40:20  send: AT+FDCC=1,5,0,2,0,0,0[0d]
     03/03 22:40:20  waiting for ``OK'' ** found **
     03/03 22:40:20  fax_command: send 'AT+FLPL=1'
     03/03 22:40:20  fax_wait_for(OK)** found **
     03/03 22:40:21  waiting...
     03/03 22:41:28  waiting for ``RING'' ** found **
     03/03 22:41:28  send: ATA[0d]
     03/03 22:41:28  waiting for ``CONNECT'' ** found **
     03/03 22:41:42  send:
     03/03 22:41:42  waiting for ``
     '' ** found **
     03/03 22:41:43 ##### data dev=tty4c, pid=6470, caller=none, conn='38400/ZyX  16800/V42b', name='', cmd='/usr/lib/uucp/uucico', user='Uartinet'