MGETTY Setup for Dialin

Mgetty is actually very simple to set up to answer the modem and to then pass control of the call either to ppp, for a ppp connection, or to login, for a login connection.

Install mgetty-sendfax

Almost all distributions come with mgetty as a part of the distribution. mgetty is the mechanism for answering modems recommended by all, including other "getty" authors, and the distributions (almost?) all include it. So the first place to look for it is on the CDRoms of your distribution. The second place to look is on the mgetty home page, www.leo.org/~doering/mgetty/ (Note that if your distribution's version is earlier than 1.1.24, get a later version as there are some security holes in those earlier versions.)

I cannot go through all of the possible ways of installing mgetty from your distribution, so I will assume that you have installed it, and that the directory
/etc/mgetty+sendfax
mgetty
exist.

Setting up /etc/mgetty+sendfax/mgetty.config

The first thing you need to do is to set up the mgetty configuration file. This is the file which tells mgetty how to set up each of the modems which you wish mgetty to handle.
There are two sections, a general section which applies to all of your modems and their lines, and a specific section for each of the separate lines.
Some possibilities here are
debug # -- The number indicated by # (which can be from 0 to 7) indicates the debugging level. This goes from no debugging messages (0) to mgetty telling you almost everything it does (7). A level of 4 is the default, but this is probably more than most people require unless you are having real problems. A level of 7 sometimes can help in clearing up stubborn misconfigurations. Note that you can set the debugging level independently for each of the ports. However, any debugging level set here is valid only after mgetty has read this line in parsing this config file. Ie, that bug may occur earlier in mgetty's running, and you may want to put in a command line option (-x #) to bump up the debugging level for mgetty actions before it reads this file.
speed 115200 -- This command is a general command which sets the speed to which the serial port is set. This is in general faster than the speed of the modem, as, due to compression by the modem, more bytes flow between the computer and the modem than between the modem and what it is connected to.
port-owner root
port-group staff
port-mode 0666 -- These commands set up the ownership, group and mode of the tty port used by the modem (ie of /dev/ttyS# devices). (mgetty must of course be running as root to be able to do this, as it usually is if started for example by init.)

Port specific section.
port ttyS# ---This says that the commands up to the next "port" line will apply only to the modem and connection on the modem connected to /dev/ttyS# where # is some number.
The most important feature in this section is the modem initialisation lines. You can also override any of the global options for each of the local modems if you so wish.
data-only -- This says that mgetty should not try to answer that port as a fax call, but only as a data modem connection.

Modem initialisation

The line for initialisation is in the form of a chat (man chat) Expect-Send string. Ie, it is a sequence of pairs, the first telling mgetty what to expect from the modem, and the second what to send when it receives the first. Thus the string for my Sportster 33 modem is
init-chat "" AT&F1 OK ATS0=0 OK
while for my Sportster 33 Voice modem is
init-chat "" AT&F1 OK ATS0=0 OK AT#CID=1 OK
Let me go through these items.
"" AT&F1 -- Expect nothing (the stuff between the two sets of double quotes) and when it comes (ie immediately) send the command AT&F1 to the modem. This is an important sequence. This tells the Sportster modems to set themselves to the Factory initialisation number 1. On Sportster modems this is the initialisation which includes hardware (RTS/CTS) flow control. On most other modems, use AT&F or AT&F0 instead. USR broke with convention and made software flow control (XON/XOFF) the default with AT&F, a stupid decision, but one they have stuck with it seems. Look in your modem manual
OK ATS0=0 -- This waits for the OK from the modem (its response to the AT&F1 command). It then sends the ATS0=0 command which tells the modem never to answer the phone. It is crucial for mgetty that this command be included, or mgetty will not work. mgetty waits to receive the word(s) RING from the modem to let it know that the phone is ringing. mgetty then sends the command ATA to the modem telling it to answer the phone. Without this, mgetty would not know when or that the modem has answered the phone. Do not forget this line.
From the above it is clear that it is crucial that the modem send to the computer its codes as words (eg RING). On most modems this is set by default with the AT&F command.
OK AT#CID=1 -- Wits to receive the response OK from the modem to that last command, and then sends the command AT#CID=1. This command tells the Sportster Voice modem to switch on Caller ID. The form of this command depends on the modem brand, so you must look into your modem manual to find the appropriate command for your modem. Note that this is useful only if you have subscribed to caller-id from your phone company. If you have, mgetty can use that information to screen which phone numbers it will answer calls from, and to enable ringback (see man mgetty) only for ringback from the same number.
OK -- This last OK waits for the OK code from the modem to ensure that that last command was successful. There is no "Send" item, so control is passed back immediately on receipt of that OK to the main mgetty program.

You can stick whatever commands you wish into that line if your modem has some particular features you want to or need to enable or disable.

/etc/mgetty+sendfax/login.config

This is the file which you use to control what mgetty does once it has answered the phone. mgetty's behaviour is to wait for a carriage return once it has answered the phone. It then sends out a welcome line with a
login:
While there are a number of options, I will just look at the crucial one(s).
/AutoPPP/ - a_ppp /usr/sbin/pppd debug require-chap This is probably the most crucial line. This tells mgetty that IF it receives an initial LCP (Link Control Protocol) request on the phone line, either immediately after the connection (ie before any carriage return) or as a response to the login prompt, it will insert the username a_ppp into the username login file (usually the wtmp or utmp file) and then run the /usr/sbin/pppd program, with the options "debug" and "require-chap". You can put whichever program you wish in here (eg some script to prepare for running the pppd program ) and whatever options you wish. This program is run as root (assuming mgetty is running with root permission).

The other option is telling mgetty what to do if a user enters a username in to mgetty's prompt. The default is to pass that name to the /bin/login progam with the user name as an argument. This is equivalent to inserting the line
* - - /bin/login @
into login.config. This says-- for anything which has not yet been handled, (*) do not assign a userid, and do not place an entry in wtmp or utmp, but run the program /bin/login with that username as an argument (@).
However, you may regard this as a security hazard, and not want to have login run at all. You can then put in the line
* nobody @ /bin/false
instead. This says that if anyone logs in, just run the program /bin/false ( whose only purpose is to exit immediately with an exit status of 1) under the userid of nobody, and enter the username entered into the utmp or wtmp file. This would disable all logins via mgetty if the AutoPPP did not work and keep a record of these attempts.

See the documetation within the login.config file for further hints as to how it can be used.

Note that any username entered is scanned down the login.config file and the first matching entry is used.

Testing

You should test mgetty to make sure you have not made any mistakes.

mgetty -x 7 ttyS3
This says to run the mgetty program, with (initial) debugging level 7 and to run it to listen on the port /dev/ttyS3. Now try dialing in with a typical computer which might be used, and see if the right things happen. The debugging output is put into the file (usually) of /var/log/mgetty.log.ttyS3, (or /var/log/mgetty.ttyS3) . Look in that file to see if any errors occurred. After the call is finished, mgetty will exit, and you will need to restart it for the next testing call. mgetty rereads its configuration files every time it is restarted.

/etc/inittab

Since you probably do not want to restart mgetty every time someone finishes their call, you can automate this with the /etc/inittab file. Edit that file and insert the following line(s)-- one for each of the modem lines you want to have mgetty listen to.
S3:345:respawn:/sbin/mgetty -x3 ttyS3
S4:345:respawn:/bin/mgetty -x3 ttyS4
... These lines are instruction to init, the main program controlling everything on Linux. The first entry is just a name for this particular line, and is used by init to state which line has problems if there are difficulties. The second group, 345, tells init to start up this line only if Linux is running in levels 3, 4, or 5 (the multiuser command levels). The word "respawn" tells it restart this program every time it dies, if it does die. Note this is what makes it important to test mgetty before hand, since if there is a bug which kills mgetty, this "respawn" will try to run it again immediately, leading to another death, a rerun,.... which can rapidly fill up your log files. (Fortunately Linus is set up so as to stop respawning for 5 min if a program has been restarted 10 times in 2 minutes.)

Once you have done this, run the line
kill -1 1
to tell init to reread the /etc/inittab file. (do not forget the -1 in that line as otherwise you will reboot your system.)

. This program may be reproduced in whole, but must maintain the name of the author, and must carry a link to the location http:www.theory.physics.ubc.ca/mgetty.html the definitive location for this page. Also, commercial use of this document must be OKed by the author.
Dec 7, 2001