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

   Copyright (C) 1993-1997 Gert Doering

mgetty + sendfax
****************

   This is the online documentation for the mgetty+sendfax package
written by Gert Doering.

Introduction
************

   `mgetty' allows you to make optimum use of your modem or fax modem in
a unix environment. `mgetty' handles incoming calls without interfering
with outgoing calls. If the modem can do fax class 2 or 2.0, `mgetty'
can also receive faxes.

   `sendfax' is a standalone backend program to send fax files.

   This manual explains how to configure and install the package on
various operating systems and modems, and how to use those programs.

Copying conditions and (lack of) warranty
=========================================

   *WARNING:* This package is still BETA software. Use it at your own
risk, there is *no* warranty. If it erases all the data on your hard
disk, damages your hardware, or kills your dog, that is entirely your
problem. Anyway, the program works for me and quite a lot of other
people.

   The `mgetty+sendfax' package is Copyright (C) 1993-1997 Gert Doering.

   You are permitted to redistribute `mgetty+sendfax' freely, modify it,
include it in other programs, ..., as long as you don't make profit
directly out of selling `mgetty' (see below), include the complete
`mgetty' source, and do not remove my name. If you distribute a
modified version, or include `mgetty' code in your projects, mark it
clearly as such ("... *derived* from `mgetty+sendfax' by Gert Doering")!

   If the program works for you, and you want to honour my efforts, you
are invited to donate as much as you want...

   What I mean above with "as long as you don't make profit directly
out of selling `mgetty'" is: it is perfectly OK if you get paid for
`mgetty' support, or if you distribute `mgetty' among other goodies on
a CD-ROM collection or whatever, but if you sell `mgetty' bundled with
a faxmodem as "unix fax package" or "with unix software!", or if you
start selling `mgetty' with only minor enhancements for lots of money,
I want a share. If in doubt, just ask me.

   In any case, if you don't like the restrictions in this license,
contact me, and we can work something out.

   This license expires, that is, two years after release date, a given
`mgetty+sendfax' release falls into the public domain, and everybody is
absolutely free to do with the code what he wants.

Features of `mgetty' and `sendfax'
==================================

   This package contains two major programs, `mgetty' and `sendfax'.

   This is what you can do with `sendfax' if you have a standard class
2 fax modem:

   * send faxes directly or using shell scripts

   * do "fax polling", this means you can call the weather station and
     get them to send you a fax containing the current weather map.
     (Not all modem manufacturers implement this feature in their
     modems!)

   * create a "fax queue", outgoing faxes get sent automatically, the
     user is informed by mail about the result.

   `mgetty' allows you to use a single modem line for receiving calls
and dialing out.

   * `mgetty' knows about "smart" modems, and will make sure that the
     modem is always in a defined state (specific modem initialization
     possible)

   * Incoming calls are answered manually (`RING' -> `ATA' ->
     `CONNECT') instead of using auto-answer (`ATS0=1'), this way the
     modem won't pick up the phone when the machine is down or logins
     are not allowed.

   * `mgetty' incorporates all features of uugetty: it honours `LCK.*'
     files created by `uucico' and other comm programs, this way it will
     prevent dial-outs while a caller is online and it won't be
     confused if other programs use the modem.

   * `mgetty' can receive faxes (if your modem supports fax class 2 or
     2.0).

   * `mgetty' knows about incoming FidoNet calls.

   * `mgetty' has extensive logging / debugging features

   * do "fax poll sending", that is, you can setup your machine as fax
     poll server, to send some fax pages to "fax poll" callers. (Send
     informations about your system, the current wheather map, ...). Be
     warned, even less modems support this feature.

   * `mgetty' can selectively refuse calls based upon CallerID, if your
     modem supports it, and you're subscribed to the service.  CallerID
     is also logged.

   * `mgetty' has facilities to allow you to refuse incoming FAXes when
     available disk space is low.

   If you have any bug reports, suggestions, please report them to
gert@greenie.muc.de (or, if [and only if!] that doesn't work, to
gert@space.net).

   Also, I have created a mgetty mailing list, for discussion of
problems and suggestions. You can subscribe by sending a request to
mgetty-request@muc.de (forwarded to Crynwr.com for precessing) and you
can send articles to the list by sending them to mgetty@muc.de.  Please
make sure that the mail address you send me is valid - I'm quite sick
of getting all list mails bounced back to me because one of the
addresses doesn't work.

   The mailing list is currently gated bidirectionally into the
newsgroup de.alt.comm.mgetty. In spite of being in the German language
hierarchy, the language in the group is English. Posts in German should
be ignored.

   The mailing list is archived on a WWW site, look at
`http://eli.wariat.org/mgarc/index.html' (many thanks to Robert J.
Brown, rj@eli.wariat.org)

Supported systems and modems
============================

   Mgetty has been successfully installed and run on the following
systems:

         SCO Unix 3.2.1 (ODT 1.0)                   (well tested)
         SCO Unix 3.2.4 (ODT 2.0 + 3.0)             (very well tested)
         SCO Open Server 5.0                        (well tested)
         Linux (everything from 0.99pl1 up)         (very well tested)
         ISC Unix 3.0                                (tested)
         SVR4 Unix                                   (well tested)
         SVR4.2 Unix                                 (needs more testing)
         AT&T 3B1 3.51m                              (well tested)
         HP-UX 8.x and 9.x                           (well tested)
         AIX 3.2.5 and 4.2                           (well tested)
         SunOS 4                                     (well tested)
         Solaris 2.x                                 (well tested)
         NetBSD / FreeBSD                         (well tested)

   It should be possible to run mgetty on any other Unix with `termio.h'
or `termios.h'. For best results, use of the library functions
`select(S)' or `poll(S)' is recommended, but there's a workaround if
your system hasn't either. (Warning: for Unix SVR3.1 or earlier, *do
not use poll()*, it will not work on tty devices.)

   Up to now, it has been successfully used with the following modems
(no exhaustive list) in fax mode:

         ZyXEL U1496 (various ROM releases)
             (very well tested, a couple of problems remain, depending on the
              ROM release)

         MultiTech (various models)
             (tested, works very well, very good fax implementation)

         SupraFAX v32bis
             (tested, works well, no fax polling available)

         GVC FM144/+
             (tested, works well, no fax polling available)

         TKR DM-24VF+ (Deltafax)
             (tested, works quite well)

         Zoom V.FAST 24K/28K
             (tested, works, some problems with fax/data distinction)

   It *should* work with all class 2 faxmodems. Maybe the DC2 character
sent at the beginning of a page by `faxrec.c' must be changed to XON,
for old class 2 modems (implementing very old drafts of the standard).
See Modems.

   In Data mode, it will work with every Hayes-compatible modem.

Configuration and installation
==============================

   Compiling of the package should be quite straightforward. You have to
copy `policy.h-dist' to `policy.h' and edit it to set some local policy
options, see the comments in that file.

   Then, edit the `Makefile', to specify installation paths, some
system defines and some system dependent libraries (explained there).

   After that, a `make' should build the programs, and `make install'
should install them.

   If your compiler complains about the `#ident' lines I use for
`SCCS', please run `make noident', that will take care of those lines.

   If you get an error message about "unresolved symbols" when linking,
you may have to tell the package whether you have the select(S) or
poll(S) system calls, by defining `-DUSE_SELECT' or `-DUSE_POLL' flags
in the `Makefile' (If you don't know it, try both, until the error goes
away). If it's not related to `select' or `poll', please check the
systems man pages which libraries to link, and add appropriate
`-l<library>' statements to `LIBS'.

   If your system has neither the select(S) call nor the poll(S) call,
mgetty is not fully operational--these functions are the only way to
prevent mgetty from eating up characters when some other process is
trying to dial out.

   You can use mgetty anyway, by specifying `-DUSE_READ' in the
Makefile, but beware: with this, mgetty will eat up at least one
character of the modem response when another program is dialing out.
That may lead to disastrous results if e.g. the `CONNECT' string is
thus corrupted, but most of the time, the character that `mgetty' eats
away will be an `cr' or `nl' or part of the command that the modem
echoes back.

   If you have any problems compiling mgetty and sendfax (on a Unix-like
system--I do not support MS-DOS or Windows!), please contact me.  *But
make sure that you have read the documentation!*

Runtime configuration: Overview
===============================

   If `mgetty' or `sendfax' are run "as is", they will use their
compiled-in defaults from `policy.h'.

   If the configuration files `mgetty.config' (see runtime-mgetty)
and `sendfax.config' (see runtime-sendfax) exist (and are readable),
both programs will get their run-time configuration from there. Items
not specified there will still be taken from the compiled-in defaults.
Command line switches will always override those settings. The
configuration files are usually located in `/etc/mgetty+sendfax/'.

   If you specify command line arguments (see the mgetty(1) and
sendfax(8) man pages for details), this will override both compiled-in
and config file defaults.

Using `mgetty'
**************

   You can't simply call `mgetty' from a shell script (like `/etc/rc')
or interactively, because login is not possible unless mgetty is called
directly by the `init' process. The next sections explain how to do
this.

How `mgetty' works
==================

   To help you understand how mgetty works, here is an example of what
happens in various circumstances when you use it to control a modem
connected to a serial line, e.g. `/dev/tty2a'.

   When the computer is booted, the operating system starts the `init'
process, which is responsible for making sure that gettys are running on
the appropiate i/o devices, e.g. virtual terminals, serial lines and
modems.  `init' reads its configuration file, `/etc/inittab' (on System
V), which tells it that the line `/dev/tty2a' should be controlled by
mgetty. It then creates an entry in `/etc/utmp' (`login' needs this,
that's why you can't log in if you try to start mgetty by hand), and
forks a new `mgetty' process, using the command line specified.

   When mgetty is started, it first checks if a valid lock file held by
another process exists. If it does, this means that the port is in use,
and mgetty will wait until the lock file goes away. Invalid lock files,
e.g. for nonexistent processes ("stale" locks), are ignored.

   Once the port is free, mgetty creates its own lockfile, initializes
the modem and removes its lock file again. Then it waits for something
to happen on the port. Note that it does not *read* any characters, it
just checks if there are any available for reading by using `poll()' or
`select()'.

   There are two possibilities once characters arrive, either a
different program (e.g.  `uucico') has started dialing out or a `RING'
was sent by the modem.  In the first case, mgetty should leave the port
alone. This is easy *if* the program dialing out has created a valid
lock file: mgetty will find it, wait for it to go away and then exit
(which will cause `init' to start a fresh `mgetty' process, which will
then wait for the next call).

   In the second case, when there is no lock file, mgetty assumes that
the phone is ringing, creates a lock file and reads the characters
available. If it finds a `RING', it picks up the phone by sending `ATA'
and waits for the `CONNECT' message. If the caller is a fax machine, it
saves the fax in the directory `FAX_SPOOL_IN' (usually
`/var/spool/fax/incoming') and exits. If it is a modem, it prints
`/etc/issue' and displays a login prompt. Once it has received a login
string, it calls `/bin/login' and lets it handle things from here.
`login' will read the password and will then start the user's login
shell, `uucico', a dialup SLIP link or whatever, but mgetty doesn't
care about that. The lock file remains so that no other programs will
try to use the modem while somebody is logged in.

   (If the `login.config' configuration file is used, mgetty can also
call other login programs than `/bin/login'. See below for more details)

   Once mgetty has terminated for whatever reason, `init' might
reinitialize the port (this is why mgetty waits for lock files to go
away instead of quitting immediately) and will then start a new
`mgetty' process, which will remove lock files left over from the last
login.

   The lock file handling is tricky, but very important. It is essential
that *all* programs that use the modem agree on one locking protocol,
otherwise one program might not know that the modem is in use and will
try to dial out anyway. A typical lock file is a file called
`/var/lock/LCK..ttyxx', containing the process ID (PID) of the process
currently using the modem. Other processes can read it and tell if the
lock file belongs to an existing process or if it is "stale" and can be
removed. This will obviously not work if the processes look for lock
files in different places, or if one of them writes its PID in ASCII
and another one tries to read it as a binary number (while mgetty and
sendfax do not care whether foreign lock files are written in binary or
ascii format, other programs do! mgetty can sometimes detect this
problem, and will then log a warning).

The `/etc/inittab' entry
========================

   An typical `inittab' entry for `mgetty' looks like this (on
SystemV-style OSes):

     <tt>:rlevel:<respawn|off>:/usr/sbin/mgetty [options] <device>

   where `tt' is a short form of the `device' name, used by `init' and
`who' for internal purposes. Usually this is something like `S0' or
`2A' or so.

   `rlevel' specifies the runlevel that the command in the fourth field
is run at, this may be `23' or `56' or so, look at `man init' and the
existing `/etc/inittab' on your system.

   The next field tells `init' whether that entry is active (`respawn')
or not (`off'), and the fourth field specifies the full path of the
program to run.

   The following options are available for `mgetty':

   `-x <LEVEL>' sets the debugging level. This is very important for
diagnosing problems, as with higher levels, `mgetty' will write very
detailed informations about its internal workings to its log file.

   `-s <SPEED>' sets the port speed. If not specified, the default from
`policy.h', (definition `DEFAULT_PORTSPEED') will be used.

   `-k <SPACE>' sets the minimum number of kbytes required on the
incoming FAX spool directory.  If there isn't this much space in the
spool directory, the connection is terminated.  The default is 1
megabyte.

   `-m 'EXPECT SEND ...'' sets the modem initialization sequence.

   `-r' for direct lines (no modem chats are done)

   `-p <LOGIN PROMPT>' sets the login prompt (various escapes are
allowed)

   `-n <RINGS>' sets the number of `RING' messages to expect before
sending `ATA' to answer the phone. Default is one `RING'.

   `-R <SEC>' tells mgetty to enable "ring-back" or "ring-twice" mode.
This means that mgetty won't pick up a call immediately, but the caller
has to hang up after the first ring, and call again in the next <SEC>
seconds.

   `-i `/etc/issue'' specifies the issue file to display before
prompting for login.

   `-S `<fax_document>'' specifies the document(s) to send to polling
fax machines (full path required). `<fax_document>' has to be in G3
format (as for `sendfax'), or a text file listing G3 fax files (one
file per line).

   A sample entry in `/etc/inittab' might look like this:

     F1a:23:respawn:/usr/sbin/mgetty -x 3 tty2a

   For a more detailed explanation of all the options, please look into
the `mgetty(1)' man page.

Choosing the right device
=========================

   Some operating systems provide two separate devices for each serial
line, one of which is intended especially for gettys. This is *NOT* a
good idea, because it won't work with `mgetty'. It is meant for modems
used in auto-answer mode.

   `mgetty' picks up the phone by hand, this will only work properly if
you use the *same* device you would use for dialing out. (Some people
like to create a symlink `/dev/modem' for this, but you have to be
consistent and use this for *all* comm programs if you do - otherwise
you'll run into problems with the lock file names).

   Here are some examples for different systems:

   * SV Unix systems using the FAS serial driver:

     Use `ttyF01' etc., (minor number 80+(port number). Do *not* use
     `ttyFMxxx'--mgetty will open the device anyway, but then an open
     to the "normal" port (without carrier detect) will block.

   * SCO Unix systems with the stock serial driver:

     Use the modem-control port (`tty2A'), *not* `tty2a', because
     hardware flow control and carrier detection do not work on
     "lowercase" tty devices.

     The same holds for "smart" serial boards, as specialix, digiboard,
     ..., because they mimic the behaviour of SCO's sio driver.

   * Linux:

     Use `/dev/ttyS*', *not* `/dev/cua*'. See Linux

   * SunOS, FreeBSD, NetBSD:

     Use `/dev/cua*', not `/dev/ttyS*'. Don't ask me why it has to be
     this way, but the other way won't work. (On SunOS or Solaris, you
     can find some gory details in the `man zs' man page).

Log files
=========

   `mgetty' will normally write all actions into a logfile, named
`LOG_PATH.<DEVICE>' (LOG_PATH is defined `policy.h'), e.g.
`/var/log/log_mg.ttyxx', so you can easily see what's happening in your
system. (If a fatal error occurs, the error message is also written to
the console, and if that is not possible, mailed to `ADMIN'). The name
of the log file can be changed in `policy.h'.

   If `mgetty' is compiled with `-DSYSLOG', auditing and error log
messages will also go to `syslog' (if your system supports it).

Denying logins
==============

   If you want to prevent mgetty from accepting calls, you can do so by
creating a file called `/etc/nologin.<DEVICE>' (e.g.
`/etc/nologin.tty2a'). If mgetty detects an incoming call, and sees
this file, it will *NOT* answer the phone. This way the caller does not
lose money for a useless call when logins are not allowed anyway. (You
can change the filename that is checked by changing `NOLOGIN_FILE' in
`policy.h')

   This can be used for quite sophisticated scheduling purposes -
imagine a modem attached to a line used for voice during the daytime.
So, you want the modem only to answer the phone during 9 pm and 7 am.
What you do is to have `cron' create a `/etc/nologin.DEVICE' file at 7
am (so the modem won't answer the call during the day) and remove it at
9 pm (so the modem can answer the phone at night).

   Naturally, this can be easily extended - e.g., answer the phone only
on weekends (similar cron job), don't answer the phone if there are less
than 5 Mbyte free on disk (have a process check for free disk space
regularily and create `/etc/nologin.*' file(s) accordingly), ...

Direct serial lines
===================

   If you have a direct serial line between two unix machines, or a unix
machine and something else, and want to run a getty program on the unix
side that should not interfere with outgoing traffic (e.g.: two unix
machines, both sides running gettys, both sides able to initiate an uucp
connection), you can also use mgetty. Start it with the `-r' flag (as
with uugetty), and it will not try to initialize the modem or wait for
RINGs. It will just sit silently on the port and wait... You won't see
`/etc/issue' on the other side until mgetty gets at least one
character, this prevents two mgettys from talking to each other.

   This may be valid for leased lines with modems in leased line mode
as well, but that may depend on your modem setup.

Interaction between `mgetty' and other programs
===============================================

   Normally, after a caller enters his login name, `mgetty' calls
`/bin/login' to do the password checking and system login.

   In some special cases, you may want to call other programs instead of
`/bin/login'. For example, you could want to call `/usr/lib/uucp/uucico
-L <username>' for all login names starting with `U*' (to have `uucico'
do the authentication, works only with taylor uucp 1.05 or taylor uucp
1.04 with my patch in `patches/taylor.p1'), or `/usr/lib/fnet/ifcico'
for incoming FidoNet calls (using `ifcico' from Eugene Crosser's
`ifmail' package).

   `mgetty' can do all this. It's controlled by a configuration file
`login.config', normally located in `/etc/mgetty+sendfax/' (definition
`LOGIN_CFG_FILE' in `policy.h'). I have provided a sample file with
lots of comments, please look into that file for the syntax to use. To
make `mgetty' understand incoming fido calls, you have to compile it
with `-DFIDO'.

   If you are worrying about security, you can also use this mechanism:
just call `/bin/login' only for trusted, known users, and `/bin/false'
for every other login name - so, only those listed in `login.config'
will be able to log in.

Using Caller-ID to selectively accept or reject calls
=====================================================

   Some telephone companies provide a service to the subscriber, called
"Caller ID", where the phone number of the caller is transmitted while
your phone is ringing. Not all providers support it, and you'll have to
ask for it.

   If your modem is able to retrieve callerid information, and `mgetty'
is compiled with `CNDFILE' defined in `policy.h', `mgetty' can check
the caller's number before answering the phone. (Right now, I know that
it works for ZyXELs. I've implemented it for Rockwell, but didn't get
feedback yet. Volunteers?). If `CNDFILE' is undefined, or if that file
does not exist, all calls will be allowed.

   One important thing: for most analog modems, you *must* set the
number of RINGs to wait for to two (2) or higher (set `rings 2' in
`mgetty.config'), because the ID code is sent between the first and the
second RING. If mgetty picks up the phone too soon, the modem can't get
this information.

   Whether a call is accepted or denied is controlled by a
configuration file, set with `CNDFILE' in `policy.h'. Usual default is
`/etc/mgetty+sendfax/dialin.config' (a sample file is installed per
default).

   That file contains a series of tokens separated by newlines, commas,
tabs and spaces. The callerid number is compared with each token in
turn, until a match occurs. A match occurs when the token compares
equally to the callerid information up to the length of the token.  If
the token is prefixed with a "!", a match means "do not answer the
phone". The token "all" matches any telephone number, and will
terminate scanning of the cndfile. If no callerid number is present, it
is assumed to have the value "none". A line starting with "#" is a
comment.  There is an implicit "all" at the end of the file.

   For example:

     	# list of my friends' data lines
     	3433535, 7445343, 5551212
     	# dad's fax
     	4164646777
     	# disallow [other] calls from numbers matching the following prefix:
     	!416
     	# disallow that speed dialer that keeps hitting my machine
     	!3444444
     	# allow all calls with the following prefixes
     	832, 555
     	# don't allow calls when there's no callerid:
     	!none
     	# It's okay to accept calls from out of area
     	# ("OUT_OF_AREA" token seems ZyXEL specific)
     	OUT_OF_AREA
     	# disallow all other calls
     	!all

   For the future, Chris Lewis is planning on adding special modem
initialization strings (e.g., 2400 bps only, fax-only, ...) dependant
on the caller number.

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

   `Mgetty' works quite well with the compiled-in defaults (it has been
the only way to configure it for a long time), but that's quite
unflexible, and especially if you use different modem types, it's
extremely unhandy.  The built-in defaults can be modified by command
line options, but that's not perfect either, because it makes
`/etc/inittab' entries very long and difficult to read.

   If compiled with *config file* support (define `MGETTY_CONFIG' in
`policy.h'), `mgetty' can use a configuration file, quite similar to
those which "Taylor UUCP" uses, which make dynamic setup far easier.

   The config file is usually located in `/etc/mgetty+sendfax/' and
named `mgetty.config'. Its format is very simple. Each line contains one
keyword, and possibly arguments for it, separated by whitespace. Empty
lines, and comment lines (lines starting with `#') are allowed.

   The config file is grouped into port-specific sections, separated by
`port <TTY-NAME>' lines. Everything before the first `port' line
specifies global defaults, everything between two `port' statements
specifies configuration items valid only for exactly this device. Let
me show you an example:

     # global defaults:
     # fax station id is always the same
     fax-id ++49-89-1234
     # per port stuff
     port tty1a
     # This modem can't fax
     modem-type data

     port tty2a
     # more verbose logging for this modem
     debug 9

   The data part of each line, following the keyword, can be a string
(in most cases), a chat sequence (a series of strings, separated by
whitespace, that specify the "modem talk" to do. It starts with
"expect" string, then "send", then "expect" again, and so on), an
integer (interpreted as decimal, octal or hexadecimal, depending on the
leading character [1-9/0/0x]), or boolean (`y(es)' or `t(rue)' vs.
`n(o)' or `f(alse)'). If no argument is specified, this will be
considered "value not set" (if allowed) or "error" (if value is
mandatory), except for boolean values.  In that case, it's interpreted
as `true'.

   Many of those configuration items can be overriden from the command
line.  In that case, command line options take precedence over
configuration file settings (and those take precedence over built-in
defaults). In many cases, the built-in defaults can be set in
`policy.h'.

   The available configuration items are (command line options, if
available, given in brackets):

   - `speed' [-s] PORT SPEED

     Specify, as integer value, the port speed to use. Default is
     `DEFAULT_PORTSPEED'. If the given speed is not valid, `mgetty'
     complains loudly and exits.

   - `switchbd' FAX RECV. SPEED

     Some modems, mainly Rockwell chipsets, switch to 19200 bps when
     entering fax mode. Others may need other speed switches (but I
     know none).  If your modem is Rockwell based, try `switchbd 19200'
     if fax reception doesn't work. (*Warning:* if this is set wrongly,
     fax reception will definitely fail. For most sane modems, you do
     *not need* this.).  Default is `FAX_RECV_SWITCHBD'.

   - `direct' YES/NO [-r]

     Tells mgetty that it is running on a direct line. Mgetty won't try
     to initialize any modem, nor will it wait for `RING'. It will just
     wait for any character, and then output the issue file and login
     prompt. This option is used if you want to connect to machines via
     nullmodem cable.  Default is NO, since `mgetty' is designed for
     modems...

   - `blocking' YES/NO [-b]

     Tells mgetty to open the device in `blocking' mode, that is, the
     `open()' system call won't succeed until carrier detect is set.
     This is set if `mgetty' is called as `getty'. I'm not sure whether
     it's very useful, but I include it for completeness. Default is NO.

   - `port-owner' USERNAME/USERID

     If set, mgetty will `chown' the tty line to the given username (you
     can specify a string or an integer uid, but the integer must be
     valid).  This is highly recommended for security purposes: only
     give port access to those users you trust not to misuse your modem
     lines! Default is `PORT_OWNER'.

   - `port-group' GROUPNAME/GID

     If set, mgetty will `chgrp' the tty line to this group id (which
     can be given as group name, or as integer gid). If it's not given,
     or not valid, the primary group id of `port-owner' will be used.
     Default is `PORT_GROUP'.

   - `port-mode' PERMISSONS

     Specifies the permissions to `chmod' the device to. *Never* make a
     modem device world-accessible, better use `0660' or even `0600'.
     Default is `PORT_MODE'.

   - `toggle-dtr' YES/NO

     Tells mgetty whether it should lower the DTR line upon startup to
     reset modem. Default is `yes', but some (few) modems react
     allergic to that and crash.

   - `toggle-dtr-waittime' MSECS

     Specifies the time to hold the DTR line low. Default is 500
     milliseconds.

   - `data-only' YES/NO [-D]

     Tells `mgetty' to forget about faxing and only use the data part of
     the modem. Default is `false'. You need this if your modem can't
     distinguish incoming fax and data calls.

   - `fax-only' YES/NO [-F]

     Tells `mgetty' to put the modem in fax-only mode. You need this if
     your modem can't distinguish incoming fax and data calls, but you
     need fax more important than data; and you need it if you want to
     disable data calls for security reasons (this could be achieved
     via `login.config' as well)

   - `modem-type' [-C] MTYPE

     Specifies the kind of modem connected to the port. Default is
     `DEFAULT_MODEMTYPE'. Valid options are:

        * auto

          Mgetty will detect the modem type itself (which may
          occasionally be not desirable, or it may fail on old modem
          equipment).

        * c2.0

          Modem is a CLASS 2.0 fax mode. Works better than class 2, if
          both are available, because its better standardized. Known to
          work with USR and ZyXEL.

        * cls2

          Modem is a CLASS 2 fax modem, mgetty will not try class 2.0.

        * cls2ok

          Modem is a CLASS 2 fax modem that does the bit order upon
          reception *right*. Most modems do it wrong (for compatibility
          with Rockwell, who botched it in the first place), but some,
          for example MultiTech modems, do it right, and it will make
          programs like `mgetty' fail. You'll see if your modem falls
          into this category if decoding of incoming faxes with
          `g32pbm' doesn't work, but `2pbm *-r*' does. This won't
          affect the reliability of fax reception at all, it will only
          ease decoding of the received pages. *Not implemented yet*.

        * data

          Do not try fax initialization, same as if `-D' given.

     There is no way (yet) to tell mgetty to use *only* fax mode and
     refuse data calls with this option, use the `fax-only true'
     statement for that.

   - `init-chat' [-m] EXPECT SEND EXPECT SEND ...

     Tells mgetty the chat sequence to use for initializing the modem.
     *Warning*: the sequence starts with *expect*, which will in most
     cases be `""' (nothing). This ordering was chosen because UUCP
     does it this way, and I wanted to avoid confusion here.

     Example:

          init-chat "" ATQ0E1V1H0 OK ATL0M0S0=0 OK AT&K3 OK

   - `force-init-chat' EXPECT SEND EXPECT SEND ...

     In some cases, the modem can get stuck in a mode where it won't
     react to a simple `AT' command. Usually this happens because the
     modem is set to ignore a DTR drop and still has a data connection
     to the other side. If you use a voice modem, it could be stuck in
     voice mode.

     In these situations, the normal `init-chat' will time out, because
     the modem won't send the proper responses back.

     To get the modem back into a sane state, you can use the
     `force-init-chat' chat sequence. The default setup will send the
     DLE ETX characters, to get voice modems back to life, and then the
     `(pause)+++(pause)ATH0' sequence to get the modem back from data
     mode to command mode.

     You could prepend this sequence to `init-chat' (it wouldn't harm),
     but especially the pauses around the +++ sequence makes this
     undesirable slow.

   - `modem-check-time' SECONDS

     Some modems have the nasty tendency to crash silently. With this
     option, you tell `mgetty' to check every SECONDS seconds with a
     simple `AT...OK' sequence whether the modem still reacts. If not,
     `mgetty' will restart itself and do a full modem reset. Default is
     `MODEM_CHECK_TIME'

   - `rings' [-n] NNN

     Sets the number of `RING' messages to wait for, before mgetty
     picks up the phone. Default is 1. *Warning:* if your modem
     auto-answers, for whatever reason, set this to something
     *different* than the value set with `ATS0=mmm', otherwise the
     modems autoanswer and mgettys manual answer will collide (most
     modems hang up if a command is received during auto-answer)

   - `get-cnd-chat' CHAT SEQUENCE

     This is needed if you have a modem that supports "caller ID"
     detection, but needs a special command to get the CID information.
     Right now, this is only needed for some ELINK ISDN adaptors (see
     Elink-ISDN), most other CID-capable modems send the CID on their
     own and don't need this.

     Don't forget to set `rings' to at least 2, otherwise the CID
     grabbing code won't work.

   - `answer-chat' CHAT SEQUENCE

     This is the command sequence that is used to answer a phone call.
     Usually you can leave it at the default ` "" ATA CONNECT \c \r ',
     but for some modems you need `ATS0=1' in place of `ATA' (ATA not
     allowed). The extra `\r' expect string is needed that the code can
     grab the full CONNECT XYZ\R string. It will work without the \r,
     but then the logging information will be less detailed. *Right now,
     \r won't work at all, it's not implemented yet. Don't use it.*

   - `answer-chat-timeout' SECS

     During the ANSWER-CHAT, each "expect" string must be seen in the
     time specified here. Default is 80 seconds. This time should be at
     least some 5 seconds longer than the time set with the `ATS7=...'
     modem setup command.

   - `autobauding' YES/NO [-a]

     Some modems switch their DTE line speed to the communication line
     speed after connecting, e.g., after sending `CONNECT 2400', the
     modem switches to 2400 bps. Newer modems usually have a switch to
     "lock" a DTE baud rate, which is strongly recommended. If your
     modem insists on doing this speed switch, setting `autobauding' to
     TRUE will make mgetty behave accordingly.

   - `ringback' YES/NO [-R]

     If you have to put your modem and your telephone on the same phone
     line, you can switch on "ringback" or "ring-twice". This means,
     mgetty won't answer the phone on the first call, but remember the
     call, and pick up on the second call (if it comes in the time
     specified by `ringback-time').

   - `ringback-time' SECS

     This setting specifies how much time may pass between the first
     and the second call if "ringback" is active. Default is 30 seconds.

   - `ignore-carrier'

     If your Modem does not assert the DCD (carrier detect) line, or the
     serial port or cable or serial driver is broken, it is possible
     that `mgetty' or `login' will block after a successful CONNECT
     (that means: everything seems to work, but suddenly nothing is sent
     to the port anymore. Depending on the operating system used, this
     can be before printing the `/etc/issue' file or not before printing
     the `password:' prompt.

     To work around this, you can switch off the carrier detection in
     the kernel: set `ignore-carrier true'. Default is `false'.

     *WARNING:* If you use this, your system won't be able to detect
     when a caller just hangs up instead of cleanly logging out. This
     may result in hanging modems, etc.

   - `issue-file' [-i] FILE

     This is the file printed before the login prompt. Default is
     `/etc/issue'.

   - `prompt-waittime' MSECS

     This specifies how long `mgetty' will wait for modem and line to
     settle down before printing issue file and login prompt. Default
     is 500 milliseconds.

   - `login-prompt' [-p] PROMPT

     This specifies the login prompt that mgetty will output. Some
     special characters in this string (and in the issue file, btw) are
     recognized and replaced by something else:

        * @ system name

        * \n newline

        * \r carriage return

        * \g bell

        * \b backspace (ascii 010)

        * \f form feed (ascii 013)

        * \t TAB

        * \P (and \L) port name (e.g. ttyS0)

        * \C date and time, in "ctime()" format

        * \I Connection string (e.g. 2400/REL)

        * \N (and \U) number of users currently logged in

        * \S Port speed (e.g. 38400)

        * \D current date in dd/mm/yy format

        * \T current time in hh:mm:ss format

        * \DIGIT character with the specified octal code

     The maximum lenght of the login prompt is limited to 140
     characters (after expansion).

   - `login-time' SECS

     This specifies the maximum time the user can take to log in. If no
     login has occured after that time, `mgetty' will hang up. Default
     is `MAX_LOGIN_TIME' from `policy.h'.

   - `fido-send-emsi' YES/NO

     Only relevant when mgetty was compiled with `-DFIDO'. Controls
     whether mgetty should send a FidoNET style "EMSI_REQA77E" packet
     before prompting for login. Default is on. Switch this off if you
     have FIDO support compiled in but experience weird problems with
     some PPP clients (or users!) being confused by that string.

   - `fax-id' [-I] LOCAL FAX NUMBER

     This sets the fax station ID used in fax mode to identify your
     site to the caller (usually this is simply your fax phone number).
     Default is `FAX_STATION_ID'.

   - `fax-server-file' [-S] POLL CONTROL FILE

     Specifies the fax file(s) that is to be sent if someone else calls
     your modem in *fax polling mode*, that is, the caller *receives* a
     document.

     Normally, the file given is a text file, containing the list of G3
     files to send to the calling machine, one file per line. Comment
     lines (starting with "#") are ignored. For backward compatibility,
     `mgetty' does check whether the named file is a G3 file itself, in
     which case this file is sent directly (but then, you can only send
     one page).

     Not all modems support fax poll *server* mode, I know that the
     ZyXEL and MultiTech do, and USR does not.

   - `diskspace' [-k] KBYTES

     This setting tells mgetty the minimum amount of disk space that
     has to be available in the fax spool directory for fax reception
     to be allowed.  Default is 1 Mbyte.

   - `notify' MAIL ADDRESS

     This is the address that will get mails if a fax is received. Not
     fully tested.

   - `fax-owner' USERNAME/UID

   - `fax-group' GROUPNAME/GID

   - `fax-mode' PERMS

     Similar to `port-owner/group/mode', these settings specify the
     owner, group and file mode mgetty will use for incoming faxes.
     Defaults are taken from `FAX_IN_OWNER', `FAX_IN_GROUP', and
     `FAX_FILE_MODE'.

   - `debug' [-x] DEBUG LEVEL

     This sets the amount of logging `mgetty' will do. A good value is
     4, more details are seen with `5', and `9' is really noisy.  Try
     it! The log data is written to the file specified by `LOG_PATH' in
     `policy.h', usually this is something like `/var/log/log_mg.ttyxx'.

   - `gettydefs' GD TAG

     If you use the gettdefs feature of `mgetty' - which is *not*
     recommended! - this specifies the gettydefs tag to use for the
     given line.  See MAN GETTYDEFS, MAN MGETTYDEFS.

   - `term' TERMINAL TYPE

     If you are on Linux or similar OSes that have `getty' set the
     `TERM=xxx' terminal type variable, and have no other method to set
     it (e.g. from `/etc/profile' or `$HOME/.profile'), `mgetty' can do
     it for you. Just specify ``term' vt100' or so. I don't think it's
     a good idea to specify the terminal type on a per line base (what
     if all your callers use different terminal types?), so the default
     is UNSET.

Fax Operations
**************

   Both mgetty and sendfax deal exclusively with raw "g3" fax files
("g3" stands for "group 3", which is the CCITT standard for encoding
images for fax transmission). You will have to use external programs to
create, view or print these.

   There are two kinds of g3 files, the high resolution type with
204x196 dpi and the low ("normal") resolution ones with 204x98 dpi.  If
you mix up the two, the recipient will get a fax page that is either
twice or half the proper length. You have been warned.

   The width of a fax page is always 1728 pixels, the length is
arbitrary (though there are some plain paper fax machines out there
that limit the page length to A4 paper). A typical full page has a
length around 2100 pixels in high-resolution mode.