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 /usr/local/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.
Do not activate this unless you understand all implications!
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.
open-delay msec
A few modems respond to raising the DTR line (when opening the device)
with ‘OK’. This can confuse mgetty, because it will see
this OK as response to the next command. In the log file, you can see if
your modem exhibits this problem if the echo of each AT command
can be seen when waiting for the response to the next AT
command. With open-delay you can give a number of milliseconds to
wait after the device is active until mgetty flushes all incoming
responses and goes ahead.
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)
Watch out: if you have setup some unusual answer-chat, incoming
calls might still come through. So check your setup!
modem-type [-C] mtype
Specifies the kind of modem connected to the port. Default is
DEFAULT_MODEMTYPE. Valid options are:
Mgetty will detect the modem type itself (which may occasionally be not
desirable, or it may fail on old modem equipment). Mgetty will use
the ATI command to find out the modem type, and select the proper
fax class accordingly. If that fails (unknown modem type), mgetty will
try class 2.0 and then class 2.
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, ZyXEL 1496 and 2864 series, and ELSA modems.
Modem is a class 2 fax modem, mgetty will not try class 2.0.
Modem conforms to the new ITU T.32 standard (class 2.1). To my knowledge, there are no such modems available yet, but supporting them will be easy as class 2.1 is very similar to class 2.0.
Modem can only do class 1 fax. NOT IMPLEMENTED YET. (And not recommended anyway).
Modem can do class 1 fax conforming to ITU T.31 standard. This isn’t much better than class 1 (use class 2 / 2.0 if available!), but is better standardized. NOT IMPLEMENTED YET.
(obsolete, use modem-quirks 02)
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.
modem-quirks bitmask
Some modems have a very peculiar interpretation of the fax standards.
Some of the internal operations of mgetty+sendfax can be adapted
to that. The argument is a number, constructed from valies in
fax_lib.h, one bit per "quirk". Usually you won’t need this
option, because those modems really needing it are auto-detected and
handled properly anyway.
Right now, the following quirks are defined:
0x01 leave the modem in class 2 mode instead of switching
to class 0 before sending ATA (you might try this if
adaptive fax/data answer doesn’t work).
0x02 class 2 bit order is correct (MultiTech) - unimplemented
0x04 do not trust +FPTS:x,lc,blc values
0x08 do not wait for XON character when sending pages
0x20 AT+FCC/+FMINSP bug workaround for (very) old USR Courier V.32
0x40 display incoming informations about ’non standard frames’ - this
might be necessary on some USR modems to work around logic bugs
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.
post-init-chat expect send expect send ...
Some modems forget parts of their settings when going from data to fax mode and back during modem initialization. For example, some USR models forget the settings of “Caller ID delivery” (AT#CID=1), and some ELSA modems forget their current DTE port speed when going from voice to data mode, thus leading to RING messages being delivered with the wrong baud rate.
For those modems, you can use this command to set up some AT commands that are executed after all other fax and voice initialization has been done. Be careful with what you do! If you send an ATZ (modem reset) or something similar here, all your fax/voice settings will be lost!
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)
msn-list msn1 msn2 msn3...
If you have an ISDN modem that signals the called party number (MSN) to the host, you can use this statement to map the MSN numbers to distictive RINGs. The MSN called will be compared the list, and the first match is used for the distinctive RING number. The list is searched from left to right.
This is known to work with ELSA and ZyXEL ISDN terminal adaptors.
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.
cnd-program pathname
Specify a program to be run before answering an incoming call. Use this if the static Caller ID selection in CNDFILE (policy.h) is not sufficient, or if you want to use the Caller ID data for other purposes (displaying, for example). See Caller-ID.
cid-program pathname
Specify a program to be run as soon as Caller ID information comes in (typically between 1st and 2nd ring). If Caller ID info is not available by the 3rd ring, still run the program (to report the time that the phone rang). This allows mgetty to behave like a caller-id box. See Caller-ID.
The return value of cid-program is evaluated as follows:
0 - handle call normally 10+n - set number of RINGs to wait for to "n", then proceed
so you can use that to have mgetty answer the phone right away
for known fax-callers (or voice spammers), and only after 8 rings
for everyone else.
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’. Some special characters are substituted by connect speed, date, etc. - see below (login-prompt) for a list.
Note: maximum line length after substitution is 300 characters, so be careful with ASCII art banners with lots of color settings and such.
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:
The maximum lenght of the login prompt is limited to 300 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.
login-env-ttyprompt-hack yes/no
On SVR4, maybe on other systems too, you can cause the ’login’ program to prompt with the same string as mgetty did, instead of the standard "login:" prompt. The string will be passed to the ’login’ program in the environment variable TTYPROMPT. This is done by putting "login" into a special (brain-dead) "ttymon"- compatibility mode. In that mode, mgetty doesn’t ask for a login name at all, so mgetty won’t work if you enable that feature and your login program doesn’t support it. You can see if it doesn’t work if the user gets a double login prompt or none at all.
As a side effect, this feature can also be used to directly start "other" applications, like a BBS software or similar things, after the modem has connected (login.config would then be used to specify what program to run.)
This feature is incompatible with FIDO and AutoPPP support - those work only if mgetty can see the user response to the login prompt.
In previous releases, this used to be ENV_TTYPROMPT in 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.
login-conf-file pathname
Specifies the path and filename of the ’login.config’ file that tells mgetty which program to call for login. See the example login.config file to get some ideas what to do with it.
The file name given will be ignored for security reasons if the file is not owned by ’root’, or is readable or writeable by anybody else than ’root’ (that is, it must be mode 0600 or 0200).
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. If you do
not want e-mail notification, specify notify without an e-mail
address.
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.
fax-spool-in dir1:dir2:dirn
Specifies a directory, or list of directories, where incoming faxes are saved. Multiple directories are tried in order until, the first one that has enough disk space and is writeable is used.
The default setting is taken from FAX_SPOOL_IN in the Makefile
usually /var/spool/fax/incoming:/tmp (/tmp is used as fallback).
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/mgetty.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.