modemcap(5)

NAME
modemcap - modem description file

DESCRIPTION
The modemcap file contains records describing how to connect to modems attached to the system, how to initialize them, what to do when calls are answered on them, and whether and how to make them available for dialout.

The modemcap file is currently used by the modemd(8) and mpoold(8) programs. Modemd(8) is a partial replacement for getty(8) which has a limited understanding of the AT command set common to most modern modems and can be used to initialize a modems to some user-defined state, wait for another modem to connect, and start some program with the modem as its controlling terminal. Mpoold listens on a TCP/IP port for connections, and when one is received, allocates a modem from a pool and connects the incoming TCP connection to that modem.

Records in the modemcap file are used to describe to modemd and mpoold how to initialize a modem, how to initialize the tty line being used to communicate with that modem, which pool of modems mpoold should allocate modems from, and what modemd should do with an incoming connection.

Each record consists of a single line or a group of lines all but the last of which ends in the '\' (backslash) character. Each record begins with a name, followed by a colon, followed by one or more definitions, also separated by colons. It is possible for one record to include the definitions from another. Definitions are processed from left to right, and when one record includes another, the contents of the included record are processed in sequence.

In general, at least one level of inclusion will be used. A record defining the characteristics of the modem will be referenced by two records, one for modemd and one for mpoold. The modemd-specific and mpoold-specific records may either define tty line parameters themselves, or may include a common tty line parameter record.

DEFINITIONS
Definitions can have either string, numeric or boolean values. String definitions are specified with definition=value. Numeric definitions are specified with definition#value. Boolean definitions are always false by default, and can be defined as true by simply listing the name of the definition.

The following definition names are currently available:

ba  (string) Login banner. This is printed out prior to starting the program specified in `lp'. If the string `%h' appears in the login banner, it is replaced with the hostname of the machine on which modemd is running. If the string `%t' appears in the login banner, it is replaced with the name of the terminal to which modemd is connected. If the string `%s' is present, it is replaced with the name of the operating system. If `%v' is present, it is replaced with the operating system release number. The string `%%' is replaced with a single `%' character.

bo  (boolean) If true, busies out the modem while initializing it. This prevents an incoming call from ringing on the modem for the brief period when it is first initializing. This can be a problem for modems in a hunt group, particularly a heavily-trafficked hunt group. However, it is not known whether this will work on any modem - it has only been tested successfully on a US Robotics Total Control modem rack. Use with caution.

br  (numeric) Sets the baud rate for transmission to and from the modem.

bs  (numeric) Sets the size of the modem AT command input buffer. Most modern modems have a 40-byte buffer, for compatibility (!) with older modems. This can be set to a larger value to gain some time during the modem initialization process, if it is known that the modem being initialized has an unusually large AT command input buffer.

bt  (numeric) Sets the number of bits per character (usually either seven or eight).

ca  (string) TCP address. If defined, instead of starting the program specified in `lp', modemd will open a TCP/IP connection to the specified address and port (see `cp'), sending all modem output to that port and all output from that port to the modem. This may be specified as either a numeric IP address or a symbolic host address as defined in hosts(5) or the Internet Domain Name Service (RFC 1034, 1035).

cl  (boolean) On most modems, an AT command can consist of a single punctuation character (most commonly &) followed by a single alphabetic character, followed by an optional numeric value, e.g. ``ATX0'' or ``AT&K4''. On some modems, however, some AT commands can contain more than one alphabetic character - for example, on the MultiTech MB2834, the command AT$SB1200 sets the serial port baud rate to 1200 baud. On modems which use multiple alphabetic characters in a single AT command, this flag must be set to avoid parse errors in the modem initialization string.

cp  (string) TCP port. If `ca' is used, `cp' defines the port to connect to. Like `ca', this can be specified either as a numeric value or as a service name, as defined in services(5).

dl  (boolean) If true, modemd will perform the usual logging that would normally be provided by login(1). This involves writing a record to /etc/utmp, to /etc/wtmp and to /etc/lastlog. The default PATH, HOME, USER and SHELL environment variables are set. The setuid(2), setgid(2), and setgroups(2) system calls are used to set the default uid, gid and group list. On systems where it is appropriate setlogin(2) is called to set the kernel-resident login name.

dv  (string) This should be the name of a device which mpoold can use as part of its modem pool. Any number of these devices may be specified in a given record; mpoold will choose modems in the order in which they are listed.

hf  (boolean) If true, hardware (RTS/CTS) flow control will be used when communicating with the modem. The host must support this kind of flow control.

is  (numeric) Sets the receive baud rate from the modem, if different from the transmit rate.

is  (string) Modem initialization string. This should be the series of AT commands that will be used to set the modem to its default state. The initialization code will automatically split this string into pieces that are small enough for the modem to handle. The AT will be automatically prepended to each sequence of commands, so it should not be present in this string. There is no default initialization string.

lp  (string) Login program. This is the name of the program to run once the modem has connected. It should always be either the standard login program on your system, some program which can do its own authentication, or some program which does not present a security exposure because access to the the service it provides need not be controlled. This defaults to login(1).

ls  (boolean) Log subprocess stderr output. If a subprocess is created on login, captures that subprocess's output on standard error (descriptor 2) and logs it. This can be useful for debugging problems with ppp daemons and the like, but should not be used for interactive login shells, where output to standard error should generally be seen by the user.

lu  (string) Login user. If a program like login(1) is not being used (see `lp'), it is most desirable to set this to the login name of some user whose uid and gid should be used when running the program specified in `lp'. Failure to do so could create a serious security exposure if there is a bug or unintended feature in that program.

ms  (boolean) If true, this flag tells modemd to switch to the baud rate printed by the modem at connect time. When a call is answered and the two modems have succeeded in connecting to each other, the modem controlled by modemd will print the message ``CONNECT''. It may also print the baud rate at which the connect occurred. If that baud rate differs from the baud rate at which modemd is currently communicating, some modems will switch to the new baud rate and expect modemd to follow.

os  (numeric) Sets the transmit baud rate to the modem, if different from the receive rate.

pa  (string) Sets the serial parity for communications to the modem. It may be set to even, odd or none; the defaults is none.

pp  (string) The name of a PPP daemon to be run if an HDLC packet is detected. If this parameter is specified, modemd will print a login prompt and wait for either a user to type a username, or for an HDLC packet to be sent by an incoming PPP connection. If an HDLC packet is seen, the PPP daemon is invoked. Otherwise, the login program (lp) is invoked with the name that the user typed in.

    This feature should not be used if the PPP daemon being invoked cannot do PAP or CHAP authentication. Otherwise, an intruder dialing in remotely could gain access to the local network without supplying any identification or authentication information.

rt  (boolean) If true, modemd will leave the tty in raw mode after accepting an incoming connection. If false, it will set the terminal into cooked mode so that a human can type at it and see the expected behaviour. Set this flag if a human will not be dialing in and if the login program (see `lp') isn't smart enough to set up the terminal mode correctly on its own.

sf  (boolean) If true, XON/XOFF flow control will be used when communicating with the modem.

si  (boolean) If true, this flag tells mpoold to skip the modem initialization. If modemd and mpoold are sharing a modem, modemd will always initialize the modem before releasing its lock on the modem, so mpoold will generally never allocate an uninitialized modem. Since initializing the modem can take a significant amount of time, it is desirable in this case to skip the modem initialization in mpoold.

sm  (boolean) This flag tells the modem initialization code to insert pauses between each character of each command sent to the modem. By default, these pauses are 50 milliseconds in duration. Normally, these pauses are only used between the A and T characters at the beginning of a string of AT commands, since those characters are used by the modem to determine the DTE baud rate. Some modems may not be able to take commands at the full data rate; for these modems, set the sm flag. I would be interested in hearing about any modems which don't work without sm, but do work with (see AUTHOR). it.

md  (numeric) Sets the delay in milliseconds between characters sent in command mode. By default, this delay is 50 milliseconds.

zm  (boolean) Some modems can be configured to do a hardware reset when DTR is dropped. If this flag is true, in addition to sending ASCII commands to reset the modem before initializing it, modemd or mpoold will drop DTR for one second to reset the modem.

FILES
/etc/modemcap
    By default, the modemcap file will be found in /etc.

SEE ALSO
modemd(8), mpoold(8), tip(1), uucico(8), getty(8), login(8).

AUTHOR
Modemcap(5), modemd(8), and mpoold(8) were written for RadioMail Corporation by Ted Lemon <mellon@vix.com> under a contract with Vixie Enterprises, and are collectively based on mgetty, a version of getty written by Paul Vixie <paul@vix.com> which understands how to talk to Hayes-compatible modems. Many of Paul's ideas for enhancements to mgetty are incorporated here, along with some of my own.