27.4 Dial-in Service

Contributed by Guy Helmer. Additions by Sean Kelly.

Configuring a FreeBSD system for dial-in service is similar to connecting terminals except that modems are used instead of terminal devices.

27.4.1 External Versus Internal Modems

External modems are more convenient for dial-up because they often can be semi-permanently configured via parameters stored in non-volatile RAM and they usually provide lighted indicators that display the state of important RS-232 signals, indicating whether the modem is operating properly.

Internal modems usually lack non-volatile RAM, so their configuration may be limited to setting DIP switches. If the internal modem has any signal indicator lights, they are difficult to view when the system's cover is in place.

27.4.1.1 Modems and Cables

When using an external modem, a proper cable is needed. A standard RS-232C serial cable should suffice as long as all of the normal signals are wired:

Table 27-4. Signal Names

Acronyms Names
RD Received Data
TD Transmitted Data
DTR Data Terminal Ready
DSR Data Set Ready
DCD Data Carrier Detect (RS-232's Received Line Signal Detector)
SG Signal Ground
RTS Request to Send
CTS Clear to Send

FreeBSD needs the RTS and CTS signals for flow control at speeds above 2400 bps, the CD signal to detect when a call has been answered or the line has been hung up, and the DTR signal to reset the modem after a session is complete. Some cables are wired without all of the needed signals, so if a login session does not go away when the line hangs up, there may be a problem with the cable.

Like other UNIX®-like operating systems, FreeBSD uses the hardware signals to find out when a call has been answered or a line has been hung up and to hangup and reset the modem after a call. FreeBSD avoids sending commands to the modem or watching for status reports from the modem.

27.4.2 Serial Interface Considerations

FreeBSD supports the NS8250-, NS16450-, NS16550-, and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 devices have single-character buffers. The 16550 device provides a 16-character buffer, which allows for better system performance. Bugs in plain 16550's prevent the use of the 16-character buffer, so use 16550A's if possible. Because single-character-buffer devices require more work by the operating system than the 16-character-buffer devices, 16550A-based serial interface cards are preferred. If the system has many active serial ports or will have a heavy load, 16550A-based cards are better for low-error-rate communications.

27.4.3 Quick Overview

As with terminals, init spawns a getty process for each configured serial port for dial-in connections. For example, if a modem is attached to /dev/ttyu0, ps ax might show this:

 4850 ??  I      0:00.09 /usr/libexec/getty V19200 ttyu0

When a user dials the modem's line and the modems connect, the Carrier Detect (CD) line is reported by the modem. The kernel notices that the carrier has been detected and instructs getty to open the port. getty sends a login: prompt at the specified initial line speed. getty watches to see if legitimate characters are received, and, in a typical configuration, if it finds junk (probably due to the modem's connection speed being different than getty's speed), getty tries adjusting the line speeds until it receives reasonable characters.

After the user enters their login name, getty executes /usr/bin/login, which completes the login by asking for the user's password and then starting the user's shell.

27.4.4 Configuration Files

There are three system configuration files in /etc that probably need to be edited to allow dial-up access to the FreeBSD system. /etc/gettytab contains configuration information for the /usr/libexec/getty daemon. /etc/ttys holds information that tells init which ttys should have getty processes running on them. Lastly, port initialization commands can be placed in /etc/rc.d/serial.

There are two schools of thought regarding dial-up modems on UNIX. One group likes to configure their modems and systems so that no matter at what speed a remote user dials in, the local computer-to-modem RS-232 interface runs at a locked speed. The benefit of this configuration is that the remote user always sees a system login prompt immediately. The downside is that the system does not know what a user's true data rate is, so full-screen programs like Emacs will not adjust their screen-painting methods to make their response better for slower connections.

The other group configures their modems' RS-232 interface to vary its speed based on the remote user's connection speed. For example, V.32bis (14.4 Kbps) connections to the modem might make the modem run its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the modem's RS-232 interface run at 2400 bps. Because getty does not understand any particular modem's connection speed reporting, getty gives a login: message at an initial speed and watches the characters that come back in response. If the user sees junk, it is assumed that they know they should press Enter until they see a recognizable prompt. If the data rates do not match, getty sees anything the user types as “junk”, tries going to the next speed and gives the login: prompt again. This procedure normally only takes a keystroke or two before the user sees a good prompt. This login sequence does not look as clean as the “locked-speed” method, but a user on a low-speed connection should receive better interactive response from full-screen programs.

This section will try to give balanced configuration information, but is biased towards having the modem's data rate follow the connection rate.

27.4.4.1 /etc/gettytab

/etc/gettytab is a termcap(5)-style file of configuration information for getty(8). Refer to gettytab(5) for complete information on the format of the file and the list of capabilities.

27.4.4.1.1 Locked-speed Config

When locking a modem's data communications rate at a particular speed, no changes to /etc/gettytab should be needed.

27.4.4.1.2 Matching-speed Config

Set up an entry in /etc/gettytab to give getty information about the speeds to use for the modem. For a 2400 bps modem, use the existing D2400 entry.

#
# Fast dialup terminals, 2400/1200/300 rotary (can start either way)
#
D2400|d2400|Fast-Dial-2400:\
        :nx=D1200:tc=2400-baud:
3|D1200|Fast-Dial-1200:\
        :nx=D300:tc=1200-baud:
5|D300|Fast-Dial-300:\
        :nx=D2400:tc=300-baud:

For a higher speed modem, add an entry in /etc/gettytab. This entry is for a 14.4 Kbps modem with a top interface speed of 19.2 Kbps:

#
# Additions for a V.32bis Modem
#
um|V300|High Speed Modem at 300,8-bit:\
        :nx=V19200:tc=std.300:
un|V1200|High Speed Modem at 1200,8-bit:\
        :nx=V300:tc=std.1200:
uo|V2400|High Speed Modem at 2400,8-bit:\
        :nx=V1200:tc=std.2400:
up|V9600|High Speed Modem at 9600,8-bit:\
        :nx=V2400:tc=std.9600:
uq|V19200|High Speed Modem at 19200,8-bit:\
        :nx=V9600:tc=std.19200:

This will result in 8-bit, no parity connections.

The example above starts the communications rate at 19.2 Kbps (for a V.32bis connection), then cycles through 9600 bps (for V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps. Communications rate cycling is implemented with the nx= (“next table”) capability. Each of the lines uses a tc= (“table continuation”) entry to pick up the rest of the “standard” settings for a particular data rate.

For a 28.8 Kbps modem or to take advantage of compression on a 14.4 Kbps modem, use a higher communications rate than 19.2 Kbps. Here is an example of a gettytab entry starting a 57.6 Kbps:

#
# Additions for a V.32bis or V.34 Modem
# Starting at 57.6 Kbps
#
vm|VH300|Very High Speed Modem at 300,8-bit:\
        :nx=VH57600:tc=std.300:
vn|VH1200|Very High Speed Modem at 1200,8-bit:\
        :nx=VH300:tc=std.1200:
vo|VH2400|Very High Speed Modem at 2400,8-bit:\
        :nx=VH1200:tc=std.2400:
vp|VH9600|Very High Speed Modem at 9600,8-bit:\
        :nx=VH2400:tc=std.9600:
vq|VH57600|Very High Speed Modem at 57600,8-bit:\
        :nx=VH9600:tc=std.57600:

For a slow CPU or a heavily loaded system without 16550A-based serial ports, there may be “sio” “silo” errors at 57.6 Kbps.

27.4.4.2 /etc/ttys

Configuration of /etc/ttys is covered in . Configuration for modems is similar, but a different argument is passed to getty and a different terminal type is specified. The general format for both locked-speed and matching-speed configurations is:

ttyu0   "/usr/libexec/getty xxx"   dialup on

The first item in the above line is the device special file for this entry. ttyu0 indicates that getty is watching /dev/ttyu0. The xxx will replace the initial gettytab capability and is the process init will run on the device. The third item, dialup, is the default terminal type. The fourth parameter, on, indicates to init that the line is operational. There can be a fifth parameter, secure, but it should only be used for terminals which are physically secure, such as the system console.

The default terminal type, dialup in this example, may depend on local preferences. dialup is the traditional default terminal type on dial-up lines so that users may customize their login scripts to notice when the terminal is dialup and automatically adjust their terminal type. Setting vt102 as the default terminal type allows users to use VT102 emulation on their remote systems.

After editing /etc/ttys, send the init process a HUP signal to re-read the file:

# kill -HUP 1

Wait until the modem is properly configured and connected before signaling init.

27.4.4.2.1 Locked-speed Config

For a locked-speed configuration, the ttys entry needs to have a fixed-speed entry provided to getty. For a modem whose port speed is locked at 19.2 Kbps, the ttys entry might look like this:

ttyu0   "/usr/libexec/getty std.19200"   dialup on

If the modem is locked at a different data rate, substitute the appropriate value for std.speed instead of std.19200. Make sure to use a valid type listed in /etc/gettytab.

27.4.4.2.2 Matching-speed Config

In a matching-speed configuration, the ttys entry needs to reference the appropriate beginning “auto-baud” entry in /etc/gettytab. For example, for the above suggested entry for a matching-speed modem that starts at 19.2 Kbps, the /etc/ttys entry might look like this:

ttyu0   "/usr/libexec/getty V19200"   dialup on

27.4.4.3 /etc/rc.d/serial

High-speed modems, like V.32, V.32bis, and V.34 modems, need to use hardware (RTS/CTS) flow control. stty can be used to set the hardware flow control flag in the FreeBSD kernel for the modem ports.

For example, to set the termios flag crtscts on COM2's dial-in and dial-out initialization devices, the following lines could be added to /etc/rc.d/serial:

# Serial port initial configuration
stty -f /dev/ttyu1.init crtscts
stty -f /dev/cuau1.init crtscts

27.4.5 Modem Settings

For a modem whose parameters may be permanently set in non-volatile RAM, a terminal program such as tip can be used to set the parameters. Connect to the modem using the same communications speed as the initial speed getty will use and configure the modem's non-volatile RAM to match these requirements:

Read the documentation for the modem to find out which commands and/or DIP switch settings are needed.

For example, to set the above parameters on a U.S. Robotics® Sportster® 14,400 external modem, give these commands to the modem:

ATZ
AT&C1&D2&H1&I0&R2&W

Other settings can be adjusted in the modem, such as whether it will use V.42bis and/or MNP5 compression.

The U.S. Robotics Sportster 14,400 external modem also has some DIP switches that need to be set. Other modems, may need these settings:

Result codes should be disabled/suppressed for dial-up modems to avoid problems that can occur if getty mistakenly gives a login: prompt to a modem that is in command mode and the modem echoes the command or returns a result code. This sequence can result in an extended, silly conversation between getty and the modem.

27.4.5.1 Locked-speed Config

For a locked-speed configuration, configure the modem to maintain a constant modem-to-computer data rate independent of the communications rate. On a U.S. Robotics Sportster 14,400 external modem, these commands will lock the modem-to-computer data rate at the speed used to issue the commands:

ATZ
AT&B1&W

27.4.5.2 Matching-speed Config

For a variable-speed configuration, configure the modem to adjust its serial port data rate to match the incoming call rate. On a U.S. Robotics Sportster 14,400 external modem, these commands will lock the modem's error-corrected data rate to the speed used to issue the commands, while allowing the serial port rate to vary for non-error-corrected connections:

ATZ
AT&B2&W

27.4.5.3 Checking the Modem's Configuration

Most high-speed modems provide commands to view the modem's current operating parameters in a somewhat human-readable fashion. On the U.S. Robotics Sportster 14,400 external modem, ATI5 displays the settings that are stored in the non-volatile RAM. To see the true operating parameters of the modem, as influenced by the modem's DIP switch settings, use ATZ and then ATI4.

For a different brand of modem, check the modem's manual to see how to double-check the modem's configuration parameters.

27.4.6 Troubleshooting

Here are a few steps for troubleshooting a dial-up modem on a FreeBSD system.

27.4.6.1 Checking Out the FreeBSD System

Hook up the modem to the FreeBSD system, boot the system, and, if the modem has status indication lights, watch to see whether the modem's DTR indicator lights when the login: prompt appears on the system's console. If it lights up, that should mean that FreeBSD has started a getty process on the appropriate communications port and is waiting for the modem to accept a call.

If the DTR indicator does not light, login to the FreeBSD system through the console and type ps ax to see if FreeBSD is trying to run a getty process on the correct port:

  114 ??  I      0:00.10 /usr/libexec/getty V19200 ttyu0
  115 ??  I      0:00.10 /usr/libexec/getty V19200 ttyu1

If something like this is displayed instead:

  114 d0  I      0:00.10 /usr/libexec/getty V19200 ttyu0

and the modem has not accepted a call yet, this means that getty has completed its open on the communications port. This could indicate a problem with the cabling or a misconfigured modem, because getty should not be able to open the communications port until carrier detect has been asserted by the modem.

If no getty processes are waiting to open the desired ttyuN port, double-check the entries in /etc/ttys to see if there are any mistakes. Also, check /var/log/messages to see if there are any log messages from init or getty. If there are any messages, triple-check /etc/ttys and /etc/gettytab, as well as the appropriate device special files, /dev/ttyuN, for any mistakes, missing entries, or missing device special files.

27.4.6.2 Try Dialing In

Try dialing into the system. Be sure to use 8 bits, no parity, and 1 stop bit on the remote system. If a prompt does not appear right away, or the prompt shows garbage, try pressing Enter about once per second. If there is still no login: prompt after a while, try sending a BREAK. When using a high-speed modem, try dialing again after locking the dialing modem's interface speed.

If there is still no login: prompt, check /etc/gettytab again and double-check that:

  • The initial capability name specified in the entry in /etc/ttys matches the name of a capability in /etc/gettytab.

  • Each nx= entry matches another gettytab capability name.

  • Each tc= entry matches another gettytab capability name.

If the modem on the FreeBSD system will not answer, make sure that the modem is configured to answer the phone when DTR is asserted. If the modem seems to be configured correctly, verify that the DTR line is asserted by checking the modem's indicator lights.

If it still does not work, take a break and come back to it later. If it still does not work, try sending an email message to the FreeBSD general questions mailing list describing the modem and the problem.