Contributed by Guy Helmer <ghelmer@cs.iastate.edu>.
This document provides suggestions for configuring a FreeBSD system to handle dial-up modems. This document is written based on the author's experience with FreeBSD versions 1.0, 1.1, and 1.1.5.1 (and experience with dial-up modems on other UNIX-like operating systems); however, this document may not answer all of your questions or provide examples specific enough to your environment. The author cannot be responsible if you damage your system or lose data due to attempting to follow the suggestions here.
To begin with, the author assumes you have some basic knowledge of FreeBSD. You need to have FreeBSD installed, know how to edit files in a UNIX-like environment, and how to look up manual pages on the system. As discussed below, you will need certain versions of FreeBSD, and knowledge of some terminology & modem and cabling.
First, it is assumed that you are using FreeBSD version 1.1 or higher (including versions 2.x). FreeBSD version 1.0 included two different serial drivers, which complicates the situation. Also, the serial device driver (sio) has improved in every release of FreeBSD, so more recent versions of FreeBSD are assumed to have better and more efficient drivers than earlier versions.
A quick rundown of terminology:
Bits per Second -- the rate at which data is transmitted
Data Terminal Equipment -- for example, your computer
Data Communications Equipment -- your modem
EIA standard for serial communications via hardware
If you need more information about these terms and data communications in general, the author remembers reading that The RS-232 Bible (anybody have an ISBN?) is a good reference.
When talking about communications data rates, the author does not use the term ``baud''. Baud refers to the number of electrical state transitions that may be made in a period of time, while ``bps'' (bits per second) is the ``correct'' term to use (at least it does not seem to bother the curmudgeons quite a much).
External modems seem to be more convenient for dial-up, because external modems 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. Blinking lights impress visitors, but lights are also very useful to see whether a modem is operating properly.
Internal modems usually lack non-volatile RAM, so their configuration may be limited only to setting DIP switches. If your internal modem has any signal indicator lights, it is probably difficult to view the lights when the system's cover is in place.
A background knowledge of these items is assumed
You know how to connect your modem to your computer so that the two can communicate (unless you have an internal modem, which does not need such a cable)
You are familiar with your modem's command set, or know where to look up needed commands
You know how to configure your modem (probably via a terminal communications program) so you can set the non-volatile RAM parameters
The first, connecting your modem, is usually simple -- most straight-through serial cables work without any problems. You need to have a cable with appropriate connectors (DB-25 or DB-9, male or female) on each end, and the cable must be a DCE-to-DTE cable with these signals wired:
Transmitted Data (SD)
Received Data (RD)
Request to Send (RTS)
Clear to Send (CTS)
Data Set Ready (DSR)
Data Terminal Ready (DTR)
Carrier Detect (CD)
Signal Ground (SG)
FreeBSD needs the RTS and CTS signals for flow-control at speeds above 2400bps, 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 you have problems, such as a login session not going away when the line hangs up, you may have a problem with your cable.
The second prerequisite depends on the modem(s) you use. If you do not know your modem's command set by heart, you will need to have the modem's reference book or user's guide handy. Sample commands for USR Sportster 14,400 external modems will be given, which you may be able to use as a reference for your own modem's commands.
Lastly, you will need to know how to setup your modem so that it will work well with FreeBSD. 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. If you are familiar with connecting modems to PC-based bulletin board systems, this may seem awkward.
FreeBSD supports 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 much 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.
Here is the process that FreeBSD follows to accept dial-up logins. A getty process, spawned by init, patiently waits to open the assigned serial port (/dev/ttyd0, for our example). The command ps ax might show this:
4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0
When a user dials the modem's line and the modems connect, the CD line is asserted by the modem. The kernel notices that carrier has been detected and completes getty's open of 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.
We hope getty finds the correct speed and the user sees a login: prompt. After the user enters his/her 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.
Let's dive into the configuration...
FreeBSD kernels typically come prepared to search for four serial ports, known in the PC-DOS world as COM1:, COM2:, COM3:, and COM4:. FreeBSD can presently also handle ``dumb'' multiport serial interface cards, such as the Boca Board 1008 and 2016 (please see the manual page sio(4) for kernel configuration information if you have a multiport serial card). The default kernel only looks for the standard COM ports, though.
To see if your kernel recognizes any of your serial ports, watch for messages while the kernel is booting, or use the /sbin/dmesg command to replay the kernel's boot messages. In particular, look for messages that start with the characters sio. Hint: to view just the messages that have the word sio, use the command:
# /sbin/dmesg | grep 'sio'
For example, on a system with four serial ports, these are the serial-port specific kernel boot messages:
sio0 at 0x3f8-0x3ff irq 4 on isa
sio0: type 16550A
sio1 at 0x2f8-0x2ff irq 3 on isa
sio1: type 16550A
sio2 at 0x3e8-0x3ef irq 5 on isa
sio2: type 16550A
sio3 at 0x2e8-0x2ef irq 9 on isa
sio3: type 16550A
If your kernel does not recognize all of your serial ports, you will probably need to configure a custom FreeBSD kernel for your system.
Please see the BSD System Manager's Manual chapter on ``Building Berkeley Kernels with Config'' [the source for which is in /usr/src/share/doc/smm] and ``FreeBSD Configuration Options'' [in /sys/conf/options and in /sys/arch/conf/options.arch, with arch for example being i386] for more information on configuring and building kernels. You may have to unpack the kernel source distribution if have not installed the system sources already (srcdist/srcsys.?? in FreeBSD 1.1, srcdist/sys.?? in FreeBSD 1.1.5.1, or the entire source distribution in FreeBSD 2.0) to be able to configure and build kernels.
Create a kernel configuration file for your system (if you have not already) by cding to /sys/i386/conf. Then, if you are creating a new custom configuration file, copy the file GENERICAH (or GENERICBT, if you have a BusTek SCSI controller on FreeBSD 1.x) to YOURSYS, where YOURSYS is the name of your system, but in upper-case letters. Edit the file, and change the device lines:
device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr
device sio1 at isa? port "IO_COM2" tty irq 3 vector siointr
device sio2 at isa? port "IO_COM3" tty irq 5 vector siointr
device sio3 at isa? port "IO_COM4" tty irq 9 vector siointr
You can comment-out or completely remove lines for devices you do not have. If you have a multiport serial board, such as the Boca Board BB2016, please see the sio(4) man page for complete information on how to write configuration lines for multiport boards. Be careful if you are using a configuration file that was previously used for a different version of FreeBSD because the device flags have changed between versions.
Note: port "IO_COM1" is a substitution for port 0x3f8, IO_COM2 is 0x2f8, IO_COM3 is 0x3e8, and IO_COM4 is 0x2e8, which are fairly common port addresses for their respective serial ports; interrupts 4, 3, 5, and 9 are fairly common interrupt request lines. Also note that regular serial ports cannot share interrupts on ISA-bus PCs (multiport boards have on-board electronics that allow all the 16550A's on the board to share one or two interrupt request lines).
When you are finished adjusting the kernel configuration file, use the program config as documented in ``Building Berkeley Kernels with Config'' and the config(8) manual page to prepare a kernel building directory, then build, install, and test the new kernel.
Most devices in the kernel are accessed through ``device special files'', which are located in the /dev directory. The sio devices are accessed through the /dev/ttyd? (dial-in) and /dev/cua0? (call-out) devices. On FreeBSD version 1.1.5 and higher, there are also initialization devices (/dev/ttyid? and /dev/cuai0?) and locking devices (/dev/ttyld? and /dev/cual0?). The initialization devices are used to initialize communications port parameters each time a port is opened, such as crtscts for modems which use CTS/RTS signaling for flow control. The locking devices are used to lock flags on ports to prevent users or programs changing certain parameters; see the manual pages termios(4), sio(4), and stty(1) for information on the terminal settings, locking & initializing devices, and setting terminal options, respectively.
A shell script called MAKEDEV in the /dev directory manages the device special files. (The manual page for MAKEDEV(8) on FreeBSD 1.1.5 is fairly bogus in its discussion of COM ports, so ignore it.) To use MAKEDEV to make dial-up device special files for COM1: (port 0), cd to /dev and issue the command MAKEDEV ttyd0. Likewise, to make dial-up device special files for COM2: (port 1), use MAKEDEV ttyd1.
MAKEDEV not only creates the /dev/ttyd? device special files, but also creates the /dev/cua0? (and all of the initializing and locking special files under FreeBSD 1.1.5 and up) and removes the hardwired terminal special file /dev/tty0?, if it exists.
After making new device special files, be sure to check the permissions on the files (especially the /dev/cua* files) to make sure that only users who should have access to those device special files can read & write on them -- you probably do not want to allow your average user to use your modems to dial-out. The default permissions on the /dev/cua* files should be sufficient:
crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cua01
crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuai01
crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cual01
These permissions allow the user uucp and users in the group dialer to use the call-out devices.
There are three system configuration files in the /etc directory that you will probably need to edit to allow dial-up access to your FreeBSD system. The first, /etc/gettytab, contains configuration information for the /usr/libexec/getty daemon. Second, /etc/ttys holds information that tells /sbin/init what tty devices should have getty processes running on them. Lastly, you can place port initialization commands in the /etc/rc.serial script if you have FreeBSD 1.1.5.1 or higher; otherwise, you can initialize ports in the /etc/rc.local script.
There are two schools of thought regarding dial-up modems on UNIX. One group likes to configure their modems and system 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 school 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 the <Enter> key 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 can continue ad nauseum, but normally only takes a keystroke or two before the user sees a good prompt. Obviously, this login sequence does not look as clean as the former ``locked-speed'' method, but a user on a low-speed connection should receive better interactive response from full-screen programs.
The author will try to give balanced configuration information, but is biased towards having the modem's data rate follow the connection rate.
/etc/gettytab is a termcap(5)-style file of configuration information for getty(8). Please see the gettytab(5) manual page for complete information on the format of the file and the list of capabilities.
If you are locking your modem's data communications rate at a particular speed, you probably will not need to make any changes to /etc/gettytab.
You will need to setup an entry in /etc/gettytab to give getty information about the speeds you wish to use for your modem. If you have a 2400 bps modem, you can probably use the existing D2400 entry. This entry already exists in the FreeBSD 1.1.5.1 gettytab file, so you do not need to add it unless it is missing under your version of FreeBSD:
#
# 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:
If you have a higher speed modem, you will probably need to add an entry in /etc/gettytab; here is an entry you could use 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:
On FreeBSD 1.1.5 and later, this will result in 8-bit, no parity connections. Under FreeBSD 1.1, add :np: parameters to the std.xxx entries at the top of the file for 8 bits, no parity; otherwise, the default is 7 bits, even parity.
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.
If you have a 28.8 Kbps modem and/or you want to take advantage of compression on a 14.4 Kbps modem, you need to 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:
If you have a slow CPU or a heavily loaded system and you do not have 16550A-based serial ports, you may receive sio ``silo'' errors at 57.6 Kbps.
/etc/ttys is the list of ttys for init to monitor. /etc/ttys also provides security information to login (user root may only login on ttys marked secure). See the manual page for ttys(5) for more information.
You will need to either modify existing lines in /etc/ttys or add new lines to make init run getty processes automatically on your new dial-up ports. The general format of the line will be the same, whether you are using a locked-speed or matching-speed configuration:
ttyd0 "/usr/libexec/getty xxx" dialup on
The first item in the above line is the device special file for this entry -- ttyd0 means /dev/ttyd0 is the file that this getty will be watching. The second item, "/usr/libexec/getty xxx" (xxx will be replaced by the initial gettytab capability) 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 the example above) 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. However, the author finds it easier at his site to specify vt102 as the default terminal type, since the users just use VT102 emulation on their remote systems.
After you have made changes to /etc/ttys, you may send the init process a HUP signal to re-read the file. You can use the command
# kill -1
1
to send the signal. If this is your first time setting up
the system, though, you may want to wait until your
modem(s) are properly configured and connected before
signaling init.For a locked-speed configuration, your 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:
ttyd0 "/usr/libexec/getty std.19200" dialup on
If your modem is locked at a different data rate, substitute the appropriate name for the std.speed entry for std.19200 from /etc/gettytab for your modem's data rate.
In a matching-speed configuration, your ttys entry needs to reference the appropriate beginning ``auto-baud'' (sic) entry in /etc/gettytab. For example, if you added the above suggested entry for a matching-speed modem that starts at 19.2 Kbps (the gettytab entry containing the V19200 starting point), your ttys entry might look like this:
ttyd0 "/usr/libexec/getty V19200" dialup on
High-speed modems, like V.32, V.32bis, and V.34 modems, need to use hardware (RTS/CTS) flow control. You can add stty commands to /etc/rc.serial on FreeBSD 1.1.5.1 and up, or /etc/rc.local on FreeBSD 1.1, to set the hardware flow control flag in the FreeBSD kernel for the modem ports.
For example, on a sample FreeBSD 1.1.5.1 system, /etc/rc.serial reads:
#!/bin/sh
#
# Serial port initial configuration
stty -f /dev/ttyid1 crtscts
stty -f /dev/cuai01 crtscts
This sets the termios flag crtscts on serial port #1's (COM2:) dial-in and dial-out initialization devices.
On an old FreeBSD 1.1 system, these entries were added to /etc/rc.local to set the crtscts flag on the devices:
# Set serial ports to use RTS/CTS flow control
stty -f /dev/ttyd0 crtscts
stty -f /dev/ttyd1 crtscts
stty -f /dev/ttyd2 crtscts
stty -f /dev/ttyd3 crtscts
Since there is no initialization device special file on FreeBSD 1.1, one has to just set the flags on the sole device special file and hope the flags are not cleared by a miscreant.
If you have a modem whose parameters may be permanently set in non-volatile RAM, you will need to use a terminal program (such as Telix under PC-DOS or tip under FreeBSD) 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:
CD asserted when connected
DTR asserted for operation; dropping DTR hangs up line & resets modem
CTS transmitted data flow control
Disable XON/XOFF flow control
RTS received data flow control
Quiet mode (no result codes)
No command echo
Please read the documentation for your modem to find out what commands and/or DIP switch settings you need to give it.
For example, to set the above parameters on a USRobotics Sportster 14,400 external modem, one could give these commands to the modem:
ATZ
AT&C1&D2&H1&I0&R2&W
You might also want to take this opportunity to adjust other settings in the modem, such as whether it will use V.42bis and/or MNP5 compression.
The USR Sportster 14,400 external modem also has some DIP switches that need to be set; for other modems, perhaps you can use these settings as an example:
Switch 1: UP -- DTR Normal
Switch 2: Do not care (Verbal Result Codes/Numeric Result Codes)
Switch 3: UP -- Suppress Result Codes
Switch 4: DOWN -- No echo, offline commands
Switch 5: UP -- Auto Answer
Switch 6: UP -- Carrier Detect Normal
Switch 7: UP -- Load NVRAM Defaults
Switch 8: Do not care (Smart Mode/Dumb Mode)
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. I have heard this sequence can result in a extended, silly conversation between getty and the modem.
For a locked-speed configuration, you will need to configure the modem to maintain a constant modem-to-computer data rate independent of the communications rate. On a USR 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
For a variable-speed configuration, you will need to configure your modem to adjust its serial port data rate to match the incoming call rate. On a USR Sportster 14,400 external modem, these commands will lock the modem's error-corrected data rate to the speed used to issue the commands, but allow the serial port rate to vary for non-error-corrected connections:
ATZ
AT&B2&W
Most high-speed modems provide commands to view the modem's current operating parameters in a somewhat human-readable fashion. On the USR Sportster 14,400 external modems, the command 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 USR's DIP switch settings), use the commands ATZ and then ATI4.
If you have a different brand of modem, check your modem's manual to see how to double-check your modem's configuration parameters.
Here are a few steps you can follow to check out the dial-up modem on your system.
Hook up your modem to your FreeBSD system, boot the system, and, if your 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 doesn't light, login to the FreeBSD system through the console and issue a ps ax to see if FreeBSD is trying to run a getty process on the correct port. You should see a lines like this among the processes displayed:
114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0
115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1
If you see something different, like this:
114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0
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 mis-configured modem, because getty should not be able to open the communications port until CD (carrier detect) has been asserted by the modem.
If you do not see any getty processes waiting to open the desired ttyd? port, double-check your entries in /etc/ttys to see if there are any mistakes there. Also, check the log file /var/log/messages to see if there are any log messages from init or getty regarding any problems. If there are any messages, triple-check the configuration files /etc/ttys and /etc/gettytab, as well as the appropriate device special files /dev/ttyd?, for any mistakes, missing entries, or missing device special files.
Try dialing into the system; be sure to use 8 bits, no parity, 1 stop bit on the remote system. If you do not get a prompt right away, or get garbage, try pressing <Enter> about once per second. If you still do not see a login: prompt after a while, try sending a BREAK. If you are using a high-speed modem to do the dialing, try dialing again after locking the dialing modem's interface speed (via AT&B1 on a USR Sportster, for example).
If you still cannot get a login: prompt, check /etc/gettytab again and double-check that
The initial capability name specified in /etc/ttys for the line matches a name of a capability in /etc/gettytab
Each nx= entry matches another gettytab capability name
Each tc= entry matches another gettytab capability name
If you dial but 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 has any).
If you have gone over everything several times and it still does not work, take a break and come back to it later. If it still does not work, perhaps you can send an electronic mail message to the FreeBSD general questions mailing list <freebsd-questions@FreeBSD.org>describing your modem and your problem, and the good folks on the list will try to help.
Thanks to these people for comments and advice:
for a number of good suggestions
For questions about FreeBSD, e-mail
<questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.